# Configure a job between runs

> Source: https://docs.clonepartner.com/guides/job-configuration/

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](/guides/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:

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

```json
{
  "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:

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

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

```yaml
- 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](/reference/job-config) for the field schema and [JSONata](/reference/jsonata) for expression context.