Developer Guide for SIP Transparency and Normalization
SIP Transparency
Download this chapter
SIP TransparencySIP Transparency
Download the complete book
Developer Guide for SIP Transparency and NormalizationDeveloper Guide for SIP Transparency and Normalization (PDF - 2 MB)
 Feedback

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