RouterNET API

Getting the list of configured campaigns and IDs

The first thing any application driving Softdial 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 a Status Broadcast [SB]event. This event will identify the tenant and transaction, and will contain the a Data (DT) parameter containing an XML document.

Using Dialer Chat 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

Status Broadcast [SB] 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 Status Request [SR] followed by Stop Status Request [SS]. If the Status Request [SR] transaction is left open the driving application can take a running object table approach which will involve updating the table on receipt of every Status Broadcast [SB] event.

While an OriginatorIdentifier (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 Status Broadcast [SB] 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 Status Broadcast [SB] event Data (DT) parameter is formatted it can be seen to contain a collection of Campaign type elements for each campaign configured in Softdial Campaign Manager™ server.

The description of attributes for the Campaign type is:

Attribute	Description	Data Type
ID	Integer ID for the campaign. This is the ID used for referencing campaigns throughout the Softdial Campaign Manager™ API.	Integer
Name	The campaign name	String
State	An enumeration showing the campaign's current state. Valid values are: 0 - Closed 1 - Opening 2 - Running 3 - Suspended 4 - Awaiting suspend (both campaign and database) 5 - Awaiting suspend (of campaign) 6 - Awaiting suspend (waiting for database updates) 7 - Awaiting close(both campaign and database) 8 - Awaiting close (of campaign) 9 - Awaiting close (waiting for database updates)10 - Preprocessing	Integer Enum
Type	The type of campaign. (Not the same as the Dialing Mode (DM) parameter value) Valid values are: 0 - Outbound Predictive 1 - Outbound Progressive 2 - Outbound Preview (dialer-directed) 3 - Inbound 6 - Agentless	Integer Enum
Cache	The number of records currently in cache. If the campaign is not running this value is 0.	Integer
Agents	The number of agents logged in and available	Integer
CallsMade	The count of calls made in total on the campaign	Integer
ListRemaining	The number of undialed records in this campaign. This value is only populated when the campaign is running. When not running contains 0.	Integer
ListTotal	The total number of records in this campaign. This value is only populated when the campaign is running. When not running contains 0.	Integer
RunoutEstimate	The estimated time to run out of data based on the current number of agents logged in and data burn rate. An integer value in minutes. This value is only populated when the campaign is running. When not running contains 0.	Integer

See also SDMP Message Protocol

Getting/ setting configuration for a specific campaign

Having got a table of campaign ID / name references it is possible for the driving application to get and set properties of a campaign. The get and set operations need to lock access to the campaign before performing the get/ set operation.

Configuration is set via the Set Campaign Properties [SO] method and configuration is retrieved via the Get Campaign Properties [GP] method and Property Data [PD] event pair.

A successful call will yield the Property Data [PD] event with a Data (DT) parameter containing a large XML document with the property set for that campaign. For details of the XML document format for properties please refer to Campaign Properties XML.

The Set Campaign Properties [SO] method can be used to set campaign properties. As a general approach to setting properties we recommend getting the existing property set, updating the XML document and setting this as the input Data (DT) parameter.

Creating and deleting campaign configurations

Job management activities

All job management methods require passing the following parameters:

Tenant Descriptor (TD)
Campaign Identifier (CY)

The choice of whether to implement synchronisation for these methods is left to the user. To implement synchronisation, the Token (TK) parameter should be set and the Message Verify [MV] and Error Report [ER] events should be handled to indicate success or failure.

The job management methods are:

Method	Description
Open Campaign [OC]	Starts the campaign
Close Campaign [CC]	Requests the campaign be brought to an orderly halt
Kill Campaign [KC]	Brings the campaign to an abrupt halt and will result in loss of result data. To bring a campaign to an abrupt halt whilst preserving data integrity the Softdial CallGem™ management interface Kill Campaign [KC] method should be used instead
Reload Campaign [RL]	Performs a cursor reload on the main recordset for outbound campaigns. It has no use on inbound campaigns
Suspend Campaign [SC]	Requests the campaign to be brought to a suspended state
Resume Campaign [RC]	Brings the campaign back to a running state from a suspended state

Other methods and events

Softdial Campaign Manager™ Server manages server-side connections to databases via ODBC. In order for a client application to validate DSN, table and column names, an interface is provided:

Validating column names

To get a collection of columns against a given table or view, call the Get Columns [GC] method, passing the following parameters:

Tenant Descriptor (TD)
Campaign Identifier (CY)
Data Source Name (B1)
Data Source User (B2) - usage is DBMS-dependent
Data Source Password (B3) - usage is DBMS-dependent
Schema (B4) - If omitted, the default schema as implemented by the DBMS is used.
Table (B5) - mandatory - identifies the table within the data source and schema

The Column Data [CB] event will return a collection of items in the Data (DT) parameter. Iterating the children of the DatabaseColumnList element in this collection will list the columns that the specified table contains. Each Item element references a column with attributes as follows:

Attribute	Description	Type
Name	Column name	String
Nullable	Whether the column allows nulls	Boolean (stored as true/ false string)
Data Type	The ODBC data type for the column	Integer
Data Length	The length of the data in the column (or max length in the case of varchar type columns	Integer
Precision	The number of places of precision for decimal number types.	Integer

Campaign Management

RouterNET API