cisco onprem uc · published

Unified CM SIP normalization and transparency scripts

Verified 2026-09-25 · 51 sources · tier 2–5

Also known as SIP normalization and transparency, SIP transparency and normalization.

In Cisco Unified Communications Manager (Unified CM), SIP normalization and transparency is an optional feature for resolving SIP interoperability issues with endpoints, service providers, PBXs, or gateways that implement SIP differently 16. The feature operates by applying a Lua script to a SIP trunk or a SIP line, allowing Unified CM to run the script against passing SIP messages 21.

How it works

Normalization scripts modify incoming and outgoing SIP messages to resolve interoperability differences 27. In Release 15, normalization scripts apply regardless of the protocol of the endpoint on the other side of the SIP trunk 26.

Transparency scripts allow Unified CM to pass SIP information, such as proprietary headers, from one call leg to the other 47. Cisco scopes transparency to calls where both call legs use SIP 48. Field reports suggest that Unified CM, acting as a back-to-back user agent, drops non-standard SIP headers between call legs unless a transparency script passes them through 2.

REFER transparency enables Unified CM to pass a REFER request across call legs without acting on the request itself, which Cisco illustrates with a call-center scenario where a centralized agent transfers a caller to a geographically local agent 36.

Memory used by a SIP normalization script is accounted for per trunk rather than per script 24. By default, a script operates with a Lua Instruction Threshold of 1000 instructions and a Memory Threshold of 50 kilobytes 6. For Webex Edge Audio, Cisco recommends increasing the Lua Instruction Threshold to 3000 and the Memory Threshold to 200 KB because every configured number raises instruction count and memory consumption 11.

Preinstalled scripts

Preinstalled scripts cannot be edited, but they can be assigned to SIP trunks and SIP profiles 5. The preinstalled scripts provide targeted interworking functions 5:

  • cisco-meeting-server-interop: Provides interoperability between Unified CM and Cisco Meeting Server 3.
  • cisco-telepresence-conductor-interop: Included among default scripts in Release 14 and Release 15 31​32.
  • cisco-telepresence-mcu-ts-direct-interop: Included among default scripts in Release 14 and Release 15 31​32.
  • diversion-counter: Provides an adjustment mechanism for the diversion counter 9.
  • HCS-PCV-PAI passthrough: Supports integration of the Cisco HCS platform with an Enterprise IMS 18.
  • redsky-alternate-id-interop: Adds RedSky headers to outbound INVITE requests 34.
  • refer-passthrough: Removes Unified CM from a call path following a blind transfer between SIP trunks 35.
  • vcs-interop: Delivers interoperability for endpoints registered to Cisco TelePresence Video Communications Server 51.

Release 12.5(1) documentation includes 7 preinstalled scripts and omits redsky-alternate-id-interop 30. Both Release 14 and Release 15 list 8 preinstalled scripts, including redsky-alternate-id-interop 31​32. WarmTransfer's reading of the sources is that redsky-alternate-id-interop was added to the default script catalog after the base 12.5(1) release 33.

Configuration and assignment

The configuration task flow follows 3 sequential steps: optionally create custom scripts, apply a script to a SIP trunk, and apply a script to SIP devices via a SIP profile 45. Cisco notes as a prerequisite that administrators developing custom scripts should review the developer guide and first verify whether an existing preinstalled script fulfills the requirement 7.

Custom scripts are created in Cisco Unified CM Administration under Device > Device Settings > SIP Normalization Script > Add New, either by entering code directly into the Contents field or by selecting Import File 4. For Webex Edge Audio integrations, the script is exported from Webex and imported using this Import File option 10.

To assign a script to a trunk, administrators select the script from the Normalization Script drop-down under Device > Trunk, with optional Parameter Name and Parameter Value pairs 49. For a SIP trunk, the script must be configured directly on the trunk configuration page; Cisco TAC documentation indicates that applying the script to the trunk's SIP profile does not work 50. Following any script assignment or change, the administrator must save and apply the configuration and reset the trunk before updates take effect 37.

To assign a script to SIP devices, the script is selected within the SIP Profile under Device > Device Settings > SIP Profile, where an SDP Transparency Profile can also be configured under the SDP Information section 44.

Scripting model and APIs

In Cisco TAC examples, Lua message handlers are defined as functions on a module table organized by direction and method, such as M.inbound_INVITE(msg) and M.outbound_INVITE(msg) 17. TAC examples manipulate headers with msg:getHeader, msg:modifyHeader, msg:removeHeader, and msg:addHeader—for instance, removing Cisco-Guid from inbound INVITE messages or appending INFO to Allow 19. SDP bodies can be read with msg:getSdp() and written back with msg:setSdp() 43.

