# Design template arguments

> Source: https://docs.clonepartner.com/guides/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](/guides/job-configuration) for values operators should edit between runs.

## Declare arguments

```yaml
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:

```yaml
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`:

```yaml
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](/reference/arguments) and [Job templates](/reference/job-templates).