The Logical APIs

In SCC, prior to 10.7, the agent model delivered the API for agent interaction with the system. In version 10.7 of SCC the agent model has been extended to cater for multisession support as the underpinnings for the ASD. SCC provides core platform support for multimedia and multisession agents, and does so in a way that makes it easy for third parties to integrate either a simple first-party agent dialog, or a complete multisession desktop.

The agent model from SCC 10.6 continues to be supported, although the agent endpoint is part of a larger multimedia turret. This means that when an agent endpoint logs on, it does so as part of a turret. There is an additional Turret ID (QI) parameter that is passed as part of agent logon.

In order to provide backwards compatibility for the many CRM client integrations, Softdial CallGem™ still accepts the old form of agent logon request without the Turret ID (QI) parameter. When using the old form of logon, CallGem models this internally as an ASD turret with a single agent endpoint. In this way reporting and other subscribers behave consistently whether there is a 10.6-style integration or new agent API.

CallGem’s internal model is such that an agent endpoint can exist in one of the following states:

Agents transition between states either in response to requests or as a result of events in the ASD.

The first thing any application driving Campaign Manager Server should do is register for a list of configured campaigns. This is achieved by calling the CampaignManagerClass method Status Request [SR], passing the Tenant Descriptor (TD), Originator Identifier (OI) and a user-generated Transaction ID (TX) parameter.

This will yield an event Status Broadcast [SB]. The EventStatusBroadcast event will identify the Tenant and Transaction, and will contain the a Data (DT) parameter containing an XML document

Using the Dialer Chat application we can see the format of this Status Broadcast [SB] message:

CM:DE:SB\TDdefault\TX1\DT<CampaignStatus Time="2012-05-22T08:01:58Z"><Campaign ID="1" Name="TestCampaign" State="2" Type="0" Cache="200" LinkMaster="" IsLocked="false" LockTag="" LockTime="" Agents="0" CallsMade="20" ListRemaining="9979" ListTotal="10000" RunoutEstimate="9780" RetriesRemaining="12" PPState="2"/></CampaignStatus>\TS41051.334708

EventStatusBroadcast is sent every 10 seconds until method Stop Status Request [SS] is invoked for the same Transaction ID (TX). Applications can choose to take a one-shot request for information by invoking StatusRequest followed by StopStatusRequest. If the StatusRequest transaction is left open the driving application can take a running object table approach which will involve updating the table on receipt of every EventStatusBroadcast event.

While an Originator Identifier (OI) parameter is not required for all SDMP2 messages, it is recommended to make a habit of always adding this parameter to avoid issues where it is required.

The XML document is delivered in the Data (DT) parameter to the EventStatusBroadcast event is a text string with no whitespace or carriage returns. In order to transmit XML via the SDMP API, backslash characters in XML element and attribute data are translated to the relevant XML escape sequence.

When the EventStatusBroadcast event Data (DT) parameter is formatted it can be seen to contain a collection of Campaign type elements for each campaign configured in CM server.

The same approach is valid when using Softdial HTTP Proxy.

For a more information about Campaign Manager integration, please refer to the SCC User and Integration Guide and API Message Reference.

See also SDMP Message Protocol.

The non-telephony media server component provided in SCC is Workflow Server. Workflow Server connects to CallGem and fulfils the telephony model. It also provides a plugin interface that allows integrators to develop their own packet media integrations cleanly. This is also used as the basis for the SCC Chat server solution.

The plugin API is exposed through an abstract base class WorkflowBase in WorkflowBase.dll. WorkflowBase.dll is part of the developer kit and has full intellisense documentation.

For further information about third party non-telephony media integration like chat servers, CRMs, ERPs, etc, and specific guidance about how to develop it using SCC Workflow Server, please contact your local Sytel representative..

The supervisor control functions offered by the management API are:

As CallGem has evolved, a family of 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 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)

The mechanisms for doing this are not immediately obvious from the basic message documentation on the API site. This document seeks to provide ‘how to’ information to enable partners to model their data integration in the best way possible.

This document uses 2 character message codes as per SDMP 1.0 for the sake of brevity. All pub-sub messages form part of CallGem’s management interface, so where you might see a message code [EA] the full message code [CG:MA:EA] is implied.

Sytel encourages all partners using a socket interface to use SDMP 2.0 conventions for messaging. In SCC 10.7, Clients using SDMP can be configured to use HTTP (or HTTP over SSL) as the underlying application protocol without the need for application code changes if using the Sytel.Mdn2 library or Sytel’s mediation services. This enables reliability improvements in public network environments, WAN-based deployment without the need for VPNs and message queuing and routing for the upcoming SCC cloud service bus.

The message set

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 complete set of pub-sub messages is as follows:

