Configure a job between runs

Use job_config for settings that an operator may change after a job is created: migration stages, dry-run switches, notifications, batching choices, and field mappings. The schema belongs to the job template; each instantiated job stores its own values.

Use template arguments instead for values chosen once when the job is created.

Lifecycle

1. A job template declares the job_config schema and defaults.
2. Creating a job copies that schema into the job snapshot.
3. Defaults seed the job's initial values.
4. Operators edit values on Job Details or through a compatible dashboard input.
5. Starting a job run snapshots the current values onto that run.
6. Tasks read the snapshot as job_config.<key>.

Changing a job after a run starts does not change that run.

Define a form

Each top-level map key is the stored key:

job_config:
  sync_options:
    type: form
    title: Sync options
    description: Settings applied to the next run
    fields:
      - key: dry_run
        label: Preview only
        type: boolean
        default: true
      - key: batch_size
        label: Batch size
        type: number
        required: true
        default: 100
      - key: notify
        label: Send completion notification
        type: boolean
        default: false

Forms store one object:

{
  "dry_run": true,
  "batch_size": 100,
  "notify": false
}

Supported field types are text, number, boolean, select, and multi_select. Selects can use inline options or a read-only connector-backed option source.

Define a field mapping

Use field_mapping when an operator maps source fields to destination fields:

job_config:
  ticket_fields:
    type: field_mapping
    title: Ticket field mapping
    allow_transform: true
    default:
      - source_field: subject
        target_field: title
    source:
      options_source:
        connector: source
        method: proxy_list
        args:
          resource: ticket_fields
      label_expr: $.title
      value_expr: $.key
      search:
        on_frontend: true
    target:
      options_source:
        connector: destination
        method: proxy_list
        args:
          resource: ticket-fields
      label_expr: $.label
      value_expr: $.name
      search:
        on_frontend: true

The stored value is an array of { source_field, target_field, transform? } rows. Connector-backed choices must use read-only methods. Large option sets should use server-side search and cursor pagination.

Read configuration in a task

Every step expression can access job_config:

- name: write
  type: call_method
  run_if: "job_config.sync_options.dry_run = false"
  concurrency: 5
  config: |
    {
      "connector": "destination",
      "method": "upsert",
      "args": {
        "table": "tickets",
        "data": input,
        "conflict_columns": ["id"]
      }
    }

For a field mapping, convert the stored row array into the mapping object expected by map_fields, and provide a static fallback so a new job is runnable:

- name: map
  type: map_fields
  config: |
    {
      "mapping": $exists(job_config.ticket_fields)
        ? job_config.ticket_fields{
            source_field: {
              "field": target_field,
              "transform": transform
            }
          }
        : {
            "subject": { "field": "title" }
          }
    }

Edit and verify

On Job Details, open the configuration section, change one entry, and save. Before a production run:

1. confirm required fields are present;
2. verify connector-backed choices still resolve;
3. inspect transformations for representative records;
4. leave destructive behavior in preview mode until validation passes;
5. start the run and confirm its recorded configuration.

For API automation, read GET /api/jobs/{id}/config before writing. Update one key with PUT /api/jobs/{id}/config/{key} and body { "value": ... }.

Avoid these mistakes

• Do not store credentials or private tokens in job configuration.
• Do not use job_config for an identity that must be fixed at job creation.
• Do not assume a later edit changes historical runs.
• Do not use connector write methods to populate option lists.
• Do not enable free-form mapping transforms for users who are not expected to author JSONata.

See Job configuration reference for the field schema and JSONata for expression context.