Job configuration

See How workflows work for the model.

Task walkthrough: Create a workflow. This page is the full configuration and troubleshooting reference.

A job is the unit of work in a workflow. It runs one job type on an agent and carries its own timing, ordering, and outcome handling.

Job fields

Field	Type	Default	Notes
id	string	assigned	The job's own identifier, a UUID assigned when the job is first saved. Not shown on the canvas or in the job editor; you see it only in the Code view. See below.
name	string	—	Job name (unique within the workflow). Must contain at least one non-whitespace character — a blank or whitespace-only name is rejected when the workflow is saved.
taskDefinition	object	—	The job type to run: taskTypeName, optional taskTypeVersion, and parameters. See How connectors work.
agentAssignment	object	—	Where the job runs (see modes below).
frequencies	map	—	One or more frequencies with runtime settings. See Scheduling and the run.
dependencies	list	—	What must be satisfied before the job runs. See Job dependencies.
connectionRefs	list	empty	The connection the job dispatches with — for a legacy job, the batch user it runs as. At most one. Set from the Batch User field on the job; see below.
events	list	—	Actions fired on certain outcomes. See Workflow events.
properties	list	—	Job instance properties (name/value pairs; a value may be encrypted).
customFields	map	—	Values for admin-defined custom fields, keyed by definition.
tags	list	—	Labels for organizing/searching jobs.
disabled	boolean	false	The Disabled switch on the job's Details section. A disabled job is left out of every build of the workflow — see A disabled job is left out of the build.
multiInstance	boolean	false	Allows more than one concurrent instance.
documentation	string	empty	Free-text notes on the job.

A disabled job is left out of the build

Disabled is a switch on the job's Details section, beside Multi-Instance. A disabled job is skipped before its frequencies are looked at, so it never reaches the build manifest — for a scheduled build, an automatic daily build, and a container's build of a sub-workflow alike. The frequency forecast leaves it out too, because the forecast previews the build.

Four things follow, and each of them catches someone:

• Its dependents see it exactly as they would a job whose frequency didn't fire. No instance of it exists, so an After dependency proceeds without it and a Requires dependency waits. See Job dependencies.
• A workflow whose every job is disabled does not build at all — there is nothing left to qualify.
• Its frequency and calendar references still have to resolve. Disabling a job does not excuse a dangling reference; the workflow still refuses to save or build over one.
• An operator can still add it to a built instance on demand. Disabling parks a job; it does not remove it. The job appears in the Processes page's Add job list with a Disabled badge, so adding it is a deliberate act rather than an accident.

Disabling the job is not the same as setting one of its frequencies to a build status of disabled. The switch takes the whole job out of every build; the frequency setting turns off that one frequency and leaves the job's others in play. See Per-frequency runtime settings.

Every job carries an id of its own

Each job definition is given an id — a UUID — the first time it is saved, and keeps it from then on, including through a rename. Existing jobs were given one automatically. The editor manages it for you; you never need to type one.

It matters in six places:

• The Code view shows it. Editing a workflow's configuration as JSON, you'll see id on every job. Leave it alone: it is what tells the platform this is the same job you saved last time. Delete it and the job is treated as new and given a fresh one.
• Copy and paste creates a new job. Copying jobs on the canvas strips the id, so a pasted job is a genuinely new job even when you paste it back into the same workflow.
• An id can only belong to one job. Pasting an id that another workflow already owns is rejected when you save, with a message naming the offending id so you can find it in a large configuration.
• Every job instance the build creates carries it, so a run can be traced back to the definition it came from even after the job has been renamed. It travels on the job's status events too.
• A dependency on this job records it. A job dependency stores the predecessor's id alongside its name, and the id is the primary key of the pair — see Job dependencies.
• A deployment transformation rule cannot change it. The id is protected, because a rule that rewrote it per environment would give one definition a different identity in each — see Fields no rule may change.

What that identity buys you today: a notification group can name one specific job and keep matching it after a rename, and a job dependency keeps pointing at the job it named when that job is renamed.

An import that overwrites an existing workflow re-assigns ids to the jobs it replaces.

A job from an older workflow version may not have an id yet

Jobs were given ids as workflow versions were saved, so a job in a version that predates that has none. Anything that needs the identity — being named as a notification group member, for instance — will not offer it. Creating a new version of the workflow gives its jobs ids.

The account a legacy job runs as

A legacy Windows, UNIX, IBM i, or SQL job runs as a batch user — a saved connection holding the account, and on Windows and SQL its password. You pick it from the Batch User field on the job; the definition stores only a reference.

Two fields carry that reference, and knowing which is which matters when you edit a configuration by hand or write a transformation rule:

Field	Role
connectionRefs	Authoritative. This is what the build stamps onto the job instance and what the agent is given. A job takes at most one entry.
taskDefinition.parameters.batchUserId	A display mirror of the same id. It is what the parameter list and the Code view show.

The editor writes both together, so they normally agree. If they diverge — a hand-edited Code view, an import, or an API call that moves one without the other — the next ordinary save corrects the mirror to match the reference, because the reference is what dispatches. Nothing about what runs changes; only the display is repaired.

That is also why a deployment transformation rule may not target the mirror. A rule there would look active and change nothing, and the job would authenticate as the source environment's account. Target $.jobs[*].connectionRefs[0].id instead — see Fields no rule may change.

Why the job name can't be blank

Within a workflow, the name is how you and almost everything else address a job: a dependency carries its predecessor's name beside the id, and the run itself is matched by name. A blank-named job can't be depended on, found, or unambiguously edited, so the name is required to hold at least one non-whitespace character. This is enforced when the workflow is saved, whether the save comes from the editor or from the API.

Custom-field errors name the job

When a save is rejected because of a custom field, the message names the job as well as the field — "Job 'Nightly Extract' is missing required custom field 'Cost Center'" — so you can find the job in a workflow of dozens without checking each one. The same applies to a value of the wrong type, a value outside a select field's options, and a reference to a custom field that doesn't exist. See Custom fields.

An incomplete job blocks the whole version

A job that could not dispatch now blocks Create Version for the workflow it is in, and is flagged with a red border on the canvas. That covers a job with no job type, a missing required task parameter or custom field, a duplicate or over-long name, a job type this workspace can't run, and a missing agent assignment where the job type needs one.

It applies to jobs that were already stored, not only to the one you just edited — so a job that predates a rule has to be opened and completed before the workflow can be versioned again. See Workflow versions and deployments.

Agent assignment modes

Mode	Behavior
Specific agent (agent)	Runs on the chosen primary agent. Secondary / tertiary / quaternary agents are saved but not used: there is no failover. A Universal Agent job goes on its pool's queue, so any agent in that pool can run it.
Pool — least-tasked (pool-least-tasked)	Runs once, on whichever agent in the named pool asks for work first.
Pool — run-all (pool-run-all)	The same as least-tasked for a Universal Agent pool: the job runs once. A legacy agent group set to run on all fans out to one job instance per member — see Agents and agent pools.

Good to know

• Encrypted properties return no value when read back (the value is null on GET) — that's by design, not data loss.
• A job pointing at a job type that needs a connection (e.g. SQL) won't run until that connection is attached — see the connector docs.
• agentPool on a job is a deprecated field; current jobs use agentAssignment. If both appear, treat agentAssignment as authoritative.
• A disabled job, or a build status of doNotSchedule/toBeSkipped, is intentional — check before treating a "missing" job as a fault.