Handlers

Руководство по работе с обработчиками

Версия 4.5.0

© 2015-2023, ООО "Процессные технологии"

# GroovyActionHandler

Данный action handler используется для пересчета значений переменных бизнес процесса.

Пример конфигурации:

My_date = new java.util.Date();
My_rnd = new java.util.Random(1000).nextInt();
My_time = java.lang.System.currentTimeMillis();

int n = Integer.parseInt(multNumber);
String[] array = new String[n];
for (int i=0; i < n; i++) {
    array[i] = "book "+i;
};
multArray = array;

Измененные в процессе исполнения скрипта переменные изменят свое значение в БП. Будут изменены лишь переменные, определенные в процессе!

Конфигурацией является корректный код Groovy (подробнее), который по синтаксису идентичен Java.

В версии RunaWFE 4.3.0, в обработчике Groovy была добавлена возможность присваивания роли переменных типа Список(Исполнитель), Список(Пользователь), Список(Группа). В этом случае роль инициализируется временной группой, содержащей исполнителей из переменной соответствующего списка. .

Роль1 = list;

Удаление временных групп выполняется с учетом значений параметров timertask.period.millis.remove.temp.groups, timertask.start.millis.remove.temp.groups

Также доступна возможность копирования списка исполнителей и в переменную типа "Исполнитель"

# ExecuteFormulaActionHandler

ExecuteFormula – универсальный ActionHandler, предназначенный для изменения значений переменных бизнес процесса. Для показа работы данного обработчика был разработан демо процесс ExecuteFormulaDemo. Обработчики располагаются на переходах между узлами. При наведении на обработчик курсора мыши, будет показана формула, используемая в конфигурации. Для редактирования формул необходимо нажать на поле «конфигурация» в свойствах обработчика:

Появится окно, в котором надо задать формулы вида : 'имя модифицируемой переменной' = выражение

В выражении могут использоваться такие операции: +, -, *, /, <, <=, ==, !=, >, >=, &, |, ^.

Наибольший приоритет (4) у умножения и деления. Приоритет 3 у операций сложения и вычитания. Приоритет 2 у сравнений. Наименьшим приоритетом обладают булевы операции «&» (and), «|» (or) и «^» (xor).

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

Помимо переменных могут использоваться непосредственные значения типов Long, Double, Boolean, String, Date и функции.

Например, функции могут быть такими: date(дата), time(дата) и hours_round_up(число)

• date(дата) округляет дату до целого числа дней, отбрасывая время.
• time(дата) отбрасывает дни, оставляя только время.
• hours_round_up(число) округляет время, заданное в минутах, до часов в верхнюю сторону.
• round(число) или round(число, количество знаков после запятой) округляет число, оставляю фиксированное количество знаков после запятой.
• round_up(число) или round_up(число, количество знаков после запятой) округляет число в верхнюю сторону.
• round_down(число) или round_down(число, количество знаков после запятой) округляет число в нижнюю сторону.
• number_to_string_ru(число) переводит число в строку на русском языке.
• number_to_string_ru(число, п2, п3, п4, п5) переводит число с зависимым словом в строку на русском языке.

п2 — 'M' или 'F' — мужской/женский род зависимого слова. п3, п4, п5 — зависимое слово в трех формах (например:день, дня, дней).

• number_to_short_string_ru(число, п2, п3, п4, п5) выбирает соответствующую числу форму зависимого слова.
• get_process_id() - возвращает номер текущего экземпляра процесса
• random() возвращает случайное вещественное число от 0 до 1.

Например:

variable1 = 2

variable2 = 3.1415926535

variable3 = true

variable4 = «string»

