Custom tasks and work item handlers in Business Central
Abstract
Preface
As a business rules developer, you can create custom tasks and work item handlers in Business Central to execute custom code within your process flows and extend the operations available for use in Red Hat Process Automation Manager. You can use custom tasks to develop operations that Red Hat Process Automation Manager does not directly provide and include them in process diagrams.
In Business Central, each task in a process diagram has a WorkItem Java class with an associated WorkItemHandler Java class. The work item handler contains Java code registered with Business Central and implements org.kie.api.runtime.process.WorkItemHandler.
The Java code of the work item handler is executed when the task is triggered. You can customize and register a work item handler to execute your own Java code in custom tasks.
Prerequisites
- Business Central is deployed and is running on a web or application server.
- You are logged in to Business Central.
- Maven is installed.
- The host has access to the Internet. The build process uses the Internet for downloading Maven packages from external repositories.
- Your system has access to the Red Hat Maven repository either locally or online
Chapter 1. Managing service tasks in Business Central
Service tasks (work items) are tasks that you can customize and reuse across multiple business processes or across all projects in Business Central. Red Hat Process Automation Manager provides a set of service tasks within the service task repository in Business Central. You can enable or disable the default service tasks and upload custom service tasks into Business Central to implement the tasks in the relevant processes.
Red Hat Process Automation Manager includes a limited set of supported custom tasks. Custom tasks that are not included in Red Hat Process Automation Manager are not supported.
Procedure
In Business Central, click
in the upper-right corner and select Service Tasks Administration.
This page lists the service task installation settings and available service tasks for processes in projects throughout Business Central. The service tasks that you enable on this page become available in the project-level settings where you can then install each service task to be used in processes. The way in which the service tasks are installed in a project is determined by the global settings that you enable or disable under Settings on this Service Tasks Administration page.
Under Settings, enable or disable each setting to determine how the available service tasks will be implemented when a user installs them at the project level.
The following service task settings are available:
- Install as Maven artifact: Uploads the service task JAR file to the Maven repository that is configured with Business Central, if the file is not already present.
-
Install service task dependencies into project: Adds any service task dependencies to the
pom.xmlfile of the project where the task is installed. -
Use version range when installing service task into project: Uses a version range instead of a fixed version of a service task that is added as a project dependency. Example:
[7.16,)instead of7.16.0.Final
Enable or disable (set to ON or OFF) any available service tasks as needed. Service tasks that you enable will be displayed in project-level settings for all projects in Business Central.
Figure 1.1. Enable service tasks and service task settings
-
To add a custom service task, click Add Service Task, browse to the relevant JAR file, and click the Upload icon. The JAR file must contain work item handler implementations annotated with
@Wid. - Optionally, to remove a service task, click remove on the row of the service task you want to remove and click Ok to confirm removal.
- After you configure all required service tasks, navigate to a project in Business Central and go to the project Settings → Service Tasks page to view the available service tasks that you enabled.
- For each service task, click Install to make the task available to the processes in that project or click Uninstall to exclude the task from the processes in the project.
If you are prompted for additional information when you install a service task, enter the required information and click Install again.
The required parameters for the service task depend on the type of task. For example, rule and decision tasks require artifact GAV information (Group ID, Artifact ID, Version), email tasks require host and port access information, and REST tasks require API credentials. Other service tasks might not require any additional parameters.
Figure 1.2. Install service tasks for use in processes
- Click Save.
Return to the project page, select or add a business process in the project, and in the process designer palette, select the Service Tasks option to view the available service tasks that you enabled and installed:
Figure 1.3. Access installed service tasks in process designer
Chapter 2. Creating work item handler projects
Create the software project to contain all configurations, mappings, and executable code for the custom task.
You can create a work item handler from scratch or use a Maven archetype to create an example project. Red Hat Process Automation Manager provides the jbpm-workitems-archetype from the Red Hat Maven repository for this purpose.
Procedure
Open the command line and create a directory where you will build your work item handler such as
workitem-home:$ mkdir workitem-home
Check the Maven
settings.xmlfile and ensure that the Red Hat Maven repository is included in the repository list.NoteSetting up Maven is outside the scope of this guide.
For example, to add the online Red Hat Maven repository to your Maven
settings.xmlfile:<settings> <profiles> <profile> <id>my-profile</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <repository> <id>redhat-ga</id> <url>http://maven.repository.redhat.com/ga/</url> <snapshots> <enabled>false</enabled> </snapshots> <releases> <enabled>true</enabled> </releases> </repository> ... </repositories> </profile> </profiles> ... </settings>Find the Red Hat library version and perform one of the following tasks:
- To find the library version online, see What is the mapping between Red Hat Process Automation Manager and the Maven library version?.
-
To find the library version offline, check
Implementation-Versioninbusiness-central.war/META-INF/MANIFEST.MForImplementation-Versioninkie-server.war/META-INF/MANIFEST.MF.
In the
workitem-homedirectory, execute the following command:$ mvn archetype:generate \ -DarchetypeGroupId=org.jbpm \ -DarchetypeArtifactId=jbpm-workitems-archetype \ -DarchetypeVersion=<redhat-library-version> \ -Dversion=1.0.0-SNAPSHOT \ -DgroupId=com.redhat \ -DartifactId=myworkitem \ -DclassPrefix=MyWorkItem
Table 2.1. Parameter descriptions
Parameter Description -DarchetypeGroupIdSpecific to the archetype and must remain unchanged.
-DarchetypeArtifactIdSpecific to the archetype and must remain unchanged.
-DarchetypeVersionRed Hat library version that is searched for when Maven attempts to download the
jbpm-workitems-archetypeartifact.-DversionVersion of your specific project. For example,
1.0.0-SNAPSHOT.-DgroupIdMaven group of your specific project. For example,
com.redhat.-DartifactIdMaven ID of your specific project. For example,
myworkitem.-DclassPrefixString added to the beginning of Java classes when Maven generates the classes for easier identification. For example,
MyWorkItem.A
myworkitemfolder is created in theworkitem-homedirectory. For example:assembly/ assembly.xml src/ main/ java/ com/ redhat/ MyWorkItemWorkItemHandler.java repository/ resources/ test/ java/ com/ redhat/ MyWorkItemWorkItemHandlerTest.java MyWorkItemWorkItemIntegrationTest.java resources/ com/ redhat/ pom.xml-
Add any Maven dependencies required by the work item handler class to the
pom.xmlfile. To create a deployable JAR for this project, in the parent project folder where the pom.xml file is located, execute the following command:
$ mvn clean package
Several files are created in the
target/directory which include the following two main files:Table 2.2. File descriptions
Parameter Description myworkitems-<version>.jarUsed for direct deployment to Red Hat Process Automation Manager.
myworkitems-<version>.zipUsed for deployment using a service repository.
Chapter 3. Work item handler project customization
You can customize the code of a work item handler project. There are two Java methods required by a work item handler, executeWorkItem and abortWorkItem.
Table 3.1. Java method descriptions
| Java Method | Description |
|---|---|
|
| Executed by default when the work item handler is run. |
|
| Executed when the work item is aborted. |
In both methods, the WorkItem parameter contains any of the parameters entered into the custom task through a GUI or API call, and the WorkItemManager parameter is responsible for tracking the state of the custom task.
Example code structure
public class MyWorkItemWorkItemHandler extends AbstractLogOrThrowWorkItemHandler {
public void executeWorkItem(WorkItem workItem, WorkItemManager manager) {
try {
RequiredParameterValidator.validate(this.getClass(), workItem);
// sample parameters
String sampleParam = (String) workItem.getParameter("SampleParam");
String sampleParamTwo = (String) workItem.getParameter("SampleParamTwo");
// complete workitem impl...
// return results
String sampleResult = "sample result";
Map<String, Object> results = new HashMap<String, Object>();
results.put("SampleResult", sampleResult);
manager.completeWorkItem(workItem.getId(), results);
} catch(Throwable cause) {
handleException(cause);
}
}
@Override
public void abortWorkItem(WorkItem workItem, WorkItemManager manager) {
// similar
}
}
Table 3.2. Parameter descriptions
| Parameter | Description |
|---|---|
|
|
Checks that all parameters marked “required” are present. If they are not, an |
|
|
Example of getting a parameter from the |
|
| Executes the custom Java code when a parameter is received. |
|
| Passes results to the custom task. The results are placed in the data output areas of the custom task. |
|
|
Marks the work item handler as complete. The |
|
| Aborts the custom Java code. May be left blank if the work item is not designed to be aborted |
Red Hat Process Automation Manager includes a limited set of supported custom tasks. Custom tasks that are not included in Red Hat Process Automation Manager are not supported.
Chapter 4. Work item definitions
Red Hat Process Automation Manager requires a work item definition (WID) file to identify the data fields to show in Business Central and accept API calls. The WID file is a mapping between user interactions with Red Hat Process Automation Manager and the data that is passed to the work item handler. The WID file also handles the UI details such as the name of the custom task, the category it is displayed as on the palette in Business Central, the icon used to designate the custom task, and the work item handler the custom task will map to.
In Red Hat Process Automation Manager you can create a WID file in two ways:
-
Use a
@Widannotation when coding the work item handler. -
Create a
.widtext file. For example,definitions-example.wid.
4.1. @Wid Annotation
The @Wid annotation is automatically created when you generate a work item handler project using the Maven archetype. You can also add the annotation manually.
@Wid Example
@Wid(widfile="MyWorkItemDefinitions.wid",
name="MyWorkItemDefinitions",
displayName="MyWorkItemDefinitions", icon="",
defaultHandler="mvel: new
com.redhat.MyWorkItemWorkItemHandler()",
documentation = "myworkitem/index.html",
parameters={
@WidParameter(name="SampleParam", required = true),
@WidParameter(name="SampleParamTwo", required = true)
}, results={
@WidResult(name="SampleResult")
},
mavenDepends={
@WidMavenDepends(group="com.redhat",
artifact="myworkitem",
version="7.26.0.Final-example-00004")
},
serviceInfo={
@WidService(
category = "myworkitem",
description = "${description}",
keywords = "",
action = @WidAction(title = "Sample Title"),
authinfo = @WidAuth(required = true, params = {"SampleParam", "SampleParamTwo"},
paramsdescription = {"SampleParam", "SampleParamTwo"},
referencesite = "referenceSiteURL")
)
}
)
Table 4.1. @Wid descriptions
| Description | |
|---|---|
|
| Top-level annotation to auto-generate WID files. |
|
| Name of the file that is automatically created for the custom task when it is deployed in Red Hat Process Automation Manager. |
|
| Name of the custom task, used internally. This name must be unique to custom tasks deployed in Red Hat Process Automation Manager. |
|
| Displayed name of the custom task. This name is displayed in the palette in Business Central. |
|
|
Path from |
|
| Description of the custom task. |
|
|
The work item handler Java class that is linked to the custom task. This entry is in the format |
|
| Path to an HTML file in the current project that contains a description of the custom task. |
|
|
Child annotation of
Note Due to the possibility of this name being used in API calls over transfer methods such as REST or SOAP, this name should not contain spaces or special characters.
|
|
|
Child annotation of
Note Due to the possibility of this name being used in API calls over transfer methods such as REST or SOAP, this name should not contain spaces or special characters.
|
|
|
Child annotation of
|
|
|
Object of
|
|
|
Object of
|
4.2. Text File
A global WorkDefinitions WID text file is automatically generated by new projects when a business process is added. The WID text file is similar to the JSON format but is not a completely valid JSON file. You can open this file in Business Central. You can create additional WID files by selecting Add Asset > Work item definitions from an existing project.
Text file example
[
[
"name" : "MyWorkItemDefinitions",
"displayName" : "MyWorkItemDefinitions",
"category" : "",
"description" : "",
"defaultHandler" : "mvel: new com.redhat.MyWorkItemWorkItemHandler()",
"documentation" : "myworkitem/index.html",
"parameters" : [
"SampleParam" : new StringDataType(),
"SampleParamTwo" : new StringDataType()
],
"results" : [
"SampleResult" : new StringDataType()
],
"mavenDependencies" : [
"com.redhat:myworkitem:7.26.0.Final-example-00004"
],
"icon" : ""
]
]
The file is structured as a plain-text file using a JSON-like structure. The filename extension is .wid.
Table 4.2. Text file descriptions
| Description | |
|---|---|
|
| Name of the custom task, used internally. This name must be unique to custom tasks deployed in Red Hat Process Automation Manager. |
|
| Displayed name of the custom task. This name is displayed in the palette in Business Central. |
|
|
Path from |
|
| Name of a category within the Business Central palette under which this custom task is displayed. |
|
| Description of the custom task. |
|
|
The work item handler Java class that is linked to the custom task. This entry is in the format |
|
| Path to an HTML file in the current project that contains a description of the custom task. |
|
|
Specifies the values to be populated in the Business Central GUI or expected by API calls as data inputs for the custom task. Parameters use the |
|
|
Specifies the values to be populated in the Business Central GUI or expected by API calls as data outputs for the custom task. Results use the |
|
|
Optional: Specifies Maven dependencies required for the correct functioning of the work item handler. Dependencies can also be specified in the work item handler |
Red Hat Process Automation Manager tries to locate a *.wid file in two locations by default:
-
Within Business Central in the project’s top-level
global/directory. This is the location of the defaultWorkDefinitions.widfile that is created automatically when a project first adds a business process asset. -
Within Business Central in the project’s
src/main/resources/directory. This is where WID files created within a project in Business Central will be placed. A WID file may be created at any level of a Java package, so a WID file created at a package location of<default>will be created directly insidesrc/main/resources/while a WID file created at a package location ofcom.redhatwill be created atsrc/main/resources/com/redhat/
Red Hat Process Automation Manager does not validate that the value for the defaultHandler tag is executable or is a valid Java class. Specifying incorrect or invalid classes for this tag will return errors.
Chapter 5. Deploying custom tasks
Work item handlers, as custom code, are created outside of Red Hat Process Automation Manager. To use the code in your custom task, the code must be deployed to the server. Work item handler projects must be Java JAR files that can be placed into a Maven repository.
In Red Hat Process Automation Manager you can deploy custom tasks using three methods:
- Within a Business Central service task repository. For more information, see Chapter 1, Managing service tasks in Business Central.
- Within Business Central where you can use both the legacy and current editors to upload the work item handler JAR to the Business Central Maven repository as an artifact.
- Outside of Business Central, you can manually copy the JAR files into the Maven repository.
5.1. Using a Business Central service task repository
You can enable, disable, and deploy service tasks within a Business Central service task repository. For more information, see Chapter 1, Managing service tasks in Business Central.
5.2. Uploading JAR Artifact to Business Central
You can upload the work item handler JAR to the Business Central Maven repository as an artifact by using the legacy and current editors.
Procedure
- In Business Central, select the Admin icon in the top-right corner of the screen and select Artifacts.
- Click Upload.
- In the Artifact Upload window, click the Choose File icon.
- Navigate to the location of the work item handler JAR, select the file and click Open.
In the pop-up dialog, click the Upload icon.
The artifact is uploaded and can now be viewed on the Artifacts page and referenced.
5.3. Manually copying work item definitions to Business Central Maven repository
Business Central automatically creates or reuses the Maven repository folder. By default the location is based on the location of the user launched Red Hat JBoss EAP. For example, the full default path would be <startup location>/repositories/kie/global. It is possible to replicate a standard Maven repository folder layout of <groupId>/<artifactId>/<versionId>/ in this folder and copy work item handler JAR files to this location. For example:
<startup location>/repositories/kie/global/com/redhat/myworkitem/1.0.0-SNAPSHOT/myworkitems-1.0.0-SNAPSHOT.jar
Any artifacts copied in this fashion are available to Red Hat Process Automation Manager without a server restart. Viewing the artifact in the Business Central Artifacts page requires clicking Refresh.
Chapter 6. Registering custom tasks
Red Hat Process Automation Manager must know how to associate a custom task work item with the code executed by the work item handler. The work item definition file links the custom task with the work item handler by name and Java class. The work item handler’s Java class has to be registered as usable in Red Hat Process Automation Manager.
Service repositories contain domain-specific services that provide integration of your processes with different types of systems. Registering a custom task is not necessary when using a service repository because the import process registers the custom task.
Red Hat Process Automation Manager creates a WID file by default for projects that contain at least one business process. You can create a WID file when registering a work item handler or edit the default WID file. For more information about WID file locations or formatting, see Chapter 4, Work item definitions.
For non-service repository deployments, work item handlers can be registered in two ways:
- Registering using the deployment descriptor.
- Registering using the spring component registration.
6.1. Registering custom tasks using the deployment descriptor inside Business Central
You can register a custom task work item with the work item handler using the deployment descriptor in Business Central.
Procedure
- In Business Central, go to Menu → Design → Projects and select the project name.
- In the project pane, select Settings → Deployments → Work Item Handlers.
- Click Add Work Item Handler.
- In the Name field, enter the display name for the custom task.
- From the Resolver list, select MVEL, Reflection or Spring.
In the Value field, enter the value based on the resolver type:
For MVEL, use the format
new <full Java package>.<Java work item handler class name>()Example:
new com.redhat.MyWorkItemWorkItemHandler()For Reflection, use the format
<full Java package>.<Java work item handler class name>Example:
com.redhat.MyWorkItemWorkItemHandlerFor Spring, use the format
<Spring bean identifier>Example:
workItemSpringBean
- Click Save to save your changes
6.2. Registering custom tasks using the deployment descriptor outside Business Central
You can register a custom task work item with the work item handler using the deployment descriptor outside Business Central.
Procedure
-
Open the file
src/main/resources/META-INF/kie-deployment-descriptor.xml. Add the following content based on the resolver type under
<work-item-handlers>:For MVEL, add the following:
<work-item-handler> <resolver>mvel</resolver> <identifier>new com.redhat.MyWorkItemWorkItemHandler()</identifier> <parameters/> <name>MyWorkItem</name> </work-item-handler>
For Reflections, add the following:
<work-item-handler> <resolver>reflection</resolver> <identifier>com.redhat.MyWorkItemWorkItemHandler</identifier> <parameters/> <name>MyWorkItem</name> </work-item-handler>
For Spring, add the following and ensure the identifier is the identifier of a Spring bean:
<work-item-handler> <resolver>spring</resolver> <identifier>beanIdentifier</identifier> <parameters/> <name>MyWorkItem</name> </work-item-handler>
NoteIf you are using Spring to discover and configure Spring beans, it is possible to use an annotation of the
org.springframework.stereotype.Componentclass to automatically register work item handlers.Within a work item handler, add the annotation
@Component("<Name>")before the declaration of the work item handler class. For example:@Component("MyWorkItem") public class MyWorkItemWorkItemHandler extends AbstractLogOrThrowWorkItemHandler {
Chapter 7. Placing custom tasks
When a custom task is registered in Red Hat Process Automation Manager it appears in the process designer palette. The custom task is named and categorized according to the entries in its corresponding WID file.
Prerequisites
- A custom task is registered in Red Hat Process Automation Manager. For information about registering custom tasks, see Chapter 6, Registering custom tasks.
- The custom task is named and categorized according to the corresponding WID file. For more information about WID file locations or formatting, see Chapter 4, Work item definitions.
Procedure
- In Business Central, go to Menu → Design → Projects and click a project.
- Select the business process that you want to add a custom task to.
- Select the custom task from the palette and drag it to the BPMN2 diagram.
- Optional: Change the custom task attributes. For example, change the data output and input from the corresponding WID file.
If the WID file is not visible in your project and no Work Item Definition object is visible in the Others category of your project, you must register the custom task. For more information about registering a custom task, see Chapter 6, Registering custom tasks.
Appendix A. Versioning information
Documentation last updated on Thursday, September 08, 2020.