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.