JBoss.orgCommunity Documentation

jBPM Form modeller - Getting Started guide

Version 6.1.0-SNAPSHOT


This guide 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.


This form must look like the following in execution:


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 section Simple 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 section Arrays 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 at org.jbpm.formModeler.core.fieldTypes.CustomFieldType:

</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&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;&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;&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;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;locale&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;current&nbsp;user&nbsp;locale</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;value&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;current&nbsp;field&nbsp;value</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;fieldName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;field&nbsp;name</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;namespace&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;required&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;readonly&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;params&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;value&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;current&nbsp;field&nbsp;value</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;fieldName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;field&nbsp;name</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;namespace&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;required&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;readonly&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;params&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;requestParameters&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;requestFiles&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;fieldName&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;The&nbsp;field&nbsp;name</span>
<!--  --><br/><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;namespace&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;previousValue&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;required&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;readonly&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@param</span><span class="java_javadoc_comment">&nbsp;params&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*&nbsp;</span><span class="java_javadoc_tag">@return</span><span class="java_javadoc_comment">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*/</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&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;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><span class="java_separator">}</span>
<!--  --><br/><span class="java_plain">&nbsp;&nbsp;&nbsp;&nbsp;&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 to Custom 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 sample File 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.


By default, a data model is always constrained to the context of a project. For the purpose of this tutorial, we will assume that a correctly configured project already exists.

To start the creation of a data model inside a project, take the following steps:

This will start up the Data Modeller tool, which has the following general aspect:


The Data Modeller panel is divided into the following sections:

A data model consists of data entities which are a logical representation of some real-world data. Such data entities have a fixed set of modeller (or application-owned) properties, such as its internal identifier, a label, description, package etc. Besides those, an entity also has a variable set of user-defined fields, which are an abstraction of a real-world property of the type of data that this logical entity represents.

Creating a data entity can be achieved either by clicking the "Create" button in the model browser section (see fig. "The data model browser" above), or by clicking the one in the top data modeller menu:


This will pop up the new object screen:


Some initial information needs to be provided before creating the new object:

  • The object's internal identifier (mandatory). The value of this field must be unique per package, i.e. if the object's proposed identifier already exists in the selected package, an error message will be displayed.

  • A label (optional): this field allows the user to define a user-friendly label for the data entity about to be created. This is purely conceptual info that has no further influence on how objects of this entity will be treated. If a label is defined, then this is how the entity will be displayed throughout the data modeller tool.

  • A package (mandatory): a data entity must always be created within a package (or name space, in which this entity will be unique at a platform level). By default, the option for selecting an already existing package will be activated, in which case the corresponding drop-down shows all the packages that are currently defined. If a new package needs to be defined for this entity, then the "New package" option should be selected. In this case the new to be created package should be input into the corresponding text-field. The format for defining new packages is the same as the one for standard Java packages.

  • A superclass (optional): this will indicate that this entity extends from another already existing one. Since the data modeller entities are translated into standard Java classes, indicating a superclass implies normal Java object extension at the generated-code level.

Once the user has provided at least the mandatory information, by pushing the "Ok" button at the bottom of the screen the new data entity will be created. It will be added to the model browser's entity listing.

It will also appear automatically selected, to make it easy for the user to complete the definition of the newly created entity, by completing the entity's properties in the Data Object Properties browser, or by adding new fields.


Note

As can be seen in the above figure, after performing changes to the data model, the model name will appear with an '*' to alert the user of the existence of un-persisted changes to the model.

In the Data Modeller's object browsing section, an entity can be deleted by clicking upon the 'x' icon to the right of each entity. If an entity is being referenced from within another entity (as a field type), then the modeller tool will not allow it to be deleted, and an error message will appear on the screen.

Once the data entity has been created, it now has to be completed by adding user-defined properties to its definition. This can be achieved by providing the required information in the "Create new field" section (see fig. "New field creation"), and clicking on the "Create" button when finished. The following fields can (or must) be filled out:

