Формы пользовательских задач

Форму задачи привязывают к элементу BPMN 2.0 на диаграмме процесса: к стартовому событию или к пользовательской задаче. Основное приложение для работы с задачами и их формами: OpenBPM Tasklist.

Форма указывается ключом формы (form key) или ссылкой на форму (form reference). В зависимости от сценария можно использовать разные типы форм:

  1. Camunda Forms редактируются визуально в OpenBPM Studio и подходят для несложных форм. Только этот тип форм можно указать и ключом формы, и ссылкой на форму.

  2. Внешние формы задач реализуются в вашем собственном приложении.

  3. Сгенерированные формы задач описываются полями формы прямо в BPMN 2.0 XML.

Если форма не указана, используется форма по умолчанию.

Структура ключа формы

Ключ формы, который ссылается на развернутую форму, имеет структуру FORM-TYPE:LOCATION:FORM.NAME.

Часть Описание

FORM-TYPE

Тип формы: camunda-forms или operaton-forms (оба префикса равнозначны). Если тип не задан, форма считается внешней формой задачи.

LOCATION

deployment: файл формы входит в развертывание, например добавлен в архив процессов или развернут из OpenBPM Studio (см. быстрый старт). Файл хранится в базе данных процессного движка и загружается оттуда. Так форма версионируется вместе с моделью процесса.

FORM.NAME

Имя файла и путь внутри развертывания, например forms/userTask.form.

Пример 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.

Указание ключа формы для Camunda Forms

Для разработчика форм 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 по умолчанию не попадают в развертывание архива процессов автоматически. Настройте развертывание явно: добавьте форму как ресурс или включите form в список additionalResourceSuffixes. В OpenBPM Engine Run все дополнительные ресурсы из каталога configuration/resources/, в том числе формы Camunda Forms, развертываются автоматически.

Развертывание формы 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

Идентификатор поля формы, которое помечается как cam-business-key.

Поля формы

Определение полей формы не добавляет разрешений на переменные процесса. Пользователи по-прежнему могут передать любые переменные через API завершения формы, например через REST API. Поля формы работают поверх API завершения задачи: по ним отображается форма и проверяются отправленные значения.

Атрибуты поля формы:

Атрибут Описание

id

Уникальный идентификатор поля формы. Совпадает с именем переменной процесса, в которую записывается значение поля при отправке формы.

label

Подпись рядом с полем формы.

type

Тип данных поля формы. Из коробки поддерживаются типы:

  • string

  • long

  • date

  • boolean

  • enum

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

Применим ко всем типам. Проверяет, что для поля передано значение. Отклоняет null и пустые строки.

<camunda:constraint name="required" />

minlength

Применим к полям типа string. Проверяет минимальную длину текста. Пропускает null.

<camunda:constraint name="minlength" config="4" />

maxlength

Применим к полям типа string. Проверяет максимальную длину текста. Пропускает null.

<camunda:constraint name="maxlength" config="25" />

min

Применим к числовым полям. Проверяет минимальное значение. Пропускает null.

<camunda:constraint name="min" config="1000" />

max

Применим к числовым полям. Проверяет максимальное значение. Пропускает null.

<camunda:constraint name="max" config="10000" />

readonly

Применим ко всем типам. Запрещает отправлять пользовательское значение для этого поля.

<camunda:constraint name="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.