Skip to content

Timer Events in Pythmata

Timer events allow you to control the flow of your process based on time. This guide explains how to configure and use timer events in Pythmata.

Timer Scheduler

Pythmata includes a robust timer scheduler that automatically triggers timer events based on their configuration. The timer scheduler has the following features:

  • Persistent Storage: Timer state is stored in Redis, ensuring timers survive application restarts
  • Efficient Scheduling: Uses APScheduler for efficient timer management
  • Fault Tolerance: Automatically recovers timer state after system crashes
  • Distributed Execution: Supports running in a distributed environment
  • Automatic Detection: Automatically detects and schedules timers from process definitions

Types of Timer Events

Pythmata supports three types of timer events:

  1. Start Timer Events: Begin a process at a specific time, after a duration, or on a recurring schedule
  2. Intermediate Timer Events: Pause the process flow until a specific time condition is met
  3. Boundary Timer Events: Attached to activities to handle timeouts or schedule additional work

Timer Configuration

Timer events can be configured using the properties panel in the BPMN modeler. When you select a timer event, you'll see a "Timer" tab in the properties panel with the following options:

Timer Types

  • Duration: Specifies a time period (e.g., 1 hour and 30 minutes)
  • Date: Specifies a specific date and time
  • Cycle: Specifies a recurring time interval

Timer Formats

All timer values use the ISO 8601 format:

  • Duration: PT[hours]H[minutes]M[seconds]S
  • Example: PT1H30M (1 hour and 30 minutes)
  • Example: PT30M (30 minutes)

  • Example: PT10S (10 seconds)

  • Date: YYYY-MM-DDThh:mm:ss

  • Example: 2025-03-15T09:00:00 (March 15, 2025, at 9:00 AM)

  • Cycle: R[repetitions]/[interval]

  • Example: R3/PT1H (repeat 3 times, every hour)
  • Example: R/P1D (repeat indefinitely, every day)

Timer Event Behavior

Start Timer Events

  • Duration: The process starts after the specified duration from deployment
  • Date: The process starts at the specified date and time
  • Cycle: The process starts repeatedly at the specified intervals

Intermediate Timer Events

  • Duration: The process flow continues after the specified duration
  • Date: The process flow continues at the specified date and time
  • Cycle: The process flow continues after each cycle interval

Boundary Timer Events

  • Interrupting: Cancels the activity when the timer triggers
  • Non-interrupting: Creates a parallel flow without cancelling the activity

Examples

Example 1: Process that starts every day at 9:00 AM

<bpmn:startEvent id="StartEvent_1">
  <bpmn:timerEventDefinition>
    <bpmn:timeCycle xsi:type="bpmn:tFormalExpression">R/PT24H</bpmn:timeCycle>
  </bpmn:timerEventDefinition>
</bpmn:startEvent>

Example 2: Activity with a 1-hour timeout

<bpmn:userTask id="UserTask_1" name="Complete Form">
  <bpmn:incoming>Flow_1</bpmn:incoming>
  <bpmn:outgoing>Flow_2</bpmn:outgoing>
</bpmn:userTask>

<bpmn:boundaryEvent id="BoundaryEvent_1" attachedToRef="UserTask_1">
  <bpmn:timerEventDefinition>
    <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">PT1H</bpmn:timeDuration>
  </bpmn:timerEventDefinition>
  <bpmn:outgoing>Flow_3</bpmn:outgoing>
</bpmn:boundaryEvent>

Example 3: Using tFormalExpression

When defining timer events in BPMN XML, you can use the xsi:type="bpmn:tFormalExpression" attribute to specify that the timer value is a formal expression:

<bpmn:startEvent id="StartEvent_1" name="5 min">
  <bpmn:timerEventDefinition id="TimerEventDefinition_1">
    <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">PT5M</bpmn:timeDuration>
  </bpmn:timerEventDefinition>
</bpmn:startEvent>

This is particularly important when: - Using the BPMN modeler to create timer events - Importing BPMN diagrams from other tools - Ensuring compatibility with the BPMN 2.0 specification

Best Practices

  1. Use appropriate timer types:
  2. Use duration for relative time periods
  3. Use date for specific points in time

  4. Use cycle for recurring events

  5. Include the xsi:type attribute:

  6. Always include xsi:type="bpmn:tFormalExpression" for timer definitions
  7. This ensures compatibility with the BPMN 2.0 specification

  8. The Pythmata validator handles this attribute correctly

  9. Consider time zones:

  10. Date timers are interpreted in UTC unless specified otherwise

  11. Be aware of daylight saving time changes

  12. Test timer behavior:

  13. Use short durations for testing

  14. Verify timer behavior in different scenarios

  15. Handle timer failures:

  16. Implement error handling for timer-related issues
  17. Consider what happens if the system is down when a timer should trigger