Routing rule (vectorrule)

Description

A rule for routing phone calls and state subscriptions applied in the second stage of a two-stage routing process (after the vector selection step).
The rules are analyzed in a strictly defined order corresponding to the priorities of the rules within the vector. Rule analysis is performed through matching conditions to query parameters, and is applied when all filters are passed.
Determines the action and can modify the request parameters, preparing them for the next phase of the routing process.

The configured set of routing vectors and rules can be tested through the diagnostic API.

Limitations

  • The collection is not available in the master domain.

  • At each call, after the vector is defined at the previous routing step, all rules belonging to the vector are analyzed - query parameters are matched with filter masks. This can adversely affect the overall performance when the number of rules within a vector is large.

Fields

Entity structure
{
  "id": uuid,
  "vector": str,
  "priority": str,
  "action": str,
  "dir": str,
  "fromnumber": str,
  "fromdomain": str,
  "fromextaccount": str,
  "tonumber": str,
  "todomain": str,
  "toextaccount": str,
  "modfromnumber": str,
  "modtonumber": str,
  "schedule": str,
  "periods": array<object>,
  "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: vector
Mode: in
Type: str
Default: required

Code vector to which this rule applies

Field: priority
Mode: in
Type: int
Default: required

The priority of a rule within a vector. When the priorities of multiple rules match, they are checked and applied in random order. A lower value means a higher priority.

Field: action
Mode: in
Type: str
Default: required

Applicable action

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

Filter based on call initiator environment

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

Source number filter mask.
The result of modification by rules in previous routing steps is checked.
Initially the source number from the username field of the Referred-By header, and in its absence from the From header, SIP-request INVITE, or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked.
Filter operation modes.

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

Source Domain Filter Mask.
Applies when a call directed in the previous step from another domain is processed.
Filter operation modes.

Field: fromextaccount
Mode: in
Type: str
Default: `"*"`", "ISP account code mask-filter in the current domain.
It is used in the first step of routing in case of call processing from the external environment.
Filter operation modes.

Field: tonumber
Mode: in
Type: str
Default: `"*"`", "Destination number mask-filter.
The result of modification by the rules in the previous steps is checked.
Initially, the number from the username field of the To SIP request header will be checked INVITE.
Filter operation modes.

Field: routecode
Mode: in
Type: str
Default: `"*"`", "Destination number mask-filter.
Special invisible value in SIP requests, used to create rule chains without modifying the target fields.
Initially, the number from the username field of the From SIP request INVITE header or the result of a more complex definition of the initiator subscriber number (e.g. sipuser phonenumber, the result of applying sipuser extension, callerid to esg conversion rules, etc.) is checked.
Filter operation modes.

Field: todomain
Mode: in
Type: str
Default: empty

The destination domain to which the routing process should be sent when the corresponding action is selected (cross)

Field: toextaccount
Mode: in
Type: str
Default: empty

The account code of the SIP telephony provider through which to send the call to the external destination when the corresponding action is selected (external).
Optionally, a modifier can be specified by specifying the prefix '/mod/'; supports tables and special substitutions {F} - from username, {T} to username, {B} by username".

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

Source number modifier.
The result is applied in the next routing steps.
Modes of operation of modifiers.

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

Destination number modifier.
The result is applied in the next routing steps and when searching for the final destination.
Modes of operation of modifiers.

Field: modroutecode
Mode: in
Type: str
Default: `"*"`", "Special value modifier to create a .
The result is applied in the next routing steps and when searching for the final destination.
Modes of operation of modifiers.

Field: schedule
Mode: in
Type: str
Default: "all"

Specifies the activity schedule of the rule.
Working/non-working hours are defined in the settings of the current domain, or in the parent domains up to the master domain.
Work schedule.

Field: periods
Mode: in
Type: array<object>
Default: empty

Activity interval during the week.
Applies in mode schedule = custom.
Each item in the list covers a specific segment within the week: from time on a particular day of the week to time on another particular day of the week.
Based on the aggregate of these segments, an overall schedule is generated.
Weekly schedule list item.

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: opts.fallback_next
Mode: in
Type: bool
Default: true

Switch to the next highest priority matching rule when the current rule application fails.
If the mode is off, a failed response is returned to the initiator.
If enabled, the next highest-priority rule in the current domain that matches the filter is applied.

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

Action

Table 2. Action
Value Description

"denied"

Reject the call

"external"

To route a call to an external account (ESG role), you must additionally specify toextaccount

"internal"

Route the call to an extension or group number in the current domain

"internalpbx"

Route the call to an extension in the current domain with the extension applied (read more)

"crossdomain"

To route a call to another domain

"featurecode"

To route a call to a service defined by subscriber feature codes. The specific CAF is determined by mapping the number to the featurecode entities in the domain.

"next"

Apply number modification rules and re-route based on the new parameters

The environment of the call initiator

Table 3. The environment of the call initiator
Value Description

"inner"

The rule can only be applied to calls initiated within the current domain

"outer"

The rule can only be applied to calls that came in from the outside through a provider account in the current domain

"cross"

The rule can only be applied to calls coming from another domain

"*"

No filter is applied, the rule is suitable for all call initiator environments

Filter operation modes

Table 4. 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 can be used (case sensitive):

  • X – any character (uppercase);

  • * – all remaining characters;

  • {F} and {f} is the original From username in its entirety;

  • {T} and {t} is the original value of To username in its entirety;

  • {E} and `{e}' is an empty value.

  • ? - any character (if used for filtering by domain names, any character except dot - domain name separator).

  • $ - to filter by domain. Any sequence of characters other than a dot - domain name separator.

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, XXX is any three-character value.

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, tonumber, fromdomain, fromextaccount, routecode.

  • 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 5. 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 the routecode);

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

  • T – substitute the original value in its entirety (not available when modifying the routecode);

  • [ in combination with ] - include in the result the service character between the brackets, e.g. [X];

  • {F} and {f} - include username value from From: SIP request header in the result INVITE;

  • {T} and {t} - include username value from To: SIP request header in the result INVITE;

  • {B} and {b} - include the username value from the Referred-By: header of the INVITE (or other transfer initiator provider) SIP request in the result. Applies only in provider account modifier mode.;

  • {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: "9090"
- modifier: "00/X/XX5[*]67{F}8*"
- Result: "00235*6790908456".

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.

Work schedule

Table 6. Work schedule
Value Description

"all"

The rule is available for use at all times

"disabled"

The rule is not available for use ever

"work"

The rule is available for use only during business hours

"non-work"

The rule is only available for use outside of business hours

"custom"

The rule defines a customized availability schedule in the periods field of the rule

Weekly schedule list item

Table 7. Weekly schedule list item
Field Value Description

daystart

1 – 7

Day of the week of the start of the segment (1 - Mon, 7 - Sun)

daystop

1 – 7

Day of the week of the end of the segment (1 - Mon, 7 - Sun)

timestart

0 – 1440

Intraday segment start time in minutes

timestop

0 – 1440

Intraday segment end time in minutes

See also

API

Logical roles

  • b2b does the routing.

  • mdc and sdc search vectors and rules.

  • Personalization
  • Increase font size
  • Decrease font size