Developer Guide for SIP Transparency and Normalization
SIP Transparency
Downloads: This chapterpdf (PDF - 453.0KB) The complete bookPDF (PDF - 1.93MB) | Feedback

SIP Transparency

Table Of Contents

SIP Transparency

Supported Features

Example for 181 Transparency

Example for INFO Transparrency

Script parameters for PCV and PAI Headers

For P-Charging Vector

For P-Asserted Identity

Diversion Counter


SIP Transparency


Cisco Unified Communications Manager (Unified CM) is a Back to Back User Agent (B2BUA). Therefore, any SIP to SIP call consists of 2 SIP dialogs. It is often useful to pass information from one dialog to the other during the life of the dialogs. This includes call setup, mid call, and end of call messaging. Using the pass through object described earlier, it is possible to trigger transparent pass through of information on from one SIP dialog (representing 1 of the call legs) to the other.

Currently, transparency is limited to INVITE dialogs on SIP trunks or SIP lines. SUBSCRIBE dialogs, PUBLISH, out-of-dialog REFER, out-of-dialog unsolicited NOTIFY are not supported, and MESSAGE are not supported.

Supported Features

The following messages support transparency:

Initial INVITE and associated responses

INVITE response

180 response

183 response

200 response

4XX, 5XX, 6XX responses

reINVITE and associated responses

UPDATE message (transparency for responses to UPDATE is not supported)

INFO message (transparency for responses to INFO is not supported)

BYE message (transparency for response to BYE is not supported)

The following messages do not support Transparency:

ACK

PRACK and associated responses

INVITE with replaces and associated responses

REFER and associated responses

Typically Cisco Unified CM processes the following information (i.e. parameters, headers, and content bodies) locally. That is relative to a particular call leg. Hence, the SIP information that is understood is consumed and not passed across to the other call leg (which may not even be SIP anyway). This allows Cisco Unified CM to support various protocol inter-workings such as SIP to H.323, SIP to MGCP, etc. SIP information which is not understood by Cisco Unified CM is typically ignored.

In the following section, information which is understood and consumed by Cisco Unified CM is said to be known and the information not understood and consumed by Cisco Unifiecd CM is said to unknown.

The following information can be passed through transparently:

Parameters

Unknown headers

Unknown content-bodies

Known headers

The following is the list of known headers:

Accept

Accept-Contact

Accept-Resource-Priority

Alert-Info

Allow

Allow-Events

Also

Authorization

Bridge-Participant-ID

Call-ID

Call-Info

CC-Diversion

CC-Redirect

Contact

Content-Disposition

Content-ID

Content-Length

Content-Type

CSeq

Date

Diversion

Event

Expires

From

Geolocation

Geolocation-Error

Join

Max-Forwards

Min-Expires

Min-SE

MIME-Version

P-Asserted-Identity

P-Preferred-Identity

Privacy

Proxy-Authenticate

Proxy-Authorization

Proxy-Require

RAck

Reason

Recv-Info

Refer-To

Referred-By

Reject-Contact

Remote-Party-ID

Replaces

Request-Disposition

Requested-By

Require

Resource-Priority

Retry-After

RSeq

RTP-RxStat

RTP-TxStat

Server

Session

Session-Expires

SIP-ETag

SIP-If-Match

Subject

Subscription-State

Supported

Target-Dialog

To

Unsupported

User-Agent

Via

Warning

WWW-Authenticate

X-Cisco-EMCCInfo

X-Cisco-FallbackID

X-Cisco-ViPR-Ticket

Known Content-bodies

application/sdp

If the script attempts to pass through a known header or content-body, it will trigger an execution error.

A script writer will quickly figure out that there is a way to pass known data through without it being consumed by or interfering with Cisco Unified CM processing. Effectively, the script can get the value for a known header and place into an unknown header. The same can be done with content bodies. The 181 Transparency example below does just that with the Reason header. It gets the Reason header value and passes it through as an X-Reason header. Of course, if there is no script on the other side to consume the X-Reason header and remove it, the header will be sent to the network.

In any case, known header or content-body transparency is not supported, and SIP Transparency and Normalization is not intended for this purpose. Customers who use SIP transparency to pass through known headers or content-bodies are also responsible for the results.

