Chapter 4. Process Designer

You can copy individual elements and finished business processes. To copy your selection into a different package:

To copy a business process into the same package:

To align diagram Elements, select the elements and click the respective button in the alignment toolbar:

Note that dockers of Connection elements are not influenced by aligning and you might need to remove them.

To change the element layering, select the required element or a group of elements and click the button in the Process Designer toolbar. Choose one of the following options:

Note that the connection elements are not influenced by the layering and remain always visible.

You can bend the connection elements and create angles in your business process. To do so, click and drag the connection element in the desired angle and direction. You can also straighten a bent connection in the same manner, that is clicking on the bent angle and dragging it back to make a straight line.

To resize Elements on the canvas, select the element, and click and pull the blue arrow displayed in the upper left or lower right corner of the element.

To make the size of multiple elements identical, select the Elements and then click the icon in the toolbar and then click on Alignment Same Size: all Elements will be resized to the size of the largest selected Element.

Note that only Activity Elements can be resized.

To create and manage an element group:

When you lock process model elements, the elements cannot be edited or moved.

Color schemes define the colors used for individual process elements in a diagram.

Color schemes are stored in the themes.json file, which is located in the global directory of each repository.

To apply a new color scheme or any other defined scheme, click the button in the Process Designer toolbar and select one of the available color schemes from the drop-down menu.

Local history keeps track of any changes, you apply to your process model so as to allow you to restore any previous status of the process model. By default, this feature is turned off.

To turn on local history recording, click the Local History button and select Enable Local History entry. From this menu, you can also display the local history records and apply the respective status to the process as well as disable the feature or clear the current local history log.

To change the size of the canvas, click the respective yellow arrow on the canvas edge.

Process validation can be set up to be continuous or to be only immediate.

To validate your process model continuously, click the Validate ( ) button in the toolbar of the Process Designer with the process and click Start Validating. If validation errors have been detected, the elements with errors are highlighted in orange. Click on the invalid element on the canvas to display a dialog with the summary of its validation errors. To disable continuous validation, click the Validate ( ) button in the toolbar of the Process Designer with the process and click Stop Validating.

Also note that errors on the element properties are visualized in further details in the Properties view of the respective element.

If you want to display the validation errors and not to keep the validation feature activated, click the Validate ( ) button in the toolbar of the Process Designer with the process and click View all issues.

Additionally after you save your process, any validation errors are also displayed in the Messages view.

Figure 4.5. Stopping continuous validation

If your process is invalid and the Process Designer is unable to render it in the designer canvas, you can open the process in XML format and make the necessary corrections.

All process elements have the following visualization properties, which can be defined in their Properties tab:

All process elements, including the process, contain a set of properties that define the following:

In element properties of the String type, use #{expression} to embed a value. The value will be retrieved on element instantiation, and the substitution expression will be replaced with the result of calling the toString() method on the variable defined in the expression.

Note that the expression can be the name of a variable, in which case it resolves to the value of the variable, but more advanced MVEL expressions are possible as well, for example #{person.name.firstname}.

To define element properties, do the following:

A process form is a form that is displayed at process instantiation to the user who instantiated the process.

To create a process form, do the following:

Note that the Form is created in the root of your current Project and is available from any other process definitions in the Projects.

A task form is a form that is displayed at User Task instantiation, that is, when the execution flow reaches the task, to the Actor of the User Task.

To create a task form, do the following:

Once you have created a form definition, you need to define its content: that is its fields and the data they are bound to. You can add either the pre-defined field types to your form, or define your own data origin and use the custom field types in your form definition.

To create a new form in Form Modeler, do the following:

The newly created form will open up. You can add various fields to it when you select the Add fields by type option on the Form Modeler tab. Use the button to place the field types onto the canvas, where you can modify them. To modify the field types, use the icons that display when you place the cursor over a field: First, Move field, Last, Group with previous, Edit, or Clear. The icons enable you to change the order of the fields in the form, group the fields, or clear and edit their content.

The following figure shows a new form created in Form Modeler.

Figure 4.8. New form

To open an existing form in a project that already has a form defined, go to Form Definitions in Project Explorer and select the form you want to work with from the displayed list.

Figure 4.9. Opening an Existing Form

To set the properties of a form field, do the following:

You can generate forms automatically from process variables and task definitions and later modify the forms using the form editor. In runtime, forms receive data from process variables, display it to the user, capture user input, and update the process variables with the new values. To configure a process in Form Modeler, do the following:

