Скрипт

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

Вкладка «Настройки»

На вкладке Настройки укажите:

exten_8

  • Название — наименование действия;
  • Название по умолчанию — наименование, отображающееся на блоке действия при добавлении его на схему бизнес‑процесса;
  • Цвет блока — цвет, в который будет окрашен блок действия на схеме процесса;
  • Описание — описание функциональных возможностей действия и его особенностей;
  • Устаревшее — опция позволяет скрыть элемент из дизайнера бизнес-процессов, чтобы пользователи не смогли добавлять его на схемы новых процессов. Устаревшие действия продолжат работать без изменений в уже созданных процессах. Например, можно включить опцию для блока после обновления модуля;
  • Модель выполнения — способ выполнения действия:
    • Синхронное — простое выполнение заданного в действии сценария, то есть синхронное исполнение функции action(). Действие с синхронным выполнением можно вызвать как функцию из других сценариев. Подробнее читайте в разделе «Вызов действий в сценариях»;
    • Запрос результата — после выполнения заданного сценария во внешний сервис отправится запрос о значении статуса. Для реализации такого подхода в действии нужно определить функцию проверки результата check(). Бизнес‑процесс продолжится только после того, как функция check() вернёт ответ true;
    • Обратный вызов — в обращении к внешнему сервису передаётся URL, на который необходимо вернуть результат. То есть в параметрах вызова передаётся адрес, который будет вызван после выполнения задачи внешним сервисом, и на который будут отправлены результаты выполнения. URL ответа передаётся как входной аргумент функции action(). Любой запрос на данный URL передаётся в функцию callback(). После этого выполнение процесса продолжится;
  • Период проверки результата* — задайте частоту вызова функции check(). Опция используется для модели выполнения Запрос результата;
  • Количество повторов при ошибке — укажите количество попыток выполнения действия;
  • Пауза между повторами при ошибке (сек)* — определите частоту попыток.

Вкладка «Контекст»

На вкладке Контекст вы можете добавить переменные, используемые для настройки действия. Для этого нажмите + Добавить. Подробнее о типах переменных читайте в статье «Типы данных в системе».

script-activity-2

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

Для передачи переменных необходимо определить, какие переменные являются входными и выходными. После добавления действия на схему процесса вы сможете сопоставить эти переменные с контекстом процесса. Подробнее об этом читайте в статье «Особенности действий в бизнес‑процессах».

Вкладка «Сценарии»

На вкладке Сценарии создаётся сценарий действия. Для написания сценариев используется язык программирования TypeScript. Подробнее о принципах написания сценариев в ELMA365 вы можете прочитать в справке ELMA365 TS SDK.

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

api-2

Вы можете использовать опции:

  • Глобальные константы — установите флажок напротив опции 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;
}