Предыдущая статья курса: Принципы работы служебных сценариев

Общая информация

Все компоненты служебных сценариев разделены на три группы:

Компоненты управления - базовые компоненты, реализующие логику работы сценария, взаимодействие с другими сценариями и работу с переменными
Компоненты работы с данными - сложные компоненты, реализующие механизмы взаимодействия с другими модулями системы, а также внешними сервисами
Компоненты обмена сообщениями - компоненты, реализующие работу с логами, уведомлениями, сообщениями между сценариями, а также голосовой почтой и заказами звонков.

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

Детальную техническую информацию обо всех компонентах сценариев можно найти на портале Vendor.

Общие параметры компонентов

У каждого компонента есть общий набор параметров - Заголовок, Переходы и Описание.

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

Переходы это параметры компонента, определяющие, какой компонент будет выполняться следующим, в зависимости от результата исполнения текущего компонента. Фактически, установка "стрелочек" задаёт параметр Переход. У каждого компонента может быть несколько переходов, в зависимости от возможных исходов его исполнения (например, разные виды ошибок). Для быстрой установки различных переходов можно использовать горячие клавиши 1-9, протягивая стрелочки левой кнопкой мышки.

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

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

Сохранение результата работы компонента

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

Результат в переменную - в данном параметре задаётся переменная сценария, в которую будет сохранен результат выполнения компонента (например, результат парсинга на скриншоте)

Ошибка в переменную - в данном параметре задается переменная сценария, в которую будет сохранен текст ошибки в случае её возникновения. С помощью этой переменной, по "ветке" ошибка можно получить текст ошибки и записать её в лог, или отобразить пользователю.

Описание базовых компонентов

Старт

Компонент, с которого начинается выполнения сценария или его обособленной ветки.

Свойства компонента
Свойство	Описание
`Тип старта`	Тип старта сценария. Возможные значения: `Начало` – основной режим выполнения сценария. Код: `default`. Id: `0`. `Пост-обработка` – режим выполнения сценария в случае завершения основной ветки по одной из возможных причин. Код: `stopping`. Id: `1`.
`Параметр запуска`	Только для Тип старта = Начало Поле для указания переменной, в которую будет записано значение из первого параметра запуска `startparam1`.
`Инициализировать переменные`	Только для Тип старта = Начало Переключатель установки всем переменным сценария значений по умолчанию соответствующего типа.
`Вариант перехода`	Только для Тип старта = Пост-обработка Причина заврешения основной ветки выполнения сценария, по возникновению которой в рамках пост-обработки будет выполнена цепочка компонентов, следующих за текущим компонентом СТАРТ. Возможные значения: `Все` (`all`, `0`) – любая причина завершения сценария. `Корректное завершение` (`normal`, `1`) – сценарий завершен компонентами, не имеющими веток перехода (Стоп, Переводы и т.д.). `Нет ветки перехода` (`transfer_not_set`, `2`) – не назначено необходимое свойство перехода у компонента основной ветки сценария. `Внешняя остановка` (`stop`, `3`) – сценарий принудительно завершен (через API). `Таймаут` (`timeout`, `4`) – не используется. `Ошибка компонента` (`error`, `5`) – критическая ошибка выполнения компонента. `Отсоединение владельца` (`ownerdown`, `6`) – завершение связанного процесса владельца, например FSM диалога звонка для IVR сценария (для IVR сценария в том числе отбой со стороны абонента). `Лимит числа компонентов` (`maxcount`, `7`) – достижение ограничения по количеству выполненных компонентов, установленного для доменаа. `Лимит времени выполнения` (`maxduration`, `8`) – достижение ограничения по времени выполнения сценария, установленного для домена.
`Время выполнения всего сценария`	Только для Тип старта = Пост-обработка Ограничение на выполнение сценария в рамках ветки пост-обработки, в миллисекундах. По истечении сценарий принудительно завершится.

Стоп

Завершает выполнение ветки сценария корректным образом. Обеспечивает возврат управления из вложенного сценария в вышестоящий сценарий.

