#Fill a form with process data

A user task fills its form from the process data once, when the task is created — field by field in Form data input, with option lists from Option data — and a start form's answers are mapped onto the input schema.

#When the values are worked out

sequenceDiagram
  participant P as Process
  participant T as User task
  participant F as Form in My tasks
  P->>T: Reach the user task
  T->>T: Work out Form data input and Option data
  alt an expression fails
    T-->>P: The task fails — it does not appear
  else all values worked out
    T->>F: The task appears, prefilled
  end
  F->>P: Completed — the answers under the task's id

The values are worked out once, when the process reaches the task. Opening the task later does not work them out again, so a change to the process data in the meantime does not reach the form.

#Prefill fields — Form data input

Select the user task. With a Form picked, open Form data input.
Click Add form fields and select the fields to prefill.
Give each field an expression — typically a value from an earlier step, such as Activity_fetch.customer.name, or __INITIATOR.email.

Which fields can be prefilled:

text field, text area, number, date time, checkbox, select, radio group, checkbox group and tag list — one value each;
a dynamic list or a table — a list, one entry per row. Give it an array: an object in its place is refused with Type "object" is not compatible with expected type "array";
display elements — a text view or HTML view gets its text, an image view or document preview its file or address.

❌ A file picker cannot be prefilled.

⚠️ The fields of the form itself are offered in the variable list, but they have no value yet when the task is created. An expression that uses one fails.

#Without Form data input

If Form data input produces no value at all, the form is filled another way:

fields whose key matches a value already stored under this task's id are prefilled from it — for example the previous answers, when the process comes back to the same task;
⚠️ and every top-level value of the process data whose name matches a field key fills that field too.

#Options from the process — Option data

A select, radio group, checkbox group or tag list whose options come from the process, not from a fixed list, needs an entry in Option data. The group lists exactly these fields.

For each, give either rows of value and label, or an expression that returns a list. Each item of that list may be:

an object with value and label — or name instead of label;
a text, used as both value and label.

⚠️ An expression that does not return a list gives an empty option list, without an error.

When the task is completed, the picked value is stored under the field key, and its label in __display. See Hand work to a person with a user task.

#When an expression fails

A prefill or option expression that fails — or gives nothing — makes the whole task fail: it never appears in My tasks, and the instance fails unless an error boundary event catches it. A field is never just left empty. null is fine.

The expression can be corrected when the step is retried from monitoring.

#Map a start form onto the input schema

When a person starts a process by hand with a form, the form's answers become the start data:

Select the start event, open Manual start and pick the Form.
For each field of the input schema, give an expression — typically formData.<field key>. A file from a file picker arrives as a file reference.

Without a mapping, the form's answers are passed on as they are. Either way the result is checked against the input schema before the process starts.

⚠️ The mapping sees only formData — not the person starting it, not other data.

⚠️ Every mapped field must have a value. A field the person left empty, or one the form hid, stops the start with an error.

#What validation checks

The panel checks each expression against the type the field expects, and asks for an Option data entry for every field that needs one. The messages are German.

⚠️ A type mismatch in Form data input is shown on the field, but does not make the process invalid, and the start-form mapping is not checked at all.

⚠️ Problems in Form data input, Display control and Input control are counted on the Option data group — which is hidden when the form has no field that needs option data.