variable5 = « \» » (для использования символа кавычки требуется поставить перед ней '\' )

variable6 = 01.09.2008

variable7 = '01.09.08 18:00' (здесь требуется заключить дату в одинарные кавычки, так как она содержит пробелы)

variable8 =round_up(2.564367, 3) (variable8 = 2.565)

variable9 = number_to_string_ru(102, «F», «спичка», «спички», «спичек»)

(variable9 = «сто две спички»)

"текущая дата" = current_date()

"время" = current_time()

"дата и время" = current_date_time()

Функция для работы с ФИО:

Функция FIO_case_ru(String fio, int caseNumber, String mode)fio - фамилия, имя и отчество в именительно падеже через пробел

caseNumber - номер падежа (от 1 до 6)

mode - строка форматирования

Символы F, I и O заменяются на фамилию, имя или отчество в соответствующем падеже.

Символы f, i и o заменяются на первую букву фамилии, имени или отчества.Остальные символы строки форматирования не меняются.

Примеры использования:

FIO_case_ru("Иванов Иван Иванович", 1, "F I O :)") Иванов Иван Иванович :)

FIO_case_ru("Иванова Ира Ивановна", 2, "F I o") Ивановой Иры И.

FIO_case_ru("Иванов Иван Иванович", 3, "F i O") Иванову И. Ивановичу

FIO_case_ru("Иванова Ира Ивановна", 4, "F i o") Иванову И. И.

FIO_case_ru("Иванов Иван Иванович", 5, "f I O") И. Иваным Ивановичем

FIO_case_ru("Иванова Ира Ивановна", 6, "о I o") о Ивановне И.

FIO_case_ru("Апырвапыркина Фыва Няковна", 5, "F I O") Апырвапыркиной Фывой Няковной

Если функция неправильно склоняет какие-либо имена и фамилии, можно добавить исключение. Для этого воспользуйтесь механизмом расширения - создайте конфигурационный файл nameCaseConf.xml и расположите его в директории ..\standalone\wfe.custom (если директория wfe.custom не существует, то создать). Например, для Windows версии RunaWFE, файл должен быть помещен в C:\Program Files\RunaWFE\Simulation\standalone\wfe.custom\.

Формат файла:

<?xml version=”1.0”>
<nameCaseConf>
 <family value = “фамилия в именительном падеже”>
   <rule case = “номер падежа”>правильный вариант фамилии</rule>
   <rule case = “номер падежа”>правильный вариант фамилии</rule>
     …
 </family>
 <family value = “фамилия в именительном падеже”>
   …
 </family>
 <name value = “имя в именительном падеже”>
   <rule case = “номер падежа”>правильный вариант имени</rule>
     …
 </name>
 <name value = “отчество в именительном падеже”>
   <rule case = “номер падежа”>правильный вариант отчества</rule>
     …
 </name>
 …
</nameCaseConf>

Пример файла конфигурации:

<?xml version="1.0" encoding="UTF-8"?>
<nameCaseConf>
  <!-- <name value="Николай">
  </name> -->
  <family value="Кримза">
    <rule case="2">Кримзы</rule>
    <rule case="3">Кримзе</rule>
    <rule case="4">Кримзу</rule>
    <rule case="5">Кримзой</rule>
    <rule case="6">Кримзе</rule>
  </family>
  <!-- <parent value="Петрович">
  </parent> -->
</nameCaseConf>

В версии RunaWFE 4.3.0, в обработчик ExecuteFormula была добавлена возможность склонения на основе файла с данными. Создайте файл mappingConf.xml и расположите его в директории ..\standalone\wfe.custom (если директория wfe.custom не существует, то создать). Например, для Windows версии RunaWFE, файл должен быть помещен в C:\Program Files\RunaWFE\Simulation\standalone\wfe.custom\}

Формат файла:

<?xml version="1.0" encoding="UTF-8"?>
<mappingConf>
  <rule title="должность в дательном падеже">
    <item input="Бухгалтер" output="Бухгалтеру" />
    <item input="Ведущий геофизик" output="Ведущему геофизику" />
    <item input="Геодезист 1 категории" output="Геодезисту 1 категории" />
    <item input="Главный специалист по геологии" output="Главному специалисту по геологии" />
  </rule>
</mappingConf>

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

some_variable = mapping("Бухгалтер", "должность в дательном падеже")

