Developer Guide

Abbreviations

Introduction

Purpose of this document

The purpose of this document is to assist CUCM Connector client applications developers to understand the flow of messages between CC and CC-Client.

Before You Start

You’re expected to have a good understanding of JMS and broker-based communication using ActiveMQ. You should know what are Topics and Queues, what is the difference between them, and how they can be used in different contexts. While you are exploring ActiveMQ, many questions arise in your mind and those are answered here.

Apache ActiveMQ is the most popular and powerful open source messaging and Integration Patterns server.

Apache ActiveMQ is fast, supports many Cross Language Clients and Protocols, and comes with easy-to-use Enterprise Integration Patterns and many advanced features while fully supporting JMS 1.1 and J2EE 1.4. Apache ActiveMQ is released under the Apache 2.0 License

First of all, download, install and run ActiveMQ Broker. You can find some samples on the ActiveMQ site. A basic Hello World program can be found here. You can find more complex examples here. All of these examples are implemented in java. If you are writing clients in a language other than Java, you can find examples in the respective technology on the ActiveMQ site.

ActiveMQ supports different types of topologies for communication. GC is using a Client-Server topology with TCP protocol for communication. You need to develop at least a simple application that communicates on given specifications.

CUCM Connector Communication Architecture

<Make diagram here showing CC-Client, CC, AMQ, CUCM>

• Describe a little bit about broker-based communication using AMQ 
• On which protocol and ports CC communicate with AMQ
• The client is expected to subscribe to AMQ <Topic>Destination
• GC listens on AMQ <Queue>Destination

A message broker is an intermediary program module that translates a message from the formal messaging protocol of the sender to the formal messaging protocol of the receiver. Message brokers are elements in telecommunication or computer networks where software applications communicate by exchanging formally-defined messages. Apache ActiveMQ is fast, supports many Cross Language Clients and Protocols, and comes with easy-to-use Enterprise Integration Patterns.

CC uses ActiveMQ as a message broker for communication. By default, CC communicates with AMQ on port 61616 (openwire) using TCP protocol. You can change port in AMQ configurations. CC listens on Queue “Connector1”, all the commands from the client should be published to Queue “Connector1” and CC replies on Topic, specified by the client in the Hello command. 

Message Pattern

CC communicates via AMQ that follows simple open text JMS messaging over OpenWire. A message could either be a request/command from the CC-Client or it could be an event/response sent by CC. In the rest of the document, the term “Command” is used to mention the message sent by the CC client, and the term “Event” is used to mention the message sent by CC.

Command Pattern

In a Command, JMS-Type contains the command and JMS-Body contains command arguments.

Commands are grouped into categories for the sake of clean and easier-to-interpret documentation.

Where

•  <Command> is any of the supported commands. See All Commands
• <Agent_ID> is the agent’s login ID
• <Client_Destination> is the ActiveMQ topic which GC-client is subscribed on. On this AMQ Topic, GC will send all events to GC-Client
• In the JMS-Body, NULL represents an empty string and NOT a “NULL” string. If no command argument is needed, set the value to an empty string.
• Multiple Command arguments are mentioned in a comma-separated string.

Event Pattern

An Event is a message sent by GC in response to any command!

There are two patterns being used for the event listening!

Default Pattern

Where

• JMS-Type carries nothing (An empty String)
• JMS-Body contains the complete event
• <Argument-N> represents event arguments. Event Arguments are separated by #

JSON Pattern

An event is actually a JSON packet sent to the topic!

Error Pattern

 If any command from client encountered by some error, GC will event contains error details.

Client Communication Use Cases

There may be 2 types of CC-Clients:

1. Desktop client - running one instance per agent like MS-CRM USD Client
2. Server client - moderating and communicating on behalf of multiple agents per server as in the case of Siebel SCAPI Driver, SAP IC, etc.

Establish Connection

The client application must ensure the proper establishment of a connection with CC before invoking any agent operations. 

To establish a connection with CC via AMQ, 

