Правило маршрутизации (vectorrule)

Описание

Правило маршрутизации телефонных звонков и подписок на состояния, применяемое на втором этапе двухэтапного процесса маршрутизации (после этапа выбора вектора).
Правила анализируются в строго определенном порядке, соответствующему приоритетам правил внутри вектора. Анализ правила проводится через сопоставление условий с параметрами запроса, и применяется при прохождении всех фильтров.
Определяет действие и может модифицировать параметры запроса, готовя их к следующей фазе процесса маршрутизации.

Настроенная совокупность векторов и правил маршрутизации может быть протестирована через диагностическое API.

Ограничения

  • Коллекция недоступна в мастер-домене.

  • При каждом звонке после определения на предыдущем шаге маршрутизации вектора анализируются все правила, принадлежащие вектору – сопоставляются параметры запроса с масками фильтров. Это может отрицательно влиять на общую производительность при большом количестве правил внутри вектора.

Поля

Структура сущности
{
  "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. Поля
Спецификация Описание

Поле: id
Режим: inout
Тип: uuid
По умолчанию: generated

Идентификатор. Может быть задан при создании, иначе генерируется системой.

Поле: vector
Режим: in
Тип: str
По умолчанию: required

Код вектора, к которому относится данное правило

Поле: priority
Режим: in
Тип: int
По умолчанию: required

Приоритет правила внутри вектора. При совпадении приоритетов нескольких правил, их проверка и применение происходит в случайном порядке. Меньшее значение означает более высокий приоритет.

Поле: action
Режим: in
Тип: str
По умолчанию: required

Применяемое действие

Поле: dir
Режим: in
Тип: str
По умолчанию: "*"

Фильтр на основе среды инициатора звонка

Поле: fromnumber
Режим: in
Тип: str
По умолчанию: "*"

Маска-фильтр номера источника.
Проверяется результат модификации правилами на предыдущих шагах маршрутизации.
Изначально на проверку попадает номер источника из поля username заголовка Referred-By, а при его отсутствии заголовка From, SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: fromdomain
Режим: in
Тип: str
По умолчанию: "*"

Маска-фильтр домена источника.
Применяется в случае обработки звонка, направленного на предыдущем шаге из другого домена.
Режимы работы фильтров.

Поле: fromextaccount
Режим: in
Тип: str
По умолчанию: "*"

Маска-фильтр кода учетной записи провайдера в текущем домене.
Применяется на первом шаге маршрутизации в случае обработки звонка из внешней среды.
Режимы работы фильтров.

Поле: tonumber
Режим: in
Тип: str
По умолчанию: "*"

Маска-фильтр номера назначения.
Проверяется результат модификации правилами на предыдущих шагах.
Изначально на проверку попадает номер из поля username заголовка To SIP-запроса INVITE.
Режимы работы фильтров.

Поле: routecode
Режим: in
Тип: str
По умолчанию: "*"

Маска-фильтр номера назначения.
Специальное невидимое в SIP-запросах значение, применяется для создания цепочек правил без модификации целевых полей.
Изначально на проверку попадает номер из поля username заголовка From SIP-запроса INVITE, либо результат более сложного определения номера абонента-инициатора (например sipuser phonenumber, результат применения sipuser extension, правил преобразования callerid на esg и др.).
Режимы работы фильтров.

Поле: todomain
Режим: in
Тип: str
По умолчанию: empty

Домен назначения, в который следует отправить процесс маршрутизации при выборе соответствующего действия (cross)

Поле: toextaccount
Режим: in
Тип: str
По умолчанию: empty

Код учетной записи провайдера SIP телефонии, через которую следует отправить вызов на внешнее направление при выборе соответствующего действия (external).
Опционально может быть задан модификатор путем указания префикса '/mod/'; поддерживает таблицы и специальные подстановки {F} - from username, {T} to username, {B} by username".

"Поле: modfromnumber
Режим: in
Тип: str
По умолчанию: "T"

Модификатор номера источника.
Результат применяется на следующих шагах маршрутизации.
Режимы работы модификаторов.

Поле: modtonumber
Режим: in
Тип: str
По умолчанию: "T"

Модификатор номера назначения.
Результат применяется на следующих шагах маршрутизации и при поиске конечного адресата.
Режимы работы модификаторов.

Поле: modroutecode
Режим: in
Тип: str
По умолчанию: "*"

Модификатор специального значения для создания .
Результат применяется на следующих шагах маршрутизации и при поиске конечного адресата.
Режимы работы модификаторов.

Поле: schedule
Режим: in
Тип: str
По умолчанию: "all"

Определяет расписание активности правила.
Рабочее/нерабочее время определяется в настройках текущего домена, либо в родительских доменах вплоть до мастер-домена.
Расписание работы.

Поле: periods
Режим: in
Тип: array<object>
По умолчанию: empty

Интервал активности в течение недели.
Применяется в режиме schedule = custom.
Каждый элемент списка охватывает определенный отрезок внутри недели: от времени в конкретный день недели до времени в другой конкретный день недели.
На основе совокупности этих отрезков формируется общее расписание.
Элемент списка еженедельного расписания.

Поле: opts
Режим: in
Тип: object
Составное поле

Поле: opts.title
Режим: in
Тип: str
По умолчанию: empty

Произвольный заголовок

Поле: opts.comment
Режим: in
Тип: str
По умолчанию: empty

Произвольный комментарий

Поле: opts.tab
Режим: in
Тип: array<object>
По умолчанию: []

Табличные данные для использования фильтров (и модификаторов) в рамках одной сессии поиска правила.
Каждый объект в списке содержит произвольные поля, которые могут использоваться в маске в виде строки {tab:some_field}.
Подробнее в разделе Режимы работы фильтра, пункт 'Таблица'.

Поле: opts.fallback_next
Режим: in
Тип: bool
По умолчанию: true

Выключатель перехода к следующему по приоритету подходящему правилу при неудаче применения текущего правила.
Если режим выключен, то инициатору возвращается неудачный ответ.
Если режим включен, то применяется следующее по приоритету подходящее по фильтру правило текущего домена.

Поле: ext
Режим: inout
Тип: object
Составное поле

Позволяет расширять состав произвольными ключами и значениями

Поле: ext.ct
Режим: out
Тип: date
По умолчанию: generated

Время создания объекта

Поле: ext.lwt
Режим: out
Тип: date
По умолчанию: generated

Действие

Table 2. Действие
Значение Описание

"denied"

Отклонить вызов

"external"

Направить вызов на внешний аккаунт (роль ESG), требуется дополнительно указать toextaccount

"internal"

Направить вызов на внутренний или групповой номер в текущем домене

"internalpbx"

Направить вызов на внутренний номер в текущем домене с применением extension (подробнее)

"crossdomain"

Направить вызов в другой домен

"featurecode"

Направить вызов на сервис, определяемый кодами абонентских функций. Конкретный КАФ определяется сопоставлением номера с сущностями featurecode в домене.

"next"

Применить правила модификации номеров и произвести повторную маршрутизацию на основе новых параметров

Среда инициатора звонка

Table 3. Среда инициатора звонка
Значение Описание

"inner"

Правило может быть применено только для звонков, инициированных внутри текущего домена

"outer"

Правило может быть применено только для звонков, пришедших снаружи через учетную запись провайдера в текущем домене

"cross"

Правило может быть применено только для звонков, пришедших из другого домена

"*"

Фильтр не применяется, правило подходит для всех сред инициаторов звонков

Режимы работы фильтров

Table 4. Режимы работы фильтров
Режим Описание

Посимвольный

Подвергаемое проверке соответствия значение посимвольно проводится через фильтр.
Могут применяться следующие спец-символы и сочетания (регистр имеет значение):

  • X – любой символ (верхний регистр);

  • * – все оставшиеся символы;

  • {F} и {f} – исходное значение From username целиком;

  • {T} и {t} – исходное значение To username целиком;

  • {E} и {e} – пустое значение.

  • ? - любой символ (если используется для фильтра по доменным именам, то любой символ кроме точки - разделителя доменных имен).

  • $ - для фильтра по доменам. Любая последовательность символов кроме точки - разделителя доменных имен.

При необходимости указать один из служебных символов как целевой, его следует заключать в квадратные скобки, например [X].

Например, XXX – любое трехсимвольное значение.

Таблица

Может применяться подстрока {tab:…​}. С помощью нее можно выделить группу символов в проверяемом значении и сопоставить их с таблицей, встроенной в правило (opts.tab).
Например, {tab:a} - выделение подстроки и сопоставление ее с полем a всех объектов/строк в таблице.
Таблица служет связке нескольких полей фильтров и модификаторов. На основании последовательной проверки фильтров в таблице остается меньшее количество строк с учетом обнаруженных совпадений.
Первая из оставшихся строк служит для применения в модификаторах. При условии что в таблице не осталось строк - правило отклоняется.
Захват символов из проверяемого значения на основе маски может происходить автоматически, либо со строгим указанием длины подстроки:

  • {tab:KEY} - Автоматический захват из проверяемого значения.

  • {tab:KEY:LENGTH} - Захват указанного количества символов из проверяемого значения.

В качестве значений полей в таблице могут применяться:

  • константы;

  • регулярные выражения (для этого необходимо задать значение в формате /reg/EXPRESSION, например /reg/^1[1-4]$);

  • сопоставления с другими полями таблицы (для этого необходимо задать значение в формате /tab/FIELD, например /tab/a). Режим используется для связывания значений различных полей. Например, чтобы разрешить звонки только на собственный ящик голосовой почты. Необходимо строго соблюдать порядок связывания: если поле таблицы, на которое производится ссылка, еще не проверялось и не было заполнено реальным значением другого поля сущности, то сопоставление не пройдет. Порядок проверки полей сущности: fromnumber, tonumber, fromdomain, fromextaccount, routecode.

  • любое значение, применяемого без регулярного выражения (для этого необходимо задать /any). Режим полезен исключительно при организации прямых сопоставлений со значениями других полей без дополнительных фильтров.

Применение табличного модификатора допускается в комбинации с другими управляющими командами посимвольного режима.
Допускается кратное указание полей в одном модификаторе, повторение, указание несуществующих полей.

Например, {tab:a:3}XXXXX{tab:b} - позволяет выделить в номере 3-символьный код города и сопоставить с полем a в таблице, и одновременно выделить хвост начиная с 9 символа и сопоставить с полем b таблицы.

Regex

К исходному значению применяется шаблон Pattern.

Структура значения regex-шаблона:
/reg/Pattern1.

Например,- значение: "302"
- маска: "/reg/0"
- результат: true.

  • значение: "302"

  • маска: "/reg/^0$"

  • результат: false.

  • значение: "302"

  • маска: "/reg/^302$"

  • результат: true.

  • значение: "302"

  • маска: "/reg/^(301|302|305)$"

  • результат: true.

При формировании шаблонов Pattern могут применяться все стандартные правила регулярных выражений.

Диапазон

Подвергаемое проверке соответствия значение - целое числовое и входит в указанный диапазон числовых значений.

Структура значения dia-шаблона:
/dia/FromValue+N - подпадают под шаблон N+1 значений от FromValue до FromValue+N.

Например,- значение: "302"
- маска: "/dia/300+10"
- результат: true.

Режимы работы модификаторов

Table 5. Режимы работы модификаторов
Режим Описание

Посимвольный

Исходное значение посимвольно с накоплением проходит через указанный модификатор.
Допускается применение следующих спец-символов и сочетаний:

  • ? – захватить текущий символ;

  • * – захватить все оставшиеся символы;

  • X – захватить текущий символ (недоступно при модификации routecode);

  • / в сочетании c ? или X – исключить текущий символ из результата, например /XXX/ исключает 3 текущих символа;

  • T – подставить исходное значение целиком (недоступно при модификации routecode);

  • [ в сочетании с ] – включить в результат служебный символ, расположенный между скобками, например [X];

  • {F} и {f} – включить в результат значение username из заголовка From: SIP-запроса INVITE;

  • {T} и {t} – включить в результат значение username из заголовка To: SIP-запроса INVITE;

  • {B} и {b} – включить в результат значение username из заголовка Referred-By: SIP-запроса INVITE (или иного поставщика инициатора перевода). Применяется только в режиме модификатора аккаунта провайдера.;

  • {E} и {e} – включить в результат пустое значение;

  • любой другой символ захватывается в результат в соответствующую ему позицию.

Например,- значение: "123456"
- From: "9090"
- модификатор: "00/X/XX5[*]67{F}8*"
- результат: "00235*6790908456".

Таблица

Может применяться подстрока {tab:…​}. С помощью нее в модифицируемое значение можно подставить подстроку из указанного поля таблицы (opts.tab).
В качестве источника выступает первая оставшаяся после фильтрации строка в таблице.
Например, {tab:ссс} - подстановка в соответствующую позицию итогового результата значения из поля ccc первой оставшейся строки в таблице.
Если в первой строке/объекте указанное поле отсутствует, то подставляется пустое значение.

Таблица служет связке нескольких полей фильтров и модификаторов. На основании последовательной проверки фильтров в таблице остается меньшее количество строк с учетом обнаруженных совпадений.
Первая из оставшихся строк служит для применения в модификаторах. При условии, что в таблице не осталось строк - правило отклоняется на этапе проверки фильтров.

Применение табличного модификатора допускается в комбинации с другими управляющими командами посимвольного режима.
Допускается кратное указание полей в одном модификаторе, повторения, указания несуществующих полей.

Regex

К исходному значению применяется шаблон Pattern с опциями Opts, и обнаруженный(-ые) блок(-и) заменяется(-ются) на шаблон Replace.
Результат может снова быть подан на следующую операцию Regex-модификации, и так далее конечное число раз.

Общая структура значения regex-модификатора:
/reg/Pattern1/Replace1/Opts1 /reg/Pattern2/Replace2/Opts2 …​.

Опции могут быть опущены, либо содержать любую комбинацию из символов:

  • i – case-insensitive

  • g – global.

Например,- значение: "qwerty,qwerty"
- модификатор: "/reg/t/E/g /reg/qwer/a/"
- результат: "aEy,qwerEy".

При формировании шаблонов Pattern и Replace могут применяться все стандартные правила регулярных выражений, включая группы захвата, поиск назад, подстановку именованных групп и т.д.

Расписание работы

Table 6. Расписание работы
Значение Описание

"all"

Правило доступно для применения всегда

"disabled"

Правило недоступно для применения никогда

"work"

Правило доступно для применения только в рабочее время

"non-work"

Правило доступно для применения только в нерабочее время

"custom"

Правило определяет индивидуальное расписание доступности в поле periods правила

Элемент списка еженедельного расписания

Table 7. Элемент списка еженедельного расписания
Поле Значение Описание

daystart

17

День недели начала отрезка (1 – пн, 7 – вс)

daystop

17

День недели конца отрезка (1 – пн, 7 – вс)

timestart

01440

Время начала отрезка внутри дня в минутах

timestop

01440

Время конца отрезка внутри дня в минутах

См. также

Логические роли

  • b2b проводит маршрутизацию.

  • mdc и sdc производят поиск векторов и правил.