Users Guide - redhat-consulting/jbpm-ee GitHub Wiki

###Introduction###

This document covers installation and usage of the JBoss Business Process Management Enterprise Edition (jBPM-EE) service layer. This report provides an overview of the service layer, which can be scaled and modified to handle your current and future enterprise project needs.  

There are five topics which Red Hat will cover in this report

  • Design
  • Installation
  • Application Development
  • Deployment
  • Design and Development

The jBPM-EE Project is split up into a number of sub-projects:

jbpm-ee-client – Classes and Interfaces for interacting with the jbpm-ee-services

  • local – Interfaces for local EJB
  • remote – Interfaces for remote EJB
  • ws – Interfaces for SOAP and REST

jbpm-ee-services – EJB, REST, SOAP, and JMS services that interact with the underlying jBPM framework 

jbpm-ee-samples - Sample projects demonstrating the functionality that is offered by jBPM-EE

jbpm-ee-archetypes – Template projects for interacting with the jbpm-ee-services

'test' projects – Used in testing jbpm-ee, can be ignored

jBPM-EE is designed around a set of EJB 3.1 Singleton, Stateless, and Message Driven beans. The REST and SOAP interfaces wrap these EJBs and share their interfaces. 

###2.1 Singleton EJBs###

The Singleton EJBs are the most important aspects of the jbpm-ee-services project. Together, they handle important details such as setting up external resources, interacting with the underlying jBPM framework, dynamically loading classes from deployed kjars. Client applications will not need to interact with these services, however, depending on application requirements, the ResourceManagementBean will need to be modified in cases where jBPM-EE will need to interact with LDAP.

###2.2 Stateless EJBs###

All service interfaces are implemented by Stateless EJBs, available in org.jbpm.ee.services.ejb.impl. They may be accessed via their local and remote interfaces available in org.jbpm.ee.services.ejb.local or remote, depending on the deployment strategy. Full descriptions are available in the Javadocs.

  • ProcessService – Start, abort, and signal processes
  • RuleService – Insert facts and set rules to fire
  • TaskService – List, Claim, Start, and Complete tasks

###2.3 Message Driven Bean (JMS)###

jBPM-EE extends the existing jBPM Command Service in a clusterable, fault tolerant fashion using JMS. It is based on, but not dependent on, the BRMS 6.0 KIE-WorkBench JMS implementation.

To simplify interacting with JMS, jBPM-EE provides an of EJB interfaces that handles sending a command and polling for a response, if one will be sent. They may be accessed via their local and remote interfaces available in org.jbpm.ee.services.ejb.local or remote, depending on the deployment strategy.  

The command objects utilized by the jBPM Command Service are available in the kie.api.command and org.jbpm.services.task.commands packages. For best results, Red Hat suggests utilizing only the commands that mimic the ProcessService, RuleService, and TaskService interfaces. Not all commands have been tested this time. 

###2.4 REST/SOAP###

REST/SOAP interfaces are available in org.jbpm.ee.client through their respective factories. They extend the same interfaces as the EJBs.

###2.5 Changes for Production###

At time of writing, jBPM-EE is based off jBPM Community Release 6.0.0.Final. Red Hat supported production binaries are expected in the future, but an exact timeline is not available. jBPM-EE is expected to require few or no changes when supported binaries become available. 

###3. Installation###

####3.1 Environment Setup####

Please refer to the jBPM-EE project setup guide. It will walk you through downloading the jBPM-EE sources, setting up JBoss Developer Studio (JBDS), and setting up development databases.

####3.2 jBPM-EE Installation####

Prior to deploying jBPM-EE artifacts on JBoss or other containers, such as GlassFish, jBPM-EE must first be compiled, packaged, and installed.

Please Refer to Tutorial 1 and Tutorial 2 for installation and configuration information.

After you have competed the Tutorials, your maven repository will contain jBPM-EE project artifacts and their dependencies.

####4.1 Apache Maven####

All jBPM-EE projects utilize Apache Maven for compilation and dependency management. Red Hat recommends using Maven for all client application development to simplify dependency management. 

#####4.1.1 Deployment Considerations#####

