JBoss.orgCommunity Documentation

Chapter 13. Form Modeler

13.1. Configure process and human tasks
13.2. Generate forms from task definitions
13.3. Edit forms
13.3.1. Form generated description
13.3.2. Customizing form
13.3.3. Field types

This chapter intends to describe in a simple ways all the steps required to create a process with human tasks, generate and modify the forms for these tasks and execute them. It will provide initial guidance to perform all initial steps, but it will not provide a full description of all available features.

Given that forms are going to be used in tasks, it's possible to generate forms automatically from process variables and task definitions. These forms can be later be modified by using the form editor. In runtime, forms will receive data from process variables, display it to the user and capture his input, and then finally updating process variables again with the new values.

The following example will show all the steps to follow to create a form for the 'Create order' task in the process below.

Process example

Figure 13.1. Process example


This form must look like the following in execution:

Process example

Figure 13.2. Process example


To hold values capture by forms, process variables can be created. These variables can be of a simple type like 'String' or a complex type. These complex types can be defined by using the Data Modeler tool, or be just regular POJOs (Plain Java Objects) created with any Java IDE.

In this example, we define a variable 'po' of type 'org.jbpm.examples.purchases.PurchaseOrder', defined with the Data Modeler tool.


This variable is declared in the 'variables definition' property for the process.

After that, we must configure which variables are set as input parameters to the task, which ones will receive the response back from the form and establish the mappings. This is done by setting the 'DataInputSet', 'DataOutputSet' and 'Assignments' properties for any human task. See screenshots below for details.




The Process Designer module provides some functionality to generate the forms automatically from task and variable definitions, as well as easily open the right form from the modeler.

This is done with the following menu option.


You can also click on the icon on top of task to open the form directly.


Forms are related to tasks by following a naming convention. If a form with a name formName-taskform is defined in the same package as the process, then this form is used by the human task engine to display and capture information from user.

Also, if a form named ProcessId-task form is created, it will be used as the initial form when starting this process.

For example, for our process the following forms would be generated.


Once the forms have been generated, you can start editing them. There are several artifacts that are generated in the previous process, but also can be created manually.

We can change the way the form is displayed to the user in the task list. Next, we will show different levels of customization that will allow change it

Each field can be configured to enhance performance in the form. There are a group of common properties, that we call ‘Generic field properties’ and a group of specific properties that depends on the field type.

Let's explain the specific properties of each field type:

  • Short Text (java.lang.String)

  • Long Text (java.lang.String)

    • Compatible field type: Long text, E-mail, Rich text

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Height: The number or rows to show at text area.

      • Formula. to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section .

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section

      • Pattern. Allow introduce an expression to specify the validation of the field. In case that the field value introduced hasn’t match the expression, and error is thrown and the error message has to be shown.

      • Default Value formula. Expression to set the field default value.

  • Float (java.lang.Float)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section .

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section

      • Pattern. Allow introduce an expression to specify how the Float value has to be displayed. The pattern allowed is show in section pattern in http://docs.oracle.com/javase/6/docs/api/java/text/DecimalFormat.html

      • Default Value formula. Expression to set the field default value.

  • Decimal (java.lang.Double)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. Used to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section.

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section .

      • Pattern. Allow introduce an expression to specify how the Double value has to be displayed. The pattern allowed is show in section pattern in http://docs.oracle.com/javase/6/docs/api/java/text/DecimalFormat.html

      • Default Value formula. Expression to set the field default value.

  • BigDecimal (java.math.BigDecimal)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. Used to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section.

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section .

      • Pattern. Allow introduce an expression to specify how the BigDecimal value has to be displayed. The pattern allowed is show in section pattern in http://docs.oracle.com/javase/6/docs/api/java/text/DecimalFormat.html

      • Default Value formula. Expression to set the field default value.

  • Big integer (java.math.BigInteger)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. Used to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section.

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section .

      • Default Value formula. Expression to set the field default value.

  • Short (java.lang.Short)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. Used to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section.

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section .

      • Default Value formula. Expression to set the field default value.

  • Integer (java.lang.Integer)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. Used to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section.

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section .

      • Default Value formula. Expression to set the field default value.

  • Long Integer (java.lang.Long)

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. Used to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section.

      • Range value. A range formula allows you to let you specify the values that the user can select from an specific field. These expressions are described in Formula & expression section .

      • Default Value formula. Expression to set the field default value.

  • E-mail (java.lang.String)

    • Compatible field type: Short text, Long text, Rich text

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Default Value formula. Expression to set the field default value.

  • Checkbox (java.lang.Boolean)

    • Specific properties

      • Required: Indicates if it’s mandatory to fill this field.

      • Default Value formula. Expression to set the field default value.

  • Rich text: (java.lang.String)

    • Compatible field type: Short text, Long text, E-mail

    • Specific properties

      • Size: input text length.

      • MaxLength: Maximum number of characters allowed.

      • Required: Indicates if it’s mandatory to fill this field.

      • Height: The number or rows to show at text area.

      • Default Value formula. Expression to set the field default value.

  • Timestamp (java.util.Date)

    • Compatible field type: Short date

    • Specific properties

      • Size: input text length.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section .

      • Default Value formula. Expression to set the field default value.

  • Short date (java.util.Date)

    • Compatible field type: Timestamp

    • Specific properties

      • Size: input text length.

      • Required: Indicates if it’s mandatory to fill this field.

      • Formula. to enter expressions that will be evaluated to set the field value. These expressions are described in Formula & expression section .

      • Default Value formula. Expression to set the field default value.

  • Simple subform (Object)

    • For more details see sectionSimple Object (Subform field Type).

      Specific properties

      • Default form. Show the list of available forms to select what one will be displayed to show the object.

  • Multiple subform (Multiple Object)

    • For more details see sectionArrays of objects.( Multiple subform field Type).

      Specific properties

      • Default form. Show the list of available forms to select what one will be displayed to show the object when no other form is configured with an specific purpose.

      • Preview form. If a form is specified, it will be used to show the item details

      • Table form. If a form is specified, it will be used to show the table columns when the item list is showed

      • New item text. Text to show at New Item button

      • Add item text. Text to show at Add Item button

      • Cancel text. Text to show at Cancel button

      • Allow remove Items. If this check is selected, the form allow remove items in table view.

      • Allow edit items. If this check is selected, the form allow edit items in table view.

      • Allow preview items. If this check is selected, the form allow preview items in table view.

      • Hide creation button. Check to not show the creation button

      • Expanded. If is checked, when a new item is being added, the field display the table with the existing items and the creation form at same time

      • Allow data enter in table mode. Allow modify data in table view directly.