Example 4.1. Defining a Variable using Data Modeler

In the Process Designer module, you can generate forms automatically from task and variable definitions, and easily open concrete forms from Form Modeler by using the following menu option:

Figure 4.10. Generating Forms Automatically

To open and edit a form directly, click the Edit Task Form icon ( ) located above a user task.

Figure 4.11. Editing the Task Form

Forms follow a naming convention that relates them to tasks. If you define a form named TASK_NAME-taskform in the same package as the process, the human task engine will use the form to display and capture information entered by the user. If you create a form named PROCESS_ID-task, the application will use it as the initial form when starting the process.

After you generate a form, you can start editing it. If the form has been generated automatically, the Form data origin tab contains the process variables as the origin of the data, which enables you to bind form fields with them and create data bindings. Data bindings determine the way task input is mapped to form variables, and when the form is validated and submitted, the way values update output of the task. You can have as many data origins as required, and use different colors to differentiate them in the Render color drop down menu. If the form has been generated automatically, the application creates a data origin for each process variable. For each data origin bindable item, there is a field in the form, and these automatically generated fields also have defined bindings. When you display the fields in the editor, the color of the data origin is displayed over the field to give you quick information on correct binding and implied data origin.

To customize a form, you can for example move fields, add new fields, configure fields, or set values for object properties.

You can place fields in different areas of the form. To move a field, access the field’s contextual menu and select the Move field option shown on the following screenshot. This option displays the different regions of the form where you can place the field.

Figure 4.12. Moving a Form Field in Form Modeler

After you click the Move field option, a set of rectangular contextual icons appears. To move a field, select one of them according to the desired new position of the field.

Figure 4.13. Destination Areas to Move a Field

You can add fields to a form by their origin or by selecting the type of the form field. The Add fields by origin tab enables you to add fields to the form based on defined data origins.

Figure 4.14. Adding Fields by Origin

The fields then have correct configuration of the Input binding expression and Output binding expression properties, so when the form is submitted, the values in the fields are stored in the corresponding data origin. The Add fields by type tab enables you to add fields to the form from the fields type palette of the Form Modeler. The fields do not store their value for any data origin until they have correct configuration of the Input binding expression and Output binding expression properties.

Figure 4.15. Adding Fields by Type

There are three kinds of field types you can use to model your form: simple types, complex types, and decorators. The simple types are used to represent simple properties like texts, numeric values, or dates. The following table presents a complete list of supported simple field types:

Complex field types are designed for work with properties that are not basic types but Java objects. To use these field types, it is necessary to create extra forms in order to display and write values to the specified Java objects.

Decorators are a kind of field types that does not store data in the object displayed in the form. You can use them for decorative purposes.

Each field can be configured to enhance performance of the form. There is a group of common properties called generic field properties and a group of specific properties that differs by field type.

Generic field properties:

Complex Field types is a category of fields in a form. You can use the complex field types to model form properties that are Java Objects. Simple subform and Multiple subform are the two types of complex field types. A simple subform represents a single object and a multiple subform represents an object array inside a parent form. Once you add one of these fields into a form, you must configure the form with information on how it must display these objects during execution. For example, if your form has fields representing an object array, you can define a tabular display of these fields in the form. You cannot represent them as simple inputs such as text box, checkbox, text area, and date selector.

Red Hat JBoss BPM Suite supports document attachments in forms using the Document form field. With the Document form field, you can upload documents that are required as part of a form or process. For information about adding fields to forms, see Section 4.8.8, “Adding New Fields to a Form”.

To enable document attachments in forms and processes, follow these steps:

Now, when you build and deploy your project, you can see any configured Document attachments in the Documents tab of the Process Management Process Instances view.

Forms generated by the Form Builder can be reused in other client applications with the help of the REST API and a JavaScript library. The REST API defines the end points for the external client applications to call and the JavaScript library makes it easy to interact with these endpoints and to render these forms.

To use this API you will need to integrate the Forms REST JavaScript library in your client application. The details of the library and the methods that it provides are given in the following section, along with a simple example. Details of the REST API are present in the Red Hat JBoss BPM Suite Developers Guide, although you should probably only use the REST API via the JavaScript library described here.

