Job 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, a Threshold dependency on a threshold's value, a Resource
dependency on free units of a resource, and an Expression dependency on an expression that
renders True. A job dependency has a Condition, a Type and a Days Offset.
WhereThe Dependencies tab of the job editor, opened from a job in Design › Workflows, or from a job of a running instance in Processes. Add New Dependency adds one; its Dependency Type picks Job, Threshold, Resource or Expression. On the workflow canvas, drawing an edge between two jobs opens the New Dependency dialog.
When
- One job must wait for another to finish OK, to fail, or either.
- Two jobs must never run at the same time, or a job must never overlap another copy of itself.
- A job must wait for a threshold value, enough of a shared resource, or a condition you can express.
To decide which days a job is in the run at all, use its frequencies instead; see Frequencies.
How
- Open the job's Dependencies tab and select Add New Dependency.
- Choose the Dependency Type. For a job dependency, pick the Workflow and Job Name, then set Condition, Type and Days Offset.
- Save the job, then commit and deploy the workflow.
The full steps are on Order jobs with dependencies.
- Requires waits when the predecessor is not in the run for the date; After proceeds. Conflict keeps two jobs from running together and takes no Condition.
- Any is the ignore-error union of the success and failure statuses. A cancelled predecessor, or one that missed its start time, satisfies no Condition.
- Days Offset runs from −365 to +365. A job cannot depend on itself on the same day.
- 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 conflict on a different workflow that carries only the workflow's name matches it case-sensitively. A name that differs in case matches nothing, and the conflict does not hold the job.
See How workflows work.
Task walkthrough: Order jobs with dependencies. This page is the full configuration and troubleshooting reference.
A job runs only when all of its dependencies are satisfied. Dependencies are how a workflow is sequenced and how jobs coordinate shared state and capacity.
Dependency types
| Type | Satisfied when | Key settings |
|---|---|---|
| Job | A predecessor job behaves as the two dependency axes require (see the Job Dependencies tab) | Predecessor Workflow + Job Name, Condition (Finished OK / Failed / Any), Type (Requires / After / Conflict), Days Offset |
| Threshold | A named threshold compares as required against a value | Threshold, Operator, Value — see Threshold dependencies |
| Resource | Enough of a named resource is available (the job reserves it) | Resource, and either Required (a unit count) or Use all — see Resource dependencies |
| Expression | A custom expression evaluates to True | The expression text — see Expression dependencies |
- Job Dependencies
- Conflicts
- Resource Dependencies
- Threshold Dependencies
- Expression Dependencies
- Across Workflows and Instances
- Identity and Renames
- Troubleshooting
Job Dependencies
The two axes of a job dependency
A job dependency has two independent axes. Set both on the job editor's Dependencies tab, or on the workflow canvas when you draw the dependency:
- Condition — which result of the predecessor satisfies the dependency: Finished OK, Failed, or Any (the ignore-error union).
- Type — what happens when the predecessor is absent from the schedule for the resolved date:
| Type | Predecessor is present | Predecessor is absent for the date |
|---|---|---|
| Requires (default) | Waits for it to reach the Condition | Waits — the dependency is not met |
| After | Waits for it to reach the Condition | Proceeds — the dependency is treated as met |
Use After for "run after this if it runs" ordering, so an optional or conditionally scheduled predecessor doesn't stall the dependent on a day it isn't scheduled. Use Requires (the default) when the predecessor must actually run.
"Absent for the date" has three causes, and the dependency card names all three: the predecessor's frequency didn't fire for this date, the predecessor is Disabled, or it isn't defined in the workflow at all. A Requires dependency on an absent predecessor waits until an operator adds that predecessor to the instance.
A third Type, Conflict, inverts the relation entirely — it is about not running at the same time rather than about order. It is covered on the Conflicts tab.
A dependency with no explicit Type behaves as Requires and keeps its previous behavior. Editing the job does not add one: the Type control shows Requires, and the dependency is saved without a Type unless you change that control.
Days Offset
Days Offset (−365 to +365) lets a job depend on a predecessor from a different day's run:
0 is the same day, −1 the previous day, +1 the next day. The offset resolves against that
day's instance of the predecessor, so a job can wait on — or run after — yesterday's or tomorrow's
run of another job.
A self-reference at a non-zero offset is allowed and points at the job's own prior or next dated
run. A job cannot depend on itself on the same day (same workflow, same job, offset 0); that
combination is now flagged on the dependency card as you author it and blocks the save, rather
than only being refused by the platform once you try to save.
Choosing a predecessor
A predecessor can be in the current workflow or another workflow — pick the workflow, then the job. When you edit a job dependency inside a running instance (from Processes), the Workflow field is read-only: a new dependency points into the instance's own workflow, and an existing one keeps the workflow it names.
If a predecessor can't be resolved, the dependency shows a warning naming the cause — either the job is absent from the dated schedule, or it has an instance with this job's instance name that is not in this workflow instance yet. See A dependency between multi-instance jobs.
How job dependencies resolve
Every dependency on a job is checked, each by its own test, and the job runs only when all of them are satisfied. If any one is not, the job keeps waiting and its dependencies are checked again. One exception is not drawn: an expression that cannot be evaluated puts the job on hold — see What each outcome does to the job.
- Condition matters: Finished OK waits for the predecessor to finish OK, Failed waits for it to fail, and Any proceeds on either. A dependency on Failed or Any is valid design (e.g. a cleanup job that runs when its predecessor fails).
- Type decides the absent-predecessor case only — see the two-axis table.
- Days Offset lets a job depend on a predecessor from a different day's run.
- Resource dependencies reserve capacity — a job waits if not enough of the resource is free.
Which predecessor statuses satisfy each Condition
A Condition is not a single status — each maps to the set of terminal statuses that release the dependent:
| Condition | Satisfied by | Notes |
|---|---|---|
| Finished OK | Finished OK, Marked Finished OK, Skipped, Fixed | A skipped or marked-fixed predecessor counts as success. |
| Failed | Failed, Marked Failed, Initialization Error, Under Review | Under Review is a deliberate non-terminal release point — the operator has acknowledged the failure, so recovery work starts without waiting for it to be marked Fixed or Failed. |
| Any | The union of the two lists above | Any is the ignore-error union, not "any outcome." |
- Cancelled and Missed Start Time satisfy nothing under any condition — a predecessor that never produced a result cannot release its dependents. Lost in Failover satisfies nothing either: its result is unknown, so neither a Finished OK nor a Failed dependent runs until a real result arrives or an operator marks the job. A job depending (even with Any) on a predecessor that ends up cancelled or missing its start time will wait forever; that's the intended behavior, not a bug. Clear it with Force Start / Skip or fix the upstream job.
- The pending statuses (Finished OK (Pending), Failed (Pending) and the other (Pending) statuses) do not satisfy dependents — the predecessor must reach its final terminal status first.
Conflicts
Conflict — keeping two jobs off each other
Requires and After both say "run in this order." Conflict says something different: this job must not run while that job is running. It constrains concurrency, not order.
Use it for the classic mutual-exclusion cases — two jobs that must not hit the same core file at once, or a singleton job that must never overlap another copy of itself on a different schedule date.
A Conflict dependency behaves unlike the other two in several ways:
| Difference | Requires / After | Conflict |
|---|---|---|
| Condition | Required (Finished OK / Failed / Any) | None — a conflict has no Condition, and setting one is rejected |
| Satisfied when | The predecessor reached the Condition | No matching job is currently running |
| Predecessor absent | Waits (Requires) or proceeds (After) | Proceeds — nothing to conflict with |
| Name matching | Exact job name | Exact, or a name prefix (Job name like) so one rule covers a family of jobs |
| Day scope | The date the Days Offset resolves to | That date, or every scheduled date (Check all days), which ignores Days Offset |
Two more behaviors worth knowing:
- A job may hold both a Conflict and an ordering dependency on the same predecessor. "Wait for X, and also don't run alongside X" are two different statements, so they are kept as two records.
- A job may conflict with itself. Only the job's own instance is left out of the match, so a same-day self-conflict settles as satisfied, unless the job fanned out into several multi-instance copies; then it keeps those copies from running at once. Combined with Check all days, a self-conflict is the standard way to express "only one copy of this job runs at a time, across every schedule date" — the ordinary singleton guard.
A job is held while a matching job is running, has finished but not yet reached its final status, or is Lost in Failover. Once no match is in any of those states, the dependency is satisfied and the job proceeds.
A conflict that names its own workflow is recognised as a same-workflow conflict whatever the
capitalization and surrounding spaces — payroll and PAYROLL are the same workflow, and the
conflict holds the job as intended.
A conflict naming a different workflow is matched by that workflow's identity when the dependency carries it (see A cross-workflow dependency survives a rename). A reference that carries only the name is matched case-sensitively. If it does not match a workflow that is built and resident, there is nothing to conflict with and the dependency is satisfied, so the job runs. Pick the predecessor's workflow from the list rather than typing it: a name-only reference that differs in case names nothing, and the conflict will not hold the job.
When several jobs conflict with each other
If two or more jobs declare conflicts on one another and all of them are waiting on that conflict — none actually running — the platform releases them one at a time rather than releasing the whole set together. The rest stay waiting and are reconsidered on the next pass.
Either way, only one member of a conflicting set is ever dispatched at a time. That guarantee is enforced where jobs are dispatched, not by the order they leave the waiting state, so a conflict does its job even when several members become eligible in the same pass.
Authoring a conflict
Set Type to Conflict on a dependency, the same way you set Requires or After — on the job editor's Dependencies tab (from either the Workflows page or the Processes page) or in the New Dependency dialog. Because a conflict carries no Condition, that field disappears when you choose it.
When you turn on prefix matching (Job name like), the Job Name field becomes free text: you are naming a pattern that jobs start with, not picking one existing job.
On the Workflows canvas a conflict is drawn as its own edge — dashed and without an arrowhead, since it expresses no order. A self-conflict draws as a loop on the job itself, and a prefix conflict draws against a node standing for the pattern rather than any one job. A conflict on a job in another workflow draws as a conflict edge to a card standing for that external job.
When a job is held by both an unmet ordering dependency and a conflict, the ordering dependency is the one reported as the reason it is waiting. A conflict is a transient "something else is running right now", so surfacing it over a genuine unmet precondition would send you after the wrong thing.
Resource Dependencies
A resource dependency holds the job until enough of a named resource is free, and the job takes those units while it runs. There are two ways to say how much it needs:
| Setting | The dependency is satisfied when |
|---|---|
| A unit count | At least that many units of the resource are free. |
| Use all | The resource is entirely free, in every environment, and its total is above zero. The job then takes every unit of it. |
Free means free across every environment. A resource's total is one pool that all your environments share, so units held by jobs in another environment are not free here. See One total for every environment.
Use all is for the job that must not share — a nightly reorganisation that cannot run alongside anything else using the same system. A count of units cannot express it, because a resource with spare capacity would let a second job in.
- Its own total is what it takes, as of the moment it takes them. Lowering the resource's total while such a job runs does not change what it gives back: the release returns what was actually allocated.
- It needs a total above zero. A resource whose total is
0is never entirely free in a meaningful sense, so a Use All dependency on one is never satisfied. - A unit count and Use All are alternatives, not a pair. Pick one.
A waiting Use All job reserves the resource
A job that needs a whole resource would otherwise never get it on a busy system — a steady trickle of small jobs each taking a unit or two means the resource is never completely free at any one moment. So while a Use All job is waiting for a resource, that resource is reserved for it:
- Jobs of the same or lower priority cannot take units of it, at the dependency gate or at dispatch. They wait.
- A job of strictly higher priority still can — that is what priority is for.
- A job that already holds units of the resource can proceed, so it can finish and give them back. Refusing it would deadlock the job that is waiting.
Which job reserves it is decided each sweep rather than being claimed and kept: of the jobs with a Use All dependency that have reached the resource gate and not yet started, the one that comes first by priority, then schedule date, workflow, run, and job name. A job becomes the reserver only once its unit-count resource dependencies are all met, and it reserves every Use All resource it needs at once — two jobs can therefore never end up each holding what the other is waiting for.
The reservation needs no cleaning up. It is re-derived from job statuses on every sweep, so it is released on the next sweep after the job starts, is held, is cancelled, or falls back to an earlier wait.
The reservation holds in every environment. A resource's total is shared by all your environments, and so is the reservation: jobs in your other environments of the same or lower priority cannot take units of a resource a Use All job is waiting for, and a job there of strictly higher priority, or one that already holds units of it, still can. When Use All jobs in two environments wait for the same resource, it is reserved for the one that comes first in the same order, so a job in one environment cannot be kept waiting for good by small jobs in another.
- If an environment stops renewing its reservation — it is down, for instance — the reservation lapses two minutes after it was last renewed.
- If an environment cannot reach the shared reservation on a sweep, it keeps honouring the other environments' reservations it last heard about until each would have lapsed, and after that falls back to the reservations of its own jobs only.
Earlier builds kept the reservation within the waiting job's own environment, so jobs in another environment went on taking units whatever their priority, and while they kept some in use the Use All job waited.
When a job has both kinds, its unit-count dependencies are taken before its Use All ones. A failure part-way through therefore never takes a whole resource only to hand it straight back.
A unit-count hold the job no longer tracks is given back, not waited on. If the platform finds the job already holds units of the resource at a different count from the one it now asks for, it gives that hold back and asks once more. If the second request finds too few units free, the job waits for the resource as usual. Earlier builds treated that hold as the resource being full, so the job moved to Waiting: Resource Dependency and back on every pass and never ran.
Threshold Dependencies
A threshold dependency holds the job until a named threshold compares as required against the value on the dependency. You choose the comparison:
| Operator | Satisfied when the threshold is |
|---|---|
| ≥ (at least) | at or above the value |
| > (greater than) | above the value |
| ≤ (at most) | at or below the value |
| < (less than) | below the value |
| = (equal to) | equal to the value |
| ≠ (not equal to) | anything but the value |
≥ (at least) is what a dependency with no operator set means, so a dependency authored before the operator existed keeps the behavior it had.
The workflow canvas draws the operator on the dependency's edge — ≥ 5, < 10 — so the comparison
the job is waiting on is readable without opening the job.
If the threshold a dependency names has been deleted, the dependency is treated as satisfied and the job proceeds. That keeps a deleted threshold from silently parking every job that referenced it.
That is the only case that releases the job. Anything else that stops the value being read — the threshold is not found, nothing is configured, a refusal, a service error — leaves the dependency blocking, because the threshold may exist and the answer is unknown. Releasing a job cannot be undone, so an unreadable threshold fails closed.
Two consequences follow from that, and they are the ones worth knowing:
- A renamed threshold blocks. A dependency saved without the threshold's identifier is looked up by name instead, and a name that matches nothing is "not found" rather than "deleted" — so the job waits rather than being released. Every dependency authored in the current job editor carries the identifier, so this affects imported ones.
- A threshold identifier that never existed blocks too, for the same reason. An automation import keeps the identifiers from the bundle it came from, so a dependency can arrive naming one this environment has never had.
A dependency carrying neither an identifier nor a name blocks without looking anything up.
Expression Dependencies
An Expression dependency holds the job until a custom
expression evaluates to True. The job waits at
Waiting: Expression Dependency while it is being asked, and the platform re-asks it about once a
second until it answers True — an expression is never a once-and-done fact, so a job that
satisfied it and then restarted on a recurring cycle is asked again.
All of a job's expressions are evaluated as one expression
A job's expression dependencies are joined with && and evaluated as a single expression,
not evaluated separately and then ANDed. Line breaks and tabs are removed from the joined text
rather than replaced with a space, so an expression split across two lines is rejoined with nothing
between the halves.
||&& and || share one precedence level and associate left to right, so the join is not the
same as requiring each expression separately. A first expression A and a second written
B || C join to A && B || C, which reads (A && B) || C: the gate opens whenever C is true,
whatever A says. Parenthesize each expression you author — (B || C) — and prefer one
expression dependency carrying the whole condition over several that have to be read together.
The stored value is the expression body. A pasted [[= … ]] wrapper is stripped from each
expression before the join, so authoring it either way works.
Only True and False answer the gate
The rendered result is read with the same parse as the ToBool operator: true
or false, case-insensitively, with surrounding whitespace tolerated. Nothing else counts.
1 is not true, and 0 is not falseA number is refused outright, and so is a non-empty string — there is no truthiness here. An
expression that computes 1 + 0 does not satisfy the dependency; it puts the job
on hold. Write a comparison — [[= 1 + 0 > 0 ]] — so the
expression renders True.
What each outcome does to the job
| The expression | What happens to the job |
|---|---|
Renders True | Advances to the next waiting status, and on to dispatch when its other dependencies are met |
Renders False | Stays at Waiting: Expression Dependency and is asked again on the next pass. This is the normal steady state of a gate that is not open yet |
Is malformed, renders something that is neither True nor False, or renders nothing | The job is put On Hold, and the reason is recorded as its termination description |
| Could not be answered because something it reads was temporarily unavailable | Stays at Waiting: Expression Dependency and is retried on the next pass — the same as False. A transient fault is not treated as a bad expression |
A job carrying no expression dependency is unaffected by any of this.
The failure text is the job's termination description, so it appears on the job detail panel, on the job's node on the workflow diagram, and as the marker beside its name in the jobs list. It leads with the cause and then names the authored expression, and it never contains a resolved value — so no property's value reaches an operator-visible message. Very long text is truncated.
Release the job once the expression is corrected. A job that was held, released and then ran successfully no longer carries the old failure text into its own result.
A job released from an expression hold goes back to waiting with that failure text cleared, so a
job that parks at Waiting: Expression Dependency because the expression is now merely False reads as
what it is — waiting, with nothing wrong — rather than still showing the text from the hold. The
cleared text also stops $JOB TERMINATION carrying it into later status events.
Only the gate's own text is cleared. A reason recorded by anything else — an operator's reason for holding the job, a failed prerun, a note the build left on a container job — is left alone, so releasing the job never erases a message the gate did not write.
An expression is resolved strictly, and against stored values
Two things about resolution differ from an expression in a job parameter:
- There is no degraded reading. A token the platform cannot resolve fails the expression instead
of rendering as its own source text, because source text that happens to read
Truewould open the gate. So a misspelled property name holds the job. - An encrypted global property cannot be an operand. An expression dependency may not read an
OI.property marked Encrypted. Saving a workflow, importing one, or saving an edit to the job on a running instance is refused with Encrypted property OI.… cannot be used in an expression dependency, naming the job on a workflow save. A gate that still reaches one when it runs puts the job On Hold, with Encrypted property OI.… cannot be used in an expression dependency as its reason. The message names the property and never its value.
Which run facts an expression can read
An expression dependency is evaluated before the job is matched to a machine, so the job's own facts read slightly differently here than they do in a job parameter at dispatch:
| Token | At the gate |
|---|---|
JI.$MACHINE NAME | Always available. The agent the job is assigned to when it names one agent and has no backup agents; otherwise Undetermined until dispatch picks a machine |
JI.$ACTUAL RUN TIME | Empty — the job has not run |
JI.$MASTER JOB NAME | The job's base definition name, so a job expanded into instances reads the name it was expanded from. It is the stored name and does not follow a later rename |
JI.$EST RUN TIME | The Estimated Run Time (in min) set on the job for the frequency it was built from, carried onto every built job and every job a $JOB:ADD event adds. Available only when that value is set. Resolves to HH:mm:ss text, never a number of minutes |
OI.$OPCONVER | Not available at the gate — a tenant property of the same name is read instead |
$EST RUN TIME needs an estimate on the jobAn expression that reads JI.$EST RUN TIME resolves only when the job carries an estimated run
time: set Estimated Run Time (in min) on the job's frequency, or on the job instance. A job
instance built by an earlier release has none until it is rebuilt or its estimate is edited. With
no estimate, the token cannot be resolved and holds the job.
$EST RUN TIME and $MAX RUN TIME are text, not a number of minutesBoth tokens reach the expression as quoted HH:mm:ss text, so a numeric comparison against them
is a type error and holds the job: [[JI.$EST RUN TIME]] > 10 fails with 'Greater Than'
operator can only be applied to numeric and string types. Compare them as text instead:
[[JI.$EST RUN TIME]] > "00:10:00".
Two more things follow from the values being text:
- Zero is not
00:00:00. An estimate or limit of0renders00:01:00. - Past 100 hours, text order stops matching time order.
"100:00:00"sorts before"20:00:00", because the values are compared as text, not as durations. Only durations that long are affected, but against one of those a>is no longer comparing elapsed time.
Where these tokens are offered from a property picker, the picker now spells the format out on the row. The Expression field itself is free text and has no picker, so write the quoted form by hand.
A job marked to be skipped still resolves its expression
A deferred skip (Job to Be Skipped) resolves its expression on the same gate rather than bypassing it, so a skip lands in the same order relative to the expression as a run would have. An expression that cannot be evaluated there does not put the job on hold — the skip you asked for is preserved, and the job stays marked.
Across Workflows and Instances
A predecessor that fanned out into several instances
A wait-on-all dependency on a multi-instance predecessor is stored as one record per matched instance. In the Processes job instance editor those are shown as a single dependency card, named for the underlying job, rather than one card per instance — so a dependency on a job that expanded into three instances reads as one dependency, which is what it is.
Editing or deleting that card applies the change across every underlying instance when you save.
Cards are only combined when the underlying records agree on their Condition and Type. If they diverge — different conditions against different instances of the same predecessor — they stay as separate cards, because collapsing them would hide a real difference.
A dependency between multi-instance jobs
A multi-instance job runs once per property group,
and its instances are named for their groups — Load.EU, Load.US. A same-workflow dependency on
such a job is matched by group:
| The dependent | Waits on |
|---|---|
An instance whose group the predecessor also has — Report.EU on Load | The predecessor's instance of that group: Load.EU |
An instance whose group the predecessor does not have — Report.APAC on Load | Every instance of the predecessor |
| A job that is not multi-instance | Every instance of the predecessor |
| Any job, on a predecessor that is not multi-instance | The predecessor's single instance |
Earlier builds marked a group the predecessor does not have as unresolved, and that job waited indefinitely whatever its Type.
When a job is added to a running instance, a dependent still waiting on it can be left waiting
for a group that has not been added yet. If Report.EU is waiting on Load and only Load.US is
added, Report.EU keeps waiting, regardless of Type, until Load.EU is added too — waiting on
Load.US instead would run it out of order. Its dependency card says so: "This predecessor has an instance with this job’s
instance name, but that instance is not in this workflow instance yet. This dependency waits
regardless of Type until an operator adds that instance of the predecessor." Add that instance to
release it.
When the workflow builds as several schedule instances
A workflow with Allow Multi-Instance on builds once per named schedule instance for a date. Dependencies and conflicts resolve within one instance, because instances are independent runs over different property values:
| Reference | Resolves to |
|---|---|
| Same workflow, same date | This job's own instance. BRANCH1's job is not held by BRANCH2's. |
| Same workflow, a day offset | The same instance name on that date — every run of it. |
| Same workflow, conflict marked for every date | Only this instance's dated runs. A singleton job stays a singleton per branch. |
| Another workflow, with an instance named on the dependency | That instance, and every run of it. |
| Another workflow, no instance named | The predecessor's first instance — the lowest name, computed over the instances that workflow defines — and its first run. |
| Another workflow, conflict, no instance named | Every instance built for that date. |
A date built before the workflow turned multi-instance. A reference that resolves to a named
instance on another date — the same workflow's day offset, or another workflow with an instance
named — finds no such instance on a date the workflow ran as a single, unnamed run. It then resolves
to that unnamed run, so BRANCH1's job today can depend on yesterday's run from before Allow
Multi-Instance was turned on. Earlier builds found nothing there, and the job waited indefinitely
under both Requires and After. A sibling instance is never used in its place.
A schedule instance can hold several runs for one date — see Repeat builds of one instance. Wherever a reference names an instance, it means the instance, not one run of it: a conflict sees every run, so live work on a later run is not overlooked and reported satisfied. A plain dependency that names no instance resolves to the first instance's first run, which is the run the workflow's own schedule produced.
Two consequences are worth planning around:
- A cross-workflow dependency with no instance named is not "whichever built first". The first instance is computed from the workflow's definition, not from the rows that exist at the moment the dependency is evaluated — so a fan-out part-way through cannot settle a dependent on the wrong branch. That matters because dependency resolution is sticky once settled.
- To make two branches contend, ask for it. Same-workflow conflicts are per-instance. Use a Resource dependency or a cross-workflow conflict when branches genuinely share something — both of those span instances.
A cross-workflow conflict keeps spanning every instance when you edit the job. Editing a job on a running instance from Processes leaves its conflict covering every instance of the other workflow, even when the same job also carries a Requires or After dependency on that same predecessor, which the build can pin to one instance. Switching a dependency's Type to Conflict in the job instance editor drops that pinned instance too, for the same reason. A conflict that an earlier edit already narrowed to one instance keeps it until the workflow instance is rebuilt.
Seeing a predecessor from outside the instance
A predecessor outside the waiting job's own workflow instance — in another workflow, or in this workflow on a different day — is drawn on the Processes page's workflow diagram as a dimmed stand-in card rather than being left off the canvas. It shows the workflow name, the job name, the schedule instance where one is named, and the Days Offset; it carries no status, because nothing on that canvas resolves it. See Predecessors outside this run.
An any-day conflict's stand-in is worth reading carefully: its arrow reports blocked whenever a match is live on any date, including dates the canvas is not showing. Over-reporting a block is the deliberate direction there.
A cross-workflow predecessor on the Design canvas
The Design module's workflow canvas draws the same idea for the job being authored. A dependency on a job in another workflow gets its own card — the job name on the first line, the workflow it lives in on the second — with an edge into the job that depends on it.
| Behaviour | Detail |
|---|---|
| One card per external job | Every dependency naming the same workflow.job pair shares one card; each dependency still draws its own edge. |
| Edge style follows the dependency | A Requires or After dependency draws the ordinary ordering edge, result colour and day-offset label included. A Conflict draws the conflict edge. |
| A prefix conflict is its own card | A conflict that names a job-name prefix rather than a job shows the prefix with a trailing *, and is a separate card from a real job of that name. |
| Display-only | There is no ⋮ menu and nothing to delete: the dependency is edited on the job editor's Dependencies tab. |
| Show or hide them | The Card Filters section has an External Jobs switch, beside Frequencies, Thresholds, Resources and Expressions. See The workflow editor tool panel. |
Selecting the card opens that workflow in a new tab. The whole card is the target — it takes keyboard focus, and Enter or Space opens it too. A double-selection opens one tab, not two.
The card carries only the workflow's name, so that is what is resolved. If it cannot be, a message says which case it was: the dependency no longer names a workflow, the workflow was not found, too many workflows have similar names (open it from the workflows list instead), or the browser blocked the tab.
A dependency on one of this workflow's own jobs is drawn as an ordinary edge, not one of these cards, even after the workflow is renamed and before it is saved: the canvas recognises it by the workflow's identity. See Renaming a workflow while you edit it.
Dragging across the card still pans the canvas, so a selection that drifts more than a few pixels is read as a drag and does not open anything.
A dependency on a workflow you cannot view
Workflows belong to workspaces, and a workflow save respects that for cross-workflow dependencies the same way it does for threshold and resource dependencies: only what the save adds or changes is checked against the predecessor workflow's workspace.
| What your save does | When you cannot view the predecessor's workflow |
|---|---|
| Adds a dependency on a job in it | Refused as though it did not exist: Workflow 'Core Close' not found, or you do not have permission to view it. The answer is the same whether or not a workflow of that name exists, and the same when the saved workflow already uses that workflow — through another dependency or a container job. |
| Changes a dependency the workflow already has on it — its predecessor job or workflow, Type, Condition, Days Offset or Frequency | Refused with the same message: Workflow 'Core Close' not found, or you do not have permission to view it. |
| Removes a dependency the workflow already has on it | Allowed. |
| Leaves that dependency as it is | Not checked. The save goes through. |
Moving a dependency to another job of the same workflow is not a change. So you can always edit the rest of a workflow you can view, even when it depends on a workflow you cannot see. Copy Workflow keeps the original's cross-workflow dependencies on the same terms: one carried over unchanged is not checked.
Identity and Renames
A dependency records the predecessor's identity
A job dependency stores two things about the job it names: that job's persistent id and its name. The id is the primary key of the pair, and it is what lets a dependency survive a rename of the job it points at.
The editor fills both in for you, and the rules that follow only matter when you edit a configuration by hand or through the API.
How the pair is resolved when a workflow is saved:
- The id wins when it resolves to exactly one job. The name beside it is then refreshed from that job — so editing the name alone does not re-point the dependency. To aim a dependency at a different job, clear the id in the same edit, or just re-pick the predecessor in the editor.
- An id that resolves to nothing falls through to the name, and the name's own job then supplies a fresh id. A dangling id is repaired rather than trusted.
- An ambiguous id or name is declined. If two jobs somehow answer to the same id, or two share the name, the reference is left name-only and picks up an id on a later save, once the ambiguity is gone.
- A prefix reference never gets an id. A conflict authored against a name prefix matches a set of jobs whose membership changes as jobs are added and renamed, so there is no single identity to point at. Those references stay name-based permanently — see Authoring a conflict.
What that means for a rename. The dependent workflow's copy of the predecessor's name is brought up to date the next time that dependent workflow is saved. Until then the stored configuration — and therefore any version built from it — still carries the old name. So after renaming a job that other workflows depend on, save those workflows and create new versions of them.
Errors a hand-edited dependency can now hit at save time:
| Message | Meaning |
|---|---|
| Job 'X' not found in current workflow | A same-workflow dependency names a job this workflow doesn't have. |
| Job 'X' not found in workflow 'Y' | A cross-workflow dependency names the workflow by name, and that workflow has no such job. |
| Workflow 'X' not found, or you do not have permission to view it. | A cross-workflow dependency names a workflow that does not exist, or one in a workspace you cannot view — including a change to a dependency the workflow already has on a workflow you cannot view. See A dependency on a workflow you cannot view. |
| A workflow reference that resolves to neither an id nor a name | The save fails. The workflow a dependency names is the dependency — a reference to a workflow that cannot be found is never stored. |
| Resolving this workflow's references rewrote a dependency to point at a renamed job or schedule… | Refreshing the stale names produced a duplicate dependency, or a dependency on the job's own self. Fix the named dependencies and save again. |
| Dependency names workflow 'X' but its id points at workflow 'Y' | The dependency carries this workflow's name but is linked to a different, existing workflow, so it could mean either. Re-pick the predecessor's workflow — see Renaming a workflow while you edit it. |
One deliberate exception: a cross-workflow dependency whose workflow id resolves but whose job is missing does not fail the save. That is exactly the reference a renamed predecessor strands, and refusing it would block the save that repairs it. It still fails at build.
A copy of a workflow drops the ids of dependencies pointing at the copied workflow's own jobs — those get fresh identities — and keeps the ids of dependencies pointing into other workflows, whose jobs are untouched. An import drops both, because a bundle's ids belong to the system it came from; the names carry over and the ids repopulate on the first save.
A deployment transformation rule may not change a dependency's job id, though the name beside it stays transformable — see Fields no rule may change.
A cross-workflow dependency survives a rename of the workflow it names
A cross-workflow dependency is now resolved at run time by the referenced workflow's identity, not by its name. Both kinds are covered: an ordering dependency (Requires or After) and a conflict. Renaming the workflow you depend on no longer breaks the dependency, and another workflow taking the old name no longer steals it.
That matters because the two failure modes were quiet and opposite:
| Situation | Before | Now |
|---|---|---|
| A conflict whose target was renamed | The target read as absent, so the conflict counted as satisfied — the two jobs ran together, which is the one thing the conflict existed to prevent | The conflict still finds its target and still holds |
| An ordering dependency whose target was renamed | The predecessor read as missing, so the dependent waited indefinitely | It resolves and the dependent runs |
| Another workflow taking the old name | The dependency silently retargeted onto the newcomer | It stays on the workflow it was authored against |
A conflict whose target genuinely has no resident instance is still satisfied — no instance means none of its work is running, which is the correct answer.
The identity is copied from the deployed configuration when a workflow instance is built, so what you have today is not repaired in place:
- Instances built before this release carry no identity and resolve by name, exactly as before, for the rest of their lives.
- A stored reference that has no workflow identity stays name-only until the dependent workflow is saved again — saving stamps it — and a version built from that save.
- A Pinned deployment builds from a fixed older version. If that version's reference already carries the identity, its next build picks it up; if it does not, it stays name-only for as long as the pin stands. Re-pinning to a newer version, or switching to Latest, clears that. See Versions and deployments.
For a name-only reference, a rename of the target still produces the old behaviour in the table above. If you are about to rename a workflow others depend on, save and rebuild the dependents first.
The editor shows the predecessor workflow's current name, and its job's. When you open a workflow, each dependency on a job in another workflow that carries that workflow's identity is shown under the name the workflow has now, so the job editor's Job Name list offers its jobs straight after a rename. When the dependency also carries the predecessor job's identity, and exactly one job in that workflow has it, the job is shown under its current name too. A conflict on a job name prefix keeps the prefix you wrote. The stored copies of both names are brought up to date the next time the dependent workflow is saved. Earlier builds showed the old workflow name until that save, and the Job Name list said the workflow was not found; a renamed predecessor job kept its old name until that save.
The Job Name list finds the predecessor workflow by its exact name. When no workflow has that name, the list says Workflow "…" not found rather than showing nothing. Earlier builds looked the name up by partial match among a limited number of results, so a workflow whose name is part of many other workflows' names could be missed, and its Job Name list looked as if the workflow had no jobs.
A lookup that fails says so. When the Job Name list cannot load the predecessor workflow's jobs, it reads Could not load jobs. Try again., and the field shows the same message as an error, so it is visible even when the job name already saved keeps the list from being empty. Earlier builds said No options, as if the workflow had no matching jobs. Creating, copying, saving, renaming or deleting a workflow refreshes these lookups, so a workflow you have just created is found at once. Earlier builds could keep saying it was not found for up to five minutes.
A dependency scoped to the workflow's own jobs is stamped when the workflow is created, too. A brand-new workflow containing a conflict between two of its own jobs used to be stored with the workflow's name and no identity — so after you renamed that workflow, the next save was refused for naming a workflow that no longer existed, and the workflow could not be saved at all until every such reference was re-picked by hand. Creation now stamps the identity the same way a save does, and an import goes down the same path, so it is covered as well.
Three less common rename cases
Because a reference is resolved by identity, a rename keeps working in these three cases too:
| What you do | What happens |
|---|---|
| Rename a workflow and, before saving it again, rely on a conflict or an ordering dependency between two of its own jobs, in a multi-instance workflow | A reference carrying this workflow's own identity is resolved as its own, under the old name or the new one, so same-workflow scoping still applies |
| Put both a Requires and a Conflict on the same job in another workflow | Both are stored independently, and later edits of that job instance on the Processes page go through |
| Rename a workflow, then give its old name to a new multi-instance workflow | A same-day dependency on the renamed workflow is matched by identity, so the new workflow taking the old name does not affect it |
A name-only reference, one built before identity stamping or on a Pinned deployment that predates it, does not take the identity path at all.
Renaming a workflow while you edit it
A dependency between two of a workflow's own jobs is recognised as its own by the workflow's identity as well as its name — in the workflow editor, in the job editor, when the workflow is saved, and at run time. So a rename, saved or not, no longer turns those dependencies into something else:
- On the Design canvas they stay drawn inside the workflow. Rename the workflow — a saved one with Rename in the Workflow Settings panel, a new one by typing its Workflow Name — and keep editing: the edges between its jobs are still edges. Undo does not duplicate them, deleting a job removes the dependencies on it, and a dependency you draw after the rename points at this workflow. Every new dependency on a job in this workflow records the workflow's identity beside its name.
- A new workflow can be renamed before its first save. Its own dependencies stay its own, and are saved under the name the workflow is created with. A dependency on another workflow is never mistaken for one of its own because the names happen to line up.
- A dependency on the workflow's own earlier runs still sees them. A job that depends on its own workflow's previous day (a Days Offset), or a conflict on its own workflow across every scheduled date, finds the runs that were built before the rename, under the old name.
- The stored name is refreshed on save. A dependency carrying this workflow's identity is this workflow's, whatever name it still holds — even a name another workflow has since taken — and saving brings that name up to date.
- The job editor judges it the same way. The Workflow picker shows such a dependency as this workflow, labelled (current), and a job set to depend on itself on the same day is blocked at save even when the dependency still carries the old name.
One combination is refused, because it could mean two different things: a dependency that names this workflow but is linked to another workflow that exists. The job editor's dependency card says This dependency names the current workflow but is linked to workflow 'Y'. Pick the workflow again., the workflow editor will not commit, and a save through the API fails with Dependency names workflow 'X' but its id points at workflow 'Y'. Re-pick the workflow on the dependency to clear it. If the linked workflow has been deleted, there is nothing to confuse it with: the dependency is treated as this workflow's, and its link is repaired on save. If the linked workflow is in a workspace you cannot view and the saved workflow already held that dependency, a save leaves it exactly as it is. Earlier builds re-pointed it at this workflow, so it could quietly change which workflow it was linked to, or fail the save with a job not found.
The workflow editor also refuses to commit a dependency on a job that is not in this workflow: Job 'A' depends on job 'B', which is not in this workflow. Point the dependency at a job the workflow has, or remove it.
Troubleshooting
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Job sits waiting and never runs | A dependency isn't satisfied — identify which one | Check each dependency: predecessor result, threshold value, resource availability, expression (Operator → Builder if the dependency is mis-set). |
| A job with an expression dependency is On Hold, with a reason naming the expression | The expression could not be evaluated, or it rendered something that is neither True nor False | Fix the expression on the job and release the job. See What each outcome does to the job. |
| A job with an expression dependency is held, and the reason names an estimated run time | The expression reads JI.$EST RUN TIME, and this job instance carries no estimate (none is set on the job's frequency, or the instance was built by an earlier release) | Set Estimated Run Time (in min) on the job's frequency and rebuild, or set Estimated Run Time on the job instance (Builder). |
| A job with an expression dependency is held, and the reason says an operator can only be applied to numeric and string types | The expression compares JI.$EST RUN TIME or JI.$MAX RUN TIME against a number; both resolve to HH:mm:ss text | Quote the bound as text — > "00:10:00" rather than > 10 (Builder). |
| A workflow save, or a held job's reason, says Encrypted property OI.… cannot be used in an expression dependency | The expression reads a global property marked Encrypted, which an expression dependency may not use | Gate the job on a property that is not encrypted, or on something else, then save — and release a held job (Builder). |
| A job with an expression dependency waits with no reason recorded | The expression is rendering False — the gate is simply not open yet | Expected. Check what the expression reads; a held job would have named a cause instead (Operator). |
| Job waits on a predecessor that already finished OK | The dependency expects Failed or a different Condition/day offset | Confirm the Condition and Days Offset match intent (Builder). |
| Job waits even though the predecessor isn't scheduled today | The dependency is Requires, which waits when the predecessor is absent | Switch the Type to After if the predecessor is optional; leave it Requires if it must run (Builder). |
| Job waits regardless of Type, with a warning on the predecessor | The predecessor has an instance with this job's instance name, but that instance has not been added to the workflow instance yet | Add that instance of the predecessor to the run (Operator). See A dependency between multi-instance jobs. |
| A job in one branch waits on a predecessor that ran in another branch | The reference names no instance, so it resolved to the predecessor workflow's first defined instance | Name the instance on the dependency, or keep the branches in the same workflow so same-workflow scoping applies (Builder). |
| Job waits only while another named job is running, then proceeds | A Conflict dependency is holding it — by design, to stop the two overlapping | Expected. If the two should be allowed to overlap, remove the conflict (Builder). |
| Job never gets a resource | Not enough of the named resource is available; another job holds it | Check resource counts and which jobs hold it (Builder / Operator). |
| Job runs earlier/later than expected relative to another | Missing or extra job dependency | Review the dependency wiring (Builder). |
| A workflow save is refused with Workflow 'X' not found, or you do not have permission to view it. for a workflow that exists | Your save adds or changes a cross-workflow dependency on a workflow in a workspace your role cannot view | Leave that dependency as it is, or remove it, or ask an administrator for View on workflows in its workspace (Builder / Administrator). See A dependency on a workflow you cannot view. |
Contact support when
- All dependencies are demonstrably satisfied but the job still does not become eligible.
Include the workflow instance, the job, and the state of each of the job's dependencies.