There are two types of complex fields: fields representing an object, and fields representing an object array.

Once the field is added to the form, either automatically or manually, it must be configured so that the form had to know how to display the objects that will contain in execution time.

Next we describe how can be the configuration process:

Once the form to represent the object, the parent form has to be configured to use them in the parent Subform or Multiple subform.

Below we will describe how the setup would be:

Form Modeler provides a Formula Engine that you can use to automatically calculate field values. That Formula engine supports Java and XPATH expressions to access the form fields values. Let’s see some examples.

There are three types of field types that you can use to model your form:

Is possible to extend the platform to add Custom Field Types that make a specific field (of any type) on the form to look and behave totally different than the standard platform fields. On this section we will take a look on how to create them and how to configure them.

Basically a Custom Field Type is a Java class that implements the org.jbpm.formModeler.core.fieldTypes.CustomFieldType interface and is packaged inside inside a jar file that is placed on the Application Server classpath or inside the application War.

Lets take a look atorg.jbpm.formModeler.core.fieldTypes.CustomFieldType:

</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">package</span><span class="java_plain">&nbsp;org</span><span class="java_separator">.</span><span class="java_plain">jbpm</span><span class="java_separator">.</span><span class="java_plain">formModeler</span><span class="java_separator">.</span><span class="java_plain">core</span><span class="java_separator">.</span><span class="java_plain">fieldTypes</span><span class="java_separator">;</span>
</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">import</span><span class="java_plain">&nbsp;java</span><span class="java_separator">.</span><span class="java_plain">util</span><span class="java_separator">.</span><span class="java_type">Locale</span><span class="java_separator">;</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">import</span><span class="java_plain">&nbsp;java</span><span class="java_separator">.</span><span class="java_plain">util</span><span class="java_separator">.</span><span class="java_type">Map</span><span class="java_separator">;</span>
</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_javadoc_comment">/**</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;Definition&nbsp;interface&nbsp;for&nbsp;custom&nbsp;fields</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">public</span><span class="java_plain">&nbsp;</span><span class="java_keyword">interface</span><span class="java_plain">&nbsp;</span><span class="java_type">CustomFieldType</span><span class="java_plain">&nbsp;</span><span class="java_separator">{</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_javadoc_comment">/**</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;This&nbsp;method&nbsp;returns&nbsp;a&nbsp;text&nbsp;definition&nbsp;for&nbsp;the&nbsp;custom&nbsp;type.&nbsp;This&nbsp;text&nbsp;will&nbsp;be&nbsp;shown&nbsp;on&nbsp;the&nbsp;UI&nbsp;to&nbsp;identify&nbsp;the&nbsp;CustomFieldType</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;locale&nbsp;The&nbsp;current&nbsp;user&nbsp;locale</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;A&nbsp;String&nbsp;that&nbsp;describes&nbsp;the&nbsp;field&nbsp;type&nbsp;on&nbsp;the&nbsp;specified&nbsp;locale.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">public</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;getDescription</span><span class="java_separator">(</span><span class="java_type">Locale</span><span class="java_plain">&nbsp;locale</span><span class="java_separator">);</span>
</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_javadoc_comment">/**</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;This&nbsp;method&nbsp;returns&nbsp;a&nbsp;string&nbsp;that&nbsp;contains&nbsp;the&nbsp;HTML&nbsp;code&nbsp;that&nbsp;will&nbsp;be&nbsp;used&nbsp;to&nbsp;show&nbsp;the&nbsp;field&nbsp;value.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;shown&nbsp;on&nbsp;screen</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;value&nbsp;The&nbsp;current&nbsp;field&nbsp;value</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;fieldName&nbsp;The&nbsp;field&nbsp;name</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;namespace&nbsp;The&nbsp;unique&nbsp;id&nbsp;for&nbsp;the&nbsp;rendered&nbsp;form,&nbsp;it&nbsp;should&nbsp;be&nbsp;used&nbsp;to&nbsp;generate&nbsp;identifiers&nbsp;inside&nbsp;the&nbsp;html&nbsp;code.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;required&nbsp;Determines&nbsp;if&nbsp;the&nbsp;field&nbsp;is&nbsp;required&nbsp;or&nbsp;not</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;readonly&nbsp;Determines&nbsp;if&nbsp;the&nbsp;field&nbsp;must&nbsp;be&nbsp;shown&nbsp;on&nbsp;read&nbsp;only&nbsp;mode</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;params&nbsp;A&nbsp;list&nbsp;of&nbsp;configuration&nbsp;params&nbsp;that&nbsp;can&nbsp;be&nbsp;set&nbsp;on&nbsp;the&nbsp;field&nbsp;configuration&nbsp;screen</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;The&nbsp;HTML&nbsp;that&nbsp;will&nbsp;be&nbsp;used&nbsp;to&nbsp;show&nbsp;the&nbsp;field&nbsp;value</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">public</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;getShowHTML</span><span class="java_separator">(</span><span class="java_type">Object</span><span class="java_plain">&nbsp;value</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;fieldName</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;namespace</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">boolean</span><span class="java_plain">&nbsp;required</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">boolean</span><span class="java_plain">&nbsp;readonly</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_separator">...</span><span class="java_plain">&nbsp;params</span><span class="java_separator">);</span>
</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_javadoc_comment">/**</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;This&nbsp;method&nbsp;returns&nbsp;a&nbsp;String&nbsp;that&nbsp;contains&nbsp;the&nbsp;HTML&nbsp;code&nbsp;that&nbsp;will&nbsp;show&nbsp;the&nbsp;input&nbsp;view&nbsp;of&nbsp;the&nbsp;field.&nbsp;That&nbsp;will&nbsp;be&nbsp;used&nbsp;to&nbsp;set&nbsp;the&nbsp;field&nbsp;value.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;value&nbsp;The&nbsp;current&nbsp;field&nbsp;value</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;fieldName&nbsp;The&nbsp;field&nbsp;name</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;namespace&nbsp;The&nbsp;unique&nbsp;id&nbsp;for&nbsp;the&nbsp;rendered&nbsp;form,&nbsp;it&nbsp;should&nbsp;be&nbsp;used&nbsp;to&nbsp;generate&nbsp;identifiers&nbsp;inside&nbsp;the&nbsp;html&nbsp;code.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;required&nbsp;Determines&nbsp;if&nbsp;the&nbsp;field&nbsp;is&nbsp;required&nbsp;or&nbsp;not</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;readonly&nbsp;Determines&nbsp;if&nbsp;the&nbsp;field&nbsp;must&nbsp;be&nbsp;shown&nbsp;on&nbsp;read&nbsp;only&nbsp;mode</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;params&nbsp;A&nbsp;list&nbsp;of&nbsp;configuration&nbsp;params&nbsp;that&nbsp;can&nbsp;be&nbsp;set&nbsp;on&nbsp;the&nbsp;field&nbsp;configuration&nbsp;screen</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;The&nbsp;HTML&nbsp;code&nbsp;that&nbsp;will&nbsp;be&nbsp;used&nbsp;to&nbsp;show&nbsp;the&nbsp;input&nbsp;view&nbsp;of&nbsp;the&nbsp;field.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">public</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;getInputHTML</span><span class="java_separator">(</span><span class="java_type">Object</span><span class="java_plain">&nbsp;value</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;fieldName</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;namespace</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">boolean</span><span class="java_plain">&nbsp;required</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">boolean</span><span class="java_plain">&nbsp;readonly</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_separator">...</span><span class="java_plain">&nbsp;params</span><span class="java_separator">);</span>
</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_javadoc_comment">/**</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;This&nbsp;method&nbsp;is&nbsp;used&nbsp;to&nbsp;obtain&nbsp;the&nbsp;field&nbsp;value&nbsp;from&nbsp;the&nbsp;submitted&nbsp;values.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;requestParameters&nbsp;A&nbsp;Map&nbsp;containing&nbsp;the&nbsp;request&nbsp;parameters&nbsp;for&nbsp;the&nbsp;submitted&nbsp;form</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;requestFiles&nbsp;A&nbsp;Map&nbsp;containing&nbsp;the&nbsp;java.io.Files&nbsp;uploaded&nbsp;on&nbsp;the&nbsp;request</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;fieldName&nbsp;The&nbsp;field&nbsp;name</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;namespace&nbsp;The&nbsp;unique&nbsp;id&nbsp;for&nbsp;the&nbsp;rendered&nbsp;form,&nbsp;it&nbsp;should&nbsp;be&nbsp;used&nbsp;to&nbsp;generate&nbsp;identifiers&nbsp;inside&nbsp;the&nbsp;html&nbsp;code.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;previousValue&nbsp;The&nbsp;previous&nbsp;value&nbsp;of&nbsp;the&nbsp;current&nbsp;field</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;required&nbsp;Determines&nbsp;if&nbsp;the&nbsp;field&nbsp;is&nbsp;required&nbsp;or&nbsp;not</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;readonly&nbsp;Determines&nbsp;if&nbsp;the&nbsp;field&nbsp;must&nbsp;be&nbsp;shown&nbsp;on&nbsp;read&nbsp;only&nbsp;mode</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;params&nbsp;A&nbsp;list&nbsp;of&nbsp;configuration&nbsp;params&nbsp;that&nbsp;can&nbsp;be&nbsp;set&nbsp;on&nbsp;the&nbsp;field&nbsp;configuration&nbsp;screen</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;The&nbsp;value&nbsp;of&nbsp;the&nbsp;field&nbsp;based&nbsp;on&nbsp;the&nbsp;submitted&nbsp;form&nbsp;values.</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_keyword">public</span><span class="java_plain">&nbsp;</span><span class="java_type">Object</span><span class="java_plain">&nbsp;getValue</span><span class="java_separator">(</span><span class="java_type">Map</span><span class="java_plain">&nbsp;requestParameters</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">Map</span><span class="java_plain">&nbsp;requestFiles</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;fieldName</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_plain">&nbsp;namespace</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">Object</span><span class="java_plain">&nbsp;previousValue</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">boolean</span><span class="java_plain">&nbsp;required</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">boolean</span><span class="java_plain">&nbsp;readonly</span><span class="java_separator">,</span><span class="java_plain">&nbsp;</span><span class="java_type">String</span><span class="java_separator">...</span><span class="java_plain">&nbsp;params</span><span class="java_separator">);</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_separator">}</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;</span>

As you can see this Interface defines the methods that determines how the field has to be shown on the screen for when the form is shown on insert(getInputHTML(...)) or readonly (getShowHTML(...)) mode. It also provides the method (getValue(...)) that reads the needed parameters from the request and to obtain the correct field value. Te returned value type must match with the type of the field added on the form. So (for example) you can create a File input that uploads a file to a server folder and saves a String with the storage path as the field value, so on your forms you can turn all the text compatible fields (Short Text, Long Text, Rich Text and Email) on Input File.

To see ho can it be done look at the example on https://github.com/droolsjbpm/jbpm-form-modeler/tree/master/jbpm-form-modeler-sample-custom-types/jbpm-form-modeler-custom-file-type.

Please note that this is just a sample and it only should be used with learning purposes.

Now let's see how to use and configure and use a Custom Field type. Following the example on the previous chapter, we have created a File Input type and we have it already installed on our application. So now we are going to create a new form and add a Short Text property and turn it into a File Input and edit the field properties changing the Field Type from Short text toCustom field.


After changing the field type a new set of properties will appear:



So opening the Custom field select box we'll be able to select the File Input from the available custom types:


After selecting the File Input type on the list and saving the field properties the form will look like:


If we build a simple process and configure a Short text to be shown as the sampleFile Input, if we build the project on runtime the field will behave uploading the choosen files to the server and allowing the user to download it like this:



If we take a look at what's the process variable value, we'll see that is storing a String with the file path stored in server.