Global variables (also known as globals) exist in a knowledge session and can be accessed and are shared by all assets in that session. Global variables belong to the particular session of the Knowledge Base and they are used to pass information to the engine.

Every global variable defines its ID and item subject reference. The ID serves as the variable name and must be unique within the process definition. The item subject reference defines the data type the variable stores.

A local variable is a variable that exists in a child element context of a process and can be accessed only from within this context: local variables belong to the particular element of a process.

For tasks, with the exception of the Script Task, the user can define Data Input Assignments and Data Output Assignments in the Assignments property. Data Input Assignment defines variables that enter the Task and therefore provide the entry data needed for the task execution. The Data Output Assignments can refer to the context of the Task after execution to acquire output data.

User Tasks present data related to the actor that is executing the User Task. Additionally, User Tasks also request the actor to provide result data related to the execution.

To request and provide the data, use task forms and map the data in the Data Input Assignment parameter to a variable. Map the data provided by the user in the Data Output Assignment parameter if you want to preserve the data as output. For further information, see Section 4.12, “Assignment”.

Process variables and rule facts do not share the same context. If a rule has to manipulate a process variable, you must explicitly map process variable to rule fact. You can access and set process variables from a business rule task using the folowing approaches:

//Instantiate the object and set the flag to false
demo1.hello1.ValidationError validationError1 = new demo1.hello1.ValidationError();
validationError1.setIsValid(false);

//Assign the object to the process variable
kcontext.setVariable("validationError",validationError1);

rule "HelloAll"
dialect "mvel"
ruleflow-group "validate"
no-loop
when
    _myvar: ValidationError()
then
    _myvar.setIsValid( true );
    update( _myvar );
    System.out.println("The value returned is: " + _myvar.getIsValid());
end

import org.kie.api.runtime.process.WorkflowProcessInstance;

    rule "sampleRule"
        no-loop true
        ruleflow-group "dynamic-group"
        when
            $process : WorkflowProcessInstance( )
        then
	    WorkflowProcessInstance $p = (WorkflowProcessInstance)kcontext.getKieRuntime().getProcessInstance($process.getId()); //casting to WorkflowProcessInstance is essential
	    $p.setVariable( "dynamicGroupId","analyst" );
	    retract($process);

kcontext.getKieRuntime().insert(kcontext.getProcessInstance());

The Data I/O Editor is the dialog window used to define Activity DataInputs and DataOutputs, as well as the mappings between them and process variables.

Like process variables, DataInputs and DataOutputs have a name and data-type, such as Integer, String, or a subclass of Java Object, such as a user-defined Data Object created within JBoss BPM Suite. The data-types of DataInputs and DataOutputs should match the data-types of the process variables which they are mapped to or from. Their names may be the same as the corresponding process variables, but this is not a requirement.

Process Variables are defined in the Variable Definitions property of the business process. Element DataInputs and DataOutputs are defined in one of three properties of Activities, depending on the element type:

The Assignments, DataOutputAssociations, and DataInputAssociations properties are all edited in the Data I/O Editor. DataInputs can have values assigned to them either by mapping from process variables or by assigning constant values to them. DataOutputs are mapped to process variables.

To define the DataInputs, DataOutputs and Assignments for an Element, select the Element in the Business process and click the button to open the Data I/O Editor. Data Input Assignments and Data Output Assignments can be added by clicking the Add button.

You can also open the Data I/O Editor to edit the Data Inputs and/or Outputs by editing the appropriate property for the activity: Assignments, DataOutputAssociations, or DataInputAssociations.

In the following example, the Data I/O Editor has been used to create some Data Inputs and Data Outputs for the user activity Check Invoice. The example makes use of two process variables that have been defined in the process:

The following Data Inputs have been added:

The Data Inputs and Data Outputs are linked to the corresponding process variables by setting the Source and Target fields in the dialog window.

The Data I/O Editor enables you to create and assign a constant to a Data Input when setting the Source column for a Data Input. This is demonstrated by the maxamount Data Input, that has the constant 1000.00, which will be assigned to it at runtime.

The myvar Data Input and Data Output demonstrates a custom Data Typecom.test.MyType, which is entered in the dialog window by the user.

You can define a work item definition in:

A work item has the following properties:

Defines the default handler implementation, for example a Java class that implements the WorkItemHandler interface and can be used to execute the service. The class can be automatically registered as a handler when importing the service from a repository.

