Создание real-time сценариев

Концепция

Сценарии – ключевая модель системы Accelera, описывающая логику обработки потоковых данных в реальном времени. Особенности сценариев:

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

Схема

Сценарий состоит из блоков, каждый из которых имеет вход и/или выход.

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

Для удаления нити щелкните на ней правой кнопкой мыши и нажмите красную кнопку с иконкой корзины:

Для удаления блока, щелкните по нему правой кнопкой мыши и нажмите красную кнопку с иконкой корзины:

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

Состояния

Пример простого сценария

С самого начала клиент отсутствует в сценарии. При поступлении в систему события login_mb система определяет, что клиент может войти в сценарий. Он размещается в состоянии, в котором ожидается событие transfer_money:

При поступлении в систему события transfer_money клиент перемещается в состояние, в котором ожидается событие logout.

Если в систему поступает событие logout, то клиент перемещается в блок end, который удаляет его из сценария.

Блоки на скриншотах - это состояния, в которых находится клиент в ожидании события.

Каждый блок имеет свой собственный номер. Нажмите на блок и в правом углу вы увидите его номер.

Данный блок имеет номер 2.

В системе есть 2 типа блоков: с состоянием и без.

Блок с состоянием будет дальше называться просто состоянием. Такие блоки имеют вход слева и один или несколько выходов справа.

К блокам с состоянием относится вышеупомянутый State и некоторые действия, которые будут описаны ниже.

Блоки без состояния имеют один вход слева и не имеют выходов справа.

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

После поступление события transfer_money будет выполнен переход в состояние ожидания события logout. И вместе с этим будет выполнен блок Add to profile, который добавит запись о клиенте в динамический профиль.

На выходе из блока с состоянием может быть только 0 или 1 блок с состоянием и любое количество блоков без состояния.

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

Структура события

Типовое событие системы - JSON-объект в следующей форме:

{
  "id": "123456789",
  "event": "login_mb",
  "context": {
    "name": "value"
  }
}

id - это идентификатор клиента, в рамках которой идет обработка события.

event - название события.

context - дополнительные параметры события, которые может передать источник.

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

При публикации события выше, в сценарии появится параметр контекста name со значением value. Количество параметров не ограничено, однако каждый параметр занимает место в оперативной памяти системы, не забывайте об этом.

Объединенный контекст

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

В систему попадает событие login_mb, которое имеет в контексте параметр device со значением phone123, а также country со значением RUS. Клиент переходит в состояние ожидания события transfer_money с контекстом

device=phone123
country=RUS

Затем система принимает событие transfer_money с параметрами amount = 100000 и country = NL. Клиент переходит в состояние ожидания события logout с параметрами

device=phone123
amount=100000
country=NL

Параметр контекста device переходит дальше из предыдущего события login_mb.

Параметр amount - новый.

Параметр country - присутствует как в предыдущем, так и в текущем контексте. Поэтому он перезаписывается новым значением.

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

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

Например, мы хотим вывести в консоль сервера сообщение Hello + параметр name из контекста. Для этого нам следует использовать действие Console log action, которое выводит сообщение в консоль сервера. Обратиться к параметру name можно через двойные фигурные скобки {{ name }}.

При попадании события transfer_money с параметром name = John клиент перейдет в состояние ожидания logout, а в консоль будет выведено сообщение:

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

Функции шаблонизации

➗Справочник по функциям шаблонизации

Управление сценарием

В верхней части находится панель управления сценарием:

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

Далее находятся кнопки управления состоянием. На скриншоте сценарий активен и обрабатывает события.

Для активации сценария нажмите соответствующую кнопку.

Следующая кнопка - пауза - приостанавливает обработку событий, сохраняя данные клиентов.

Кнопка остановки полностью останавливает обработку события, удаляя все данные клиентов.

Кнопка удаления сценария удаляет его с диска без возможности восстановления.

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

Статусы также отображаются в таблице всех сценариев.

Далее расположены кнопки приближения/отдаления, кнопка генерации тестового события, кнопка проверки "пульса" сценария, а также экспорт сценария в виде файла.

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

Кнопка экспорта сохраняет сценарий на ваш компьютера в формате <имя_сценария>.flow

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

Описание основных блоков

Главные блоки

Главные блоки выделены в группу General:

Start

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

End

Блок выхода из сценария. Может быть несколько внутри сценария. Данный блок удаляет все данные по клиенту внутри сценария (состояние, контекст, таймеры)

State

Блок, в котором клиент ожидает то или иное событие. В блоке можно ждать более 1 события, для этого нажмите кнопку Add trigger и введите название нужного события. При поступлении в систему одного из них, выполнение пойдет по нужной ветке.

Notes

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

Tag

