Feedback
Table Of Contents
Overview
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:
Introduction
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.
–
–
•
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:
–
–
–
–
–
–
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.
Scripting Environment
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:
•
•
•
•
•
Lua also provides some basic libraries, like:
•
•
•
•
•
•
•
•
•
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
1. M = {}2. function M.inbound_INVITE(msg)3. msg:convertHIToDiversion()4. end5. function M.outbound_INVITE(msg)6. msg:removeHeader("Cisco-Guid")7. end8. return MThere are three important parts to the above script:
1.
2.
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.
Message Handlers
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.
Naming
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.
•
<direction>_<method>Example
inbound_INVITEoutbound_UPDATE•
<direction>_<response code>_<method>Example
inbound_183_INVITEinbound_200_INVITEoutbound_200_UPDATEUse Case
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.
Wild cards
The message handler names also support wild carding. The wild card support is dependent on whether the message is request or response SIP message.
Request messages
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
Response messages
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.
Rules to Pick Message Handler
Cisco Unified CM uses the following rules to find the message handler for a given message:
1.
2.
3.
4.
Note
Example
inbound_INVITE is valid handler name; whereas InBound_INVITE is NOT a valid handler name
5.
6.
Example
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
In other words, the following message handlers are valid:
inbound_ANY_ANY
outbound_ANY_ANY
But these are invalid:
inbound_401_ANY
outbound_200_ANY
etc.
