Developing process services in Red Hat Process Automation Manager

Procedure

1. In your VS Code IDE, select the Extensions menu option and search for Red Hat Business Automation Bundle for DMN, BPMN, and test scenario file support.

   For DMN or BPMN file support only, you can also search for the individual DMN Editor or BPMN Editor extensions.

2. When the Red Hat Business Automation Bundle extension appears in VS Code, select it and click Install.
3. For optimal VS Code editor behavior, after the extension installation is complete, reload or close and re-launch your instance of VS Code.

Procedure

1. Install the standalone editors using one of the following methods:

   Download each JavaScript file manually: For this method, follow these steps:

   1. Download the JavaScript files.
   2. Add the downloaded Javascript files to your hosted application.

   3. Add the following <script> tag to your HTML page:

      Script tag for your HTML page for the DMN editor

      <script src="https://<YOUR_PAGE>/dmn/index.js"></script>

      Copy to Clipboard Toggle word wrap

      Script tag for your HTML page for the BPMN editor

      <script src="https://<YOUR_PAGE>/bpmn/index.js"></script>

      Copy to Clipboard Toggle word wrap

   Use the NPM package: For this method, follow these steps:

   1. Add the NPM package to your package.json file:

      Adding the NPM package

      npm install @kie-tools/kie-editors-standalone

      Copy to Clipboard Toggle word wrap

   2. Import each editor library to your TypeScript file:

      Importing each editor

      import * as DmnEditor from "@kie-tools/kie-editors-standalone/dist/dmn"
      import * as BpmnEditor from "@kie-tools/kie-editors-standalone/dist/bpmn"

      Copy to Clipboard Toggle word wrap

2. After you install the standalone editors, open the required editor by using the provided editor API, as shown in the following example for opening a DMN editor. The API is the same for each editor.

   Opening the DMN standalone editor

   const editor = DmnEditor.open({
     container: document.getElementById("dmn-editor-container"),
     initialContent: Promise.resolve(""),
     readOnly: false,
     origin: "",
     resources: new Map([
       [
         "MyIncludedModel.dmn",
         {
           contentType: "text",
           content: Promise.resolve("")
         }
       ]
     ])
   });

   Copy to Clipboard Toggle word wrap

   Use the following parameters with the editor API:

   Expand

   Table 2.1. Example parameters

   Parameter	Description
   container	HTML element in which the editor is appended.
   initialContent	Promise to a DMN model content. This parameter can be empty, as shown in the following examples: Promise.resolve("") Promise.resolve("<DIAGRAM_CONTENT_DIRECTLY_HERE>") fetch("MyDmnModel.dmn").then(content ⇒ content.text())
   readOnly (Optional)	Enables you to allow changes in the editor. Set to false (default) to allow content editing and true for read-only mode in editor.
   origin (Optional)	Origin of the repository. The default value is window.location.origin.
   resources (Optional)	Map of resources for the editor. For example, this parameter is used to provide included models for the DMN editor or work item definitions for the BPMN editor. Each entry in the map contains a resource name and an object that consists of content-type (text or binary) and content (similar to the initialContent parameter).

   Show more

   The returned object contains the methods that are required to manipulate the editor.

   Expand

   Table 2.2. Returned object methods

   Method	Description
   getContent(): Promise<string>	Returns a promise containing the editor content.
   setContent(path: string, content: string): void	Sets the content of the editor.
   getPreview(): Promise<string>	Returns a promise containing an SVG string of the current diagram.
   subscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): (isDirty: boolean) ⇒ void	Sets a callback to be called when the content changes in the editor and returns the same callback to be used for unsubscription.
   unsubscribeToContentChanges(callback: (isDirty: boolean) ⇒ void): void	Unsubscribes the passed callback when the content changes in the editor.
   markAsSaved(): void	Resets the editor state that indicates that the content in the editor is saved. Also, it activates the subscribed callbacks related to content change.
   undo(): void	Undoes the last change in the editor. Also, it activates the subscribed callbacks related to content change.
   redo(): void	Redoes the last undone change in the editor. Also, it activates the subscribed callbacks related to content change.
   close(): void	Closes the editor.
   getElementPosition(selector: string): Promise<Rect>	Provides an alternative to extend the standard query selector when an element lives inside a canvas or a video component. The selector parameter must follow the <PROVIDER>:::<SELECT> format, such as Canvas:::MySquare or Video:::PresenterHand. This method returns a Rect representing the element position.
   envelopeApi: MessageBusClientApi<KogitoEditorEnvelopeApi>	This is an advanced editor API. For more information about advanced editor API, see MessageBusClientApi and KogitoEditorEnvelopeApi.

   Show more

1. Go to project Settings.
2. Open Deployment → Environment entries.

3. Enter the following values in the given fields:

   • Name - Autoclaim
   • Value - "false”

Procedure

1. Create a business process.
2. In the process designer, select the Activities tool from the tool palette.
3. Select Business Rule.
4. Click a blank area of the process designer canvas.
5. If necessary, in the upper-right corner of the screen, click the Properties icon.

