Zum Hauptinhalt springen

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 typeVersioned local toolEffect
list_tour_templatestour_templates.list, version 1Search within the allowed template set.
read_tour_templatetour_templates.get, version 1Read one allowed template.
read_tourtours.get, version 1Read an operational Tour.
create_tourtours.create, version 1Create a draft Tour from Default or a named template.
update_tourtours.update, version 1Update supported Tour fields.
set_tour_participantstours.set_participants, version 1Replace the complete participant set.
publish_tourtours.publish, version 1Explicitly 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.