Difference between revisions of "MOR SIP Header Transformations"

From Kolmisoft Wiki
Jump to navigationJump to search
 
(18 intermediate revisions by the same user not shown)
Line 80: Line 80:
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'''.
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'''.


<br><br>
<br>


=Dynamic variables=
=Dynamic variables=
Line 92: Line 92:
  ${variables:offset:length}
  ${variables:offset:length}


<br><br>
<br>


==Asterisk variables==
==Asterisk variables==
Line 115: Line 115:
Before putting Transformations to production, it is advisable to test them on various values.  
Before putting Transformations to production, it is advisable to test them on various values.  


<br><br>
<br>
 
====Test in Linux console====
====Test in Linux console====


Line 125: Line 126:


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


====Validate regex====
====Validate regex====
Line 138: Line 140:
* Only POSIX regex is allowed
* Only POSIX regex is allowed


<br><br>
<br>
=Examples=
=Examples=
TODO: remove kamailio stuff


{| style="font-family: monospace; font-size: 13px" border="1" cellpadding="5" cellspacing="0"  
{| style="font-family: monospace; font-size: 13px" border="1" cellpadding="5" cellspacing="0"  
Line 152: Line 153:
|-
|-
| <nowiki>/sip:\+?(.*)/sip:+\1/</nowiki> || <nowiki><sip:3701234567@myhost.sip></nowiki> || <nowiki><sip:+3701234567@myhost.sip></nowiki> || Add + if it is not present already
| <nowiki>/sip:\+?(.*)/sip:+\1/</nowiki> || <nowiki><sip:3701234567@myhost.sip></nowiki> || <nowiki><sip:+3701234567@myhost.sip></nowiki> || Add + if it is not present already
|-
| <nowiki>/sip:(.*)@/sip:$fU@/</nowiki> || <nowiki><sip:anonymous@myhost.sip></nowiki> || <nowiki><sip:3701234567@myhost.sip></nowiki> || Using Kamailio variable $fU replace the original number with the number from SIP FROM header
|-
|-
| <nowiki>/sip:(\+|00)/sip:/</nowiki> || <nowiki><sip:003701234567@myhost.sip></nowiki> ||  <nowiki><sip:3701234567@myhost.sip></nowiki> || Cut prefix 00 or +
| <nowiki>/sip:(\+|00)/sip:/</nowiki> || <nowiki><sip:003701234567@myhost.sip></nowiki> ||  <nowiki><sip:3701234567@myhost.sip></nowiki> || Cut prefix 00 or +
|-
| <nowiki><tel:$fU;cpc=ordinary></nowiki> || Overwriting current header or creating a new header ||  <nowiki><tel:5557061219;cpc=ordinary></nowiki> || Format header in the format requested by the Supplier: <nowiki><tel:NUMBER;cpc=ordinary>/</nowiki> (special PAI example here)
|-
|-
| <nowiki>/sip:(.*)@/sip:0\1123@/</nowiki> || <nowiki><sip:XXXXXXXX@myhost.sip></nowiki> ||  <nowiki><sip:0XXXXXXXX123@myhost.sip></nowiki> || Add 0 in front and 123 at the end
| <nowiki>/sip:(.*)@/sip:0\1123@/</nowiki> || <nowiki><sip:XXXXXXXX@myhost.sip></nowiki> ||  <nowiki><sip:0XXXXXXXX123@myhost.sip></nowiki> || Add 0 in front and 123 at the end
|-
|-
|}


<br>


|}
=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:
 
<nowiki>P-Asserted-Identity: <sip:370@host></nowiki>
 
On the same Device, a PAI Transformation is set to:
 
<nowiki>/sip:${src:0:3}@/sip:${src}@/CD</nowiki>
 
====Scenarion #1====
 
When an incoming call has SIP From header:
 
<nowiki>From: <sip:37064123456@host></nowiki>
 
The PAI Transformation will produce the following PAI header:
 
<nowiki>P-Asserted-Identity: <sip:37064123456@host></nowiki>
 
'''Explanation:'''<br><br>
 
'''C''' flag in the Transformation forces the PAI header to be searched in the Custom SIP Header, which in our case is '''<nowiki>P-Asserted-Identity: <sip:370@host></nowiki>'''. Then, Regexp '''<nowiki>sip:${src:0:3}@</nowiki>''' will be translated to '''<nowiki>sip:370@</nowiki>''' (here ${src:0:3} was set to a length of 3 because our Custom PAI header has a length of 3). Regexp '''<nowiki>sip:370@</nowiki>''' matches Custom PAI header '''<nowiki>P-Asserted-Identity: <sip:370@host></nowiki>''' and is replaced by '''<nowiki>sip:${src}@</nowiki>''' (which translates to '''<nowiki>sip:37064123456@</nowiki>'''). The final PAI header will be:
 
<nowiki>P-Asserted-Identity: <sip:37064123456@host></nowiki>
 
====Scenarion #2====
 
When an incoming call has SIP From header:
 
<nowiki>From: <sip:37164123456@host></nowiki>
 
Then, the Custom PAI header will be deleted.<br><br>
 
'''Explanation:'''<br><br>


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


=See also=
=See also=


TODO
* [[Devices]]
* [[Device settings]]
* [[Providers]]

Latest revision as of 12:13, 29 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 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 (delete header on no-match) is set in the Transformation, Custom PAI header will be removed.

See also