Time triggers

Introduction to time triggers

Time triggers are interrupts which signal that a certain time has passed since a case has entered a scope or activity. They can be attached to scopes and activities. A time trigger attached to a scope is initialized when a case has entered this scope. Scopes can have several time triggers. A time trigger attached to an activity is initialized when this activity has been executed. An activity can have only one time trigger. The actions which should be performed when the configured time has passed need to be scripted in an automatic activity connected to the trigger.

Examples for the use of time triggers:

• Put a case on hold for a defined time period.

• Control escalation times and SLAs by implementing alerts if a case has not been taken care of in a defined time period, for example, by adding overlays to the case icon or sending emails or notifications to the users.

• Move a case which is closed from a business perspective to the end node, i.e., technically close the case, after the configured time period.

Process logic with time triggers

The following general logic applies to time triggers:

The time measuring of a trigger is started (i.e., the trigger is initialized) when the case enters the scope / activity. It stops (i.e., the trigger fires) when the defined period of time which has been set as fixed value (minutes / hours / days) or the manually defined time has elapsed.

1. The trigger is initialized, i.e., the time measuring is started, when the case enters the scope or activity.

2. The trigger fires when the defined period of time has elapsed.

   • For manual triggers at activities, this is the time which the user sets when he executes the activity.

   • For automatic triggers at activities or scopes, this is the time defined in minutes, hours and days.

   • It is possible to set another time when the timer is initialized or running, see Modifying timers in scripts.

   If the time measuring should consider a business calendar, you need to set the Use calendar option and assign a business calendar to the queue, see Using a business calendar.

3. When the trigger fires, the trigger script is executed. If it returns true, the following automatic activity or decision node with two following automatic activities is executed.

Available settings for time triggers

The following settings are available for time triggers:

• Path:
  Read-only. The path to the time trigger within the workflow. Used to reference the trigger in scripts.

• Set time manually:
  Optional. Only for time triggers at activities. Determines if the time when the trigger fires should be set by the user. In this case, a calendar is displayed when the user selects the activity in the Web Client and the trigger is initialized with the time entered by the user. Therefore, the fields to define the time period are not available.

• Time period:
  Mandatory. Enter the number of days, hours and minutes after which the trigger fires.

• Use calendar:
  Optional. Determines if the time calculation is based on the business calendar, see Using a business calendar.

• Repeatable:
  Optional. Determines if the trigger can fire more than once for a case. Repeatable triggers are re-initialized immediately after having fired, i.e., the time count starts again and the initialization script is executed again.

• Initializing script:
  Optional. Determines if and when the trigger should fire, see Timer is initialized.

• Script:
  Optional. Determines if the subsequent automatic activity is executed, see Time has elapsed.

  Best practice

  Use this script only to determine if the automatic activity is executed or not. All other actions should be performed in the script of the automatic activity connected to the trigger.

• Retry interval:
  Optional. Determines the time in seconds after which the trigger execution should be executed again in case a script has run with an error. The default time is configured in the system property cmas-workflow-engine, jobExecutor.timerRetryInterval.seconds.

Tasks

Using a business calendar

By default, the calculation of the time when a trigger fires is based on absolute times. You can use a business calendar to adapt the calculation to your working hours. This avoids that time triggers fire during the weekend or outside your business hours.

Please perform the following steps to use a business calendar:

1. Define a business calendar, see Calendars.

2. Assign the business calendar to the queues which use the workflow, see Queues.

3. Select the checkbox Use calendar for all time triggers to which the business calendar should apply, see Available settings for time triggers.

Example: A time trigger is set to fire after 1 day.

Without business calendar:

The trigger fires 24 hours later, i.e., at the same time on the next day.

With business calendar:

There is a business calendar which defines the working hours as Monday to Friday from 9am to 5pm. The trigger fires 24 business hours later.

• Initialization on Monday, 10am
  → The trigger fires on Thursday, 10am. This is three working days later (24 hours / 8 working hours per day).

• Initialization on Friday, 10am
  → The trigger fires on Wednesday, 10am. This is three working days later (24 hours / 8 working hours per day) and the weekend is omitted.

The following figure shows an example of business calendars used to calculate SLA times.

Figure 14: ConSol CM - Business calendar

You can use the methods of the class BusinessCalendarUtil to calculate time periods which are based on a business calendar.

Modifying timers in scripts

You can modify timers in several ways, depending on the current point within the process.

Timer is initialized

The timer is initialized when the case enters the respective scope or activity. At this point, the timer can be modified using the initialization script. This script can be used, for example, to calculate the reaction time based on the case priority, or to disable the timer if it is not relevant for the case.

The trigger is implicitly available as trigger (class TimerTrigger) in the script. There are two actions you can perform in the script:

• Omit / disable the trigger, so that it is not fired for the case unless it is initialized again.
  → Return null or false.

• Modify the time when the trigger should fire.
  → Calculate a Long value, standing for the milliseconds from the moment of initialization to the moment of firing, and pass the value as a parameter to the method trigger.setDueTime(). The method defines the time period in milliseconds from the moment when the case enters the scope or activity to the moment of firing.

  Example: The escalation time of a case should be based on its priority. For each priority, there is a system property which holds the escalation time in minutes.

  def escalationTime = configurationService.getValue("custom-mycompany-properties","escalation.time.medium.minutes")

  def escalationTimeMillisecs = escalationTime * 60 * 1000L

  trigger.setDueTime( escalationTimeMillisecs )

Timer is running

The timer runs as long as the case is located in the scope or activity where the trigger is attached. You can modify the timer using workflowApi methods.

• Reinitialize a timer with the original initialization date.
  → Use the method reinitializeTrigger(String pTriggerName) to reinitialize the timer with the date when the case entered the scope or activity.

• Reinitialize a timer either with a new initialization date.
  → Use the method reinitializeTrigger(String pTriggerName, Date pBaseDate) to reinitialize the timer with the provided date. This is independent from the date when the case entered the scope or activity. If you want to reinitialize the trigger of another case, use the method reinitializeTrigger(Ticket pTicket, String pTriggerName, Date pBaseDate) which accepts the case as a parameter.

• Deactivate a timer so that it does not fire unless it is initialized again.
  → Use the method workflowApi.deactivateTimer(String pName).

These operations need to performed in an activity outside the trigger flow. The trigger is referenced by its path.

Time has elapsed

The trigger fires when the configured time has elapsed. Then, the trigger script is executed. If it returns true, the automatic activity or decision node after the trigger is executed. If it returns false, they are not executed, i.e., the trigger has no effect for the case.