> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aseeflow.org/llms.txt
> Use this file to discover all available pages before exploring further.

# User Task Forms

There are different types of forms which are primarily used in Tasklist. To implement a task form in your application, you have to connect the form resource with the BPMN 2.0 element in your process diagram. Suitable BPMN 2.0 elements for calling tasks forms are the [StartEvent][start-event] and the [UserTask][user-tasks].

Forms are referenced using Form Keys or Form References and can either be embedded in ASEE Flow Tasklist or handled by a custom application. Depending on your use-case, different Form Types can be used:

1. [Embedded Task Forms](#embedded-task-forms) allow you to embed custom HTML and JavaScript forms into Tasklist.
2. [Camunda Forms](#camunda-forms) offer visual editing of forms in the Camunda Modeler and can be used for less complex forms. Camunda Forms are the only form type that can be referenced either by Form Key or by Form Reference.
3. [External Task Forms](#external-task-forms) can be used to link to custom applications. The Form will not be embedded in Tasklist.

If no form key is present, a [Generic Task Form](#generic-task-forms) will be shown.

## Form Key details

Form keys that are used in Tasklist have the structure `FORM-TYPE:LOCATION:FORM.NAME`.

<table class="table table-striped">
  <tr> <th>Name</th> <th>Description</th> </tr>
  <tr> <td>FORM-TYPE</td> <td>Can be <code>embedded</code> or <code>camunda-forms</code> depending on the form type. If no type is set, the form will be shown as an [External Task Form](#external-task-forms).</td> </tr>
  <tr> <td>LOCATION</td> <td>Can be either <code>deployment</code> or <code>app</code>: <ul> <li><em>deployment</em>: The file is part of your deployment (e.g., [by adding it to your process archive](/reference/deployment-descriptors/tags/process-archive) or [by deploying from the Camunda Modeler](/get-started/quick-start/deploy#using-the-camunda-modeler-to-deploy)), which means that it is stored in the ASEE Flow database. It can then be loaded from there. Note that this allows versioning of your form alongside the process model.</li> <li><em>app</em>: Add the file to your development project in a folder <code>src/main/webapp/forms</code>. The form file will be packaged into your deployment artifact (typically a WAR archive). During runtime it will be loaded from there.</li> </ul> </td> </tr>
  <tr> <td>FORM.NAME</td> <td>The file name and path in the deployment, e.g. <code>forms/startFrom.html</code></td> </tr>
</table>

To configure the form in your process, open the process with the [Camunda Modeler](https://camunda.com/bpmn/tool/) and select the desired [UserTask][user-tasks] or [StartEvent][start-event]. Open the properties panel and enter the Form Key. The relevant XML tag looks like this:

```xml theme={null}
<userTask id="theTask" camunda:formKey="camunda-forms:deployment:forms/userTask.form"
          camunda:candidateUsers="John, Mary"
          name="my Task">
```

## Embedded Task Forms

Embedded task forms are HTML and JavaScript forms. We provide more information about the creation of embedded forms in our [Embedded Task Forms Reference](/reference/forms/embedded-forms).

To add an embedded form to your application, simply create an HTML file and refer to it from a [UserTask][user-tasks] or a [StartEvent][start-event] in your process model. For example, you can create a `FORM_NAME.html` file containing the relevant content for your form, e.g., a simple form with two input fields:

```html theme={null}
<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>
```

The form key for this file could be `embedded:deployment:FORM_NAME.html` or `embedded:app:forms/FORM_NAME.html`.

## Camunda Forms

Camunda Forms are created as separate files using the Camunda Modeler and can be deployed together with the process models. The form schema is stored in `.form` files.
You can find out how to build Camunda Forms in the [Camunda Modeler documentation](/modeler) or refer to the [Camunda Forms Reference](https://docs.camunda.io/docs/guides/utilizing-forms/) to explore all configuration options for form elements.

[Process variables](/user-guide/process-engine/variables) are mapped to form fields where the field's key matches the variable name.

<Warning>
  **Process variables access**

  Defining forms does not introduce any permissions on process variables.
  Users can still submit any variables via APIs for form completion like the
  [Submit Task Form](/reference/rest/task/submit-form) REST API.
  Forms can be used on top of the task completion API to render form fields and validate submitted values.
</Warning>

### Form Reference

With Form References, Camunda Forms provide a flexible way of linking an element in a BPMN diagram to a form. To link a BPMN element ([StartEvent][start-event] or [UserTask][user-tasks]) to a Camunda Form, you have to specify the Id of the Camunda Form as the `camunda:formRef` attribute. Additionally, the `camunda:formRefBinding` attribute specifies which version of the Camunda Form to reference.

Valid values are:

* `deployment`, which references the Camunda Form with the given key that was deployed with the same deployment as the referencing process.
* `latest`, which will refer to the latest deployed version of the Camunda Form.
* `version`, which allows you to specify a specific version to be referenced from the BPMN element with the `camunda:formRefVersion` attribute.

```xml theme={null}
<bpmn:userTask
    id="myUserTask"
    camunda:formRef="formId"
    camunda:formRefBinding="version"
    camunda:formRefVersion="1">
</bpmn:userTask>
```

The attributes `camunda:formRef` and `camunda:formRefVersion` can be specified as an expression which will be evaluated on execution of the task or start event.

```xml theme={null}
<bpmn:userTask
    id="myUserTask"
    camunda:formRef="${formId}"
    camunda:formRefBinding="version"
    camunda:formRefVersion="${formVersion}">
</bpmn:userTask>
```

<img src="https://mintcdn.com/aseeflow/EOwJaxQ7KmXM1Gws/user-guide/task-forms/img/reference-camunda-form.png?fit=max&auto=format&n=EOwJaxQ7KmXM1Gws&q=85&s=6c6ebdafcb2898bb0d78b4f54bbd93df" alt="Provide Form Key for Camunda Forms" width="1800" height="873" data-path="user-guide/task-forms/img/reference-camunda-form.png" />

### Form Key

Aa an alternative to `formRef` you can reference a Camunda Form file with a `deployment` or `app` [form key](/user-guide/task-forms#form-key-details):

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

To enter the `formKey` in the Modeler,  you have to select `Embedded or External Task Forms` as Type in the dropdown.

From the form developers point of view, `formRef` offers more flexibility than `formKey` as they can be deployed independently from the process model.

### Process Variable Binding

To define a default value for a form field, a process variable with the same name as the form field key needs to be defined. Local variables (e.g. created by defining an [Input Parameter](/user-guide/process-engine/variables#inputoutput-variable-mapping) for the User Task) take precedence over process variables.

<img src="https://mintcdn.com/aseeflow/EOwJaxQ7KmXM1Gws/user-guide/task-forms/img/variable-mapping-camunda-form.png?fit=max&auto=format&n=EOwJaxQ7KmXM1Gws&q=85&s=f8fa059fd68d630a0277e151306cc76f" alt="User Input/Output Mappings for default values for form fields" width="420" height="512" data-path="user-guide/task-forms/img/variable-mapping-camunda-form.png" />

The submitted values of a form are returned as variables to the process engine:

* When a process variable with the same name as the form field key already existed, then its value will be overwritten by the form submission.
* When the User Task has an Input Parameter defined with the same name as the form field key, then this local variable will be used. In this case, an [Output Parameter](/user-guide/process-engine/variables#inputoutput-variable-mapping) needs to be defined to map the local variable to a process variable for usage in other process elements.
* When no variable exists with the same name as the form field key, then a new process variable will be created and gets the value from the submission.

### Dynamic Components

You can bind the available options of some component types (Select, Radio Buttons, Checklist, and Taglist) to a variable.
Like this, Camunda Forms show available options dynamically based on process data (variables).

To bind a variable to a dynamic component, define its name in Camunda Modeler's form builder in the Properties Panel under **Options Source** -> **Type** -> **Input Data** -> **Dynamic options** -> **Input values key** for the respective component.

Camunda Forms support the following variable types that can represent JSON:

* `Json`
* `Object` with the `serializationDataFormat: application/json`

Camunda Forms store and retrieve user selections for each component in a variable whose name equals the component key.
If a variable supposed to store the user selection for multi-select components (Checklist or Taglist) doesn't exist yet, a new one is created on form submission with the same type as the variable that defines the available options.

The format to define available options looks as follows:

```json theme={null}
[
  {
    "label": "Dynamic Value 1",
    "value": "dynamicValue1"
  },
  {
    "label": "Dynamic Value 2",
    "value": "dynamicValue2"
  }
]
```

If you are about to prototype your application, you can also use the shortcut format:

```json theme={null}
["Dynamic Value 2", "Dynamic Value 2"]
```

### Deployment

If you want to include your Camunda Form as part of the `deployment`, then you need to deploy the `.form` file in the same deployment as the respective `.bpmn` diagram - for example using the Camunda Modeler (since Modeler Version 5.0.0).

<Warning>
  **Automatic deployment**

  Camunda Forms are not automatically deployed as part of a [process archive](/reference/deployment-descriptors/tags/process-archive) by default.
  You need to configure it accordingly by adding it as a resource directly or by adding `form` to the list of `additionalResourceSuffixes`.
  Using [ASEE Flow Run](/user-guide/aseeflow-bpm-run#starting-with-asee-flow-run), all additional resources - including Camunda Forms -
  placed inside the `configuration/resources/` directory are automatically deployed.
</Warning>

<img src="https://mintcdn.com/aseeflow/EOwJaxQ7KmXM1Gws/user-guide/task-forms/img/deploy-form.png?fit=max&auto=format&n=EOwJaxQ7KmXM1Gws&q=85&s=f191ce9c406997d56a50acd847643419" alt="Deploy your Camunda Form file" width="1800" height="873" data-path="user-guide/task-forms/img/deploy-form.png" />

You can also include Camunda Forms from other deployments by using [form references](#form-reference).

## External Task Forms

<Info>
  **Using Task Forms outside of ASEE Flow Tasklist**

  When embedding the process engine into a custom application, you can use any value in the form key property as a reference to your custom form. This way, your front-end can ensure to render the correct form for each user task.
</Info>

If you want to call a task form that is not part of your application, you can add a reference to the desired form. The referenced task form will be configured in a way similar to the embedded task form. Open the properties view and enter `FORM_NAME.html` as form key. The relevant XML tag looks like this:

```xml theme={null}
<userTask id="theTask" camunda:formKey="app:FORM_NAME.html"
          camunda:candidateUsers="John, Mary"
          name="my Task">
```

Tasklist creates the URL by the pattern:

```xml theme={null}
"../.." + contextPath (of process application) + "/" + "app" + formKey (from BPMN 2.0 XML) + "processDefinitionKey=" + processDefinitionKey + "&callbackUrl=" + callbackUrl;
```

When you have completed the task, the call back URL will be called.

<Info>
  **How To**

  [How to add JSF Forms to your process application](/user-guide/task-forms/jsf-task-forms)
</Info>

## Other Task Forms

These Task forms do not use the form-key attribute to be referenced. They are not recommended for production use and are intended for testing and development purposes.

### Generic Task Forms

The generic form will be used whenever you have not added a dedicated form for a [UserTask][user-tasks] or a [StartEvent][start-event].

<img src="https://mintcdn.com/aseeflow/EOwJaxQ7KmXM1Gws/user-guide/task-forms/img/tasklist-generic-form.png?fit=max&auto=format&n=EOwJaxQ7KmXM1Gws&q=85&s=21ef7a9a37a9846acdb112145154f6f4" alt="Generic Start Form" width="1340" height="457" data-path="user-guide/task-forms/img/tasklist-generic-form.png" />

Hit the *Add a variable* button to add a variable that will be passed to the process instance upon task completion. State a variable name, select the type and enter the desired value. Enter as many variables as you need.
After hitting the *Complete* button, the process instance contains the entered values. Generic task forms can be very helpful during the development stage, so you do not need to implement all task forms before you can run a workflow. For debugging and testing this concept has many benefits as well.

You can also retrieve already existing variables of the process instance by clicking the *Load Variables* button.

[user-tasks]: /reference/bpmn20/tasks/user-task

[start-event]: /reference/bpmn20/events/start-events

[jsf-task-forms]: /user-guide/task-forms/jsf-task-forms

### Generated Task Forms

<Info>
  **Camunda Forms or Generated Task Forms?**

  The feature set of Camunda Forms and Generated Task Forms are similar. For new projects, we recommend to use Camunda Forms, as they offer more flexibility and are easier to create.
</Info>

The ASEE Flow process engine supports generating HTML task forms based on Form Data Metadata provided in the BPMN 2.0 XML. Form Data Metadata is a set of BPMN 2.0 vendor extensions provided by ASEE Flow, allowing you to define form fields directly in the BPMN 2.0 XML:

```xml theme={null}
<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>
```

Form metadata can be graphically edited using the [Camunda Modeler](https://camunda.com/download/modeler/).

This form would look like this in Tasklist:

<img src="https://mintcdn.com/aseeflow/EOwJaxQ7KmXM1Gws/user-guide/task-forms/img/generated-forms-example.png?fit=max&auto=format&n=EOwJaxQ7KmXM1Gws&q=85&s=a4e2ee01de2c66e79675a633901e5bfc" alt="Generated Form" width="899" height="385" data-path="user-guide/task-forms/img/generated-forms-example.png" />

As you can see, the `<camunda:formData ... />` element is provided as a child element of the BPMN `<extensionElements>` element. Form metadata consists of multiple form fields which represent individual input fields where a user has to provide some value or selection.

A form data can have following attributes:

<table class="table table-bordered">
  <thead>
    <tr> <th>Attribute</th><th>Explanation</th> </tr>
  </thead>

  <tbody>
    <tr> <td>businessKey</td> <td>Id of a form field that will be marked as <code>cam-business-key</code></td> </tr>
  </tbody>
</table>

#### Form Fields

<Warning>
  **Process variables access**

  Defining form fields does not introduce any permissions on process variables.
  Users can still submit any variables via APIs for form completion like the
  [Submit Task Form](/reference/rest/task/submit-form) REST API.
  Form fields can be used on top of the task completion API to render forms and validate submitted values.
</Warning>

A form field can have the following attributes:

<table class="table table-bordered">
  <thead>
    <tr> <th>Attribute</th><th>Explanation</th> </tr>
  </thead>

  <tbody>
    <tr> <td>id</td><td>Unique id of the form field, corresponding to the name of the process variable to which the value of the form field is added when the form is submitted.</td> </tr>
    <tr> <td>label</td><td>The label to be displayed next to the form field.</td> </tr>
    <tr> <td>type</td> <td>The data type of the form field. The following types are supported out of the box: <ul> <code><li>string</li> <li>long</li> <li>date</li> <li>boolean</li> <li>enum</li></code> </ul> </td> </tr>
    <tr> <td>defaultValue</td><td>Value to be used as a default (pre-selection) for the field.</td> </tr>
  </tbody>
</table>

#### Form Field Validation

Validation can be used for specifying frontend and backend validation of form fields. ASEE Flow provides a set of built-in form field validators and an extension point for plugging in custom validators.

Validation can be configured for each form field in the BPMN 2.0 XML:

```xml theme={null}
<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>
```

As you can see, you can provide a list of validation constraints for each form field.

The following built-in validators are supported out of the box:

<table class="table table-bordered">
  <thead>
    <tr> <th>Validator</th><th>Explanation</th> </tr>
  </thead>

  <tbody>
    <tr> <td>required</td> <td> <p>Applicable to all types. Validates that a value is provided for the form field. Rejects 'null' values and empty strings.</p> <p> <code>\<camunda:constraint name="required" /></code> </p> </td> </tr>
    <tr> <td>minlength</td> <td> <p>Applicable to <code>string</code> fields. Validates the minimum length of text content. Accepts 'null' values.</p> <p> <code>\<camunda:constraint name="minlength" config="4" /></code> </p> </td> </tr>
    <tr> <td>maxlength</td> <td> <p>Applicable to <code>string</code> fields. Validates the maximum length of text content. Accepts 'null' values.</p> <p> <code>\<camunda:constraint name="maxlength" config="25" /></code> </p> </td> </tr>
    <tr> <td>min</td> <td> <p>Applicable to numeric fields. Validates the minimum value of a number. Accepts 'null' values.</p> <p> <code>\<camunda:constraint name="min" config="1000" /></code> </p> </td> </tr>
    <tr> <td>max</td> <td> <p>Applicable to numeric fields. Validates the maximum value of a number. Accepts 'null' values.</p> <p> <code>\<camunda:constraint name="max" config="10000" /></code> </p> </td> </tr>
    <tr> <td>readonly</td> <td> <p>Applicable to all types. Makes sure no input is submitted for the given form field.</p> <p> <code>\<camunda:constraint name="readonly" /></code> </p> </td> </tr>
  </tbody>
</table>

ASEE Flow supports custom validators. Custom validators are referenced using their fully qualified classname or an expression. Expressions can be used for resolving Spring or CDI @Named beans:

```xml theme={null}
<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>
```

<Info>
  The name attribute must be set to "validator" in order to use custom form field validator.
</Info>

A custom validator implements the `org.camunda.bpm.engine.impl.form.validator.FormFieldValidator` interface:

```java theme={null}
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();

  }

}
```

If the process definition is deployed as part of a ProcessApplication deployment, the validator instance is resolved using the process application classloader and / or the process application Spring Application Context / CDI Bean Manager, in case of an expression.