It is also possible to use MVEL to resolve the expression. MVEL provides the additional benefit of resolving handler’s parameters. For example:

"defaultHandler" : "mvel: new org.jbpm.process.workitem.twitter.TwitterHandler(ksession)"

Available parameters are for example: ksession, taskService, runtimeManager, classLoader, and entityManagerFactory.

The dependencies for the defaultHandler class. It is usually the handler’s implementation JAR, but the list can contain additional external dependencies as well.

Make sure you provide correct path to the files: use relative path to the directory where the work item configuration file is located.

If the dependencies are located in a Maven repository, you can define them in the mavenDependencies property:

"mavenDependencies" : [
  "org.jbpm:jbpm-twitter:1.0",
  "org.twitter4j:twitter4j-core:2.2.2" ]

JBoss Developer Studio Process Designer

To create a custom work item definition (WID) in JBoss Developer Studio Process Designer, follow these steps:

Web Process Designer

To create a custom work item definition (WID) in the Web Process Designer, follow these steps:

To upload a custom icon for your work item definition, follow these steps:

You can now refer to your icon in your WID. Your WID is in the Process Designer, in the Service Tasks section by default.

A work item handler is a Java class used to execute or abort (during asynchronous execution) work items. The class defines the business logic of the work item, for example how to contact another system and request information, which is then parsed into the custom task parameters. Every work item handler must implement org.kie.api.runtime.process.WorkItemHandler, which is a part of the KIE API.

For more information about work item handlers, see Appendix B. Service Tasks from Red Hat JBoss BPM Suite User Guide.

Red Hat JBoss BPM Suite comes with multiple work item handlers in the following modules:

The work item handlers must define the executeWorkItem() and abortWorkItem() methods as defined by the WorkItemHandler interface. These are called during runtime on work item execution.

When a work item is executed, the following is performed:

To abort the work item, use the WorkItemHandler.abortWorkItem() before it is completed. For more information about asynchronous execution, see Red Hat JBoss BPM Suite Development Guide.

To register a work item handler in Business Central, follow these steps:

To register your Work Item Handler in the kie-deployment-descriptor.xml file:

Alternatively, if you use RuntimeManager directly, see the following example:

import java.util.Map;

import org.kie.api.KieServices;
import org.kie.api.io.ResourceType;
import org.kie.api.runtime.process.WorkItemHandler;
import org.kie.api.runtime.manager.RuntimeEngine;
import org.kie.api.runtime.manager.RuntimeEnvironment;
import org.kie.api.runtime.manager.RuntimeEnvironmentBuilder;
import org.kie.api.runtime.manager.RuntimeManagerFactory;
import org.jbpm.executor.impl.wih.AsyncWorkItemHandler;
import org.jbpm.runtime.manager.impl.DefaultRegisterableItemsFactory;

...

RuntimeEnvironment environment = RuntimeEnvironmentBuilder.Factory.get().newDefaultBuilder()
  .userGroupCallback(userGroupCallback)
  .addAsset(ResourceFactory.newClassPathResource("BPMN2-ScriptTask.bpmn2"), ResourceType.BPMN2)
  .registerableItemsFactory(new DefaultRegisterableItemsFactory() {

    @Override
    public Map<String, WorkItemHandler> getWorkItemHandlers(RuntimeEngine runtime) {
      Map<String, WorkItemHandler> handlers = super.getWorkItemHandlers(runtime);
      handlers.put("async", new AsyncWorkItemHandler(executorService, "org.jbpm.executor.commands.PrintOutCommand"));
      return handlers;
    }
  })
  .get();

manager = RuntimeManagerFactory.Factory.get().newSingletonRuntimeManager(environment);

To include a custom WorkItemHandler, implement the RegisterableItemsFactory interface. Alternatively, you can extend the following existing implementation and add your handlers:

For further information about the implementation, see the org.jbpm.runtime.manager.impl.* package.

For a list of Maven dependencies, see example Embedded jBPM Engine Dependencies in chapter Dependency Management of the Red Hat JBoss BPM Suite Development Guide.

There are two ways of installing services from a service repository: using Process Designer in Business Central or during the Business Central startup process.

Installing Services in Process Designer

To import a work item from a service repository directly in Business Central, do the following:

Installing Services During Business Central Startup

The automatic installation enables you to specify the repository URL and a list of services to be installed during the Business Central startup process. The services are then ready for use after you create or open a process in Process Designer.

