Timers & Scheduling
Every workflow has steps that should not wait for a person. An approval that auto-escalates after 48 hours. A nightly batch job that runs at 2 AM. An SLA reminder every Monday morning. Without timer support, you need external schedulers, polling loops, or custom cron jobs to advance the process on a schedule.
Timers on transitions let Workflow Engine fire state changes automatically - after a delay, at a specific time, or on a recurring interval. The runtime tracks pending timers in the persistence store, evaluates them continuously, and fires the associated transition when the timer condition is met.
With timers, you model time-driven behavior directly in the workflow scheme. An approval step has two outgoing transitions: one triggered by the user clicking "Approve" and one triggered by a 48-hour timer. Whichever fires first determines the path. No polling, no external scheduler, no custom code.
What it is
Think of a timer as an alarm clock attached to a transition. When a process instance enters an activity that has a timer-enabled outgoing transition, the runtime sets the alarm. If the user acts first, the alarm is cancelled. If the alarm rings first, the process advances automatically.
A timer is defined on a transition by setting its trigger type to Timer and attaching a TimerDefinition with a name, a type, and a value. The timer type determines how the value is interpreted:
- Interval - a delay measured in milliseconds from when the process enters the source activity. The value can be a plain number of milliseconds (
"3600000"for one hour) or a combined string ("1 d 3 h"for one day and three hours). - Time - a specific time of day, expressed as
"HH:mm". If the time has already passed today, the timer fires at that time tomorrow. - Date - a specific calendar date. The timer fires at midnight (00:00:00) on that date.
- DateAndTime - a specific date and time combination, such as
"2025-12-31 23:59". - Expression - a custom expression that returns a
DateTimevalue at runtime. This lets you calculate the timer value dynamically based on process parameters.
When the timer fires, the runtime evaluates the transition's condition before executing. If the condition returns false - for example, the process state no longer matches the timer's intent - the timer is consumed without advancing the process. This prevents stale timer firings from moving the workflow when the context has changed.
Calendar-aware intervals use the w prefix on time units: whours, wdays, wmonth, wyears. These intervals skip non-working time defined in the Working Calendar. A timer set for "48 whours" from Friday at 5 PM fires on Tuesday instead of Sunday - the working hours counter pauses over the weekend.
For developers: timers are defined as TimerDefinition objects on transitions with Trigger.Type == TriggerType.Timer. The runtime registers the timer in persistence when the process enters the source activity and deletes it when the process leaves via another transition. The timer evaluator polls for due timers and fires the associated transition. See Timer concept for the full API reference.
Why it matters
Timers deliver these outcomes:
Automatic escalation and SLA enforcement - set a timer on an approval activity to escalate to a manager after a working-day delay. No polling, no custom scheduler, no developer intervention.
Time-based branching - a single activity can have two outgoing transitions: a command transition for the user and a timer transition for automatic advance. The first to fire wins. This is how approval escalation works without custom code.
Calendar-aware scheduling - working-day and working-hour intervals (
wdays,whours) respect your configured business calendar. Timers fire only during business hours and skip holidays, weekends, and non-working days automatically.Dynamic timer values - the Expression timer type lets you calculate the timer delay from process parameters. For example, the approval deadline can be set per-instance based on the order priority or customer tier.
Who it is for
Evaluator (CEO, CTO, PM): timers eliminate the need for external schedulers and polling jobs for workflow automation. Escalation paths, SLA enforcement, and scheduled processing are modeled inside the workflow scheme, not scattered across cron jobs and background services.
Developer: timers are configured as a property on a transition in the scheme. The runtime handles registration, evaluation, and cleanup automatically. No timer management code is needed in your application. See Configure Timers for setup.
Enterprise architect: timer records are stored in the persistence database alongside process instances and are evaluated by the runtime's timer manager. In multi-server deployments, timers are distributed across nodes with locking to prevent duplicate execution. The runtime enforces timer consistency even under node failure.
When to use it
Use timer-driven transitions when a process must advance without direct user action. Typical examples:
- Approval escalation - an expense report approval auto-escalates to the next manager if the first approver does not act within 48 working hours. The timer is defined on the "Pending Approval" activity alongside the "Approve" command.
- SLA enforcement - a support ticket workflow sends an automated reminder if a ticket remains in "Assigned" state for more than 4 hours. The timer fires, evaluates the condition, and triggers a notification action.
- Scheduled batch processing - a nightly workflow runs at 2:00 AM to process end-of-day reports. The timer type is
Timewith value"02:00". - Dynamic deadlines - a contract review process calculates the deadline based on the contract value. High-value contracts get a 24-hour deadline, standard contracts get 72 hours. The timer uses type
Expressionwith a formula that reads the contract value parameter.
How it compares
Timers in Workflow Engine are built into the runtime at the persistence layer. The alternative is to manage scheduling externally.
| Approach | What it requires | Result |
|---|---|---|
| External cron / scheduler | A separate scheduling service, polling logic in the workflow, API calls to execute commands at scheduled times. | Two systems to maintain. Risk of drift between the scheduler schedule and the workflow state. |
| Workflow Engine timers | Configure the timer on the transition in the scheme. The runtime handles registration, evaluation, firing, and cleanup. | Timer logic lives in the workflow definition. The runtime manages the full lifecycle and guarantees that a timer fires only if the process is still in the expected state. |
Workflow Engine timers are not a replacement for a general-purpose task scheduler. They are scoped to the lifecycle of a process instance - the timer exists only while the process is in the source activity and is automatically cleaned up when the process moves on.
Frequently asked questions
What timer types does Workflow Engine support?
Five types: Interval (delay in milliseconds or combined time units), Time (specific time of day), Date (specific date at midnight), DateAndTime (specific date and time), and Expression (dynamic value calculated at runtime). All are defined as a TimerDefinition on a transition with TriggerType.Timer.
Can I use calendar-aware intervals that skip weekends and holidays?
Yes. Prefix the time unit with w to make it calendar-aware: whours, wdays, wmonth, wyears. These intervals skip non-working time as defined in the Working Calendar. For example, "48 whours" fires after 48 working hours, skipping weekends and holidays.
Are timers automatically cancelled when the process moves on?
Yes. When a command or auto-transition executes and moves the process out of the source activity, the runtime deletes all pending timers registered for transitions from that activity. The persistence provider's DeleteInactiveTimersByProcessIdAsync handles cleanup. No explicit API call is needed.
Do I need a specific license or edition to use timers?
No. Timer support is included in the core runtime and is available in all Workflow Engine editions.
Can I calculate the timer delay dynamically from process parameters?
Yes. Use the Expression timer type. The value is a formula that returns a DateTime. For example, you can set the deadline based on an order priority parameter, a contract value, or a customer tier. The expression is evaluated when the process enters the source activity.