Свойства компонента
Свойство	Описание
`Возврат управления`	Разрешает или запрещает дальнейшую передачу управления предыдущему сценарию в стеке вложенных сценариев при завершении текущего, при условии, что он вложенный. Возврат произойдет только в том случае, если значение поля – `Да` и запуск текущего сценария был осуществлен компонентом с включенным режимом возврата управления.
`Результат`	Аргумент, содержащий результат, возвращаемый сценарием назад по стеку вызовов. Это сохраняется в переменную родительского сценария, указанную в поле 'Результат в переменную' компонента 'Запуск сценария'. Также заносит значение в переменную с именем "result", если она существует в сценарии. Эта переменная в ряде функций передает значение из сценария в вышестоящую логику. Например, сценарий внешней авторизации.

Пауза

Осуществляет задержку сценария перед выполнением следующего компонента. В случае указания нулевого таймаута – компонент пропускается.

В некоторых случаях при работе с большими сценариями удобно использовать компонент «Пауза» в качестве пустышки. Для выравнивания визуального представления сценария, для удобства и быстроты смены свойств. Например, по веткам выхода из компонента «Меню», где каждое свойство перехода задается внутри специального окна путем выбора одного объекта из списка всех объектов сценария.

Свойства компонента
Свойство	Описание
`Время, мс`	Длительность паузы, в миллисекундах. В случае отрицательных значений компонент работает в синхронном режиме. В случае `0` компонент работает в асинхронном режиме с нулевым ожиданием.
`Очистить события`	Определяет поведение компонента с очередью необработанных событий. Необработанные события накапливаются в очереди, если исполняемый во время поступления события компонент не призван их обрабатывать, и остаются в очереди до тех пор, пока очередной компонент не обработает их (или не завершится сценарий). Обрабатывать события могут только асинхронные компоненты, то есть проводящие асинхронные операции и ожидающие событий. К множеству рассматриваемых событий НЕ ОТНОСЯТСЯ события, обрабатываемые самой скрипт-машиной, например события межсценарного взаимодействия, подмены сценариев, завершения или подмены владельца и т.д. К накапливаемым событиям относятся: Входящие ДТМФ сигналы; Входящие SIP-сообщения INFO; Входящие SIP-сообщения MESSAGE; Компонент ПАУЗА в режиме накопления собирает в очередь все прочие поступающие на обработку в компоненты события. Возможные значения: `Нет` (`no`,`0`) - необработанные события накапливаются и добавляется в конец текущей очереди необработанных событий, доставшейся от предыдущих комонентов. `Да` (`yes`,`1`) - накопленные необработанные события сбрасываются, а новые не сохраняются вплоть до передачи управления следующему компоненту. Использование компонента с нулевым таймаутом и режимом очистки очереди событий может применяться в тех местах сценария, где с точки зрения логики важно сбросить накопленные хвосты. Например введенные ранее DTMF сигналы.
`Сохранить состояние сценария`	Включение режима сохранения состояния сценария IVR для возможного дальнейшего восстановления разговора с продолжением обслуживания с сохраненной позиции. Возможные значения: `Нет` (`no`,`0`) - обычная пауза. `Да` (`yes`,`1`) - производится сохранение состояния. Применяется совместно с режимом sip_restore_enabled. Имеет смысл только для IVR сценариев. Если состояние сценария не сохранялось, то при восстановлении разговора (в случае пропадания ноды IVR или падения сервера с нодой IVR) сценарий начнется с самого начала от момента маршрутизации сценария на фичакод. Состояние включает весь стек вложенных вызовов, значения всех локальных переменных, стартовые параметры, хранилище, код сценария, номер компонента, время начала, счетчики и т.д. Метаданные сценария не хранятся. Исполнение начнется непосредственно с компонента, следующего за текущим компонентом 'Пауза', исполняющим сохранение. Сценарий будет загружен из доменного центра, поэтому если он существенно изменился (сбились номера компонентов или отсутствует сохраненный номер компонента), то корректное продолжение выполнения будет невозможно. Состояние может быть объемным, операция сохранения состояния не должна применяться после каждого компонента в длинных интенсивных циклах без пауз. При завершении обработчика сценария сохраненное состояние автоматически удаляется из хранилища. Сеанс вызова при восстановлении разговора сохраняется вне зависимости от того, сохранялось ли состояние сценария IVR. Состояние сохраняется в объектное хранилище, управляемое микросервисом store. Если количество сохранений заведомо большое, и микросервис store нагружается, следует его размножать на сайте. Восстановленный экземпляр обработчика сценария утрачивает связь с временными файлами предыдущего обработчика, использованными им в макро-путях :TEMP и :LOCAL. Функция getscriptref() нового экземпляра имеет новое значение. Контекст может восстанавливаться произвольное количество раз.