In the field, transparency implementations commonly use an inbound handler that reads a header and forwards it to the other call leg via msg:getPassThrough() and pt:addHeader(), provided the header is listed in M.allowHeaders; an outbound handler subsequently rewrites or removes the header 28. In the field, practitioners read trunk Parameter Name and Parameter Value pairs inside a script with scriptParameters.getValue(name), allowing one script to be reused with different values 41.

The Cisco DevNet SIP Normalization and Transparency page provides developer guides for releases 8.5(1), 9.0(1), and 9.1(1), with the newest published on 7 January 2013 8. WarmTransfer's reading of the sources is that no release-specific Lua developer guide newer than 9.1(1) was found; current Feature Configuration Guides reference a generic programming-reference list instead, so API behaviour on Release 14 or 15 is documented only by carry-forward from the 2013 guide 25.

Diagnostics and troubleshooting

Enabling the Enable Trace option on a SIP trunk or SIP profile causes the script to output SDI traces, which Cisco recommends while debugging 12. When trace logging is active, CallManager SDL traces record script modifications, allowing administrators to search for Before Normalization and After Normalization markers 42. In the field, practitioners log custom messages from a script with trace.format() and read them in CallManager traces collected through RTMT when Enable Trace is checked 46.

TAC troubleshooting procedures recommend verifying Lua script syntax with an external compiler and confirming script direction, message types, and execution logic against the developer guide 15.

The Release 15 RTMT Administration Guide lists Cisco SIP Normalization and Cisco SIP Line Normalization as performance objects under Voice and Video counters 40.

See also

Applicability

Applies to: Cisco Unified Communications Manager and Cisco Unified Communications Manager with Webex Edge Audio. Deployments: on-premises, hybrid, and hosted. Sources checked 2026-09-25. The 12.5(1) System Configuration Guide lists 7 preinstalled scripts and omits redsky-alternate-id-interop 30. The Release 14 and SUs Feature Configuration Guide lists 8 preinstalled scripts, including redsky-alternate-id-interop 31. The Release 15 guide lists 8 preinstalled scripts 32.

What remains uncertain

The Lua version, sandbox, full msg, sdp, pt, scriptParameters, trace, and sipUtils APIs, and handler naming grammar from the 9.1(1) Developer Guide are not covered by the sources below.

The current-release field table for SIP Normalization Script Configuration, including thresholds, ranges, defaults, and recovery-action labels, is not covered by the sources below.

Official guidance on testing scripts before production via lab, offline harness, or simulator is not covered by the sources below.

The exact UI labels and defaults for Script Execution Error Recovery Action and System Resource Error Recovery Action in Release 14 and 15 are not covered by the sources below.

Maximum script Contents size and any per-cluster script count limit are not covered by the sources below.

Prerequisites for refer-passthrough and its interaction with transfer features and CDR are not covered by the sources below.

Cisco Meeting Server with CUCM deployment guide statements on cisco-meeting-server-interop are not covered by the sources below.

The names of the headers inserted by redsky-alternate-id-interop are not covered by the sources below.

See also

Related to

  • Expressway business-to-business calling — The preinstalled vcs-interop script targets endpoints registered to TelePresence VCS; whether it applies to current Expressway trunks is not established in this packet
  • RedSky E911 for enterprise UC — Unified CM 14 and 15 ship a preinstalled redsky-alternate-id-interop script that adds RedSky headers to outbound INVITEs (see claim cucm-sip-normalization-redsky-script)

Referenced by