# SQLActionHandler

Используется для взаимодействия с БД.

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

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

В версии RunaWFE 4.4.1 была добавлена возможность использования не только JNDI источника данных

• "Источник данных (JNDI Name)" – имя источника данных зарегистрированного на сервере (для WildFly как правило используется с префиксом java:/)
• "Переменная с JNDI именем" - переменная содержащая JNDI имя источника зарегистрированного на сервере
• "Имя источника данных" - здесь доступен выбор из определенных в DevStudio источников данных (см. "Источники данных")
• "Переменная с именем" - переменная содержащая имя источника данных

SQL запрос — собственно сам запрос (в формате java.sql.PreparedStatement).

В версии RunaWFE 4.4.1 писать SQL запрос стало значительно удобнее - запрос теперь может располагаться не на одной строке, также была введена подсветка синтаксиса SQL.

Синтаксис запроса включает текст запроса котором вместо знаками ? Отмечаются параметры, количество которых должно соответствовать числу параметров в секции Параметры запроса. Если запрос типа SELECT, то он должен явно перечислять столбцы, значения которых будут присвоены переменным, перечисленным в секции Результаты запроса.

Можно использовать запрос как значение переменной, для этого нужно указать строку запроса в конфигураторе в виде ${query}, где query - переменная типа "Строка", содержащая сформированный в процессе запрос.

# Выполнение хранимой процедуры MSSQL

Создание таблицы и заполнение данными

CREATE TABLE dbo.tests (session_id INT NOT NULL, group_id INT NOT NULL) ON [PRIMARY]
GO
INSERT INTO dbo.tests VALUES (1, 10)
INSERT INTO dbo.tests VALUES (2, 20)
INSERT INTO dbo.tests VALUES (3, 30)
GO

Создание хранимой процедуры

CREATE PROCEDURE dbo.test @session_id INT, @group_id INT OUTPUT
AS
SET NOCOUNT ON
SELECT TOP 1 @group_id = group_id FROM dbo.tests WHERE session_id = @session_id
IF(@@ROWCOUNT != 1)
BEGIN
 RETURN -1
END
RETURN 1
GO

Пример вызова процедуры из Management Studio

DECLARE @resultCode INT, @groupId INT
EXEC @resultCode = dbo.test @session_id = 1, @group_id = @groupId OUTPUT
SELECT @resultCode, @groupId

Задание конфигурации в процессе Файл:SqlProcedureTest.par

# AssignSwimlaneActionHandler

Позволяет (пере)определить роль в любом месте процесса по заданной конфигурации. Значение инициализатора имеет такой же синтаксис как и на вкладке редактирования ролей.

# SendEmailActionHandler

Позволяет послать сообщение по e-mail. Сообщением может быть форма задания, если обработчик установлен на узле, а не на переходе. Альтернативным вариантом отправки сообщения является использование бота SendEmailTaskHandler. Формат файла конфигурации для него не отличается от формата конфигурации для SendEmailActionHandler (за исключением контекстной мета-информации).

Для создании конфигурации SendEmailActionHandler используется специальный конфигуратор. Для того, чтобы открыть конфигуратор необходимо создать обработчик, выбрав класс ru.runa.wfe.extension.handler.SendEmailActionHandler из списка доступных обработчиков и начать редактирование конфигурации. Текст файла конфигурации в формате xml можно посмотреть на вкладке "XML" диалогового окна конфигуратора. Для отправки сообщения используется JavaMail, таблицы параметров внутри API пакетов по ссылке).

Начиная с версии 4.2 осуществляется гарантированная доставка сообщений с помощью JMS.

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

• Не продолжать выполнение процесса при ошибке отправки: при ошибке обработки конфигурации выполнение процесса не проходит дальше (транзакция откатывается к предыдущей точке).
• Файл базовых настроек, расположенный на сервере. Здесь можно указать путь к файлу (относительно jboss/standalone/wfe.custom/),который содержит базовые настройки (вкладок Соединение с сервером и Реквизиты сообщения) в таком же формате. Это облегчает конфигурирование нескольких обработчиков (общие параметры). Эти параметры имеют меньший приоритет перед заданными в конфигураторе (если заданы).

