MOR SIP Header Transformations

From Kolmisoft Wiki
Jump to navigationJump to search

MOR SIP Header Transformations allow advanced manipulation of SIP headers like P-Asserted-Identity (PAI).

Usage

Currently, only PAI Transformation in Provider and Device settings allow transformations.

Mor pai transformation.png

Transformation format

/match_expression/replacement_expression/flags

  • match_expression - POSIX regular expression
  • replacement_expression - replacement expression with back references to matched tokes: \1, \2, …, \9
  • flags (optional):
    • i - match ignore case
    • g - replace all matches
    • d - delete header on match
    • D - delete header on no-match
    • c - search for header in Custom SIP Header or incoming SIP header (priority for Custom SIP Header)
    • C - search for header only in Custom SIP Header



Match Expression

POSIX regular expression (regex) matching is done on full SIP header (for example: "name" <sip:number@host>;params). This allows to match and modify any part of the header (name, number, host, parameters).

Replacement Expression

If the regex match is successful, then the portion which was matched is replaced with a replacement.

A Transformation:

/sip:00/sip:/

applied on a header:

<sip:00370123456789@example.sip>

would result in:

<sip:370123456789@example.sip>

Here we match sip:00 in the original header and replace it with sip:. If the original header did not contain a number starting with 00, then regex would not match and nothing would be replaced.

Additionally, the replacement can contain \n (n is a number from 1 to 9, inclusive) references, which refer to the portion of the match which is contained between parentheses ( ). References are numbered by counting their opening parentheses from left to right.

A regex:

(.*) <sip:(.*)@(.*)>(.*)

applied on a header:

"John" <sip:00370123456789@example.sip>;user=phone 

would produce the following references:

  • \1 - "John"
  • \2 - 00370123456789
  • \3 - example.sip
  • \4 - ;user=phone

Using these references you can construct your own header:

A Transformation:

/(.*) <sip:(.*)@(.*)>(.*)/\2 <sip:\2@myhost.sip>\4/

applied on a header:

"John" <sip:00370123456789@example.sip>;user=phone

would result in:

00370123456789 <sip:00370123456789@myhost.sip>;user=phone

Here we construct a new header and set the name part to \2 (which, in our case, is a number) and set static text as a host.


Dynamic variables

Regexp and Replacement Expressions accept dynamic variables, either Asterisk channel variables or MOR custom variables in the format:

${variable}

or when a substring of variable is required:

${variables:offset:length}


Asterisk variables

Asterisk channel variables can be used in transformations. As an example, let's replace the URI number part in a header with a dialed extension:

/sip:.*@/sip:${EXTEN}@/

More on Asterisk channel variables

MOR custom variables

Custom MOR variables can also be used in transformations:

  • ${src} - current source number
  • ${dst} - current destination number


Testing

Before putting Transformations to production, it is advisable to test them on various values.


Test in Linux console

Execute sed command (add s before transformation s/regex/replacement/flags):

echo '<sip:00370123456789@myhost.sip>' | sed -E 's/sip:00/sip:/'

Test in online sed live editor

If you do not have access to the Linux console, use https://sed.js.org/ (or any other online sed editor).

Validate regex

The Regex part of a Transformation can be validated using https://regexr.com/ (or any other online regex editor).


Quick notes

  • Header must be present to apply Transformations
  • In case of error, no changes will be applied
  • Only POSIX regex is allowed


Examples

Transformation Original header Modified header Comment
/sip:00/sip:/ <sip:003701234567@myhost.sip> <sip:3701234567@myhost.sip> Cut prefix 00
/sip:\+/sip:/ <sip:+3701234567@myhost.sip> <sip:3701234567@myhost.sip> Cut + (here + is escaped by \ since it is special regex symbol)
/sip:\+370/sip:86/ <sip:+3701234567@myhost.sip> <sip:861234567@myhost.sip> Cut prefix +370, add prefix 86
/sip:\+?(.*)/sip:+\1/ <sip:3701234567@myhost.sip> <sip:+3701234567@myhost.sip> Add + if it is not present already
/sip:(\+|00)/sip:/ <sip:003701234567@myhost.sip> <sip:3701234567@myhost.sip> Cut prefix 00 or +
/sip:(.*)@/sip:0\1123@/ <sip:XXXXXXXX@myhost.sip> <sip:0XXXXXXXX123@myhost.sip> Add 0 in front and 123 at the end


Advanced Examples

Transformations provide the ability to design advanced scenarios through the use of flags and dynamic data.

Let's take this scenario as an example:

Set the number in the PAI header to the number of incoming From header if the incoming source number matches the pattern in a Custom SIP Header field or remove the PAI header if the source number does not match a pattern in Custom SIP Header

For this example, a Custom SIP Header is set on a Device:

p-Asserted-Identity: <sip:370@host>

On the same Device, a PAI Transformation is set to:

/sip:${src:0:3}.*@/sip:${src}@/CD

Scenarion #1

When an incoming call has SIP From header:

From: <sip:37064123456@host>

The PAI Transformation will produce the following PAI header:

p-Asserted-Identity: <sip:37064123456@host>

Explanation:

C flag in the Transformation forces the PAI header to be searched in the Custom SIP Header, which in our case is p-Asserted-Identity: <sip:370@host>. Then, Regexp sip:${src:0:3}.*@ will be translated to sip:370.*@ (here ${src:0:3} was set to a length of 3 because our Custom PAI header has a length of 3). Regexp sip:370.*@ matches Custom PAI header p-Asserted-Identity: <sip:370@host> and is replaced by sip:${src}@ (which translates to sip:37064123456@). The final PAI header will be:

p-Asserted-Identity: <sip:37064123456@host>

Scenarion #2

When an incoming call has SIP From header:

From: <sip:37164123456@host>

Then, the Custom PAI header will be deleted.

Explanation:

Regexp sip:${src:0:3}.*@ will be translated to sip:371.*@. Final Regexp sip:371.*@ does not match Custom PAI header p-Asserted-Identity: <sip:370@host> and since the flag D (remove header on no-match) is set in the Transformation, Custom PAI header will be removed.

See also

TODO