Workflow record actions
Workflow definition format 1 supports read_record, update_record and upsert_record actions.
Each action has a typed record configuration whose operation is respectively read, update
or upsert. Incomplete selections can be saved; publication requires valid values and current
publisher authority. These actions do not require Script or Agent execution permission.
Workflows with a recurring trigger must choose record inputs
explicitly because their trigger supplies schedule timestamps and timezone rather than a record.
A read configuration selects object_id, readable_attribute_ids and record_id:
{
"operation": "read",
"object_id": "11111111-1111-4111-8111-111111111111",
"readable_attribute_ids": [],
"record_id": {
"type": "field",
"source_node_id": "22222222-2222-4222-8222-222222222222",
"field_path": "record.id"
}
}
record_id accepts a literal UUID string or a field binding. An update additionally supplies
values, an array of {attribute_id, value} entries. A value is either
{type:"literal", value:...} or {type:"field", source_node_id:..., field_path:...}.
Every literal must include value; explicit null clears a nullable attribute. Omitted attributes
are preserved. Duplicate attribute IDs are invalid. A field binding from a skipped source also
supplies null and clears the selected nullable attribute. It is not omitted from the write.
To preserve the attribute on the other path, put the write inside the conditional branch or
omit that attribute from values. Record IDs and upsert keys must use sources that run on every
path to the record step.
An upsert uses key_attribute_id and key_value instead of record_id. The key must be a writable,
unique TEXT attribute, and its value must be non-null text. Matching is case-sensitive. An existing
match is updated; otherwise a record is created. Configure the key only in key_value, not in
values. Concurrent unique-key conflicts retry the entire transaction.
All operations require record READ grants and ordinary object/record access. Update additionally requires record UPDATE; upsert requires UPDATE and CREATE. Publication freezes the selected object, readable attributes and writable attributes. The execution host enforces that scope together with current domain validation. Object-schema changes invalidate the frozen contract and require review and republication. Parent-controlled objects and writes to managed fields are unsupported.
The Worker validates the complete frozen record closure before executing any step, so a known incompatibility in a later record step cannot allow an earlier Task or write to commit first. The same checks still run when each dependency is used. See run diagnostics.
Relationship targets and tracked locations require explicit related_record_access entries. These
entries use the same record-access vocabulary as Scripts and Agents, permit only read, and cannot
include writable attributes. No related objects or fields are inferred. Every tracked-location hop
must be covered by the declared READ scope.
Authoring and bindings
GET /api/v2/workflows/objects/{object_id}/record-schema returns the object (with its optional
icon and color), field choices,
output_schema, and writable_fields containing canonical JSON schemas keyed by attribute_id.
Optional readable_attribute_ids and writable_attribute_ids use repeated plural
UUID query keys (OpenAPI style: form, explode: true), with at most 512 distinct IDs each.
Comma-separated values are rejected. Omit a selection to request none. This metadata
surface requires workflows:manage and relevant record/object access, without
objects:configuration:read. It reads no record values. Incomplete related access is permitted while
editing; publication validates the full closure. workflows_record_schema_get provides the
same MCP operation.
Discover record-operation targets with GET /api/v2/workflows/objects?purpose=record; this includes
structurally supported built-ins and excludes parent-controlled objects. Trigger discovery uses
purpose=trigger and excludes built-ins. SELECT and STATE choices provide id, value and title;
write the choice UUID id (or an array of IDs for multiselect), not its descriptive value.
Even an empty attribute selection returns the canonical record envelope in output_schema.
Bindings can use the admitted trigger's record.id, record.object_id, display name and captured
text attributes. A preceding step can supply a guaranteed output path such as output.id,
output.displayName or output.data.name. Every intermediate object and path segment must be
required and non-null; optional paths and descendants of nullable objects are unavailable. Selected
record data keys are always present in the output, with explicit null when absent. A Task title
requires a non-null text output.
Durable results
Workflow publication retains encrypted record contracts. All retained Script, Agent, record, Tour and Task dependencies must fit within one combined 128 KiB budget. Both manual and automatic admissions copy the exact closure into the run input. Each record operation and its encrypted result receipt commit in one transaction. A successful READ also has a receipt: retries reuse that result even if the record changes later. Execution does not depend on the availability of history projection.
Run inspection exposes the captured canonical result in a step's record_output, including id,
objectId, displayName and the selected data. This is separate from task_id; retained results
survive later record changes or deletion. Record writes emit their ordinary events and webhooks with
workflow causation, while automatic workflow admission ignores those originating workflow writes.
Business fields used by a display-name template must be in the publication's readable-field scope.
The generated natural ID used as a label fallback is identity metadata, like the record UUID;
it does not require an additional readable-field selection. This does not add unselected fields to data.
Copying locations with Tasks
Native Task actions share the fixed location vocabulary with custom-object location attributes.
GET /api/v2/workflows/capabilities supplies task_actions with each available action's
input_schema and output_schema, filtered by the caller's grants.
read_taskmaps theidinput to a literal UUID or a preceding output and requirestasks:read.create_taskdefaultstask_typetosimple. Usetask_type: "visit"and map the requiredlocationinput to a complete location, for exampleoutput.data.sitefromread_record.update_taskaccepts an optionallocationbinding.task_source_node_idselects a Create Task or Read Task step guaranteed to precede it. A location binding requires a Visit Task and replaces the entire location, clearing destination fields absent from the copied value.- Task creation/update/completion require
tasks:write. Native actions do not requireworkflows:code:execute. Publication rechecks the relevant grants.
For example, a Visit Task action can bind a location read by the previous step:
{
"id": "33333333-3333-4333-8333-333333333333",
"type": "create_task",
"task_type": "visit",
"title": [{ "type": "literal", "text": "Visit customer" }],
"input_bindings": [{
"type": "field",
"input_name": "location",
"source_node_id": "22222222-2222-4222-8222-222222222222",
"field_path": "output.data.site"
}]
}
Read/create/update return output.location alongside Task metadata. Map this whole value into
an update_record location attribute to copy it back. Non-visit Tasks expose a null location;
copying that into a nullable record attribute clears it. A missing, null or unresolved source
cannot create or replace a Visit Task destination: the action fails before changing the Task.
Valid zero coordinates, address-only values, labels and located_at remain intact.
A tracked record location must first be resolved by an authorized record read with every source hop covered by its declared READ scope. Task copying removes the tracking reference and stores the captured fixed value. It never geocodes or follows the source again on retry.
Publication retains the current Task tool schemas with the other executable dependencies. Each
Task read/write and its encrypted result receipt commit together. Retries reuse that receipt;
later Task edits do not alter downstream inputs. Run inspection exposes the result in task_output.
Only one current version of each tool is available; pre-release contracts are updated in place.