6. Add or define the task information listed in the following table as required.

   Expand

   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.

   Show more
7. Click Save.

Procedure

1. Create a business process.
2. In the process designer, select the Activities tool from the tool palette.
3. Select Script.
4. Click a blank area of the process designer canvas.
5. If necessary, in the upper-right corner of the screen, click the Properties icon.

6. Add or define the task information listed in the following table as required.

   Expand

   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.

   Show more
7. Click Save.

Procedure

1. In Business Central, select the Admin icon in the top-right corner of the screen and select Artifacts.
2. Click Upload to open the Artifact upload window.

3. 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.

4. Create a project you want to use.
5. Go to your project Settings → Dependencies.
6. Click Add from repository, locate the uploaded .jar file, and click Select.
7. Open your project Settings → Work Item Handler.

8. Enter the following values in the given fields:

   • Name - Service Task
   • Value - new org.jbpm.process.workitem.bpmn2.ServiceTaskHandler(ksession, classLoader)

9. 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:

   1. Create a business process.
   2. If necessary, in the upper-right corner of the screen, click the Properties icon.
   3. Click in the Imports property to open the Imports window.

   4. Click +Add next 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.

   5. In the process designer, select the Activities tool from the tool palette.
   6. Select Service Task.
   7. Click a blank area of the process designer canvas.

   8. Add or define the task information listed in the following table as required.

      Expand

      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.

      Show more

   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:

   1. Create a business process.
   2. In the process designer, select the Activities tool from the tool palette.
   3. Select Service Task.
   4. Click a blank area of the process designer canvas.
   5. If necessary, in the upper-right corner of the screen, click the Properties icon.

   6. Add or define the task information listed in the following table as required.

      Expand

      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.

      Show more
10. Click Save.

Procedure

1. Create a business process.
2. In the process designer, select the Activities tool from the tool palette.
3. Select User.
4. Drag and drop a user task onto the process designer canvas.
5. If necessary, in the upper-right corner of the screen, click the Properties icon.

6. Add or define the task information listed in the following table as required.

   Expand

   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.

   Show more
7. Click Save.

Procedure

1. In the business process designer, click Copy in the upper-right toolbar.
2. In the Make a Copy window, enter a new name for the copied business process, select the target package, and optionally add a comment.
3. Click Make a Copy.
4. Modify the copied business process as needed and click Save to save the updated business process.

Procedure

1. In the business process designer, select the element and click the red dot in the lower-right corner of the element.

2. Drag the red dot to resize the element.

   Figure 5.2. Resize an element

   

   View larger image

   

3. 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

   

   View larger image

   

Procedure

1. In Business Central, navigate to a project that contains a business process and select the process.

2. 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

   

   View larger image

   

Procedure

1. Open a business process asset.
2. Click a blank area of the process designer canvas.
3. Click the Properties icon on the upper-right side of the screen to open the Properties panel.
4. If necessary, expand the Process section.
5. In the Global Variables sub-section, click the plus icon.
6. Enter a name for the variable in the Name box.
7. Select a data type from the Data Type menu.

Procedure

1. Open a business process asset.
2. Click a blank area of the process designer canvas.
3. Click the Properties icon on the upper-right side of the screen to open the Properties panel.
4. If necessary, expand the Process Data section.
5. In the Process Variables sub-section, click the plus icon.
6. Enter a name for the variable in the Name box.
7. Select a data type from the Data Type menu.

Procedure

1. Open a business process asset.
2. Select a task that is not a script task.
3. Click the Properties icon on the upper-right side of the screen to open the Properties panel.
4. Click the box under the Assignments sub-section. The Task Data I/O dialog box opens.
5. Click Add next to Data Inputs and Assignments or Data Outputs and Assignments.
6. Enter a name for the local variable in the Name box.
7. Select a data type from the Data Type menu.
8. Select a source or target then click Save.

Procedure

1. In Business Central, go to Menu → Manage → Process Instances.
2. Select the Process Variables tab and click Edit for the variable name that you want to edit.
3. Add or change the Variable Value and click Save.

Procedure

1. In Business Central, go to Menu → Manage → Process Definitions.
2. Select the process definition for which you want to start a new process instance from the list. The details page of the definition opens.
3. Click New Process Instance in the upper-right corner to start a new process instance.
4. Provide any required information for the process instance.
5. Click Submit to create the process instance.
6. View the new process instance in Menu → Manage → Process Instances.

Procedure

1. In Business Central, go to Menu → Manage → Process Instances.
2. Click New Process Instance in the upper-right corner and select the process definition for which you want to start a new process instance from the drop-down list.
3. Provide any information required to start a new process instance.

4. Click Start to create the process instance.

   The new process instance appears in the Manage Process Instances list.

Procedure

1. In Business Central, go to Menu → Design → Projects.
2. Click the project name to open the asset view and then click the business process name.
3. In the process designer, click the process task that you want to create a form for (if applicable).

4. In the upper-right toolbar, click the Form Generation icon and select the forms that you want to generate:

   • Generate process form: Generates the form for the entire process. This is the initial form that a user must complete when the process instance is started.
   • Generate all forms: Generates the form for the entire process and for all user tasks.
   • Generate forms for selection: Generates the forms for the selected user task nodes.

   Figure 14.2. Form generation menu

   

   View larger image

   

   The forms are created in the root directory of your project.

5. Go to the root directory of your project in Business Central, click the new form name, and use the Form Modeler to customize the form to meet your requirements.

Procedure

1. In Business Central, go to Menu → Design → Projects and click the project name.
2. Click Add Asset → Form.

3. Provide the following information in the Create new Form window:

   • Form name (must be unique)
   • Package name

   • Model type: Select either Business Process or Data Object.

     • For the Business Process model type, select your business process from the Select Process drop-down menu, and then select the form that you want to create from the Select Form drop-down menu.
     • For the Data Object model type, select one of your project data objects from the Select Data Object from Project drop-down menu.
4. Click Ok to open the Form Modeler.
5. In the Components view on the left side of the Form Modeler, expand the Model Fields and Form Controls menus and create a new form by dragging your required fields and form controls to the canvas.
6. Click Save to save your changes.

1. Set the document marshalling strategy.
2. Create a document variable in the business process.
3. Map the task inputs and outputs to the document variable.

Procedure

1. In Business Central, go to Menu → Design → Projects and click the project name.
2. Select or create the business process asset in which you want to invoke the DMN service.
3. In the process designer, use the left toolbar to drag and drop BPMN components as usual to define your overall business process logic, connections, events, tasks, or other elements.

4. To incorporate a DMN service in the business process, add a Business Rule task from the left toolbar or from the start-node options and insert the task in the relevant location in the process flow.

   For this example, the following Accept Train business process incorporates the DMN service in the Route To Rail node:

   Figure 15.4. Example Accept Train business process with a DMN service

   

   View larger image

   

5. Select the business rule task node that you want to use for the DMN service, click Properties in the upper-right corner of the process designer, and under Implementation/Execution, define the following fields:

   • Rule Language: Select DMN.
   • Namespace: Enter the unique namespace from the DMN model file. Example: https://www.drools.org/kie-dmn
   • Decision Name: Enter the name of the DMN decision node that you want to invoke in the selected process node. Example: Rail

   • DMN Model Name: Enter the DMN model name. Example: Compute Rail

     Important

     When you explore the root node, ensure that the Namespace and DMN Model Name fields consist of the same value in BPMN as DMN diagram.

6. Under Data Assignments → Assignments, click the Edit icon and add the DMN input and output data to define the mapping between the DMN service and the process data.

   For the Route To Rail DMN service node in this example, you add an input assignment for Train that corresponds to the input node in the DMN model, and add an output assignment for Rail that corresponds to the decision node in the DMN model. The Data Type must match the type that you set for that node in the DMN model, and the Source and Target definition is the relevant variable or field for the specified object.

   Figure 15.5. Example input and output mapping for the Route To Rail DMN service node

   

   View larger image

   
7. Click Save to save the data input and output data.

8. Define the remainder of your business process according to how you want the completed DMN service to be handled.

   For this example, the Properties → Implementation/Execution → On Exit Action value is set to the following code to store the rail number after the Route To Rail DMN service is complete:

   Example code for On Exit Action

   train.setRailNumber(rail);

   Copy to Clipboard Toggle word wrap

   If the rail number is not computed, the process reaches a No Appropriate Rail end error node that is defined with the following condition expression:

   Figure 15.6. Example condition for No Appropriate Rail end error node

   

   View larger image

   

   If the rail number is computed, the process reaches an Accept Train script task that is defined with the following condition expression:

   Figure 15.7. Example condition for Accept Train script task node

   

   View larger image

   

   The Accept Train script task also uses the following script in Properties → Implementation/Execution → Script to print a message about the train route and current rail:

   com.myspace.trainstation.Train t =
       (com.myspace.trainstation.Train) kcontext.getVariable("train");
   System.out.println("Train from: " + t.getDepartureStation() +
                      ", to: " + t.getDestinationStation() +
                      ",  is on rail: " + t.getRailNumber());

   Copy to Clipboard Toggle word wrap

9. After you define your business process with the incorporated DMN service, save your process in the process designer, deploy the project, and run the corresponding process definition to invoke the DMN service.

   For this example, when you deploy the TrainStation project and run the corresponding process definition, you open the process instance form for the Accept Train process definition and set the departure station and destination station fields to test the execution:

   Figure 15.8. Example process instance form for the Accept Train process definition

   

   View larger image

   

   After the process is executed, a message appears in the server log with the train route that you specified:

   Example server log output for the Accept Train process

   Train from: Zagreb, to: Belgrade,  is on rail: 1

   Copy to Clipboard Toggle word wrap

Procedure

1. In Business Central, go to Menu → Track → Task Inbox.
2. On the Task Inbox page, click the task to open it.

3. On the Work tab of the task page, click Start. Once you start a task, its status changes to InProgress.

   You can view the status of tasks on the Task Inbox as well as on the Manage Tasks page.