Общая логика обработки сценариев Аксател

В Аксател реализовано два типа сценариев:

• IVR сценарии - сценарии, участвующие в SIP диалогах и являющиеся одной из сторон разговора

• SVC сценарии - сервисные сценарии, выполняющие определённые действия и запускаемые по расписанию или по событиям.

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

Сценарий состоит из компонентов. Обработчик сценариев включает в себя алгоритмы реализации функциональности компонентов.

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

1. загружает сценарий,

2. создает области данных для хранения объявленных переменных,

3. отыскивает в сценарии компонент Старт с типом основной ветки,

4. сопоставляет с компонентом алгоритм его работы,

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

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

7. обрабатывает ответ компонента:

a. продолжение работы компонента;

b. откладывание обработки очередного события;

c. завершение работы компонента. По завершении работы компонента тот возвращает:

i. идентификатор следующего компонента, тогда процесс повторяется с новым компонентом начиная с этапа его поиска в сценарии, расширяясь накопленным контекстом;

ii. код следующего сценария (при необходимости запустить вложенный / асинхронный сценарий);

iii. ошибка, тогда сценарий завершается и, возможно, производится запуск ветки пост-обработки;

iv. команда возврата к предыдущему сценарию, тогда восстанавливается контекст предыдущего сценария и позиция в нем;

v. команда остановки, тогда сценарий завершается, и, возможно, производится запуск ветки пост-обработки;

Выполнение компонента может протекать синхронно и асинхронно.

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

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

Возможные варианты пост обработки определены в компоненте Старт. Выполнение ветки пост-обработки при завершении уже не предполагает переключения на другую ветку.

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

• определенные в сценарии в рамках Web интерфейса Администрирования

• передаваемые из родительского сценария дочернему (имеют приоритет над определенными через Гуи-интерфейс)

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

IVR сценарии

Сценарии голосовой обработки (IVR) используются как виртуальный SIP-телефон. По таблице маршрутизации IVR сценарий обслуживается как Код абонентских функций и может иметь множество номеров.

Каждый сценарий является стороной А или стороной В разговора.

IVR сценарий может быть запущен:

• через таблицу маршрутизации. Выступает в качестве стороны В

• через Дозвон до абонента. Выступает в качестве стороны А

• переводом из другого IVR сценария. Обслуживание разговора передается от одного сценария к другому без использования SIP Re-invite или других SIP взаимодействий.

Служебные сценарии

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

• Ручной запуск сценария из part_title

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

• Асинхронный запуск из других сценариев

• В качестве обработчика сообщений и запросов с внешних каналов

• В качестве контекстного сценария параллельно каждому звонку

Переменные сценариев

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

Переменные объявляются при редактировании сценария. Область данных выделяется только в момент выполнения сценария. Переменные могут передаваться между сценариями. Идентификатором переменной служит ее название.

Области видимости

При сохранении в переменную, слишком большого значения, оно размещается в файловой системе (категория :SYNC), а вместо переменной автоматически размещается путь к файлу.

Типы значений

​

Преобразование значений

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

Начальные значения

Использование переменных в Выражениях невозможно до присвоения им значений. По-умолчанию все переменные создаются с пустым значением.

Присвоение значений переменным

• при старте сценария

– определенные в сценарии в рамках Web интерфейса Администрирования начальных значений – передаваемые из родительского сценария дочернему (имеют приоритет над определенными через Web-интерфейс). Синхронизация по имени переменной

– в компоненте Старт могут быть присвоены дефолтные нулевые значения (переключатель Инициализировать переменные)

• во время работы сценария

– компонентом Присвоение в режимах одиночного и множественного присвоения

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

В компоненте Старт допускается установить режим присвоения начальных значений по умолчанию.

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

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

Аргументы сценариев

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

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

Типы аргументов

1. Фиксированное значение (константа); 2. Переменная; 3. Выражение (арифметические и строковые операции с переменными, константами и функциями от них). 4. Шаблон

Типы значений

Значение аргумента может принадлежать к одному из типов:

• Число (целое или десятичное);

• Строка;

• Дата/время.

Приведение типов

При сопоставлении значений аргументов, происходит их приведение к одному типу по следующему правилу:

• Если типы значений совпадают, то приведения не производится.

• Если оба значения могут быть представлены в виде чисел, производится приведение к числам.

• Если оба значения могут не могут быть представлены в виде чисел, то производится приведение к строке.

Выражения сценариев

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

Результат выражения может иметь тип сроки, числа и даты (в формате RFC3339).

