Purpose:

The purpose of this document is to describe handling, pass through and manipulation of SIP Alert-Info header information from 3^rd party alerting systems or SIP enabled nurse calling systems such as Rauland Responder 5.  The Alert-Info header can be leveraged to play an alternative ringtone on the end device signaling a call that has a higher importance than typical calls.  A differentiated ringtone can indicate call urgency without the end user having to unclip a wireless phone from his/her belt to answer or otherwise address the call while occupied with another critical task.

Challenges:

CUCM acts as a back to back user agent (B2BUA) which consumes and then regenerates its own SIP messages between the incoming and outgoing call legs on each side of the call routing logic.  Proprietary or nonstandard SIP header information is typically ignored by CUCM and discarded.  To address the cases where header pass through is needed CUCM offers a SIP Normalization Scripting environment using the Lua scripting language and API’s that allow for header manipulation and pass through. 

Solution Example

First of all, I’ have included a Youtube video here that you might also find helpful, otherwise, keep reading below.

In the Alert-Info header use case a SIP invite will come into CUCM from an external system on a SIP trunk.  The Inbound Script will collect the Alert-Info header information and pass it through the CUCM calling process to the outgoing call leg. 

Note: CUCM does use the Alert-Info header in a different manner so the pass-through object will only accept the Alert-Info header by a different name.  In the example below X-Alert-Info is used.

The general configuration is represented below.  The Inbound Lua normalization script is assigned to the SIP Trunk.  The outgoing script is assigned to the SIP profile of the particular phone based on the format that phone expects to parse from the Alert-Info SIP header.

*The configuration below is only an example.  Consult the documentation for your specific model of IP phone and environment adapt this configuration accordingly.  

In this example the sending system is sending a simplified Alert-Info header that is matched and manipulated with user configurable variables.  The external system is configured to send three separate Alert-Info values based on alarm severity as shown here:

Alert-Info: Low
Alert-Info: Medium
Alert-Info: High

To process these or any incoming Alert-Info headers the inbound script must be assigned to the SIP trunk where calls enter CUCM from alerting systems or nurse call systems.  The script collects the Alert-Info header value and adds it to a fictious X-Alert-Info header for the purpose of pass through.

1
2
3
4
5
6
7
8
9
10
11
12
13

M = {}
M.allowHeaders = {"Alert-Info"}
 
function M.inbound_INVITE(msg) 
  local alert = msg:getHeader("Alert-Info")
  <br />  if alert
  then       
    pt = msg:getPassThrough()       
    pt:addHeader("X-Alert-Info", alert)
  end<br />
end
 
return M

The outbound script is shown below.  This script checks to see if the X-Alert-Info header is part of the message.  If its value is captured and matched and replaced according to the rules of the script.  If no X-Alert-Info value is found the script exits without making changes to the outgoing SIP message.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

M = {}
M.allowHeaders = {"X-Alert-Info","Alert-Info"}
 
function M.outbound_INVITE(msg)
  local alert = msg:getHeader("X-Alert-Info")
 
  if alert then
    msg:removeHeader("X-Alert-Info")
    local ringtone = alert
 
    --If alert variable is a replacement keyword replace it, else, exit
    if alert == "low" or alert == "Low" then
      ringtone = scriptParameters.getValue("low")
    elseif alert == "medium" or alert == "Medium" then
      ringtone = scriptParameters.getValue("medium")
    elseif alert == "high" or alert == "High" then
      ringtone = scriptParameters.getValue("high")
    else
      --do nothing
    end
 
   --modify the outgoing Alert-Info header with the custom one
   msg:modifyHeader("Alert-Info", ringtone)
 
  end
end
 
return M

When this script is assigned to an end device SIP profile the “low” “medium” and “high variables can be user defined allowing the Alert-Info header delivered to the phone to be changed without changing the script its self.  Additionally, this allows the same script to be used with IP phone devices with differing requirements while reusing the script. 

Below you can see a script called ALERT-INFO-OUT assigned with variables configured to address low, medium and high severities.  The parameter values are in Spectralink Veristy accepted form. 

The resulting SIP call flow will result in the following Invite messages between the 5555 extension, CUCM, and extension 1002.

From Alerting System:

INVITE sip:17175551002@10.100.112.11:5060 SIP/2.0
Via: SIP/2.0/UDP 10.100.112.99:5060;branch=z9hG4bKF533
From: "+15555555555" <sip:+15555555555@10.100.112.99>;tag=1C9A52E1-F61
To: <sip:15555551002@10.100.112.11>
Allow: INVITE, OPTIONS, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY, INFO, REGISTER
CSeq: 101 INVITE
Alert-Info: High

From CUCM to end station:

INVITE sip:+15555551002@10.100.201.76:5070;ob SIP/2.0
Via: SIP/2.0/UDP 10.100.112.11:5060;branch=z9hG4bK5dcf205ff413
From: <sip:+15555555555@10.100.112.11>;tag=37626~50e2cf88-d77c-45f7-8860-bd687089f873-30177065
To: <sip:+15555551002@10.100.112.11>
User-Agent: Cisco-CUCM11.5
Allow: INVITE, OPTIONS, INFO, BYE, CANCEL, ACK, PRACK, UPDATE, REFER, SUBSCRIBE, NOTIFY
CSeq: 101 INVITE
Alert-Info: <ftp://localhost/Carina.wav>
...

Other Key Resources:

SIP Transparency:  https://www.cisco.com/c/en/us/td/docs/voice_ip_comm/cucm/sip_tn/9_1_1/sip_t_n/10-sip_transparency.html