This site has been deprecated. Do not edit pages here. Please visit the new Pico Labs documentation.


Skip to end of metadata
Go to start of metadata

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

Scheduled Events


There are two types of scheduled events

  • single occurances
  • repeating

One time events

Single Event

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

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

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

Recurring Event

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

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

"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
Labels: