Difference between revisions of "MOR SIP Header Transformations"

From Kolmisoft Wiki
Jump to navigationJump to search
Line 6: Line 6:
Currently, only '''PAI Transformation''' in Provider and Device settings allow transformations.
Currently, only '''PAI Transformation''' in Provider and Device settings allow transformations.


TODO: add a screenshot
[[File:mor_pai_transformation.png]]
<br><br>
<br><br>



Revision as of 08:55, 19 March 2024

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 Expression 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

TODO: remove kamailio stuff

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:(.*)@/sip:$fU@/ <sip:anonymous@myhost.sip> <sip:3701234567@myhost.sip> Using Kamailio variable $fU replace the original number with the number from SIP FROM header
/sip:(\+|00)/sip:/ <sip:003701234567@myhost.sip> <sip:3701234567@myhost.sip> Cut prefix 00 or +
<tel:$fU;cpc=ordinary> Overwriting current header or creating a new header <tel:5557061219;cpc=ordinary> Format header in the format requested by the Supplier: <tel:NUMBER;cpc=ordinary>/ (special PAI example here)
/sip:(.*)@/sip:0\1123@/ <sip:XXXXXXXX@myhost.sip> <sip:0XXXXXXXX123@myhost.sip> Add 0 in front and 123 at the end



See also

TODO