Subscribe Message to CallGem	Publish message from CallGem
Enumerate Tenants [E1]	TenantData [Z1]
Enumerate Agents [EA]	Agent Data [AZ]
Enumerate Campaigns [EC]	Campaign Data [CZ]
Enumerate Groups [EG]	Group Data [GZ]
Enumerate Switches [ES]	Switch Data [SZ]
Enumerate Sessions [EI]	Session Data [IZ]
Enumerate Notifications [EN]	Notify Event [NE]
Enumerate Outcomes [EO]	Outcome Data [OZ]
Enumerate Queue [EQ]	Queue Data [QZ]
Enumerate Telephony [ET]	Telephony Message [TE]
Enumerate Transfer Activity [EX]	TransferData [XZ]
Enumerate Metrics [EM]	Queue Metrics [MZ]
And in 10.7…
Enumerate Turrets [QE]	Turret Data [TZ]
Enumerate Session Events [EV]	Session Event Data [VZ]
Enumerate Chat [QC]	Chat Data [XD]
Enumerate Status [ES]	Status Data [SD]

Each of these subscribe requests is uniquely identified by its Transaction Tag (TX) parameter. Best practice for traceability and avoiding name clashes is to use some short application tag concatenated with a UUID as the Transaction Tag.

The subset of these messages that deliver an initial digest of resources (and their current states) is

Subscribe Message to CallGem	Publish message from CallGem
Enumerate Tenants [E1]	TenantData [Z1]
Enumerate Agents [EA]	Agent Data [AZ]
Enumerate Campaigns [EC]	Campaign Data [CZ]
Enumerate Groups [EG]	Group Data [GZ]
Enumerate Switches [ES]	Switch Data [SZ]
And in 10.7…
Enumerate Turrets [QE]	Turret Data [TZ]
Enumerate Status [ES]	Status Data [SD]

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.

Most of the messages act as a simple feed for state change events. This applies to:

Subscribe Message to CallGem	Publish message from CallGem
Enumerate Sessions [EI]	Session Data [IZ]
Enumerate Notifications [EN]	Notify Event [NE]
Enumerate Outcomes [EO]	Outcome Data [OZ]
Enumerate Queue [EQ]	Queue Data [QZ]
Enumerate Switches [ES]	Switch Data [SZ]
Enumerate Telephony [ET]	Telephony Message [TE]
Enumerate Transfer Activity [EX]	TransferData [XZ]
Enumerate Metrics [EM]	Queue Metrics [MZ]
And in 10.7…
Enumerate Session Events [EV]	Session Event Data [VZ]
Enumerate Chat [QC]	Chat Data [XD]

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 TS parameter, enabling historical notifications to be retrieved for up to 1 hour in the past.

Ending subscription is achieved through sending Enumerate End [EE]. Closing the socket connection will achieve the same end, although this may not be desirable.

SDMP sessions are denoted by an authenticated TCP socket connection to CallGem. In a reliable network environment not under extremes of load a socket connection will stay active as long as the application connecting to CallGem keeps running.

On socket disconnect or permanent write failure, 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 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 to try to resolve this.

By appending a Persist Token (PS) parameter to a subscribe message, 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 parameter. 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

CallGem will cache (subject to memory constraints) up to one hours’ worth of transaction data for the persist tag. CallGem is a real-time service running an ASD and predictive dialing engine. Both of these functions are clock-sensitive and so as a matter of policy 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 CallGem cannot use file-based storage to persist subscriber data, hence the 1 hour limit. Subscriber services either need to be designed to be stateless and demand-started-and-stopped, or stateful and long-running.

A stateless subscriber would need to be started and run on a regular schedule, to avoid problems associated with 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 is using sockets as a transport:

1. On start, connect to CallGem and resubscribe.
2. 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.
3. If the reconnect timer handler fails to reconnect, log, raise SNMP alert or other network management alert, and repeat the 60 second timer.

Alternatively, using the HTTP proxy to communicate with CallGem, or using the Sytel.Mdn2 library SoftdialConnection class to establish a HTTP session with CallGem, will provide a reliable session without the need to handle socket closure/write failure. This will double the network bandwidth required for the session but this is only a consideration for installations with many hundreds of agents.

This means that a subscriber would be a simple extract service that receives event messages and writes them to a database without further ado.

2) Flow control

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 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. Subscriber messages support an optional parameter Calls-per-Second (CS) 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 tag) 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 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. Your local Sytel representative will be able to advise on this if necessary.

3) Message sequence and content

While a subscriber request is dormant because of disconnect, CallGem caches messages in time sequence against the persist tag. 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.

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 tag. 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:

CG:MA:EA\TXfoo1234\PSmytoken
CG:MA:EC\TXfoo5678\PSmytoken
CG:MA:EI\TXfoo90AB\PSmytoken

But this set is not valid:

CG:MA:EA\TXfootenant1\TDtenant1\PSmytoken
CG:MA:EA\TXfootenant2\TDtenant2\PSmytoken
CG:MA:EI\TXfoo90AB\PSmytoken

as it has 2 separate Enumerate Agents [EA] transactions.

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 CallGem and subsequent messages for the same persist tag being rejected. 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 tag preserves sequence only in respect of that persist tag. While a service is catching up with roll forward messaging, it would be possible for the service to enqueue these messages in time order, time given by the TS parameter on the event message. The messages could then be dequeued in time order once catch-up is complete or well under way.