Schedule instances

Task walkthrough: Schedule a workflow. 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.

caution

Not the same thing as a multi-instance job

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

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 offers Default rather 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 instances is not a multi-instance-only field: in single-instance mode it holds the workflow's own properties in that one implicit Default instance.

Turning it off does not un-build what is already built

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 below, 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 and tags.

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".

The editor shows both as a blank field

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.

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.

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 below.

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 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.

What this does and doesn't change

A single-instance workflow, and a plain named build with no overrides, are unaffected: both sides of the comparison carry the same properties, so the match always succeeds and you get the old conflict behaviour. Repeats only appear once a build supplies property values that differ — 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 — the setting is what says repeats are wanted.
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.

note

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 Multiple Instances 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:

Outcome	Meaning
BUILT	The instance was built.
SKIPPED	Not built, with a reason — ALREADY_EXISTS, NOT_OVERWRITABLE (the slot is taken and busy), IDENTITY_CONFLICT, or BUILD_REJECTED (bad input you can act on).
FAILED	BUILD_FAILED — an internal fault.

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	—	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. A job in a multi-instance workflow 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 Name column shows the composed name, and a separate Instance Name filter narrows the grid.
Processes → Jobs grid	The workflow column shows the composed name.
Job detail	The workflow shown on the summary is the composed name, and following it back to the workflow list narrows that list to the instance you came from.
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 Name orders by the bare workflow name, so an instance's siblings sort as peers rather than being separated by their instance names.

The Instance Name filter on the Workflows grid is a partial, case-insensitive match, matching the Workflow Name filter beside it — typing BRANCH matches BRANCH1 and BRANCH2. It excludes single-instance runs entirely: those have no instance name, and "instance name matches X" has no answer that includes them. Both the filter and the composed name are saved and restored with a filter preset.

note

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 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.
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.
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 to BRANCH2 purely 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: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. 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.

caution

$JOB:TAGADD and $JOB:TAGDEL cannot name an instance

Both 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: against a workflow with 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

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	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 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).
The Workflows grid shows nothing after clearing filters	An Instance Name filter was left applied — it matches nothing against single-instance runs	Clear the Instance Name filter (Operator).
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.