In particular, SDP transparency is not supported. Cisco Unified CM cannot apply region bandwidth policies or call admission control in this case, nor can it insert media resources, which may be necessary. Many call flows result in SDP updates, which Cisco Unified CM would be unable to perform correctly. While it may be possible in some cases to manipulate declared elements in SDP successfully, manipulating negotiated elements is unlikely to succeed beyond initial call setup.

Example for 181 Transparency

Without transparency, if Cisco Unified CM receives a 181 on the outbound trunk leg, Cisco Unified CM's native behavior is to send a 180 back on the inbound trunk leg. To achieve 181 transparency, a script is required for both the inbound 181 (received on the B side) and for the would-be outbound 180 (sent on the A side).

Since the 181 is received from the PBX-B first, consider doing the following first:

Get the Reason header value

Pass through the Reason header value— Since the Reason header is a known header, the script will bypass the known header check by passing through the value using the header name X-Reason.

Cisco Unified CM will automatically merge the pass through data with the outbound message it would have sent. As mentioned previously, it would natively send a 180. The auto merge functionality therefore, places the X-Reason header into an outbound 180.

Next, one must consider what the A side needs to do:

Get the X-Reason header value and see if contains something about 181

Add a Reason header with the X-Reason header value

Remove the X-Reason header

Convert the response code and phrase to 181 Call is Being Forwarded.

These steps are depicted in the following callflow diagram:

The B-side and A-side scripts are shown below:

B-Side Script

B = {}
function B.inbound_181_INVITE(msg)
    local pt = msg:getPassThrough()
    local reason = msg:getHeader("Reason")
    if pt and reason
    then
        pt:addHeader("X-Reason", reason)
    end
end
return B

A-Side Script

A = {}
function A.outbound_180_INVITE(msg)
    local reason = msg:getHeader("X-Reason")
    if reason
    then
        if string.find(reason, "cause=181")
        then
            msg:setResponseCode(181,"Call is being forwarded")
            msg:addHeader("Reason", reason)
        end
 
   
        msg:removeHeader("X-Reason")
    end
end
return A
 
   

Example for INFO Transparrency

Without transparency, Cisco Unified CM ignores the inbound INFO message and content body. Using transparency, Cisco Unified CM extracts the proprietary content body sent by a Nortel PBX, extract the DTMF digits from that content body, create a new dtmf-relay content body and pass that through to the other call leg.

Script

M = {}
function M.inbound_INFO(msg)
    local body = msg:getContentBody("application/vnd.nortelnetworks.digits")
    if body
    then
        local digits = string.match(body, "d=(%d+)")
        if digits
			then
            pt = msg:getPassThrough()
            body = string.format("Signal=%d\r\nDuration=100\r\n", digits)
            pt:addContentBody("application/dtmf-relay", body)
        end
    end
end
return M

Inbound Message

INFO sip: 1000@10.10.10.1 SIP/2.0
Via: SIP/2.0/UDP 10.10.10.57:5060
From: <sip:1234@10.10.10.57>;tag=d3f423d 
To: <sip:1000@10.10.10.1>;tag=8942 
Call-ID: 312352@10.10.10.57 
CSeq: 5 INFO 
Content-Type: application/vnd.nortelnetworks.digits
Content-Length: 72
 
   
p=Digit-Collection
y=Digits
s=success
u=12345678
i=87654321
d=4

Outbound Message

INFO sip: 1000@10.10.10.58 SIP/2.0 
Via: SIP/2.0/UDP 10.10.10.1:5060 
From: <sip:1234@10.10.10.1>;tag=ef45ad 
To: <sip:1000@10.10.10.58>;tag=1234567
Call-ID: 475623@10.10.10.1 
CSeq: 5 INFO 
Content-Type: application/dtmf-relay
Content-Length: 26
 
   
Signal=4
Duration=100
 
   

Script parameters for PCV and PAI Headers

For P-Charging Vector

P-Charging Vector header script parameter is enhanced to add transparency to pass through mobile related information.

Prior to release 8.6(1), if Cisco Unified Communications Manager received a call that had P-Charging Vector, Cisco Unified Communications Manager sent call information on the inbound trunk leg without any mobile or IP Multimedia Subsystem (IMS) values to its service providers. Now, using the modified PCV script parameter for better transparency, Cisco Unified Communications Manager extracts the charging information that is sent from a mobile or PSTN (received on the B side), and passes that information through to the other call leg without modification (sent on the A side).

