Handlers are a powerful extension point for the Interaction Center. They allow advanced customization beyond what is capable with the Interaction Center public APIs.
ICWS exposes an API for initiating custom handlers and subscribing to notifications sent by handlers.
Jump to a section that describes an area of the handler notification API:
Interaction Designer may be used to design custom handlers and publish them on the Interaction Center server. Interaction Designer is IC's graphical programming and application generator tool.
All custom handlers always start with an initiator as their first step, and an initiator is comprised of a set of events that start a custom handler. Custom handlers are registered with Interaction Processor, which watches for matching initiator events, and launches the proper custom handler when a match is found. From there, the handler can perform various steps, including making calls, calling web services, and sending notifications back to the appropriate clients.
For more information about Interaction Designer and custom handlers, refer to the Interaction Designer help.
To get started, open Interaction Designer and create a new handler. From the File menu, select Change Initiator. Then from the Available Initiators dialog box, choose Custom Notification and click OK. This will add a Custom Notification box onto the handler design surface.
Double-clicking on the Custom Notification box will bring up the properties for it. Set the inputs and outputs as wanted. In the example below, we will use "SwipeObjectID" and "SwipeEventId" as the Object ID and the Notification Event, respectfully. Note that the input Object ID value corresponds to the objectId property, the input Notification Event value corresponds to the eventId property, and the output Custom Notification Data value corresponds to the data property in the POST /icws/{sessionId}/system/handler-notification API.
From here, design and publish your custom handler as you wish.
The POST /icws/{sessionId}/system/handler-notification API is used to send a notification and initiate any handlers that are waiting to be initiated. For example, the client may perform a request such as:
POST /icws/{sessionId}/system/handler-notification
{
"objectId": "SwipeObjectID",
"eventId": "SwipeEventID",
"data": ["Master Card", "1234 5678 9876 5432", "01/2014", "965", "ITEMCODE:12345"]
}
If any handlers have initiators that are watching for the specified object identifier and event identifier, they will be launched by Interaction Processor.
Note: due to the nature of custom handlers, the server does not provide any guarantee that the notification is handled or results in any side-effects. There also is no direct response to sending a notification.
Sending a notification to clients from a handler is achieved by adding the Send Custom Notification step to your handler.
From Interaction Designer, add the Send Custom Notification step found under the System tab. Open the properties for the step. Set the Custom Object Identifier, Custom Event Identifier, and Custom Notification Data input values as wanted. In the example below, the "CompletePurchaseObjectID" object identifier and "CompletePurchaseEventID" event identifier are subscribed by the client. Note that the input Custom Object Identifier value corresponds to the objectId property, the input Custom Notification Identifier value corresponds to the eventId and eventIds properties, and the output Custom Notification Data value corresponds to the data property in the PUT /icws/{sessionId}/messaging/subscriptions/system/handler-sent-notifications subscription API and in the associated message when the notification is sent.
The PUT /icws/{sessionId}/messaging/subscriptions/system/handler-sent-notifications API is used to subscribe to a set of object identifier and event identifier headers that may be sent by one or more custom handlers. For example, the client may subscribe by performing a request such as:
PUT /icws/{sessionId}/messaging/subscriptions/system/handler-notifications
{
"headers": [{
"objectId": "CompletePurchaseObjectID",
"eventIds": ["CompletePurchaseEventID"]
}]
}
When a custom handler performs the Send Custom Notification step with the appropriate object identifier and event identifier pair, the server will issue a message such as:
{
"__type": "urn:inin.com:system:handlerSentNotificationMessage",
"isDelta": false,
"objectId": "CompletePurchaseObjectID",
"eventId": "CompletePurchaseEventID",
"data": ["AUTHCODE:asd5gzftsadsf8493dafs5kl436y", "ITEMPRICE:9.99"]
}
The client then can handle the message as wanted.