side menu

Скрипт

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

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

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

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 модуля.

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

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

Трассировка скрипта действия

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

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

Подробнее о включении трассировки и информации в трейсе читайте в статье «Трассировка серверных скриптов».

Вызов действий в скриптах

С помощью действий в бизнес-процессах можно создать в модуле пользовательскую библиотеку функций. В отличие от методов 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. Подробнее читайте в статье «Опциональные зависимости».

Допустим, в скрипте бизнес-процесса на уровне раздела установлена опциональная зависимость от модуля, в котором настроено действие для получения курса валют. Для модуля в настройках зависимостей установлено уникальное имя 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;
}

extention-activities.html call-process-activity.html