1. Integrate the JavaScript library in the codebase for the external client application so that its functions are available.
2. Create a new instance of the jBPMFormsAPI class in your own JavaScript code. This is the starting point for all interactions with this library.

   var jbpmRestAPI = new jBPMFormsAPI();

3. Call your desired methods on this instance. For example, if you want to show a form, you would use the following method:

   jbpmRestAPI.showStartProcessForm(hostUrl, deploymentId, processId, divId, onsuccess, onerror);

   and provide the relevant details (hostUrl, deploymentId, processId and so on. A full list of the methods and parameters follows after this section).
4. Do post processing with the optional onsuccess and onerror methods.
5. Work with the form, starting processes (startProcess()), claiming tasks (claimTask()) starting tasks (startTask()) or completing tasks (completeTask). Full list of available methods follows after this section.
6. Once you're finished with the form, clear the container that displayed it using clearContainer() method.

1. showStartProcessForm(hostUrl, deploymentId, processId, divId, onsuccessCallback, onerrorCallback): Makes a call to the REST endpoint to obtain the form URL. If it receives a valid response, it embeds the process start form in the stated div. You need these parameters:
   • hostURL: The URL of the Business Central instance that holds the deployments.
   • deploymentId: The deployment identifier that contains the process to run.
   • processId: The identifier of the process to run.
   • divId: The identifier of the div that has to contain the form.
   • onsuccessCallback (optional): A JavaScript function executed if the form is going to be rendered. This function will receive the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to render the form. This function will receive the server response as a parameter.
2. startProcess(divId, onsuccessCallback, onerrorCallback): Submits the form loaded on the stated div and starts the process. You need these parameters:
   • divId: The identifier of the div that contains the form.
   • onsuccessCallback(optional): A JavaScript function executed after the process is started. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to start the process. This function receives the server response as a parameter.
3. showTaskForm(hostUrl, taskId, divId, onsuccessCallback, onerrorCallback): Makes a call to the REST endpoint to obtain the form URL. If it receives a valid response, it embeds the task form in the stated div. You need these parameters:
   • hostURL: The URL of the Business Central instance that holds the deployments.
   • taskId: The identifier of the task to show the form.
   • divId: The identifier of the div that has to contain the form.
   • onsuccessCallback (optional): A JavaScript function executed if the form is going to be rendered. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to render the form. This function receives the server response as a parameter.
4. claimTask(divId, onsuccessCallback, onerrorCallback): Claims the task whose form is being rendered. You need these parameters:
   • divId: The identifier of the div that contains the form.
   • onsuccessCallback (optional): A JavaScript function executed after the task is claimed. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to claim the task. This function receives the server response as a parameter.
5. startTask(divId, onsuccessCallback, onerrorCallback): Starts the task whose form is being rendered. You need these parameters:
   • divId: The identifier of the div that contains the form.
   • onsuccessCallback (optional): A JavaScript function executed after the task is claimed. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to claim the task. This function receives the server response as a parameter.
6. releaseTask(divId, onsuccessCallback, onerrorCallback): Releases the task whose form is being rendered. You need these parameters:
   • divId: The identifier of the div that contains the form.
   • onsuccessCallback (optional): A JavaScript function executed after the task is claimed. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to claim the task. This function receives the server response as a parameter.
7. saveTask(divId, onsuccessCallback, onerrorCallback): Submits the form and saves the state of the task whose form is being rendered. You need these parameters:
   • divId: The identifier of the div that contains the form.
   • onsuccessCallback (optional): A JavaScript function executed after the task is claimed. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to claim the task. This function receives the server response as a parameter.
8. completeTask(divId, onsuccessCallback, onerrorCallback): Submits the form and completes task whose form is being rendered. You need these parameters:
   • divId: The identifier of the div that contains the form.
   • onsuccessCallback (optional): A JavaScript function executed after the task is claimed. This function receives the server response as a parameter.
   • onerrorCallback (optional): A JavaScript function executed if any error occurs and it is impossible to claim the task. This function receives the server response as a parameter.
9. clearContainer(divId): Cleans the div content and the related data stored on the component. You need these parameters:
   • divId: The identifier of the div that contains the form.

Procedure 4.5. Defining a Global in the Process Designer

