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

Этот раздел перенесён из документации Camunda 7 и в дальнейшем будет доработан с учётом особенностей OpenBPM Engine

Существует несколько типов форм, которые в первую очередь используются в OpenBPM Engine Tasklist. Чтобы реализовать форму задачи в вашем приложении, необходимо связать ресурс формы с BPMN 2.0-элементом на диаграмме процесса. Для вызова форм задач подходят BPMN 2.0-элементы Start Event и User Task.

Формы указываются с помощью Form Key или Form Reference и могут либо встраиваться в OpenBPM Engine Tasklist, либо обрабатываться пользовательским приложением. В зависимости от вашего сценария можно использовать разные типы форм:

Встроенные формы задач позволяют встраивать в Tasklist пользовательские HTML- и JavaScript-формы.
OpenBPM Engine Forms позволяют визуально редактировать формы в Camunda Modeler и подходят для менее сложных форм. Это единственный тип форм, который можно указывать как через Form Key, так и через Form Reference.
Внешние формы задач можно использовать для ссылок на пользовательские приложения. Такая форма не встраивается в Tasklist.

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

Детали Form Key

Form key, используемые в Tasklist, имеют структуру FORM-TYPE:LOCATION:FORM.NAME.

Имя Описание

Имя	Описание
FORM-TYPE	Может быть embedded или camunda-forms в зависимости от типа формы. Если тип не задан, форма будет показана как внешняя форма задачи.
LOCATION	Может быть deployment или app: `deployment`: файл входит в ваш deployment, например если добавить его в process archive или развернуть его из Camunda Modeler по ссылке https://docs.camunda.org/get-started/quick-start/deploy/#use-the-camunda-modeler-to-deploy-the-process. Это означает, что файл хранится в базе данных процессного движка и может быть загружен оттуда. Такой подход также позволяет версионировать форму вместе с моделью процесса. `app`: добавьте файл в проект разработки в каталог src/main/webapp/forms. Файл формы будет упакован в артефакт deployment (обычно WAR-архив) и во время выполнения будет загружаться оттуда.
FORM.NAME	Имя файла и путь внутри deployment, например forms/startFrom.html

FORM-TYPE

Может быть embedded или camunda-forms в зависимости от типа формы. Если тип не задан, форма будет показана как внешняя форма задачи.

LOCATION

Может быть deployment или app:

deployment: файл входит в ваш deployment, например если добавить его в process archive или развернуть его из Camunda Modeler по ссылке https://docs.camunda.org/get-started/quick-start/deploy/#use-the-camunda-modeler-to-deploy-the-process. Это означает, что файл хранится в базе данных процессного движка и может быть загружен оттуда. Такой подход также позволяет версионировать форму вместе с моделью процесса.
app: добавьте файл в проект разработки в каталог src/main/webapp/forms. Файл формы будет упакован в артефакт deployment (обычно WAR-архив) и во время выполнения будет загружаться оттуда.

FORM.NAME

Имя файла и путь внутри deployment, например forms/startFrom.html

Чтобы настроить форму в процессе, откройте процесс в Camunda Modeler по ссылке http://camunda.org/bpmn/tool/ и выберите нужный User Task или Start Event. Затем откройте панель свойств и введите Form Key. Соответствующий XML-тег выглядит так:

<userTask id="theTask" camunda:formKey="camunda-forms:deployment:forms/userTask.form"
          camunda:candidateUsers="John, Mary"
          name="my Task">

Встроенные формы задач

Embedded task forms представляют собой HTML- и JavaScript-формы. Подробнее о создании встроенных форм можно прочитать в справочнике по встроенным формам задач.

Чтобы добавить встроенную форму в приложение, просто создайте HTML-файл и сошлитесь на него из User Task или Start Event в модели процесса. Например, можно создать файл FORM_NAME.html, содержащий нужную разметку формы, например простую форму с двумя полями ввода:

<form role="form" name="form">
  <div class="form-group">
    <label for="customerId-field">Customer ID</label>
    <input required
           cam-variable-name="customerId"
           cam-variable-type="String"
           class="form-control" />
  </div>
  <div class="form-group">
    <label for="amount-field">Amount</label>
    <input cam-variable-name="amount"
           cam-variable-type="Double"
           class="form-control" />
  </div>
</form>

Form key для такого файла может быть embedded:deployment:FORM_NAME.html или embedded:app:forms/FORM_NAME.html.

OpenBPM Engine Forms

