Очередь ожидания (hunt)

Описание

Дескриптор очереди ожидания. В качестве ресурсов очереди назначаются SIP-пользователи.

Обслуживается ролью huntq, которая на основании дескрипторов выстраивает очереди ожидания, следит за состояниями ресурсов и соединяет ожидающие объекты с ресурсами на основе настроенных стратегий.
В очередь могут быть размещены звонки. Размещением звонков в очереди управляет роль IVR посредством КАФ (featurecode) с типом 'hunt' и 'queue'.

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

Объект может представлять собой шаблон, на основании которого динамически выстраиваются дескрипторы очередей в момент поступления вызова на код абонентской функции "queue".
Так, одним экземпляром сущности hunt можно настроить единый формат разных очередей для нескольких (или всех) объектов - пользователей или групп. Сущность рассматривается как шаблон, если значение поля 'opts.template_type' указано 'personal' или 'group'.
При поступлении вызова на очередь постфикс набираемого номера (extension) рассматривается как номер, по которому сначала ищется конкретная сущность hunt, затем ищется шаблон, затем выстраивается динамический дескриптор со стандартными значениями по умолчанию.
Будет ли применен конкретный шаблон для динамического построения на базе него дескриптора зависит от заданного типа ('opts.template_type') и маски номера ('opts.filter_number'). Конкретно, удовлетворяет ли маска, заданная в поле 'opts.filter_number' (и опционально 'opts.tab'), расширению набранного номера. Если удовлетворяет, то обнаруживается учетная запись sipuser или sipgroup с исследуемым номером в зависимости от того, какой тип шаблона указан в поле 'opts.template_type'.

Ограничения

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

  • Лицензируется количественным параметром: расходуется лицензия на количество ресурсов выбранного типа.

Поля

