Формы пользовательских задач
Форму задачи привязывают к элементу BPMN 2.0 на диаграмме процесса: к стартовому событию или к пользовательской задаче. Основное приложение для работы с задачами и их формами: OpenBPM Tasklist.
Форма указывается ключом формы (form key) или ссылкой на форму (form reference). В зависимости от сценария можно использовать разные типы форм:
-
Camunda Forms редактируются визуально в OpenBPM Studio и подходят для несложных форм. Только этот тип форм можно указать и ключом формы, и ссылкой на форму.
-
Внешние формы задач реализуются в вашем собственном приложении.
-
Сгенерированные формы задач описываются полями формы прямо в BPMN 2.0 XML.
Если форма не указана, используется форма по умолчанию.
Структура ключа формы
Ключ формы, который ссылается на развернутую форму, имеет структуру FORM-TYPE:LOCATION:FORM.NAME.
| Часть | Описание |
|---|---|
FORM-TYPE |
Тип формы: |
LOCATION |
|
FORM.NAME |
Имя файла и путь внутри развертывания, например |
Пример XML пользовательской задачи с ключом формы:
<userTask id="theTask" camunda:formKey="camunda-forms:deployment:forms/userTask.form"
camunda:candidateUsers="John, Mary"
name="my Task">
Camunda Forms
Формы Camunda Forms создаются отдельными файлами в OpenBPM Studio и развертываются вместе с моделями процессов. Схема формы хранится в файле .form. Как процессный движок развертывает и находит формы, описано в справочнике Camunda Forms.
Поле формы связывается с переменной процесса, если ключ поля совпадает с именем переменной.
|
Определение формы не добавляет разрешений на переменные процесса. Пользователи по-прежнему могут передать любые переменные через API завершения формы, например через REST API. Форма работает поверх API завершения задачи: она отображает поля и проверяет переданные значения. |
Ссылка на форму
Ссылка на форму позволяет гибко связать элемент BPMN-диаграммы с формой Camunda Forms. Чтобы связать стартовое событие или пользовательскую задачу с формой, укажите идентификатор формы в атрибуте camunda:formRef. Атрибут camunda:formRefBinding определяет, какая версия формы используется.
Допустимые значения camunda:formRefBinding:
-
deployment: форма с указанным ключом из того же развертывания, что и процесс со ссылкой; -
latest: последняя развернутая версия формы; -
version: конкретная версия, заданная атрибутомcamunda:formRefVersion.
<bpmn:userTask
id="myUserTask"
camunda:formRef="formId"
camunda:formRefBinding="version"
camunda:formRefVersion="1">
</bpmn:userTask>
Атрибуты camunda:formRef и camunda:formRefVersion можно задать выражениями. Они вычисляются, когда выполнение доходит до задачи или стартового события.
<bpmn:userTask
id="myUserTask"
camunda:formRef="${formId}"
camunda:formRefBinding="version"
camunda:formRefVersion="${formVersion}">
</bpmn:userTask>
В OpenBPM Studio ссылка на форму задаётся на панели свойств: в поле Form → Form type выберите Camunda form, затем выберите форму в поле Form → Form reference.
Ключ формы
Вместо formRef на файл формы Camunda Forms можно сослаться ключом формы:
-
camunda-forms:deployment:FORM_NAME.form -
operaton-forms:deployment:FORM_NAME.form
OpenBPM Tasklist отображает форму Camunda Forms с любым из этих префиксов так же, как форму, заданную через formRef.

Для разработчика форм formRef гибче, чем formKey: форму можно развертывать независимо от модели процесса.
Связывание переменных процесса
Чтобы задать значение поля формы по умолчанию, определите переменную процесса с тем же именем, что и ключ поля. Локальные переменные, например созданные через входной параметр пользовательской задачи, имеют приоритет над переменными процесса.

Отправленные значения формы возвращаются в процессный движок как переменные:
-
Если переменная процесса с именем, совпадающим с ключом поля формы, уже существует, её значение перезаписывается значением из формы.
-
Если у пользовательской задачи есть входной параметр с именем, совпадающим с ключом поля формы, значение записывается в эту локальную переменную. Чтобы передать его в переменную процесса для других элементов процесса, определите выходной параметр.
-
Если переменной с таким именем нет, при отправке формы создаётся новая переменная процесса со значением из формы.
Динамические компоненты
Список доступных значений некоторых компонентов (Select, Radio Buttons, Checklist и Taglist) можно связать с переменной. Тогда форма показывает варианты выбора на основе данных процесса.
Чтобы привязать переменную к динамическому компоненту, укажите её имя в конструкторе форм OpenBPM Studio на панели Properties: Options Source → Type → Input Data → Dynamic options → Input values key.
Для значений поддерживаются следующие типы переменных, которые могут содержать JSON:
-
Json; -
ObjectсserializationDataFormat: application/json.
Выбор пользователя в каждом компоненте сохраняется в переменной, имя которой совпадает с ключом компонента, и читается из неё. Если для компонента с множественным выбором (Checklist или Taglist) такой переменной ещё нет, при отправке формы создаётся новая переменная того же типа, что и переменная с доступными значениями.
Формат доступных значений:
[
{
"label": "Dynamic Value 1",
"value": "dynamicValue1"
},
{
"label": "Dynamic Value 2",
"value": "dynamicValue2"
}
]
Для прототипа можно использовать сокращённый формат:
["Dynamic Value 2", "Dynamic Value 2"]
Развертывание
Чтобы форма Camunda Forms вошла в deployment, разверните файл .form в том же развертывании, что и диаграмму .bpmn, например из OpenBPM Studio.
|
Формы Camunda Forms по умолчанию не попадают в развертывание архива процессов автоматически.
Настройте развертывание явно: добавьте форму как ресурс или включите |