Сравнение

Сравнивает значения двух аргументов. Компонент осуществляет ветвление внутри сценария. В случае соответствия выбранной логической операции и значений аргументов переход осуществляется по ветке «Правда», в противном случае – по ветке «Ложь».

Свойства компонента
Свойство	Описание
`Аргумент 1`	Операнд 1
`Аргумент 2`	Операнд 2
`Тип сравнения`	Логическая операция между Операндами. Возможные значения: `<` (`0`) – Строго меньше. `=<` (`1`) – Меньше или равно. `==` (`2`) – В точности равно. `>=` (`3`) – Больше или равно. `>` (`4`) – Строго больше. `=/=` (`5`) – Не равно. При сравнении значений разных типов осуществляется их предварительное преобразование к одному типу.
`Переход, правда`	Компонент, которому передается управление в случае истинности операции.
`Переход, ложь`	Компонент, которому передается управление в случае ложности операции.

Сравнивает аргумент со списком значений. Компонент осуществляет ветвление внутри сценария. Может иметь неограниченное число веток перехода. Переход осуществляется по ветке значения, с которым совпало значение аргумента. Если совпадений не найдено, переход осуществляется по ветке «Прочее».

Свойства компонента
Свойство	Описание
`Аргумент`	Операнд, подлежащий сопоставлению с перечнем значений
`Значения`	Набор вариантов значений для операнда и соответствующих им веток перехода.
`Переход, прочее`	Компонент, которому передается управление в случае, если операнд не был сопоставлен ни с одним из перечисленных вариантов.

Присвоение

Задает значение указанной переменной. В качестве присваемого значения выступает аргумент. Используется механизм преобразования типов, если типы значения аргумента и переменной не совпадают. Допускает присвоение значений нескольким переменным.

Свойства компонента
Свойство	Описание
`Режим`	Режим работы компонента по количеству одновременных операций присвоения Возможные значения: `Одиночный` (`single`,`0`) `Множественный` (`multi`,`1`)
`Переменная`	Только для Режим=Одиночный Переменная - назначение для одиночного присвоения.
`Значение`	Только для Режим=Одиночный Аргумент, поставляющий значение для одиночного присвоения.
`Операции`	Только для Режим=Множественный Список последовательно выполняющихся операций присвоения, где каждой переменной сопоставляется отдельный аргумент. Одной и той же переменной может быть присвоено значение многократно.

Мьютекс

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

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

Ожидание захвата может быть прервано по таймауту, при этом происходит отказ от захвата.

Критическая секция будет удерживаться до одного из событий:

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

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

