Order jobs with dependencies
- Synopsis
- Full Details
In briefA job runs only when all of its dependencies are satisfied. A Job dependency waits
on another job's result, or with Conflict keeps two jobs from running at once; a Threshold
dependency waits on a threshold's value, a Resource dependency on free units, and an
Expression dependency on an expression that renders True. You add them on the job editor's
Dependencies tab.
- Requires waits when the predecessor isn't in the run for the date; After proceeds without it. Conflict takes no Condition.
- Any means a success or a failure result. A cancelled predecessor, or one that missed its start time, satisfies no Condition.
- Inside a workflow built as several schedule instances, a dependency resolves within the same instance. A resource spans instances.
- A Requires dependency on a predecessor that never comes waits indefinitely. Use After for an optional predecessor.
- An expression that renders anything other than
TrueorFalse, including a number, puts the job on hold. - A job can't depend on itself at a Days Offset of
0; the save is blocked.
Dependencies control when each job runs: a job waits until everything it depends on is satisfied. Use them to sequence work (run B after A succeeds), coordinate shared limits, or run recovery steps when something fails.
Jobs that only run on a timer either start before the data they need is ready, or plough ahead after an upstream step has failed, producing wrong results that no one catches until much later.
Dependency types
| Type | A job waits until… |
|---|---|
| Job | A predecessor job behaves as you require — set by its Condition and Type (see the Condition and Type tab), optionally from another day. |
| Threshold | A named threshold compares as you require against a value — pick the comparison as well as the number. |
| Resource | Enough of a named resource is free (the job reserves it). |
| Expression | A custom expression renders True — see Gate a job on an expression. |
- Condition and Type
- Success, Failure, or Any
- Add a Dependency
- Conflicts
- Expressions
Condition and Type
A job dependency has two settings that work together:
- Condition — which result satisfies it: Finished OK, Failed, or Any.
- Type — what happens when the predecessor isn't scheduled for the day:
- Requires (the default) — the job waits. Use it when the predecessor must run.
- After — the job proceeds without it. Use it for "run after this if it runs" ordering.
- Conflict — not about order at all: the job must not run while the other job is running. See Keep two jobs from running at the same time.
When the predecessor is scheduled, Requires and After both wait for it to reach the Condition. The difference only shows when the predecessor is absent that day.
"Isn't scheduled" covers three cases, and the dependency card names them: the predecessor's frequency didn't fire for the date, the predecessor's Disabled switch is on, or it isn't defined in the workflow. A Requires dependency on any of them waits until an Operator adds that predecessor to the run.
Success, Failure, or Any
What counts as success, failure, or any
For a job dependency, each Condition maps to more than one outcome:
| Condition | The predecessor is satisfied when it… |
|---|---|
| Finished OK | Finished OK, including when it was marked finished OK, fixed, or skipped. |
| Failed | Failed, including a marked-failed, an initialization error, or a job flagged under review. |
| Any | Reached either a success or a failure result (above). It does not mean "any outcome." |
If a predecessor is cancelled or misses its start time, it never produced a result, so a dependent (even one set to Any) keeps waiting. That's intended. If you see a job stuck waiting on a predecessor that was cancelled or missed, clear it from Processes with Force Start or Skip, or fix the upstream job.
- A job runs only when all its dependencies are satisfied.
- Depending on Failed or Any is a valid pattern. For example, a cleanup job runs only when its predecessor fails.
- If a job waits on a day the predecessor isn't scheduled, its Type is Requires. Switch it to After when the predecessor is optional.
- A resource dependency makes a job wait for capacity, so use it to keep too many jobs from running at once against a shared system.
If the workflow builds as several named
schedule instances — one run per branch, say — a dependency
between two of its jobs is scoped to the instance it is running in. BRANCH1's job waits on
BRANCH1's predecessor, not on BRANCH2's, so you author the sequence once and every branch gets
its own copy of it.
If two branches genuinely contend for one shared system, that's what a Resource dependency is for — resources span instances.
A dependency remembers which job it points at, not just the name — so renaming a job does not break the workflows that depend on it.
There is one step to finish, though: the dependent workflow's own copy of the name is brought up to date the next time that workflow is saved. So after renaming a job that other workflows depend on, open each of those workflows, save it, and create a new version. Until you do, the version they build from still names the job as it used to be called — even though the editor already shows the job's current name when you open them.
Two related points while you are in there:
- Editing the predecessor name on a dependency card no longer re-points it. The remembered identity wins. To aim a dependency at a different job, re-pick the predecessor rather than retyping its name.
- A conflict authored against a name prefix is the exception — a prefix matches a set of jobs, so there is no single job to remember. Those keep working by name alone.
Add a Dependency
To add a dependency to a job, complete the following steps:
- In the job editor, open the Dependencies tab.
- Select Add New Dependency and choose its Dependency Type (Job, Threshold, Resource, or Expression).
- For a job dependency:
- Choose the predecessor's Workflow — the current workflow or another one — then its Job Name.
- Set the Type (Requires, After, or Conflict).
- Set the Condition (Finished OK, Failed, or Any). A Conflict has no Condition, so the field disappears when you choose it.
- Set a Days Offset if it depends on another day's run:
0is the same day,−1the previous day,+1the next day.
- For a threshold dependency, choose the threshold, the Operator — ≥ (at least), > (greater than), ≤ (at most), < (less than), = (equal to) or ≠ (not equal to) — and the Value. For a resource dependency, choose the resource and either the number of units Required or Use all, which waits until nothing in any environment is using the resource and then takes all of it — see Resource dependencies.
- For an expression dependency, write the expression — see the Expressions tab.
- Select Save.
Depending on the same job in the same workflow at offset 0 is flagged on the dependency card and
blocks the save. A non-zero offset is fine — it points at that job's own previous or next day's run.
A dependency on a job in another workflow draws its own card on the Design canvas — the job name on the first line, the workflow it lives in on the second — with an edge into the job that waits on it. Select that card to open the other workflow in a new tab, so you can check the predecessor without going back to the workflow list. Enter or Space does the same when the card has focus.
The card is display-only otherwise: edit the dependency on the Dependencies tab. If the cards get in the way, turn External Jobs off under Card Filters in the sidebar. See A cross-workflow predecessor on the Design canvas.
A cross-workflow dependency or conflict is now resolved by the referenced workflow's identity, so a rename no longer breaks it — and another workflow taking the old name no longer steals it. Previously a renamed target made a conflict read as absent (so the two jobs ran together) and left an ordering dependency waiting indefinitely.
That applies from the next build, not retroactively. Save and rebuild the dependent workflows before renaming the one they point at: a reference that has not been saved since this shipped is still name-only, and so is a run built from a pinned version whose stored reference carries no identity. See A cross-workflow dependency survives a rename.
Conflicts
Keep two jobs from running at the same time
A Conflict dependency holds the job while a matching job is running (or has finished but not yet reached its final status). Once nothing that matches is running, the job proceeds — and if the other job isn't in the run at all, there is nothing to conflict with, so it proceeds too. Use it when two jobs must not hit the same file or system at once.
- Job name like matches every job whose name starts with what you type, so one rule covers a family of jobs. The Job Name field becomes free text.
- Check all days matches the job on every scheduled date, ignoring Days Offset.
- A job may conflict with itself. With Check all days on, that is the way to say "only one copy of this job runs at a time, across every schedule date".
- Only one member of a set of jobs that conflict with each other is dispatched at a time.
A conflict naming a different workflow matches its name case-sensitively. A name that differs in case matches nothing, so the conflict does not hold the job. See Conflict.
Expressions
Gate a job on an expression
An expression dependency holds the job until your expression renders True. The job waits at
Waiting: Expression Dependency (Wait Expression Dependency on Processes), and the platform re-asks about once a second until it does.
Three rules decide whether your expression does what you meant:
- Only
TrueorFalseanswers the gate (case doesn't matter). A number does not: an expression that renders1does not open the gate, it puts the job on hold. Write a comparison —[[= [[OI.BatchReady]] == "Y" ]]— so it rendersTrue. - A job's expressions are joined with
&&and read as one expression. Parenthesize any half that contains||, or better, put the whole condition in a single expression dependency. - An expression that can't be evaluated holds the job, with the reason recorded against it —
there is no quiet fallback, because text that happened to read
Truewould open the gate. A misspelled property name is enough to trigger this, so check the names before you rely on it.
JI.$EST RUN TIME is the Estimated Run Time (in min) set on the job's frequency, so an
expression can use it once that value is set; without one, the expression holds the job. Other job
facts are available too; see Which run facts an expression can read.
Compare it as text. It and JI.$MAX RUN TIME render as HH:mm:ss, not as
a number of minutes, so > 10 is a type error that holds the job — write > "00:10:00".
An OI. property marked Encrypted cannot be used in an expression dependency. The save is
refused with Encrypted property OI.… cannot be used in an expression dependency, and a job
that reaches one when it runs is put on hold with the same reason. Gate the job on a property that
isn't encrypted. See
An expression is resolved strictly.
If a job is on hold with a reason naming your expression, fix the expression and release the job. See Expression dependencies for the full set of outcomes.
Related topics
- Job dependencies — full configuration reference and troubleshooting
- Add jobs to a workflow (Builder)
- Workflow Settings (Builder)