Script Parameter

term-ioi—Configure this parameter if the script needs to add the term-ioi parameter to the P-Charging-Vector header in any of the outgoing 200 OK originating from Call Manager.

For P-Asserted Identity

P-Asserted Identity header script parameter is enhanced so that Cisco Unified Communications Manager can pass through any of the PAI information unmodified, present in the incoming calls to the outgoing calls, that originate from Cisco Unified Communications Manager.

Script Parameter

pai-passthru—Configure this parameter if the script needs to pass through the P-Asserted-Identity in the outgoing calls.

Diversion Counter

The diversion counter script handles the diversion counter parameter for call forward scenarios. The diversion counter script provides the following functionality:

Acts as a pass-through diversion counter parameter for a basic tandem (trunk-to-trunk) call with no diversions within the Unified CM cluster

Handles the diversion counter parameter for a tandem call with one or more diversions within the Unified CM cluster

Handles the diversion counter parameter for a tandem call when the inbound INVITE message has more than two Diversion headers and there is also one or more diversions within the Unified CM cluster.

Exceptions

The diversion counter script has the following exceptions:

The diversion counter script is applicable only for tandem calls.

If there are multiple diversions within the cluster, the diversion counter parameter is increased by just one.

Script

--[[
    Description: 
        Diversion Counter Handling For Call Forward Scenarios. This script should be 
attached to both inbound and outbound trunk. This script provides the following 
functionalists: 
 
   
			1. Pass through counter parameter in case Basic Tandem call with NO Diversion 
within the cluster.
			2. Handling of counter parameter for Tandem call with one or more Diversion within 
CUCM cluster 
			3. Handling of counter parameter for Tandem call when inbound INVITE has more than 
two Diversion headers and there is also one or more Diversion within CUCM cluster 
 
   
    Exceptions:
			1. This script is only applicable for Tandem (trunk-to-trunk) calls.
			2. If there are multiple diversions within the cluster, the Diversion counter 
parameter will be increase just by 1.
--]]
 
   
M = {}
function M.inbound_INVITE(msg)
    if msg:isReInviteRequest()
    then
        return
    end
 
   
    -- Get the Diversion header. If no Diversion header then return. 
    local diversion = msg:getHeader("Diversion")
    if not diversion
    then
			return
    end
    local pt = msg:getPassThrough()
    pt:addHeader("X-Diversion", diversion)
end
function M.outbound_INVITE(msg)
	-- This script is applicable only for initial INVITE.
		if msg:isReInviteRequest()
        then
                return
        end
	-- Get Diversion header. If there is no Diversion header then return
        local diversion = msg:getHeader("Diversion")
        if not diversion
        then
                return
        end
 
   
        -- Get X-Diversion Header. If there was no X-Diversion header then return
        local xDiversion = msg:getHeader("X-Diversion")
        if not xDiversion
        then
                return
        end
 
   
	-- Get URI from Diversion header
        local divString = msg:getUri("Diversion")
        if divString
        then
		
		-- Parse URI and get DN and Host
                local divuri = sipUtils.parseUri(divString)
                if divuri
                then
                        lrn_user = divuri:getUser()
                        lrn_host = divuri:getHost()
 
   
				end
        end
 
   
	-- Get URI from X-Diversion header
        local xdivString = msg:getUri("X-Diversion")
        if xdivString
        then
			-- Parse URI and get DN and Host
                local xdivuri = sipUtils.parseUri(xdivString)
                if xdivuri
                then
                        xlrn_user = xdivuri:getUser()
                        xlrn_host = xdivuri:getHost()
                end
        end
 
   
	-- Get counter parameter value from inbound diversion (X-Diversion). 
	local counter = msg:getHeaderValueParameter("X-Diversion", "counter")
 
   
	-- If new LRN is different from incoming LRN, that means there was a local
        -- call forward on UCM, so increase the counter.
        if not ( string.match(lrn_user, xlrn_user) and string.match(lrn_host, xlrn_host) )
        then
                 
		-- If there is no counter parameter, then find out how many Diversion
		-- headers are there. Set the counter to no. of Diversion Header.
		-- If there is a counter value, just increase it by 1.
                if not counter
                			then        
 
   
                       local xdiv = msg:getHeaderValues("X-Diversion")
                       if #xdiv > 1
                        then
                                counter = #xdiv
                        end
				else
                       counter = counter + 1
                end
                msg:addHeaderValueParameter("Diversion","counter", counter)
		else
               -- As there is no local call forwarding, so pass through the counter 
				-- parameter.
                if counter
                then
			msg:addHeaderValueParameter("Diversion","counter", counter)
			end
        end
        msg:removeHeader("X-Diversion")