1. CC-Client should create an AMQ topic (Client Destination) where this client will listen.

1. For a Desktop client, this should be unique for every client instance.
2. For a Server client, this should be unique for every server instance.

• Create an AMQ producer with Destination <Queue> name Connector1 to send commands.
• Send Hello Command
• If GC-Client receives System#IN_SERVICE, the GC is assumed to be connected and ready to listen.

Note: If CC-Client doesn’t receive System#IN_SERVICE after CONNECT_TIMEOUT (Max. 3 seconds suggested) period, it should periodically keep sending the Hello command.

All Commands

Following is the list of all possible commands supported by CC. Each of the commands is explained with parameters supplied, events expected against the command, and possible errors that can occur for that particular command.

Note: While sending a command message, set the value for the property Time To Live for the message to a certain time(milliseconds), after the specified time that message/command will automatically be discarded by AMQ. It needs to do so that the old command should not be processed. 

CC supports synchronous requests. To achieve this, you need to send JMSCorrelationID along with the command, CC will send the same JMSCorrelationID with the event that corresponds to that particular command. 

Set ReplyTo attribute of command message to the topic on which the client is subscribed to receive events.

Hello

Hello is the first command sent from Client to CC for handshake purposes. If CC replies with some event mean that your connection with CC has been established and the client is able to send further commands to CC. If the client does not receive any response from CC, either CC is dead or the command is not delivered to CC. Before sending a Hello command you should know on which topic the client will listen from CC. You need to create that topic on ActiveMQ explicitly and subscribe to it. Specify that particular topic in the hello command as <Client_Destination> parameter. If the client receives System#IN_SERVICE, you can supply further commands to CC (other than the hello command). Normally,  Connect and Login commands are sent after a successful handshake to CC in order to start your session (Make and receive calls). If the client receives System#OUT_OF_SERVICE or no response from CC, keep sending the hello command. 

Login

The Login command is used to actually log in to CUCM. This command actually registers the IP phone with CUCM. Login command parameters are agent extension, dummy_value, and dummy_value. In case of a successful login, CC raises Agent Info, AgentState, and Dialog state events. Now the agent will be able to make and receive calls on the client application.  

Logout

The Login command is used to actually log in to CUCM. This command actually registers the IP phone with CUCM. Login command parameters are agent extension, dummy_value, and dummy_value. In case of a successful login, CC raises Agent Info, AgentState, and Dialog state events. Now the agent will be able to make and receive calls on the client application.  

Make a Call

This command allows a user to make a call. Source IP phone diales the destination extension and make a call. 

Answer a Call

This command allows a user to answer an incoming call. Via NEW INBOUND Call event, we receive the details about the other extension. 

Release a Call

This command allows a user to drop a call.

Hold a Call

This command allows a user to drop a call.

Retrieve a Call

This command allows a user to drop a call.

Blind Transfer 

This command allows a user to transfer the call blindly without waiting for the other agent to receive the call.

Consult Call 

This command allows a user to initiate a consult call with another agent. Once the call is accepted by the other agent, the user can either transfer this call to the other agent or can initiate the conference call between all parties.

Consult Transfer 

This command allows a user to transfer the customer call to the consulted agent. This will drop the consult call between agents and transfer the customer call to the other agent.

Conference Call 

This command allows a user to initiate the conference call with the customer and the consulted agent. 

GetState

This command allows a user to drop a call.

All Events

System#IN_SERVICE

System#IN_SERVICE is the event that a client connected to CC receives frequently. Normally it is the response of Hello or Beat commands. It indicates that the GC is connected to CUCM and can perform actions in response to the command.

Default Format

JSON Format

{
"type": "System",
"status": "IN_SERVICE"
}

System#OUT_OF_SERVICE

Normally it is the response of Hello or Beat commands. It indicates that the GC is not connected to CUCM and is unable to perform an action in response to the commands. After sending this event, GC will stop receiving further commands from clients. The client should send Hello until it didn’t receive System#IN_SERVICE.

Default Format

