Scheduled events allow you to raise an event at a point in time or on a recurring schedule. Scheduled events function like a raised event with a few restrictions.
- you may only schedule an event for the current ruleset
- events are scheduled for the current entity
- all scheduled events raise events through the Sky Event API
- event granularity resolves to the minute. For single events, the ISO8601 DateTime format allows you to specify seconds, but will not be guaranteed by the scheduler
- the scheduler operates on UTC
Methods to list, delete and get the history of scheduled events are available through the Event module
There are two types of scheduled events
- single occurances
One time events
As with raised events, <domain> is limited to these pre-defined values
The name or type of the event <eventtype> can be any KRL <expr> that evaluates to a string
Because the event type is an expression, you should use a string for fixed event names rather than using a bare word. A bare word will be treated as a string for reasons of backward compatibility unless it is previously defined (i.e. in a rule prelude) in which case it evaluated and its value will be used as the event type. Save yourself the grief of accidentally having a bare word evaluated and use a string.
<ISO8601 DateTime> can be a string in the format of "2015-07-01T13:50:05Z" or a KRL <expr> that evaluates to the ISO8601 format. The default behavior for methods and functions in the time module is to return ISO8601 so this is a valid expression for scheduling a notification event in 5 minutes
There are 2 components to this time expression: time:now() selects the current time; time:add() takes the current time and calculates the time in 5 minutes. By using the native time module expressions, you can avoid some of the headache of converting between localtime and UTC
<modifier_clause> uses the familiar KRL modifier syntax
attributes is an alternative to the modifier clause that allows you to pass a map to the raised event
setting(<var>) clause stores the identifier for this scheduled event in the
<var>. Note that
<var> is a variable for the current rule and goes out of scope when the rule terminates, so it must be used inside the postlude where the scheduled event is created.
The format is the same as for single events; however the keyword repeat (instead of at) requires <timespec> to be a CRON style string. CRON specifies a string of 5 fields which help define a repeating event. CRON fields are (in order) minute, hour, day of month, month, day of week. More info on CRON and the the timespec format
Notice that there is no field for year. Recurring events operate on a yearly cycle. If you want to schedule an event to be raised every 16 months, calculate the next few occurances and schedule several single events
A '*' in a field will match any value
Complex expressions can be defined with a <timespec>. The extent of the CRON format is beyond the scope of this article, but some examples of recurring events that can be expressed through a cron <timespec> are