(Classic) Scheduling events in the Postlude

Engine Compatibility

The node pico-engine's implementation has some differences and is documented here: schedule

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 pico
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
repeating

One time events

Single Event

schedule <domain> event <eventtype> at <ISO8601 DateTime> [with <modifier_clause> | attributes <expr>] [setting(<var>)]

As with raised events, <domain> is limited to these pre-defined values

explicit
http
system
notification
pds
error

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

schedule notification event "remind5" at time:add(time:now(),{"minutes" : 5})

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

with <var> = <expr> [and <var> = <expr>]*

attributes is an alternative to the modifier clause that allows you to pass a map to the raised event

schedule notification event "remind5" at time:add(time:now(),{"minutes" : 5})
  attributes event:attrs()

The 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.

Recurring events

The format is the same as for single events; however the keyword repeat (instead of at) requires <timespec> to be a CRON style time specification (see below).

Recurring Event

schedule <domain> event <eventtype> repeat <timespec> [with <modifier_clause> | attributes <expr>] [setting(<var>)]

Event Idempotence

You can give recurring events a name using the attribute _name. A recurring events with a given name will only be scheduled once, enforcing idempotence.

schedule flip event scratch repeat "5 0 * * *" 
  with _name = "just_one"

Time Specifications

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 timespec format

field          allowed values
-----          --------------
minute         0-59
hour           0-23
day of month   1-31
month          1-12 (or names, see below)
day of week    0-7 (0 or 7 is Sun)

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 occurrences and schedule several single events

A '*' in a field will match any value

Minimum Scheduled Event Period

The classic pico engine enforces a minimum period for scheduled events. The default is 599 seconds and can be configured.

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

"5 0 * * *"       run five minutes after midnight, every day
"15 14 1 * *"     run at 2:15pm on the first of every month
"0 22 * * 1-5"    run at 10 pm on weekdays
"23 0-23/2 * * *" run 23 minutes after midn, 2am, 4am ..., everyday
"5 4 * * 0"     run at 5 after 4 every sunday