Действие типа Скрипт можно использовать для создания интеграций, например, для отправки запросов во внешнюю систему. Настройки действия выполняются на трёх вкладках: Настройки, Контекст, Сценарии.
Вкладка «Настройки»
На вкладке Настройки укажите:
- Название — наименование действия;
- Название по умолчанию — наименование, отображающееся на блоке действия при добавлении его на схему бизнес‑процесса;
- Цвет блока — цвет, в который будет окрашен блок действия на схеме процесса;
- Описание — описание функциональных возможностей действия и его особенностей;
- Устаревшее — опция позволяет скрыть элемент из дизайнера бизнес-процессов, чтобы пользователи не смогли добавлять его на схемы новых процессов. Устаревшие действия продолжат работать без изменений в уже созданных процессах. Например, можно включить опцию для блока после обновления модуля;
- Модель выполнения — способ выполнения действия:
- Синхронное — простое выполнение заданного в действии сценария, то есть синхронное исполнение функции
action()
. Действие с синхронным выполнением можно вызвать как функцию из других сценариев. Подробнее читайте в разделе «Вызов действий в сценариях»; - Запрос результата — после выполнения заданного сценария во внешний сервис отправится запрос о значении статуса. Для реализации такого подхода в действии нужно определить функцию проверки результата
check()
. Бизнес‑процесс продолжится только после того, как функцияcheck()
вернёт ответtrue
; - Обратный вызов — в обращении к внешнему сервису передаётся URL, на который необходимо вернуть результат. То есть в параметрах вызова передаётся адрес, который будет вызван после выполнения задачи внешним сервисом, и на который будут отправлены результаты выполнения. URL ответа передаётся как входной аргумент функции
action()
. Любой запрос на данный URL передаётся в функциюcallback()
. После этого выполнение процесса продолжится;
- Синхронное — простое выполнение заданного в действии сценария, то есть синхронное исполнение функции
- Период проверки результата* — задайте частоту вызова функции
check()
. Опция используется для модели выполнения Запрос результата; - Количество повторов при ошибке — укажите количество попыток выполнения действия;
- Пауза между повторами при ошибке (сек)* — определите частоту попыток.
Вкладка «Контекст»
На вкладке Контекст вы можете добавить переменные, используемые для настройки действия. Для этого нажмите + Добавить. Подробнее о типах переменных читайте в статье «Типы данных в системе».
Контекстные переменные действия можно передавать в бизнес-процесс, который содержит это действие. В свою очередь, действие может получать контекстные переменные процесса, в котором оно используется.
Для передачи переменных необходимо определить, какие переменные являются входными и выходными. После добавления действия на схему процесса вы сможете сопоставить эти переменные с контекстом процесса. Подробнее об этом читайте в статье «Особенности действий в бизнес‑процессах».
Вкладка «Сценарии»
На вкладке Сценарии создаётся сценарий действия. Для написания сценариев используется язык программирования TypeScript. Подробнее о принципах написания сценариев в ELMA365 вы можете прочитать в справке ELMA365 TS SDK.
По умолчанию в сценарии действия можно обращаться только к свойствам, процессам, методам API из модуля, на уровне которого действие настроено. Вы можете предоставить доступ к другим объектам системы в сценарии, используя глобальные константы. Для этого в верхнем меню нажмите Настройки.
Вы можете использовать опции:
- Глобальные константы — установите флажок напротив опции Global, чтобы получить возможность обращаться к объектам из всех разделов системы и к глобальным параметрам. Для этого применяется константа Global;
начало внимание
При использовании константы Global
в сценарии действия модуль с этим действием нельзя экспортировать.
конец внимание
- Опциональные зависимости (доступны в объекте Imports) — выберите разделы или пользовательские модули, чтобы установить от них опциональные зависимости. После этого к ним можно обращаться через константу Imports. При использовании опциональных зависимостей модуль можно экспортировать без ограничений.
Чтобы создать зависимость, нажмите + Добавить раздел и выберите компонент системы. Затем в колонке Псевдоним задайте для него уникальное имя, которое будет использоваться в сценарии. Допустимы латинские буквы и цифры, для разделения слов можно использовать знак подчёркивания. По умолчанию используется код раздела или ID модуля.
начало внимание
Опциональные зависимости и константа Imports
по умолчанию доступны в поставке SaaS, а также On‑Premises, начиная с версии системы 2024.2. В более ранних версиях администратору системы нужно включить фича-флаг allowScriptImportsDependencies
. Подробнее об этом читайте в статьях «Изменение параметров On‑Premises Enterprise» и «Изменение параметров On‑Premises Standard».
конец внимание
После внесения данных о действии нажмите Сохранить и Опубликовать на верхней панели окна настроек.
Действие будет доступно в дизайнере бизнес-процессов, на панели инструментов справа от поля для моделирования, на вкладке Интеграции.
Вызов действий в сценариях
С помощью действий в бизнес-процессах можно создать в модуле пользовательскую библиотеку функций. В отличие от методов API, в действиях задаются входные и выходные переменные, для которых указывается определённый тип. Это позволяет при написании сценария чётко понимать, данные каких типов нужно передавать при вызове действия и каким будет результат его выполнения.
В сценариях можно вызывать только действия типа Скрипт с моделью выполнения Синхронное.
Действие можно использовать:
- внутри модуля, на уровне которого оно настроено: в сценариях других действий, методов API, бизнес‑процессов, обработчиков событий;
- в сценариях других компонентов системы, в которых установлена опциональная зависимость от модуля с данным действием.
Для обращения к действию используется свойство action
, которое доступно, если в модуле опубликовано подходящее действие. Для вызова применяется метод call()
, в качестве параметра которого передаётся объект с входными переменными действия.
При обращении к свойству action
и действию используется оператор ?.
— оператор опциональной последовательности. Это необходимо, чтобы в случае удаления действия обращение к модулю обрабатывалось корректно.
Обратите внимание, если входная переменная действия обязательна и имеет значение по умолчанию, во входной структуре метода call()
она становится необязательной. В выходной структуре метода, вне зависимости от обязательности выходной переменной, она также становится необязательной.
В качестве примера рассмотрим действие, которое позволяет получить курсы валют ЦБ РФ. У действия есть входные переменные — код валюты (тип Строка) и текущая дата (тип Дата), а также выходная переменная — курс валюты (тип Число).
В сценариях модуля действие можно вызвать следующим образом:
// Создание объекта, в который передаются параметры для выполнения действия — код валюты и текущая дата
let input: {
currency_code: TString;
date: TDate;
};
// Создание объекта, в который будет записываться результат выполнения действия — курс валюты
let output: {
currency_rate?: TFloat;
}
// Запись кода валюты из контекста и текущей даты, чтобы передать данные во входные переменные действия
input = {
currency_code: Context.data.currency_code,
date: new TDate(),
};
// Вызов действия для получения курса валюты, настроенного внутри модуля
output = await Namespace.action?.get_currency_rate?.call(input);
// Проверка, что результат выполнения действия получен
if (output) {
// Получение данных из объекта, в который записан результат
Context.data.current_currency_rate = output.currency_rate;
}
Действие также можно вызвать из сценария компонента, который не является частью модуля. Например, из виджета на уровне раздела или из обработчика событий на уровне другого модуля. Для этого в настройках сценариев компонента нужно установить опциональную зависимость от модуля с данным действием. После этого к действию можно обратиться с помощью глобальной константы Imports
. Подробнее читайте в статье «Опциональные зависимости».
начало внимание
Опциональные зависимости и константа Imports
по умолчанию доступны в поставке SaaS, а также On‑Premises, начиная с версии системы 2024.2. В более ранних версиях администратору системы нужно включить фича-флаг allowScriptImportsDependencies
. Подробнее об этом читайте в статьях «Изменение параметров On‑Premises Enterprise» и «Изменение параметров On‑Premises Standard».
конец внимание
Допустим, в сценарии бизнес-процесса на уровне раздела установлена опциональная зависимость от модуля, в котором настроено действие для получения курса валют. Для модуля в настройках зависимостей установлено уникальное имя currency_module
. Вызвать действие из сценария процесса можно следующим образом:
// Вызов действия `get_currency`, настроенного в модуле
// Во входные переменные действия передаются код валюты и текущая дата
const output = await Imports?.currency_module?.action?.get_currency_rate?.call({
currency_code: Context.data.currency_code,
date: new TDate(),
});
// Проверка, что результат выполнения действия получен
if (output) {
// Запись курса валюты, полученного с помощью модуля, в переменную из контекста процесса
Context.data.current_currency_rate = output.currency_rate;
}