The schedule template
provides a framework for scheduling and calendaring. It's primary aim is to provide support for automatically scheduling operations within
a web application. Prior to the schedule template scheduling was usually achieved through an adhoc combination of tools such as cron and wget.
With release 1.3.16 of Whitebeam the applicability of the schedular has been extended beyond the initial release that dealt with
time based scheduling to support message queue based 'triggers' and 'listeners'. These enhancements allow applications to decouple
significant portions of code from one-another.
The template operates around the following concepts:
- An event, which can be considered as
a state-machine that's waiting for triggers to occur. Originally an 'event' state machine was waiting for simply waiting for timer events
and defined a start point, end point and period in time. Version 1.3.16 extends this concept to allow events to listen for generic triggers. A
'trugger' can be the occurance of a period timers or the result of something happening in another area of an application.
- An action which defines what to do when an event occurs. With
1.3.16 the 'action' is used to define for which triggers each associated event should be listening.
Each event can be configured to cause an action to occur when the event is due. Alternatively some applications (for example a users calendar)
could store events which have no programmed actions.
Many events can share the same action definition. Each event can be associated with at most one action.
The Schedule template manages a set of events. Each event has a unque identifier. An event is a point in time that may repeat. The schedule
template allows these points to be defined with the following parameters:
- A start and end date/time. This forms a window within which the event can occur. The first occurrance of an event is at the start of this
window. If an event it to happen exactly once then the start and end of the window will be the same.
- A repeat 'period' which is specified as an interval and represented as a string. The interval is specified as a number and a unit,
potentially repeated several times. For example "1 month 2 days" is a valid period.
For calendaring applications each event can also have a specified 'duration' which is specified using the same interval format as the 'period'.
For example an event could describe an annual festival which could have a '1 year' period and a '3 day' duration.
Although actions are only associated with the start of an event the 'duration' allows complex calendar querries to be requested. For example
if an event is schedule for the 30th April and lasts 5 days then a query for "all events that occur in May" would include
this event because it finishes within May.
A number of application specific fields are provided that can be used to query and filter events returned in iterators:
- type - as with other templates this allows different modules within an application to create their own namespace for the
events they user.
- state - some applications may schedule an event to occur multiple times with slightly different behaviour each time. For
example an initial state where a welcome message is sent followed by a second occurrance of the event that causes a reminder.
- contactID - The unique ID of a contact (from the contact template).
Triggers occur against specific contacts (see below).
Each event can be associated with at most one action. In simple terms an action is a URL that the schedule template will request when a trigger
occurs. Many events can share the same action definition and store state specific information in the event record. The intended use is that actions
contain definitions of work-flows or state machines to be driven by triggers. The 'events' are instances of those state machines and store the
individual 'current state'.
For example consider an application that sends a series of emails to new members when they join a site, each email containing information on
a different subject. The 'action' defines the sequence of emails to send - it's meta-data contains the blueprint for the state machine.
As each member joins the site a new 'event' record is created for that user and the current 'state' stored in the events record. The
URL that is triggered can read both the current state of the event and the action definition and send he correct email before moving the
event to the next state.
Listening for 'triggers'
Actions can 'listen for' trigger. A trigger can be fired by any component in an application simply by calling
rb.schedule.action.trigger. Triggers are
identified by a name, for example a CRM system might trigger "crm/newcontact" whenever a new contact record is created
allowing, for example, a new sequence of introductory emails to be sequenced for that contact.
A trigger comprises two parts: the name of the trigger as specified above) and a specific contact ID. The trigger will be applied
to any events that are listening for the named trigger and that also are linked to that specific contact ID.
There are many situations in which it's useful to use a 'trigger' to bootstrap a specific sequence of events for a contact - the
example above of introductory emails is a good example. In this case the listening action can be asked to be triggered even if there
is no event with the specified contact ID. The action URL is still invoked but with no contact. The code in the target
page can then create the event code.
Actions taken when events occur are in effect web page reads. It can be very difficult to debug issues in these pages because they are invoked
automatically. To help with debugging the schedule template includes a logging facility. Logging can be switched on either at the
action level, in which case all events that use a specific action are logged, or at the event level, so that only actions triggered by a specific
event are logged.
There are two logging controls:
- basic - stores information about the date/time when the event occurred along with the HTTP status code returned
- body log - returns the 'body' from the HTTP request. This is useful where a page is creating an error and not
When logging is enabled a log entry is created before the HTTP request is made. The request will usually then receive the ID of the
log entry as a get parameter (called wbsched-logid). The page itself can then store debug information into the log record.