Documentation by ClonePartner

Start typing to search.

Job & Dashboard Reference

Arguments schema

View Markdown

Reference every argument definition field: types, required, default, enum, widget pickers, connector_slot, and ${VAR} substitution.

Arguments schema

Tasks and job templates declare typed parameters under an arguments: key. Task arguments are supplied at run time and read in JSONata as arguments.<name>. Template-level arguments are collected when a Job is created and substituted into the job snapshot wherever ${VAR} placeholders appear. For template arguments the schema is enforced by parseJobDefinition in src/job-parser.ts; this page covers both surfaces because the definition fields are the same.

For guidance on choosing arguments over job_config, see Template arguments.

Definition

arguments:
  day:
    type: string
    description: Which dataset to process
    required: true
    enum: [day1, day2, day3]
  limit:
    type: number
    default: 100
  dry_run:
    type: boolean
    default: false
  issue_keys:
    type: string[]
    default: [FP-14, SUP-1234]

Definition fields

Field Type Required Description
type string No string, number, boolean, string[], or number[]. Template arguments default to string when omitted; any other value is rejected.
description string No Human-readable description shown in run and create dialogs.
required boolean No Whether the value must be provided at runtime (default: false).
default any No Value used when the caller omits the argument.
enum array No Restrict allowed values to this list.
widget string No UI picker hint for the Create Job and Run Task dialogs (see below).
integration string No With widget: integrated_account, filter accounts by integration slug for multi-integration connectors.
connector_slot string No With picker widgets, the connector slot name whose mapping supplies the connector (for example truto, mongo).

Array types (string[], number[]) render as comma-separated inputs in the dialogs. At runtime they coerce to real arrays — JSON arrays and comma-separated strings are both accepted from CLI and API.

UI widgets

widget changes only how operators pick a value — never the runtime behavior.

Default (no widget)

A plain input matching the type, or a dropdown when enum is set.

integrated_account

Use whenever an argument holds an integrated-account connector's integrated_account_id UUID, so operators pick from a searchable account list instead of pasting UUIDs:

sf_integrated_account_id:
  type: string
  required: true
  widget: integrated_account
  integration: salesforce
  connector_slot: truto
  description: Truto integrated account ID for the customer's Salesforce org

The picker lists accounts from the connector mapped to connector_slot and optionally filters them by integration. A per-integration catalog connector normally uses the account pinned in its connector config, so omit the argument there unless the task deliberately lets operators choose.

mongo_collection_record

Use when the value should be selected from a MongoDB collection through a mapped Mongo connector slot:

TRUTO_MIGRATION_JOB_NAME:
  type: string
  required: true
  widget: mongo_collection_record
  connector_slot: mongo
  mongo_collection: migration_jobs
  mongo_value_field: name
  mongo_label_field: name
  mongo_description_fields: [tenant_id]
  mongo_search_fields: [name, tenant_id, source_id, destination_id]
  mongo_sort:
    updated_at: -1
    created_at: -1
    name: 1
Field Description
mongo_collection Mongo collection to query.
mongo_value_field Field path stored as the argument value.
mongo_label_field Field path shown as the primary label.
mongo_description_fields Field paths shown as muted metadata.
mongo_search_fields Field paths searched with a case-insensitive Mongo regex.
mongo_filter Base Mongo filter merged into every picker query.
mongo_sort Mongo sort object.

The picker requires mongo_value_field to exist and be non-empty on a row, so sparse rows do not consume a page without producing selectable options.

${VAR} substitution

Template-level arguments are baked in at job creation: the UI collects the declared values, then every ${VAR_NAME} placeholder in the template YAML is replaced before the Job is saved. A template must explicitly map each argument into the task nodes that need it:

arguments:
  SF_OBJECT:
    type: string
    required: true
 
tasks:
  sync_meetings:
    task: my/sf-to-hs
    arguments:
      sf_object: ${SF_OBJECT}

Task-node arguments: values are otherwise passed verbatim — they are not JSONata. Writing sf_object: arguments.SF_OBJECT delivers the literal string "arguments.SF_OBJECT" to the task.

Runtime access

Read arguments in any JSONata config expression:

config: |
  {
    "connector": "blob_source",
    "method": "read",
    "args": {
      "blob": "data/" & arguments.day & "/records.csv",
      "format": "csv"
    }
  }

Arguments, variables, and job_config

  • Arguments — caller-supplied or defaulted runtime values that vary between runs.
  • Variables — static values authored in the task YAML with a fixed value.
  • job_config — Job settings that stay editable between runs. See job_config schema.

Never put credentials in any of these — connector configuration carries secrets.