'Schedule' Template Overview

Introduction

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.

Events

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).
• customData - a JavaScript object that can contain application specific information for this event.

Actions

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.

Logging

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 completing properly.

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.