Representation rule (representative)

Description

Rule for representing a number (and optionally displayname) when calling from one domain to another.
Allows determining which initiator number a subscriber from another domain will see. And accordingly, where the callback will be directed when REDIAL is pressed. Used when organizing a common number plan for several domains.

The representation search process consists of several sequential stages, each of which interrupts the process on success and passes control to the next stage on failure.
(1) A suitable CROSS rule is searched in the called subscriber’s domain.
(2) A suitable INNER rule is searched in the domain of the subscriber who forwarded the call.
(3) A suitable INNER rule is searched in the call initiator’s domain.
(4) A suitable GLOBAL rule is searched in the first-level domain (relative to the call initiator’s domain).
If all stages fail, the number "undefined" is substituted. By default, a rule substituting the initiator number unchanged is automatically added to newly created domains.
Global number plan configuration rules should follow the given sequence of stages.

The configured set of representation rules can be tested through the diagnostic API.

Limitations

  • The collection is unavailable 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
  }
}
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 higher priority.

Field: dir
Mode: in
Type: str
Default: "*"

Filter by application direction.
According to the representation rule search process described above, 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 applied at the second stage of 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 subscriber domain filter mask.
Not applied at the first stage of representation rule search.
Filter operation modes.

Field: forusername
Mode: in
Type: str
Default: "*"

Called subscriber username filter mask.
Filter operation modes.

Field: fornumber
Mode: in
Type: str
Default: "*"

Called subscriber number filter mask.
Filter operation modes.

Field: redirbydomain
Mode: in
Type: str
Default: "*"

Domain filter mask of the subscriber who forwarded the call.
Not applied at the second stage of representation rule search.
Filter operation modes.

Field: redirbyusername
Mode: in
Type: str
Default: "*"

Username filter mask of the subscriber who forwarded the call.
Filter operation modes.

Field: redirbynumber
Mode: in
Type: str
Default: "*"

Number filter mask of the subscriber who forwarded the call.
Filter operation modes.

Field: action
Mode: in
Type: str
Default: "apply"

Action determined by the rule.

Field: modifier
Mode: in
Type: str
Default: "T"

Source number modifier.
Used if action = "apply".
Modifier operation modes.

Field: moddisplay
Mode: in
Type: str
Default: "*"

Source name modifier in the DisplayName field.
Used if action = "apply".
The prepared user name is passed to the input - the result of applying the sipuser account name to the DisplayName received in the request/response.
In most standard cases, no name modifier is required.
Modifier operation modes.

Field: opts
Mode: in
Type: object
Compound field

Field: opts.title
Mode: in
Type: str
Default: empty

Arbitrary title

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 one rule search session.
Each object in the list contains arbitrary fields that can be used in the mask as the string {tab:some_field}.
More in Filter operation modes, item 'Table'.

Field: ext
Mode: inout
Type: object
Compound field

Allows extending 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

Time of last modification of the object

Filter options by application direction

Table 2. Filter options by application direction
Value Description

"cross"

The rule applies only at the first stage, in the called subscriber’s domain. Represents accounts of other domains for the current domain.

"inner"

The rule applies:
* at the second stage in the domain of the subscriber who forwarded the call. Represents accounts of the current domain for other domains.
* at the third stage in the domain of the call initiator subscriber. Represents accounts of the current domain for other domains.

"global"

The rule applies only at the fourth stage in the first-level domain that is the root relative to the call initiator subscriber’s domain. Makes sense only in first-level domains (relative to the master domain). Represents accounts of arbitrary domains for other domains.

"*"

The rule applies at all stages

Filter operation modes

Table 3. Filter operation modes
Mode Description

Per-character

The value being checked is passed through the filter character by character.
The following special characters and combinations can be used:

  • X – any character;

  • ? – any character;

  • * – all remaining characters;

  • {F} and {f} – the entire username value;

  • {T} and {t} – the entire To username value;

  • {E} and {e} – empty value.

If one of the service characters must be specified as a target, it should be enclosed in square brackets, e.g. [X].

For example, XX[X] – any three-character value with the character X at the end.

Table

The substring {tab:…​} can be used. It allows selecting a group of characters in the checked value and matching them against the table embedded in the rule (opts.tab).
For example, {tab:a} selects a substring and matches it against the a field of all objects/rows in the table.
The table links several filter and modifier fields. Based on sequential filter checks, fewer rows remain in the table, taking detected matches into account.
The first remaining row is used in modifiers. If no rows remain in the table, the rule is rejected.
Character capture from the checked value based on the mask can occur automatically or with strict specification of the substring length:

  • {tab:KEY} - Automatic capture from the checked value.

  • {tab:KEY:LENGTH} - Capture the specified number of characters from the checked value.