Формы Camunda Forms из других развертываний можно подключать ссылкой на форму.
Внешние формы задач
Если процессный движок встроен в ваше приложение, в качестве ключа формы можно указать любое значение и использовать его как ссылку на собственную форму. По ключу формы ваш фронтенд выбирает, какую форму показать для пользовательской задачи.
<userTask id="theTask" camunda:formKey="FORM_NAME"
camunda:candidateUsers="John, Mary"
name="my Task">
В OpenBPM Tasklist такими формами служат пользовательские React-компоненты, зарегистрированные по значению formKey. Подробнее см. Пользовательские формы.
Задачи без формы
Если для пользовательской задачи или стартового события форма не задана, OpenBPM Tasklist при запуске процесса показывает только поле Business Key, а для задачи только кнопку Complete.
Сгенерированные формы задач
|
Camunda Forms и сгенерированные формы задач во многом похожи по возможностям. Для новых проектов рекомендуется Camunda Forms: они гибче, и их проще создавать. |
| OpenBPM Tasklist не отображает сгенерированные формы задач. |
Процессный движок OpenBPM Engine может генерировать HTML-формы задач по метаданным формы (form data), заданным в BPMN 2.0 XML. Метаданные формы задаются расширениями BPMN 2.0 от OpenBPM Engine и описывают поля формы прямо в BPMN 2.0 XML:
<userTask id="usertask" name="Task">
<extensionElements>
<camunda:formData>
<camunda:formField
id="firstname" label="First Name" type="string">
<camunda:validation>
<camunda:constraint name="maxlength" config="25" />
<camunda:constraint name="required" />
</camunda:validation>
</camunda:formField>
<camunda:formField
id="lastname" label="Last Name" type="string">
<camunda:validation>
<camunda:constraint name="maxlength" config="25" />
<camunda:constraint name="required" />
</camunda:validation>
</camunda:formField>
<camunda:formField
id="dateOfBirth" label="Date of Birth" type="date" />
</camunda:formData>
</extensionElements>
</userTask>
Метаданные формы можно редактировать графически в OpenBPM Studio.
Элемент <camunda:formData … /> задаётся как дочерний элемент BPMN-элемента <extensionElements>. Метаданные формы состоят из полей формы (form fields). Каждое поле описывает отдельный элемент ввода, в котором пользователь вводит значение или выбирает вариант.
Атрибуты элемента formData:
| Атрибут | Описание |
|---|---|
businessKey |
Идентификатор поля формы, которое помечается как |
Поля формы
|
Определение полей формы не добавляет разрешений на переменные процесса. Пользователи по-прежнему могут передать любые переменные через API завершения формы, например через REST API. Поля формы работают поверх API завершения задачи: по ним отображается форма и проверяются отправленные значения. |
Атрибуты поля формы:
| Атрибут | Описание |
|---|---|
id |
Уникальный идентификатор поля формы. Совпадает с именем переменной процесса, в которую записывается значение поля при отправке формы. |
label |
Подпись рядом с полем формы. |
type |
Тип данных поля формы. Из коробки поддерживаются типы:
|
defaultValue |
Значение поля по умолчанию (предварительный выбор). |
Валидация полей формы
Валидация задаёт проверку полей формы на стороне фронтенда и бэкенда. OpenBPM Engine предоставляет набор встроенных валидаторов и точку расширения для собственных валидаторов.
Валидация настраивается для каждого поля формы в BPMN 2.0 XML:
<camunda:formField
id="firstname" label="First Name" type="string">
<camunda:validation>
<camunda:constraint name="maxlength" config="25" />
<camunda:constraint name="required" />
</camunda:validation>
</camunda:formField>
Для каждого поля формы можно задать список ограничений.
Встроенные валидаторы:
| Валидатор | Описание |
|---|---|
required |
Применим ко всем типам. Проверяет, что для поля передано значение. Отклоняет
|
minlength |
Применим к полям типа
|
maxlength |
Применим к полям типа
|
min |
Применим к числовым полям. Проверяет минимальное значение. Пропускает
|
max |
Применим к числовым полям. Проверяет максимальное значение. Пропускает
|
readonly |
Применим ко всем типам. Запрещает отправлять пользовательское значение для этого поля.
|
OpenBPM Engine поддерживает собственные валидаторы. На них можно сослаться по полному имени класса или выражением. Через выражение можно получить бины Spring или CDI с аннотацией @Named:
<camunda:formField
id="firstname" label="First Name" type="string">
<camunda:validation>
<camunda:constraint name="validator" config="com.asdf.MyCustomValidator" />
<camunda:constraint name="validator" config="${validatorBean}" />
</camunda:validation>
</camunda:formField>
Для собственного валидатора атрибут name должен иметь значение validator.
|
Собственный валидатор реализует интерфейс io.openbpm.bpm.engine.impl.form.validator.FormFieldValidator:
public class CustomValidator implements FormFieldValidator {
public boolean validate(Object submittedValue, FormFieldValidatorContext validatorContext) {
// ... do some custom validation of the submittedValue
// get access to the current execution
DelegateExecution e = validatorContext.getExecution();
// get access to all form fields submitted in the form submit
Map<String,Object> completeSubmit = validatorContext.getSubmittedValues();
}
}
Если определение процесса развернуто в составе процессного приложения, класс валидатора загружается через загрузчик классов процессного приложения. Если валидатор задан выражением, бин разрешается через контекст Spring или CDI Bean Manager процессного приложения.
Документация создана на основе Camunda 7 Docs (Camunda, docs.camunda.org) и распространяется по лицензии Creative Commons Attribution-ShareAlike 3.0 Unported.