Термины и определения

Сценарий

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

В состав сценария входит:

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

  Структура события определяется в общем пайплайне прохождения событий

• Одна или несколько исполняемых функций
• Различные функции-преобразователи и поставщики данных, операторы сравнения, функции обращения к API, переменные и т.д.

Структура

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

Содержит следующие параметры:

• Общая информация
  • Название структуры
  • Описание структуры
• Свойства структуры
  • Название свойства
  • Тип
    Могут быть использованы все существующие типы данных (кроме Exec), а также другие структуры.
  • Подсказка
    Описание свойства структуры, будет подсвечиваться при наведении на соответствующий пин на холсте сценария

Создание локальных структур возможно двумя способами: ручным и автоматическим:

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

• Автоматический режим - по нажатию кнопки {+} откроется окно Создания структуры из JSON. Необходимо задать название и в поле Json вставить любую структуру в JSON-формате, с данными или без - не важно, любого уровня вложенности. После создания в списке появится как создаваемая cтруктура, со всеми свойствами и типами данных, так и вложенные (если таковые были).

Перечисления

С целью обеспечения удобства пользователей бизнес-процессов, внедрен новый тип данных в сценариях автоматизации: Enum (перечисление). В текущей версии доступны локальные перечисления, которые можно создавать внутри сценария, а также системные перечисления, предоставляемые разработчиками. Выбранное перечисление отображается в настройках Действия БП в виде выпадающего списка, что позволяет пользователям легко выбирать одну из доступных констант без необходимости исследования документации.

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

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

Создание локальных перечислений

1. Перейдите в раздел "Enums/Перечисления" в диспетчере сценариев
2. Нажмите кнопку "+", чтобы создать новое перечисление
3. Задайте название перечислению и добавьте описание при необходимости
4. Добавьте константы, которые будут доступны в выпадающем списке для выбора пользователей

Редактирование существующего перечисления

Для того чтобы изменить существующее перечисление:

1. В разделе "Перечисления" диспетчера объектов выберите нужное перечисление
2. В инспекторе объектов вы можете изменить название и описание, а также управлять константами (добавлять, удалять, изменять их значения)

Удаление неактуальных перечислений

Для того чтобы удалить неактуальное перечисление:

1. В разделе "Перечисления" диспетчера объектов выберите нужное перечисление
2. Нажмите кнопку удаления
3. Подтвердите удаление. Учтите, что перечисления, используемые в других частях системы, не могут быть удалены.

Блок

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

Пример блока:

Параметры блока

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

Категоризация блоков

Событие запуска

• OnRawLogEvent - блок инициирует запуск сценария в препроцессоре (обработчике) событий потока данных.
• OnLogEvent - блок инициирует запуск сценария при получении события через какой-либо поток данных и содержит в себе поступившее первичное событие в переменной Value
• OnScheduledEvent - блок инициирует запуск сценария по планировщику
• OnThresholdEvent - блок инициирует запуск сценария при открытии или закрытии порогов при обработке метрик
• OnProcessedThresholdEvent - блок инициирует запуск сценария после обработки порогов в сценарии с типом ThresholdsProcessor
• OnThresholdForecastEvent - блок инициирует запуск сценария при каждом расчете прогноза по порогу в соответствии с установленной частотой расчета
• OnRawBuildEvent - блок инициирует запуск сценария при получении файла Allure отчета для последующего парсинга
• OnBuildEvent - блок инициирует запуск сценария после обработки файла Allure отчета для генерации сигналов

Локальные функции

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

Глобальные функции

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

Переменные

Подробней о типах переменных

Пин

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

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

Категории пинов

1. Пин передачи данных. Обозначение на Блоках - 🔴🟠🟡🟢🔵🟣🟤.

   1. Могут быть входящие и исходящие Пины.
      • Нельзя соединить между собой 2 исходящих Пина, равно как и 2 входящих между собой.
      • Для входящего Пина передачи данных может быть установлена только одна связь.
      • Исходящий Пин может быть соединен с множеством входящих Пинов других блоков.
      • Нельзя соединять Пины одного блока между собой.
      • При попытке выполнить не валидные соединения пользователь получит уведомление.
      • Если у блока существует входящий Пин, для него может быть установлено значение или протянута связь.

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

   2. Пины различаются по типам данных, которые передаются между ними. Подробнее о Типах данных
   3. Пины различных типов и связи между ними данных должны различаться визуально;
   4. Для некоторых универсальных функций на этапе их создания могут быть объявлены Пины неопределенного типа - Wildcard.