Настройки соединения с сервером

В этой вкладке допускается использование переменных в полях формы в виде ${скриптовоеНазваниеПеременной}.

• Протокол отправки: протокол работы с сервером
• Адрес сервера: IP адрес или название узла почтового сервера
• Порт сервера: Порт почтового сервера
• Использовать аутентификацию: Исходящий почтовый сервер требует проверки подлинности пользователя
• Режим трассировки: если включить - в логи пишется информация о взаимодействии с почтовым сервером
• Дополнительные параметры соединения можно задать исходя из всех возможных в javamail.

Настройки реквизитов сообщения

В этой вкладке допускается использование переменных в полях формы в виде ${скриптовоеНазваниеПеременной}.

Также можно указать email исполнителя с помощью метода: ${GetExecutorEmails(Согласователь)}, где Согласователь может быть пользователем или группой, в т.ч. ролью.

• Заголовок: заголовок сообщения
• Кому: email-адрес для отправки сообщения
• Копия: email-адрес для отправки копии

Дополнительные параметры сообщения можно задать исходя из всех возможных в javamail.

Настройки тела сообщения

• Использовать форму узла-действия: Чек-бокс доступен, если обработчик находится в узле, в этом узле определена форма и форма

является типа FTL (freemarker).

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

# Что можно использовать в теле сообщения

В теле сообщения можно использовать все переменные БП по скриптовому названию.

В теле сообщения обработчика также доступны контекстные переменные

Интерактивная форма (${interaction}, ru.runa.wfe.form.Interaction) - только если обработчик помещён на узле-действии

Использовать проверку в браузере	${interaction.useJSValidation?string("да", "нет")}
Список обязательных переменных		${interaction.requiredVariableNames}
Код формы	 			${interaction.formData} (byte[])

Задание (${task}, ru.runa.wfe.task.Task) - только если обработчик помещён на узле-действии

ID					${task.id}
ID задания				${task.nodeId}
Название 				${task.name}
Описание 				${task.description}
Название роли    			${task.swimlane.name}
Исполнитель				${task.executor.label}
Дата создания		    		${task.createDate?datetime}
Срок выполнения (deadline)    		${task.deadlineDate?datetime}

Экземпляр процесса (${process}, ru.runa.wfe.execution.Process)

ID					${process.id}
Дата запуска				${process.startDate?datetime}
Дата завершения 			${process.endDate?datetime} (только для асинхронных заданий)
Иерархия подпроцессов			${process.hierarchyIds}

Определение процесса (${process.deployment}, ru.runa.wfe.definition.Deployment)

ID					${process.deployment.id}
Версия					${process.deployment.version}
Название				${process.deployment.name}
Описание				${process.deployment.description}
Категория				${process.deployment.category}
Загружено в систему			${process.deployment.createDate?datetime}

В теле сообщения бота также доступны контекстные переменные

Интерактивная форма (${interaction}, ru.runa.wfe.form.Interaction)

Использовать проверку в браузере	${interaction.useJSValidation?string("да", "нет")}
Список обязательных переменных		${interaction.requiredVariableNames}
Код формы	 			${interaction.formData} (byte[])

Задание (${task}, ru.runa.wfe.task.dto.WfTask)

ID					${task.id}
ID задания				${task.nodeId}
ID процесса				${task.processId}
ID определение процесса		${task.deploymentId}
Название определение процесса		${task.definitionName}
Название 				${task.name}
Описание 				${task.description}
Название роли    			${task.swimlaneName}
Исполнитель				${task.owner.label}
Дата создания		    		${task.creationDate?datetime}
Срок выполнения (deadline)    		${task.deadlineDate?datetime}
Срок выполнения на исходе (90%)	${task.deadlineWarningDate?datetime}

Настройки в XML

Здесь отображается конфигурация как она есть в реальности.

