CallerId conversion rule and CalledId (provider_callerid)

Table of Contents

Description
Limitations
Fields
See also
- API

Description

CallerId and CalledId conversion rule for SIP telephony provider accounts.
Used as an adapter for external and internal number plans. In particular, when modifying the CallerId of internal subscribers to send to the outside, adaptation to the external number plan takes place, and when modifying the CallerId of external subscribers to send to the inside, adaptation to the internal number plan takes place, i.e. preparation of data for routing.

The detected modification rule is applied to modify both From username (number), and To username (number). If it is necessary to separate modifications to reduce the number of rules, a special "priority" pointer can be applied as a modifier for To special "priority" pointer (first the rule for FromNumber is applied, and then the rule for ToNumber is searched for and applied, but with priority greater than or equal to the original rule and with filtering on the already modified one FromNumber).

The configured set of CallerId conversion rules can be tested via diagnostic API. Note, however, that there is a difference between the application in the test and in the call due to the fact that in the call the To number is taken from Request-Uri, and also if the value matches the username of the entity account, an empty string is substituted as the number to modify.

Limitations

The collection is not available in the master domain.

Fields

Entity structure

{
  "id": uuid,
  "priority": int,
  "dir": str,
  "idprovider": uuid,
  "providercode": str,
  "fromdomain": str,
  "fromnumber": str,
  "tonumber": str,
  "modfromdisplay": str,
  "modfromnumber": str,
  "modtonumber": str,
  "ext": {
    "ct": date,
    "lwt": date
  },
  "opts": {
    "title": str,
    "comment": str
  }
}

Description of the specification’s characteristics

Table 1. Fields
Specification	Description
Field: `id` Mode: `inout` Type: `uuid` Default: generated	Identifier. Can be specified at creation, otherwise generated by the system.
Field: `priority` Mode: `in` Type: `int` Default: required	Rule Priority. A lower value means a higher priority.
Field: `dir` Mode: `in` Type: `str` Default: required	Filter by direction of change. The rule applies to either internal caller data or external caller data, regardless of which way the call goes. A call between external callers actually has two dialogs per role esg, each linking the external caller as one arm of the dialog per role B2BUA.
Field: `idprovider` Mode: `in` Type: `uuid \| str_empty` Default: str_empty	Filter by identifier SIP telephony provider. The application of this filter multiplies the speed of the rule search. To specify a specific provider, clear the mask in the field beforehand 'providercode'.
Field: `providercode` Mode: `in` Type: `str` Default: empty	Filter mask for code SIP telephony provider. Filter operation modes.
Field: `fromdomain` Mode: `in` Type: `str` Default: `"*"`", "Call initiator address/domain filter mask (From SIP request header INVITE). Filter operation modes.	Field: `fromnumber` Mode: `in` Type: `str` Default: `"*"`
Mask-filter number/username of the call initiator (From SIP request header INVITE). Filter operation modes.	Field: `tonumber` Mode: `in` Type: `str` Default: `"*"`
Destination number/username filter mask (To SIP request header INVITE). Filter operation mode.	Field: `modifier_mode` Mode: `in` Type: `str` Default: `"mask"`", "Modifier operation mode from_username, from_displayname, to_username. Allows you to switch the normal modifier mode (separate each field using a string modifier) to a service script. Possible options: `mask` - normal mode of operation using separate sequential application of string modifiers to the corresponding values. `svcscript` - modification of three fields takes place in one service script, the code of which is specified in the field mod_svcscriptcode.
Field: `modfromdisplay` Mode: `in` Type: `str` Default: `"*"`", "Call initiator name modifier. The result goes to the input submission process. Modes of operation of modifiers.	Field: `modfromnumber` Mode: `in` Type: `str` Default: `"*"`
Call initiator number modifier. The result goes to the input of the call routing process. Modes of operation of modifiers.	Field: `modtonumber` Mode: `in` Type: `str` Default: `"*"`
Call destination number modifier. The result of the application goes to the input of the call routing process. Modes of operation of modifiers.	Field: `mod_svcscriptcode` Mode: `in` Type: `str` Default: empty
Service script code for CallerId number modification and CalledId. The service script is executed once and immediately returns three values using variables with special names: `from_username` - initiator’s subscriber number (From header, username field in the URI); `from_displayname` - initiator’s subscriber name (From header, field displayname); `to_username` - dialed number (To header, username field in the URI). Variables must be created in the script with the specified names. The script is executed synchronously during the routing process and takes a maximum of 3 seconds to execute. According to the ReInvite request forwarding mode selected for the provider account, the script, as well as string modifiers, can be applied when subscriber data changes on either side. As start parameters are passed to the script: 1 - provider account code 2 - call direction ('inside' or 'outside') 3 - From username 4 - From domain 5 - From display_name 6 - To username 7 - To domain 8 - Diversion username. If there is no Diversion header - empty line, if there are several, the first (last assigned) one.	Field: `opts` Mode: `in` Type: `object` Composite field
	Field: `opts.title` Mode: `in` Type: `str` Default: empty