1. Open the Process in the Process Designer.
2. In the Properties panel of the BPMN Diagram expand the Extra item.
3. Click the empty value cell next to the Globals and click the arrow.
   

   Figure 4.22. Global properties cell

4. In the Editor for Variable Definitions window, click the Add Variable button and define the variable details.
   

   Figure 4.23. Editor for Variable Definitions

Procedure 4.6. Defining and Initializing a Global using the API

1. Define the variables as a Map of the <String, Object> values.
2. Provide the map as a parameter to the startProcess() method.

1. In the Project Explorer panel (the Project Authoring perspective), select your project.
2. In the perspective menu, click New Item → Work Item Definition.
3. In the Create new dialogue box, define the definition details:
   • In the Name field provide the definition name.
   • Click the OK button.
4. A new tab with the work item definition template opens up in the Work Item editor.

   Note

   Whenever a user creates a new business process in some project, the default WID will be created. Users will be able to reuse or directly alter the WID file whenever necessary. In addition, there will always be a default WID once the BPMN process is created.
5. In the editor, edit the source of the MVEL work item definition. The definition is stored in the current package.
   If you are planning to add the work item using the service repository as opposed to adding the work item handler to the classpath, make sure to define its dependencies, category, etc.
   If you are creating the definition out of Business Central, your project directory structure should be similar to PROJECT_NAME/src/main/resources/PACKAGE_NAME/WID_NAME.wid (visible in the Repository view).

   Example 4.8. Example wid file

   import org.drools.core.process.core.datatype.impl.type.StringDataType;
   import org.drools.core.process.core.datatype.impl.type.ObjectDataType;
   
   [
     [
       "name" : "MyTask",
       "parameters" : [
           "MyFirstParam" : new StringDataType(),
           "MySecondParam" : new StringDataType(),
           "MyThirdParam" : new ObjectDataType()
       ],
       "results" : [
           "Result" : new ObjectDataType("java.util.Map")
       ],
       "displayName" : "My Task",
       "icon" : ""
     ]
   ]

6. Upload and assign an icon to the Work Item:
   1. Click New Item → Uploaded file.
   2. In the Create new Uploaded file dialogue box, define the resource name and make sure to include the file's extension in the name. Click the Choose File option to locate and upload the file (png or gif, 16x16 pixels). Click Ok.
   3. Make sure your mouse is positioned within the blank " " of the icon parameter:

          "icon" : " "

      Click the Select icon to add drop-down and click the icon file. The icon path will appear within the parameter:

          "icon" : "ExampleIcon.png"

      Note

      The path to describe the location of an icon can be relative or absolute, as long as the icon can be found using one of these methods. For example, the following paths are supported:

       "icon" : "ExampleIcon.png"           (icon in the same folder as the .wid file)
       "icon" : "com/test/ExampleIcon.png"  (icon relative to .wid file location)
       "icon" : "../test/ExampleIcon.png"   (icon relative to .wid file location)
       "icon" : "/HR/src/main/resources/ExampleIcon.png"   (absolute path to icon)
      

7. In the Process Designer, check if your work item is available in the palette.

1. Create a maven project with your implementation of a work item handler with the required business logic. Make sure to call the completeWorkItem() function to finish the business logic execution and add the kie-api artifact with the 6.x.x.redhat-x version value as the project dependency.

   Example 4.9. Notification work item handler

   package com.sample;
   
   import org.kie.api.runtime.process.WorkItem;
   import org.kie.api.runtime.process.WorkItemHandler;
   import org.kie.api.runtime.process.WorkItemManager;
   
   public class NotificationWorkItemHandler implements WorkItemHandler {
   
     public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
       String from = (String) workItem.getParameter("From");
       String to = (String) workItem.getParameter("To");
       String message = (String) workItem.getParameter("Message");
       String priority = (String) workItem.getParameter("Priority");
   
   /*
     Send email.
     The ServiceRegistry class is an example class implementing the task business logic.
   */
       EmailService service = ServiceRegistry.getInstance().getEmailService();
       service.sendEmail(from, to, "Notification", message);
   
   /*
     Notify manager that work item has been completed.
     The completeWorkItem() call completes the work item execution.
   */
       manager.completeWorkItem(workItem.getId(), null);
     }
   
     public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
     // Do nothing, notifications cannot be aborted
     }
   
   }

   Important

   If the WorkItemManager is not notified about the work item completion, the process engine is never notified that your work item node has completed.