Записывает указанный тег по клиенту, который можно отслеживать в аналитике. Название тега может быть задано только латиницей, символы использовать запрещено, для соединения нескольких слов используйте snake_case или kebab-case.

Add aggregation

Блок агрегации данных. Всегда выполняется раньше всех, агрегирует информацию по параметру в заданные переменные. Принцип использования:

В поле Aggregation name укажите название параметра, в который будет выполнена агрегация параметров.

В поле Aggregation context parameter укажите название параметра контекста, который нужно агрегировать.

При выполнении этого блока в контекст пользователя будут добавляться параметры с постфиксом _min, _max, _sum, _count. Пример:

Когда клиент в состоянии ожидания событий transfer_money или end_aggregation, при поступлении первого события клиент не будет никуда двигаться, будет выполняться только агрегация параметра amount в score с постфиксами. При поступлении события end_aggregation, клиент перейдет в состояние ожидания logout, и параметры больше не будут агрегироваться.

В действии Console log action добавим вывод параметров контекста в виде текста в консоль:

min: {{score_min}}, max: {{score_max}}, sum: {{score_sum}}, count: {{score_count}}.

Отправим событие transfer_money с параметром amount = 100 три раза. Затем отправим событие end_aggregation, посмотрим вывод в консоль:

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

Expressions

Данный блок служит для расчета математических выражений. В выражении вы можете использовать как константы, так и параметры контекста. Пример возведения параметра amount в квадрат:

Параметр amount возводится в квадрат и записывается в параметр result. Выведем его в консоль:

Вывод:

Таким образом, можно рассчитывать разные параметры, фиксируя результат в переменные.

Add to sliding window

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

Блок работает по принципу stateless (не хранит состояние пользователей). Для записи данных выберите существующее окно. Если нужного вам окна нет, добавьте его на странице Sliding Window.

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

Далее заполните поля данных, поле ввода работает по принципу шаблона. Подробнее см. Обращение к параметрам контекста.

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

Get from sliding window

Блок нужен для получения данных из временного окна.

Данный блок также работает как stateless (не хранит в себе состояние клиента).

Его настройка:

1. Сначала выберите необходимое вам временное окно.

2. Затем укажите интервал, за который вы хотите получить данные. Например, 10 минут.

3. Далее укажите ключ (если он отличается от того, который был использован в сценарии)

