Правило представления (representative)

Описание

Правило представления номера (и опционально displayname) при звонке из одного домена в другой.
Позволяет определить, какой номер инициатора звонка увидит абонент из другого домена. И соответственно, куда будет направлен обратный вызов при нажатии REDIAL.
Применяется в случаях организации общего номерного плана у нескольких доменов.

Процесс поиска представления состоит из трех последовательных этапов, каждый из которых в случае успеха прерывает процесс, а в случае неудачи передает управление следующему этапу.
(1) В домене вызываемого абонента ищется подходящее CROSS правило.
(2) В домене абонента, переадресовавшего вызов, ищется подходящее INNER правило.
(3) В домене инициатора звонка ищется подходящее INNER правило.
(4) В домене первого уровня (относительно домена инициатора звонка) ищется подходящее GLOBAL правило.
В случае неудачи на всех этапах, подставляется номер "undefined". По умолчанию во вновь создаваемые домены автоматически добавляется правило, подставляющее номер инициатора без изменения
Правила настройки глобального номерного плана должны ориентироваться на приведенную последовательность этапов.

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

Ограничения

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

Поля

Структура сущности
{
  "id": uuid,
  "priority": int,
  "dir": str,
  "ofdomain": str,
  "ofusername": str,
  "ofnumber": str,
  "fordomain": str,
  "forusername": str,
  "fornumber": str,
  "action": str,
  "modifier": str,
  "opts": {
    "title": str,
    "comment": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Поля
Спецификация Описание

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

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

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

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

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

Фильтр по направлению применения.
В соответствии с приведенным в описании процессом поиска правил представления каждое направление привязывает правило к конкретному этапу его применения.

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

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

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

Маска-фильтр username инициатора звонка.
Режимы работы фильтров.

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

Маска-фильтр номера инициатора звонка.
Режимы работы фильтров.

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

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

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

Маска-фильтр username вызываемого абонента.
Режимы работы фильтров.

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

Маска-фильтр номера вызываемого абонента.
Режимы работы фильтров.

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

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

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

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

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

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

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

Действие, определяемое правилом.

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

Модификатор номера источника.
Используется если поле action = "apply".
Режимы работы модификатора.

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

Модификатор имени источника в поле DisplayName.
Используется если поле action = "apply".
На вход подается подготовленное имя пользователя - результат применения имени учетной записи sipuser к поступившему в запросе/ответе DisplayName.
В большинстве стандартных случаев задание модификатора имени не требуется.
Режимы работы модификатора.

Поле: 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. Варианты фильтров по направлению применения
Значение Описание

"cross"

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

"inner"

Правило применяется:

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

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

"global"

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

"*"

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

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

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

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

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

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

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

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

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

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

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

Например, XX[X] – любое трехсимвольное значение, с символом X на конце.

Таблица

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

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

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

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

  • константы;

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

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

  • любое значение, применяемого без регулярного выражения (для этого необходимо задать /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. Действия
Значение Описание

"apply"

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

"abort"

Прерывает текущий этап поиска и передает управление на следующий этап

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

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

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

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

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

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

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

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

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

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

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

  • {T} и {t} – включить в результат значение username вызываемого абонента;

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

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

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

Таблица

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

См. также

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

  • b2b проводит маршрутизацию и применение правил представления.

  • esg проводит маршрутизацию и применение правил представления.

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