When finished introducing the initial information for a new field, clicking the 'Create' button will add the newly created field to the end of the entity's fields table below:


The new field will also automatically be selected in the entity's field list, and its properties will be shown in the Field tab of the Property editor. The latter facilitates completion of some additional properties of the new field by the user (see below).

At any time, any field (without restrictions) can be deleted from an entity definition by clicking on the corresponding 'x' icon in the entity's fields table.

As stated before, both entities as well as entity fields require some of their initial properties to be set upon creation. These are by no means the only properties entities and fields have. Below we will give a detailed description of the additional entity and field properties.

The data model in itself is merely a visual tool that allows the user to define high-level data structures, for them to interact with the Drools Engine on the one hand, and the jBPM platform on the other. In order for this to become possible, these high-level visual structures have to be transformed into low-level artifacts that can effectively be consumed by these platforms. These artifacts are Java POJOs (Plain Old Java Objects), and they are generated every time the data model is saved, by pressing the "Save" button in the top Data Modeller Menu.


At this time each entity that has been defined in the model will be translated into a Java class, according to the following transformation rules:

  • The entity's identifier property will become the Java class's name. It therefore needs to be a valid Java identifier.

  • The entity's package property becomes the Java class's package declaration.

  • The entity's superclass property (if present) becomes the Java class's extension declaration.

  • The entity's label and description properties will translate into the Java annotations "@org.kie.workbench.common.services.datamodeller.annotations.Label" and "@org.kie.workbench.common.services.datamodeller.annotations.Description", respectively. These annotations are merely a way of preserving the associated information, and as yet are not processed any further.

  • The entity's role property (if present) will be translated into the "@org.kie.api.definition.type.Role" Java annotation, that IS interpreted by the application platform, in the sense that it marks this Java class as a Drools Event Fact-Type.

A standard Java default (or no parameter) constructor is generated, as well as a full parameter constructor, i.e. a constructor that accepts as parameters a value for each of the entity's user-defined fields.

The entity's user-defined fields are translated into Java class fields, each one of them with its own getter and setter method, according to the following transformation rules:

  • The entity field's identifier will become the Java field identifier. It therefore needs to be a valid Java identifier.

  • The entity field's type is directly translated into the Java class's field type. In case the entity field was declared to be multiple (i.e. '[0..N]'), then the generated field is of the "java.util.List" type.

  • The equals property: when it is set for a specific field, then this class property will be annotated with the "@org.kie.api.definition.type.Key" annotation, which is interpreted by the Drools Engine, and it will 'participate' in the generated equals() method, which overwrites the equals() method of the Object class. The latter implies that if the field is a 'primitive' type, the equals method will simply compares its value with the value of the corresponding field in another instance of the class. If the field is a sub-entity or a collection type, then the equals method will make a method-call to the equals method of the corresponding entity's Java class, or of the java.util.List standard Java class, respectively.

    If the equals property is checked for ANY of the entity's user defined fields, then this also implies that in addition to the default generated constructors another constructor is generated, accepting as parameters all of the fields that were marked with Equals. Furthermore, generation of the equals() method also implies that also the Object class's hashCode() method is overwritten, in such a manner that it will call the hashCode() methods of the corresponding Java class types (be it 'primitive' or user-defined types) for all the fields that were marked with Equals in the Data Model.

  • The position property: this field property is automatically set for all user-defined fields, starting from 0, and incrementing by 1 for each subsequent new field. However the user can freely changes the position among the fields. At code generation time this property is translated into the "@org.kie.api.definition.type.Position" annotation, which can be interpreted by the Drools Engine. Also, the established property order determines the order of the constructor parameters in the generated Java class.

  • The entity's role property (if present) will be translated into the "@org.kie.api.definition.type.Role" Java annotation, that IS interpreted by the application platform, in the sense that it marks this Java class as a Drools Event Fact-Type.

