Resource Enumeration API
The SDMP protocol is a full-duplex protocol for exchange of tokenised text messages over a TCP socket connection. Its primary use is as a transport for line-of-business services inside the contact center to “plug in” to Softdial CallGem™ to make a complete contact center solution. As Softdial CallGem™ has evolved, a family of enumeration messages was developed to enable third-party services to get a real-time view of the state of the contact center and subscribe to a stream of events.
These messages form the bulk of Softdial CallGem™’s management API; they are multi-purpose, providing the following types of functionality to third parties:
- Subscribe for a digest of state of a class of resources (sessions, agents, queues, campaigns, tenants etc). After the digest is delivered, deliver state change deltas until the subscription ends.
- Subscribe for a set of state change events (possibly from a given start time).
- For services that are not long running, or need to work in challenging network/ load environments, resubscribe to reconnect to an existing subscription that has become dormant because of client connection failure.
- Filter subscriptions based on scope (for example agent state subscriptions can be filtered by tenant or campaign)
Softdial CallGem™ can support multiple connections to external control applications.
Sytel encourages all partners using a socket interface to use SDMP 2.0 conventions for messaging.
This topic uses 2 character message codes as per SDMP 1.0 for the sake of brevity. All publish-subscribe messages form part of Softdial CallGem™’s management interface, so where you might see a message code (EA) the full message code (CG:MA:EA) is implied.
Enumeration messages - standard pattern
Each enumeration message has an ‘event data’ response. The standard pattern is that when Softdial CallGem™ receives an enumeration request message, it will respond with an enumeration data message which contains a set of messages that reflect the current state of the enumerated resource within the selection criteria set in the enumeration request message.
So for example, in the case of an Enumerate Agents [EA] message, every time an agent’s state changes within the specified selection criteria, an Agent Data [AZ] message will be sent to provide updated state information.
An enumerate transaction is terminated either by sending an Enumerate End [EE] message or by breaking the socket connection that sent the enumerate request message (although this may not be desirable).
The standard parameter pattern for enumeration messages is:
E?\TX<transaction tag>[\TD<tenant>][<selection criteria params>
- <transaction tag> - a unique identifier. Best practice for traceability and avoiding name clashes is to use some short application tag concatenated with a UUID as the transaction tag.
- \TD<tenant> - optional, and if specified restricts scope to a specific tenant. If the Tenant (TD) parameter is omitted the scope is all tenants.
Enumeration messages - description
Not all of the subscriber messages work in the same way. There is a fairly consistent pattern but one size does not fit all. Some of the messages have evolved to meet specific application needs.
The following messages deliver an initial digest of resources (and their current states):
| Request | Response | Description |
|---|---|---|
| Enumerate Agents [EA] | Agent Data [AZ] | It is possible to request varying levels of detail on agent state using the Level of Detail (LD) parameter. When this parameter is included, the Agent Data [AZ] response will include a Detail State (DS) parameter. The default level of detail (1) gives logged in/ acd available / logged out state. For more detailed state information specify Level of Detail (LD) of 2 or 3. An enumeration example showing usage of the Level of Detail (LD) parameter is given in the Dialer Chat tutorial page. You may filter the request by Campaign Name (CN). |
| Enumerate Campaigns [EC] | Campaign Data [CZ] | Provides campaign state information |
| Enumerate Campaign Properties [EP] | Property Data [PD] | Provides campaign property information |
| Enumerate Groups [EG] | Group Data [GZ] | Reports changes in queue state, including session enqueue and dequeue. Can be filtered by specifying the Campaign Name (CN) and Queue Address (GA) parameters in the request. |
| Enumerate Tenants [E1] | TenantData [Z1] | The Tenant (TD) parameter should not be sent with this message. The TenantData [Z1] messages return tenant state. A tenant state may be decommissioned, commissioning, active or decommissioning. |
| Enumerate Switches [ES] | Switch Data [SZ] | Reports presence/ absence of telephony resources and number of trunks/ ports each telephony resource supports. |
Table 1
After an initial feed of current resource states, the transaction then delivers events for changes to state of one of these resources. These queries are useful for clients needing to get a snapshot of resources for directory-type services:
| Request | Response | Description |
|---|---|---|
| Enumerate Notifications [EN] | Notify Event [NE] | Can be filtered by specifying the Facility (FA) and Severity (SE) parameters in the request. The Timestamp (TS) parameter allows event history to be sent. |
| Enumerate Sessions [EI] | Session Data [IZ] | A Session Data [IZ] message is sent for completed call sessions. It contains various session data parameters including timestamps of all of the major call events, the agent that dispositioned the call and outcome information. Sessions can be filtered by specifying the Campaign Name (CN) parameter in the request. |
| Enumerate Metrics [EM] | Queue Metrics [MZ] | Allows an application to query queue metrics periodically based on an Interval (TV) parameter and a moving Time Window (TW) parameter over which the metrics are collated. The Queue Metrics [MZ] message is sent at intervals defined in the Interval (TV) parameter. |
| Enumerate Outcomes [EO] | Outcome Data [OZ] | Outcome Data [OZ] is sent for completed call sessions. The data may be filtered by specifying the Campaign Name (CN), Connected Outcomes (SO) and Failure Outcomes (FO) parameters in the request message. |
| Enumerate Queue [EQ] | Queue Data [QZ] | Reports information on call activity on an Inbound queue or set of Inbound queues. |
| Enumerate Telephony [ET] | Telephony Message [TE] | Allows a third party application to interrogate the stream of telephony events. The request message must specify which events should be reported by specifying the Call Initiate (CI), Line Connected (LC), Call Disconnect (CD), Now Disconnected (ND) and Recording Acknowledge (RA) parameters |
| Enumerate Transfer Activity [EX] | TransferData [XZ] | Allows a third party to get detail of state change events relating to call transfers. Transfers go through Offering and Conferencing states before completing (or being rejected). The TransferData [XZ] messages provide timing for all of these events |
Table 2
These messages generally report resource state change events as and when they occur, with a couple of exceptions. The Enumerate Sessions [EI] and Enumerate Notifications [EN] allow a ‘start time’ to be set with the Timestamp (TS) parameter, enabling historical notifications to be retrieved for up to 1 hour in the past.
The New Persistent ID [WP] message informs the controlling application of a new instance of a Persistent ID passed in a preceding enumeration request. This allows the application to establish if the enumeration request was made by a previous instance of the application.
Message flow example
In order to maximise speed and minimise bandwidth usage, these queries work as a set of transactions, as in the following examples:
- The control application sends a query to Softdial CallGem™ requesting either a list of resources, e.g. agents currently logged in to a campaign (Enumerate Agents [EA]), running campaigns, (Enumerate Campaigns [EC]), available switches (Enumerate Switches [ES]).
- Softdial CallGem™ provides the current state information for each agent (Agent Data [AZ]), campaign ( Campaign Data [CZ]) or switch (Switch Data [SZ]) in separate transactions.
- Softdial CallGem™ provides any changes in state information (e.g. Agent Data [AZ], Campaign Data [CZ] or Switch Data [SZ]) in separate transactions.
- The Control App terminates the query (Enumerate End [EE]).
- Softdial CallGem™ confirms the termination (Enumerate Finished [EF]).
This method ensures that the information provided to the control application is always up-to-date and minimises bandwidth use.
SDMP example
A typical session between a control application and Softdial CallGem™ to monitor Agent state is shown below. Tenant Descriptor (TD) parameters have been omitted for clarity:
| Time | To Softdial CallGem™ | From Softdial CallGem™ | What It Means |
|---|---|---|---|
| 00:00 | EA\TX001\CNCustCare | - | 'Please send agent list for Campaign CustCare' |
| 00:00 | - | AZ\TX001\CNCustCare\ANHarry\ZA1 | |
| 00:00 | - | AZ\TX001\CNCustCare\ANLarry\ZA1 | |
| 00:00 | - | AZ\TX001\CNCustCare\ANMoe\ZA1 | Three agents (Harry, Larry and Moe) are now logged in and working |
| 00:01 | - | AZ\TX001\CNCustCare\ANLarry\ZA2 | Larry has gone on break |
| 00:02 | - | AZ\TX001\CNCustCare\ANFred\ZA2 | Fred has logged on but is not available |
| 00:02 | - | AZ\TX001\CNCustCare\ANFred\ZA1 | Fred is now available |
| 00:03 | - | AZ\TX001\CNCustCare\ANLarry\ZA0 | Larry has gone home |
| 00:04 | EE\TX001 | - | 'Please stop sending agent list' |
| 00:04 | - | EF\TX001 | Finished |
In the above example the Agent State (ZA) parameter of the Agent Data [AZ] message reflects the current login agent state.
Persistence across network/ socket interruptions
SDMP sessions are denoted by an authenticated TCP socket connection to Softdial CallGem™. In a reliable network environment not under extremes of load a socket connection will stay active as long as the application connecting to Softdial CallGem™ keeps running.
On socket disconnect or permanent write failure, Softdial CallGem™ performs housekeeping, assuming that whatever resources were ‘owned’ by the session are to be terminated, and relevant state updates propagated to the other connected applications.
This also applies to publish-subscribe requests. On connection failure, transactions originating from the closed socket connection are deemed to be complete and are cleaned up.
For digest-type requests this is not a problem; the application connects and re-issues the subscribe request, and a new digest is delivered, enabling the application to be stateless.
For ETL (Extract, Transform, Load) applications this is not ideal behaviour. An ETL service needs to gather a full set of events, sometimes in time order, in order to aggregate events into meaningful KPIs and session data.
The persist token mechanism was introduced (from 10.6.263) to try to resolve this.
By appending a Persist Token (PS) parameter to a subscribe message, Softdial CallGem™ is advised that the subscribe request is to persist beyond the lifetime of the socket connection that sent the subscribe message. In the event of a connection failure, the application can reconnect and issue a new subscribe message with the same Persist Token (PS) parameter. Softdial CallGem™ will then ‘roll forward’, delivering the messages it has cached against this persist token, before carrying on with reporting new events.
There are 3 important consequences of this behaviour:
1) Caching limits
Softdial CallGem™ will cache (subject to memory constraints) up to one hour's worth of transaction data for the persist token. Softdial CallGem™ is a real-time service running an ACD and predictive dialing engine. Both of these functions are clock-sensitive and so as a matter of policy, Softdial CallGem™ limits its I/O to socket I/O and writing log files. The logging mechanism relies on worker threads implementing message queues and performing blocking I/O to avoid interference with real-time processing.
This also means that Softdial CallGem™ cannot use file-based storage to persist subscriber data, hence the 1 hour limit. Subscriber services need to be designed to be either
- stateless and started/ stopped on demand, or
- stateful and long-running
A stateless subscriber would need to be started and run on a regular schedule, to avoid problems associated with Softdial CallGem™ aging out and discarding old subscriber events. Our advice for such a service would be to schedule it to run every 5 minutes.
If a stateful, long running service is needed it should be written to mitigate network glitches. The following pattern of behaviour is recommended:
- On start, connect to Softdial CallGem™ and resubscribe.
- Run a housekeeping timer that, every 60 seconds, sends a Verify Status [VS] message (The SDMP equivalent of a ping). If the socket send fails, close the socket and run another 60 second timer for reconnect/ resubscribe.
- If the reconnect timer handler fails to reconnect, log, raise SDMP alert or other network management alert, and repeat the 60 second timer.
2) Flow control
Softdial CallGem™ does not implement flow control in its messaging protocols, for the simple reason that if a subscriber service is unable to handle reasonable volumes of traffic at all times then problems will ensue. A flow control protocol would enable a subscriber to force the memory cache in Softdial CallGem™ to build up to the point where it would be forced to discard events.
Instead, in order to prevent overload, the API supports flow rate limiting (from V10.6.660). Subscriber messages support an optional Rate Control (CS) parameter, which is the number of event messages per second that the subscriber can handle during rollforward after re-subscribing. This defaults to 100 messages per second (per Persist Token) but can be set at anything between 1 and 1 million messages per second by the subscriber.
Sytel recommends leaving this at 100 unless you have a tenant with several hundred active agents, in which case you may need to set this slightly higher. Looking at the Softdial CallGem™ transaction log files for your peak hour should give some idea of event load. The flow rate for recovery should be set at not less than twice the peak event load. Sytel Support will be able to advise on this if necessary.
3) Message sequence and content
While a subscriber request is dormant because of disconnect, Softdial CallGem™ caches messages in time sequence against the Persist Token. On reconnect and resubscribe, the messages are rolled forward at the rate discussed in (2) above. The cached messages are marked with the original transaction tag, not the new one set up by resubscribe. In fact, if the subscriber attempted to persist the original transaction tag and re-use, it would fail validation because the original tag still belongs to an existent transaction. The subscriber application will need to be aware that rollforward messages will have a different transaction tag.
On completion of rollforward, the original transaction is re-registered with new transaction tag if the registry value ReplacePersistantTxOnReconnect is set to a nonzero value. By default it is.
Keeping message sequence across multiple enumerations
A stateless service that performs simple ‘extract to database’ operations will have no need of this.
A stateful service that performs aggregation may depend on messages for different enumerations arriving on the same socket in time order.
In order to support this there is a limited mechanism that allows multiple enumerate messages to share a common Persist Token. This is used by Sytel’s own ETL services. This preserves message sequence across multiple subscribe requests. There are a number of limitations though:
Each persist tag can support only one instance of each of the different types of subscriber messages. This means that the following set of subscriber messages sent on a single connection is valid:
EA\TXfoo1234\PSmytoken
EC\TXfoo5678\PSmytoken
EI\TXfoo90AB\PSmytoken
But the following set is not valid, as it has 2 separate EA transactions:
EA\TXfootenant1\TDtenant1\PSmytoken
EA\TXfootenant2\TDtenant2\PSmytoken
EI\TXfoo90AB\PSmytoken
When multiple subscribe messages are bound together with the same persist token, the first enumerate message received on re-subscribe reactivates all subscriptions. This has the side-effect of the first subscribe message being accepted by Softdial CallGem™ and subsequent messages for the same persist tag being rejected. Softdial CallGem™ will still have re-activated all the original subscriptions.
If this strategy does not fit a customers’ application there is an alternative approach which requires a little work, but would be reliable. Having individual enumerations have their own Persist Token preserves sequence only in respect of that Persist Token. While a service is catching up with rollforward messaging, it would be possible for the service to enqueue these messages in time order (time given by the Timestamp (TS) parameter) on the event message. The messages could then be dequeued in time order once catch-up is complete or well under way.
The effect of closing a campaign
If a campaign is closed while there are any agent enumerations in progress, the agent enumerations on that campaign will be ended. Integrators will need to ensure that their control applications accept 'unsolicited' Enumerate Finished [EF] messages.
If a control application socket connection terminates, all ongoing queries through that connection will be terminated.