4. Далее выберите данные, которые хотите извлечь из временного окна (например в выбранном окне это поле amount. В комментарии под полем prefix вы можете увидеть параметры, которые будут добавлены в контекст в результате выполнения блока.

   

5. Затем вы можете указать желаемый префикс к результату. Этот префикс будет добавлен в начале параметра, чтобы избежать перезаписи данных в контексте (если вы, к примеру берете данные по одному и тому же временному окну, те же параметры, но за разное время). Например укажем префикс x:

   

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

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

Profile API

Информацию по Profile API смотрите в разделе

👤Использование Profile API

Блоки действий

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

A/B split

Действие с состоянием – имеет выходы.

Используйте данное действие для пропорционального случайного распределения клиентов на группы:

Audience / Profile

Действие с состоянием – имеет выходы.

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

При попадании в этот блок выполнится проверка клиента на наличие в заданной аудитории. Если клиент в ней отсутствует, то выполнение пойдет по ветке с желтым выходом (на скриншоте - состояние ожидания события event2). Если клиент в аудитории имеется, то он будет перемещен в состояние ожидания event1, а все параметры из аудитории будут помещены в контекст и доступны для обращения.

В поле profile key можно указать любой доступный параметр контекста. Поиск в аудитории будет выполнен по этому параметру. Например в текущем сценарии клиенты имеют идентификаторы типа CIF, а в аудитории загружены данные в рамках идентификатора типа номер телефона. Указав в поле Profile key название параметра с номером телефона вы сможете найти клиента в нужной аудитории.

Указывать Profile key нужно в формате стандартного обращения к полю контекста, {{ fieldName }}

Console log action

Действие без состояния.

Выводит указанное сообщение в консоль.

Context table

Действие с состоянием.

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

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

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

При поступлении события event клиент переходит в блок контекстной таблицы, а далее:

• если поле amount = 10000, а поле country = RUS, то переход в состояние ожидания event1;
• если поле amount = 3000, а country = NL, то переход в состояние ожидания event2;
• если поля amount и country не соответствуют условиям выше или их нет вообще, то клиент переходит по ветке Default, в блок End.

Decision action

Действие с состоянием.

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

При выполнении условия клиент переходит по ветке с синим выходом (true), при невыполнении - желтым (false).

Для настройки правил нажмите кнопку Configure.

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

Данная настройка эквивалентна условию

(amount ≥ 1000 AND amount < 10000 AND country = 'RUS') OR (amount ≥ 10000)

Добавление и удаление групп или ключей выполняется соответствующими кнопками. Для сохранения нажмите кнопку Save and continue.

Delay trigger

Действие без состояния – без выходов.

При выполнении заводит таймер на указанные дату и время. При наступлении указанной даты генерирует событие с заданным названием:

09 сентября 2021 года в 10:00 будет сгенерировано событие event1, которое мы будем ожидать в следующем блоке.

Если указать только время, без даты, то таймер будет заведен на сегодняшнюю дату по умолчанию. Если указанное время уже прошло (вы указали 10:00, а сейчас 12:00), то таймер будет заведен на завтрашний день.

Delete profile record

Действие без состояния.

Удаляет запись о пользователе из динамического профиля.

Выберите нужный профиль, откуда запись будет удалена. Также имеется возможность указать profile key. В поле profile key можно указать любой доступный параметр контекста. Поиск в профиле и удаление будет выполнен по этому параметру.

Get coupon

Действие необходимо для получение нового купона из созданного стека.

Данное действие является stateful, то есть хранит в себе клиента, после получения купона передвигает его далее по логике сценария.

Пример:

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

Если купоны закончились, выполнение идет по нижней ветке.

Пример настройки блока:

Согласно данной настройке купон будет взят из стека с названием Test. А затем записан в переменную coupon, к которой вы можете получить доступ как к обычной переменной контекста через {{}}.

HTTP Request

Действие без состояния.

Выполняет http-запрос с указанными параметрами.

При нажатии на кнопку Configure откроется редактор.

В поле URL укажите адрес запроса, выберите метод, укажите нужные заголовки из списка или кастомный и сформируйте тело сообщения в формате JSON.

Данное действие обладает функцией возврата ответа в сценарий как событие

По умолчанию если не задано имя в поле Context parameter для данных, которые возвращаются в http response, то данные возвращаются в теле контекста.

{
	"response": <полученная информация в текстовом виде>
}

Если ответ пришел с заголовком Content-Type text/html, тогда действие оборачивает результат в JSON
В другом случае действие парсит ответ в JSON и возвращает полученный ответ в контекст события.

Событие, которое поступит в сценарий в результате этого действия если не задать свое название в поле Calback trigger, имеет дефолтное название http_response

Если при запросе произошла ошибка, в ответ приходит событие http_failed с ответом.

Пример ответа при ошибке:

{
  id: '12314',
  event: 'http_failed',
  context: {
    '': '',
    status: 401,
    result: {
      error: 'Missing API key.',
      how_to_get_one: 'https://reqres.in/signup'
    }
  },
  flowId: 'awvso94140',
  flow_name: 'Exapmple-http-api',
  flow_id: 'awvso94140'
}

Jump action

Действие без состояния.

Перемещает клиента в указанное состояние.

На скриншоте при выполнении блока Jump to state клиент будет перемещен в состояние 16, в котором будет ожидать события event2.

Publish trigger

Действие без состояния.

Генерирует событие с указанными именем и параметрами по текущему клиенту.

Нажмите кнопку Configure. Введите необходимые значения.

При выполнении этого блока будет сгенерировано событие new_event с параметром a и значением b.

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

Sendsay e-mail

Действие без состояние.

Выполняет отправку e-mail по заданному шаблону в системе Sendsay.

Для настройки действия нажмите кноку “Configure”, откроется модал конфигурации действия.

Для отправки e-mail необходимо знать id или alias шаблона. В системе sendsay он указан рядом с названием.

Введите название шаблона в соответствующее поле, нажмите кнопку со значком обновления:

Система автоматически загрузит данные о шаблоне, имя и email отправителя. Заполните параметры и укажите данные, кому необходимо отправить письмо. Нажмите Save and continue. Отправка письма готова.

Accelera считывает параметры из шаблона, которые обернуты в конструкцию [% %], например [% name %].

Set profile record

Действие без состояния.

Добавляет запись о клиенте в динамический профиль.

В окне настройки выберите нужный профиль. При активации в списке параметров автоматически будут сформированы поля с параметрами этого профиля. Заполните их статичными значениями или параметрами контекста. Для доступа к параметрам используйте форму {{ fieldName }}.

Для записи в профиль в рамках другого идентификатора заполните поле Profile key.

Timer action

Действие с состоянием.

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

Через 60 минут клиент перейдет в следующее состояние.
Допустимая погрешность таймера допустима в рамках 1-2 минут.

Timer trigger

Действие без состояния.

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

Это один из многочисленных примеров использования Timer trigger. В примере выше по клиенту после события event заводится таймер и ожидается событие event1 или timeout. Если в течении 60 минут событие event1 не придет, то будет обработано событие timeout и клиент покинет сценарий.
Допустимая погрешность таймера допустима в рамках 1-2 минут.