How to Embed a jBPM Process in a Java EE Application

BPMS, Without a Dedicated Server

If you want process management without a standalone server, then you can..

Embed JBPM in Your Application

You can use the JBPM APIs to run your processes directly from your java code.

What You’ll Need

1. JBoss Developer Studio w/ JBoss EAP 7.1+ Download here
2. JBoss Maven Repositories (Section 1: Steps 4-7)
3. Basic Maven and EJB knowledge

Build a KJAR

1. Download and import the simple-process-starter project
   • It’s a bare java 1.8 maven project
2. Change packaging to kjar
   • In your pom.xml, add the jbpm version between the property tags
     

     
     

     Java

      

     
     

     
     

     
     

     
     

     x

     
     

     
     

      

     1

     <jbpm.version>7.11.0.Final-redhat-00004</jbpm.version>

     
     

     
     
   • Add the kie maven plugin in between the build tags
     

     
     

     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     15

     
     

     
     

      

     1

     <plugins>

     2

         <plugin>

     3

             <groupId>org.kie</groupId>

     4

             <artifactId>kie-maven-plugin</artifactId>

     5

             <version>${jbpm.version}</version>

     6

             <extensions>true</extensions>

     7

             <dependencies>

     8

                 <dependency>

     9

                     <groupId>org.jbpm</groupId>

     10

                     <artifactId>jbpm-bpmn2</artifactId>

     11

                     <version>${jbpm.version}</version>

     12

                 </dependency>

     13

             </dependencies>

     14

         </plugin>

     15

     </plugins>

     
     

     
     
   • Change packaging to kjar (a package structure for workflow files)
     

     
     

     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     <packaging>kjar</packaging>

     
     

     
     
3.  Add a kmoduledescriptor
   • In src/main/resources/META-INF, create a file called kmodule.xml with the following:
     

     
     

     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     <kmodule xmlns="http://jboss.org/kie/6.0.0/kmodule" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

     
     

     
     
4. Add a sample process
   • Create the folder src/main/resources/com/sample
   • Unzip this and copy the process (the bpmn file) into that folder 
   • If you want to view the process diagram, download the BPM eclipse plugin. I’m using v1.4.3
5. Build & Deploy to Maven Repo
   • Right click your project -> Run as -> Maven Build. In the goals section, type..
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     clean install

     
     

     
     

Run an Embedded Process

1. Download and import the embedded-process-starter project
   • It’s a single page web application. After we’re done, we’ll be able to start a process with one click.
   • The pom.xml contains dependencies for running a jBPM process.
   • The persistence.xml contains standard objects and queries for jBPM
2. Deploy the KJAR
   • Open the StartupBean class. It’s an EJB that runs at startup (@Startup)
   • Inside this class, declare a DeploymentService EJB
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     @EJB

     2

     DeploymentServiceEJBLocal deploymentService;

     
     

     
     
   • In the init() method, deploy the kjar we just built.
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     String[] gav = DEPLOYMENT_ID.split(":"); // Splits into group, artifact, and version 

     2

     3

     DeploymentUnit deploymentUnit = new KModuleDeploymentUnit(gav[0], gav[1], gav[2]);

     4

     5

     deploymentService.deploy(deploymentUnit);

     
     

     
     
   • The group, artifact and version specify which artifact we want to deploy
3.  Start the process
   • In ProcessServlet, declare a ProcessorService EJB
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     @EJB

     2

     private ProcessServiceEJBLocal processService;

     
     

     
     
   • In doPost(), add code to start our process
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     long processInstanceId = -1;

     2

     Map<String, Object> params = new HashMap<String, Object>();

     3

     processInstanceId = processService.startProcess(StartupBean.DEPLOYMENT_ID, "com.sample.bpmn.hello", params);

     4

     5

     System.out.println("Process instance " + processInstanceId + " has been successfully started.");

     
     

     
     
4. Build and deploy to JBoss
   • Right-click your project -> Run as -> Maven Build.
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     Goals: clean install

     
     

     
     
   • Deploy using Method 1 here. If you’re on EAP 7, be sure to start your server with the full profile:
     Java

      

     
     

     
     

     
     

     
     

     xxxxxxxxxx

     1

     
     

     
     

      

     1

     ./standalone.sh --server-config=standalone-full.xml

     
     

     
     
5. Start a process
   • Go to http://localhost:8080/simple-embedded-process/
   • Click “Start Process”
   • Check the logs. You should see “Hello World!”

Recap

Build a kjar

1. We created a kjar with our sample process and deployed it to maven
   • KJAR (knowledge jar) –  a packaged artifact of all our business rules & process files
   • kie-maven-plugin – a plugin to compile our processes & create the kjar
   • kmodule – a kjar descriptor

Run an Embedded process

1. We declared a DeploymentService to deploy our process.
   • The group, artifact, and version (GAV) specify the package to deploy.
2. We used ProcessService to start our process.
   • com.sample.bpmn.hello is the processId
   • When we click “Start Process” on our webpage, it starts this flow. See below
3. Our sample process has a Script Task that prints out “Hello World”

Best Practices for Embedded jBPM

Keep your workflow files (processes, rules) in a separate project from your application code. This will make it easy to change your code & workflows independently.

And, if possible, use JBoss BPM Suite for a centralized repo solution instead of embedding jBPM in your application.