Skip to main content

Schedule a workflow

Two things decide when work happens: frequencies (which days and times a job is eligible) and build settings (how and when the workflow becomes a concrete day's run). Holiday calendars and working days remove days that shouldn't run.

What this solves

A workflow scheduled wrong (wrong days, no holiday handling, or built too early) either runs when it shouldn't or isn't ready when the business needs it.

Set when a job runs​

To set a job's schedule, complete the following steps:

  1. In the job editor, open the Frequencies tab.
  2. Add the frequency (or frequencies) the job should run on.
  3. Under Offset Information, set the job's timing for that frequency: the Start Offset, and the Late to Start and Late to Finish thresholds.
  4. Under Latest Offset, set the Latest Start Offset — the point past which the job should no longer start at all. Leave it at 00:00 to have no deadline; that value means not configured rather than midnight.
  5. Under Run Time, set the maximum and estimated run time.
  6. Optionally enable failure retries (Maximum Attempts, 1–999, and Minutes Between Attempts, 0–1440) and success reruns.
  7. Select Save & Close.
An offset counts from the workflow's start time, and can reach a later day

Every offset here is a duration from the workflow's start time on the job's schedule date, not a clock time. In a workflow that starts at 08:00, a Start Offset of 06:00 makes the job eligible at 14:00.

Because it is a duration, the hours field is not capped at 23 — it goes up to 99, a little over four days out — so a job that must start by 02:00 the morning after an 08:00 schedule takes 18:00. Earlier builds capped it at 23:59 and a cross-day deadline simply couldn't be written.

Each group has its own Format control (absolute/relative). The one under Offset Information covers the start offset and both thresholds that hang off it; Latest Offset has its own. Only absolute — measured from the planned start, as described above — is honored today; relative is stored and resolves the same way. See Offsets past midnight.

Offsets used to count from midnight

Earlier builds resolved these from midnight of the schedule date, so the 08:00 workflow above started its job at 06:00 — eight hours early, with nothing logged. If you set a deadline before this change and saw it firing too early, the definition needs no repair; rebuild the schedule date.

Clearing one of the four back to 00:00 on an already-built job instance is refused, with a message naming the field. Clear it on the definition and rebuild the date instead. See 00:00 means not configured.

Max Run Time now reaches the built job — and reports an overrun

A job set to overrun its Max Run Time used to do so silently and finish reported as a plain success. Two things were wrong and both are fixed, so check any job you set a limit on:

  • The limit never reached the built job. The frequency's Max Run Time was saved and carried through deployment, and every job the build produced carried no limit at all — the only way to get one onto a run was to edit the job instance by hand. The frequency's value now reaches every built job.
  • Nothing compared the elapsed time against it. The job now carries an Exceeded Max Run Time badge in the run, raises the Exceeded Max Runtime notification, and fires any job event on the exceededMaxRuntime trigger.

Set the value in minutes; 0 means no limit. The platform reports the overrun and does not stop the job — to have it killed, add an exceededMaxRuntime event with a $JOB:KILL command (see Run events on job outcomes). See Exceeding Max Run Time.

Failure retries now take effect, and Maximum Attempts counts retries

A job set to retry after failing made no second attempt in earlier builds — the plan was saved and the failing job never acted on it — so a retry configuration you set up in the past and assumed was inert is live now. Two things to get right before you rely on it:

  • Maximum Attempts is a count of retries, not of runs. 3 allows four runs: the first, and three more.
  • Leave room inside the Latest Start Offset. A retry that would fall after the deadline is not taken — the job fails at that point instead. With 3 attempts 30 minutes apart, the deadline needs at least an hour and a half of headroom past the job's own run time.

Between attempts the job waits in Wait start time, holding the last attempt's exit code, and releases no dependents until it is genuinely out of budget — so a failure-triggered recovery job does not fire on an attempt that is about to be retried. See Failure retries.

Success reruns now take effect

A job set to rerun after finishing OK never actually restarted in earlier builds — the setting was saved and the running job never saw it. It works now, so a rerun configuration you set up in the past and assumed was inert is live. If a job reruns on configured instance times and a run can outlast the next one, set Action on overlap: On completion (the default) fires the elapsed time immediately, Skip waits for the next time still in the future. See Success reruns.

The Latest Start Offset bounds every rerun, not just the first run

A job with both a run window and success reruns used to honour the window on its first run and then restart on its interval regardless of it. It no longer does: once the Latest Start passes, no further restart is scheduled, and a job already waiting for one ends as Missed start time — which retires the rest of its cycle. Set the Latest Start to a point that leaves room for every run you expect, or leave it at 00:00 for no deadline. See Recurring jobs and the latest-start deadline.

The Start Offset is the other way round — it gates the first start only, because scheduling a restart supersedes it.

Set how the workflow builds​

In the workflow's settings, set how the day's run is created:

  • Days in advance and days to build: which dates are created. Days in advance is the offset of the first date — 0 is today — and days to build is how many consecutive dates follow it.
  • Build on hold: build the run held, so it won't start until you release it.
  • Overwrite on build: let a rebuild replace an existing run for the same date.
  • Holiday calendar and working days: exclude days the workflow shouldn't run.
  • Allow Multi-Instance: build the workflow once per named schedule instance instead of once per date — see below.

Built runs are not removed automatically. A run stays in Processes until you delete it or a rebuild replaces it.

Who starts the build

The platform can build these dates for you once a day, but that daily build is off unless it's been enabled for your environment — until it is, someone starts each build. Two things behave differently when it is on: there is no per-workflow build time (one pass builds everything, at a time set for the environment), and an unattended rebuild never replaces a completed or cancelled run. See Automatic daily build.

Run one workflow per branch, region, or entity​

If the same sequence of jobs has to run several times a day over different data — one run per branch, per region, per legal entity — you don't need a copy of the workflow for each. Turn on Allow Multiple Instances and define a named schedule instance per variant, each carrying its own property values. One PAYROLL definition then builds as PAYROLL_BRANCH1 and PAYROLL_BRANCH2 for the same date.

  1. Open the workflow's Workflow Settings panel and go to the Instance Properties tab.
  2. Turn on Allow Multi-Instance.
  3. Add New Instance, name it, and add the properties whose values differ for this variant. Repeat per variant.
  4. Reference those values from your jobs with the SI scope — [[SI.BRANCH_CODE]].
  5. Save and deploy as usual.

To build them: Processes → Schedule Workflow, pick the workflow, then use the Schedule Instance picker — All instances builds every one, or pick a single instance to build just that one (which also lets you override its property values for that build).

Schedule Date takes a range, so you can build several days in one pass — up to 31 days, opening on today. Each date is built in turn and reported on its own, and one date the workflow isn't deployed for no longer abandons the rest. Your instance choice, the property overrides and both check boxes apply to the whole range, which matters most for Overwrite Existing: one tick across a week of a two-instance workflow deletes fourteen runs. See Scheduling a workflow across a date range.

Good to know
  • Instance names are case-sensitive and must be unique in the workflow. [[SI.InstanceName]] always resolves to the instance being run, so you can use it in job parameters and log paths.
  • A property marked Encrypted is deliberately not carried onto the run, so [[SI.…]] can't read it back. Don't put a value your jobs need there.
  • Dependencies inside the workflow stay within one instance — BRANCH1's jobs are not held by BRANCH2's. If two branches really do share something, use a Resource dependency.
  • You can't turn Allow Multi-Instance back off while more than one instance is defined, and turning it off does not un-build instances already built for a date.
  • Turning the setting on without defining any instance is fine — the workflow builds as one implicit instance named Default, and because it declares no properties, every build adds another run rather than colliding with the last. Earlier builds refused the second one.

Building the same instance twice for one date​

You can build one instance more than once for a date, and what decides whether you get a second run or a rebuild of the first is the instance property values the build carries:

  • Override a value so the set differs from every run already built, and you get a new run — displayed as PAYROLL_BRANCH1$0002.
  • Build with the same values as an existing run and it is that run: without Overwrite Existing you're told it already exists, and with it that run is replaced.
  • A workflow with the setting on that declares no instances has no property values to compare, so every build of it adds a run — the second reads PAYROLL_Default$0002.

Two things to know before you rely on it:

  • An overwrite against an instance holding several runs replaces only the matching run. If none matches, the build is refused rather than guessing — delete the runs you don't want, or build without overwrite to add one alongside.
  • One instance is capped at 100 live runs per date. Deleting a run makes room.

Schedule instances is the full reference — naming rules, repeat builds, what overwrite deletes, the per-request and per-instance limits, and how events target one instance.

Good to know
  • A job appears in a day's run only when its frequency matches that date and the day isn't excluded by a calendar or working-days rule.
  • The late-to-start, late-to-finish, and max-run-time settings drive the matching job statuses you (and Operators) can act on.
  • Build on hold is the safe way to stage a workflow without it running until you're ready.

Related topics