Структура сущности
{
  "id": uuid,
  "code": str,
  "phonenumber": str,
  "priority": int,
  "type": str,
  "resourses": array<object>,
  "strategy": object,
  "resmode": str,
  "objmode": str,
  "weight": int,
  "wivrscript": str,
  "qivrscript": str,
  "preivrscript": str,
  "reslimit": int,
  "maxattempts": int,
  "maxattemptstrannumber": str,
  "resdialtimeout": int,
  "timeout": int,
  "timeouttrannumber": str,
  "displayname": str,
  "huntblock": object,
  "resbansec": int,
  "opts": {
    "title": str,
    "comment": str,
    "exit_no_resource": bool
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Поля
Спецификация Описание

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

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

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

Код. Используется для ассоциирования с другими сущностями. Уникальное значение.

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

Телефонный номер.
Применяется и обязательное поле при type = sipuser.

Является ключом при поиске сущности во время поступления звонка на КАФ (featurecode) типа 'hunt'.
При использовании сущности в качестве явного заданного дескриптора персональной или групповой очереди (КАФ типа 'queue'), номер должен совпадать с номером соответствующей учетной записи sipuser или sipgroup.

При формировании шаблона поле не используется и заполняется автоматически.

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

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

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

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

Список ресурсов (участников) в очереди с указанием их приоритета. Состав полей элемента списка.

Поле: strategy
Режим: in
Тип: object
По умолчанию: {"mode": "simple"}

Стратегия добавления участников для объекта (абонента). Состав полей.

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

Стратегия выбора ресурса (участника) из числа свободных ресурсов при поступлении нового объекта в пустую очередь

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

Стратегия выбора объекта очереди при освобождении ресурса

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

Вес очереди.
Используется при освобождении ресурса для выбора следующего объекта (абонента) для обслуживания в случае, если номер участвует в нескольких очередях с одинаковым приоритетом (wfq).

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

Код IVR-сценария приветствия в очереди звонков.
Применется при type = sipuser.

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

Код IVR-сценария ожидания в очереди звонков.
Применется при type = sipuser.

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

Код IVR-сценария предварительного воспроизведения участнику очереди звонков после его ответа перед соединением с абонентом.
Применется при type = sipuser.

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

Количество одновременно выдаваемых ресурсов.
0 – специальное ограничение не установлено, поведение напрямую соответствует значению strategy.
Любое положительное значение устанавливает strategy в timers с указанием заданного количества нулей.

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

Максимально допустимое количество вызовов ресурсов (участников).
В любом случае очередь не выдаст более указанного количества инициатив на вызов ресурсов, вне зависимости от того, как настроена стратегия.
После достижения и отказа по последнему из вызываемых ресурсов произойдет отбой из очереди.
В случае type = sipuser дополнительно может быть произведено переключение на номер maxattemptstrannumber.

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

Номер для переключения при превышении попыток maxattempts.
Применяется при type = sipuser.

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

Продолжительность попытки дозвона в секундах.
0 – специальное ограничение не установлено.
Применяется только при type = sipuser, и работает только в сторону уменьшения таймаута относительно установленного в настройках SIP-пользователя.

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

Максимальное время ожидания в очереди в секундах

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

Номер для переключения при превышении максимального времени ожидания.
После таймаута происходит отбой из очереди.
Применяется при type = sipuser.

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

DislpayName, подставляемый в звонок из очереди к ресурсу.
Применется при type = sipuser.

Поле: huntblock
Режим: in
Тип: object
По умолчанию: {"enabled": false}

Режим применения временного запрета использования ресурса типа SIP-пользователь после завершения обслуживания звонка.
Опциональные поля в структуре:
- expires – время установки состояния,
- reason – причина установки состояния.

Пример:
{
  "enabled": false,
  "expires": 20,
  "reason": "Поствызов"
}

Применется при type = sipuser.

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

Время в секундах, на которое ресурс (участник) становится заблокированным в связи с неудачей соединения.
Минимально допустимое значение – 10, максимально – 86400.

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

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

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

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

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

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

Признак прекращения ожидания при отсутствии доступных ресурсов

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

Выключатель режима early-media во время ожидания в очереди.
При включенном режиме при звонке на HUNT-номер отправляется ответ "183 Session Progress", а SIP-ответ "200 ОК" отправляется только в момент соединения с вызываемым абонентом.
Исключение составляет случай, когда SIP-ответ "200 ОК" отправляется в сценарии приветствия или ожидания в очереди, которые могут быть настроены администратором и назначены для использования в HUNT-номер.

При вызовах из внешней сети провайдеры могут ограничивать время пребывания в состоянии Early Media, например 20 секундами, после чего производит обрыв сеанса.
Если известно, что подключенный провайдер связи ограничивает, то следует:

  • либо держать флаг выключенным для всех случаев;

  • либо использовать настроенный администратором сценарий приветствия или ожидания в очереди, внутри которого производить разветвление и отсчет времени. Это необходимо для того, чтобы все внешние вызовы, поступившие через провайдера, получили SIP-ответ "200 ОК" в установленный период и не были отбиты провайдером.

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

Режим шаблона. По умолчанию не используется. Варианты значений:

  • none - не используется в качестве шаблона. Используется напрямую в качестве статического дескриптора.

  • personal - используется в качестве шаблона персональной очереди. Шаблон применяется для номеров, которые подходят по маске, заданной в поле 'opts.filter_number' и одновременно принадлежат учетным записям sipuser.

  • group - используется в качестве шаблона групповой очереди. Шаблон применяется для номеров, которые подходят по маске, заданной в поле 'opts.filter_number' и одновременно принадлежат учетным записям sipgroup.

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

Маска-фильтр номера, которому принадлежит правило переадресации.
Это может быть напрямую указанный номер учетной записи SIP-пользователя – в этом случае правило индивидуального применения.
Но также может быть указана маска поискового фильтра.
Режимы работы фильтра.

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

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

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

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

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

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

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

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

Типы очередей

Table 2. Типы очередей
Значение Описание

"user"

Все ресурсы являются идентификаторами объекта user.
Используется в чат-центре.

"sipuser"

Все ресурсы являются идентификаторами объекта sipuser.
Используется при маршрутизации на КАФ (featurecode) с type = hunt

Состав полей элемента списка ресурсов

Table 3. Состав полей элемента списка ресурсов
Поле Тип значения Описание

id

uuid

Идентификатор ресурса (участника) – sipuser или user

priority

int

Приоритет ресурса (участника) в момент применения resmode

Состав полей стратегии

Table 4. Состав полей стратегии
Поле Тип значения Описание

mode

uuid

Название стратегии:

  • simple – один объект получает только один ресурс единовременно,

  • timers – один объект может получить несколько ресурсов единовременно.

seconds

array<int>

Список временных сдвигов начала вызова следующего ресурса (участника), начиная со второго.
Применяется только для mode = timers

Стратегии выбора ресурса (участника)

Table 5. Стратегии выбора ресурса (участника)
Значение Описание

"priorityrandom"

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

"random"

Выбирает случайный ресурс из свободных на данный момент

"cascade"

Выбирает из свободных ресурсов ровно в том порядке, как они указаны в списке в поле resources

Стратегии выбора объекта (абонента)

Table 6. Стратегии выбора объекта (абонента)
Значение Описание

"spq"

(Strict Priority Queueing) – режим выбора очереди на основании priority

"wfq"

(Weighted Fair Queueing) – режим выбора очереди на основании weight

"spqwfq"

режим выбора очереди, на основании priority, а среди одинаковых по weight

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

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

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

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

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

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

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

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

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

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

Таблица

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

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

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

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

  • константы;

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

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

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

См. также

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

  • huntq производит процессинг очередей.

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