Routing rule (vectorrule)

Description

Routing rule for telephone calls and state subscriptions, applied at the second stage of the two-stage routing process (after the vector selection stage).
Rules are analyzed in a strictly defined order corresponding to the priorities of rules within the vector. A rule is analyzed by matching conditions against request parameters, and is applied when all filters pass.
Determines the action and can modify request parameters, preparing them for the next phase of the routing process.

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

Limitations

  • The collection is unavailable in the master domain.

  • On every call, after the vector is determined at the previous routing step, all rules belonging to the vector are analyzed — request parameters are matched against filter masks. This can negatively affect overall performance with a large number of rules within a vector.

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
  }
}
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 of the vector this rule belongs to

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

Rule priority within the vector. If several rules have the same priority, their check and application occur in random order. A lower value means higher priority.

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

Applied action

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

Filter based on the call initiator environment

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

Source number filter mask.
The result of modification by rules at previous routing steps is checked.
Initially the source number from the username field of the Referred-By header, or, if absent, the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

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

Source domain filter mask.
Applied when processing a call directed from another domain at the previous step.
Filter operation modes.

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

Filter mask for the provider account code in the current domain.
Applied at the first routing step when processing a call from the external environment.
Filter operation modes.

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

Destination number filter mask.
The result of modification by rules at previous steps is checked.
Initially the number from the username field of the To header of the SIP INVITE request is checked.
Filter operation modes.

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

Destination number filter mask.
A special value invisible in SIP requests, used to create rule chains without modifying target fields.
Initially the number from the username field of the From header of the SIP INVITE request, or the result of a more complex determination of the initiating subscriber number (e.g. sipuser phonenumber, the result of sipuser extension, callerid transformation rules on esg, etc.) is checked.
Filter operation modes.

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

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

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

Code of the SIP telephony provider account through which the call should be sent to an external destination when the corresponding action (external) is selected.
Optionally, a modifier can be specified using the '/mod/' prefix; tables and special substitutions are supported: {F} - from username, {T} to username, {B} by username.

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

Source number modifier.
The result is applied at subsequent routing steps.
Modifier operation modes.

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

Destination number modifier.
The result is applied at subsequent routing steps and when searching for the final destination.
Modifier operation modes.

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

Modifier of the special value for creating chains.
The result is applied at subsequent routing steps and when searching for the final destination.
Modifier operation modes.

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

Defines the rule activity schedule.
Working/non-working time is determined in the current domain settings or in parent domains up to the master domain.
Work schedule.

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

Activity interval during the week.
Applied when schedule = custom.
Each list element covers a specific segment within the week: from a time on a specific day of the week to a time on another specific day of the week.
The overall schedule is formed from the set of these segments.
Weekly schedule list element.

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

Switch for moving to the next matching rule by priority when applying the current rule fails.
If disabled, an unsuccessful response is returned to the initiator.
If enabled, the next matching rule by priority in the current domain is applied.

Field: opts.use_redirect
Mode: in
Type: bool
Default: false

Switch for the redirect option when moving to another domain (for cross-type rules).
If disabled, moving to another domain is not considered a redirect.
If enabled, moving to another domain is treated as a redirect, and for example when calculating the initiator representation in the resulting one-step transfer call, it becomes possible to use a filter by the current rule’s domain.

Field: opts.probability_percent
Mode: in
Type: float
Default: 100.0

Probabilistic rule application coefficient.
Used to distribute weights within a group of rules.

Example. To make three rules in a group apply with equal probability, they should be assigned adjacent but different priorities. Set the first rule probability to 33.33%, the second to 50%, and the third to 100%. Then the probability of applying the third rule is 1 * (1 - 0.5) * (1 - 0.333) ~ 33.33%.

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

Direction code.

Used to configure group access restriction policies by direction.
Restricts calls for subscribers whose CoS does not contain this direction either in the 'call_types' list or in any 'toll_lists'.
The TollLists specified by codes may contain this direction code directly in the 'call_types' field or in the TollLinks matrix.

If direction application is blocked by policy, routing continues searching among lower-priority rules.

More in the article CoS/CoR group access restriction.

Field: opts.restriction_level
Mode: in
Type: integer
Default: 0

Required CoS access level in the call context.

Used to configure group access restriction policies by direction.
It is one variant of direction restriction (mandatory model).
Any value greater than 0 here, for calls with non-empty CoS, requires a corresponding CosProfile with a 'restriction_level' not less than this value.

More in the article CoS/CoR group access restriction.

Field: opts.modify_cos
Mode: in
Type: str
Default: "*"

CoS (class of service) group modifier in the call context.

The value * leaves the CoS in the call context unchanged.
An empty value resets the CoS in the context and effectively disables the group access restriction policy for the current call.
Any other value overrides the CoS in the current call context.

It is a deeply optional configuration variant, since call restrictions within group policies can be introduced based on the access matrix between CoS and CoR groups of end subscribers.

Applying the modifier can have unexpected consequences, for example blocking a call from IVR whose CoS was initially empty (group policy disabled).

The modifier is applied first, then group policies are checked based on the already changed CoS value.

More in the article CoS/CoR group access restriction.

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

Action

Table 2. Action
Value Description

"denied"

Reject the call

"external"

Route the call to an external account (ESG role); toextaccount must also be specified

"internal"

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

"internalpbx"

Route the call to an internal number in the current domain using extension (more)

"crossdomain"

Route the call to another domain

"featurecode"

Route the call to a service determined by subscriber feature codes. The specific feature code is determined by matching the number against featurecode entities in the domain.

"next"

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

Call initiator environment

Table 3. Call initiator environment
Value Description

"inner"

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

"outer"

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

"cross"

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

"*"

The filter is not applied; the rule is suitable for all call initiator environments

Filter operation modes

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

  • X – any character (uppercase);

  • * – all remaining characters;

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

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

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

  • ? - any character (when used for domain name filtering, any character except the dot, the domain name separator).

  • $ - for domain filtering. Any sequence of characters except the dot, the domain name separator.

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

For example, XXX – any three-character value.

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

  • 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.

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 routecode);

  • / 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 routecode);

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

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

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

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

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

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.

Work schedule

Table 6. Work schedule
Value Description

"all"

The rule is always available for application

"disabled"

The rule is never available for application

"work"

The rule is available for application only during working hours

"non-work"

The rule is available for application only outside working hours

"custom"

The rule defines an individual availability schedule in the rule periods field

Weekly schedule list element

Table 7. Weekly schedule list element
Field Value Description

daystart

1 – 7

Day of week when the segment starts (1 – Mon, 7 – Sun)

daystop

1 – 7

Day of week when the segment ends (1 – Mon, 7 – Sun)

timestart

0 – 1440

Start time of the segment within the day, in minutes

timestop

0 – 1440

End time of the segment within the day, in minutes

See also

Logical roles

  • b2b performs routing.

  • mdc and sdc search for vectors and rules.