Form Tasks
Form tasks render an Atlas Form inline inside the WorkDesk task card. The employee fills out structured fields and submits — the form data is passed as output to the next workflow node, enabling rich data collection at any workflow stage.
How Form Tasks Work
When a Flow Studio workflow reaches a HIL node configured with type form, it stores the formId (referencing an Atlas Form) and any initialValues (pre-populated from the workflow data context) in the task record. WorkDesk retrieves this and uses the Atlas Forms FormRenderer component to render the form inline.
Workflow Suspends at HIL Form Node
Process Engine writes task record with type: "form", formId: "form-xyz", and initialValues extracted from workflow data.
WorkDesk Fetches Form Definition
Task detail page loads the task. WorkDesk calls GET /api/forms/{formId} to get the Atlas Form definition (field types, validation rules, layout).
FormRenderer Renders the Form
FormRenderer from @bizfirstai/player-components-react renders the form with the provided initialValues. Fields appear pre-populated where workflow data was available.
Employee Submits
FormRenderer validates the form. On valid submission, onSubmit callback fires. WorkDesk POSTs the form data to /resume. Workflow continues with form data as node output.
FormRenderer Integration
import { FormRenderer } from '@bizfirstai/player-components-react';
function FormTaskCard({ task }: { task: HilTask }) {
const resumeExecution = useResumeExecution();
const handleSubmit = async (formData: Record<string, unknown>) => {
await resumeExecution({
executionId: task.executionId,
taskId: task.taskId,
response: {
type: 'form',
formData,
submittedAt: new Date().toISOString(),
},
});
};
return (
<div className="form-task-card">
<h2>{task.title}</h2>
<p className="description">{task.description}</p>
<FormRenderer
formId={task.formId!}
initialValues={task.initialValues ?? {}}
onSubmit={handleSubmit}
submitLabel="Submit and Continue Workflow"
theme="workdesk"
/>
</div>
);
}Initial Values (Pre-Population)
The Flow Studio HIL node configuration specifies which workflow data fields should pre-populate which form fields. For example, an onboarding form task can pre-populate the employee's name and department from the upstream "New Employee" node output — the employee only fills in the additional fields specific to this step.
// Flow Studio HIL node configuration (workflow designer sets this)
{
"type": "hil",
"taskType": "form",
"formId": "form-onboarding-step2",
"initialValues": {
"employeeName": "{{data.newEmployee.fullName}}",
"department": "{{data.newEmployee.department}}",
"startDate": "{{data.newEmployee.startDate}}"
},
"assignedTo": { "type": "actor", "actorId": "{{data.hrManagerId}}" }
}Form Validation
Validation rules are defined in the Atlas Form definition — they are not duplicated in WorkDesk. The FormRenderer enforces all validation client-side (required fields, type constraints, regex patterns, cross-field rules). The Submit button is disabled until all validation passes.
Resume API — Form Submission
POST /api/executions/{executionId}/resume
Authorization: Bearer {token}
Content-Type: application/json
{
"taskId": "...",
"response": {
"type": "form",
"formData": {
"employeeName": "John Doe",
"department": "Engineering",
"startDate": "2026-06-01",
"equipmentRequired": ["Laptop", "Monitor", "Keyboard"],
"officeLocation": "NYC-Floor-3",
"additionalNotes": "Remote on Fridays"
},
"submittedAt": "2026-05-25T12:00:00Z"
}
}The submitted formData object becomes the output data of the HIL form node. Downstream nodes can reference any field using workflow expression syntax — e.g., {{nodes.hilFormStep.output.officeLocation}}.
If a form task is long and the employee cannot complete it in one sitting, WorkDesk auto-saves form state to localStorage every 30 seconds. When they return to the task, the saved draft is restored. The task remains in Pending state until formally submitted.