2. Register the work item handler in the DEPLOY_DIR/business-central.war/WEB-INF/classes/META-INF/CustomWorkItemHandlers.conf file.
   The CustomWorkItemHandlers.conf file contains information like the following:

   [
     "Log": new org.jbpm.process.instance.impl.demo.SystemOutWorkItemHandler(),
     "WebService": new org.jbpm.process.workitem.webservice.WebServiceWorkItemHandler(ksession),
     "Rest": new org.jbpm.process.workitem.rest.RESTWorkItemHandler()
   ]

   Notice the "Rest" value in the previous file. This indicates the WorkItemHandler is capable of interacting with REST services. It supports both secured/authenticated and open/not authenticated services.
   This REST value is defined in the project's WID file in the following manner:

   [
     "name" : "Rest",
     "parameters" : [
   
     //Url - Mandatory resource location to be invoked.
         "Url" : new StringDataType(),
   
     //Method - Defaults to GET and is the HTTP method that will be executed.
         "Method" : new StringDataType(),
   
     //ConnectionTimeout - Defaults to 60 seconds for the connection timeout.
         "ConnectTimeout" : new StringDataType(),
   
     //ReadTimeout - Defaults to 60 seconds for the read timeout.
         "ReadTimeout" : new StringDataType(),
   
     //Username - The username for authentication that overrides the one given on handler initialization.
         "Username" : new StringDataType(),
   
     //Password - The password for authentication that overrides the one given on handler initialization.
         "Password" : new StringDataType()
     ],
     "results" : [
         "Result" : new ObjectDataType(),
     ],
     "displayName" : "REST",
     "icon" : "defaultservicenodeicon.png"
   ]

   The configuration options displayed about must be given via the work item parameter. The authentication information can be given on handler initialization, but it can be overridden via the work item parameter.
3. Compile the project. The resulting JAR file should be placed in (DEPLOY_DIR/business-central.war/WEB-INF/lib/).
4. Restart the server.

1. Register the work item handler in the Administration menu path PROJECT_NAME/src/main/resources/META-INF/kmodule.xml
2. Make sure the work item handler is given as a MVEL expression; for example, new org.jbpm.wih.CustomHandler() or FQCN expression: org.jbpm.wih.CustomHandler.
3. Compile the project. Upload the work item handler JAR into Business Central via the Artifact Repository. Then add it as a dependency for the project where the user wants to use this handler.

1. Register the work item handler like the following:

   /* Create the drools name of the <task> and the custom work item handler instance */
   KieSession kieSession = kieBase.newKieSession();
   ksession.getWorkItemManager().registerWorkItemHandler(
     "Notification",
     new NotificationWorkItemHandler()
   );
   

2. Look at the BPMN2 syntax for the process. The previous registration example would appear as follows:

   <?xml version="1.0" encoding="UTF-8"?>
   <definitions id="Definition"
                xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
                xs:schemaLocation="http://www.omg.org/spec/BPMN/20100524/MODEL BPMN20.xsd"
   ...
                xmlns:tns="http://www.jboss.org/drools">
   
   ...
   
       <process isExecutable="true" id="myCustomProcess" name="Domain-Specific Process" >
   
   ...
   <!-- The tns:taskName attribute in the <task> node is necessary for the WorkItemManager to be able to see which WorkItemHandler instance should be used with which task or work item. -->
       <task id="_5" name="Notification Task" tns:taskName="Notification" >
   
   ...

1. Open your Process in the Web Process Designer.
2. In the editor menu, click the Connect to a Service Repository button.
3. In the Service Repository Connection window, define the location of the repository on the location input line and click Connect.
   

   Figure 4.25. Establishing connection to a service repository

4. Double-click the asset to import it.

