Presentation rule (representative)

Table of Contents

Description
Limitations
Fields
See also
- API
- Logical roles

Description

A rule for presenting a number (and optionally displayname) when calling from one domain to another.
Allows you to determine which call initiator number a caller from another domain will see. And accordingly, where the callback will be routed to when pressed REDIAL.
It is used in cases of organizing a common number plan for several domains.

The representation search process consists of three consecutive stages, each of which, in case of success, interrupts the process, and in case of failure transfers control to the next stage.
(1) A matching CROSS rule is searched for in the domain of the called party.
(2) A matching INNER rule is searched for in the domain of the call forwarding subscriber.
(3) A matching INNER rule is searched for in the call initiator domain.
(4) In the first-level domain (relative to the domain of the call initiator), a suitable GLOBAL rule is searched for.
In case of failure at all stages, the number is substituted "undefined". By default, a rule is automatically added to newly created domains, substituting the initiator number without modification
The rules for configuring the global number plan should be guided by the sequence of steps given.

A customized set of presentation rules can be tested via diagnostic API.

Limitations

The collection is not available in the master domain.

Fields

Entity structure

{
  "id": uuid,
  "priority": int,
  "dir": str,
  "ofdomain": str,
  "ofusername": str,
  "ofnumber": str,
  "fordomain": str,
  "forusername": str,
  "fornumber": str,
  "action": str,
  "modifier": str,
  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

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	Priority. A lower value means a higher priority.
Field: `dir` Mode: `in` Type: `str` Default: `"*"`", "Filter by direction of application. As described in the description of the representation rule search process, each direction binds the rule to a specific stage of its application.	Field: `ofdomain` Mode: `in` Type: `str` Default: `"*"`
Call initiator domain filter mask. Not applicable in the second step of the representation rule search. Filter operation modes.	Field: `ofusername` Mode: `in` Type: `str` Default: `"*"`", "Call initiator username filter mask. Filter operation modes.
Field: `ofnumber` Mode: `in` Type: `str` Default: `"*"`	Call initiator number filter mask. Filter operation modes.
Field: `fordomain` Mode: `in` Type: `str` Default: `"*"`	Called party domain filter mask. Not applicable in the first step of the search for representation rules. Filter operation modes.
Field: `forusername` Mode: `in` Type: `str` Default: `"*"`	Mask-filter username of the called party. Filter operation modes.
Field: `fornumber` Mode: `in` Type: `str` Default: `"*"`	Mask-filter the number of the called party. Filter operation modes.
Field: `redirbydomain` Mode: `in` Type: `str` Default: `"*"`", "The domain filter mask of the caller who forwarded the call. Not applicable in the second step of the representation rule search. Filter operation modes.	Field: `redirbyusername` Mode: `in` Type: `str` Default: `"*"`
Mask-filter username of the caller who forwarded the call. Filter operation modes.	Field: `redirbynumber` Mode: `in` Type: `str` Default: `"*"`
Mask-filter the number of the caller who forwarded the call. Filter operation modes.	Field: `action` Mode: `in` Type: `str` Default: `"apply"
Action defined by rule.	Field: `modifier` Mode: `in` Type: `str` Default: `"T"`
Source number modifier. Used if the field action = `"apply"`. Modes of modifier operation.	Field: `moddisplay` Mode: `in` Type: `str` Default: `"*"`
Source name modifier in field DisplayName. Used if the field action = `"apply"`. The input is a prepared user name - the result of applying the sipuser account name to the request/response received in the request/response DisplayName. In most standard cases, specifying a name modifier is not required. Modes of modifier operation.	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

Filter variants by application

Table 2. Filter variants by application
Value	Description
`"cross"`	The rule applies only in the first step, in the domain of the called party. Produces a representation of accounts from other domains for the current domain.
`"inner"`	The rule applies: at the second stage in the domain of the subscriber who forwarded the call. Produces a representation of the current domain accounts for other domains.
`* at the third stage in the domain of the call initiator subscriber. Produces a representation of the current domain accounts for other domains."`	`"global"`
`The rule applies only at the fourth step in the first-level domain, which is the root domain with respect to the domain of the call initiator’s subscriber. Makes sense only in first-level domains (relative to the master domain). Makes arbitrary domain accounts present to other domains.`	`"*"`

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 and combinations may be used: `X` – any character; `?` – any character; `*` – all remaining characters; `{F}` and `{f}' is the entire username value; `{T}` and `{t}` is the entire To username value; `{E}` and `{e}' is an empty value. 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]`. For example, `XX[X]` is any three-character value, with `X` at the end.
`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: ofdomain, ofusername, ofnumber, fordomain, forusername, fornumber. 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`.

Actions

Table 4. Actions
Value	Description
`"apply"`	Applies the rule of representation
`"abort"`	Aborts the current search step and transfers control to the next step

Modes of modifier operation

Table 5. Modes of modifier operation
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 'moddisplay'); `/` in combination with `?` or `X` - exclude the current character from the result, e.g. `/XXX/` excludes 3 current characters; `T` – substitute the original value (not available when modifying DisplayName - field 'moddisplay'); `[` in combination with `]` - include in the result the service character between the brackets, e.g. `[X]` or `[]`; `{F}` and `{f}` - include the call initiator’s username value in the result; `{T}` and `{t}` - include the username value of the called party in the result; `{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"` - modifier: `"00/X/XX5[]67{E}8?T"` - Result: `"00235*678456123456"`.
`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.