Skip to main content

Workflow Task actions

create_task and read_task can select a Simple or Visit Task definition with definition_id. update_task inherits the definition of its preceding Create or Read action through task_source_node_id. A Task cannot change definition. Workflow question Tasks use the separate question actions; they cannot use custom definitions.

Discover choices through GET /api/v2/definitions/tasks. Retrieve the chosen action's field schemas with GET /api/v2/workflows/task-definitions/{definition_id}/task-schema?action=create_task (or read_task / update_task). The response contains type, input_schema and output_schema. It requires workflows:manage and tasks:read for Read, or tasks:write for Create/Update, and reads no record values. MCP exposes the same operation as workflows_task_schema_get.

Inputs and outputsโ€‹

Custom input_bindings[].input_name values are immutable attribute UUIDs. Native bindings keep names such as location and id. Title and assignee remain native action properties; a definition cannot override them. Values may be literals or fields from preceding steps. A field binding can provide default_value when its source may be absent or null. Publication validates the complete required input set and rejects incompatible field types. Omitted creation values receive the Task definition's defaults; omitted update values are preserved.

{
"id": "22222222-2222-4222-8222-222222222222",
"type": "create_task",
"task_type": "simple",
"definition_id": "33333333-3333-4333-8333-333333333333",
"title": [{ "type": "literal", "text": "Inspect equipment" }],
"input_bindings": [{
"type": "literal",
"input_name": "44444444-4444-4444-8444-444444444444",
"value": "Check hydraulic lines"
}]
}

Visit creation also requires a location binding. Write SELECT/STATE choices using choice UUIDs, not labels. Relationship inputs use the ordinary Task attribute write shapes and each target resource's read authority. Publication verifies and freezes the necessary reference grants.

Task outputs include definitionId, native metadata, custom data keyed by public attribute slugs, and relationshipPageInfo. Later actions can bind paths such as output.data.instructions. A Read with definition_id rejects a Task belonging to another definition. Without it, Read exposes only native fields. A Create without definition_id uses the corresponding system base.

Updating statusโ€‹

update_task accepts an optional status: open or done. Omission or null preserves the current status. Set done to complete the Task, or open to reopen it. Setting the current status is allowed. Title, assignment and other field changes are applied before status in the same transaction; the step's retained output reflects the final Task. Retrying a committed step returns its receipt without reapplying any changes.

{
"id": "55555555-5555-4555-8555-555555555555",
"type": "update_task",
"task_source_node_id": "22222222-2222-4222-8222-222222222222",
"title": [{ "type": "literal", "text": "Equipment inspected" }],
"status": "done"
}

The source must be a Create Task or Read Task step guaranteed to precede the update. Dry runs and run history report the requested status in mutation_input.status. An unknown status is rejected with a field-level 422 pointing at that action's status. The former complete_task type is no longer supported and is rejected as an unknown action type.

Schema changes, deletion and copiesโ€‹

Saving a draft indexes its Task definition dependencies and fixed record references. The reference API exposes task_definition and task_relationship_record targets; it does not emit a separate reference for every Task attribute. The conservative definition-level guard protects the whole schema. Retained publications continue to protect those schemas even after the Workflow is deleted. Incompatible schema changes are rejected; labels, field order, prefixes and permitted optional additions remain editable. Publication freezes the output projection, so new optional fields do not alter earlier runs' captured results.

Fixed records used by required relationship inputs cannot be deleted. Optional relationship records may be deleted and are omitted when a new effect executes. Each Task operation and its encrypted output receipt commit in one transaction. Retrying the same effect returns that receipt rather than reapplying an update or rereading current values.

Full tenant copies remap definition, attribute and choice identities without rewriting UUID-shaped text, retain ordinary operational references, and leave Workflows disabled. Frozen tenant templates continue to exclude Workflows; Tour-template required-reference repair is a separate configuration copying contract.