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

  1. Open the command line and create a directory where you will build your work item handler such as workitem-home: 

    $ mkdir workitem-home

  2. Check the Maven settings.xml file and ensure that the Red Hat Maven repository is included in the repository list.

    Note

    Setting up Maven is outside the scope of this guide.

    For example, to add the online Red Hat Maven repository to your Maven settings.xml file: 

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

  3. Find the Red Hat library version and perform one of the following tasks:

  4. In the workitem-home directory, 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

    ParameterDescription

    -DarchetypeGroupId

    Specific to the archetype and must remain unchanged.

    -DarchetypeArtifactId

    Specific to the archetype and must remain unchanged.

    -DarchetypeVersion

    Red Hat library version that is searched for when Maven attempts to download the jbpm-workitems-archetype artifact.

    -Dversion

    Version of your specific project. For example, 1.0.0-SNAPSHOT.

    -DgroupId

    Maven group of your specific project. For example, com.redhat.

    -DartifactId

    Maven ID of your specific project. For example, myworkitem.

    -DclassPrefix

    String added to the beginning of Java classes when Maven generates the classes for easier identification. For example, MyWorkItem.

    A myworkitem folder is created in the workitem-home directory. 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

  5. Perform the following two items as a workaround for an active bug in the archetype when building artifacts from the generated project:

    • Edit the pom.xml file to remove or comment out the following dependency: 

      <dependency>
  <groupId>org.jbpm</groupId>
  <artifactId>jbpm-workitems-core</artifactId>
  <type>test-jar</type>
  <scope>test</scope>
</dependency>

    • Include the -Dmaven.test.skip=true variable when executing Maven builds. For example, $ mvn clean package -Dmaven.test.skip=true.

      Note

      This is generally not recommended but is necessary to workaround the bug. For more information about the bug, see Generating Maven jbpm-workitems-archetype fails due to missing "tests" jar.

  6. Add any Maven dependencies required by the work item handler class to the pom.xml file.

  7. 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 -Dmaven.test.skip=true

    Several files are created in the target/ directory which include the following two main files:

    Table 2.2. File descriptions

    ParameterDescription

    myworkitems-<version>.jar

    Used for direct deployment to Red Hat Process Automation Manager.

    myworkitems-<version>.zip

    Used for deployment using a service repository.