Sources

  1. 1
    The SIP normalization alarms are SIPNormalizationScriptOpened, SIPNormalizationScriptClosed, SIPNormalizationScriptError (which reports the failing line number), SIPNormalizationResourceWarning and SIPNormalizationAutoResetDisabled.
  2. 2
    Practitioners report that Unified CM, acting as a back-to-back user agent, drops non-standard SIP headers between call legs unless a transparency script passes them through.field report
    CUCM SIP Normalization and Transparency Scripting Example · Core problem / introduction · Checked 2026-09-25
  3. 3
    The preinstalled cisco-meeting-server-interop script provides interoperability between Unified CM and Cisco Meeting Server.
  4. 4
    Custom scripts are created in Cisco Unified CM Administration under Device > Device Settings > SIP Normalization Script > Add New, either by typing into the Contents box or by using Import File.
  5. 5
    Preinstalled scripts cannot be edited, but they can be assigned to SIP trunks and SIP profiles.
    Feature Configuration Guide for Cisco Unified Communications Manager, Release 15 and SUs - Configure SIP Normalization and Transparency · SIP Normalization and Transparency Overview (paragraph preceding the default scripts table) · Checked 2026-09-25
  6. 6
    By default, a SIP normalization script has a Lua Instruction Threshold of 1000 instructions and a Memory Threshold of 50 kilobytes.
    Cisco Webex Edge Audio Customer Configuration Guide · Create SIP Normalization Script from the Webex LUA Script · Checked 2026-09-25
  7. 7
    Cisco lists as a prerequisite that anyone developing custom scripts should review the Developer Guide for SIP Normalization and Transparency, and should first check whether a default script already meets the need.
  8. 8
    The Cisco DevNet SIP Normalization and Transparency page lists developer guides only for releases 8.5(1), 9.0(1) and 9.1(1); the newest is dated 7 January 2013.
    SIP Normalization and Transparency - UC Manager SIP - Cisco DevNet · document list (three PDF entries) · Checked 2026-09-25
  9. 9
    The preinstalled diversion-counter script provides a way to adjust the diversion counter.
  10. 10
    For Edge Audio, the Lua script is exported from Webex and loaded into Unified CM with Import File in the SIP Normalization Script window.
    Cisco Webex Edge Audio Customer Configuration Guide · Create SIP Normalization Script from the Webex LUA Script · Checked 2026-09-25
  11. 11
    For Webex Edge Audio, Cisco recommends raising the script's Lua Instruction Threshold to 3000 and its Memory Threshold to 200 KB, because each configured number increases the script's instruction count and memory use.
    Cisco Webex Edge Audio Customer Configuration Guide · Create SIP Normalization Script from the Webex LUA Script · Checked 2026-09-25
  12. 12
    Checking Enable Trace on the trunk or SIP profile makes the script produce SDI traces, and Cisco recommends enabling tracing while debugging scripts.
    Feature Configuration Guide for Cisco Unified Communications Manager, Release 15 and SUs - Configure SIP Normalization and Transparency · Apply Normalization Script to SIP Trunk, step 5 and following Note · Checked 2026-09-25
  13. 13
    A non-zero ErrorInternal counter indicates a system defect unrelated to the script's content or execution.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters: ErrorInternal description · Checked 2026-09-25
  14. 14
    In 8.5 and 9.0-era documentation, the Script Execution Error Recovery Action field offers these actions after an execution error: roll back the message only, disable the script, reset the script automatically, or reset the trunk automatically.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Script Execution Error Recovery discussion within the Cisco SIP Normalization counters and alarms section · Checked 2026-09-25
  15. 15
    The TAC troubleshooting checklist advises checking script syntax with any external Lua compiler and checking script direction, message type and logic against the developer guide.
    Configure SIP Normalization Script in CCM · Troubleshoot · Checked 2026-09-25
  16. 16
    In Unified CM, SIP normalization and transparency is an optional feature for resolving SIP interoperability issues with endpoints, service providers, PBXs or gateways that implement SIP differently.
    Feature Configuration Guide for Cisco Unified Communications Manager, Release 15 and SUs - Configure SIP Normalization and Transparency · Configure SIP Normalization and Transparency > SIP Normalization and Transparency Overview · Checked 2026-09-25
  17. 17
    Cisco's example scripts define message handlers as functions on a module table, named by direction and method, for example M.inbound_INVITE(msg) and M.outbound_INVITE(msg).
    Configure SIP Normalization Script in CCM · Develop Script for Common Scenarios > Modify Header and Remove Header code samples · Checked 2026-09-25
  18. 18
    The preinstalled HCS-PCV-PAI passthrough script supports integration of the Cisco HCS platform with an Enterprise IMS.
  19. 19
    Cisco's TAC examples manipulate headers with msg:getHeader, msg:modifyHeader, msg:removeHeader and msg:addHeader, for example removing Cisco-Guid from inbound INVITEs and adding INFO to Allow.
    Configure SIP Normalization Script in CCM · Develop Script for Common Scenarios > Modify Header / Remove Header / Add Header · Checked 2026-09-25
  20. 20
    An error during script initialization, after the script has loaded, automatically disables the script.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters: ErrorInit description · Checked 2026-09-25
  21. 21
    The feature is configured by applying a Lua script to a SIP trunk or a SIP line, and Unified CM then runs the script against the SIP messages passing through that trunk or line.
  22. 22
    The DeviceResetManually counter counts resets made through the administration interface or AXL.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters: DeviceResetManually · Checked 2026-09-25
  23. 23
    MemoryUsagePercentage reports a script's memory use as a percentage of its configured Memory Threshold.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters: MemoryUsagePercentage · Checked 2026-09-25
  24. 24
    Memory use by a SIP normalization script is counted per trunk, not per script.
  25. 25
    No release-specific Lua developer guide newer than 9.1(1) was found; current Feature Configuration Guides point to a generic programming-reference list instead, so API behaviour on Release 14 or 15 is documented only by carry-forward from the 2013 guide.inferred
    SIP Normalization and Transparency - UC Manager SIP - Cisco DevNet · document list, compared with the Prerequisites section of the Release 15 Feature Configuration Guide · Checked 2026-09-25
  26. 26
    The Release 15 guide states that normalization scripts apply regardless of the protocol of the endpoint on the other side of the SIP trunk.
  27. 27
    Normalization scripts modify incoming and outgoing SIP messages to resolve interoperability differences.
  28. 28
    A common field pattern for transparency: an inbound handler reads a header and copies it to the other leg with msg:getPassThrough() and pt:addHeader(), after listing the header in M.allowHeaders; an outbound handler then rewrites or removes it.field report
    CUCM SIP Normalization and Transparency Scripting Example · Inbound script and Outbound script sections (Alert-Info example) · Checked 2026-09-25
  29. 29
    The Cisco SIP Normalization perfmon object includes status counters (ScriptActive, ScriptOpened, ScriptClosed, ScriptDisabledAutomatically), error counters (ErrorExecution, ErrorInit, ErrorInternal, ErrorLoad, ErrorResource), reset counters (DeviceResetAutomatically, DeviceResetManually), MessageRollback, per-API counters such as msgAddHeader and ptAddHeader, and MemoryUsage and MemoryUsagePercentage.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters list · Checked 2026-09-25
  30. 30
    The 12.5(1) System Configuration Guide lists seven preinstalled scripts and does not include redsky-alternate-id-interop.
    System Configuration Guide for Cisco Unified Communications Manager, Release 12.5(1) - Configure SIP Normalization and Transparency · Configure SIP Normalization and Transparency > SIP Normalization and Transparency Overview > default scripts · Checked 2026-09-25
  31. 31
    The Release 14 and SUs Feature Configuration Guide lists the same eight preinstalled scripts, redsky-alternate-id-interop included.
    Feature Configuration Guide for Cisco Unified Communications Manager, Release 14 and SUs - Configure SIP Normalization and Transparency · SIP Normalization and Transparency Overview > default scripts table · Checked 2026-09-25
  32. 32
    The Release 15 guide lists eight preinstalled scripts: cisco-meeting-server-interop, cisco-telepresence-conductor-interop, cisco-telepresence-mcu-ts-direct-interop, diversion-counter, HCS-PCV-PAI passthrough, redsky-alternate-id-interop, refer-passthrough and vcs-interop.
    Feature Configuration Guide for Cisco Unified Communications Manager, Release 15 and SUs - Configure SIP Normalization and Transparency · SIP Normalization and Transparency Overview > default scripts table · Checked 2026-09-25
  33. 33
    redsky-alternate-id-interop appears to have been added as a preinstalled script after the 12.5(1) base release; the exact release or SU that introduced it is not established.inferred
    System Configuration Guide for Cisco Unified Communications Manager, Release 12.5(1) - Configure SIP Normalization and Transparency · default scripts list compared with the Release 14 and 15 Feature Configuration Guides · Checked 2026-09-25
  34. 34
    The preinstalled redsky-alternate-id-interop script adds RedSky headers to outbound INVITEs.
  35. 35
    The preinstalled refer-passthrough script removes Unified CM from a call after a blind transfer between SIP trunks.
  36. 36
    REFER transparency lets Unified CM pass a REFER request to the other call leg without acting on it itself; Cisco gives a call-center example in which a centralized agent transfers a caller to a geographically local agent.
    Feature Configuration Guide for Cisco Unified Communications Manager, Release 15 and SUs - Configure SIP Normalization and Transparency · SIP Normalization and Transparency Overview > SIP Transparency (REFER transparency paragraph) · Checked 2026-09-25
  37. 37
    After a script is assigned or changed, the configuration must be saved and applied and the trunk reset before the change takes effect.
    Configure SIP Normalization Script in CCM · Configure > Apply Script on Trunk in CUCM (final step) · Checked 2026-09-25
  38. 38
    If a script exceeds its memory or Lua instruction threshold while loading or initializing, it is disabled; if it does so during execution, the configured System Resource Error Recovery Action is taken.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters: ErrorResource description · Checked 2026-09-25
  39. 39
    When a script hits an execution error, Unified CM automatically restores the message to its original content before taking the configured recovery action.
    Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information · Cisco SIP Normalization counters: ErrorExecution and MessageRollback descriptions · Checked 2026-09-25
  40. 40
    The Release 15 RTMT Administration Guide still lists Cisco SIP Normalization and Cisco SIP Line Normalization as performance objects under Voice and Video counters.
    Cisco Unified Real-Time Monitoring Tool Administration Guide, Release 15 and SUs - Performance Counters and Alerts · Performance Counters and Alerts > Voice and Video Counters (table of contents; anchor CUCM_RF_C02B96FA_00) · Checked 2026-09-25
  41. 41
    Practitioners read the trunk's Parameter Name and Parameter Value pairs inside a script with scriptParameters.getValue(name), so one script can be reused with different values.field report
    CUCM SIP Normalization and Transparency Scripting Example · Outbound script section · Checked 2026-09-25
  42. 42
    With trace enabled, the CallManager SDL trace logs the changes a script makes, and troubleshooting looks for Before Normalization and After Normalization markers.
    Configure SIP Normalization Script in CCM · Verify; Troubleshoot · Checked 2026-09-25
  43. 43
    SDP bodies can be read with msg:getSdp() and written back with msg:setSdp(), as in Cisco's codec-line example.
    Configure SIP Normalization Script in CCM · Develop Script for Common Scenarios > Manipulate SDP Content · Checked 2026-09-25
  44. 44
    For SIP devices, the script is chosen in the SIP Profile (Device > Device Settings > SIP Profile), where an SDP Transparency Profile can also be selected in the SDP Information area.
  45. 45
    The task flow has three steps in this order: optionally create custom scripts, apply a script to a SIP trunk, and apply a script to SIP devices through the SIP profile.
  46. 46
    Practitioners log custom messages from a script with trace.format() and read them in CallManager traces collected through RTMT when Enable Trace is checked.field report
    vranosim/CUCM-LUA: SIP normalization scripts for CUCM · README setup notes · Checked 2026-09-25
  47. 47
    Transparency scripts let Unified CM pass SIP information such as proprietary headers from one call leg to the other.
  48. 48
    The Release 15 guide scopes transparency to calls where both call legs are SIP.
  49. 49
    A script is applied to a trunk under Device > Trunk by choosing it from the Normalization Script drop-down; Parameter Name and Parameter Value pairs are optional.
  50. 50
    For a SIP trunk, the script must be applied on the trunk itself; the TAC tech note says putting it on the SIP profile instead will not work.
    Configure SIP Normalization Script in CCM · Configure > Apply Script on Trunk in CUCM · Checked 2026-09-25
  51. 51
    The preinstalled vcs-interop script provides interoperability for endpoints registered to Cisco TelePresence Video Communications Server.

