MOR SIP Header Transformations
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.
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