OpenBPM Engine Forms создаются как отдельные файлы в Camunda Modeler и могут развёртываться вместе с моделями процессов. Схема формы хранится в файлах .form. Чтобы изучить все параметры конфигурации элементов формы, обратитесь к справочнику OpenBPM Engine Forms по ссылке https://docs.camunda.io/docs/guides/utilizing-forms/.

Переменные процесса сопоставляются с полями формы, если ключ поля совпадает с именем переменной.

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

Ссылка на форму

Form References дают OpenBPM Engine Forms гибкий способ связывать элемент BPMN-диаграммы с формой. Чтобы связать BPMN-элемент Start Event или User Task с OpenBPM Engine Form, необходимо указать идентификатор формы в атрибуте camunda:formRef. Дополнительно атрибут camunda:formRefBinding определяет, какую версию формы нужно использовать.

Допустимые значения:

deployment: ссылается на OpenBPM Engine Form с указанным ключом, которая была развёрнута в том же deployment, что и процесс, содержащий ссылку.
latest: указывает на последнюю развёрнутую версию OpenBPM Engine Form.
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 Engine Forms

Ключ формы

В качестве альтернативы formRef можно сослаться на файл OpenBPM Engine Form с помощью deployment или app form key:

camunda-forms:deployment:FORM_NAME.form
camunda-forms:app:forms/FORM_NAME.form

Чтобы ввести formKey в Modeler, в выпадающем списке необходимо выбрать тип Embedded or External Task Forms.

С точки зрения разработчика форм formRef предоставляет больше гибкости, чем formKey, поскольку формы можно развёртывать независимо от модели процесса.

Связывание переменных процесса

Чтобы задать значение по умолчанию для поля формы, необходимо определить переменную процесса с тем же именем, что и ключ поля. Локальные переменные, например созданные через Input Parameter по ссылке ../process-engine/variables/#input-output-variable-mapping для User Task, имеют приоритет над переменными процесса.

Маппинги ввода и вывода для значений полей формы по умолчанию

Отправленные значения формы возвращаются в процессный движок как переменные:

Если переменная процесса с тем же именем, что и ключ поля формы, уже существует, её значение будет перезаписано значением из формы.
Если у User Task задан Input Parameter с тем же именем, что и ключ поля формы, будет использована эта локальная переменная. В этом случае необходимо определить Output Parameter по ссылке ../process-engine/variables/#input-output-variable-mapping, чтобы перенести локальную переменную в переменную процесса для дальнейшего использования в других элементах процесса.
Если переменной с таким именем ещё нет, при отправке формы будет создана новая переменная процесса и получит значение из формы.

Динамические компоненты

Можно связать список доступных значений некоторых типов компонентов (Select, Radio Buttons, Checklist и Taglist) с переменной. Таким образом OpenBPM Engine Forms смогут динамически показывать доступные варианты на основе данных процесса (переменных).

Чтобы привязать переменную к динамическому компоненту, укажите её имя в конструкторе форм Camunda Modeler на панели Properties в разделе Options Source → Type → Input Data → Dynamic options → Input values key для соответствующего компонента.

OpenBPM Engine Forms поддерживают следующие типы переменных, которые могут представлять JSON:

Json
Object с serializationDataFormat: application/json

OpenBPM Engine Forms сохраняют и читают пользовательский выбор для каждого компонента в переменной, имя которой совпадает с ключом компонента. Если переменной для хранения выбора пользователя в multi-select компонентах (Checklist или Taglist) ещё нет, при отправке формы будет создана новая переменная того же типа, что и переменная, задающая доступные значения.

Формат для определения доступных значений выглядит так:

[
  {
    "label": "Dynamic Value 1",
    "value": "dynamicValue1"
  },
  {
    "label": "Dynamic Value 2",
    "value": "dynamicValue2"
  }
]

Если вы только прототипируете приложение, можно использовать и сокращённый формат:

["Dynamic Value 2", "Dynamic Value 2"]

Развёртывание

Если вы хотите включить OpenBPM Engine Form в состав deployment, необходимо развернуть файл .form в том же deployment, что и соответствующую диаграмму .bpmn, например с помощью Camunda Modeler, начиная с версии Modeler 5.0.0.

OpenBPM Engine Forms по умолчанию не развёртываются автоматически как часть process archive. Для этого необходимо явно настроить deployment: либо добавить форму как ресурс напрямую, либо включить form в список additionalResourceSuffixes. При использовании OpenBPM Engine Run все дополнительные ресурсы, включая OpenBPM Engine Forms, размещённые в каталоге configuration/resources/, развёртываются автоматически.

Развёртывание файла OpenBPM Engine Form

