Whitebeam Template Reference Documentation

Site Map
 
Home
 
Application Guide
Reference
  Installation
  Configuration
  XML Markup
  JavaScript Classes
  ROM
  Templates
  Environment
  Dev Process
  Tools
  External Links
  Example libraries
Community
Contact Whitebeam
To-Do
Download
Credits
Licence
Whitebeam Users
 
 
 

Whitebeam Template Reference Documentation

Schedule Template

action.listenFor()

Listen for specific triggers

Syntax

number = rb.schedule.action.listenFor(actionID, trigger, listen, when)

Parameters

The 'action.listenFor' method takes 4 parameters:

Name Type/Value Range/Length Description
actionIDnumber  Required. The ID of the action class which is listening
triggerstring  Required. The unique name of the trigger for which we're listening
listenbool  Optional, default = 1
If set to true we want to listen for these triggers. If false then delete the listener.
whenstring  Optional, default = ANY

Specifies the conditions that must be met before this trigger will be received by an event. This is currently defined as a set of integers, separated by ','. Each integer references a value of 'state' property of matching events. The following special cases are allowed:

  • 'exist' - only accept this trigger for existing schedule events
  • '!exist' - invoke if there is not existing schedule for the triggers contact ID
  • 'any' - always invoke regardless of state or existence of the event

If no numeric values are specified then no match against state is made.

Example: exist,1,2,5


Results

The 'action.listenFor' method returns number:

Type/Value Range/Length Description
number   1 if the listener is created; 0 if it already exists and -1 if the action ID doesn't exist

Remarks

This method allows an application/module to register to listen for specific 'triggers'. A 'trigger' is a simple text name - up to 30 characters. It is recommended that application agree a naming convention that allows triggers to be scoped to a specific component - eg 'email/click'

The listen request is tied to an action ID. The action however is effectively used as a template for 'events'. Events are (optionally) linked to specified actions and to a specific contact ID.

When one part of an application causes a 'trigger' (by calling rb.schedule.action.trigger) it specifies a contact ID. The template will look at all actions that have registered a listener for that named trigger. For all those actions it will look for all existing events using that action with the triggered contact ID.

If an event exists for that contact ID the 'state' of the event is compared with the states listed in the listen request. If the state matches the action URL will be called.

If no event of the specified action exists linked with the triggered contact ID and the 'when' field includes '!exist' then the action URL will be invoked anyway but with no event ID

The when parameter is a string comprising a comma separated list of values. These values are either interers or one of a list of 'tokens'. Integer values are matched against the events 'state' attribute. Valid tokens are as follows:

  • exist - call the action URL where events exist with the specific contact ID
  • !exist - call the action URL where no event exists with the specific contact ID
  • any - The equivalent of 'exist,!exist'

Listening using wild-card triggers

The trigger name specified in this call can include standard SQL wild-card characters '_' and '%'. These allow an application (with suitable naming conventions) to listen to classes of trigger or to allow trigger names to append ancillary information to the event being triggered.

Action URL and triggers

When the template determines that an action URL needs to be invoked for a specific trigger it and the URL is to have paramters appended, which is the default, the URL will be qualified with the following query parameters:

  • wbsched-id - the ID of the event record against which this trigger is being dispatched. If the listener has '!exist' in the when attribute and no event exists for the triggered contact ID then this parameter will have the value '0' (zero)
  • wbsched-logid - if logging is enabled for this action/event combination then this is the ID of the log object that's been created
  • wbsched-trig - the text name of the trigger
  • wbsched-trigID - the unique ID of this specific occurance of a trigger. Some applications may register ancillary information that qualifies this trigger in which case the recipient may retrieve that data from the template using rb.schedule.action.triggerData and passing this ID. The trigger record is transient and only exists for the duration of the URL call.

Whitebeam release 1.3.36
(loadtime : 114ms)