JBoss.orgCommunity Documentation
Apache Maven is used by jBPM for two main purposes:
as deployment units that gets installed into runtime environment for execution
as dependency management tool for building systems based on jBPM - embedding jBPM into application
Since version 6, jBPM provides simplified and complete deployment mechanism that is based entirely on Apache Maven artifacts. These artifacts also known as kjars are simple jar files that include a descriptor for KIE system to prodice KieBase and KieSession. Descriptor of the kjar is represented as xml file named kmodule.xml and it can be:
empty to apply all defaults
custom configuration of KieBase and KieSession
<kmodule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://jboss.org/kie/6.0.0/kmodule">
</kmodule>
Empty kmodule.xml that provides all defaults for the kjar:
single default KieBase that
contains all assets from all packages
event processing mode set to - cloud
equality behaviour set to - identity
declarative agenda is disabled
scope set to - ApplicationScope - valid for CDI integrations only
single default stateless KieSession that
is bound to above (single, default) KieBase
clock type is set to - real time
scope set to - ApplicationScope - valid for CDI integrations only
single default stateful KieSession that
is bound to above (single, default) KieBase
clock type is set to - real time
scope set to - ApplicationScope - valid for CDI integrations only
All these and more can be configured manually via kmodule.xml when defaults are not enough. The complete set of elements can be found in xsd schema of kmodule.xml.
<kmodule xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://jboss.org/kie/6.0.0/kmodule">
<kbase name="defaultKieBase" default="true" eventProcessingMode="cloud" equalsBehavior="identity" declarativeAgenda="disabled" scope="javax.enterprise.context.ApplicationScoped" packages="*">
<ksession name="defaultKieSession" type="stateful" default="true" clockType="realtime" scope="javax.enterprise.context.ApplicationScoped">
<workItemHandlers>
<workItemHandler name="CustomTask" type="FQCN_OF_HANDLER" />
</workItemHandlers>
<listeners>
<listener type="FQCN_OF_EVENT_LISTENER" />
</listeners>
</ksession>
<ksession name="defaultStatelessKieSession" type="stateless" default="true" clockType="realtime" scope="javax.enterprise.context.ApplicationScoped"/>
</kbase>
</kmodule>
As illustrated on the listining above the kmodule.xml provides fliexible way of instructing the runtime engine on what and how should be configured. The example above does not present all available option but these that are most common when working with processes.
Important to note is that when using RuntimeManager, KieSession instances are created by the RuntimeManager instead of by KieContainer but kmodule.xml (or model in general) is aways used as a base of the construction process. KieBase although is always taken from KieContainer.
Kjars are represented same way as any other Maven artifact - by Group Artifact Version which is then represented as ReleaseId in KIE API. This the the only thing required to deploy kjar into runtime environment such as KIE Workbeanch.
When building systems that embed jBPM as wrokflow engine the simplest way is to configure all dependencies required by jBPM via Apache Maven. jBPM provides set of BOMs (Bill Of Material) to simplify what artifacts needs to be declared. Common way to start with integration of custom application and jBPM is to define dependency management:
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<drools.version>6.0.0.Final</drools.version>
<jbpm.version>6.0.0.Final</jbpm.version>
<hibernate.version>4.2.0.Final</hibernate.version>
<hibernate.core.version>4.2.0.Final</hibernate.core.version>
<slf4j.version>1.6.4</slf4j.version>
<jboss.javaee.version>1.0.0.Final</jboss.javaee.version>
<logback.version>1.0.9</logback.version>
<h2.version>1.3.161</h2.version>
<btm.version>2.1.4</btm.version>
<junit.version>4.8.1</junit.version>
</properties>
<dependencyManagement>
<dependencies>
<!-- define drools BOM -->
<dependency>
<groupId>org.drools</groupId>
<artifactId>drools-bom</artifactId>
<type>pom</type>
<version>${drools.version}</version>
<scope>import</scope>
</dependency>
<!-- define drools BOM -->
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-bom</artifactId>
<type>pom</type>
<version>${jbpm.version}</version>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Above should be declared in top level pom.xml so all modules that need to use KIE (drools and jBPM) API can access it.
Next, module(s) that would operate on KIE API should declare following dependencies:
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-flow</artifactId>
</dependency>
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-flow-builder</artifactId>
</dependency>
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-bpmn2</artifactId>
</dependency>
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-persistence-jpa</artifactId>
</dependency>
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-human-task-core</artifactId>
</dependency>
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-runtime-manager</artifactId>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>${slf4j.version}</version>
</dependency>
Above are the main runtime dependencies, reagrdless of where the application is deployed (application server, servlet container, standalone app). A good practice is to test the workflow components to ensure they work properly before actual deployment and thus following test dependencies should be defined:
<!-- test dependencies -->
<dependency>
<groupId>org.jbpm</groupId>
<artifactId>jbpm-shared-services</artifactId>
<classifier>btm</classifier>
<scope>test</scope>
</dependency>
<dependency>
<groupId>ch.qos.logback</groupId>
<artifactId>logback-classic</artifactId>
<version>${logback.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>${junit.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-entitymanager</artifactId>
<version>${hibernate.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<version>${hibernate.core.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>${h2.version}</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.codehaus.btm</groupId>
<artifactId>btm</artifactId>
<version>${btm.version}</version>
<scope>test</scope>
</dependency>
Last but not least, define the JBoss Maven repository for artifacts resuolution:
<repositories>
<repository>
<id>jboss-public-repository-group</id>
<name>JBoss Public Repository Group</name>
<url>http://repository.jboss.org/nexus/content/groups/public/</url>
<releases>
<updatePolicy>never</updatePolicy>
</releases>
<snapshots>
<updatePolicy>daily</updatePolicy>
</snapshots>
</repository>
</repositories>
That should allow to configure jBPM in your application and provide access to KIE API to operate on processes, rules, events.
jBPM 6 comes with out of the box integration with CDI (Contexts and Dependency Injection). Although most of the API can be used in CDI world there are some dedicated modules that are designed especially for CDI containers. The most important one is jbpm-kie-services that provides high level services that shall be used in most of the cases were CDI is available for jBPM integration. It provides following set of services:
DeploymentService
FormProviderService
RuntimeDataService
BPMN2DataService
These services are first class citizens for CDI world so they are available for injection in any other CDI bean.
Service responsible for deploying DeploymentUnits into runtime environment. By deploying given deployment unit becomes ready for execution and has RuntimeManager created for it.DeploymentService can next be used to retrieve:
RuntimeManager instance for given deployment id
DeployedUnit that represents complete deployment process for given deployment id
list of all deployed units known to the deployment service
Deployment service stores the deployed units only in memory and thus in case of a need to restore all previously deployed units, component that uses deployment service needs to store that information itself. Common places for such store is data base, file system, repository of some sort etc. Deployment service will fire CDI events on deployment and undeployment to allow application components to react real time to these events to be able to store deployments or remove them from the store when they are undeployed.
DeploymentEvent with qualifier @Deploy will be fired on deployment
DeploymentEvent with qualifier @Undeploy will be fired on undeployment
use CDI observer mechanism to get notification on above events. First to save deployments in the store of your choice:
public void saveDeployment(@Observes @Deploy DeploymentEvent event) {
// store deployed unit info for further needs
DeployedUnit deployedUnit = event.getDeployedUnit();
}
next to remove it when it was undeployed
public void removeDeployment(@Observes @Undeploy DeploymentEvent event) {
// remove deployment with id event.getDeploymentId()
}
Due to the fact that there might be several implementation of DeploymentService use of qualifiers is needed to instruct CDI container which one shall be injected. jBPM comes with two out of the box:
@Kjar - KmoduleDeploymentService that is tailored to work with KmoduleDeploymentUnits that are small descriptor on top of a kjar - recommended to use in most of the cases
@Vfs - VFSDeploymentDService that allows to deploy assets directly from VFS (Virtual File System) that is provided by UberFire framework. Due to that fact VFSDeploymentService and VFSDeploymentUnit are not bundled with jbpm core modules but with jbpm-console-ng modules.
The general practice is that every implementation of DeploymentService should come with dedicated implementation of DeploymentUnit as these two provided out of the box.
FormProviderService provides access to form representations usually displayed on UI for both process forms and user task forms. It is built on concept of isolated FormProviders that can provide different capabilities and be backed by different technologies. FormProvider interface describes contract for the implementations
public interface FormProvider {
int getPriority();
String render(String name, ProcessDesc process, Map<String, Object> renderContext);
String render(String name, Task task, ProcessDesc process, Map<String, Object> renderContext);
}
Implementations of FormProvider interface should always define priority as this is the main driver for the FormProviderService to ask for the content of the form of a given provider. FormProviderService will collect all available providers and iterate over them asking for the form content (rendered) in their priority order. The lower the number the higher priority it gets during evaluation, e.g. provider with priority 5 will be evalauted before provider with priority 10. FormProviderService will irerate over available providers as long as one delivers the content. In worse case scenario simple text based forms will be returned.
jBPM comes with following FormProviders out of the box:
Fremarker based implementation to support jbpm version 5 process and task forms - priority 3
Default forms provider, considered last resort if none of the other providers deliver content this one will always provide simplest possible forms - lowest priority (1000)
when form modeler is used there is additional FormProvider available to deliver forms modeled in that tool - priority 2
RuntimeDataService provides access to actual data that is availabe on runtime such as
available processes to be executed - with various filters
active process instances - with various filters
process instance history
process instance variables
active and completed nodes of process instance
Default implementation of RuntimeDataService is observing deployment events and index all deployed processes to expose them to the calling components. So whatever gets deployed RuntimeDataService will be aware of that.
Service that provides access to process details stored as part of BPMN2 xml.
Before using any method that provides information, findProcessId must be invoked to populate repository with process information taken from BPMN2 content.
BPMN2DataService provides access to following data:
overall description of process for given process definition
collection of all user tasks found in the process definition
information about defined inputs for user task node
information about defined outputs for user task node
ids of reusable processes (call activity) defined within given process definition
information about process variables defined within given process definition
information about all organizational entities (users and groups) included in the process definition. Depending on the actual process definition the returned values for users and groups can contain
actual user or group name
process variable that will be used to get actual user or group name on runtime e.g. #{manager}
To make use of jbpm-kie-services in your system you'll need to provide some beans for the out of the box services to satisfy all dependencies they have. There are several beans that depends on actual scenario
entity manager and entity manager factory
user group callback for human tasks
identity provider to pass autheticated user information to the services
When running in JEE environment like an JBoss Application Server following producer bean should satisfy all requirements of the jbpm-kie-services
public class EnvironmentProducer {
@PersistenceUnit(unitName = "org.jbpm.domain")
private EntityManagerFactory emf;
@Inject
@Selectable
private UserGroupCallback userGroupCallback;
@Produces
public EntityManagerFactory getEntityManagerFactory() {
return this.emf;
}
@Produces
@RequestScoped
public EntityManager getEntityManager() {
EntityManager em = emf.createEntityManager();
return em;
}
public void close(@Disposes EntityManager em) {
em.close();
}
@Produces
public UserGroupCallback produceSelectedUserGroupCalback() {
return userGroupCallback;
}
@Produces
public IdentityProvider produceIdentityProvider {
return new IdentityProvider() {
// implement IdentityProvider
};
}
}
Then beans.xml for the application should enable proper alternative for user group callback (that will be taken based on @Selectable qualifier)
<beans xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://docs.jboss.org/cdi/beans_1_0.xsd">
<alternatives>
<class>org.jbpm.services.task.identity.JAASUserGroupCallbackImpl</class>
</alternatives>
</beans>
org.jbpm.services.task.identity.JAASUserGroupCallbackImpl is just an example here which usually is the good fit for JBoss Application Server to reuse security settings on application server regardless of what it actually is (LDAP, DB, etc). Check Human Task section for more alternatives for UserGroupCallback.
Optionally there can be several other producers provided to deliver:
WorkItemHandlers
Process, Agenda, WorkingMemory event listeners
These components can be provided by implementing following interfaces
/**
* Allows to provide custom implementations to deliver WorkItem name and WorkItemHandler instance pairs
* for the runtime.
* <br/>
* It will be invoked by RegisterableItemsFactory implementation (especially InjectableRegisterableItemsFactory
* in CDI world) for every KieSession. Recommendation is to always produce new instances to avoid unexpected
* results.
*
*/
public interface WorkItemHandlerProducer {
/**
* Returns map of (key = work item name, value work item handler instance) of work items
* to be registered on KieSession
* <br/>
* Parameters that might be given are as follows:
* <ul>
* <li>ksession</li>
* <li>taskService</li>
* <li>runtimeManager</li>
* </ul>
*
* @param identifier - identifier of the owner - usually RuntimeManager that allows the producer to filter out
* and provide valid instances for given owner
* @param params - owner might provide some parameters, usually KieSession, TaskService, RuntimeManager instances
* @return map of work item handler instances (recommendation is to always return new instances when this method is invoked)
*/
Map<String, WorkItemHandler> getWorkItemHandlers(String identifier, Map<String, Object> params);
}
and
/**
* Allows do define custom producers for know EventListeners. Intention of this is that there might be several
* implementations that might provide different listener instance based on the context they are executed in.
* <br/>
* It will be invoked by RegisterableItemsFactory implementation (especially InjectableRegisterableItemsFactory
* in CDI world) for every KieSession. Recommendation is to always produce new instances to avoid unexpected
* results.
*
* @param <T> type of the event listener - ProcessEventListener, AgendaEventListener, WorkingMemoryEventListener
*/
public interface EventListenerProducer<T> {
/**
* Returns list of instances for given (T) type of listeners
* <br/>
* Parameters that might be given are as follows:
* <ul>
* <li>ksession</li>
* <li>taskService</li>
* <li>runtimeManager</li>
* </ul>
* @param identifier - identifier of the owner - usually RuntimeManager that allows the producer to filter out
* and provide valid instances for given owner
* @param params - owner might provide some parameters, usually KieSession, TaskService, RuntimeManager instances
* @return list of listener instances (recommendation is to always return new instances when this method is invoked)
*/
List<T> getEventListeners(String identifier, Map<String, Object> params);
}
Beans implementing these two interfaces will be collected on runtime and consulted when building KieSession by RuntimeManager. See RuntimeManager section for more details on this.
RuntimeManager itself can be injected as CDI bean into any other CDI bean within the application. It has then requirement to get RungimeEnvironment properly produces to allow RuntimeManager to be correctly initialized. RuntimeManager comes with three predefined strategies and each of them gets CDI qualifier so it can be referenced:
@Singleton
@PerRequest
@PerProcessInstance
Producer that was defined in Configuration section should be now enhanced with producer methods to provide RuntimeEnvironment
public class EnvironmentProducer {
@PersistenceUnit(unitName = "org.jbpm.domain")
private EntityManagerFactory emf;
@Inject
@Selectable
private UserGroupCallback userGroupCallback;
@Inject
private BeanManager beanManager;
@Produces
public EntityManagerFactory getEntityManagerFactory() {
return this.emf;
}
@Produces
@RequestScoped
public EntityManager getEntityManager() {
EntityManager em = emf.createEntityManager();
return em;
}
public void close(@Disposes EntityManager em) {
em.close();
}
@Produces
public UserGroupCallback produceSelectedUserGroupCalback() {
return userGroupCallback;
}
@Produces
public IdentityProvider produceIdentityProvider {
return new IdentityProvider() {
// implement IdentityProvider
};
}
@Produces
@Singleton
@PerRequest
@PerProcessInstance
public RuntimeEnvironment produceEnvironment(EntityManagerFactory emf) {
RuntimeEnvironment environment = RuntimeEnvironmentBuilder.Factory.get()
.newDefaultBuilder()
.entityManagerFactory(emf)
.userGroupCallback(getUserGroupCallback())
.registerableItemsFactory(InjectableRegisterableItemsFactory.getFactory(beanManager, null))
.addAsset(ResourceFactory.newClassPathResource("BPMN2-ScriptTask.bpmn2"), ResourceType.BPMN2)
.addAsset(ResourceFactory.newClassPathResource("BPMN2-UserTask.bpmn2"), ResourceType.BPMN2)
.get();
return environment;
}
}
In this example single producer method is capable of providing RuntimeEnvironment for all strategies of RuntimeManager by specifying all qualifiers on the method level.
Once complete producer is available, RuntimeManager can be injected into application's CDi bean
public class ProcessEngine {
@Inject
@Singleton
private RuntimeManager singletonManager;
public void startProcess() {
RuntimeEngine runtime = singletonManager.getRuntimeEngine(EmptyContext.get());
KieSession ksession = runtime.getKieSession();
ProcessInstance processInstance = ksession.startProcess("UserTask");
singletonManager.disposeRuntimeEngine(runtime);
}
}
That's all what needs to be configured to make use of CDI power with jBPM.
An obvious limitation of injecting directly RuntimeManager via CDI is that there might be only one RuntimeManager in the application. That in some case can be desired and that's why there is such option. In general recommended approach is to make use of DeploymentService whenever there is a need to have many RuntimeManagers active within application.
As an alternative to DeploymentService, RuntimeManagerFactory can be injected and then RuntimeManager instance can be created manually by the application. In such case EnvironmentProducer stays same as for DeploymentService and following is an example of simple ProcessEngine bean
public class ProcessEngine {
@Inject
private RuntimeManagerFactory managerFactory;
@Inject
private EntityManagerFactory emf;
@Inject
private BeanManager beanManager;
public void startProcess() {
RuntimeEnvironment environment = RuntimeEnvironmentBuilder.Factory.get()
.newDefaultBuilder()
.entityManagerFactory(emf)
.addAsset(ResourceFactory.newClassPathResource("BPMN2-ScriptTask.bpmn2"), ResourceType.BPMN2)
.addAsset(ResourceFactory.newClassPathResource("BPMN2-UserTask.bpmn2"), ResourceType.BPMN2)
.registerableItemsFactory(InjectableRegisterableItemsFactory.getFactory(beanManager, null))
.get();
RuntimeManager manager = managerFactory.newSingletonRuntimeManager(environment);
RuntimeEngine runtime = manager.getRuntimeEngine(EmptyContext.get());
KieSession ksession = runtime.getKieSession();
ProcessInstance processInstance = ksession.startProcess("UserTask");
manager.disposeRuntimeEngine(runtime);
manager.close();
}
}
All core jbpm jars (and core dependencies) are OSGi-enabled. That means that they contain MANIFEST.MF files (in the META-INF directory) that describe their dependencies etc. These manifest files are automatically generated by the build. You can plug these jars directly into an OSGi environment.
OSGi is a dynamic module system for declarative services. So what does that mean? Each jar in OSGi is called a bundle and has its own Classloader. Each bundle specifies the packages it exports (makes publicly available) and which packages it imports (external dependencies). OSGi will use this information to wire the classloaders of different bundles together; the key distinction is you don't specify what bundle you depend on, or have a single monolithic classpath, instead you specify your package import and version and OSGi attempts to satisfy this from available bundles.
It also supports side by side versioning, so you can have multiple versions of a bundle installed and it'll wire up the correct one. Further to this Bundles can register services for other bundles to use. These services need initialisation, which can cause ordering problems - how do you make sure you don't consume a service before its registered? OSGi has a number of features to help with service composition and ordering. The two main ones are the programmatic ServiceTracker and the xml based Declarative Services. There are also other projects that help with this; Spring DM, iPOJO, Gravity.
The following jBPM jars are OGSi-enabled: