Правило преобразования CallerId и CalledId (provider_callerid)

Описание

Правило преобразования CallerId и CalledId для учетных записей провайдеров SIP-телефонии.
Применяется в качестве адаптера внешних и внутреннего номерных планов. В частности при модификации CallerId внутренних абонентов для отправки наружу происходит адаптация во внешний номерной план, а при модификации CallerId внешних абонентов для отправки внутрь системы происходит адаптация к внутреннему номерному плану, то есть подготовка данных к процессу маршрутизации.

Обнаруженное правило модификации применяется для модификации и From username (number), и To username (number). В случае необходимости разделить модификации для сокращения количества правил, в качестве модификатора для To может быть применен специальный указатель "priority" (сначала применяется правило для FromNumber, а затем ищется и применяется правило для ToNumber, но с priority большим или равным исходному правилу и с фильтром по уже измененному FromNumber).

Настроенная совокупность правил преобразования CallerId может быть протестирована через диагностическое API. Однако следует иметь в виду, что существует разница применения в тесте и в звонке за счет того, что в звонке номер To берется из Request-Uri, а также при совпадении значения с username учетной записи сущности, в качестве номера для модификации подставляется пустая строка.

Ограничения

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

Поля

Структура сущности
{
  "id": uuid,
  "priority": int,
  "dir": str,
  "idprovider": uuid,
  "providercode": str,
  "fromdomain": str,
  "fromnumber": str,
  "tonumber": str,
  "modfromdisplay": str,
  "modfromnumber": str,
  "modtonumber": str,
  "ext": {
    "ct": date,
    "lwt": date
  },
  "opts": {
    "title": str,
    "comment": str
  }
}

Описание характеристик спецификации

Table 1. Поля
Спецификация Описание

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

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

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

Приоритет правила. Меньшее значение означает более высокий приоритет.

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

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

Поле: idprovider
Режим: in
Тип: uuid | str_empty
По умолчанию: str_empty

Фильтр по идентификатору провайдера SIP-телефонии.
Применение этого фильтра кратно повышает скорость поиска правила.

Чтобы задать конкретного провайдера, очистите предварительно маску в поле 'providercode'.

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

Маска-фильтр для кода провайдера SIP-телефонии.
Режимы работы фильтров.

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

Маска-фильтр адреса/домена инициатора звонка (заголовок From SIP-запроса INVITE).
Режимы работы фильтров.

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

Маска-фильтр номера/username инициатора звонка (заголовок From SIP-запроса INVITE).
Режимы работы фильтров.

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

Маска-фильтр номера/username назначения (заголовок To SIP-запроса INVITE).
Режим работы фильтров.

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

Режим работы модификаторов from_username, from_displayname, to_username.
Позволяет переключить обычный режим работы модификаторов (раздельно каждое поле с помощью строкового модификатора) на служебный сценарий.

Возможные варианты:

  • mask - обычный режим работы с помощью раздельного последовательного применения строковых модификаторов к соответствующим значениям.

  • svcscript - модификация трех полей происходит в одном служебном сценарии, код которого задан в поле mod_svcscriptcode.

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

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

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

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

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

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

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

Код служебного сценария модификации номеров CallerId и CalledId.
Служебный сценарий выполняется однократно и сразу возвращает три значения с помощью переменных со специальными именами:

  • from_username - номер абонента инициатора (заголовок From, поле username в URI);

  • from_displayname - имя абонента инициатора (заголовок From, поле displayname);

  • to_username - набранный номер (заголовок To, поле username в URI).

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

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

В качестве стартовых параметров в сценарий передаются:

  • 1 - код учетной записи провайдера

  • 2 - направление вызова ('inside' или 'outside')

  • 3 - From username

  • 4 - From domain

  • 5 - From display_name

  • 6 - To username

  • 7 - To domain

  • 8 - Diversion username. Если заголовок Diversion отсутствует - пустая строка, если их несколько то первый (последний назначенный).

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

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

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

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

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

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

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

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

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

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

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

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

Время последней модификации объекта

