Timer events

Timer events are events triggered by a defined timer.

Timer start events

A process can have one or more timer start events (besides other types of start events). Each of the timer events must have either a time date or time cycle definition.

When a process is deployed, it schedules a timer for each timer start event. Scheduled timers of the previous version of the process (based on the BPMN process id) are canceled.

When a timer is triggered, a new process instance is created and the corresponding timer start event is activated.

Intermediate timer catch events

An intermediate timer catch event can either be a time duration, or a time date.

When an intermediate timer catch event is entered, a corresponding timer is scheduled. The process instance stops at this point and waits until the timer is triggered. When the timer is triggered, the catch event is completed and the process instance continues.

Timer boundary events

An interrupting timer boundary event must have a time duration, or a time date definition. When the corresponding timer is triggered, the activity is terminated. Interrupting timer boundary events are often used to model timeouts; for example, canceling the processing after five minutes and doing something else.

A non-interrupting timer boundary event must have either a time duration, a time cycle definition, or a time date definition. When the activity is entered, it schedules a corresponding timer. If the timer is triggered and defined as time cycle with repetitions greater than zero, it schedules the timer again until the defined number of repetitions is reached. It's important to note that a non-interrupting timer boundary event that's defined with a time duration will only trigger a single time once the date is reached.

Non-interrupting timer boundary events are often used to model notifications; for example, contacting support if the processing takes longer than an hour.

Timers

Timers must be defined by providing either a date, a duration, or a cycle.

A timer can be defined either as a static value (e.g. P3D) or as an expression. There are two common ways to use an expression:

• Access a variable (e.g. = remainingTime).
• Use temporal values (e.g. = date and time(expirationDate) - date and time(creationDate)).

If the expression belongs to a timer start event of the process, it is evaluated on deploying the process. Otherwise, it is evaluated on activating the timer catch event. The evaluation must result in either a string that has the same ISO 8601 format as the static value, or an equivalent temporal value (i.e. a date-time, a duration, or a cycle).

note

Zeebe is an asynchronous system. As a result, there is no guarantee a timer triggers exactly at the configured time.

Depending on how much load the system is under, timers could trigger later than their due date. However, timers will never trigger earlier than the due date.

Time date

A specific point in time defined as ISO 8601 combined date and time representation. It must contain timezone information, either Z for UTC or a zone offset. Optionally, it can contain a zone id.

• 2019-10-01T12:00:00Z - UTC time
• 2019-10-02T08:09:40+02:00 - UTC plus two hours zone offset
• 2019-10-02T08:09:40+02:00[Europe/Berlin] - UTC plus two hours zone offset at Berlin

Time duration

A duration is defined as a ISO 8601 durations format, which defines the amount of intervening time in a time interval and are represented by the format P(n)Y(n)M(n)DT(n)H(n)M(n)S. Note that the n is replaced by the value for each of the date and time elements that follow the n.

The capital letters P, Y, M, W, D, T, H, M, and S are designators for each of the date and time elements and are not replaced, but can be omitted.

• P is the duration designator (for period) placed at the start of the duration representation.
• Y is the year designator that follows the value for the number of years.
• M is the month designator that follows the value for the number of months.
• W is the week designator that follows the value for the number of weeks.
• D is the day designator that follows the value for the number of days.
• T is the time designator that precedes the time components of the representation.
• H is the hour designator that follows the value for the number of hours.
• M is the minute designator that follows the value for the number of minutes.
• S is the second designator that follows the value for the number of seconds.

Examples:

• PT15S - 15 seconds
• PT1H30M - 1 hour and 30 minutes
• P14D - 14 days
• P14DT1H30M - 14 days, 1 hour and 30 minutes
• P3Y6M4DT12H30M5S - 3 years, 6 months, 4 days, 12 hours, 30 minutes and 5 seconds

If the duration is zero or negative, the timer fires immediately.

Time cycle

A cycle defined as ISO 8601 repeating intervals format; it contains the duration and the number of repetitions. If the repetitions are not defined, the timer repeats infinitely until it is canceled.

• R5/PT10S: Every 10 seconds, up to five times
• R/P1D: Every day, infinitely

It's possible to define a start time. By doing this, the timer triggers for the first time on the given start time. Afterwards, it will follow the interval as usual.

• R3/2022-04-27T17:20:00Z/P1D: Every day up to three times, starting from April 27, 2022 at 5:20 p.m. UTC
• R/2022-01-01T10:00:00+02:00[Europe/Berlin]/P1D: Every day infinitely, starting from January 1, 2022 at 10 a.m. UTC plus 2 hours

Additionally, you can specify a time cycle using cron expressions. Refer to the CronExpression Tutorial for additional information about using cron expressions.

• 0 0 9-17 * * MON-FRI: Every hour on the hour from 9-5 p.m. UTC Monday-Friday

Additional resources

XML representation

A timer start event with time date:

 <bpmn:startEvent id="release-date">
  <bpmn:timerEventDefinition>
    <bpmn:timeDate>2019-10-01T12:00:00Z</bpmn:timeDate>
  </bpmn:timerEventDefinition>
</bpmn:startEvent>

An intermediate timer catch event with time duration:

<bpmn:intermediateCatchEvent id="coffee-break">
  <bpmn:timerEventDefinition>
    <bpmn:timeDuration>PT10M</bpmn:timeDuration>
  </bpmn:timerEventDefinition>
</bpmn:intermediateCatchEvent>

A non-interrupting boundary timer event with time cycle:

<bpmn:boundaryEvent id="reminder" cancelActivity="false" attachedToRef="process-order">
  <bpmn:timerEventDefinition>
    <bpmn:timeCycle>R3/PT1H</bpmn:timeCycle>
  </bpmn:timerEventDefinition>
</bpmn:boundaryEvent>

References

• Expressions
• ISO 8601