1. Header Manipulation Rules Resource Guide
  2. Header Manipulation Rules
  3. HMR Development

HMR Development

Before you start developing an HMR, ask yourself whether you need an HMR. Check whether an alternative is available. For example, you can configure the OCSBC to perform some of the more common needed message manipulations like stripping telephone events from SDP or resolving delayed offer issues. If you need more flexibility to address your problem, then HMR is probably the answer.

Development Overview

Once you have decided you want to use HMR to resolve an issue, Oracle recommends you follow this development procedure:

  1. Understand regex. Your knowledge of regex is fundamental to building an HMR that yields the desired result.
  2. Identify the direction of the traffic in relation to the OCSBC to which you want to apply an HMR (inbound or outbound).
  3. Identify the SIP message portion on which you want the HMR to operate: header, parameter, or body.
  4. Identify the remote entities involved and know their represented in your OCSBC configuration. Are they session agents, realms or SIP interfaces? Take into consideration the order of precedence among these entities for applying HMRs.
  5. Build the HMR and test it using the OCSBC's Testing SIP Manipulations.
  6. Apply the HMR appropriately to your configuration. Oracle recommends that you develop, test, and apply HMRs in test or laboratory environments only.
  7. Analyze the data resulting from your HMR to confirm it is working as you intend.

Development Tips

  • Define all storage rules first. Each subsequent header rule processes against the same SIP message, so each additional header rules works off of the results from the application of the rule that precedes it.

    In general, you want to store values from the original SIP header rather than from the iteratively changed versions.

  • Implement rules at the element rule rather than the header rule level. Header rules should only be a container for element rules.
  • Add additional element rules to modify a single header. Do not create multiple header rules, each with one element rule. Instead, create multiple element rules within a header rule.
  • Think of performance. Reuse as many built in variables as possible
  • Avoid lengthy string matches unless absolutely necessary
  • Wherever possible, constrain your HMR appropriately by specifying a SIP method and message type
  • Build an HMR library

Planning Considerations

You want to plan your functionality carefully when developing HMRs and you want to test it thoroughly before deploying it on your production system.

Traffic Direction

You need to determine if you want changes to occur on traffic that is relative to the OCSBC inbound or outbound.

Order of Application Precedence

As you decide direction, you must also consider the order in which the OCSBC applies HMR for session agents, realms, and SIP interfaces. The order of precedence is:

  • session agent
  • realm
  • SIP interface

A SIP manipulation applied to a session agent overrides the other two, and a SIP manipulation for a realm overrides one for a SIP interface.

Order of HMR Execution

The OCSBC applies SIP header rules in the order you have entered them, which guards against the removal of data that might be used by other header rules. The order starts with the top-most rule and continues with the execution of the sub-rules one by one. Each new rule is carried out on the result of the preceding rule.

This ordering also lets you strategically use manipulations. For example, you can use two rules if you want to store the values of a regular expression. The first rule stores the value of a matched regular expression and the second deletes the matched value.

Applying HMR to a Specific Header

You can operate on a specific instance of a given header by adding a trailing [<index>] value after the header name. This [<index>] is a numerical value representing the specific instance of the header on which to operate. However, the OCSBC takes no action if the header does not exist. You can also use the caret ^ to reference the last header of that type if there are multiple instances.

The count for referencing is zero-based, meaning that the first instance of the header counts as 0.

Note:

You cannot use a trailing [<index>] value after the header name to insert headers into a specific location. Headers are added to the end of the list, except that Via headers are added to the top.

HMR Sets

Although the OCSBC has a set method for how certain manipulation rules take precedence over others; you can use multiple SIP HMR sets to

  • Apply multiple inbound and outbound manipulations rules to a SIP message
  • Provision the order in which the OCSBC applies HMRs

You cause the header rule in one HMR to invoke another HMR. Values from that invoked HMR for the match value, comparison type, and methods are then supported. The invoked HMR is performed when those values are true.

Create Pseudocode

You start with a high-level design, refine the design to pseudocode, and then refine the pseudocode to source code. This successive refinement in small steps allows you to check your design as you drive it to lower levels of detail. The result is that you catch high level errors at the highest level, mid-level errors at the middle level, and low-level errors at the lowest level -- before any of them becomes a problem or contaminates work at more detailed levels.

Test HMRs

Test methodologies include:

  • Wireshark traces to create SIPp scripts
  • test-pattern-rule to test pattern matches from the ACLI
  • test-sip-manipulation available through the ACLI
  • log.sipd messages

test-sip-manipulation

You can use a tool that allows you to test the outcome of your SIP manipulation and header rules without sending real traffic through the OCSBC to see if they work.

To use the tool, you enter the ACLI's test-sip-manipulation utility and reference the rule you want to test using its name. Then you enter a mode where you put in a SIP message entered in ASCII. You can cut and paste this message from sipmsg.log or from some other location. Using <Ctrl-D> stops the SIP message collection and parses it.

The test informs you of any parsing errors found in the SIP message. Once the message is entered, you can execute the SIP manipulation against the message. The output after this step is the modified SIP message after manipulations have been applied. You will also find a debugging option, which displays SIP manipulation logging to the screen as the manipulation takes place.