Кнопки

• Отправить тестовое письмо: отправка письма в соответствии с указанными параметрами, непосредственно из Среды разработки. Обратите внимание, что при задании настроек соединения в Файле базовых настроек тестовое сообщение отправлено не будет.
• Копировать: копирование конфигурации в буфер обмена (как Ctrl-C)
• Ок: сохранение конфигурации
• Отмена редактирования

# Пример использования smtp.gmail.com в качестве сервера исходящей почты

Заполните параметры обработчика как показано на рисунке ниже:

Использование smtp.gmail.com:465 требует других настроек.

   <param name="mail.transport.protocol" value="smtps"/>
   <param name="mail.host" value="smtp.gmail.com"/>
   <param name="mail.smtps.port" value="465"/>
   <param name="mail.smtps.auth" value="true"/>
   <param name="mail.user" value="***@gmail.com"/>
   <param name="mail.password" value="***"/>
   <param name="mail.smtps.ssl.trust" value="smtp.gmail.com"/>

Если название компьютера содержит неподдерживаемые символы (например кириллицу) для отправки команд SMTP HELO, EHLO, может помочь параметр.

<param name="mail.smtp.localhost" value="localhost"/>
<param name="mail.smtps.localhost" value="localhost"/>

# Установка сертификата в хранилище

Если вы не используете настройку {mail.smtp.ssl.trust, mail.smtps.ssl.trust} - то необходимо импортировать сертификат сервера в хранилище ключей для устранения ошибки

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Для получения сертификата используйте пакет OpenSSL:

openssl s_client -connect smtp.gmail.com:587 -starttls smtp > mail-smtp.cer

Откройте сформированный mail-smtp.cer и удалите все что до -----BEGIN CERTIFICATE----- и после -----END CERTIFICATE----- , сохраните изменения.

Скопируйте полученный сертификат в JAVA_HOME

Перейти в JAVA_HOME и выполните

C:\Program Files (x86)\Java\jdk1.7.0_01>keytool -import -alias smtp.gmail.com -file mail-smtp.cer -keystore .\jre\lib\security\jssecacerts

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

# ActorNameActionHandler (не рекомендуется к использованию ^4.0.0+, используйте GetExecutorInfoHandler)

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

Необходимо указать переменную с кодом сотрудника или переменную с логином сотрудника в качестве входящих данных для обработчика. Затем выбрать формат исходящих данных:

• name - логин сотрудника

• full name - полное имя сотрудника

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

# BotInvokerActionHandler

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

# EscalationActionHandler

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

# AddObjectToListActionHandler

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

# RemoveObjectFromListActionHandler

Удаляет переменную из списка.

# CreateOptionActionHandler

Создает опцию (ru.runa.wf.web.Option) (может быть использована в элементе формы множественный выбор).

# Обработчики Excel/Word

Сюда входят обработчики, предназначенные для работы с xlsx и docx файлами. Данные обработчики построены на основе библиотеки Apache POI.

Apache POI — это библиотека на языке Java для чтения и записи документов,таких как Excel, PowerPoint и Word.

Для чтения данных из xlsx файлов используется обработчик office.excel.handler.ExcelReadHandler, для записи - office.excel.handler.ExcelSaveHandler. Для работы с файлами DOCX используется обработчик office.doc.DocxHandler

excel.handler.ExcelReadHandler

Позволяет выполнять чтение данных из xlsx файлов. Для настройки параметров обработчика используется следующая форма:

“Входной файл” – здесь задается полный путь к файлу, либо файловая переменная, указывающая на данный файл, например:

“Добавить ячейку” – добавляет параметры для чтения данных из отдельной ячейки:

1). “Переменная” – в которую будет считано значение из ячейки;

2). “Страница” – имя или номер страницы, на которой расположена ячейка;

3). “Столбец/Строка” – адрес ячейки (нумерация с 1 до 999999999);

“Добавить горизонтально”/ “Добавить вертикально” – добавляет параметры для чтения массивов данных по горизонтали и вертикали соответственно:

1). “Переменная” – переменная массив формата "Список", в который будет считаны данные;

2). “Страница” – так же как и в случае отдельной ячейки, данный параметр задает имя или номер (нумерация с 1) страницы, на которой расположены считываемые данные;

3). “Начальный столбец”/“Строка”, “Столбец/Начальная строка” – адрес ячейки, начиная с которой необходимо считывать массив данных (по горизонтали – строка, по вертикали - столбец), нумерация также начинается с “1”;

Например:

Обработчик будет выполнять чтение файла “ввод.xls”, находящегося по адресу \\SRV\nfsshared\

Будет считано значение в переменную “Ячейка1” из отдельной ячейки, находящейся на странице с именем “Лист5” по адресу столбец 2, строка 1.

Будет считан массив “список1”, в который попадут значения из строки 3, начиная со столбца 1. Страница задана по номеру – 1.

Будет считан массив “список2”, в который попадут значения из столбца 7, начиная со строки 4. Страница – “Sheet1”.

Также конфигурацию обработчика можно задать и в виде xml, например:

excel.handler.ExcelSaveHandler

Используется для записи данных в файл xlsx,имеет форму для конфигурирования параметров:

Описание параметров:

“Входной файл” – представляет собой шаблон документа, на основе которого будет создан выходной файл. Данный параметр можно задать как с помощью файловой переменной или полного пути к файлу, так и создать/импортировать шаблон непосредственно в бизнес-процесс.

Например, если шаблон имеет следующий вид:

то результат будет содержать:

“Выходной файл” – результирующий файл, в который будут записаны данные. Здесь отдельно задается имя файла и путь, но можно также использовать файловую переменную, например:

“Добавить ячейку”, “Добавить горизонтально”, “Добавить вертикально” – добавляет параметры для записи переменной в отдельную ячейку, массива в область по горизонтали и массива по вертикали соответственно. Параметры и возможные значения, такие же как и в конфигураторе для обработчика excel.handlers.ReadHandler

Например:

В качестве входного файла (шаблона) задан файл c:/in/sample.xls, на основе его будет создан файл c:/out/Result.xls, на страницу Sheet1 запишутся:

• переменная “Ячейка1” по адресу столбец 1: строка 1

• массив “список1” (столбец 2: начальная строка 1):

• массив “список2” (начальный столбец 3: строка 1)

doc.DocxHandler

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

Описание синтаксиса шаблонов

Конфигуратор обработчика имеет следующий вид:

“Входной файл” – файл шаблона, на основе которого формируется выходной docx файл. Задается с помощью файловой переменной или полного пути к файлу. Также существует возможность создать/импортировать файл шаблона непосредственно в бизнес-процесс;

“Выходной файл” – здесь вводится “Имя файла”, и “Каталог” в котором необходимо создать docx файл. Но также как и в случае входного файла, можно использовать и файловую переменную.

“Выдавать ошибку в случае несоответствия шаблона” – при установке данного параметра, будет производится проверка входного файла (шаблона) на соответствие с конфигурацией, в случае отсутствия каких либо переменных или несоответствия имен, в ходе выполнения данного обработчика – будет выдаваться ошибка, и выходной файл сформирован не будет;

# Создать переменную даты

Класс: ru.runa.wfe.extension.handler.var.CreateCalendarHandler

Проводит операции с переменной даты: установление или добавление времени. В конфигурации в качестве числа можно указать целочисленную переменную в формате ${переменная}. Для операции добавления разрешается использовать рабочее время с учетом бизнес-календаря.

# Добавить права на чтение процесса

Класс: ru.runa.wfe.extension.handler.process.AddReadProcessPermissionsHandler

Добавляет полномочия на чтение на текущий экземпляр процесса указанным исполнителям.

Параметры

название	тип	примечание
Исполнители	Один или несколько исполнителей (организованные в списке)	В случае если полномочия уже имеются - ничего не происходит. В случае если переменная не проинициализирована - ничего не происходит.