Routing vector (route)

Description

Routing vector for telephone calls and state subscriptions, applied at the first stage of the two-stage routing process.
Vectors are analyzed in a strictly defined order corresponding to priorities.
A vector is analyzed by matching conditions against request parameters. If all conditions are met, routing rules are searched within the vector — the second stage 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.

Fields

Entity structure
{
  "id": uuid,
  "vector": str,
  "priority": int,
  "dir": str,
  "fromnumber": str,
  "fromdomain": str,
  "fromextaccount": str,
  "tonumber": 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

Vector code

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

Vector priority. If several vectors have the same priority, their check and application occur in random order. A lower value means higher priority.

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: 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 route 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.probability_percent
Mode: in
Type: float
Default: 100.0

Probabilistic route application coefficient.
Used to distribute weights within a group of routes.

Example. To make three routes 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: 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

Call initiator environment

Table 2. Call initiator environment
Value Description

"inner"

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

"outer"

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

"cross"

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

"*"

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

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;

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

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

Work schedule

Table 4. Work schedule
Value Description

"all"

The vector is always available for application

"disabled"

The rule is never available for application

"work"

The vector is available for application only during working hours

"non-work"

The vector is available for application only outside working hours

"custom"

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

Weekly schedule list element

Table 5. 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.