2. Пин вызова функции

   1. Пины вызова функции и связи между ними визуально отличаются от Пинов данных - ▶.
   2. Нельзя соединить Пин передачи данных и Пин вызова функции.
   3. Если у блока существует входящий Пин вызова функции, то для его запуска обязательно должна быть протянута связь от другого блока функции или блока События запуска.
      • Отсутствие связей для Пинов вызова функции не будет вызывать ошибок провала сборки кода, просто функция не будет исполнена.
      • Исходящие Пины так же могут не иметь связей. Это означает, что участок сценария завершится исполнением данной функции, при наличии входящей связи.
      • От одного исходящего пина вызова функции нельзя построить несколько связей.
      • Несколько связей может идти к одному пину вызова от других функций или событий.

Конструкция сценария

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

Пример конструкции:

Инспектор объектов

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

Пример инспектора:

Диспетчер объектов

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

Пример диспетчера:

Функция

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

Функции разделяют на 2 основных класса:

CodeFunction

Данный тип функции, кроме базовых настроек, включает в себя возможность построить конструкцию используя скриптовый язык программирования C# scripts

Общесистемные функции

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

Все функции так же делятся на 2 категории:

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

Pure & Impure функции

Функции могут быть Pure (чистые) и Impure (нечистые)

Pure (чистые):

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

Impure (нечистые):

1. Данные блоки функций участвуют в управлении потоком выполнения сценария.
2. Блоки функций управления характеризуют наличие специальных Пинов "вызова функции".
3. Нечистые функции могут менять состояние элементов сценария и глобальные переменные.

Пользовательская переменная

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

1. Переменные делятся на:
   • Предопределенные стандартные (системные) переменные:
     • ID текущего сценария
     • ID Рабочей группы
     • Bearer token - токен авторизации от имени Automaton Bot
     • Scenario - переменная содержит общие параметры сценария (ScenarioId, OwnerWorkGroupId, RobotToken, BaseUri, UserspaceId)
   • Локальные переменные, созданные пользователем для текущего сценария (настраиваемые в инспекторе, по аналогии с настройкой локальных функций CodeFunction).
2. Для каждой переменной существует 2 состояния: SET и GET. При добавлении в сценарий пользователь может указать состояние переменной.
   • GET - используется для получения значения переменной в сценарии.
   • SET - используется для установки значения предопределенной переменной.

Правила именования функций и переменных

Имя функции или переменной может содержать:

• буквы (строчные и прописные).
• знак нижнего подчеркивания ("_").
• цифры.

Имя функции или переменной должно начинаться с:

• буквы (строчные и прописные).
• знака нижнего подчеркивания ("_").
• символа "@".

Язык программирования C# чувствителен к регистру: name и Name - 2 разные сущности.

Имя функции или переменной не может совпадать с ключевыми словами (for, if, using).

Пример	Допустимо/Недопустимо
myvar	Допустимо
Myvar14092	Допустимо
_name	Допустимо
@variable1	Допустимо
123myvar	Недопустимо, начинается с цифры
my var	Недопустимо, содержит пробел

Типы данных

Блоки функций поддерживают передачу данных через Пины следующих типов:

Название	Возможные значения	Возможность установить значение по умолчанию	Валидация
Boolean	True/False	ДА	-
Byte	Целые числа от 0 до 255	ДА	Только целые неотрицательные числа.
Char	Единичный символ Unicode	ДА	Запрет на ввод более одного символа
Double		ДА
Dynamic	Хранит любые значения	НЕТ	-
GUID	Значение формата 00000000-0000-0000-0000-000000000000	ДА	Валидация по маске
Integer	От -2147483648 до 2 147 483 647	ДА	Только целые числа. При вводе числа меньше или больше допустимого значения, значение приводится к минимально или максимально допустимому
Integer64	От -9223372036854775808 до 9223372036854775807	ДА	Только целые числа. При вводе числа меньше или больше допустимого значения, значение приводится к минимально или максимально допустимому
String	Строка символов Unicode	ДА	Разрешено использовать любые символы. Ограничений на количество символов нет.
Structure		НЕТ	-
Enum		НЕТ	-

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

Связь между Пинами можно установить только между Пинами одного типа.

Глобальные переменные

Работа с глобальными переменными осуществляется при помощи соответствующи глобальных функций:

• SetStorageValue - инициализация глобальной переменной и задание её значения
• StorageTryGetValue - попытка получения значения глобальной переменной
• StorageContainsKey - проверка наличия глобальной переменной
• StorageRemoveKey - удаление глобальной переменной

Automaton bot

Automaton Bot - системный пользователь, использующийся для "обезличивания" операций в сценариях модуля "Автоматизация".

• Automaton Bot не отображается в списке пользователей.
• Пользователя Automaton Bot нельзя изменить или удалить.
• Пользователя Automaton Bot нельзя добавить в Рабочие Группы.
• Для каждой "Рабочей группы"-владельца сценария Автоматизации у пользователя Automaton Bot выписан соответствующий токен.