Documents

tier 2 current vendor documentation

Cisco Unified Communications Manager Managed Services Guide 9.0 - New and changed information

Cisco Systems · accessed 2026-09-25

tier 2 current vendor documentation

Cisco Unified Real-Time Monitoring Tool Administration Guide, Release 15 and SUs - Performance Counters and Alerts

Cisco Systems · 2026-09-09 · accessed 2026-09-25

tier 2 current vendor documentation

Cisco Webex Edge Audio Customer Configuration Guide

Cisco Webex · 2025-10-28 · accessed 2026-09-25

tier 2 current vendor documentation

Configure SIP Normalization Script in CCM

Cisco Systems (TAC) · 2018-07-26 · accessed 2026-09-25

tier 2 current vendor documentation

SIP Normalization and Transparency - UC Manager SIP - Cisco DevNet

Cisco DevNet · accessed 2026-09-25

tier 5 independent technical research

CUCM SIP Normalization and Transparency Scripting Example

Technology or Die (independent blog) · 2019-10-29 · accessed 2026-09-25

tier 5 independent technical research

vranosim/CUCM-LUA: SIP normalization scripts for CUCM

GitHub user vranosim · accessed 2026-09-25

Cite this page

APA

WarmTransfer. (2026, September 25). Unified CM SIP normalization and transparency scripts. WarmTransfer. https://warmtransfer.net/knowledge/cucm-sip-normalization

BibTeX

@misc{warmtransfer-cucm-sip-normalization,
  title  = {Unified CM SIP normalization and transparency scripts},
  author = {{WarmTransfer}},
  year   = {2026},
  url    = {https://warmtransfer.net/knowledge/cucm-sip-normalization},
  note   = {Verified 2026-09-25}
}