Arbitrary header	Field: `opts.comment` Mode: `in` Type: `str` Default: empty
Arbitrary comment	Field: `opts.tab` Mode: `in` Type: `array<object>` Default: `[]`
Tabular data for using filters (and modifiers) within a single rule search session. Each object in the list contains arbitrary fields that can be used in the mask as a string {tab:some_field}. For more details see Filter operation modes, item 'Table'.	Field: `ext` Mode: `inout` Type: `object` Compound field
Allows you to extend the compound with arbitrary keys and values	Field: `ext.ct` Mode: `out` Type: `date` Default: generated
Object creation time	Field: `ext.lwt` Mode: `out` Type: `date` Default: generated

Direction of application of the rule

Table 2. Direction of application of the rule
Value	Description
`"inner"`	In the direction from the internal subscriber to the external subscriber. The rule applies to the internal subscriber’s data when it is transmitted towards the external subscriber.
`"outer"`	In the direction from the external subscriber to the internal subscriber. The rule applies to the external subscriber’s data when it is transmitted towards the internal subscriber.

Filter operation modes

Table 3. Filter operation modes
Mode	Description
`Posymbolic`	The value to be subjected to the conformance check is passed through the filter character by character. The following special characters may be used: `X` – any character; `*` – all remaining characters; `?` – any character (if used for domain name mask, any character except dot); `$` – any number of characters to the nearest point. If it is necessary to specify one of the service characters as a target character, it should be enclosed in square brackets, e.g. `[X]`.
`Table`	The `{tab:…}` substring can be used. It can be used to select a group of characters in the tested value and match them with the table embedded in the rule (`opts.tab`). For example, `{tab:a}` - select a substring and map it to the `a` field of all objects/rows in the table. The table serves as a bundle of several filter fields and modifiers. Based on the sequential check of filters, there are fewer rows in the table, taking into account the detected matches. The first of the remaining rows is used for application in modifiers. If there are no rows left in the table, the rule is rejected. Capturing characters from the mask-based value being checked can be done automatically, or with strict specification of the substring length: `{tab:KEY}` - Automatic capture from the value being tested. `{tab:KEY:LENGTH}` - Capture the specified number of characters from the value being checked. Field values in the table can be used as field values: * constants; * regular expressions (to do this, you must specify a value in the format `/reg/EXPRESSION`, e.g. `/reg/^1[1-4]$`); * mapping with other fields of the table (for this purpose it is necessary to specify the value in `/tab/FIELD` format, for example `/tab/a`). The mode is used to bind values of different fields. For example, to allow calls only to your own voice mailbox. The binding order must be strictly observed: if the referenced table field has not been checked yet and has not been filled with the real value of another entity field, the matching will fail. The order of checking entity fields: fromnumber, fromdomain, tonumber. * any value applied without a regular expression (for this purpose `/any` must be set). The mode is useful only when organizing direct comparisons with values of other fields without additional filters. The tabular modifier may be used in combination with other character mode control commands. Multiple specification of fields in one modifier, repetition, specification of non-existent fields are allowed. For example, `{tab:a:3}XXXXX{tab:b}` - allows you to highlight the 3-character city code in the number and map it to the `a` field in the table, and simultaneously highlight the tail starting at the 9th character and map it to the `b` field in the table.
`Regex`	The pattern is applied to the original value Pattern. The structure of a regex pattern value: `/reg/Pattern1`. For example,- significance: `"302"` - mask: `"/reg/0"` - Result: `true`. significance: `"302"` mask: `"/reg/^0$"` Result: `false`. significance: `"302"` mask: `"/reg/^302$"` Result: `true`. significance: `"302"` mask: `"/reg/^(301\|302\|305)$"` Result: `true`. All standard regular expression rules can be applied when forming Pattern patterns.
`Range`	The value subject to compliance checking is a numeric integer and is within the specified numeric range. The structure of the dia-template value: `/dia/FromValue+N` - fall under the pattern of N+1 values from FromValue to FromValue+N. For example,- significance: `"302"` - mask: `"/dia/300+10"` - Result: `true`.