As a starting point for testing, this tool comes loaded with a default SIP message. It cannot be associated with realms, session agents, or SIP interfaces, and so it also comes with certain resolves reserved words, such as: $LOCAL_IP, $TRUNK_GROUP_CONTEXT, and $REMOTE_PORT. In addition, you can use your settings for testing across terminal sessions; if you choose to save your settings, everything (including the SIP message) will be saved, with the exception of the debugging option.

It is not recommended that you use this tool to add an ISUP message body.

Development Example

You want to perform specialized call routing for x11 numbers, such as 211, 311, 411 and so on, based on from where the call originated. You want to concatenate the user part of the To URI with the seven digits following the +1 in the user part of the From URI and to swap that value in the user part of the Request URI: 

INVITE sip:211;csel=nonind@192.168.65.16:5060;user=phone SIP/2.0
Via:SIP/2.0/UDP 10.1.110.34;branch=z9hG4bK-BroadWorks.as3.otwaon10-192.168.65.16V5060-0-31288454-509069652-1273520380170-
From:"JOHN SMITH"<sip:+14167601262@sipt.itech.ca;user=phone>
To:<sip:211;csel=noind@92.168.65.16:5060;user=phone>

Note:

  • To user-uri: 211
  • From user-uri: +14167601262
  • Desired Request-URI: 2114167601

Writing the Pseudo Code

  • Header rule getToURI for To header is not needed. The built-in variable $RURI_USER can be used.
  • Header rule getFromURIDigits for From header. Stores specific digits for the uri-user-only part of the From header.
  • Header rule constructRURIUsingToAndFrom to build the Request-URI. Replaces the uri-user of the Request-URI with a concatenation of the stored digits.

Testing the Pattern Rule

(configure)# session-router test-pattern-rule
(test-pattern-rule)# string +14167601262
expression made 0 matches against string
(test-pattern-rule)# expression ^\+1([0-9]{7}).*$
expression made 2 matches again string
(test-pattern-rule)# show
Pattern Rule:
Expression	: ^\+1([0-9]{7}).*$
String	: +14167601262
Matched	: TRUE
Matches:
$0 +14167601262
$1 4167601

Note:

  • A $ was used to denote the end of the string. Using a carriage return line feed \r\n will not result in matches.
  • $0 is the entire string being matched against.
  • $1 is the string represented in the first set of parentheses. Here, $1 matches the desired output so the regular expression is correct.

Constructing the HMR

sip-manipulation
name                        ContructURI
description	
header-rule
    name                    getFromURIDigits
    header-name             From
    action                  store
    comparison-type         case-sensitive
    match-value
    msg-type                request
    new-value
    methods                 INVITE
    element-rule
        name                getDigit
        parameter-name 
        type                uri-user
        action              store
        match-val-type      any
        comparison-type     pattern-rule
        match-value         ^\+1([0-9]{7}).*$
        new-value
header-rule
    name                    constructRURIUsingToAndFrom
    header-name             request-uri
    action                  manipulate
    comparison-type         case-insensitive
    match-value
    msg-type                request
    new-value
    methods                 INVITE
    element-rule
        name                constructRURI 
        parameter-name 
        type                uri-user 
        action              replace 
        match-val-type      any 
        comparison-type     pattern-rule 
        match-value 
        new-value           $RURI_USER.$0+$getFromURIDigits.$getDigits.$1

Note:

$RURI_USER.$0+$getFromURIDigits.$getDigits.$1

Concatenate the two and replace the uri-user of the R-URI. The plus sign (+) serves as the concatenation operator when the comparison-type is pattern-rule. Only the $1 from the second ruleset is used because it represents just the subset of the From digits needed.

Loading Test SIP Message

(test-sip-manipulation)# load-sip-message

You might want to edit the Content-Length value default value of 276 or to remove the header. Retaining that value causes test-sip-manipulation to transmit only the first 276 characters of the loaded SIP message.

Configuring Testing

Test Sip Manipulation:
    sip-manipulation	       : ConstructRURI
    debugging	              : enabled
    direction	              : out
    manipulation-string	    :
    manipulation-pattern	   : \,+
    tgrp-context	           :
    local-ip	               : 192.168.1.60:5060
    remote-ip	              : 192.168.1.61:5060
    sip-message	            : parsed OK

Executing Testing

(test-sip-manipulation)# execute
Header Rule ConstructRURI (headerName=request-uri action=manipulate cmpType=pattern-rule) does not apply to method INVITE
After Manipulation[ConstructRURI]

The following output snippet shows that the HMR worked: 

INVITE sip:2114167601@192.168.65.16:5060;user=phone SIP/2.0
Via: SIP/2.0/UDP 10.1.119.152:5060;branch=x9hG4bKj3svpd1030b08nc9t3f1.1
From: JOHN SMITH<sip:+14167601262@sipt.tech.ca;user=phone;tag=SDekcfd01-966714349-1273696750280-
To: <sip:211;csel=noind@10.1.119.151:5060;user=phone

Log File Analysis

Run log.sipd at debug level on the OCSBC where you plan to test the HMR to gain the most information. Then examine log.sipd to review information about the HMR execution.