Свойства компонента
Свойство	Описание
`Ключ`	Аргумент, содержащий имя критической секции.
`Действие`	Выбор действия над критической секцией. Возможные значения: `Заблокировать` (`lock`, `1`) – Дождаться очереди и захватить критическую секцию. `Освободить` (`unlock`, `2`) – Освободить критическую секцию.
`Тип операции`	Выбор типа блокируемой операции. Операции чтения могут взаимно не блокироваться (например узнать значение глобальной переменной), однако операции изменения (сначала взятие значения глобальной переменной, потом преобразование и затем сохранение глобальной переменной) требуют полной блокировки критической секции. Возможные значения: `read` (`read`, `1`) – Операция чтения. Все операции чтения получают одновременный доступ до тех пор, пока в очередь не встанет операция записи. `write` (`write`, `2`) – Операция записи. Любая операция записи получает индивидуальную блокировку критической секции под процесс обработчика сценария. Применяется для захвата.
`Время ожидания, мс`	Аргумент, содержащий таймаут в миллисекундах, после истечения которого ожидание захвата следует прекратить. Управление возвращается по ветке таймаута. Применяется для захвата`.
`Гарантированное время освобождения, мс`	Аргумент, содержащий время удержания блокировки в миллисекундах, по истечении которого критическая секция гарантированно освободится без ожидания других событий. Применяется для захвата.

Запуск сценария

Обеспечивает процессное или функциональное ветвление на уровне сценариев.

В случае организации автоматических сервисов размеры сценария могут быть достаточно велики, и компонент «Запуск сценария» предоставляет возможность разбить крупный сценарий на несколько логических блоков. Таким образом, один сценарий передает управление в начало другого сценария. При этом можно задать некоторое значение на запуск, которое примет компонент «Старт» вложенного сценария и сохранит в свою локальную переменную. Помимо этого, все переменные одного типа, которые названы одинаково в запускающем и запускаемом сценариях, перенесут свои значения из одного в другой без изменений. Такой способ запуска называется вложенным.

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

Свойства компонента
Свойство	Описание
`Режим`	Режим запуска дочернего сценария. Возможные значения: `Вложенный` (`sub`,`0`) – Вложенный с объединением переменных. Запускается в том же обработчике, приостанавливая выполнение текущего сценария и передавая вложенному сценарию весь набор накопленных значений локальных переменных и других контекстов. После завершения вложенного сценария может быть осуществлен возврат управления при одновременном выставлении свойства 'Возврат управления' в текущем компоненте и в компоненте Стоп вложенного сценария. Поскольку переменные общие, то все измененные значения локальных переменных транслируются обратно в передавший управление сценарий. Допускается каскадная вложенность сценариев глубиной до 100 уровней. `Влож. без переменных` (`sub_split_vars`,`2`) – Вложенный без объединения переменных. Запускается в том же обработчике, приостанавливая выполнение текущего сценария и передавая вложенному сценарию параметры вызова, доступные там через функцию выражений 'startparam/1'. Значения переменных не передаются внутрь и не возвращаются назад. После завершения вложенного сценария может быть осуществлен возврат управления при одновременном выставлении свойства 'Возврат управления' в текущем компоненте и в компоненте Стоп вложенного сценария. При возврате назад, может передать результат, установленный компонентом 'Стоп'. Это значение поступает в виде аргумента для сохранения в переменную, указанную в поле 'Результат в переменную'. Все локальные переменные сценария, передавшего управление вложенному, сохраняют свои значения на момент передачи управления. Допускается каскадная вложенность сценариев глубиной до 100 уровней. `Асинхронный служебный` (`async`,`1`) – Запускается новый экземпляр обработчика служебного сценария. Запущенный сценарий получает весь набор накопленных на текущий момент переменных и их значений на вход. При совпадении имен переменных производится заполнение их значений вне зависимости от того, на каком уровне вложенности внутри нового обработчика используется сценарий с совпавшим именем переменной. Исполнение производится на произвольном сервере текущего сайта с ролью svc. `Асинх. без переменных` (`async_split_vars`,`3`) – Асинхронный служебный без копирования значений переменных. Запускается новый экземпляр обработчика служебного сценария. Исполнение производится на произвольном сервере текущего сайта с ролью svc. Запущенный сценарий инициализирует значения переменных без копирования накопленных на момент вызова значений из текущего сценария. Асинхронному сценарию могут быть переданы несколько параметров вызова, доступные там через функцию выражений 'startparam/1'.
`Источник сценария`	Способ выбора сценария для запуска. Возможные значения: `Вложенный` (`code_sel`,`0`) – Выбор вложенного сценария из списка. `Асинхронный служебный` (`code`,`1`) – Указание кода сценария с помощью аргумента.
`Сценарий`	Выпадающий список с кодами сценариев. Содержит все доступные (нескрытые) сценарии того же типа, что и текущий сценарий, содержащиеся в текущем домене.
`Сценарий`	Выпадающий список с кодами сценариев. Содержит все доступные (нескрытые) служебные сценарии, содержащиеся в текущем домене.
`Код сценария`	Аргумент, определяющий код запускаемого сценария. Может указывать также коды скрытых сценарии. При отсутствии сценария с указанным кодом, управление передается по ветке ошибки. В мастер-домене в качестве кода сценария может быть указано значение `"DOMAIN @ SCRIPT_CODE"`, где в качестве домена указывается название любого домена кластера, а в качестве кода - код содержащегося в этом домене сценария. Такой режим используется для запуска контекстных сценариев звонка в домене и трансляции ему событий: поскольку звонок не принадлежит домену, то контекстный сценарий запускается в мастер-домене. Настройка контекстного сценария производится в настройках мастер-домена.
`Ид в переменную`	Переменная для сохранения значения идентификатора запущенного сценария, по которому можно производить взаимодействие.
`Возврат управления`	Разрешает или запрещает возврат управления из вложенного сценария и продолжение работы по ветке дальше.
`Значения переменных`	Таблица начальных значений для локальных переменных запускаемого сценария. Доступно только если выбранный режим отличается от "вложенного с объединением переменных". Ключи - названия переменных запускаемого сценария. Сопоставление происходит по именам переменных, значения присваиваются только тем переменным, которые определены в сценарии. Если запускаемый сценарий передает управление вложенному, то присвоение значений каждой из указанных переменных производится не более одного раза, но может откладываться вплоть до загрузки вложенного сценария, имеющего переменную с соответствующим именем. Установленные таким образом значения приоритетны перед значениями по умолчанию внутри запускамого сценария.
`Параметр 1 - Параметр 10`	Параметры для асинхронного служебного сценария. Доступ к значению осуществляется через функцию выражений `startparam(n)` , где n - номер параметра, или через сохранение значения в компоненте Старт (только для первого)
`Прочие параметры`	JSON-массив, содержащий параметры 11, 12 и т.д. для асинхронного служебного сценария. Доступ к значению осуществляется через функцию выражений `startparam(N)`, где N > 10.

Блок кода JavaScript

Осуществляет выполнение кода JS, заданного аргументом, в микросервисе продуктового слоя.

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

Внутри тела могут выполняться любые действия с примененмем переданного объекта в контексте продуктового слоя.

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

Пример:

return { a: x + y.name + z[0].caption };

для переданных переменных или параметров

x = "abc"

 y = {"name": "def"}

z = [{"caption": "ghi"}]

вернет "abcdefghi" и присвоит в существующую переменную сценария 'a', а также тело "{ a: "abcdefghi" }" в переменную возвращающую результат, если она задана.

При необходимости можно выполнять асинхронный запрос:

return async function() { await GlobalUtils.wait(500); return { a: 1, b: x }; }

Свойства компонента
Свойство	Описание
`Код JS`	Код JS функции для исполнения в node.js в окружении микросервиса продуктового слоя.
`Способ задания параметров`	Переключает режим задания параметров для среды выполнения. Возможные значения: `Все переменные` (`allvars`,`0`) - передаются все переменные с их значениями. В коде JS можно обращаться к ним напрямую по именам. `Заданные аргументы` (`args`,`1`) - свойством 'Аргументы' задается перечень именованных передаваемых параметрах. В коде JS можно обращаться к ним по указанным именам. При передаче значений JSON-строки представляющие собой объекты доступны в коде как объекты, JSON-массивы - как массивы, строки и числа по умолчанию, даты в виде строки, а незаполненные значения остаются незаполненными (null).
`Аргументы`	Список передаваемых параметров и их имен. Доступ к ним из выполняемого кода через имена как к обычным переменным. Если значение представляет собой JSON-строку с объектом или массивом, то в коде JS при обращении к соответсвующей переменной будет доступен непосредственно объект или массив.
`Таймаут, сек`	Аргумент, определяющий таймаут выполнения кода в ноде JS. По истечении таймаута сценарий передает управление по ветке 'Переход, таймаут', а код продолжает выполняться.

Следующая статья курса: Компоненты работы с данными

Предыдущая статья курса: Принципы работы служебных сценариев