Modes of operation of modifiers

Table 4. Modes of operation of modifiers
Mode	Description
`Posymbolic`	The initial value is posymbolic with accumulation passes through the specified modifier. The following special characters and combinations are allowed: `?` – grab the current character; `` – capture all remaining characters; `X` – capture the current character (not available when modifying DisplayName - field 'modfromdisplay'); `/` in combination with `?` or `X` - exclude the current character from the result, e.g. `/XXX/` excludes 3 current characters; `[` in combination with `]` - include in the result the service character between the brackets, e.g. `[X]`; `{C}` – include the code of the SIP-telephony provider account in the result; `{c}` – include the SIP-telephony provider account code in the lowercase result; `{U}` – include username of the SIP-telephony provider account in the result; `{u}` – include the username of the SIP-telephony provider’s account in the result lowcase username; `{D}` – include the displayname of the SIP-telephony provider account in the result; `{d}` – include in the result the lowercase displayname of the SIP-telephony provider account; `{F}` – include username from the header in the result From; `{f}` – include the lowercase username from the header in the result From; `{T}` – include username from the header in the result To; `{t}` – include the lowercase username from the header in the result To; `{DIV}` – include username from the Diversion header in the result (empty string if missing); `{div}` – include username from the Diversion header in the result (empty string if missing); `{E}` and `{e}` - include an empty value in the result; any other character is captured in the result at its corresponding position. For example,- significance: `"123456"` - From displayname: `"Abonent"` - Code: `"R1"` - modifier: `"00/X/XX5[]67{E}8?{d}{C}"` - Result: `"00235678456abonentR1"`.
`Table`	The `{tab:…}` substring can be applied. It can be used to substitute a substring from a specified table field into the modifiable value (`opts.tab`). The source is the first remaining row in the table after filtering. For example, `{tab:cccc}` - substituting the value from the `ccc` field of the first remaining row in the table into the appropriate position of the summary result. If the specified field does not exist in the first row/object, an empty value is substituted. The table serves as a bundle of several filter fields and modifiers. Based on the sequential check of filters, there are fewer rows in the table, taking into account the detected matches. The first of the remaining rows is used for application in modifiers. If there are no rows left in the table - the rule is rejected at the filter check stage. The tabular modifier may be used in combination with other character mode control commands. Multiple specification of fields in one modifier, repetitions, specification of non-existent fields are allowed.
`Regex`	The Pattern pattern with Opts options is applied to the original value and the detected block(s) are replaced with the pattern Replace. The result can be fed again to the next Regex-modification operation, and so on a finite number of times. The general structure of the regex modifier value: `/reg/Pattern1/Replace1/Opts1 /reg/Pattern2/Replace2/Opts2 …`. Options may be omitted, or may contain any combination of characters: `i` – case-insensitive `g` – global. For example,- significance: `"qwerty,qwerty"` - modifier: `"/reg/t/E/g /reg/qwer/a/"` - Result: `"aEy,qwerEy"`. When forming Pattern and Replace patterns, all standard regular expression rules can be applied, including capture groups, backward lookup, substitution of named groups, etc.
`"priority=…"`	The mode is realized in the task #192. For `To:` username modifiers, it is allowed to specify the value `priority=X` as the modifier, where `X` is any non-negative number. By doing so, the process of modifying CallerId and CalledId becomes as follows: (1) The rule R1 is searched by the initial From and To. (2) It is used to apply a modifier to From. (3) If the modifier To is 'priority=X', where X is any non-negative number, then (3.1.1) a new rule R2 is searched by new From and initial To, with priority starting from the specified one X. (3.1.2) modifier To from rule R2 is applied to the initial To. (3.2) otherwise the modifier To of rule R1 is applied to the initial To. The algorithm for constructing a compact set of CallerId and CalledId conversion rules can be as follows: (1) Proceed as usual. (2) If there is a need to reduce MN rules to M+N, then (2.1) Allocate M From modification rules with high priorities, in them set the values of modifiers To in values 'priority=X'. (2.2) Create N more rules where From filters correspond to the result of modifying From, or ``, and set modifiers To. (2.3) In the case where From modification is not required for certain values, then either modify To immediately or specify priority=X, where X is greater than the priority of the current rule.