This guide explains the interface specification used for Customization of SIP messages on Cisco Unified CM- Session Management (SME). It includes details on Lua environment available on Cisco Unified CM-SME and APIs to support SIP Transparency and Normalization functionality.
This chapter describes the following topics:
This chapter describes Lua Environment, the interface used for customizing Session Management (SM) behavior for a particular deployment. Lua is a non-proprietary, lightweight scripting language. It is assumed that the reader of this guide has basic familiarity with the Lua scripting language.
Cisco Unified CM provides a set of features called SIP Normalization and Transparency to customize the SIP messages:
•Normalization—It is the process of transforming inbound and outbound messages.
–For inbound messages, normalization happens after having received the message from the network. The inbound message normalization is used to make the message more palatable to Cisco Unified CM. For example, Cisco Unified CM supports Diversion header for carrying redirecting number information. Some SIP devices connected to Cisco Unified CM use the History-Info header for this purpose. Inbound normalization transforms the History-Info headers into Diversion headers so that Cisco Unified CM recognizes the redirecting information.
–For outbound messages, normalization happens just prior to sending the message to the network. Thus outbound message normalization is used to make the message more palatable to an external SIP device (e.g. another SIP capable PBX). For example, outbound normalization can be used to transform Diversion headers into History-Info headers so that the external SIP device will recognize the redirecting information.
•Transparency— It allows SIP information to be passed through from one call leg to another even though Cisco Unified CM is a Back to Back User Agent (B2BUA).
The Normalization and Transparency features is exposed by a script which is associated with a SIP Trunk. The scripts manifest themselves as a set of message handlers that operate on inbound and outbound SIP messages. For normalization, the script manipulates almost every aspect of a SIP message including:
–The request URI
–The response code and phrase
For transparency, the script passes through almost any information in a SIP message including:
This guide describes the scripting environment and APIs used to manipulate and pass through SIP message information.
The interface for customizing Cisco Unified CM SIP Trunk behavior is provided by a scripting language called Lua. Lua is an open source, lightweight scripting language.
The Lua Environment available for Cisco Unified CM (SM) is a restricted sub-set of Lua. In addition to the basic capabilities provided by Lua, like:
•values and types
Lua also provides some basic libraries, like:
•IO facilities and
However, the Cisco SIP Lua Environment available on SM only supports the string library in its entirety and a subset of the base library. The other libraries are not supported.
For the base library, the following is supported:
The Cisco SIP Lua Environment provides a global environment for the scripts to use, it does not expose the default Lua global environment (i.e. _G) to the scripts.
The Lua script provides a set of call back functions called message handlers to manipulate SIP messages in the context of SM environment. The name of the message handler indicates the handler that is invoked for a particular SIP message. For example, the script's "inbound_INVITE" message handler is invoked when an inbound INVITE is received by Cisco Unified CM. The message handlers receives a single parameter called msg representing a SIP Message. The Lua script uses the APIs defined in Cisco SIP Message library to access and manipulate the msg parameter.
The following part of the guide describes the details on the message handler construct. The next section has details on the Cisco SIP Message library API's.
Let's take a look at an example script that simply removes the "Cisco-Guid" header in an outbound INVITE. The script is shown with line numbers on left for ease of describing the script.
Simple Script: M.lua
2. function M.inbound_INVITE(msg)
5. function M.outbound_INVITE(msg)
There are three important parts to the above script:
1. Module Initialization—The first line of the script creates a Lua table called 'M' and initializes it to be empty. This table contains set of callback functions provided by this script. The variable M is a Lua table and is also the name of the module.
2. Message Handler Definitions—Lines 2-4 defines an inbound INVITE message handler. This callback function is executed when an inbound INVITE is received out on the SIP trunk with this script. In this example, the message handler invokes an API to convert History-Info headers into Diversion headers.
Lines 5-6 defines an outbound INVITE message handler. This callback function is executed when an outbound INVITE is sent out on the SIP trunk with this script. In this example, the message handler invokes an API to remove the "Cisco-Guid" header.
The script can define multiple message handlers. The name of the message handler dictates which message handler is invoked (if any) for a given SIP message.
3. Returning the Module—The last line returns the name of the module. This line is absolutely required. This is how the Cisco SIP Lua Environment finds the message handlers associated with the script.
The Lua script provides a set of call back functions called message handlers to manipulate SIP messages in the context of SM environment. The name of the message handler indicates which handler is invoked for a particular SIP message.
The naming rules for message handlers dictate which message handler is invoked for a given SIP message. Various SIP messages by specification, are split into requests and responses.
•For requests-the message handler is named according to the message direction and the SIP request method name. The method name is the one in the 'request line' of SIP message.
•For responses-the message handler is named according to the message direction, the response code, and the SIP method . For responses, the method name is obtained from the CSeq header of SIP message.
Consider the case where a Cisco Unified CM-SME is connected to PBX-A and PBX-B via two trunks. A script that returns module A is attached to trunk connecting to PBX-A. Similarly, a script that returns module B is attached to trunk connecting to PBX-B.
The following handlers are executed for an INVITE dialog.
The message handler names also support wild carding. The wild card support is dependent on whether the message is request or response SIP message.
A wildcard ANY can be used in place of <method>. The <direction> does not support wild card.
Refer to Table 1-1 for valid request message handler names
Table 1-1 Valid Request Message Handler Names
This message handler is invoked for all inbound INVITE messages including initial INVITEs and reINVITEs.
This message handler is invoked for all inbound requests.
This message handler is invoked for all outbound requests.
A wildcard ANY can be used in place of <method> and/or <response code>. The <direction> does not support wild card. Additionally, a wildcard character X can be used in <response code>.
Refer to Table 1-2 for valid response message handler names.
Table 1-2 Valid Response Message Handler Names
This message handler is invoked for all inbound 18X responses including 180, 181, 182, and 183.
This message handler is invoked for all inbound responses for an INVITE request including all 18X, 2XX, 3XX, 4XX, 5XX, and 6XX responses.
This message handler is invoked for all outbound responses regardless of the request method.
Rules to Pick Message Handler
Cisco Unified CM uses the following rules to find the message handler for a given message:
1. Message handlers are case-sensitive.
2. The direction is either inbound or outbound.
3. The direction is always written as lowercase.
4. The message direction is relative to SM.
Note The message direction is completely separate from dialog direction in SIP.
inbound_INVITE is valid handler name; whereas InBound_INVITE is NOT a valid handler name
5. The method name obtained from SIP message is converted to uppercase for the purpose of finding the appropriate message handler in the script.
6. CUCM-SME uses a longest-match criterion to find the correct message handler.
Assume a script has two message handlers; inbound_ANY_ANY and inbound_183_INVITE. When a 183 response is received by the Cisco Unified CM, the inbound_183_INVITE handler will be executed since it is most explicit match.
Note Although inbound or outbound is supported with ANY (response code) and ANY (method), we do not currently support the ANY (method) wildcard with specific response codes.
In other words, the following message handlers are valid:
But these are invalid: