Chapter 5. Creating a business process in Business Central The process designer is the Red Hat Process Automation Manager process modeler. The output of the modeler is a BPMN 2.0 process definition file. The definition is used as input for the Red Hat Process Automation Manager process engine, which creates a process instance based on the definition. The procedures in this section provide a general overview of how to create a simple business process. For a more detailed business process example, see Getting started with process services . Prerequisites You have created or imported a Red Hat Process Automation Manager project. For more information about creating projects, see Managing projects in Business Central . You have created the required users. User privileges and settings are controlled by the roles assigned to a user and the groups that a user belongs to. For more information about creating users, see Installing and configuring Red Hat Process Automation Manager on Red Hat JBoss EAP 7.4 . Procedure In Business Central, go to Menu Design Projects . Click the project name to open the project's asset list. Click Add Asset Business Process . In the Create new Business Process wizard, enter the following values: Business Process : New business process name Package : Package location for your new business process, for example com.myspace.myProject Click Ok to open the process designer. In the upper-right corner, click the Properties icon and add your business process property information, such as process data and variables: Scroll down and expand Process Data . Click to Process Variables and define the process variables that you want to use in your business process. Table 5.1. General process properties Label Description Name Enter the name of the process. Documentation Describes the process. The text in this field is included in the process documentation, if applicable. ID Enter an identifier for this process, such as orderItems . Package Enter the package location for this process in your Red Hat Process Automation Manager project, such as org.acme . ProcessType Specify whether the process is public or private (or null, if not applicable). Version Enter the artifact version for the process. Ad hoc Select this option if this process is an ad hoc sub-process. Process Instance Description Enter a description of the purpose of the process. Imports Click to open the Imports window and add any data object classes required for your process. Executable Select this option to make the process executable part of your Red Hat Process Automation Manager project. SLA Due Date Enter the service level agreement (SLA) expiration date. Process Variables Add any process variables for the process. Process variables are visible within the specific process instance. Process variables are initialized at process creation and destroyed on process completion. Variable Tags provide greater control over variable behavior, for example whether the variable is required or readonly . For more information about variable tags, see Chapter 6, Variables . Metadata Attributes Add any custom metadata attribute name and value that you want to use for custom event listeners, such as a listener to implement some action when a metadata attribute is present. Global Variables Add any global variables for the process. Global variables are visible to all process instances and assets in a project. Global variables are typically used by business rules and constraints, and are created dynamically by the rules or constraints. The Metadata Attributes entries are similar to Process Variables tags in that they enable new metaData extensions to BPMN diagrams. However, process variable tags modify the behavior of specific process variables, such as whether a certain variable is required or readonly , whereas metadata attributes are key-value definitions that modify the behavior of the overall process. For example, the following custom metadata attribute riskLevel and value low in a BPMN process correspond to a custom event listener for starting the process: Figure 5.1. Example metadata attribute and value in the BPMN modeler Example metadata attribute and value in the BPMN file <bpmn2:process id="approvals" name="approvals" isExecutable="true" processType="Public"> <bpmn2:extensionElements> <tns:metaData name="riskLevel"> <tns:metaValue><![CDATA[low]]></tns:metaValue> </tns:metaData> </bpmn2:extensionElements> Example event listener with metadata value public class MyListener implements ProcessEventListener { ... @Override public void beforeProcessStarted(ProcessStartedEvent event) { Map < String, Object > metadata = event.getProcessInstance().getProcess().getMetaData(); if (metadata.containsKey("low")) { // Implement some action for that metadata attribute } } } In the process designer canvas, use the left toolbar to drag and drop BPMN components to define your business process logic, connections, events, tasks, or other elements. Note A task and event in Red Hat Process Automation Manager expect one incoming and one outgoing flow. If you want to design a business process with multiple incoming and multiple outgoing flows, then consider redesigning the business process using gateways. Using gateways makes the logic apparent, which a sequence flow is executing. Therefore, gateways are considered as a best practice for multiple connections. However, if it is a must to use multiple connections for a task or an event, then you must set the JVM (Java virtual machine) system property jbpm.enable.multi.con to true . When Business Central and KIE Server run on different servers, then ensure that both of them contains the jbpm.enable.multi.con system property as enabled otherwise, the process engine throws an exception. After you add and define all components of the business process, click Save to save the completed business process. 5.1. Creating business rules tasks Business rules tasks are used to make decisions through a Decision Model and Notation (DMN) model or rule flow group. Procedure Create a business process. In the process designer, select the Activities tool from the tool palette. Select Business Rule . Click a blank area of the process designer canvas. If necessary, in the upper-right corner of the screen, click the Properties icon. Add or define the task information listed in the following table as required. Table 5.2. Business rule task parameters Label Description Name The name of the business rule task. You can also double-click the business rule task shape to edit the name. Rule Language The output language for the task. Select Decision Model and Notation (DMN) or Drools (DRL). Rule Flow Group The rule flow group associated with this business task. Select a rule flow group from the list or specify a new rule flow group. On Entry Action A Java, JavaScript, or MVEL script that specifies an action at the start of the task. On Exit Action A Java, JavaScript, or MVEL script that specifies an action at the end of the task. Is Async Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example a task performed by an outside service. AdHoc Autostart Select if this is an ad hoc task that should be started automatically. AdHoc Autostart enables the task to automatically start when the process or case instance is created instead of being starting by a start task. It is often used in case management. SLA Due Date The date that the service level agreement (SLA) expires. Assignments Click to add local variables. Metadata Attributes Add any custom metadata attribute name and value that you want to use for custom event listeners, such as a listener to implement some action when a metadata attribute is present. The Metadata Attributes enable the new metaData extensions to BPMN diagrams and modify the behavior of the overall task. Click Save . 5.2. Creating script tasks Script tasks are used to execute a piece of code written in Java, JavaScript, or MVEL. They contain code snippets that specify the action of the script task. You can include global and process variables in your scripts. Note that MVEL accepts any valid Java code and additionally provides support for nested access of parameters. For example, the MVEL equivalent of the Java call person.getName() is person.name . MVEL also provides other improvements over Java and MVEL expressions are generally more convenient for business users. Procedure Create a business process. In the process designer, select the Activities tool from the tool palette. Select Script . Click a blank area of the process designer canvas. If necessary, in the upper-right corner of the screen, click the Properties icon. Add or define the task information listed in the following table as required. Table 5.3. Script task parameters Label Description Name The name of the script task. You can also double-click the script task shape to edit the name. Documentation Enter a description of the task. The text in this field is included in the process documentation. Click the Documentation tab in the upper-left side of the process designer canvas to view the process documentation. Script Enter a script in Java, JavaScript, or MVEL to be executed by the task, and select the script type. Is Async Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example a task performed by an outside service. AdHoc Autostart Select if this is an ad hoc task that should be started automatically. AdHoc Autostart enables the task to automatically start when the process or case instance is created instead of being starting by a start task. It is often used in case management. Metadata Attributes Add any custom metadata attribute name and value that you want to use for custom event listeners, such as a listener to implement some action when a metadata attribute is present. The Metadata Attributes enable the new metaData extensions to BPMN diagrams and modify the behavior of the overall task. Click Save . 5.3. Creating service tasks A service task is a task that executes an action based on a web service call or in a Java class method. Examples of service tasks include sending emails and logging messages when performing these tasks. You can define the parameters (input) and results (output) associated with a service task. You can also define wrapped parameters that contain all inputs into a single object. To define wrapped parameters, create a new work item handler using Wrapped` : `True in the data assignment. A Service Task should have one incoming connection and one outgoing connection. Procedure In Business Central, select the Admin icon in the top-right corner of the screen and select Artifacts . Click Upload to open the Artifact upload window. Choose the .jar file and click . Important The .jar file contains data types (data objects) and Java classes for web service and Java service tasks respectively. Create a project you want to use. Go to your project Settings Dependencies . Click Add from repository , locate the uploaded .jar file, and click Select . Open your project Settings Work Item Handler . Enter the following values in the given fields: Name - Service Task Value - new org.jbpm.process.workitem.bpmn2.ServiceTaskHandler(ksession, classLoader) Save the project. Example of creating web service task The default implementation of a service task in the BPMN2 specification is a web service. The web service support is based on the Apache CXF dynamic client, which provides a dedicated service task handler that implements the WorkItemHandler interface: org.jbpm.process.workitem.bpmn2.ServiceTaskHandler To create a service task using web service, you must configure the web service: Create a business process. If necessary, in the upper-right corner of the screen, click the Properties icon. Click in the Imports property to open the Imports window. Click +Add to the WSDL Imports to import the required WSDL (Web Services Description Language) values. For example: Location : http://localhost:8080/sample-ws-1/SimpleService?wsdl The location points to the WSDL file of your service. Namespace : http://bpmn2.workitem.process.jbpm.org/ The namespace must match targetNamespace from your WSDL file. In the process designer, select the Activities tool from the tool palette. Select Service Task . Click a blank area of the process designer canvas. Add or define the task information listed in the following table as required. Table 5.4. Web service task parameters Label Description Name The name of the service task. You can also double-click the service task shape to edit the name. Documentation Enter a description of the task. The text in this field is included in the process documentation. Click the Documentation tab in the upper-left side of the process designer canvas to view the process documentation. Implementation Specify a web service. Interface The service used to implement the script, such as CountriesPortService . Operation The operation that is called by the interface, such as getCountry . Assignments Click to add local variables. AdHoc Autostart Select if this is an ad hoc task that should be started automatically. AdHoc Autostart enables the task to automatically start when the process or case instance is created instead of being starting by a start task. It is often used in case management. Is Async Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example a task performed by an outside service. Is Multiple Instance Select if this task has multiple instances. MI Execution mode Select if the multiple instances execute in parallel or sequentially. MI Collection input Specify a variable that represents a collection of elements for which new instances are created, such as inputCountryNames . MI Data Input Specify the input data assignment that is transferred to a web service, such as Parameter . MI Collection output The array list in which values returned from the web service task is stored, such as outputCountries . MI Data Output Specify the output data assignment for the web service task, which stores the result of class execution on the server, such as Result . MI Completion Condition (mvel) Specify the MVEL expression that is evaluated on each completed instance to check if the specified multiple instance node can complete. On Entry Action A Java, JavaScript, or MVEL script that specifies an action at the start of the task. On Exit Action A Java, JavaScript, or MVEL script that specifies an action at the end of the task. SLA Due Date The date that the service level agreement (SLA) expires. Metadata Attributes Add any custom metadata attribute name and value that you want to use for custom event listeners, such as a listener to implement some action when a metadata attribute is present. The Metadata Attributes enable the new metaData extensions to BPMN diagrams and modify the behavior of the overall task. Example of creating Java service task When you create a service task using Java method, then the method can only contain one parameter and returns a single value. To create a service task using a Java method, you must add the Java class to the dependencies of the project: Create a business process. In the process designer, select the Activities tool from the tool palette. Select Service Task . Click a blank area of the process designer canvas. If necessary, in the upper-right corner of the screen, click the Properties icon. Add or define the task information listed in the following table as required. Table 5.5. Java service task parameters Label Description Name The name of the service task. You can also double-click the service task shape to edit the name. Documentation Enter a description of the task. The text in this field is included in the process documentation. Click the Documentation tab in the upper-left side of the process designer canvas to view the process documentation. Implementation Specify the task is implemented in Java. Interface The class used to implement the script, such as org.xyz.HelloWorld . Operation The method that is called by the interface, such as sayHello . Assignments Click to add local variables. AdHoc Autostart Select if this is an ad hoc task that should be started automatically. AdHoc Autostart enables the task to automatically start when the process or case instance is created instead of being starting by a start task. It is often used in case management. Is Async Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example a task performed by an outside service. Is Multiple Instance Select if this task has multiple instances. MI Execution mode Select if the multiple instances execute in parallel or sequentially. MI Collection input Specify a variable that represents a collection of elements for which new instances are created, such as InputCollection . MI Data Input Specify the input data assignment that is transferred to a Java class. For example, you can set the input data assignments as Parameter and ParameterType . ParameterType represents the type of Parameter and sends arguments to the execution of Java method. MI Collection output The array list in which values returned from the Java class is stored, such as OutputCollection . MI Data Output Specify the output data assignment for Java service task, which stores the result of class execution on the server, such as Result . MI Completion Condition (mvel) Specify the MVEL expression that is evaluated on each completed instance to check if the specified multiple instance node can complete. For example, OutputCollection.size() <= 3 indicates more than three people are not addressed. On Entry Action A Java, JavaScript, or MVEL script that specifies an action at the start of the task. On Exit Action A Java, JavaScript, or MVEL script that specifies an action at the end of the task. SLA Due Date The date that the service level agreement (SLA) expires. Metadata Attributes Add any custom metadata attribute name and value that you want to use for custom event listeners, such as a listener to implement some action when a metadata attribute is present. The Metadata Attributes enable the new metaData extensions to BPMN diagrams and modify the behavior of the overall task. Click Save . 5.4. Creating user tasks User tasks are used to include human actions as input to the business process. Procedure Create a business process. In the process designer, select the Activities tool from the tool palette. Select User . Drag and drop a user task onto the process designer canvas. If necessary, in the upper-right corner of the screen, click the Properties icon. Add or define the task information listed in the following table as required. Table 5.6. User task parameters Label Description Name The name of the user task. You can also double-click the user task shape to edit the name. Documentation Enter a description of the task. The text in this field is included in the process documentation. Click the Documentation tab in the upper-left side of the process designer canvas to view the process documentation. Task Name The name of the human task. Subject Enter a subject for the task. Actors The actors responsible for executing the human task. Click Add to add a row then select an actor from the list or click New to add a new actor. Groups The groups responsible for executing the human task. Click Add to add a row then select a group from the list or click New to add a new group. Assignments Local variables for this task. Click to open the Task Data I/O window then add data inputs and outputs as required. You can also add MVEL expressions as data input and output assignments. For more information about the MVEL language, see Language Guide for 2.0 . Reassignments Specify a different actor to complete this task. Notifications Click to specify notifications associated with the task. Is Async Select if this task should be invoked asynchronously. Make tasks asynchronous if they cannot be executed instantaneously, for example a task performed by an outside service. Skippable Select if this task is not mandatory. Priority Specify a priority for the task. Description Enter a description for the human task. Created By The user that created this task. AdHoc Autostart Select if this is an ad hoc task that should be started automatically. AdHoc Autostart enables the task to automatically start when the process or case instance is created instead of being starting by a start task. It is often used in case management. Multiple Instance Select if this task has multiple instances. On Entry Action A Java, JavaScript, or MVEL script that specifies an action at the start of the task. On Exit Action A Java, JavaScript, or MVEL script that specifies an action at the end of the task. Content The content of the script. SLA Due Date The date that the service level agreement (SLA) expires. Metadata Attributes Add any custom metadata attribute name and value that you want to use for custom event listeners, such as a listener to implement some action when a metadata attribute is present. The Metadata Attributes enable the new metaData extensions to BPMN diagrams and modify the behavior of the overall task. Click Save . 5.4.1. Setting the user task assignment strategy The user task assignment strategy is used to automatically assign the tasks to a suitable user. The assignment strategy allows more efficient task allocation based on the associated properties, such as potential owners, task priority, and task data. org.jbpm.task.assignment.strategy is the system property for the user task assignment strategy in Red Hat Process Automation Manager. You can also explicitly define an assignment strategy for a user task in Business Central. Prerequisites You have created a project in Business Central. You must set the org.jbpm.task.assignment.enabled system property to true . Procedure Create a business process. For more information about creating a business process in Business Central, see Chapter 5, Creating a business process in Business Central . Create a user task. For more information about creating a user task in Business Central, see Section 5.4, "Creating user tasks" . In the upper-right corner of the screen, click the Properties icon. Expand Implementation/Execution and click below to Assignments , to open the Data I/O window. Add a data input with the name AssignmentStrategy , with the type String , and with the constant source, such as the strategy name. Note If AssignmentStrategy is set as null, then no assignment strategy is used for the task. Click Ok . The AssignmentStrategy variable is added as a data input to the user task. 5.5. BPMN2 user task life cycle in process designer You can trigger a user task element during the process instance execution to create a user task. The user task service of the task execution engine executes the user task instance. The process instance continues the execution only when the associated user task is completed or aborted. A user task life cycle is as follows: When a process instance enters a user task element, the user task is in the Created stage. Created stage is a transient stage and the user task enters the Ready stage immediately. The task appears in the task list of all the actors who are allowed to execute the task. When an actor claims the user task, the task becomes Reserved . Note If a user task has a single potential actor, the task is assigned to that actor upon creation. When an actor who claimed the user task starts the execution, the status of the user task changes to InProgress . Once an actor completes the user task, the status changes to Completed or Failed depending on the execution outcome. There are also several other life cycle methods, including: Delegating or forwarding a user task so the user task is assigned to another actor. Revoking a user task, then the user task is no longer claimed by a single actor but is available to all actors who are allowed to take it. Suspending and resuming a user task. Stopping a user task that is in progress. Skipping a user task, in which the execution of the task is suspended. For more information about the user task life cycle, see the Web Services Human Task specification . 5.6. BPMN2 task permission matrix in process designer The user task permission matrix summarizes the actions that are allowed for specific user roles. The user roles are as follows: Potential owner: User who can claim the task, which was claimed earlier and is released and forwarded. The tasks with Ready status can be claimed, and the potential owner becomes the actual owner of the task. Actual owner: User who claims the task and progresses the task to completion or failure. Business administrator: Super user who can modify the status or progress with the task at any point of the task life cycle. The following permission matrix represents the authorizations for all operations that modify a task. + indicates that the user role is allowed to do the specified operation. - indicates that the user role is not allowed to do the specified operation, or the operation does not match with the user's role. Table 5.7. Main operations permissions matrix Operation Potential owner Actual owner Business administrator activate - - + claim + - + complete - + + delegate + + + fail - + + forward + + + nominate - - + release - + + remove - - + resume + + + skip + + + start + + + stop - + + suspend + + + 5.7. Making a copy of a business process You can make a copy of a business process in Business Central and modify the copied process as needed. Procedure In the business process designer, click Copy in the upper-right toolbar. In the Make a Copy window, enter a new name for the copied business process, select the target package, and optionally add a comment. Click Make a Copy . Modify the copied business process as needed and click Save to save the updated business process. 5.8. Resizing elements and using the zoom function to view business processes You can resize individual elements in a business process and zoom in or out to modify the view of your business process. Procedure In the business process designer, select the element and click the red dot in the lower-right corner of the element. Drag the red dot to resize the element. Figure 5.2. Resize an element To zoom in or out to view the entire diagram, click the plus or minus sign on the lower-right side of the canvas. Figure 5.3. Enlarge or shrink a business process 5.9. Generating process documentation in Business Central In the process designer in Business Central, you can view and print a report of the process definition. The process documentation summarizes the components, data, and visual flow of the process in a format (PDF) that you can print and share more easily. Procedure In Business Central, navigate to a project that contains a business process and select the process. In the process designer, click the Documentation tab to view the summary of the process file, and click Print in the top-right corner of the window to print the PDF report. Figure 5.4. Generate process documentation

Commands:
<bpmn2:process id="approvals" name="approvals" isExecutable="true" processType="Public"> <bpmn2:extensionElements> <tns:metaData name="riskLevel"> <tns:metaValue><![CDATA[low]]></tns:metaValue> </tns:metaData> </bpmn2:extensionElements>
public class MyListener implements ProcessEventListener { @Override public void beforeProcessStarted(ProcessStartedEvent event) { Map < String, Object > metadata = event.getProcessInstance().getProcess().getMetaData(); if (metadata.containsKey("low")) { // Implement some action for that metadata attribute } } }