Interaction Designer: Queue Listener
Overview
![](../__attachments/3904943434/att_1_for_3869147232.png?inst-v=c3007bf4-8f91-43d3-9633-90859273c945)
A queue listener allows you to monitor a “listener queue” for the arrival of data. Data arrives in the form of JSON packages—placed on the queue either by an external system, or at submission of a web form.
Downstream queue activities can then use this data to execute offers. You might typically use a queue listener for the sending of an email e.g. after a customer makes a purchase, or when a web form is submitted in a landing page.
A validation error raised if a queue listener workflow contains two or more queue activities that use different audience definitions.
Mini toolbar
The following options are available in the mini toolbar when you select a queue listener:
Activate: this button is shown when a queue listener is Inactive or Deactivated, and when there are no unsaved changes in its workflow. Invocation places the queue listener into an Activated state (via an intermediate Waiting for Trigger state).
Deactivate: this button is shown when a queue listener is Activated. Invocation places the queue listener into a Deactivated state.
Rollback: this button is shown when a queue listener has been Deactivated in Production mode. Invocation removes any offer history records associated with its execution.
View results: displays the Results Window.
Show configuration panel: shows the configuration panel.
Configuration panel
A queue listener’s configuration panel contains a single General tab. It contains the following:
![](../__attachments/3904943434/att_4_for_3869147232.png?inst-v=c3007bf4-8f91-43d3-9633-90859273c945)
Listener section
Listener key: a read-only GUID value that is unique to the current queue listener. The queue listener's Listener key is used when placing messages onto the listener queue; messages that contain a unique Listener key value are processed by the queue listener matching the supplied value.
Listener Key Alias: this editable text property accepts a maximum of 100 characters. It allows you to pass a “TriggerAlias” parameter to the queue listener which overrides use of its trigger key. If you activate a queue listener having specified a Listener Key Alias that is in use in another active queue listener, an error is thrown.
Usage information: a button is provided which, when selected, copies details of how external parties can place messages on the listener queue for processing by queue listeners:
There are three ways for external systems to integrate with this queue listener.
Via the Interaction API web service
Via the Interaction Realtime API web service
By placing messages directly onto the queue
Interaction API web service
Endpoint: https://local.rphelios.net/interaction/api/triggers/queue
NB. The message header must contain a valid bearer token.
Interaction Realtime API web service
Endpoint: https://local.rphelios.net:5511/api/events/queue
NB. The message header must contain the RPIAuthKey setting configured for this service.
Direct to queue
The queue type and path are configured in the Execution Service app settings
MESSAGE BODY
{"TriggerKey":"4b2e3496-50de-47a8-a779-ea9192a86ffd","SendAddress":"e.g. email address","Parameters":{"Subscriber Key":"x"}}
MESSAGE BODY
{"TriggerAlias":"","SendAddress":"e.g. email address","Parameters":{"Subscriber Key":"x"}}
If system configuration setting RealtimeAPIAddress is not configured, the copied text is as follows:
There are two ways for external systems to integrate with this queue listener.
Via the Interaction API web service
By placing messages directly onto the queue
Interaction API web service
Endpoint: https://local.rphelios.net/interaction/api/triggers/queue
NB. The message header must contain a valid bearer token.
Direct to queue
The queue type and path are configured in the Execution Service app settings.
MESSAGE BODY
{"TriggerKey":"1621df9d-48af-41dd-a66b-52132b086267","SendAddress":"e.g. email address","Parameters":{"Subscriber Key":"x"}}
MESSAGE BODY
{"TriggerAlias":"","SendAddress":"e.g. email address","Parameters":{"Subscriber Key":"x"}}
If the queue listener’s associated queue activity’s audience definition is configured to support queue listener repeater parameters, the Message Body section appears as follows:
{'TriggerKey':'95f401e4-76ae-4db4-9cb8-2f21ff020db5','SendAddress':'e.g. email address','Parameters':{'EmailAddress':'NOT SET','FirstName':'NOT SET','LastName':'NOT SET'},'RepeaterParameters':[{'OrderTitle':'NOT SET','ParamProductName':'NOT SET','ParamProductValue':'1','ParamProductDate':'7/6/2016 12:00:00 AM','ParamDateOnly':'3/30/2017 12:00:00 AM','ParamMoney':'5.00','ParamDecimal':'7.77'}]}
Realtime Event section
![](../__attachments/3904943434/att_3_for_3869147232.png?inst-v=c3007bf4-8f91-43d3-9633-90859273c945)
Listen for Realtime events: this checkbox is unchecked by default. When checked, the properties below it are shown.
Web events adapter: this mandatory property allows you to select a web events adapter to provide Realtime event data to which the queue listener will respond. A dropdown, it lists all configured web events adapters. The default web tracker is selected by default.
Event: this mandatory property allows you to select a fulfillment state representing an event to which the queue listener will respond. It is available when a Web events adapter has been selected. Selecting the button displays the Choose Event dialog. All states made available by the selected Web events adapter are listed. You can select a state to select it in the dialog, or double-click it to select it and close the dialog. Selecting the Close button removes the dialog from display (selecting off the dialog has the same effect). Having selected an Event, you can clear it using the button provided.
Event detail: this optional property allows you to apply a filter to the event—e.g. a Page Visit page name or Link Click URL. It supports a maximum length of 2000 characters. Partial matches can be used.
Event Metadata: this optional property allows you to apply an additional filter, on the metadata accompanying the event. All specified event metadata must be received for the queue listener to be fired.
A list of event metadata Name/Value pairs can be specified. Names must be unique within the list, and both Name and Value are mandatory. An Add New Event Metadata button, displayed below the list, allows you to add a new entry. Its default name is “New event metadata” (if this name already exists, and incrementing integer can be appended to ensure uniqueness), and its default value is blank.
Realtime queue profile: this optional property allows you to select a
QueueListenerConfiguration
name (as defined at RPI Realtime's appsettings file), which defines the parameters to be sent to the queue listener. The default configuration is used if the property is not set. A dropdown property, values are sourced from appsettings. If provided manually, a maximum length of 100 characters can be accommodated.
An example of a QueueListenerConfiguration
entry is provided below:
"QueueListenerConfiguration": [
{
"Name": "Cart",
"SendAddressParameter": "EmailAddress",
"Parameters": [
"FirstName",
"LastName
],
"RepeaterParameters": [
"CartItem",
"CartItemPrice"
]
}
Note that SendAddressParameter
and Parameters are sourced from a visitor's Realtime profile.
Note also the presence of RepeaterParameters
above; these can be used to include transactional details in an email delivered on Realtime triggering of the queue via a smart asset configured with a listener key, or via a queue listener configured to respond to Realtime events. Repeater parameters are sourced from array values persisted in profile parameters, or from a cached attribute list lookup.
Note that the number of array elements present in each repeater parameter must match the data received in that context.
Prevent repeat sends for: this optional property allows you to specify a time period within which repeat sends to same recipient from the current queue listener will be disregarded.
Cached Attribute List section
![](../__attachments/3904943434/att_2_for_3869147232.png?inst-v=c3007bf4-8f91-43d3-9633-90859273c945)
Use cached attribute list: this checkbox is unchecked by default. It is unavailable if no cached attribute lists (CALs) have been defined in the current RPI installation. When checked, the Cached attribute property is displayed.
Cached attribute list: this dropdown lists all existing attribute-based CALs alphabetically. On receipt of a queue message when a CAL has been selected, if a queue message contains the CAL's lookup key, all attributes configured in the CAL are made available for use in outbound personalization.
Note that it is not possible to specify trigger constaints in the context of a queue listener.