Tour workflow actions
Workflows can read templates, create independent Tours and change their participants or publication
state. Discover the available actions and exact input/output schemas in
GET /api/v2/workflows/capabilities (tour_actions), filtered by the caller's grants.
Workflow action type | Versioned local tool | Effect |
|---|---|---|
list_tour_templates | tour_templates.list, version 1 | Search within the allowed template set. |
read_tour_template | tour_templates.get, version 1 | Read one allowed template. |
read_tour | tours.get, version 1 | Read an operational Tour. |
create_tour | tours.create, version 1 | Create a draft Tour from Default or a named template. |
update_tour | tours.update, version 1 | Update supported Tour fields. |
set_tour_participants | tours.set_participants, version 1 | Replace the complete participant set. |
publish_tour | tours.publish, version 1 | Explicitly publish through normal Tour lifecycle checks. |
These are ordinary graph actions. No Script or Agent is required. Input bindings use the tool's
camelCase input names, such as tourTemplateId and tourDate; JSON properties of the surrounding
REST payload use snake_case, such as input_bindings and input_name.
Template selection and scope
A literal tourTemplateId binds that exact template. A value from a preceding step needs a declared
tour_template_ids allowlist on the consuming action. Template reads and searches cannot access
arbitrary templates: searches filter inside that allowlist before pagination. An empty allowlist
provides no dynamic named-template access. A fixed literal template adds its ID automatically.
When creation can omit the template, publication also captures permission to use the protected
Default. Publication checks Task-creation permission when the selected templates contain Tasks;
execution checks again against their current content. Older frozen scopes without permission for
the effective Default fail closed and require republication. A completed effect receipt still
replays its original result without applying today's Default.
Publication retains the tool contract and template authority, not template content. Creation loads the latest saved template when the action executes. A read performed earlier in the run has its own retained result; later creation can use a newer saved template.
Template edits do not modify previously created Tours. Required skills, defaults, mixed Tasks and
Stops are copied into independent resources. Omit optional creation fields to inherit defaults;
use a literal null to clear a description or planned bound, and [] to clear required skills.
See Tour creation and templates.
Values supplied at manual start
A manual_record workflow can declare start_inputs on its definition. Each declaration has a
safe snake_case name, a display label, and a type: text, number, boolean, date or
tour_template. All declared values are required. There can be at most 16 declarations and
16 KiB of supplied values. Text is bounded to 4,096 characters. Dates are valid calendar dates
in YYYY-MM-DD form. Values are never coerced between types.
"start_inputs": [
{"name": "template", "label": "Delivery template", "type": "tour_template"},
{"name": "day", "label": "Delivery date", "type": "date"}
]
Bind the chosen template from the trigger's input.template field and the date from input.day.
The Create tour action must still declare its allowed tour_template_ids. Declaring an input
as tour_template enables the picker and resource metadata; it does not grant access to an
arbitrary template. Example binding:
{
"type": "field",
"input_name": "tourTemplateId",
"source_node_id": "00000000-0000-4000-8000-000000000001",
"field_path": "input.template"
}
POST /api/v2/workflows/{workflow_id}/runs accepts the values alongside the existing manual
run identity and record selection:
{
"request_id": "00000000-0000-4000-8000-000000000901",
"version_id": "00000000-0000-4000-8000-000000000902",
"record_id": "00000000-0000-4000-8000-000000000903",
"start_inputs": {
"template": "00000000-0000-4000-8000-000000000010",
"day": "2026-09-16"
}
}
Admission validates exact declared names and types and captures the values in the immutable run
snapshot. Omission means an empty object; null, missing required values and undeclared names are
rejected. Retry with the same request_id and the same values; changed values conflict.
Creating another run intentionally requires a new request identity. This extends existing workflow
admission and does not introduce generalized HTTP idempotency.
On definition PATCH, omitting start_inputs preserves declarations, [] clears them, and null is
rejected. Nonempty declarations require a manual trigger before publication. Preview does not
supply manual start values; conditions depending on them have an unknown preview outcome.
The web start form keeps entered values in session storage, scoped to the user, workspace, workflow, request, publication and record. It saves them before admission and reuses them after a lost response or reload in the same tab. Values are absent from URLs and Ask Rob page context. If recovery values are unavailable, replay is blocked until the user returns to the original tab or explicitly chooses a new run. Backend workflow receipts do not expire with browser storage.
Recurring creation
create_tour accepts scheduled_tour_date_offset_days for recurring triggers. It derives the date
from the captured scheduled occurrence in the selected template's timezone and then adds the day
offset (−365 through 365). A delayed execution still uses its original scheduled occurrence.
Do not bind tourDate simultaneously. Without this option, template creation needs a tourDate
binding containing a calendar date (YYYY-MM-DD).
For example, this definition creates a draft Tour every weekday:
{
"format_version": 1,
"triggers": [
{
"id": "00000000-0000-4000-8000-000000000001",
"type": "recurring",
"timezone": "Europe/Vienna",
"schedule": {
"frequency": "weekly",
"time": "08:00",
"weekdays": [1, 2, 3, 4, 5]
}
}
],
"actions": [
{
"id": "00000000-0000-4000-8000-000000000002",
"type": "create_tour",
"scheduled_tour_date_offset_days": 0,
"input_bindings": [
{
"type": "literal",
"input_name": "tourTemplateId",
"value": "00000000-0000-4000-8000-000000000010"
}
]
}
],
"edges": [
{
"source": "00000000-0000-4000-8000-000000000001",
"target": "00000000-0000-4000-8000-000000000002"
}
]
}
Replace the template UUID with an existing template in your workspace. Publishing the workflow
activates its schedule. It does not publish the resulting Tours. Add a separate publish_tour
node and bind its tourId to the Create tour node's output.id when publication is wanted.
Tour publication still requires participants and the applicable grant.
Scripts and Agents
Scripts may select the versioned Tour read and local-write tools. Agents may select only the
three read tools. Both declare tour_template_ids in their inline step configuration; workflow publication freezes
the set into their execution contracts. Replacing an action with an omitted or empty set clears
its template access. Null is rejected.
An Agent can read its allowed templates and return a selected template ID. Bind that result to an explicit Create tour action with its own allowed template set. Permission to read or select does not give an Agent permission to create or publish a Tour.
Workflow references and creation origin
GET /api/v2/workflows/references?target_type=tour_template&target_id={id}&page=0&size=25 requires
workflows:manage and tour-templates:read. Each row distinguishes uses, may_use, may_select or
origin, and identifies its current draft or publication and authored node where applicable.
Paused current publications still count as current references. Historical versions and deleted
workflows are excluded from active use; scope=all includes their retained references as history.
Use blocks_deletion=true for current blockers. Origins and historical rows never block deletion.
POST /api/v2/workflows accepts optional origin_tour_template_id to record where creation began.
The template must currently exist and be readable. This metadata survives later graph edits and
appears in the reference projection. Origin alone does not prevent template deletion. Exact current
references and current Script/Agent scopes do prevent deletion (409 Conflict).
Execution and retries
A typed Tour action commits its local database changes and its validated result receipt in one transaction. Rollback removes both. Retrying the same admitted workflow operation reuses that result; template changes or deletion after a successful creation cannot duplicate or change it. A new workflow run is a separate operation. Scripts and Agents retain their existing execution receipts and do not acquire an additional receipt around the same protected tool invocation.
This guarantee applies to workflow execution. Ordinary HTTP and Ask Rob creation calls currently execute independently; identical arguments do not identify one operation. Generalized retry-safe HTTP/Ask Rob mutations are deferred to TF-2290.