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 | actionID | number | | Required. The ID of the action class which is listening | trigger | string | | Required. The unique name of the trigger for which we're listening | listen | bool | | Optional, default = 1 If set to true we want to listen for these triggers. If false then delete the listener. | when | string | | 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 triggersThe 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 triggersWhen 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.
|