Core Triggers and Actions - Timer Trigger
The documents in this section discuss the core triggers and actions in Flux.
The timer trigger fires at a scheduled date and/or time. There are a few ways a timer trigger can be scheduled, including running once at an absolute time (known as a “one-shot” firing), running repeatedly on a schedule, running repeatedly on a schedule until a given date, or even running a certain number of times on a schedule before following some alternate flow.
Unlike the delay trigger, a timer trigger can be configured to make up for missed firings.
The timer trigger can also be expedited. Expediting a timer trigger does not update its internal state (such as decrementing the count or adjusting the next scheduled date), so expediting a timer trigger will not have any effect on normally scheduled future firings.
Properties
Business Interval
Specifies an (optional) business interval that the engine can consult when scheduling future firings for this trigger.
If there is a business interval specified on the trigger, then the special character “b” and “h” will be evaluated to check for business and non-business days, respectively.
For more information on using business intervals and scheduling timer triggers against those intervals, see Business Intervals and Time Expressions.
Count
The total number of times this trigger should be allowed to fire.
For example, a count of “5” means that the timer trigger will fire 5 times according to its schedule. The next time a flow enters the trigger, it will see that the count has been met and the timer trigger will expire.
You can also use the count to take a certain action after a specific number of firings - for example, sending a notification on the last firing of the day. For more information about this, see timer trigger expiration.
End Date
The date at which the timer trigger will expire. No future firings may occur after this date is reached.
For example, if the trigger’s end date is April 30, 2011 08:00:00, then the trigger will fire normally according to schedule until that date. Once that date is reached, the trigger will expire.
End Time Expression
A time expression that indicates when the timer trigger should expire. This time expression is applied to the date that the workflow is exported to the engine to determine the expiration date.
For example, if the End Time Expression is “+1M” (or one month), then the timer trigger will fire normally for a month after being exported to the engine. After the month has elapsed, the timer trigger will expire.
Late Time Window
A time expression is applied to the trigger’s scheduled firing date to determine the absolute latest time the trigger can fire without being skipped.
For example, a late time window of “+5m” (five minutes) means that the timer trigger can fire up to five minutes past its scheduled firing time. A late time window of “+1d” would allow the timer trigger to fire up to one day late.
Flux will only fire missed firings if the latest missed firing is within the late time window, or if makeup firing is enabled.
A timer trigger might be late for a number of reasons - for example, the engine might be down for an extended period of time, where one or more firings would normally have occurred. In this case, when the engine was available again, it would consult the late time window to determine whether the missed firings should be made up.
When setting a late time window, it is important to consider that during normal operation, a timer trigger may be late by several seconds or even minutes. For this reason, we do not recommend setting the late time window lower than “+5m” (five minutes), to allow workflows ample time to fire in normal operation.
If the timer trigger attempts to run but the late time window has elapsed, it will simply determine the next scheduled date and continue running as normal (unless makeup firing is enabled - see below for details).
If you do not want the trigger to make up for any missed firings at all, it is more appropriate to use a delay trigger. A delay trigger will fire as soon as possible after its scheduled trigger date, then calculate the next firing time based on when it is next re-entered (in other words, the next firing time is calculated when the next incoming flow to the delay trigger arrives); a timer trigger, on the other hand, calculates next firing times based on the schedule trigger date and not the actual date.
The table below contains several examples of using the late time window. In the table, “Scheduled Date” is the date that the trigger is scheduled to execute, “Late Time Window” is the late time window configured on the trigger, “Actual Date” is the date that the engine attempted to fire the trigger, “Time Expression” is the time expression for the trigger, and “Result” is the behavior of the engine when it evaluates the late time window.
Examples
| Scheduled Date | Late Time Window | Actual Date | Time Expression | Result |
|---|---|---|---|---|
| April 30, 2011 08:00:00 | +6H | April 30, 2011 10:30:00 | +6H | Actual date is within the late time window, so the trigger fires. Only one firing was missed so the trigger continues as normal, scheduling the next firing for 14:00:00. |
| April 30, 2011 08:00:00 | +5m | April 30, 2011 08:06:00 | +6H | Actual date is not within the late time window, the trigger does not fire. The trigger simply schedules the next execution at 14:00:00 as though no firing was missed. |
| April 30, 2011 08:00:00 | +30m | April 30, 2011 08:25:00 | +10m | Actual date is within the window, so the trigger fires. Two additional firings were missed(08:10:00 and 08:20:00); the triggers fire again for each of those before setting the next date (April 30, 2011 08:30:00). |
| April 30, 2011 08:00:00 | +1H | April 30, 2011 10:30:00 | +1H | Actual date is not within the late time window, the trigger does not fire (even though one of the missed firings was within the window). The next firing date (April 30, 2011 11:00:00) is scheduled. |
Makeup Firing Enabled
This property is only evaluated if the late time window has elapsed but there are one or more missed firings.
If makeup firing is enabled, at least one firing was missed, but that firing did not fall within the late window, then Flux will fire a single makeup firing before advancing to the next scheduled trigger date.
This is useful in cases where several firings were missed and did not fall within the late time window, but you still want to fire once to compensate for the missed firings.
Examples
| Scheduled Date | Late Time Window | Actual Date | Time Expression | Enable Makeup Firing | Result |
|---|---|---|---|---|---|
| April 30, 2011 08:00:00 | +6H | April 30, 2011 15:00:00 | +6H | true | Late time window has elapsed but makeup firing is enabled, so the trigger fires. The next date (April 30, 2011 20:00:00) is scheduled. |
| April 30, 2011 08:00:00 | +6H | April 30, 2011 15:00:00 | +6H | false | Late time window elapsed and makeup firing is disabled, so the trigger does not fire. The next date (April 30, 2011 20:00:00) is scheduled. |
| April 30, 2011, 08:00:00 | +1H | April 30, 2011 10:32:00 | +5m | true | Late time window has elapsed but makeup firing is enabled, so the trigger fires once. The next date (April 30, 2011 10:35:00) is scheduled. |
Scheduled Trigger Date
The date and time that the trigger is next scheduled to fire.
For a one-shot timer, the trigger will fire on this date and ignore any value set for the time expression. This is ideal when you are scheduling a trigger that should only fire once at a specific instant.
For a recurring timer, the trigger will fire on this date, then use the time expression to calculate the next firing date. This is useful when you want to fire on a repeating scheduling that should begin on a specific date.
Time Expression
A time expression that governs how frequently the timer trigger will fire. The time expression is applied to the last scheduled trigger date (if the timer trigger has not fired previously and there is no scheduled trigger date, the time expression is applied to the time that the workflow is exported to the engine).
For a one-shot timer, if there is no scheduled trigger date, the time expression is applied to the time that the workflow is exported to determine when the timer trigger will fire. If there is a scheduled trigger date on a one-shot timer, this property is ignored.
For a recurring timer, the expression is applied to the last scheduled trigger date to determine the next firing. So, for example, if the last scheduled trigger date was April 30, 2011 at 08:00:00 and the time expression is “+2H”, the next scheduled date will be set to April 30, 2011 at 10:00:00. Note that since the expression is applied against the last scheduled date (and not the actual firing date), a late or missed firing will not affect future scheduled dates.
If you would prefer for the time expression to be applied against actual firing dates instead of scheduled dates, you must use a delay trigger in place of the timer trigger.
Time Zone
The time zone this trigger should use when calculating firing times. This is useful when the trigger is created in one time zone but must be scheduled according to a different time zone.
If you do not specify a time zone, the trigger will use the default time zone (the time zone of the JVM) from the client side. Keep in mind that because the client side time zone is used, the trigger may not fire according to the server’s time zone if the client and server do not share a time zone.
If the system or JVM time zone is not correctly configured on the client, the trigger’s time zone may be set to the generic format (such as “GMT+05:30”) instead of the proper form (“Asia/Calcutta”). If the time zone is set in the generic format, any daylight savings time information will be lost. In some areas of the world (such as India) where daylight savings is not observed, this will not cause any information to be lost.
In addition, if you use a custom time zone, its ID must match the generic time zone format (such as “GMT+05:30”) for Flux to store the custom time zone. This means that daylight savings information in the custom time zone cannot be stored (this is due to a limitation in the JDK time zone API).
Results
The Timer Trigger returns its result in the flow context variable “result”. The result contains a boolean indicating whether the trigger has expired. You can access the result from the following field:
| Flow Context Variable | Field | Java Type | Description | Prescript / Postscript Example |
|---|---|---|---|---|
| RESULT | result | boolean | Indicates whether the timer trigger has expired. The trigger can expire if its maximum count is reached, or it reaches the end date or the end time expression is satisfied. If this value is true, the timer trigger has not expired. If the value is false, the timer trigger has expired. By default, every flow you create from a timer trigger has the condition “RESULT.result”. This means that the flow will only be followed if the trigger has not expired. If you create a flow with the else condition or the condition “NOT RESULT.result”, then the trigger will only follow that flow after it has expired. This is useful when the workflow must take a certain action only after the last scheduled firing has occurred and the trigger is expired. | boolean expired = flowContext.get("RESULT").result; System.out.println("Expired? " + result); |
Passing Results with a Runtime Data Map
You can use a Runtime Data Map to copy the result field into a new variable (for future reference or to reuse the data later in the workflow).
To copy the result, you can use a data map like:
One-shot vs. Recurring Timers
A one-shot timer fires just once. One-shot timers are useful when a certain task must be scheduled for a single firing at a specific instant.
A recurring timer, on the other hand, firings on a schedule. Recurring timers can fire forever on a schedule, or be restricted to fire a certain number of times or until a certain date.
A timer trigger will only reschedule itself (that is, schedule the next firing) when a flow enters it. A recurring workflow, therefore, must have a flow looping back into either — either from somewhere else in the workflow or from the timer trigger itself. For more information on this, refer to the Flux FAQ.
One-shot
To schedule a one-shot timer, set the time expression or scheduled trigger date and make sure that there are no flows leading back into the timer trigger.
Recurring Timers
To schedule a recurring timer, set the time expression and (optionally) the scheduled trigger date, then add a loop in the workflow that flows back into the timer trigger.
By default, the timer will never expire, meaning that it will continue on this schedule as long as there are future firings available. If you want the timer to expire, you can set either the count, end date, or end time expression to specify when the timer should expire.
Timer Trigger Expiration
By setting the count, end date, or end time expression, you can cause your timer trigger to expire at a certain date or after a certain number of firings. Once a timer trigger has expired, it will stop firing, set the result value to false, and follow any else flow or conditional flow with the condition “NOT RESULT.result”.
You should use the timer trigger expiration when your workflow needs to follow a certain schedule, but only for a limited number of firings or until a certain date occurs.
You can also use the expiration when you are executing a number of steps on a schedule, and you want to take another action after a certain number of firings have occurred (for example, if you wanted to send an email after the last scheduled firing for the day). To do so, you would need two things:
- A count set on the trigger specifies how many firings will occur before the alternate action takes place. For example, if your trigger fires 10 times a day, you might set the count to 10 so the trigger expires after the last firing.
- An else flow or conditional flow (with the “NOT RESULT.result” condition) that moves into some other action, such as a mail action to send a notification.
- At the end of the branch created by the else / conditional flow, add another flow going back into the timer trigger. This will reset the count to its original value and schedule the next firing.