To install a service (for example Twitter) from the repository located at http://docs.jboss.org/jbpm/v6.4/repository/, start the server using the following command:

./standalone.sh -Dorg.jbpm.service.repository=http://docs.jboss.org/jbpm/v6.4/repository/ -Dorg.jbpm.service.servicetasknames=Twitter

You can specify more services at once by separating them with a comma. Install-all option is not currently available.

./standalone.sh -Dorg.jbpm.service.repository=http://docs.jboss.org/jbpm/v6.4/repository/ -Dorg.jbpm.service.servicetasknames=Twitter,Jabber

A service repository can be any repository, local or remote, with the index.conf file in its root directory.

Repository Configuration File

The index.conf file must be located in the root directory of the service repository. It contains a list of folders to be processed when searching for services in the service repository.

Email
FileSystem
ESB
FTP
Google
Java
Jabber
Rest
RSS
Transform
Twitter

Each directory can contain another index.conf file. In that case, a new hierarchical structure is created and additional subfolders are scanned. Note that the hierarchical structure of the repository is not shown when browsing the repository using the import wizard, as the category property in the configuration file is used for that.

Work Item Configuration File

Directories with work items must contain:

A work item configuration file is a file with the same name as the parent directory, for example Twitter.wid, that contains details about the work item resources in the service repository. The file is an extension of the work item definition file (see Section 4.14.1, “Work Item Definition”). Note that the configuration file must contain references to any dependencies the work item handler requires. Optionally, it can define the documentation property with a path to documentation and category which defines the category the custom work item is placed under in the repository.

import org.drools.core.process.core.datatype.impl.type.StringDataType;
[
  [
    "name" : "Twitter",
    "description" : "Send a Twitter message.",
    "parameters" : [
      "Message" : new StringDataType() ],
    "displayName" : "Twitter",
    "eclipse:customEditor" : "org.drools.eclipse.flow.common.editor.editpart.work.SampleCustomEditor",
    "icon" : "twitter.gif",
    "category" : "Communication",
    "defaultHandler" : "org.jbpm.process.workitem.twitter.TwitterHandler",
    "documentation" : "index.html",
    "dependencies" : [
      "file:./lib/jbpm-twitter.jar",
      "file:./lib/twitter4j-core-2.2.2.jar" ]
  ]
]

When creating a work item configuration file, it is also possible to use JSON instead of MVEL. See the previous example written in JSON:

[
  [
    "java.util.HashMap",
     {
      "name":"TestServiceFour",
      "displayName":"Twitter",
      "description":"Send a Twitter message",
      "parameters":[
        "java.util.HashMap",
         { "Message":["org.drools.core.process.core.datatype.impl.type.StringDataType", {}] } ],
      "eclipse:customEditor":"org.drools.eclipse.flow.common.editor.editpart.work.SampleCustomEditor",
      "defaultHandler" : "org.jbpm.process.workitem.twitter.TwitterHandler",
      "documentation" : "index.html",
      "dependencies":[
        "java.util.ArrayList", ["file:./lib/jbpm-twitter.jar", "file:./lib/twitter4j-core-2.2.2.jar"] ]
     }
  ]
]

Classes provided in the org.jbpm.process.workitem package allow you to connect to the service and retrieve service information. For example, to list all the services contained in a repository and declared in index.conf, use:

Map<String, WorkDefinitionImpl> workitemsFromRepo = WorkItemRepository.getWorkDefinitions("http://docs.jboss.org/jbpm/v6.4/repository/");

To get more detailed information about a service, use:

workitemsFromRepo.get("Twitter").getName();           // "Twitter"
workitemsFromRepo.get("Twitter").getDescription();    // "Send a Twitter message."
workitemsFromRepo.get("Twitter").getDefaultHandler(); // "org.jbpm.process.workitem.twitter.TwitterHandler"
workitemsFromRepo.get("Twitter").getDependencies();   // String["file:./lib/jbpm-twitter.jar","file:./lib/twitter4j-core-2.2.2.jar"]
...

To check whether the correct version of a service is contained in the repository:

if(workitemsFromRepo.containsKey("Twitter") && workitemsFromRepo.get("Twitter").getVersion().equals("1.0")) {
  // Do something here.
}

To be able to use the LDAP UserGroupCallback implementation configure the respective LDAP properties (see Section 4.17, “LDAP connection”) in one of the following ways: