tray-patterns

Tray Workflow Patterns

Consult this when building workflows or debugging structure issues.

Incremental Build Flow

Workflows are built step-by-step, not as monolithic JSON:

create_workflow(project_id, workflow_name, trigger={...})
  → workflow_id + version_id

add_workflow_steps(workflow_id, version_id, steps=[{...}, {...}, ...])
  → new version_id

update_workflow_steps(workflow_id, new_version_id, steps=[{step_name, properties, ...}, ...])
  → newer version_id

CRITICAL: Version ID chaining — Every mutating tool returns a version_id. You MUST pass it to the next call. Stale version_ids cause API errors (which include the latest version_id for recovery).

Trigger Properties

For the canonical trigger connector table (names, versions, which triggers need public_url), see tray-connectors. The one trigger whose structure is worth codifying here is the scheduled daily operation — it has the richest required-field shape.

Scheduled trigger — daily operation

{
  "public_url": {"type": "jsonpath", "value": "$.env.public_url"},
  "hour": {"type": "string", "value": "9"},
  "minute": {"type": "string", "value": "0"},
  "tz": {"type": "string", "value": "Europe/London"},
  "day_of_week": {
    "type": "object",
    "value": {
      "monday": {"type": "boolean", "value": true},
      "tuesday": {"type": "boolean", "value": true},
      "wednesday": {"type": "boolean", "value": true},
      "thursday": {"type": "boolean", "value": true},
      "friday": {"type": "boolean", "value": true},
      "saturday": {"type": "boolean", "value": true},
      "sunday": {"type": "boolean", "value": true}
    }
  }
}

day_of_week must be explicit — always set all 7 days. Do not rely on defaults.

Trigger output uses zero-indexed month and day_of_week — January is 0, December is 11; Monday is 0, Sunday is 6. Branches that compare the trigger's day/month output against a literal day name will silently route wrong on production runs (the validator can't catch it because the jsonpaths are valid). For any date arithmetic prefer the Date Time Helper's Get Date Property operation over parsing the trigger payload directly.