Child pages
  • Timer Trigger
Skip to end of metadata
Go to start of metadata

 

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 elapse, the timer trigger will expire.

Late Time Window

If the Late Time Window is Not Specified

If a late time window is not specified a trigger will fire whenever the scheduled firing date is less than the current system time. So if a timer trigger is set to fire at noon, but the Flux server is unavailable until 1:00 PM, the trigger will fire when the server is brought back up at 1:00 PM.

A time expression that 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.
  • there is not enough concurrency available to process jobs in a timely manner, so a timer trigger may not be reached for scheduling until after its late time window has passed.

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 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 fires 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 - Assume the Flux server was unavailable from April 30, 2011 07:59:00 to April 30, 2011 15:00:00

Scheduled Date

Late Time Window

Actual Date

Time Expression

Enable Makeup Firing

Result

April 30, 2011 08:00:00

Not specified

April 30, 2011 15:00:00

+6H

Not specified (default is false)

The trigger fires at April 30, 2011 15:00:00. 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

true

Late time window has elapsed but makeup firing is enabled, so the trigger fires at April 30, 2011 15:00:00. 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 the trigger fires. 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

Specifies the time zone this trigger will use to calculate firing times. This setting can be especially useful when you run a workflow in one time zone, but it must fire according to another time zone – for example, a workflow that runs in New York, but executes at 08:00 London time.

If you don't specify a time zone, the timer trigger will automatically detect the default time zone at development time. The trigger will pick up the client-side time zone, which can come from one of two places: if you are using the Designer, it will use the time zone of the server where the Operations Console is running; if you are using the Java API, it will use the time zone of your development workstation.

Because the time zone is specified directly on the trigger, and is either set or automatically detected at development time, the trigger may not fire according to the engine's time zone. If you want to ensure that the trigger will execute on the engine's time zone, take care to specify a matching time zone on the trigger when designing your workflows.

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 ("GMT+05:30") instead of the proper form ("Asia/Calcutta"). In this case, any daylight savings time information is lost. In some areas of the world (such as India) where daylight savings is not observed, this will not impact the trigger's expected schedule.

If you use a custom time zone, its ID must match the generic time zone format (such as "GMT+05:30") to be stored in Flux. 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).

Even if a Timer Trigger has a Time Zone set (different than the Time Zone the engine is in), all forecasts will be shown in the engine's Time Zone. Flux calculates the time different between the trigger's TZ and the engine's TZ and then prints out the schedule in the engine's local time.

If you'd like to display the schedule in another Time Zone (other than the one the engine is in), you can follow the steps provided in: Convert date and time between timezones.

 

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 VariableFieldJava TypeDescriptionPrescript / Postscript Example
RESULTresultboolean

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.

One-shot

To schedule a one-shot timer, set the 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:

  1. A count set on the trigger that 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.
  2. 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.
  3. 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.

Daylight Saving Time (DST) Considerations

Timer triggers using cron-style time expressions behave in the following manner when encountering a Daylight Saving Time switch. None of the following applies to relative time expressions.

  • In the spring (when time "springs forward"), any trigger set to fire between and including 2 AM to 2:59:59 AM will be skipped since the interval from 2 AM to 2:59:59 AM does not exist during the DST change.
  • In the fall (when time "falls backward"), any trigger set to fire at 2 AM will fire at the 2 AM after the DST change has occurred. It will not fire twice - i.e., the trigger does NOT FIRE at the 2 AM that would have occurred before the DST change and again at the 2 AM that occurs after falling back to 1 AM and again progressing to 2 AM).

Additional Questions and Answers:

1)  During the spring DST change when 2am becomes 3am, how does a timer trigger interact with the "late time window" and "makeup firing"? Does Flux think that 3:00am was more than an hour after 1:59am, and so if the late time window were 90 minutes or makeup firing were enabled, a trigger scheduled at 2:01am would run at or shortly after the "new" 3:00am.

Answer) No. When Flux fires a timer trigger, Flux then looks forward in time to schedule the next firing. Because of the DST spring ahead, the time interval on the DST date 2:00:00 AM to 2:59:59 does not exist - so when Flux schedules a job ( using 0 0 1 2 as the time expression) to run at 2:01 AM on the DST date, it actually schedules the job to run on DST date + 1 day 2:01 AM. Since a timer trigger can never fire at 2:01 AM, it can not late fire either. Setting a late time window or makeup firing will have no impact in this case.

2) During the fall DST change, will triggers scheduled to fire between 01:00 and 01:59 trigger twice. Will the 1 o'clock hour be repeated?

Answer) No. After a timer trigger fires, Flux then schedules the trigger for its next firing. Flux always schedules into the future. So a trigger set to fire at say 1:15 AM and 1:30 AM - once fired - would reschedule for the next day at 1:15 and 1:30. The 1:15 and 1:30 firings would not be repeated during a DST fallback.
3) What is the time expression for the second before the DST change in the U.S.?
Answer) For the spring change it is 0 0 59 1 8-14 MAR 1 * * * *. For the fall change it is 0 0 59 1 1-7 Nov 1 * * * *

 

 

 

  • No labels