JSON Format

{
"type": "System",
"status": "OUT_OF_SERVICE"
}

Note: Above events can also be received in case of CUCM is down or up!

Terminal#CiscoTermInServiceEv \ Terminal#CiscoTermOutServiceEv

System#IN_SERVICE is the event that a client connected to CC receives frequently. Normally it is the response of Hello or Beat commands. It indicates that the GC is connected to CUCM and can perform actions in response to the command.

Default Format

JSON Format

{
"type": "Terminal",
"status": "CiscoTermInServiceEv"
}

DialogState

DialogState describes the current state of the call. Normally CC sends this event during call state change.

Default Format

JSON Format

DialogState

{
	"agentId":"42031",
	"participants":[],
	"connectionID":"52129051",
	"startTime":1658337036689,
	"state":"DISCONNECTED",
	"type":"DialogState"
}
 

agentId

state

stateChangeTimeString

Inbound Call State

This event is fired when CC receives an update about an agent from CUCM for an inbound call.

JSON Format

InboundCall

{
	"agentId":"42031",
	"participants":[],
	"connectionID":"52129051",
	"startTime":1658336990025,
	"state":"CONNECTED",
	"type":"InboundCall",
	"callType":"INBOUND_CALL"
}
 

agentId

State

startTime

State

AgentState describes the current state of the agent. Normally CC sends this event when the agent call state changes!

JSON Format

AGENT_STATE

{
  "agentId": "42034",
  "otherParticipants": [
    {
      "extension": "42033",
      "connectionID": "58410407",
      "state": "DIALING"
    }
  ],
  "state": "ACTIVE",
  "type": "State"
} 

agentId

state

state (Inside part)

All Errors

All the possible errors are listed below with the suggested action on the client side. You can display friendly messages against these messages on the client end. Error origin is mentioned with each error that helps the developer to debug the issue.

MISSING_EXTENSION

Extension is missing in request.

Default Format

JSON Format

{
"type": "Error",
"agentId": "",
"errorType": "MISSING_EXTENSION",
"message": "extension is missing" 
}

WRONG_EXTENSION

The extension provided in the request contains alphabetic characters. 

JSON Format

{
"type": "Error",
"agentId": "42601",
"errorType": "WRONG_EXTENSION",
"message": "extension is wrong or invalid" 
}

USER_NOT_FOUND

Agent Extension isn't found in CUCM

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "USER_NOT_FOUND",
"message": "Topic is not created" 
}

GENERAL_ERROR

When the root cause of the error is unclear. This error is sent only for the Login command.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "GENERAL_ERROR",
"message": "" 
}

CF_GENERIC_UNSPECIFIED

When the root cause of the error is unclear. No specific details are available. Can occur at any command.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "CF_GENERIC_UNSPECIFIED",
"message": "" 
}

CF_INVALID_OBJECT_STATE

The object is in the incorrect state for the request.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "CF_INVALID_OBJECT_STATE",
"message": "Agent is not in valid state" 
}

PLEASE_RETRY

Invalid request params, IOException, request timeout.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "PLEASE_RETRY",
"message": "Requested params are invalid" 
}

INVALID_PARTY

An InvalidPartyException indicates that a party given as an argument to the method call was invalid. This may either be the originating party of a telephone call or the destination party of a telephone call.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "INVALID_PARTY",
"message": "party given as an argument to the method call was invalid" 
}

PRIVILLEGE_VIOLATION

A PrivilegeViolationException indicates that an action pertaining to a certain object failed because the application did not have the proper security permissions to execute that command.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": "PREVILLEGE_VIOLATION",
"message": "a certain object failed because the application did not have the proper security permissions to execute that command" 
}

LICENSES_EXCEEDED

A LICENSES_EXCEEDED indicates that a client has crossed the max number of agents licensesed.

Default Format

JSON Format

{
"type": "Error",
"agentId": "42021",
"errorType": " LICENSES_EXCEEDED ",
"message": "No. of agent exceeded from the available license" 
}