Task Forms: Collect Structured Input Inside a Human Task

What it is

A Task Form combines structured data collection and a human decision in one Task node. The assignee opens the task, completes the fields, and selects an Allowed Action such as Approve, Request changes, or Escalate. That action validates and submits the form, records the decision, and chooses the outgoing workflow route.

There is no separate Submit button. The Allowed Actions are the form's buttons.

Task Forms are different from a Manual Start form:

Why it's useful

• One complete hand-off — the assignee provides the values, files, comment, and decision on the same task screen.
• Structured workflow data — later Email, Documents, Report, AI Agent, and routing steps can use the submitted values by their field names.
• Action-based routing — every button can lead to a different branch without adding an artificial Submit step.
• Consistent internal and external work — the same form schema is used on the signed-in Workflow Task Manager and on a valid external task link.
• Traceable results — the selected action and form values stay attached to the task result and workflow instance.
• AI-assisted design — AI Builder understands Task Forms and can propose fields, actions, and branches from a plain-language description.

Before you start

• Open the workflow in Flow Builder Edit mode.
• Add or select a Task node.
• Decide who will receive the task and which business outcomes it needs.
• Decide which values later nodes must use. These values determine the stable Variable name for each field.

Configure a Task Form

1. Select the Form category

1. Double-click the Task node to open Task Properties.
2. Complete the required settings on Basic Info, including the task title and assignee.
3. Open the Form tab.
4. Set Task category to Form.

The panel now shows Task form fields. If you later switch the category away from Form, RAPTIX asks for confirmation before removing the configured fields.

2. Add fields

1. Select Add field.
2. Enter a Variable name. This is the stable output name used by later nodes.
3. Enter the Label shown to user.
4. Choose the Field type.
5. Open More options when you need help text, a placeholder, a default, choices, or document metadata.

Supported field types:

For a dropdown or checkbox group, add at least one option. Enter one option per line. Use Label|value when the user-facing label and stored value should differ:

Low risk|low
Needs review|review
High risk|high

3. Configure field behaviour

Each field can use the following settings:

Hidden fields cannot be required. A hidden file field does not upload or produce a value; keep file fields visible.

4. Use safe variable names

A field variable name:

• starts with a letter or underscore;
• contains only letters, numbers, and underscores;
• is unique within the Task Form.

Do not use the engine-owned names action, actor, comments, form_data, signal_data, or signal_received.

Changing a field label later does not change its variable name. Treat the variable name as the stable contract with downstream nodes.

Configure the buttons and routes

1. Define Allowed Actions

Open the Actions tab. Add or edit the actions the assignee can take.

Action IDs must be unique. Good IDs include approve, request_changes, and send_to_legal.

Do not add an action named submit only to send the form. Every Allowed Action already submits the form.

2. Connect every outcome

1. Save the Task node.
2. Draw an outgoing connection from the Task node.
3. Choose the action outcome that should use that connection.
4. Repeat for every Allowed Action that needs its own path.

For example:

approve         → Generate final report
request_changes → Email requester → Return to review
send_to_legal   → Assign legal review task

Before running the workflow, confirm that every declared action has a valid next step. The action ID on the connection must match the Action ID in Task Properties.

What the assignee sees

When a signed-in assignee opens the task from My Tasks or Workflow Detail:

1. RAPTIX shows the task context and any associated document.
2. The Task form section displays visible fields in the configured order.
3. Required fields are marked and validated.
4. The Allowed Actions section displays the configured action buttons.
5. Selecting an action uploads pending files, validates the fields and comment requirement, records the full response, and continues through that action's route.

An external assignee with a valid secure action link sees the same Task Form fields without needing a workspace account. The link remains scoped to that task and its authorised action; confirming it submits the fields and continues through that action's route.

Use Task Form values downstream

Each submitted field becomes an output of the Task node under its Variable name. The result also keeps the values together under form_data for grouped inspection and audit views.

Example fields:

risk_level
review_notes
signed_contract

Later nodes can use those outputs to:

• route an If/Else condition using risk_level;
• include review_notes in an email or generated report;
• pass the values into an AI Agent;
• attach or save signed_contract through a file-aware downstream node.

File fields are persisted as protected document references, not public file URLs. Use the variable/output picker in the downstream node to select them rather than typing an guessed path.

Build a Task Form with AI Builder

Describe the human step, fields, actions, and branch outcomes together. For example:

Add a contract review task for [email protected]. Collect a required risk level with low, review, and high choices; optional review notes; and a required signed contract file. Add Approve and Request changes actions. Approval should generate a report. Request changes should email the requester and loop back to the review.

AI Builder can propose the Task Form fields and Allowed Actions, then wire downstream branches using the exact action IDs. Review the proposed changes before selecting Apply to canvas, then open Task Properties and verify the field names, required rules, recipient, and routes.

Validation and safety

• Task Form submissions accept only fields defined on the Task node.
• Required values, number/date types, checkbox choices, and dropdown choices are validated by the server.
• Uploaded files must belong to the same workflow instance; a task cannot submit a file reference from another case.
• The selected action must be one of the task's Allowed Actions.
• A completed task cannot be submitted a second time through the same pending action.
• Task Form results are preserved in ordinary, parallel, and Foreach task execution.

Troubleshooting