Значения типа bool на выходе автоматически преобразуются к строке true или false. С помощью функции ifelse(bool,any,any) результат можно привести к другим значениям, например числам 0 или 1.

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

Для явного указания строки следует заключать текст в кавычки. В противном случае, сначала будут вычислены все арифметические комбинации, доступные для расчета. В приведенных примерах 2.3 и 2.4 результат будет разный (у 2.3 результат начинается с "5", а у 2.4 с "23").

Разбиение на строки производится с помощью функции endline().

Примеры выражений

Примеры числовых выражений

 1.1. [var_num_1] + 1
 1.2. 2 ^ [var_num_2] * ( Log10 ( [var_num_3] ) + 2 )
 1.3. sin ( len ( [var_string_1] ) )

Примеры строковых выражений

 2.1. [var_string_1] + [var_string_2]
 2.2. "Кусок текста" + [var_string_1]
 2.3. 2 + 3 + [var_string_1]
 2.4. "2" + "3" + [var_string_1]
 2.5. SubStr ( [var_string_1], 1, Length ( [var_string_1] ) - 1 )
 2.6. If ( num([a]) > 5, "больше", "меньше")

Операции

Операции над аргументами

Шаблоны

Приложение редактора сценариев позволяет задавать выражения с помощью шаблонов.

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

Пример записи одного вычисления на закладке Выражение и Шаблон:

Закладка выражения

Закладка шаблона

Функции сценариев

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

Каталог функций

Не все функции доступны в каждом Продукте.

Ниже приведен полный список функций системы по всем Продуктам.

Математические функции

Строковые функции

Функции по работе с датами/временем

Функции преобразования

Хеш-суммы

Функции по работе с файловыми путями

Служебные функции

Функции Доступа

Функции конфигурации

Константы

Символы

Функции сценариев IVR

Переменные

В этом блоке находятся все объявленные в сценарии переменные. В Выражения сценариев они добавляется в [ и ] Например, переменная ABC в Выражение (и шаблоны) будет добавлена как [ABC]

Дополнительная информация

Функция modify json

modify_json(п1 str,п2 json,п3json)

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

Пример:

modify_json(
   "\"chat\"/0/\"msgs\"",
   "{\"chat\":[{\"msgs\":[{\"txt\":\"abc\"}]}]}",
   "{\"action\":\"append\",\"value\":{\"txt\":\"zcv\"}}"
 )

Опции представлены в виде json-объекта с обязательным ключом action. Возможные варианты:

• append - для массива. Добавляет новый элемент в конец. В опциях значение элемента по ключу value.

• prepend - для массива. Добавляет новый элемент в начало. В опциях значение элемента по ключу value

• insert - для массива. Добавляет новый элемент в указанную позицию. В опциях значение элемента по ключу value, позиция по ключу index.

• replace - для массива. Заменяет элемент в указанной позиции на новый. В опциях значение нового элемента по ключу value, позиция по ключу index.

• replace_auto - для массива. Заменяет все элементы массива на указанное значение. В опциях значение по ключу value.

• delete - для массива. Удаляет элемент из указанной позиции. В опциях значение позиции по ключу index.

• keystore - для объекта. Сохраняет элемент по указанному ключу, в зависимости от наличия ключа добавляет или изменяет значение. В опциях значение элемента по ключу value, значение ключа по ключу key.

• keyreplace - для объекта. Заменяет элемент по указанному ключу, а если ключ отсутствует, то оставляет без изменений. В опциях значение элемента по ключу value, значение ключа по ключу key.

• keyinsert - для объекта. Сохраняет элемент по указанному ключу, если он отсутствует, а иначе завершается с ошибкой. В опциях значение элемента по ключу value, значение ключа по ключу key.

• keydelete - для объекта. Удаляет элемент по указанному ключу. В опциях значение ключа по ключу key.

Примеры.

Исходная переменная x

{
 "name": "Андрей Васильев",
 "id": "1377340472378151"
 }

Пример 1. Keyinsert

Добавлено в json ключа "channel" со значением "test".

modify_json(
     "",
     [x],
     "{\"action\":\"keyinsert\", \"key\":\"channel\", \"value\":\"\\\"test\\\"\"}"
 )

Результат

{
 "channel":"test",
 "name":"Андрей Васильев",
 "id":"1377340472378151"
 }

Если Key channel существует до выполнения modify_json, то результат будет Ошибка

Пример 2. Keyreplace

Заменена значения у поля name.

modify_json(
     "",
     [x],
     "{\"action\":\"keyreplace\", \"key\":\"name\", \"value\":\"\\\"test\\\"\"}"
 )

