Extend Red Hat JBoss BPM Suite through the Service Repository

Introduction

Red Hat JBoss BPM Suite offers a really flexible BPMN engine that can be extended with Custom Reusable Services. Most users know them as Work Item Handler (the technical implementation name), but few of them know that it's possible to expose them in a comfortable list of reusable services. In fact, you can create a repository of services and simplify the life of the BPMN designer that can easily pick and choose the right service.

Another advantage of this approach is that the BPM designer hasn't had to get down to the nitty-gritty of the configuration, because the import procedure addresses almost everything for you, so you need to focus on consuming the service through a clean interface.
To make the magic happen, the service developer has to prepare the service repository. In doing that you enable the rest of the organization to reuse your work item handlers in a simple and clear manner. But even if the service developer is not planning to share these services across the organization, they can leverage the service repository to simplify the work item handler installation across the internal team.

The Service Repository

Creating a new service (Work Item Handler) in a BPM project requires the BPM designer to tinker with at least three configuration files:

• kie-deployment-descriptor.xml defines how to instantiate the Work Item Handler class
• WorkDefinitions.wid the service interface and the icon used in the BPMN editor
• pom.xml where to add the dependency for Work Item Handler project
• Optionally the icon

You could argue that even creating the repository structure requires some care, but the great benefit is that this effort is done once and reused across multiple projects. The service provider manages many configuration details while the service consumer can disregard them.

The Service Repository is basically a static directory structure that can be served through an HTTP server, or a plain file system accessible by the Business Central.

You can see this simple structure in the following picture:

At the root there is:

• the file index.conf
• a folder for each service

The index.conf contains the list of folders (the name MUST match exactly the folder name).
Each folder contains:

• <service-name>.wid that contains the juice of the service definition; <service-name> MUST match exactly the containing folder name
• Optionally, a png file containing an icon for the service, it MUST match the definition in the previous file
• Optionally, an index.html that documents the service usage

Here a sample of a github project containing a service repository.

The core is the .wid file contained in the folders:

https://gist.github.com/dmarrazzo/1b9c5e1e6696a957a4e8c6b3b298dcdd

The content is pretty straight forward:

1. name: of the work item handler that implements the service
2. description: a service description
3. parameters: the input parameters
4. results: the service outputs
5. displayName: the name of the task when used in the BPMN diagram
6. icon: the icon of the service
7. category: a category that is used to group the services in the BPMN editor palette
8. defaultHandler: a mvel expression to instantiate the Work Item Handler class (the constructor with the paramerters). Be aware that you can leverage some variables available in this context: ksession and classLoader
9. documentation: to point to the documentation html file
10. mavenDependencies: the maven dependencies using the GAV convention
11. dependencies: optional dependencies to jar files included in the repository

The Service Consumer

From the user point of view, consuming a service is easy:

1. Open the BPMN editor and click on the Service Repository icon:
   
2. Select the service you need by clicking on the corresponding wrench icon:
   
3. Close and open again the BPMN editor to reload the service palette
4. Drag and drop your new service:
   

Conclusion

Sharing a Service in a repository encourages the reuse and clarifies the separation of roles between the process designer and the service developer.
Red Hat JBoss BPM Suite promotes this good practice.