1. Create an implementation of the UserGroupInfoProducer interface and provide your own custom callback (see Section 4.15.5.1, “Connecting to LDAP”) and user info implementations according to the needs from the producer.
   This implementation must be annotated with the @Selectable qualifier for it to be found by Business Central. The listing below shows an example LDAP implementation:

   import javax.enterprise.context.ApplicationScoped;
   import javax.enterprise.inject.Alternative;
   import javax.enterprise.inject.Produces;
   
   import org.jbpm.services.task.identity.LDAPUserGroupCallbackImpl;
   import org.jbpm.services.task.identity.LDAPUserInfoImpl;
   import org.jbpm.shared.services.cdi.Selectable;
   import org.kie.api.task.UserGroupCallback;
   import org.kie.internal.task.api.UserInfo;
   
   @ApplicationScoped
   @Alternative
   @Selectable
   public class LDAPUserGroupInfoProducer implements UserGroupInfoProducer {
   
     private UserGroupCallback callback = new LDAPUserGroupCallbackImpl(true);
     private UserInfo userInfo = new LDAPUserInfoImpl(true);
   
     @Override
     @Produces
     public UserGroupCallback produceCallback() {
       return callback;
     }
   
     @Override
     @Produces
     public UserInfo produceUserInfo() {
       return userInfo;
     }
   
   }

2. Package your custom implementations (the LDAPUserGroupInfoProducer, the LDAPUserGroupCallbackImpl and the LDAPUserInfoImpl classes from the example above) into a bean archive (jar with META-INF/beans.xml so it can be found by CDI container). Add this jar file to business-central.war/WEB-INF/lib.
3. Modify business-central.war/WEB-INF/beans.xml and add the implementation (LDAPUserGroupInfoProducer from the example above) as an alternative to be used by Business Central.

   <beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://docs.jboss.org/cdi/beans_1_0.xsd">
   
       <alternatives>
           <class>com.test.services.producer.LDAPUserGroupInfoProducer</class>
       </alternatives>
   </beans>
   

   Warning

   The use of a custom UserGroupInfoProducer requires internal APIs, which may be broken in future releases. Using a custom UserGroupInfoProducer is not recommended or supported by Red Hat.
4. Restart your server and your custom callback implementation should now be used by Business Central.

1. On the top menu of the Business Central, go to Process Management → Process Instances.
2. In the list on the Process Instances tab, click the button.
   The New Process Instance List dialog box opens.
3. In the New Process Instance List dialog box:
   1. Provide the name and description for your search process instance list in the Labels tab.
   2. Click the Filter tab to create new query filter.
      1. Click Add New.
      2. From the list of filter values, select CORRELATIONKEY. If you want to create a search filter using partial correlationKey, select the like query operator and provide the value as partial-correlation-key% where partial-correlation-key is the value you are searching for.
      3. Click Ok.
   A new tab is created that displays your custom process instance list.

1. On the top menu of the Business Central, go to Process Management → Process Instances.
2. In the list on the Process Instances tab, click the button. The New Process Instance List dialog box opens.
3. In the New Process Instance List dialog box, perform the following:
   1. Provide the name and description for your search process instance list in the Labels tab.
   2. Add a new query filter in the Filter tab:
      1. Click Add New.
      2. From the list of filter values, select processId and equalsTo.
      3. Provide a valid processId value and click Ok.
   A new tab is created that displays your custom process instance list in a tabular form. This new tab provides process instance variables (business data) as selectable columns. You can view the variables corresponding to each process instance in the table by enabling these columns, which are disabled by default.

1. In the Tree Menu (the panel in the lateral menu of the Showcase workspace), click Administration → Data providers.
2. In the Data Providers panel, click the Create new data provider button.
3. In the updated Data Providers panel, select in the Type dropdown menu the type of the data provider depending on the source you want the data provider to operate on.
4. Define the data provider parameters:

   Data provider over a CSV file

   • Name: user-friendly name and its locale
   • CSV file URL: the url of the file (for example, file:///home/me/example.csv)
   • Data separator: the symbol used as separator in the CSV file (the default value is semicolon; if using comma as the separator sign, make sure to adapt the number format if applicable)
   • Quoting symbol: the symbol used for quotes (the default value is the double-quotes symbol; note that the symbol may vary depending on the locale)
   • Escaping symbol: the symbol used for escaping the following symbol in order to keep its literal value
   • Date format: date and time format
   • Number format: the format of numbers as resolved to thousands and decimals

   Data provider over a database (SQL query)

   • Name: user-friendly name and its locale
   • Data source: the data source to query (the default value is local, which allows you to query the Dashboard Builder database)
   • Query: query that returns the required data

5. Click Attempt data load to verify the parameters are correct.
6. Click Save.
7. In the table with the detected data, define the data type and if necessary provide a user-friendly name for the data. Click Save.