As an example, the generated Java class code for the Purchase Order entity, corresponding to its definition as shown in the following figure purchase_example.jpg is visualized in the figure at the bottom of this chapter. Note that the two of the entity's fields, namely 'header' and 'lines' were marked with Equals, and have been assigned with the positions 2 and 1, respectively).




package org.jbpm.examples.purchases;
/**
 * This class was automatically generated by the data modeler tool.
 */
@org.kie.api.definition.type.Role(value = 
  org.kie.api.definition.type.Role.Type.EVENT)
@org.kie.workbench.common.services.datamodeller.annotations.Label(value = 
  "Purchase Order")
@org.kie.workbench.common.services.datamodeller.annotations.Description(value = 
  "This entity models the client purchase orders.")
public class PurchaseOrder extends org.jbpm.examples.purchases.parent 
                           implements java.io.Serializable {
static final long serialVersionUID = 1L;
  @org.kie.workbench.common.services.datamodeller.annotations.Label(value = 
    "Description")
  @org.kie.api.definition.type.Position(value = 0)
  @org.kie.workbench.common.services.datamodeller.annotations.Description(value = 
    "A description for this purchase order.")
  private java.lang.String description;
  @org.kie.workbench.common.services.datamodeller.annotations.Label(value = 
    "Lines")
  @org.kie.api.definition.type.Position(value = 1)
  @org.kie.workbench.common.services.datamodeller.annotations.Description(value = 
    "The purchase order items (collection of Purchase Order Line sub-entities).")
  @org.kie.api.definition.type.Key
  private java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines;
  @org.kie.workbench.common.services.datamodeller.annotations.Label(value = 
    "Header")
  @org.kie.api.definition.type.Position(value = 2)
  @org.kie.workbench.common.services.datamodeller.annotations.Description(value = 
    "The purchase order header (Purchase Order Header sub-entity).")
  @org.kie.api.definition.type.Key
  private org.jbpm.examples.purchases.PurchaseOrderHeader header;
  public PurchaseOrder() {}
  public PurchaseOrder(
    java.lang.String description,
    java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines,
    org.jbpm.examples.purchases.PurchaseOrderHeader header )
  {
    this.description = description;
    this.lines = lines;
    this.header = header;
  }
  public PurchaseOrder(
    java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines,
    org.jbpm.examples.purchases.PurchaseOrderHeader header )
  {
    this.lines = lines;
    this.header = header;
  }
  public java.lang.String getDescription() {
    return this.description;
  }
  public void setDescription(  java.lang.String description ) {
    this.description = description;
  }
  public java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> 
    getLines() 
  {
    return this.lines;
  }
  public void setLines(
    java.util.List<org.jbpm.examples.purchases.PurchaseOrderLine> lines ) 
  {
    this.lines = lines;
  }
  public org.jbpm.examples.purchases.PurchaseOrderHeader getHeader() {
    return this.header;
  }
  public void setHeader(  org.jbpm.examples.purchases.PurchaseOrderHeader 
    header ) 
  {
    this.header = header;
  }
  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (== null || getClass() != o.getClass()) return false;
    org.jbpm.examples.purchases.PurchaseOrder that = 
      (org.jbpm.examples.purchases.PurchaseOrder)o;
    if (lines != null ? !lines.equals(that.lines) : that.lines != null) 
      return false;
    if (header != null ? !header.equals(that.header) : that.header != null) 
      return false;
    return true;
  }
  @Override
  public int hashCode() {
    int result = 17;
    result = 13 * result + (lines != null ? lines.hashCode() : 0);
    result = 13 * result + (header != null ? header.hashCode() : 0);
    return result;
  }
}

Using an external model means the ability to use a set for already defined POJOs in current project context. In order to make those POJOs available a dependency to the given JAR should be added. Once the dependency has been added the external POJOs can be referenced from current project data model.

There are two ways to add a dependency to an external JAR file: