Atlas Forms Integration
Atlas Forms provides the form rendering engine used inside WorkDesk HIL form tasks. When a workflow reaches a HIL form node, the Atlas Form identified by formId is rendered inline in the task card using the FormRenderer component.
How It Works
WorkDesk does not build its own form rendering engine. Instead, it uses the Atlas Forms player component library (@bizfirstai/player-components-react) — the same library used in App Studio and standalone form deployments. This ensures form behavior (validation, field types, conditional logic) is identical across all contexts.
FormRenderer Props in WorkDesk
import { FormRenderer } from '@bizfirstai/player-components-react';
// Used in FormTaskCard.tsx
<FormRenderer
formId={task.formId!} // Atlas Form ID — from HIL task record
initialValues={task.initialValues ?? {}} // Pre-populated values from workflow data context
mode="edit" // "edit" for submission, "view" for read-only review
onSubmit={handleFormSubmit} // Called with formData on valid submission
onError={handleFormError} // Called if form load fails
submitLabel="Submit and Continue Workflow"
theme="dark" // Matches WorkDesk dark theme
locale={userLocale} // User's locale for field formatting
/>Form Load Flow
Task Record Created
WorkDesk task record includes formId (Atlas Form ID) and initialValues (JSON map of field values from workflow data context).
FormRenderer Loads Form Definition
FormRenderer calls GET /api/atlas-forms/{formId}/definition to fetch the form schema — field types, layout, validation rules, conditional logic.
Form Renders with Initial Values
Fields are rendered with initialValues pre-populated. Read-only fields (if any) show workflow data without allowing edits. Conditional visibility logic activates based on initial values.
Employee Submits
FormRenderer validates the submission. On success, onSubmit(formData) fires. WorkDesk POSTs the formData to POST /api/executions/{id}/resume.
View Mode for Review Tasks
Review tasks that display a completed form use FormRenderer with mode="view". All fields are rendered read-only with their current values — no Submit button, no validation. This allows reviewers to see the exact form state without risking accidental modification.
// Read-only mode for review tasks
<FormRenderer
formId={task.formId!}
initialValues={task.currentFormData}
mode="view" // no submit button, no validation
theme="dark"
/>Error Handling
| Error Scenario | Behavior |
|---|---|
| Form definition not found (404) | Error card shown: "Form configuration error — contact your workflow administrator" |
| Form definition load timeout | Retry button shown — employee can retry loading the form |
| Initial value type mismatch | FormRenderer silently discards incompatible initial values and renders the field empty |
| Form validation failure on submit | FormRenderer highlights invalid fields — WorkDesk submit is not called until all validation passes |
WorkDesk uses the @bizfirstai/player-components-react package version pinned to the platform's current Atlas Forms version. When Atlas Forms is updated, WorkDesk's package dependency must be updated together to ensure compatibility.