Design template arguments

Template arguments collect values when a job is created. Envoy substitutes them into the job template snapshot before the job is stored. Use them for identities and structural choices that should remain fixed for that job.

Examples include an integrated account ID, source tenant, migration project ID, object type, or target workspace.

Use job configuration for values operators should edit between runs.

Declare arguments

arguments:
  account_id:
    type: string
    description: Account used by all source tasks
    required: true
    widget: integrated_account
    connector_slot: truto
    integration: salesforce
 
  include_archived:
    type: boolean
    description: Include archived records
    default: false
 
  max_records:
    type: number
    description: Test limit
    default: 100

Arguments support string, number, boolean, string[], and number[]. Use enum for fixed choices. The integrated_account and mongo_collection_record widget hints provide searchable account or record pickers.

Picker choices are resolved through the connector selected during job creation. Large lists use server-side search and cursor pagination.

Substitute values

Use ${NAME} in template fields that must be resolved before the job is stored:

tasks:
  extract:
    task: extract-tickets
    connector_mapping:
      source: truto
    arguments:
      integrated_account_id: ${account_id}
      include_archived: ${include_archived}

Substitution is textual and occurs before the resolved job YAML is parsed. Place a placeholder as the complete scalar value. An unquoted numeric or boolean replacement is then parsed as that YAML type; quoted replacements remain strings. Avoid embedding arrays or other structured values inside longer strings, and inspect the resolved job before running it.

Task expressions then read the bound value from arguments:

config: |
  {
    "connector": "source",
    "method": "list",
    "args": {
      "integrated_account_id": arguments.integrated_account_id,
      "resource": "tickets",
      "unified_model": "ticketing"
    }
  }

Keep ownership clear

There are two argument layers:

• template arguments are the job creation form;
• task arguments are the values a particular task accepts at runtime.

The template explicitly maps the first layer into each task node. Reusing the same name does not bind them automatically.

Updating a template

Existing jobs keep their original substituted snapshot. Updating a template argument default or choice list affects future jobs only.

If a fixed identity must change, create a new job or use the supported job-upgrade flow after reviewing the snapshot diff. Do not hide a structural identity in editable job_config.

Security and validation

• Never collect passwords, API keys, tokens, or connection strings as arguments.
• Store secrets in connector configuration or a configured secret provider.
• Treat connector option labels as display data and IDs as stored values.
• Validate selections again when creating the job; an option can disappear between search and submit.
• Use a bounded test job before scheduling a newly selected tenant or workspace.

See Arguments reference and Job templates.