Reference every job template YAML key: connectors, task nodes, depends_on, connector_mapping, arguments, job_config, and on_failure.

Job template YAML

A job template composes reusable Tasks into a directed acyclic graph (DAG) with type-only connector slots, create-time arguments, and runtime-editable configuration. parseJobDefinition in src/job-parser.ts enforces this schema for files in jobs/, rows in the job_templates table, and envoy job validate. Creating a Job from a template binds real Connectors to the template's connector names and snapshots the resolved YAML.

For the authoring workflow and DAG design guidance, see Job templates and DAGs.

Top-level keys

Key	Type	Required	Description
`name`	string	No	Template name. Defaults to the file name without its extension.
`description`	string	No	Human-readable description.
`arguments`	object	No	Create-time parameters substituted into the snapshot via `${VAR}` placeholders. See Arguments schema.
`job_config`	object	No	Runtime-editable configuration schema copied to each Job. See job_config schema.
`connectors`	object	No	Type-only connector slots: name → `{ type }`.
`tasks`	object	Yes	Task nodes keyed by task key. Must be a YAML object.
`on_failure`	string	No	Failure policy: `pause` (default), `abort`, or `continue`.

`connectors`

Template connectors declare a name and a type only — never credentials. Each entry must be an object with a string type:

connectors:
  source:
    type: csv
  destination:
    type: dynamics365
  mapping_db:
    type: sqlite

When a Job is created from the template, each template connector name is bound to a stored Connector of the same type. Task nodes wire their task's slots to these names through connector_mapping.

`tasks`

Each key in the tasks map is the task key — the stable identifier used by depends_on, targeted runs (--tasks), Triggers, and dashboards. Task keys must be unique because they are YAML map keys.

tasks:
  gen_lookup:
    task: migrations/gen-contact-lookup
    type: command
    connector_mapping:
      mapping_db: mapping_db
  validate_csv:
    task: migrations/validate-contact-csv
    type: validation
    connector_mapping:
      csv_source: source
  migrate_contacts:
    task: migrations/migrate-contact
    depends_on: [gen_lookup, validate_csv]
    connector_mapping:
      source: source
      destination: destination
      mapping_db: mapping_db

Task node keys

Key	Type	Required	Description
`task`	string	Yes	Referenced task definition name (relative to the tasks directory).
`type`	string	No	`command` or `validation`. Omit for a regular task.
`depends_on`	string[]	No	Task keys this node depends on. Every entry must be a defined task key.
`arguments`	object	No	Key-value pairs passed to the task as runtime arguments.
`connector_mapping`	object	No	Task connector slot → template connector name. Values must be defined template connector names.

`type`

command — setup or teardown tasks. Output is parsed as a TaskResult (status: pass | fail | warn with messages).
validation — pre-run checks. A TaskResult with status: "fail" stops the job.
Omitted — regular tasks, evaluated by exit code.

`depends_on`

depends_on is an array of task keys. The parser rejects references to undefined tasks, and the scheduler rejects cycles. Nodes with no dependency path between them run in the same topological level, so the same parameterized task can fan out across sibling nodes and a downstream node can depend on all of them.

`arguments`

Task-node arguments: values are passed to the task verbatim — they are not JSONata and are not interpolated at run time. Only ${VAR} placeholders that name a template-level argument are substituted, once, when the Job is created:

arguments:
  ACCOUNT_ID:
    type: string
    required: true
 
tasks:
  pull_tickets:
    task: migrations/pull-tickets
    arguments:
      integrated_account_id: ${ACCOUNT_ID}

Inside the task, values are read in JSONata as arguments.integrated_account_id.

`connector_mapping`

Maps the task's connector slot names to template connector names:

# Task declares:      connectors: { source: { type: csv }, dest: { type: sqlite } }
# Template declares:  connectors: { csv_source: { type: csv }, db: { type: sqlite } }
connector_mapping:
  source: csv_source
  dest: db

Every mapped value must be a string naming a defined template connector; the parser rejects references to undefined connectors.

`on_failure`

Controls what happens to the DAG when a task fails:

pause (default) — the Job Run pauses so an operator can inspect and resume it (envoy job resume on the CLI, or Resume in the UI).
abort — the run stops.
continue — remaining work that does not depend on the failed task continues.

Any other value is rejected with Invalid on_failure policy: <value> (must be pause, abort, or continue).

Complete example

name: fiserv-migration
description: Migrate from Enact CRM to D365
 
connectors:
  d365:
    type: dynamics365
  mapping_db:
    type: sqlite
  csv_source:
    type: csv
 
arguments:
  ACCOUNT_ID:
    type: string
    required: true
    description: Integrated account ID for the destination org
 
job_config:
  migration_options:
    type: form
    title: Migration options
    fields:
      - key: notify
        label: Notify when complete
        type: boolean
        default: false
 
tasks:
  gen_lookup:
    task: migrations/gen-contact-lookup
    type: command
    connector_mapping:
      mapping_db: mapping_db
      csv_source: csv_source
  validate_csv:
    task: migrations/validate-contact-csv
    type: validation
    connector_mapping:
      csv_source: csv_source
  migrate_contacts:
    task: migrations/migrate-contact
    depends_on: [gen_lookup, validate_csv]
    arguments:
      integrated_account_id: ${ACCOUNT_ID}
    connector_mapping:
      source: csv_source
      destination: d365
      mapping_db: mapping_db
 
on_failure: pause

Validation errors

parseJobDefinition raises these messages (the same checks run in envoy job validate and on template save):

Message	Cause and fix
`Job must be a YAML object`	The file parses to a scalar or array. Start with top-level keys.
`Job must have a tasks object`	`tasks` is missing or not a map. Add at least one task node.
`connectors must be an object`	`connectors` is a list or scalar. Use a name → `{ type }` map.
`Connector "<name>" must have a type`	A connector entry omits `type`. Add a string `type`.
`Task "<key>" must have a task reference`	A node omits `task`. Point it at a task definition name.
`Task "<key>" has invalid type: <value> (must be command or validation)`	Remove `type` or use one of the two values.
`Task "<key>" depends_on must be an array of task keys`	`depends_on` is not a string array.
`Task "<key>" depends on undefined task "<dep>"`	A dependency names a task key that does not exist.
`Task "<key>" connector_mapping references undefined connector "<name>"`	The mapping points at a connector the template does not declare.
`Argument "<name>" has invalid type: <type> (must be string, number, boolean, string[], number[])`	Use a supported argument type.
`Invalid on_failure policy: <value> (must be pause, abort, or continue)`	Use one of the three policies.
`Circular dependency detected among tasks: <keys>`	The `depends_on` graph contains a cycle. Break it.

Validation checks structure only — it cannot verify credentials, network access, or external side effects.

Job templates and DAGs — authoring workflow, fan-out patterns, and task overrides
Arguments schema — every argument definition field and widget
job_config schema — runtime-editable form and field-mapping entries
Commands and flags — envoy job run, resume, status, and validate