Timers

Overview

A Timer represents one of internal triggers that makes a process leave the idle state and perform a specific action. Timers can be exceptionally useful to schedule a certain action or event within your project. For example, you can create a timer that will send an email after your specified time interval.

The primary advantage of timers is their ability to automate processes, eliminating the need for manual intervention in routine tasks. Therefore, timers enable the execution of actions at precise moments, which in turn allows enhancing accuracy. Timers can also optimize resource allocation by automating tasks, contributing to overall operational efficiency.

In addition, timers can be aligned with working hours and days, ensuring actions are performed only within specified operational periods. The system also allows establishing and configuring your work calendars. Learn more about setting up timers with work calendars in the Work Calendars article.

The system incorporates specific properties and rules that ensure the correct and optimized execution of your specified actions and events. The following introduces such properties, rules, and provides other important technical specifications of the Timer functionality.

Timer Properties

The system allows configuring various properties of your timer by using a corresponding button on the Toolbar. Once this button is clicked, the following properties become available for the subsequent modification:

• Name: All timer objects are identified by their case-sensitive names.
• Type: Your selected timer type influences the Timer Value interpretation.
• Value: Depending on your specified Type, the system allows setting one of the following values:
  • Interval: If you select this type, you can establish a delay for a subsequent action and utilize the following units:
    • An integer, interpreted as milliseconds (e.g., 1);
    • An integer followed by 'd'/ 'day'/ 'days', indicating days (e.g., 2d);
    • An integer followed by 'h'/ 'hour'/ 'hours', indicating hours (e.g., 3h);
    • An integer followed by 'm'/ 'minute'/' minutes', indicating minutes (e.g., 4m);
    • An integer followed by 's'/ 'second'/ 'seconds', indicating seconds (e.g., 5s);
    • An integer followed by 'ms'/ 'millisecond'/ 'milliseconds', indicating milliseconds (e.g., 1ms);
    • Note that the interval measurement units can be combined, for example, "2d 5h 24m 15s", "2days 5hours", etc.
  • Date: In case this type is selected, the system will trigger an action on a specified date at 0 hours 0 minutes. The date format is MM/dd/yyyy by default, for example, 02/20/2020.
  • Time: Selecting this type will activate an action at a designated time. If the specified time has not yet occurred when the timer is set, it will trigger on the current day; if the time has already passed, it will activate on the following day. The default time format is in 24-hour HH:mm:ss, for example, 15:45:55.
  • Date And Time: This type triggers an event at a specified time and date. The date format is MM/dd/yyyy HH:mm:ss by default, for example, 02/20/2020 15:45:55;
  • Expression: This type allows you to use expressions with parameters. That will be interpreted the following way:
    • If the expression returns a DateTime the timer will be set to the DateTime;
    • If the expression returns an integer value the timer will act as an interval timer where the returned value is interpreted as an interval in milliseconds;
    • If the expression returns a TimeSpan value, the value will be added to the current value;
    • If the expression returns a string, it will be attempted to be converted to an integer and the value interpreted as an interval in milliseconds. If the conversion is not possible, the runtime.GetCustomTimerValueAsync method will be used, if you implemented it;
• Override: If set to true (i.e., checked), your provided Timer Value cannot be overridden in case a timer object with the same name is already exist in the WorkflowProcessTimer table. This feature can be helpful to implement complex use case scenarios. For example, you can orchestrate the system to trigger a service call every 5 minutes within a 2-hour window and structure this operation as a singular activity.

Important to note

In case of using the <w> notation before provided Interval timer values (e.g., 1wd for 1 workday), the system will activate the timer according to your provided work calendar. Refer to the Work Calendars article for more details.

IIS warning

caution

In case you host WorkflowRuntime via an IIS server (or any other web server) and want to utilize timers, it is necessary to keep your server up so that it will not stop running a process when there are no active queries. Thus, for example, the required setting within IIS is called Idle Time-out and it is applied to Application Pool.

Timer Execution Rules

In order to successfully deploy timers within WorkflowRuntime, follow the steps bellow:

1. Configure the WorkflowRuntime for single-server or multi-server environment:

• Use the following call for the single-server environment:

  runtime.AsSingleServer();

• Use the following call for the multi-server environment:

  runtime.AsMultiServer();

2. Call Start() method to launch the workflow runtime:

   runtime.Start();

As a result, the timers should be deployed within the workflow runtime.

The WorkflowRuntime object incorporates TimerManager. As the name suggests, the TimerManager is used to control the execution of timers within the system. These timers, associated with specific tasks, are stored in the WorkflowProcessTimer table. When an internal timer triggers, the TimerManager identifies the timers set for execution at the current time and schedules their tasks accordingly. Note that timer execution closely resembles command execution, with the key distinction being that it's initiated by the TimerManager. The process does not receive any parameters apart from the name of the triggered timer.

Upon task scheduling, the TimerManager calculates the next triggering time and updates the internal timer accordingly. If the server has experienced a prolonged idle state during which timers were meant to execute, they will be executed immediately once the runtime.Start() command is invoked.

In case a process reaches a new Activity that contains a Transition triggered by Timer, the system initiates the following sequence of actions:

• All timers associated with the process that do not trigger any transitions from the new Activity are removed.
• Timers responsible for triggering transitions from the new Activity are determined. Each timer is assigned a specific triggering time.
• The triggering configurations for each timer are recorded in the WorkflowProcessTimer table. In case a timer with the same name already exists, the system checks the Override attribute. If this attribute is set to false, the timer's triggering time will not be updated.

When the designated triggering time of the Timer is reached, the system selects all associated transitions from the current Activity within the corresponding process. Note that the system also identifies the right transition that should be executed. Thus, for instance, in case multiple conditions are established for transitions, the system checks these transitions and selects a required transition that should be executed.