Можно также подключать OpenBPM Engine Forms из других deployment, используя form references.

Внешние формы задач

При встраивании процессного движка в пользовательское приложение можно использовать любое значение в свойстве form key как ссылку на собственную форму. Благодаря этому ваш фронтенд сможет отрисовывать корректную форму для каждой пользовательской задачи.

Если вы хотите вызвать форму задачи, которая не является частью вашего приложения, можно добавить ссылку на нужную форму. Такая форма настраивается аналогично embedded task form. Откройте панель свойств и укажите FORM_NAME.html в качестве form key. Соответствующий XML-тег выглядит так:

<userTask id="theTask" camunda:formKey="app:FORM_NAME.html"
          camunda:candidateUsers="John, Mary"
          name="my Task">

Tasklist создаёт URL по следующему шаблону:

"../.." + contextPath (of process application) + "/" + "app" + formKey (from BPMN 2.0 XML) + "processDefinitionKey=" + processDefinitionKey + "&callbackUrl=" + callbackUrl;

После завершения задачи будет вызван callback URL.

Как добавить JSF-формы в процессное приложение

Другие формы задач

Эти формы задач не используют атрибут form-key для ссылки. Они не рекомендуются для production-использования и предназначены в основном для тестирования и разработки.

Универсальные формы задач

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

Универсальная стартовая форма

Нажмите кнопку Add a variable, чтобы добавить переменную, которая будет передана экземпляру процесса при завершении задачи. Укажите имя переменной, выберите тип и введите нужное значение. Можно добавить столько переменных, сколько требуется. После нажатия кнопки Complete экземпляр процесса будет содержать введённые значения. Generic task forms особенно полезны на этапе разработки, когда вы ещё не реализовали все формы задач, но уже хотите запускать workflow. Для отладки и тестирования у такого подхода тоже есть заметные преимущества.

Уже существующие переменные экземпляра процесса можно загрузить, нажав кнопку Load Variables.

Сгенерированные формы задач

Набор возможностей OpenBPM Engine Forms и Generated Task Forms во многом похож. Для новых проектов рекомендуется использовать OpenBPM Engine Forms, поскольку они гибче и их проще создавать.

Процессный движок OpenBPM Engine поддерживает генерацию HTML-форм задач на основе метаданных Form Data, заданных в BPMN 2.0 XML. Form Data Metadata представляет собой набор vendor-extensions 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>

Метаданные формы можно редактировать графически в Camunda Modeler по ссылке https://camunda.com/products/camunda-platform/modeler/.

В Tasklist такая форма будет выглядеть следующим образом:

Сгенерированная форма

Как видно, элемент <camunda:formData … /> задаётся как дочерний элемент BPMN-элемента <extensionElements>. Метаданные формы состоят из нескольких form fields, которые представляют отдельные поля ввода, где пользователь должен указать значение или выбрать вариант.

Form Data может содержать следующие атрибуты:

Attribute	Explanation
businessKey	Идентификатор поля формы, которое будет помечено как cam-business-key

Attribute

Explanation

businessKey

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

Поля формы

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

Поле формы может иметь следующие атрибуты:

Attribute	Explanation
id	Уникальный идентификатор поля формы, соответствующий имени переменной процесса, в которую будет записано значение поля при отправке формы.
label	Подпись, отображаемая рядом с полем формы.
type	Тип данных поля формы. Из коробки поддерживаются следующие типы: string long date boolean enum
defaultValue	Значение, используемое по умолчанию (предварительный выбор) для поля.

Attribute

Explanation

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

label

Подпись, отображаемая рядом с полем формы.

type

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

string
long
date
boolean
enum

defaultValue

Значение, используемое по умолчанию (предварительный выбор) для поля.

Валидация полей формы

Validation можно использовать для задания frontend- и backend-валидации полей формы. OpenBPM Engine предоставляет набор встроенных валидаторов полей формы и точку расширения для подключения пользовательских валидаторов.

Validation можно настроить для каждого поля формы в 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>

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

Из коробки поддерживаются следующие встроенные валидаторы:

Validator Explanation

Validator	Explanation
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" />`

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();

  }

}

Если определение процесса развёрнуто как часть deployment процессного приложения, экземпляр валидатора разрешается через classloader процессного приложения и/или через Spring Application Context / CDI Bean Manager процессного приложения, если используется выражение.

Лицензия и атрибуция

Эта документация была создана на базе материала "Camunda 7 Docs" от Camunda, находится под лицензией Creative Commons Attribution-ShareAlike 3.0 Unported License .

Оригинал документации: https://docs.camunda.org