Результат

{
 "name":"test",
 "id":"1377340472378151"
 }

Взаимодействие сценариев

Каждый сценарий в процессе своего выполнения может запускать другие сценарии в двух режимах

• Вложенное (синхронное) выполнение. Родительский сценарий ждет завершения дочернего для продолжения своей работы.

• Асинхронное выполнение. Родительский сценарий не ждет завершения дочернего, а продолжает свою работу.

Варианты вызова сценариев

IVR → IVR

Вызов дочернего IVR осуществляется через Запуск сценария по имени или по коду. Вызов возможен только во Вложенном (синхронном) режиме. Все Локальные переменные родительского IVR наследуются дочерним сценарием. Для возврата управления в родительский IVR, дочерний сценарий необходимо завершить компонентом Стоп с включенным признаком возврата управления. Вместе с управлением в родительский вернутся изменения в значениях локальных переменных, если таковые были сделаны в дочернем сценарии.

Обычно применяется для

• разбиения больших сценариев на более понятные;

• для выделения идентичной логики несколькими сценариями;

IVR → Служебный сценарий

Вызов служебного сценария из IVR-сценария осуществляется через Запуск сценария по имени или по коду. Вызов возможен только в Асинхронном служебном режиме. Все Локальные переменные родительского IVR наследуются служебным сценарием.

Обычно применяется для асинхронной обработки данных, полученных из IVR сценария (которая может занять длительное время и не должна влиять на голосовое взаимодействие с абонентом)

Служебный → IVR сценарий

Для вызова IVR-сценария из служебного сценария используется Исходящий звонок. Происходит инициация исходящего звонка от имени IVR на указанный номер и при поднятии трубки запускается указанный IVR сценарий.

Обычно используется для автоматических задач дозвона и оповещения.

Служебный → Служебный сценарий

Для вызова служебного сценария из служебного сценария используется Запуск сценария . Вызов возможен в обоих режимах - вложенного и асинхронного.

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

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

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

​

Верхняя панель

​

Для запуска сценария или отмены изменений в информационной панели нажмите на ​

Затем выберите нужно действие в контекстном меню выбора.

​

Основное окно

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

​

Правила хорошего тона

Графический интерфейс создания сценариев предоставляет удобный и легкий в использовании инструментарий, отражающий концепцию Low-Code/No-Code. Но с другой стороны "некрасивое" рисование сценария приведет к сложностям дальнейшей модификации и понимания. Поэтому мы рекомендуем придерживаться следующих правил:

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

2. Названия сценариев должны быть "говорящими".

a. Префикс должен отражать прямое предназначение, проект, другую классификацию.

b. Основная часть имени должна нести смысловую нагрузку

c. Постфикс можно использовать на номер версии, дату последнего релиза и т.п.

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

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

5. Использование Комментарий где можно выделить отдельно значимый блок. В описании указать что это за блок, какие функции он выполняет и в дальнейшем вести changeLog изменений в нем

6. Оптимизация количества компонент. Не рекомендуется более 100 компонент в одном сценарии. Рекомендация крайне условная, но ей можно придерживаться при формальной оценке сложности сценария.

7. У компонент тоже должны быть "говорящие" названия. Не "Присвоение 3" (по пиктограмме видно что это Присвоение, а "i+1" или "увеличение счетчика i".

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

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

10. Отладочные компоненты настроены не на константы, а на переменные, которые можно изменить в начале сценария. Например пользователь у компонента Уведомление.

11. Нет брошенных веток. Каждая ветка завершается компонентом Стоп или Отбой или другим конечным компонентом.

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

13. Использование компонента SQL-запрос только там, где данные принадлежат Аксател (а не другой системе) или в случае, если сторонняя ИС не может предоставить WebService API доступ к данным.

Рекомендации по этапам работы над сценариями

• Этап проектирования архитектуры разбиения ответственности за реализацию по сценариям.

• Этап проектирования структуры сценария

– входные - выходные данные,

– протоколы взаимодействия,

– основные блоки и алгоритмы внутри сценария

• Этап разработки.

• Этап отладки.

• Этап приведения сценария в состояние релиза

• Этап оценки качества. Рекомендуем на этот этап привлекать инженера, кто не задействован в текущем проекте. Цель этапа - оценить читаемость сценария и насколько сторонний инженер сможет в нем разобраться через месяц-год.

IVR-сценарии и Служебные сценарии имеют как общие компоненты так и уникальные. Также набор компонент может отличаться между Продуктами.

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

​

​

​

​Каталог функций​

​

​