Направление применения правила

Table 2. Направление применения правила
Значение Описание

"inner"

В сторону от внутреннего абонента к внешнему. Правило применяется к данным внутреннего абонента при передаче их в сторону внешнего абонента.

"outer"

В сторону от внешнего абонента к внутреннему. Правило применяется к данным внешнего абонента при передаче их в сторону внутреннего абонента.

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

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

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

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

  • X – любой символ;

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

  • ? – любой символ (если используется для маски по имени домена, то любой символ кроме точки);

  • $ – любое количество символов до ближайшей точки.

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

Таблица

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

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

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

В качестве значений полей в таблице могут применяться:
* константы;
* регулярные выражения (для этого необходимо задать значение в формате /reg/EXPRESSION, например /reg/^1[1-4]$);
* сопоставления с другими полями таблицы (для этого необходимо задать значение в формате /tab/FIELD, например /tab/a). Режим используется для связывания значений различных полей. Например, чтобы разрешить звонки только на собственный ящик голосовой почты. Необходимо строго соблюдать порядок связывания: если поле таблицы, на которое производится ссылка, еще не проверялось и не было заполнено реальным значением другого поля сущности, то сопоставление не пройдет. Порядок проверки полей сущности: fromnumber, fromdomain, tonumber.
* любое значение, применяемого без регулярного выражения (для этого необходимо задать /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 4. Режимы работы модификаторов
Режим Описание

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

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

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

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

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

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

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

  • {C} – включить в результат код учетной записи провайдера SIP-телефонии;

  • {c} – включить в результат lowercase код учетной записи провайдера SIP-телефонии;

  • {U} – включить в результат username учетной записи провайдера SIP-телефонии;

  • {u} – включить в результат lowercase username учетной записи провайдера SIP-телефонии;

  • {D} – включить в результат displayname учетной записи провайдера SIP-телефонии;

  • {d} – включить в результат lowercase displayname учетной записи провайдера SIP-телефонии;

  • {F} – включить в результат username из заголовка From;

  • {f} – включить в результат lowercase username из заголовка From;

  • {T} – включить в результат username из заголовка To;

  • {t} – включить в результат lowercase username из заголовка To;

  • {DIV} – включить в результат username из заголовка Diversion (пустая строка при отсутствии);

  • {div} – включить в результат lowercase username из заголовка Diversion (пустая строка при отсутствии);

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

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

Например,- значение: "123456"
- From displayname: "Abonent"
- Code: "R1"
- модификатор: "00/X/XX5[*]67{E}8?*{d}{C}"
- результат: "00235*678456abonentR1".

Таблица

Может применяться подстрока {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 могут применяться все стандартные правила регулярных выражений, включая группы захвата, поиск назад, подстановку именованных групп и т.д.

"priority=…​"

Режим реализован в задаче #192.
Для модификаторов To: username допускается указание в качестве модификатора значения priority=X, где X - любое неотрицательное число.
Тем самым процесс модификации CallerId и CalledId становится следующим:

(1) Ищется правило R1 по начальным From и To.

(2) Из него применяется модификатор к From.

(3) Если модификатор To равен 'priority=X', где X - любое неотрицательное число, то

(3.1.1) ищется новое правило R2 по новому From и начальному To, с приоритетом, начиная с указанного X.

(3.1.2) модификатор To из правила R2 применяется к начальному To.

(3.2) иначе применяется модификатор To правила R1 к начальному To.

Алгоритм построении компактного набора правил преобразования CallerId и CalledId может быть следующим:

(1) Действовать как обычно.

(2) Если возникает потребность сократить M*N правил до M+N, то

(2.1) Выделить M правил модификации From с высокими приоритетами, в них установить в значения модификаторов To в значения 'priority=X'.

(2.2) Создать еще N правил, где фильтры From соответствуют результату модификации From, либо *, и задать модификаторы To.

(2.3) В случае, когда для определенных значений не требуется модификация From, то либо сразу модифицировать To, либо указывать priority=X, где X больше приоритета текущего правила.

См. также

API

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт