Job configuration
- Synopsis
- Full Details
In briefA job is one unit of work in a workflow. It names a job type and its parameters, where
it runs, when it builds, what it waits for, and what it does on each outcome. Each job also has an
id of its own, given the first time it is saved, which survives a rename.
WhereIn Design › Workflows, open a workflow and open the job in the Job Editor
(open its context menu on the canvas › Edit Job). Its tabs are Job Definition, Properties,
Frequencies, Dependencies, Events and Documentation. Job Definition holds the
Details (including Disabled and Multi-Instance), Job Type, Agent Assignment and
Job Parameters sections. The workflow's Code view shows the same job as JSON, including its
id.
WhenUse this page when you need to:
- know what each part of a job controls, and its default;
- choose how a job is placed on an agent;
- find out why a version will not commit, or why a job did not build;
- edit a job's configuration by hand and keep its identity.
How
- Name the job. The name must be unique in the workflow and cannot be blank.
- Choose the job type and fill its required parameters.
- Choose an Agent Assignment mode where the job type needs one: Specific Agent, Pool - Least Tasked or Pool - Run on All.
- Add frequencies, dependencies, events and properties.
- Save, then commit the workflow to a version.
For the full steps, see Add jobs to a workflow.
- A disabled job is left out of every build. Its dependents treat it like a job whose frequency did not fire.
- On Specific Agent, the secondary, tertiary and quaternary agents are used, in that order, when the primary cannot take the job — see Backup agents.
- For a legacy job,
connectionRefsis what decides the account it runs as. The batch user id shown in the parameters is only a copy of it. - An incomplete job blocks Commit changes to a version and is flagged on the canvas.
- The Documentation tab shows web addresses as links that open in a new tab. Edit opens the text box, and Done returns to the view.
- Leave a job's
idalone in the Code view. If you delete it, the job is treated as new. - Pasting an
idthat another workflow already owns is refused at save. - A deployment transformation rule cannot target the Connection parameter (
batchUserId). TargetconnectionRefsinstead. - A disabled job still needs its frequency and calendar references to resolve.
- Multi-Instance cannot be turned off while the job has more than one property group. Remove all but one first, or in the same save. A job already saved that way fails the build and Add Job.
See How workflows work for the model.
Task walkthrough: Add jobs to 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
- Agent Assignment Modes
- Disabled and Multi-Instance
- Job Identity
- Connection
- Save and Version Checks
Job Fields
| Field | Default | Notes |
|---|---|---|
id | 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 the Job Identity tab. |
| 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, and at most 255 characters. |
| Job Type | — | The job type to run, chosen in the Job Type section, with its settings under Job Parameters. The list offers only the job types turned on for your organization; a job whose type has since been turned off keeps it, and still saves and runs — see Plugins. See How connectors work. |
| Agent Assignment | — | Where the job runs (see the Agent Assignment Modes tab). |
| Frequencies tab | — | One or more frequencies, each with its own runtime settings. See Scheduling and the run. |
| Dependencies tab | — | What must be satisfied before the job runs. See Job dependencies. |
| Connection | empty | The connection the job dispatches with — for a legacy job, the batch user it runs as. At most one. See the Connection tab. |
| Events tab | — | Actions fired on certain outcomes. See Workflow events. |
| Properties tab | — | Job instance properties: name and value pairs, each of which can be marked Encrypted. |
| Custom fields | — | Values for admin-defined custom fields, each shown under its own label in the Details section. |
| Tags | — | Labels for organizing and searching jobs. You can add several. |
| Disabled | Off | A switch in 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. |
| Multi-Instance | Off | A switch in the job's Details section. The job runs once per property group, each an instance on its Properties tab. It cannot be off while the job has more than one property group — see Multi-Instance stays on while a job has several instances. |
| Documentation tab | empty | Free-text notes on the job. Web addresses in it are links — see The Documentation tab. |
The Documentation tab
The Documentation tab shows a job's notes as text, with every http:// or https:// address in
them turned into a link that opens in a new browser tab. The same tab is on a job in Design and
on a job instance edited on Processes.
- Edit switches the tab to a text box, and Done switches it back to the view. Your text is saved with the job, as before; Done does not save on its own.
- A job with no documentation opens straight in the text box, so you can start typing.
- Where you cannot edit the job, the tab shows only the view, with no Edit button, and reads No documentation. when there is none.
- Only
http://andhttps://addresses become links. Any other address, such asmailto:orftp://, or a bare host name likewww.example.com, stays plain text. Punctuation straight after an address, such as a full stop, a comma or a closing parenthesis the address did not open, is not part of the link.
Documentation on workflows, calendars, frequencies and other objects stays plain text: addresses there are not links.
Agent Assignment Modes
| Mode | Behavior |
|---|---|
Specific Agent (agent) | Runs on the chosen primary agent. When the primary cannot take the job, it runs on the first available secondary / tertiary / quaternary agent — see Backup agents. 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. For a legacy agent group, the platform picks an online member when it dispatches. |
Pool - Run on 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. |
Not every job type allows every mode. SMAFT File Transfer and OpCon RPA Task jobs run on Specific Agent only, with no backup agents: the editor offers nothing else, and a save that sets another mode or a backup agent on one is refused. See Which assignments a job type allows.
- An encrypted property's value is withheld when a job instance is read back (it comes back null) — 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.
- In the Code view,
agentPoolon a job is a deprecated field; current jobs useagentAssignment. If both appear, treatagentAssignmentas authoritative. - A disabled job, or a Build Status of Do Not Schedule or To Be Skipped, is intentional — check before treating a "missing" job as a fault.
Disabled and Multi-Instance
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.
Multi-Instance stays on while a job has several instances
A multi-instance job runs once per property group. Each group is an instance on the job's Properties tab, added with Add Instance and named in Instance Name. A job that is not multi-instance has a single group of its own.
While the job has more than one group, Multi-Instance cannot be turned off. In the workflow's job editor the Multi-Instance switch is locked on, with the hint "Remove all but one property group to turn this off." Turning it on is never restricted.
The same rule is checked when the workflow is saved, whether from the editor, the Code view, the API or an import. A configuration with the switch off and more than one group is refused, naming the job: "Cannot turn off Multi-Instance on job '…' while … property groups are defined. Remove all but one in the same update." Only what you are saving is checked, so turning the switch off and removing the extra groups in one save is accepted.
The build and Add Job apply the same rule. A job with Multi-Instance off and more than one property group fails the build once its frequency applies, and no instance of the workflow is built for that date. The message names the job: "Job "…" has Multi-Instance off but … property groups defined; turn Multi-Instance on or remove all but one group". This holds on a job that runs on all agents in a group too. Adding such a job to a running workflow instance with Add Job is refused with the same message.
Earlier builds let the switch be turned off with several groups still defined. The workflow saved,
and its build then took the job's properties from its group named Default, or, when it had none,
was refused with a message about a missing default group rather than the switch. A workflow saved
that way still holds that shape: it no longer builds, and its next save is refused, until the job is
fixed. Turn Multi-Instance back on, or remove all but one property group.
Job Identity
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
idon 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.
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.
Connection
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 Connection 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 save from the workflow editor 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.
Save and Version Checks
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. A save refuses a missing required value, a value that does not fit its field (the message names the value too: Job 'Job-1' has an invalid value '5' for custom field 'Priority': …). Before it checks, the save gives a job with no value each field's default and removes a value for a custom field that was deleted or has never existed, and the editor warns you which values it removed. A required field with a usable default therefore blocks a save only when you cleared its value on the job. See How a default reaches a job.
A new job keeps the defaults its form shows
When you create a job, every required job-type field that has a default — Destination File
Filter * on an OpCon MFT transfer, the configuration file on a Corelation or Fiserv DNA job, the
transfer options on an SMAFT File Transfer — is stored on the job with that default. Saving without
touching those fields keeps exactly the values the form showed, and the save is accepted. Change a
value and your value is stored instead; clear it and the save refuses the empty field, as for any
required field.
Property names that differ only in case are refused
Within one job's Properties tab, two property names in the same group may not differ only in capitalisation. Host and HOST are the same name, and a built job instance refuses to be edited while it holds both. Design now applies that rule when the pair is created, not when the run is edited:
- In the job editor, the property row says Same name as 'Host' (case is ignored), and the save message names both: Property 'HOST' has the same name as 'Host' when case is ignored. Property names must be unique, ignoring case. When the job has more than one property group, the save message begins with the group it is in — Property group 'EU': …. The same grid is used by the Process View job editor and by Add Job.
- A workflow save, copy or import is refused with a message that names the job, the group when the job has more than one, and both properties: Property 'HOST' on job 'Extract' has the same name as 'Host' when case is ignored. Property names must be unique within a property group, ignoring case; rename or remove one. An exact repeat reads Property 'Host' on job 'Extract' appears twice. Property names must be unique within a property group; rename or remove one. Nothing is saved.
- A workflow that already holds such a pair stays editable. A save is checked only for the groups it touches: a new job, or a group whose property names the save changes. Changing a property's value, or anything outside that group, is accepted, and a change to that group's names has to fix the pair.
- A deployment is not refused. A transformation rule that renames a property onto another that differs only in case can still create a pair at deployment. The workflow is served as it is, and that job cannot be edited on a built instance until the pair is fixed.
A workflow's own schedule instance properties follow the same rule, checked on the Instance Properties tab and at Create Version — see Property names that differ only in case.
A job's agent name and agent must agree
A job's agent is stored as the agent's identity with its name beside it, in each of the primary, secondary, tertiary and quaternary slots. The job editor shows the name; the job runs on the agent the identity points at. A legacy agent behind a relay also carries a machine name, which is the machine the relay runs the job on. The job editor sets all of these together when you choose an agent. A hand edit in the Code view can split them, so saving a workflow checks each job the save adds or changes, and refuses the save, naming the job, when:
| The job's agent | Message |
|---|---|
| Identity matches no agent here | Job 'Load': primary agent 'AGT-01' (id '…') matches no agent here. Choose another agent. |
| Name is a different agent's from the one the identity points at | Job 'Load': primary agent name 'AGT-02' does not match agent id '…' (agent 'AGT-01'). Choose the agent again, or set the id and name to the same agent. |
| Machine name, on a legacy agent behind a relay, is not that agent's name | Job 'Load': machine name 'AGT-02' does not match primary agent 'AGT-01'. Choose the agent again, or set the machine name to 'AGT-01'. |
Names are compared without regard to case, except the machine name. A job the save leaves as it is is not checked, so a workflow whose agent was renamed or deleted since its last save stays editable, and a job copied by Copy Workflow is not checked against its source. If the agents cannot be looked up when you save, the check is skipped rather than blocking the save. Earlier builds saved such a job, which then showed one agent and ran on another.
An incomplete job blocks the whole version
A job that could not dispatch now blocks the commit action (Commit changes to a version) for the workflow it is in, and is flagged with a warning border on the canvas; hovering the job shows the problem. 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.