Timer Events
Timer Events
Timers are currently supported on the following event objects:
- Timer Start Event - Timer controls when the process starts.
- Timer Intermediate Catch Event - the timer delays the process flow and controls when the process moves on to the next event.
- Timer Boundary Events - both interrupting and non-interrupting timer boundary events can be set on tasks, userTask, and subProcess objects to implement reminder, timeout, and period closing processes. Non-interrupting timer boundary events can fire repetitively to create repeating reminders.
Timer details are specified in the Flow Modeler properties panel. Timers can be specified in ISO 8601 format or in Oracle date and interval formats. Details of the syntax and substitutions allowed are shown here.
Note that the Timer system uses the Oracle database Scheduler (DBMS_SCHEDULER). Flows for APEX requires a scheduler program and job to be created and operating. See the timer administration documentation. for more details.
Timer Start Event
The Timer Start Event allows a process start to be delayed so that it occurs at a particular date & time, after a delay, or on a regular scheduled basis.
If you want to start a regular, repeating start event โ for example, a process that runs every week to generate a sales report โ you should use APEX automations to create a regular event, and have the Automation start a process instance by calling flow_api_pkg.create_process()
.
Timer Intermediate Events
Standalone Timer Intermediate Catch Event
A Timer Intermediate Catch Event will cause the sequence flow to wait until the timer fires, thus causing a delay to the sequence flow.
Timer Boundary Event - Interrupting
These can be set on a task, a userTask, a manualTask, or a subProcess (TODO - Call Activity??)
Behaviour. When the underlying object becomes the current task, a timer is started. If the object is still the current object when the timer fires (because it has not yet completed), the underlying task is terminated, and the timer boundary event becomes the current object. It performs a task_complete on the boundary event, moving the process on to the next step.
Use Cases These are used to perform a business process timeout โ the usual forward path is suspended, and replaced by the timeout process path. This can also be used to implement a period closure, when for example a submission period or a review period has completed.
Only one interrupting timer can be set on each object. (TODO - is this still correct?)
In the example below, task C has an attached interrupting timer:
- If task C completes before the timer fires, the timer event is removed.
- If the timer fires before C has completed, processing switches from the normal path and instead continues with
C Timeout
as the next task.
Timer Boundary Events - Non Interrupting
These can be set on a task, a userTask, a manualTask, or a subProcess. (TODO - Call activity?)
Behaviour. When this object becomes the current task, a timer is started. If the object is still the current object when the timer fires because it has not yet been completed, the underlying task continues, and a new subflow starts to operate in parallel to execute the โreminderโ path. The new โreminder pathโ performs a task_complete on the boundary event, moving the process on to the first task on that path.
Use Cases. Non-Interrupting Timer Boundary Events are used to implement reminder processes, or to start time-delayed parallel process paths. If the underlying task completes before the timer fires, the โreminder pathโ timer and associated subflow are deleted.
Repeats. Non-Interrupting Timer Boundary Events can fire once or can repeat, a specified number of repetitions / cycles, or indefinitely.
Multiple Events. Multiple non-interrupting timer events can be set on a single task, userTask, manualTask, or subProcess.
In the example above, task A has one non-interrupting boundary timer attached to it. If task A is not completed in the given 20 seconds, the timer fires - which starts task โA Reminderโ on a parallel subflow to the main subflow.
Configuring Timers - Specifying the Time, Delay, and Repeat Cycles
Timer events can be defined to fire at a specific time (date) or after a specified delay (period).
Dates and delay periods can be specified in either ISO 8601 format or Oracle format.
Timers can be defined
definitions can be specified in the properties panel as a literal value, or can be specified using a process variable substitution. Timers can be specified using ISO 8601 syntax, or using more familiar Oracle syntax.
Under Timer, select the type of timer you want. There are separate options for ISO 8601 and Oracle format Date and Interval specifications.
In addition, Flows for APEX Process Variables can also be used as substitution parameters so that you can use a Process Variable to define a Timer syntax component. Valid substitutions and the required format and typing are listed below.
ISO Syntax
Under Timer Definition, use the ISO 8601 format for the required time or interval, as below. A good overview to ISO 8601 date/time format strings can be found on Wikipedia. (click here)
ISO 8601 Date
Specify a specific date and time for the process to start. Date/Time components are listed from broader to more specific, with date components separated by dash (โ-โ) characters, time components separated by colon (โ:โ) characters, and an upper-case โTโ character separating the date from the time components. All components used must be zero-padded.
If only a Time component is provided, the event will be scheduled for the next time the specified time occurs. So, for example, if the given string was T14:00
, and the current time was 09:00, the event would be scheduled for 14:00 (2PM) today; if the time is after 14:00, the event will be scheduled for 14:00 (2PM) tomorrow.
- Some examples:
2007-04-05T14:30
2021-11-23T07:15:23
T14:30:15 represents the next occurring 14:00:15 today or tomorrow.
-
Allowed Substitutions: ISO Dates can be substituted with Flows for APEX Process Variables using the
&F4A$proc_var_name.
substitution syntax as follows:- Date-typed Process Variable. The date-typed process variable must contain the date/time that the event should fire.
- Varchar2-typed Process Variable. The varchar2-typed process variable must contain a valid Oracle-date using a format mask of
YYYY-MM-DD HH24:MI:SS
. The Time zone used will be that of the database server.
ISO 8601 Duration / Period
Specifies a delay from the current time or the process to start, using an ISO 8601 duration string. This always starts with an upper-case โPโ.
- Some examples:
P3Y6M4DT12H30M5S" represents a duration of three years, six months, four days,
twelve hours, thirty minutes, and five seconds.
P3M represents 3 months. (without the T)
PT3M represents 3 minutes. (with the T)
PT5M represents 5 minutes.
PT30S represents 30 seconds.
-
Allowed Substitutions: ISO Durations can be substituted with Flows for APEX Process Variables using the
&F4A$proc_var_name.
substitution syntax as follows:- Varchar2-typed Process Variable. The varchar2-typed process variable must contain a valid ISO 8601 Duration / Period using a format mask of
P(yyY)(mmM)(ddD)T(hhH)(mmM)(ssS)
. Each bracketed component is optional.
- Varchar2-typed Process Variable. The varchar2-typed process variable must contain a valid ISO 8601 Duration / Period using a format mask of
ISO 8601 Repeating Duration / Cycle Timers
Specifies the date/time for an initial run and then defined intervals for repetition. Repeating timers are supported in Flows for APEX from v22.1 onwards. The Repeating Period uses a Repeat Specification followed by the Period Specification, above.
The Repeat Specification is of the form Rnn/
where R is an upper-case โRโ character to denote a โRepeatโ, โnnโ is the number of times the timer should fire, and the slash character (โ/โ) is the separator between the Repeat specification and the Period specification. If โnnโ is omitted or equals โ-1โ, the timer will fire continuously until cancelled. The โTโ character is still required to separate date components from time components.
- Some examples:
R5/P5D represents 5 events, starting in 5 Days and repeating every 5 days.
R10/PT1H20M represents 10 events, starting in 80 minutes and repeating every 80 minutes.
R/PT20S represents an unlimited number of events, repeating every 20 seconds.
R-1/PT6H represents an unlimited number of events, repeating every 6 hours.
-
Allowed Substitutions: ISO Durations can be substituted with Flows for APEX Process Variables using the
&F4A$proc_var_name.
substitution syntax as follows:- Varchar2-typed Process Variable. The varchar2-typed process variable must contain a valid ISO 8601 Repeating Duration / Cycle Timer (as described above) using a format mask of
Rnn/P(yyY)(mmM)(ddD)T(hhH)(mmM)(ssS)
. Each bracketed component is optional.
- Varchar2-typed Process Variable. The varchar2-typed process variable must contain a valid ISO 8601 Repeating Duration / Cycle Timer (as described above) using a format mask of
Oracle-format Date and Interval Syntax.
From v22.1 onwards, you can also use the Oracle format Date and Interval specifications, and for Dates you can also specify the Format Mask.
For more information on Oracle date / time formats, please see the Oracle SQL Language Reference Manual.
Oracle Dates
Oracle Dates can be specified as an Oracle-format date and an associated Oracle date format mask.
-
Allowed Substitutions: Oracle Dates can be substituted with Flows for APEX Process Variables using the
&F4A$proc_var_name.
substitution syntax as follows:- Date-typed Process Variable. The date-typed process variable must contain the date/time that the event should fire.
- Varchar2-typed Process Variable. The varchar2-typed process variable must contain a valid Oracle-date using a format mask of
YYYY-MM-DD HH24:MI:SS
. The Time zone used will be that of the database server.
Oracle Duration
Oracle Durations are specified with two separate components - a Years-Months Interval and a Days-Seconds Interval. Both must be supplied as a varchar2 string in the required format. The Timer duration is the sum of both components.
- Interval Years to Months: The Interval Years-to-Months component must be supplied in format
YY-MM
. - Interval Days(3) to Seconds: The Interval Days-to-Seconds must be supplied in the format
DDD HH24:MI:SS
. -
Allowed Substitutions: Each component of an Oracle Duration can optionally be substituted with a Flows for APEX Process Variables using the
&F4A$proc_var_name.
substitution syntax as follows:- For the Interval YM Component: A varchar2-typed Process Variable containing a valid Oracle Interval YM using a format mask of
YY-MM
. - For the Interval DS Component: A varchar2-typed Process Variable containing a valid Oracle Interval DS using a format mask of
DDD HH24:MI:SS
.
- For the Interval YM Component: A varchar2-typed Process Variable containing a valid Oracle Interval YM using a format mask of
Oracle Cycle Timer
Oracle Cycle Timers are specified as three separate components:
- Interval to First Firing: The Interval Days(3)-to-Seconds must be supplied in the format
DDD HH24:MI:SS
. - Interval between Repeat Firings: The Interval Days-to-Seconds must be supplied in the format
DDD HH24:MI:SS
. - Maximum Number of Runs: The maximum number of times the timer will fire, in format
nnn
. If omitted, the timer will continue to fire until cancelled. -
Allowed Substitutions: Each component of an Oracle Cycle can optionally be substituted with a Flows for APEX Process Variables using the
&F4A$proc_var_name.
substitution syntax as follows:- For the Interval to First Firing: A varchar2-typed Process Variable containing a valid Oracle Interval-DS using a format mask of
DDD HH24:MI:SS
. - For the Interval between Repeat Firings: A varchar2-typed Process Variable containing a valid Oracle Interval-DS using a format mask of
DDD HH24:MI:SS
. - For the Maximum Number of Runs: A varchar2-typed Process Variable containing a valid number in format
nnnn
.
- For the Interval to First Firing: A varchar2-typed Process Variable containing a valid Oracle Interval-DS using a format mask of
Manual Triggering of Timers During Development
The Flow Monitorย ยป Instance Details page includes an Action Menu item so that timers can be checked immediately. When you are testing timer functionality, or demonstrating timer capability, you can now Step Timers
and then Refresh
to step due times forward without having to wait for the database scheduler to complete its next wake up cycle. (Note that the timer wake-up time must have passed).