Schedule instances
- Synopsis
- Full Details
In briefA schedule instance lets one workflow build more than once for the same date, once per
named instance, each with its own property values. One PAYROLL definition runs as
PAYROLL_BRANCH1 and PAYROLL_BRANCH2 side by side, and each instance has its own build numbers.
WhereInstances are defined in the workflow editor's Workflow Settings panel: turn on
Allow Multi-Instance on the Overview tab, then add them on the Instance Properties tab
with Add New Instance. A build names one in Processes › Schedule Workflow, in the
Schedule Instance picker. A built instance appears as Workflow_Instance in the Processes
grids.
When
- The same sequence of jobs runs for several branches, regions or entities, over different data.
- You want one definition to maintain instead of a copy of the workflow per branch.
- You need to build one branch on its own, or rebuild it, without touching the others.
If you need one job to fan out inside a single run, use a multi-instance job instead; that is a different mechanism, named with a dot rather than an underscore.
How
- Turn on Allow Multi-Instance and add each instance, with a name and its properties, on Instance Properties.
- Read the values in job commands with the
SIscope, such as[[SI.BRANCH_CODE]]. - Commit and deploy, then build from Processes › Schedule Workflow, choosing All instances or one by name.
The full steps are on Workflow Settings.
- Instance names are case-sensitive, unique within the workflow, 40 characters or less, and follow
the workflow-name character rules.
(unnamed)is reserved. - Property names within one instance must differ by more than case; Create Version is blocked
until a pair such as
Regionandregionis renamed. - A dependency or conflict inside one workflow resolves within the same instance.
- An event that acts on a built schedule takes an optional, last Named Instance field.
- An encrypted instance property is not copied onto the run, so
[[SI.…]]cannot read it. - Changing Allow Multi-Instance after a date is built makes the next build of that date refuse
with
IDENTITY_CONFLICTunless you overwrite. - An event against a date with several instances built, or a job that exists in several, is refused unless it names the instance.
Task walkthrough: Workflow Settings. This page is the full configuration and troubleshooting reference.
A schedule instance lets one workflow definition build more than once for the same schedule
date, once per named instance, with each instance carrying its own property values. One PAYROLL
workflow becomes PAYROLL_BRANCH1 and PAYROLL_BRANCH2 — two separate daily runs of the same
sequence of jobs, over different data.
That is the point of the feature: rather than copying a workflow once per branch, region or entity and maintaining the copies in step, you define the differences as instance properties and let one definition build once per instance.
The workflow setting is Allow Multi-Instance and the concept here is a schedule instance — a whole dated run of the workflow.
A multi-instance job is a different mechanism: one job inside a run that fans out into several
job instances, from a property group or an agent pool. Those are named with a dot
(EXTRACT.US). A schedule instance is named with an underscore (PAYROLL_BRANCH1). The two can
be in play at once, and they do not interact.
- Defining Instances
- Building
- How Instances Appear
- Dependencies and Events
- Troubleshooting
Defining Instances
Defining instances
Instances live on the workflow, on the Instance Properties tab of the Workflow Settings panel (called Workflow Set-up in earlier builds).
- Allow Multi-Instance off — the workflow has one implicit instance named
Default, and the tab is a flat list of that instance's properties. There is no instance name to edit and none is shown. - Allow Multi-Instance on — each instance is a group with an editable name, its own
property list, and a delete control. Add New Instance adds another. Instances and the
properties inside them are drag-reorderable. Turn the setting on and declare nothing, and the
workflow still has one implicit instance named
Default— it is buildable, and the build picker offersDefaultrather than an empty list.
Each property row is Name, Value, and an Encrypted toggle. Value may be left empty — that is how you say an optional setting is unset, and it is no longer rejected on save.
Instance name rules
A name is the instance's whole identity — there is no instance number — so the rules are enforced when the workflow is saved:
| Rule | Detail |
|---|---|
| Required | An instance in multi-instance mode must be named. |
| Unique within the workflow | A duplicate name makes the second definition unreachable, so it is rejected. |
| 40 characters or less | The same ceiling as a workflow name. |
No ' | ; % & < > ( ) [ ] { } , = ! \ " | The same blocklist as a workflow name. This is one of the naming exceptions — most objects have no such blocklist. |
(unnamed) is reserved | That is how an instance with no name is displayed, so an instance actually called (unnamed) could not be told apart from one. |
Names are matched exactly, including case, everywhere: BRANCH1 and branch1 are two legal,
distinct instances. This is deliberate and it is consistent end to end — the workflow name is
matched case-insensitively, the instance name is not.
Names are workflow-local. The same instance name in two different workflows denotes two unrelated instances.
Turning the setting back off
You cannot clear Allow Multi-Instance while more than one instance is defined — the save is rejected and names the count. Remove all but one in the same save, which is what the editor does when you toggle it off.
The threshold is "more than one", not "any", because the instance list is not a multi-instance-only
setting: in single-instance mode it holds the workflow's own properties in that one implicit
Default instance.
Turning the setting off after BRANCH1…BRANCH5 are built for a date leaves five schedules built
and running. The next build for that date then targets the unnamed slot instead — see
Building the other identity on the Building tab, which refuses rather than
quietly creating a sixth run.
Instance properties
An instance's properties are materialized onto the built run, and are read with the SI (schedule
instance) scope — [[SI.BRANCH_CODE]]. See
Properties.
InstanceName is supplied for you. Every build stamps a property called InstanceName carrying
the instance's name, so [[SI.InstanceName]] always resolves. A single-instance build gets
Default. It is written last, so a property you define called InstanceName cannot shadow it.
An Encrypted property's value is not copied onto the run. The built run's property set is
stored in the clear, so a property flagged encrypted is omitted by name rather than copied. It
cannot be supplied as a build-time override either — the override is dropped by the same name rule,
so it cannot be used to smuggle a value past the exclusion. The name match folds case, so ApiKey
and apikey are one property for this purpose.
An empty value and no value are different things here. An empty value is a real value: it is carried onto the run and resolves to the empty string. A property whose value was never set carries no value, and the build skips it rather than passing it on — so it is the way to express "this instance defines no such property".
A never-set value and a deliberately empty one look identical in the property row. So typing into a never-set property and then clearing the field again does not restore it — it now carries an empty value, which the build propagates where it previously skipped the property altogether. That matters most for a container job's child workflow, which receives what the parent passes on. If a child starts behaving as though a property exists with no value, look here.
A job's own instance properties do not work this way, so don't carry the rule across: there, a value that was never set is copied onto the job instance as it stands and also resolves to the empty string. Skipping is specific to a schedule-instance property.
The runtime job detail's instance-properties panel renders a deliberately empty value as (empty) rather than as "no value", so the two can be told apart after the fact.
Property names that differ only in case
Within one instance, two property names may not differ only in capitalisation or in trailing
spaces. The build reads Region, region and Region as one property, and the later one silently
replaces the earlier, so the tab holds them to the same rule as a job's properties. Leading spaces
still count: Region is a different name.
- The property row says so as you type — Same name as 'Region' (case is ignored), or Duplicate name for an exact repeat.
- Create Version is blocked until one is renamed. The message names where the pair is and both properties: Instance 'BRANCH1' properties: Property 'region' has the same name as 'Region' when case is ignored. Property names must be unique, ignoring case. With Allow Multi-Instance off it begins Instance properties:.
- The save itself refuses the pair, so it cannot arrive another way either — through the API, or in an automation import. The message names the property and, with Allow Multi-Instance on, the instance: Schedule instance property 'region' in instance 'BRANCH1' has the same name as 'Region' when case is ignored. Property names must be unique within an instance, ignoring case; rename or remove one.
- A workflow that already holds such a pair can still be versioned. Only an instance whose property names you changed since the saved version is checked, so an unrelated change, or a change to a value, is not blocked. Its build keeps the last value, as before.
- A trailing space no longer hides a property from its token. The build stores each name
without its trailing spaces, so
[[SI.Region]]reads a property defined asRegion.
See Property names that differ only in case are refused for the same rule on a job's properties.
Building
Building
Processes → Schedule Workflow. When the selected workflow allows multiple instances, a Schedule Instance picker appears:
| Choice | What builds |
|---|---|
| All instances (N: …) — the default | One build per defined instance, in the order they are authored. The option names them. |
| A named instance | That one instance only. |
An instance with no name is not offered in the picker.
Choosing a named instance also opens a property editor for it, pre-filled from its definition,
so you can override values for this build. Encrypted rows are shown read-only with the value masked,
and the InstanceName row is read-only.
There is no property editor when All instances is selected, by design: one set of overrides
applied to every instance would flatten exactly the difference the instances exist to express. A
build that tries it is refused, unless the workflow declares an instance named Default: a build
that supplies overrides and no instance name is then a single build of Default.
Build numbers are per instance
Build number and instance name are separate axes. Build number counts rebuilds of the same
thing; the instance name distinguishes different things. So BRANCH2 does not land at build number
2 and read as "PAYROLL was rebuilt" — each instance has its own build 1.
One consequence matters for events: when several instances are built for one date, their build numbers are not comparable and there is no "newest" across them. Anything acting on a built schedule therefore has to say which instance it means — see Events on the Dependencies and Events tab.
Building one instance more than once for a date
One schedule instance can be built more than once for the same date — a second run of BRANCH1
carrying different property values, beside the first. That gives a dated run three independent
axes, and telling them apart is the whole trick:
| Axis | Answers | Changes when |
|---|---|---|
| Instance name | Which instance — BRANCH1 or BRANCH2 | You build a different instance. |
| Run | Which run of that instance for the date | A build carries instance properties that no existing run of the name carries. |
| Build number | Which rebuild of that one run | You overwrite or force-rebuild a run. |
The instance properties decide which of the two you get. When a build targets an instance:
- If its merged property set — the definition's values with your overrides applied — matches an
existing run of that name, the build is that run. Everything behaves exactly as it did before
repeats existed: without Overwrite Existing you get
ALREADY_EXISTS, and with it that run is replaced in place at the same build number. - If the set matches no existing run, the build is a different instance in all but name, and it gets the next run rather than a conflict. The exception is a build with Overwrite Existing (or a force-rebuild) when the instance holds exactly one run: that build replaces the one run whatever its properties.
The comparison is on the whole set. Names are matched case-insensitively; values are compared
exactly, trailing spaces included, because a value reaches a job's command line as typed. The
synthetic InstanceName property is excluded, since it is derived from the target rather than
supplied.
A single-instance build and a plain named build, each with no overrides, are unaffected: both sides of the comparison carry the same properties, so the match succeeds and you get the old conflict behaviour. Repeats only appear once a build carries property values that differ from every existing run — through overrides, or after a redeploy changes a value — with one exception, below.
The exception: multi-instance on with nothing declared
A workflow with Allow Multi-Instance on that declares no instances builds as the implicit
Default instance, and it is repeatable on every build. There are no instance properties to
compare, so no build ever matches an existing run, and each one adds a run beside the last.
That is deliberate, and it is the line between the two cases:
| The workflow | A second build for the same date |
|---|---|
| Allow Multi-Instance off | Refused as already built, unless the build carries instance property values that differ from every existing run — then it is a new run. |
| Allow Multi-Instance on, no instances declared | A new run. The second reads PAYROLL_Default$0002. |
| Allow Multi-Instance on, instances declared | Matched on properties as described above. A re-fired fan-out over BRANCH1/BRANCH2 still skips what already exists rather than duplicating it. |
Earlier builds refused the second build of the middle row outright — "Nothing was built — 1 already exists. Tick Overwrite Existing to replace it." — so such a workflow could not be run twice for one date at all.
The implicit instance is stored under the name Default, so its repeat reads PAYROLL_Default$0002
rather than PAYROLL$0002. A workflow that explicitly declares one instance named Default with
no properties is a named instance and still refuses a repeat, even though nothing on screen
distinguishes the two.
An automatic (unattended) build is deliberately kept off this path: it always resolves to a run the sweep already produced rather than adding one, so a redeployed property value cannot make a nightly pass re-run a date it has already built. See Scheduling and the run.
Overwrite
Overwrite Existing deletes exactly what the build targets, and the confirmation says which:
| Building | Overwrite deletes |
|---|---|
| A named instance | The one run this build replaces in that instance, and all its jobs. |
| All instances | The one run this build replaces in each instance, and all of their jobs. |
| A single-instance workflow | The run this build replaces, and all its jobs. |
Job output files are hard-deleted and do not come back.
Where an instance holds more than one run for the date, an overwrite or force-rebuild replaces
only the run whose property set matches this build. If none of them matches, the build is
refused rather than guessing which run you meant — the message lists the existing runs and their
build numbers. Delete the runs you don't want and build again, or build without overwrite to add
a new run beside them. An API caller that already knows the run can name it directly with
instanceOccurrence; that field is rejected on a fan-out, where there is no single run for it to
identify.
Building the other identity
A build sits on one side of a two-valued identity axis: named, or unnamed (the
single-instance run). A request refuses when the date is already built on the other side, and
reports IDENTITY_CONFLICT rather than a generic "already exists".
This is an ordinary sequence, not an exotic one: build BRANCH1/BRANCH2 today, turn Allow
Multi-Instance off, rebuild. Without the refusal the rebuild would probe the unnamed slot,
find nothing, and create a third schedule while both branches were still built and still
running — every job in the workflow running twice. Enabling the setting over an existing unnamed
run is the same problem mirrored.
Under Overwrite Existing the conflicting rows on the other side are cleared instead, and the response names what was destroyed.
What each instance reports
A build reports one outcome per instance, so a fan-out tells you what happened to each. The Schedule Workflow dialog lists every instance that was not built, each with its message:
| Outcome | Meaning |
|---|---|
| Built | The instance was built. |
| Skipped | Not built because it already exists. |
| Failed | Not built, with a reason: the slot is taken and busy, an identity conflict, bad input you can act on, or an internal fault. |
Through the API these outcomes are BUILT, SKIPPED and FAILED, and the reasons are
ALREADY_EXISTS, NOT_OVERWRITABLE, IDENTITY_CONFLICT, BUILD_REJECTED and BUILD_FAILED.
In a fan-out an instance that already exists is skipped and the batch continues; it does not abort the remaining instances.
Limits
| Limit | Default | Notes |
|---|---|---|
| Instances per build request | 50 | A blank-name build is one sequential build per instance inside one request, so this bounds how long that request takes. Build one at a time by name to exceed it. |
| Live runs per instance, per date | 100 | Bounds repeat builds of one instance. The message names the instance, because the cap is per instance rather than per workflow. It counts live runs, so deleting one makes room. |
| Total jobs across the request | 5,000 | Counted as jobs per instance × instances targeted. At the defaults, a workflow over 100 jobs cannot reach the 50-instance cap. |
| Projected job name | 255 characters | The name a job is actually stored under. See below. |
These are all checked before anything is written, so exceeding one costs nothing.
A projected job name over 255 characters is refused, and the refusal names the job. Each
instance of a multi-instance job is stored as <job>.<instance>, and a
run-on-all job as <job>__<member> or
<job>.<instance>__<member> — so the stored name can be much longer than anything you typed, and the
instance and agent-group member names that lengthen it have no 255-character ceiling of their own.
The build now checks every shape it is about to write and refuses with the job and the instance
named, for example Job name "JobA.GGG…" projected by instance "GGG…" of multi-instance job "JobA" is
longer than 255 characters. Earlier builds got as far as the write and failed with a raw database
error, which told you nothing about which name was at fault. The same check applies when a job is
added to a running instance.
How Instances Appear
The composed name is Workflow_Instance — PAYROLL_BRANCH1. A single-instance run shows the bare
workflow name.
A repeat run adds a four-digit run suffix: the second run of BRANCH1 reads
PAYROLL_BRANCH1$0002. The first run of anything carries no suffix, so every name that exists
today is unchanged.
| Where | What you see |
|---|---|
| Processes → Workflows grid | The Workflow column shows the composed name. There is no separate Instance Name filter. |
| Processes → Jobs grid | The workflow column shows the composed name. |
| Job detail | The workflow shown on the summary is the composed name. Following it opens the workflow list filtered to that workflow and date, with the run you came from expanded. |
| Workflow details panel | An Instance Name row, shown only for a named instance. |
| Failed Jobs dashboard widget | The composed name. |
| Job History report | A dedicated Instance Name column and filter. |
Sorting the grid by Workflow orders by the bare workflow name, so an instance's siblings sort as peers rather than being separated by their instance names.
The Job History report's Workflow Name column holds the bare workflow name, not the composed form, because that column is also the report's filter — a composed value pasted back into it would match nothing. The instance is in its own column. In that report, filtering Instance Name with Is empty selects exactly the single-instance rows.
Dependencies and Events
Dependencies and conflicts
A dependency or conflict is resolved within one instance where the two jobs belong to the same workflow, and instances are treated as independent runs.
| Case | How it resolves |
|---|---|
| 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. On a date the workflow ran as a single, unnamed run — before Allow Multi-Instance was turned on — that run. |
| Same workflow, conflict marked for every date | Only this instance's dated runs. A singleton job stays a singleton per branch — BRANCH1 still refuses to start while yesterday's BRANCH1 runs, and no longer waits on yesterday's BRANCH2. |
| Another workflow, a named instance on the dependency | Exactly that instance, or, on a date that workflow ran as a single unnamed run, that run. A sibling instance is never used in its place. |
| Another workflow, no instance named | The predecessor's first instance — the lowest name, computed over the instances the workflow defines, not over whichever happen to be built at the time. |
| Another workflow, conflict, no instance named | Every built instance on that date. A conflict is mutual exclusion, so narrowing to one instance would let a running sibling go unseen. |
Two things worth drawing out:
- The first-instance rule reads the definition, not the built rows. During a fan-out only some
instances exist yet, and instances build in authored order rather than name order — so a workflow
authored
[BRANCH2, BRANCH1]would otherwise resolve a dependent toBRANCH2purely because it committed first. Dependency resolution is sticky once settled, so that would never correct itself. - A conflict across instances needs to be asked for. Same-workflow conflicts are per-instance. If two branches genuinely contend for one shared resource, use a resource dependency or a cross-workflow conflict — both of those span instances.
See Job dependencies.
Events
Every event verb that acts on an already-built schedule takes an optional trailing Named Instance field, because build numbers are not comparable across instances and there is no newest to fall back on.
It is always last and always optional: omitting it stays correct for a workflow that has one instance built for the date, which is every workflow that has not opted in, and every event already in flight keeps parsing unchanged.
Verbs that take it: $SCHEDULE:HOLD, $SCHEDULE:RELEASE, $SCHEDULE:START,
$SCHEDULE:CANCEL, $SCHEDULE:DELETE, and the job verbs $JOB:ADD, $JOB:ADDHLD,
$JOB:HOLD, $JOB:RELEASE, $JOB:START, $JOB:SKIP, $JOB:GOOD, $JOB:BAD, $JOB:FIXED,
$JOB:CANCEL, $JOB:KILL, $JOB:DELETE, $JOB:UNDERREVIEW,
$JOB:RESTART, $JOB:RESTARTHLD, $JOB:RESCHEDULE, $JOB:RESCHEDHLD, $JOB:MACHGRP,
$JOB:MAXRUNTIME, $JOB:PRIORITY, $JOB:USER.
$SCHEDULE:BUILD and $SCHEDULE:BUILDHLD already carried the field — on those it says which
instance to build, and leaving it blank on a multi-instance workflow fans out over every defined
instance, exactly as the dialog's All instances does. A blank-name build reports one state change
per instance actually built.
Pass (unnamed) to target the single-instance run explicitly — a blank field means "don't narrow",
not "the unnamed one".
When the target is ambiguous the event is refused, naming the instances that hold the job so the remedy is to pick one. A schedule event is ambiguous when more than one instance is built for the date; a job event is ambiguous when the job exists in more than one of them. It does not act on an arbitrary instance.
That protection extends one axis down. If the instance the event names has been built more than once for the date, the event is also refused, naming the runs that exist — because build numbers are allocated per run and are no more comparable across runs than across instances. The event grammar has no field for a run, so the remedy is to act on the run from Processes, or by instance id through the API.
$JOB:TAGADD and $JOB:TAGDEL cannot name an instanceBoth end in a tags field that absorbs everything after it — that is what lets a tag list contain commas — so the comma-delimited event grammar has nowhere to put another field. Appending one would make every multi-tag event unbuildable; inserting one before the tags would silently re-read the first tag as the instance name.
They are still protected rather than misdirected: when the job exists in more than one instance built for the date, a tag event is refused rather than applied to the wrong instance. Against a single built instance it works as it always has.
A refused or ambiguous event is visible in the Event log with the reason.
Troubleshooting
Troubleshooting
| Symptom | Likely cause | Resolution |
|---|---|---|
| Build refused: "not configured for multiple instances, so instanceName … cannot be applied" | A named build against a workflow with Allow Multi-Instance off | Turn the setting on, or build without naming an instance (Builder / Operator). |
| Build refused: "Unknown instance '…'" | The name does not match any defined instance — check the case | The message lists the defined instances; use one exactly as spelled (Operator). |
| Build refused: "has an instance with no name at position N" | A deployed config carries a blank instance name | Name every instance and redeploy. A blank name is refused rather than skipped, so the build cannot quietly produce fewer instances than the workflow defines (Builder). |
| Build refused: "already has N live runs for …, the per-instance cap of 100" | The instance is at its repeat-build cap for that date | Rebuild an existing run with Overwrite Existing, or delete one (Operator). |
| Build refused: "none of its N existing runs carries the instance properties being built" | An overwrite or force-rebuild against an instance holding several runs, none matching this build | Delete the runs you don't want, or build without overwrite to add a run beside them (Operator). |
| Build refused: "has no run N for …" | An API caller named an instanceOccurrence that doesn't exist | The message lists the runs that do (Operator). |
| Build refused: "instanceProperties has no single target" | Overrides supplied without naming an instance, on a workflow that does not declare an instance named Default | Name the instance the overrides apply to (Operator). |
| Build refused: exceeds "the per-request fan-out cap" | More instances defined than one request may build | Build instances individually by name, or have the cap raised (Operator → Administrator). |
Build refused with IDENTITY_CONFLICT | The date is already built on the other side of the named/unnamed axis, because Allow Multi-Instance changed after it was built | Delete the built runs for that date, or rebuild with Overwrite Existing (Operator). |
| Save rejected: "Cannot disable multiple instances while N instances are defined" | Clearing the setting with more than one instance still defined | Remove all but one in the same save (Builder). |
| Save rejected: "Duplicate instance name '…'" | Two instances share a name | Rename one. Names are case-sensitive, so BRANCH1 and branch1 are already distinct (Builder). |
| An event is refused as an ambiguous schedule instance | Several instances are built for the date (for a job event, the job exists in more than one) and the event named none | Add the Named Instance field, or (unnamed) for the single-instance run. $JOB:TAGADD/$JOB:TAGDEL cannot be narrowed at all (Builder). |
| An event is refused as an ambiguous schedule instance run | The named instance has been built more than once for the date | An event cannot name a run. Act on the run from Processes, or by instance id through the API (Operator). |
| A second build of one instance was refused as already existing, and you expected a new run | Its merged property set matches an existing run, so the build reads as a rebuild of that run | Change the instance property values this build carries, or overwrite the run deliberately (Operator). |
| Every job in the workflow ran twice for one date | Two runs exist on opposite sides of the named/unnamed axis, from a build that predates the identity check | Cancel the duplicate run and rebuild the date with Overwrite Existing (Operator). |
| A branch's job waits on another branch | A resource dependency or a cross-workflow conflict — both span instances by design | Expected. Use a same-workflow conflict if the hold should be per-branch (Builder). |
| An instance property has no value at run time | It is flagged Encrypted, so its value is deliberately not copied onto the run | Supply the value another way — encrypted instance properties cannot be read by [[SI.…]] (Builder). |
Contact support when
- Two runs of one workflow exist for the same date on opposite sides of the named/unnamed axis and neither can be deleted.
- A named build reports an instance as unknown that the Instance Properties tab plainly shows, with the case matching exactly.
Include the workflow, the schedule date, the instance name as spelled, and the build response's per-instance outcomes.