The following can be used as table field values:

  • constants;

  • regular expressions (to do this, set the value in the format /reg/EXPRESSION, e.g. /reg/^1[1-4]$);

  • mappings to other table fields (to do this, set the value in the format /tab/FIELD, e.g. /tab/a). The mode is used to link values of different fields. For example, to allow calls only to one’s own voicemail box. The linking order must be strictly observed: if the referenced table field has not yet been checked and filled with the real value of another entity field, the match will not succeed. Entity field check order: ofdomain, ofusername, ofnumber, fordomain, forusername, fornumber.

  • any value applied without a regular expression (to do this, set /any). The mode is useful exclusively for direct mappings to values of other fields without additional filters.

Using the table modifier is allowed in combination with other control commands of per-character mode.
Repeated specification of fields in one modifier, repetition, and specification of nonexistent fields are allowed.

For example, {tab:a:3}XXXXX{tab:b} allows selecting the 3-character city code in the number and matching it with field a in the table, and simultaneously selecting the tail starting from the 9th character and matching it with table field b.

Regex

The Pattern template is applied to the source value.

Structure of the regex template value:
/reg/Pattern1.

For example,- value: "302"
- mask: "/reg/0"
- result: true.

  • value: "302"

  • mask: "/reg/^0$"

  • result: false.

  • value: "302"

  • mask: "/reg/^302$"

  • result: true.

  • value: "302"

  • mask: "/reg/^(301|302|305)$"

  • result: true.

All standard regular expression rules can be used when forming Pattern templates.

Range

"The value being checked is an integer and falls within the specified range of numeric values.

Structure of the dia template value:
/dia/FromValue+N - matches N+1 values from FromValue to FromValue+N.

For example,- value: "302"
- mask: "/dia/300+10"
- result: true.

Actions

Table 4. Actions
Value Description

"apply"

Applies the representation rule

"abort"

Interrupts the current search stage and passes control to the next stage

Modifier operation modes

Table 5. Modifier operation modes
Mode Description

Per-character

The source value passes through the specified modifier character by character with accumulation.
The following special characters and combinations are allowed:

  • ? – capture the current character;

  • * – capture all remaining characters;

  • X – capture the current character (unavailable when modifying DisplayName - the 'moddisplay' field);

  • / combined with ? or X – exclude the current character from the result, e.g. /XXX/ excludes 3 current characters;

  • T – substitute the entire source value (unavailable when modifying DisplayName - the 'moddisplay' field);

  • [ combined with ] – include the service character located between the brackets in the result, e.g. [X] or [*];

  • {F} and {f} – include the call initiator username in the result;

  • {B} and {b} – include the username of the subscriber who forwarded the call in the result;

  • {T} and {t} – include the called subscriber username in the result;

  • {E} and {e} – include an empty value in the result;

  • any other character is captured into the result at its corresponding position.

For example,- value: "123456"
- modifier: "00/X/XX5[*]67{E}8?*T"
- result: "00235*678456123456".

Table

The substring {tab:…​} can be used. It allows substituting a substring from the specified table field (opts.tab) into the value being modified.
The source is the first row remaining after filtering in the table.
For example, {tab:ccc} substitutes the value from field ccc of the first remaining table row into the corresponding position of the final result.
If the specified field is absent in the first row/object, an empty value is substituted.

The table links several filter and modifier fields. Based on sequential filter checks, fewer rows remain in the table, taking detected matches into account.
The first remaining row is used in modifiers. If no rows remain in the table, the rule is rejected at the filter check stage.

Using the table modifier is allowed in combination with other control commands of per-character mode.
Repeated specification of fields in one modifier, repetitions, and specification of nonexistent fields are allowed.

Regex

The Pattern template with Opts options is applied to the source value, and the found block(s) are replaced with the Replace template.
The result can again be passed to the next Regex modification operation, and so on a finite number of times.

General structure of the regex modifier value:
/reg/Pattern1/Replace1/Opts1 /reg/Pattern2/Replace2/Opts2 …​.

Options can be omitted or contain any combination of the characters:

  • i – case-insensitive

  • g – global.

For example,- value: "qwerty,qwerty"
- modifier: "/reg/t/E/g /reg/qwer/a/"
- result: "aEy,qwerEy".

When forming the Pattern and Replace templates, all standard regular expression rules can be used, including capture groups, backreferences, named group substitution, etc.

See also

Logical roles

  • b2b performs routing and applies representation rules.

  • esg performs routing and applies representation rules.

  • mdc and sdc search for representation rules.