Utilizing the existing archetypes simplifies initial project creation substantially. However, it’s important to consider how the final application will be deployed. In all cases, jbpm-ee-services.war must be deployed in a container supporting JPA, EJBs, JAX-RS, and JAX-WS, such as JBoss.

  • Same JVM: Create an EAR project (use custom-application-local-ear as an example). Note that Maven creates ‘skinny’ wars and uses a single lib folder in the EAR for all project dependencies. Projects would depend upon jbpm-ee-client-local. 
  • Separate JVM: Use Remote EJB, REST, or SOAP interfaces, depending on requirements. Projects would depend upon jbpm-ee-client-remote or jbpm-ee-client-ws.

####4.2 KJAR and ReleaseId####

jBPM has the concept of a kjar, which is a jar containing the Java classes, processes, rules, human task forms, and deployment configuration. jBPM requires the kjar be loaded before any resource it contains can be utilized. In jBPM-EE, the kjar is identified by its Maven information, its GroupId, ArtifactId, and Version. This is the kjar’s ReleaseId.

jBPM-EE expects the kjar to be accessible via Maven, locally or remotely. 

####4.3 Special Handling for EJBs####

There are cases where Java object definitions might only exist in deployed kjars. To ensure the kjar is loaded prior to deserializing these Java objects, all interfaces lazy load parameters. EJBs require a client side interceptor to enable this behavior.

The application, on start-up will need to register the interceptor with JBoss using the following code:

import org.jbpm.ee.services.ejb.interceptors.SerializationInterceptor;
...
static{
    EJBClientContext.getCurrent().registerInterceptor(0, new SerializationInterceptor());
}

The EJB interceptor, should be statically defined (or defined as a singleton for the application. An example of this may be found in the custom-application-remote project under org.jbpm.ee.test.BaseTest.

####4.4 Starting a Process####

To start a process, the ProcessService requires kjar’s ReleaseId and the unique identifier for the process (defined within the process itself). Additionally, you may supply a Map<String, Objects> which will correspond to the process’s starting variables.  All objects passed through the Map must be serializable.

The startProcess functions return a ProcessInstance object, which details the process’s current state and its ID. The ID is used to further interact with the process.

Note:  Since jBPM-EE is a remote service, there is no functionality to modify or retrieve a running or completed process’s variables via the ProcessService. Red Hat recommends this be done via a process Service Task via a WorkItemHandler.

####4.5 Process State####

To get an updated snapshot of the process state, use ProcessService’s getProcessInstance function. A null indicates the process is no longer active, either it has been completed or aborted.

####4.6 Abort a Running Process####

Use ProcessService’s abortProcessInstance function.

####4.7 Signal a Process####

Use ProcessService’s signalProcessInstance function. Type represents the process’s event you would like to signal. Event represents the event information to be passed to the process.

####4.8 Insert Rule Facts into a Process####

Use RuleService’s insert function. 

####4.9 Set Rules to Fire####

RuleService’s fireAllRules function must be called before any rules will be fired. This signals to jBPM-EE that no more facts will be inserted into the process and to proceed with Rule Tasks.

Note: Additional facts may be inserted during a process’s Service and Script Tasks. However, fireAllRules must be called again to ensure the rule engine updates its state.

####4.10 LDAP####

The ideal situation for user group configuration for jBPM is to use LDAP. During the development of your application, a file based configuration may be used to simplify development. For more information please refer to User Group Configuration.

####4.11 Security#### jBPM-EE expects authentication to occur within the calling application. The jBPM-EE integration with LDAP is purely to resolve User and Group relationships. Therefore, any calls into jBPM which require username do not require password, since authentication is expected to occur upstream.

####5.1 Datasource####

jBPM-EE uses only JPA entities and is database agnostic. An example datasource may be found under in jbpm-ee-services/resources/jbpm-ee-ds.xml. jBPM-EE, at time of writing, expects three (3) datasources to be available with the JNDI names java:/jdbc/jbpm-main,java:/jdbc/jbpm-timers-xa, and java:/jdbc/jbpm-timers-non-xa.

For coordinated transaction support, Red Hat recommends the datasource be configured as an XA datasource. Instructions may be found in the EAP Administration and Configuration Guide.

####5.2 JMS Queue####

jBPM-EE, likewise, is JMS Queue agnostic. An example JMS configuration may be found under jbpm-ee-services/resources/jbpm-ee-jms.xml. jBPM-EE, at the time of writing, expects the queues to be available with the JNDI names jms/JBPMCommandRequestQueue as a JMS Queue and jms/JBPMCommandResponseQueue as a JMS Topic.

Instructions may be found in the EAP Administration and Configuration Guide.