end
return M

Message Transformation

If there is call forwarding within the cluster and an incoming INVITE message has a Diversion header with a counter parameter, the diversion counter script increases the counter parameter by one in the outbound INVITE message.

Original Inbound Message

INVITE sip:3002@10.10.10.53:5060 SIP/2.0^M
Via: SIP/2.0/TCP 10.10.10.51:5060;branch=z9hG4bK4b8a7eea6b41^M
From: <sip:1003@10.10.10.51>;tag=130169~d434b1d7-c1e3-44e7-a77e-abf211d2682e-26620367^M
To: <sip:3002@10.10.10.53>^M
Date: Fri, 04 Nov 2011 14:51:39 GMT^M
Call-ID: 7ef45500-eb31fbfb-3ec2-330a0a0a@10.10.10.51^M
Supported: timer,resource-priority,replaces^M
Min-SE:  1800^M
User-Agent: Cisco-CUCM8.6^M
Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY^M
CSeq: 101 INVITE^M
Expires: 180^M
Allow-Events: presence, kpml^M
Supported: X-cisco-srtp-fallback^M
Supported: Geolocation^M
Call-Info: <sip:10.10.10.51:5060>;method="NOTIFY;Event=telephone-event;Duration=500"^M
Cisco-Guid: 2129941760-0000065536-0000000148-0856295946^M
Session-Expires:  1800^M
Diversion: <sip:1001@10.10.10.51>;reason=no-
answer;privacy=off;screen=yes;counter=2,<sip:1006@10.10.10.51>;reason=no-
answer;privacy=off;screen=yes^M
P-Asserted-Identity: <sip:1003@10.10.10.51>^M
Remote-Party-ID: <sip:1003@10.10.10.51>;party=calling;screen=yes;privacy=off^M
Contact: <sip:1003@10.10.10.51:5060;transport=tcp>^M
Max-Forwards: 69^M
Content-Length: 0^

Outbound Message

Changes to the outbound message after the diversion counter script runs are in bold.

IINVITE sip:1005@10.10.10.51:5060 SIP/2.0^M
Via: SIP/2.0/TCP 10.10.10.53:5060;branch=z9hG4bK1d64062fa6f^M
From: <sip:1003@10.10.10.53>;tag=18448~94147210-61b5-4d32-a08d-5daf91ec321b-27003595^M
To: <sip:1005@10.10.10.51>^M
Date: Fri, 04 Nov 2011 14:51:44 GMT^M
Call-ID: 81ef4580-eb31fc00-e2-350a0a0a@10.10.10.53^M
Supported: timer,resource-priority,replaces^M
Min-SE:  1800^M
User-Agent: Cisco-CUCM8.6^M
Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY^M
CSeq: 101 INVITE^M
Expires: 180^M
Allow-Events: presence, kpml^M
Supported: X-cisco-srtp-fallback^M
Supported: Geolocation^M
Call-Info: <sip:10.10.10.53:5060>;method="NOTIFY;Event=telephone-event;Duration=500"^M
Cisco-Guid: 2179941760-0000065536-0000000121-0889850378^M
Session-Expires:  1800^M
Diversion: <sip:3002@10.10.10.53>;reason=no-
answer;privacy=off;screen=yes;counter=3,<sip:1006@10.10.10.51>;reason=no-
answer;privacy=off;screen=yes^M
P-Asserted-Identity: <sip:1003@10.10.10.53>^M
Remote-Party-ID: <sip:1003@10.10.10.53>;party=calling;screen=yes;privacy=off^M
Contact: <sip:1003@10.10.10.53:5060;transport=tcp>^M
Max-Forwards: 68^M
Content-Length: 0^M