This document describes how to configure and use the CSTAp2 gateway of TelServer.
The purpose of this TelServer gateway is to convert the CSTAp2 ECMA 217 protocol into PBX specific call control protocols and vice-versa. ECMA CSTA is the most deployed CTI protocol. It is supported by many PBX manufacturers to allow call control over the PBX phones. Although CSTA I, II and III (BER or XML) have been specified by ECMA, the ECMA 217/218 (CSTA phase II) is the most widespread. It gathers all the needed features to allow enhanced call control.
For the above reason, many applications support the CSTA phase II protocol. This gateway allows thoses applications to be connected to other types of PBX non supporting CSTA phase II (for example JTAPI enabled PBXs). It can also be used for developping first party applications built over CSTA phase II because it enables many TCP clients to connect to the gateway while there is a single PBX connection.
The TelServer CSTAp2 gateway can either multiplex all the devices on one TCP connection, either use one TCP connection per device. A useful feature for dynamically selecting the PBX information (IP, port and so on) is also offered. The gateway does not expect ACSE and will ignore any ACSE requests not responding to it. All PDUs are prepended by a two bytes length delimiter. There is no special exhange for starting or stopping the connection.
In case the PBX is a CSTA PBX, the CSTA model of the PBX is strictly kept. For example, if the ConnectionID is built with dynamic device, the gateway does not change this is provides the same dynamic device.
All CSTA operations are supported by the gateway which transmit them to the PBX; supporting or not a specific function is thus left to the PBX.
In that mode, the data exchanged by the application and the gateway are through a single TCP connection per PBX. This is the classic behavior of an ECMA CSTA connection. All information for all devices is wrapped within a ROSE envelope and CSTA events are reported for a specific cross reference identifier. This mode is efficient because all the incoming messages are directly passed to the lower layer handling the PBX specific call control protocol. The gateway however supports several clients if there are several PBXs, one client connection per PBX.
In that mode, the gateway expects one TCP connection par device. At each argument reception, the gateway finds the concerned device with the device number if given or the ConnectionID. The result is indeed sent on the TCP connection as well as each CSTA event concerning the device that has opened a MonitorStart on that connection.
This feature allows the client application to provide the PBX connection information to the gateway at runtime, without the need to define statically the PBX properties. It is expected to be the first message from the application.
This feature relies on the CSTAp2 extension mechanism. The TelServer CSTAp2 gateway accepts a private EscapeServiceArgument operation. The private data used in the EscapeServiceArgument is defined as :
CSTAPrivateData ::= CHOICE {
pbxConnection [0] IMPLICIT UTF8String, -- containing the PBX properties as a String like they should be defined in the TelServer.properties file.
...
}
Hereafter is an example.
Let's assume the following properties for the PBX (refer to PBX settings for more information) :
pbxlink.pbx.type=PBX_CISCO pbxlink.pbx.address=192.168.0.6 pbxlink.pbx.user.name=admin pbxlink.pbx.user.password=secret pbxlink.pbx.jtapi.peer=com.cisco.jtapi.CiscoJtapiPeerImpl
One should then encode the following (adding new lines '\n' after each property) into an element of the privateData component :
pbxlink.pbx.type=PBX_CISCO\npbxlink.pbx.address=192.168.0.6\npbxlink.pbx.user.name=admin\npbxlink.pbx.user.password=secret\npbxlink.pbx.jtapi.peer=com.cisco.jtapi.CiscoJtapiPeerImpl
Take care of the encoding of the length which is BER encoded : if length is lower or equal than 127, the length is encoded on one byte with bit 8 set to '0'; if it is greater than 127, the first byte has got its bit 8 set to '1' and contains the number of bytes of the length that will follow and while following bytes represent the length encoded as a binary unsigned integer.
Let's assume pbxProperties is this String, the bytes to encode are (the code is written in Java using uniGone's CSTAp2 Asn1API but is easily adaptable).
CSTAp2.csta_escape_service.EscapeServiceArgument escapeServiceArgument = new CSTAp2.csta_escape_service.EscapeServiceArgument();
CSTAp2.csta_escape_service.EscapeServiceArgument._privateData._element_ element = escapeServiceArgument.privateData().newElement();
byte[] ba = new byte[1 + 2 + pbxProperties.length()]; // tag + length (2 bytes) + the bytes of the String
ba[0] = (byte)0x80; // the [0] tag
ba[1] = (byte)(0x80 | 1); // because the length is greater than 178 (> 127), the first byte gives the number of bytes (1) of the
// length and the next byte gives the length (on one byte). If one byte length is enough (< 127), simply
// write ba[1] = (byte)props.length();
ba[2] = (byte)pbxProperties.length();
System.arraycopy(pbxProperties.getBytes(), 0, ba, 3, pbxProperties.length());
element.setValue(ba);
escapeServiceArgument.privateData().add(element);
When the CSTAp2 gateway receives this operation, it considers that the PBX link must be established with the given properties. This feature enables the gateway to be statically configured but for the PBX configuration which can be provided dynamically by the application.
This feature allows the application to define the logging level at runtime.
As above, this feature relies on the CSTAp2 extension mechanism. The private data used in the EscapeServiceArgument is defined as :
CSTAPrivateData ::= CHOICE {
loggingLevel [1] IMPLICIT UTF8String, -- containing "OFF", "FATAL", "ERROR", "WARN", "INFO", "DEBUG" or "ALL".
...
}
Hereafter is an example.
String loggingLevel = "ALL"; CSTAp2.csta_escape_service.EscapeServiceArgument escapeServiceArgument = new CSTAp2.csta_escape_service.EscapeServiceArgument(); CSTAp2.csta_escape_service.EscapeServiceArgument._privateData._element_ element = escapeServiceArgument.privateData().newElement(); byte[] ba = new byte[1 + 1 + loggingLevel.length()]; // tag + length (1 byte) + the bytes of the String ba[0] = (byte)0x81; // the [1] tag ba[1] = (byte)loggingLevel.length(); System.arraycopy(loggingLevel.getBytes(), 0, ba, 2, loggingLevel.length()); element.setValue(ba); escapeServiceArgument.privateData().add(element);
When the CSTAp2 gateway receives this operation, it defines the logging level in consequence.