DRAW your processes CONNECT to your systems RUN in one clic

Custom Application Development with Bonita Execution Engine

by Charles Souillard CTO and co-founder, BonitaSoft
Contents
1. 2. 3. 4. 5. Introduction Understanding object models Using APIs Configuring the Execution Engine Using EJBs 6. 7. 8. 9. Using commands Example 1 Example 2 Conclusion

1. Introduction
Bonita Open Solution is a 3-in-1 suite composed of: Bonita Studio, an integrated process-based application builder based on BPMN2 modeling and drag-and-drop form customization, Bonita Execution Engine, a powerful and scalable BPM engine, and Bonita User Experience, a breakthrough end-user interface.

Creating applications with Bonita Open Solution is easy with the help of Bonita Web Application Builder which dramatically reduces the need for coding. But sometimes developers may want to break away from Bonita end-user technology either to create highly customized interfaces - using for example a different framework than GWT (Google Web Toolkit) used in Bonita User Experience - or embed Bonita Execution Engine in even more complex applications, which is possible through the use of Bonita Execution Engine APIs. Bonita Execution Engine - also referred as Runtime in this paper - was designed to provide a lot of flexibility through service injection. It is a completely configurable engine using an XML file called environment. This configuration describes all services used. You can change all of them or replace them with your own implementation. In addition, Bonita Execution Engine is non-intrusive, meaning that it requires only Java. You can install it in any JVM of your choice, in any web/JEE container or use it as a simple Java library. Another remarkable feature of Bonita Execution Engine is that it supports for command injection, allowing you to create your own operations in the Runtime.
Free download on www.bonitasoft.com BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

The white paper aims at helping you understand how you can use Bonita Execution Engine for your custom developments. Note: the Bonita Execution Engine is available as a separate download

2. Understanding object models

Bonita Execution Engine APIs use 2 different object models: Definition and Runtime. Definition object model Definition objects represent the process model. The root object of the hierarchy is ProcessDefinition. A ProcessDefinition is a Java representation of a process (i.e. pool) designed in Bonita Studio. Technically, this object is built using the ProcessBuilder. ProcessDefinition contains the following fields:

uuid name label description version state deployedBy deployedDate undeployedBy undeployedDate

ProcessDefinition also contains a set of other entities: e.g. datafields, participants, activities, attachments, metadata. The most used entities are: activities, datafields and participants. All major elements in the Definition object model have the following fields in common:

uuid to identify uniquely an object name label description

All objects which are children of ProcessDefinition also have direct access to the parent process uuid. A ProcessDefinition can be in one of the three following states:

enabled: the process is in the runtime repository and can be instantiated disabled: the process is in the runtime repository and cannot be instantiated (i.e. suspended) archived: the process is no longer in the runtime repository. It has been moved to the history repository and can no longer be instantiated.
BonitaSoft, 2010

Free download on www.bonitasoft.com

DRAW your processes CONNECT to your systems RUN in one clic

Runtime object model Runtime objects represent the runtime model. The root object of the hierarchy is ProcessInstance. A ProcessInstance represents one executing/executed instance of a ProcessDefinition. A ProcessDefinition can be instantiated multiple times (e.g. ProcessDefinition can be ArrivalOfANewEmployee, and we have more than one new employee). ProcessInstance contains a set of fields including:

instanceUUID processUUID state startedBy startedDate endedBy endedDate

ProcessInstance also contains a set of other entities including:

activities variables attachments involvedUsers variableUpdates (history of all variables assignments during the process instance life) stateUpdates (history of all states assignments during the process instance life)

The most used entities are: activities and variables. A few explanations about activities There are two types of activities. Automatic activities do not require a human contribution. Manual activities require a human contribution. The Runtime object model makes the distinction between these by using inheritance. Automatic activities are of type ActivityInstance. Human activities are of type TaskInstance. A TaskInstance is an ActivityInstance with additional information. A ProcessInstance can be in one of the following states:

started: the process instance is started and currently executing (some activities still have to be done) finished: the process instance has reached the end and is finished canceled: an admin user has manually canceled this instance and it can no longer be executed aborted: an internal error has aborted this instance and it can no longer be executed

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic 3. Using APIs
Bonita Execution Engine provides a very useful feature related to environment management. This feature ensures that your application is not dependent on the target deployment architecture. You can develop your application inside a simple web container and then deploy it on a JEE server without modifying your Java code. This is automatically done through AccessorUtil capabilities. AccessorUtil (org.ow2.bonita.util.AccessorUtil) is the main entry point to Bonita Execution Engine APIs. Using this utility class, you can get access to all available APIs. Bonita Execution Engine provides different APIs organized by the following concepts: ManagementAPI operations related to process installation/removal, resources/filters management. e.g. deploy(businessArchive), deleteProcess(processUUID), addMetadata(key, value)

QueryDefinitionAPI query operations related to the Definition object model. These operations do not modify the persisted objects. e.g. getProcesses(), getProcess(processUUID), getProcessActivities(processUUID, activityName)

RuntimeAPI modification operations related to the Runtime object model. These operations modify the persisted objects. e.g. executeTask(taskUUID), assignTask(taskUUID, userId), instantiateProcess(processUUID), setProcessInstanceVariable(processInstanceUUID, variableName, variableValue), deleteProcessInstance(processInstanceUUID)

QueryRuntimeAPI Query operations related to the Runtime object model. These operations do not modify the persisted objects. e.g. getProcessInstances(), getActivityInstance(activityInstanceUUID), getTaskList(taskState), getVariable(activityInstanceUUID, variableName), getProcessInstanceVariable(processInstanceUUID, variableName)

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

RepairAPI advanced administration operations to handle executing process instances that may be off nominal e.g. startExecution(processInstanceUUID, activityName), stopExecution(processInstanceUUID, activityName)

CommandAPI operations to execute commands available in a given process or in the overall engine e.g. execute(command, processUUID), execute(command)

IdentityAPI operations related to embedded user module e.g. addUser(userName, password), addRole(roleName), getUsers(), getUsersInRole(roleName)

BAMAPI query operations to retrieve statistics from the runtime data e.g. getNumberOfOverdueSteps(), getNumberOfOpenSteps(), getNumberOfOpenStepsPerDay(startDate)

4. Configuring Bonita Execution Engine - the Runtime

Bonita Execution Engine can be exported from Bonita Open Solution Studio in Process menu and then Export Application menu entry. You only have to tick Export Runtime option and click the Finish button. You have now access to Bonita Execution Engine distribution. As you can see, it is mainly composed by 3 different folders: conf, ear and lib. Lets start with one of the most important one: lib. It is composed by 2 folders client and server - it is a very important distinction that you have to keep in mind when integrating Bonita Execution Engine in your applications. Bonita Server module has a dependency on Bonita Client module not vice versa. You also have to know that Bonita Server contains Bonita Client. Let me just define what is Bonita Client side and Bonita Server side. In a very simple architecture i.e. all web applications + runtime installed within the same web server there is no real client side. In a more complex architecture you can install Bonita Execution Engine in a JEE server and web applications in another web container. In this case, web applications are on the client side. There are many configuration points available both in client and server side.

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

Java System properties on the client side:

Java standard logging property: -Djava.util.logging.config.file=<absolute path to your logging.properties> (one logging.properties is provided in the distribution) Java standard security configuration (JAAS): java.security.auth.login.config=<absolute path to your jaas configuration file> (some configurations are provided in the distribution for local and JEE deployments) Bonita API type access: org.ow2.bonita.api-type (only used if Bonita Runtime is not in the same JVM as this Client) Java standard JEE naming properties: -Djava.naming.factory.initial and Djava.naming.provider.url

Java System properties on the server side:

org.ow2.bonita.environment=<absolute path to your bonita environment xml file>

Bonita Execution Engine Server configuration using Environment xml file

This file is embedded in bonita-server.jar and is also provided in Bonita Execution Engine distribution. This xml file defines all services used by the Execution Engine and you can configure all of them either by modifying the embedded bonita-default-environment.xml file or by defining bonita environment Java System property on the server side and linking your own bonita-environment.xml (e.g. the one provided in the distribution). Let me explain the main configurations you can be interested in: 1. Finished-instance-handler: This entry defines a chain of handlers called when an instance ends. By default, a finished instance is archived, i.e. moved from runtime database called journal to history database (org.ow2.bonita.services.handlers.impl.ArchiveFinishedInstanceHandler). 2. Hibernate-configuration: This entry defines the Hibernate configurations (hibernate.properties files) used by the runtime. There are 2 different configurations: core and history, i.e. journal and history. Hibernate.properties files are embedded in bonita-server.jar, this is why these files are referenced as resource. You can either update them in the jar file to change the database or update the environment file to link an external file: dont forget to rename resource attribute to file in that case. In addition, be careful on Windows OS, you would need to replace a Linux / by \\. 3. Large-data-repository: This entry defines the implementation of the large data repository. By default, artifacts (bar files, classes and attachments) are stored to the file system. You can also write your own implementation to store them in database. If needed, you can store the large data repository to another folder on the file system by specifying an absolute path in this entry instead of property:java.io.tmpdir

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

Bonita Execution Engine security mechanism
Bonita Execution Engine only needs to know who is the current logged user to store this information in its history. To get the userID, Bonita Execution Engine is calling a service described in the environment xml file called security. By default, org.ow2.bonita.facade.AutoDetectSecurityContext. This class uses an algorithm to detect the current architecture: if no Bonita EJB3 can be reached, then try to lookup a Bonita EJB2 and if none is found, the local architecture is used. In all these cases, the userId is propagated from client side to server side using JAAS. This is not mandatory but this is the default implementation. If you are integrating the runtime with a tiers application which for example stores the userId in a session, you can write your own implementation of the security service which is going to read the userId in this session. If you want to use the default mechanism, you have to use JAAS to propagate the userId to the server. Bonita Execution Engine distribution comes with a set of default JAAS configuration files for widely used architectures either in local, with JBoss or with JOnAS applications servers. On the client side, you have to login against the default login Module (called Bonita) or one of your choice. Dont forget to set Java System property to this JAAS file (java.security.auth.login.config: see above).

5. Using EJBs
Bonita Execution Engine distribution contains an ear folder. In this folder, all necessary artifacts are provided to build an ear containing Bonita Execution Engine ejbjar and all its dependencies. The generated ear is build using the conf folder, i.e. if you modify hibernate.properties files or environment, changes will be used in the ear. ear folder also contains deployment descriptors for JBoss, JOnAS, Weblogic and Glassfish (EJB3 only). If you want to include other deployment descriptors, you can add your own in this folder. You can build ear files for both EJB3 and EJB2 by calling ear.ejb3 or ear.ejb2 from the root folder of the distribution. Once the ear file is generated, you have to install it in your preferred JEE application server and then start the server with the Java System properties:

Bonita API type access: org.ow2.bonita.api-type=<EJB3 or EJB2> java.naming.factory.initial java.naming.provider.url Dont forget to use the correct JAAS file (probably one of the configurations you can find in the distribution

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic 6. Using commands
Bonita Execution Engine is providing its very useful mechanism called Commands which allows developers to write their own commands inside the Bonita Execution Engine Server. A command is a Java class implementing org.ow2.bonita.util.Command interface. There is only one operation to implement: T execute(org.ow2.bonita.env.Environment environment) throws Exception; To execute a command, you have to make it available in both client and server side classpath. You can do that either by

having the jar file containing the command available in the classpath (Env property or common lib folder in a web container for example) including the command compiled class in the deployed bar file deploying the jar file containing the command inside Bonita class loader using ManagementAPI

A command has many benefits and can be used for different purposes. A command is executed on the server side and you have access to the entire runtime inside (I mean not only APIs but all internal objects, services). Let me give you the reasons why you could use Commands: 1. Transaction: you want that a sequence of APIs calls to be executed in the same transaction. e.g. you want to create a new ProcessInstance and then set some variables. If setVariable call fails and you are doing that outside of a command, then your ProcessInstance remains created. If the behavior you want is Do no create the ProcessInstance if something fails then you have to write your own command with these 2 calls inside. 2. Bug fixing: youve identified a bug in an API operation and you want to fix it without waiting for the next maintenance release. You can use all internal Object model and services to implement the needed feature without bug 3. Missing operation: APIs are offering a wide scope of operations but maybe you miss one important thing for your application? In that case, you can use the commands mechanism to implement your own feature just as explained in point 2. You can find an example of commands in the community source explorer here. Bonita Execution Engine full Javadoc can be accessed here

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic Example 1: Embedded application using Maven
In this chapter, I am going to help you to get started with your first Bonita project using Maven. In this example I am going to setup a very simple architecture without any container (neither Web neither EJB). Bonita Execution Engine is going to be used as a simple library. This example will illustrate basic operations of the APIs such as

deploy process instantiate process get task list execute task

This example will use a very simple process inside Bonita Open Solution Studio. This process contains only 2 human tasks, both assigned to the process instance initiator:

Lets start with our 5 minutes setup using my favorite IDE: Eclipse. First of all, you can create a new simple maven project with the following parameters:

Group ID: org.bonitasoft.example Artifact ID: runtime Version: 1.0

I also created an additional source folder:

src/main/resources in which I copied the exported process and jaas-standard.cfg file (available in runtime distribution).
Free download on www.bonitasoft.com BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

Once this maven project is created, we can add a maven dependency to the server side libraries. You only have to add a new dependency to Bonita-server artifact (note that I added a parent to get pre configured OW2 maven repository): <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd" <modelVersion>4.0.0</modelVersion> <groupId>org.bonitasoft.example</groupId> <artifactId>runtime</artifactId> <packaging>jar</packaging> <version>1.0</version> <name>runtime</name> <url>http://www.bonitasoft.org</url> <parent> <groupId>org.ow2</groupId> <artifactId>ow2</artifactId> <version>1.1</version> </parent> <dependencies> <dependency> <groupId>org.ow2.bonita</groupId> <artifactId>bonita-server</artifactId> <version>5.0.2</version> </dependency> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>3.8.1</version> </dependency> </dependencies> </project> Our maven project is now configured, we can start coding! In this application, we are going to do the following operations: 1. 2. 3. 4. 5. 6. 7. 8. 9. login deploy the bar file create a new process instance get task list and execute task1 assign task2 to another user and then back to the logged user execute task2 check created process instance is finished clean the database (delete all processes) logout
BonitaSoft, 2010

Free download on www.bonitasoft.com

DRAW your processes CONNECT to your systems RUN in one clic

/** * Copyright (C) 2009 BonitaSoft S.A. * BonitaSoft, 31 rue Gustave Eiffel 38000 Grenoble * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 2.0 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see &lt;http://www.gnu.org/licenses/&gt;. */ package org.bonitasoft.example.runtime; import java.io.File; import java.util.Collection; import javax.security.auth.login.LoginContext; import org.ow2.bonita.facade.ManagementAPI; import org.ow2.bonita.facade.QueryRuntimeAPI; import org.ow2.bonita.facade.RuntimeAPI; import org.ow2.bonita.facade.def.element.BusinessArchive; import org.ow2.bonita.facade.def.majorElement.ProcessDefinition; import org.ow2.bonita.facade.runtime.ActivityState; import org.ow2.bonita.facade.runtime.InstanceState; import org.ow2.bonita.facade.runtime.TaskInstance; import org.ow2.bonita.facade.uuid.ProcessDefinitionUUID; import org.ow2.bonita.facade.uuid.ProcessInstanceUUID; import org.ow2.bonita.util.AccessorUtil; import org.ow2.bonita.util.BonitaConstants; import org.ow2.bonita.util.BusinessArchiveFactory; import org.ow2.bonita.util.SimpleCallbackHandler;

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

/** * @author Charles Souillard */ public class App { private static final String LOGIN = admin; private static final String PASSWORD = bpm; private static final String BAR_FILE_PATH = src/main/resources/example_1.0.bar; private static final String JAAS_FILE_PATH = src/main/resources/jaas-standard.cfg; static { System.setProperty(BonitaConstants.JAAS_PROPERTY, JAAS_FILE_PATH); } public static void main( String[] args ) throws Exception { //get all used APIs final ManagementAPI managementAPI = AccessorUtil.getManagementAPI(); final RuntimeAPI runtimeAPI = AccessorUtil.getRuntimeAPI(); final QueryRuntimeAPI queryRuntimeAPI = AccessorUtil.getQueryRuntimeAPI(); //define non final fields Collection&lt;TaskInstance&gt; tasks = null; //login final LoginContext loginContext = new LoginContext(Bonita, new SimpleCallbackHandler(LOGIN, PASSWORD)); loginContext.login(); try { //deploy the bar file final File barFile = new File(BAR_FILE_PATH); final BusinessArchive businessArchive = BusinessArchiveFactory.getBusinessArchive(barFile); final ProcessDefinition process = managementAPI.deploy(businessArchive); final ProcessDefinitionUUID processUUID = process.getUUID(); //we can use the QueryDefinition API to get the process definition based on the process UUID //final QueryDefinitionAPI queryDefinitionAPI = AccessorUtil.getQueryDefinitionAPI(); //final ProcessDefinition deployedProcess = queryDefinitionAPI.getProcess(processUUID); //create a new process instance without initial variables, attachments final ProcessInstanceUUID instanceUUID = runtimeAPI.instantiateProcess(processUUID); //get the task list and check it is not empty tasks = queryRuntimeAPI.getTaskList(ActivityState.READY); if (tasks.size() != 1) { throw new RuntimeException(Incorrect task list size! Actual size: + tasks.size()); } //get the first task in the list which must be task1 final TaskInstance task1 = tasks.iterator().next(); if (!task1.equals(task1.getActivityName())) { throw new RuntimeException(Incorrect task name! Actual name: + task1.getActivityName()); }

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

//execute task1 and assign it to me runtimeAPI.executeTask(task1.getUUID(), true); //check we have a new task in the task list tasks = queryRuntimeAPI.getTaskList(ActivityState.READY); if (tasks.size() != 1) { throw new RuntimeException(Incorrect task list size! Actual size: + tasks.size()); } //get the first task in the list which must be task1 final TaskInstance task2 = tasks.iterator().next(); if (!task2.equals(task2.getActivityName())) { throw new RuntimeException(Incorrect task name! Actual name: + task2.getActivityName()); } //assign task2 to another user runtimeAPI.assignTask(task2.getUUID(), john); //check my tasklist is empty tasks = queryRuntimeAPI.getTaskList(ActivityState.READY); if (tasks.size() != 0) { throw new RuntimeException(Incorrect task list size! Actual size: + tasks.size()); } //assign back task2 to admin and execute it runtimeAPI.assignTask(task2.getUUID(), LOGIN); runtimeAPI.executeTask(task2.getUUID(), true); //check process instance is finished final InstanceState instanceState = queryRuntimeAPI.getProcessInstance(instanceUUID).getInstanceState(); if (!InstanceState.FINISHED.equals(instanceState)) { throw new RuntimeException(Incorrect state for process instance! Actual state: + instanceState); } System.err.println(\n**********\n); System.err.println(Application executed successfully!); System.err.println(\n**********\n); } finally { //delete all processes to be able to run this App many times without getting Process already deployed exception //this MUST NOT be done in production environment! managementAPI.deleteAllProcesses(); //logout loginContext.logout(); } } } You can now launch this application like a Java Main: right click on the background and Run As -> Java Application. If you want to use this example as a basis for your applications, you can download it here: Compressed example
Free download on www.bonitasoft.com BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic Example 2: Write your own Web applications with Bonita Execution Engine
Bonita Open Solution Studio is generating web applications for your processes using GWT (Google Web Toolkit) technology. In some cases, this may not fit your needs as you want to use another technology to develop your BPM applications. In that case, you can still leverage Bonita Execution Engine or runtime functionalities by using APIs. In this example Im going to explain in details on how to use major APIs operations to create your own Web application based on Bonita Execution Engine. Application functionalities This application is divided in many screens. 1. Login: allows you to log to the application using default users: admin, john, james, jack (all with password bpm).

2. Home: displays the tasks of the logged user. Both job done and job to be done are displayed. The logged in user can also start a new process instance of one of Enabled processes.

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

3. Task details: displays the properties of the selected task and the list of both local and global variables accessible from this task. If the task is active, then variables can be updated. This page also allows to execute the task.

4. Processes: displays the list of enabled and disabled processes. For every process in those lists, you can execute appropriate actions. This page is accessible only for users that have admin rights (admin user by default).

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

5. Instances: displays the list of instances (max. 20 per source). For every instance in those lists, you can execute appropriate actions. This page is accessible only for users that have admin rights (admin user by default).

Source code structure To build this example application, I decided to use a different web technology than GWT to demonstrate Bonita Execution Engine that can be leveraged in all Java compliant Web technologies: Java Server Pages. The project contains different folders, so let me explain what is the content of each of them. This application is a simple Maven web-app project. I created it using: mvn archetype:create -DgroupId=org.bonitasoft.example -DartifactId=bonita-application DarchetypeArtifactId=maven-archetype-webapp

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

pom.xml: maven pom file defining dependencies to Bonita-server, servlet-api and jsp-api webapp: contains jsp files that display the pages above and html header and footer (only for a look & feel purpose). webapp/actions: contains jsp file in charge of executing an action without displaying anything (when action is performed, a redirection is performed) webapp/WEB-INF: contains web.xml file (very simple one) webaap/WEB-INF/classes: contains jaas-standard.cfg file used if no jaas property is defined webaap/css: contains css files used by html header and footer webapp/images: contains images used by html header and footer

Jsp actions in detail In this section Im going to explain all API calls performed in this application. login.jsp Bonita Execution Engine does not require JAAS authentication but this is the default configuration. It comes with 2 different login modules:

BonitaAuth in charge of authenticating the user with the given login and password BonitaStore in charge of propagating the user credentials to the server (in our case, the runtime is embedded in the application, so credentials are stored in a ThreadLocal)

You can see that both login modules are used. You will see in other jsp files that only BonitaStore is called before using APIs. Once the user is authenticated, we store the user name in the web session and we only need to propagate the user name to the server before calling APIs. This jsp file also determines and stores in the web session if the user has admin rights or not. logout.jsp In this action, we only remove information stored in the web session to force a new login. apiCall.jsp This jsp file is in charge of executing all usual Bonita Execution Engine API calls. This file has 2 required parameters:

back: the name of the jsp file to which the user must be redirected after the api call action: the id of the action to execute

This file may have been split in one file per API action but to prevent code duplication, I wrote everything in the same file.

Free download on www.bonitasoft.com

BonitaSoft, 2010

DRAW your processes CONNECT to your systems RUN in one clic

Let me give you a quick overview of actions performed in this file:

archiveProcess: archive a process based on its ProcessDefinitionUUID o managementAPI.archive(ProcessDefinitionUUID) cancelInstance: cancel a process instance base on its ProcessInstanceUUID o runtimeAPI.cancelProcessInstance(ProcessInstanceUUID) createInstance: create a new process instance of the given ProcessDefinitionUUID o runtimeAPI.instantiateProcess(ProcessDefinitionUUID) deleteInstance: delete a process instance based on its ProcessInstanceUUID o runtimeAPI.deleteProcessInstance(ProcessInstanceUUID) deleteProcess: delete a process based on its ProcessDefinitionUUID o managementAPI.deleteProcess(ProcessDefinitionUUID) deployProcess: deploy a new process based on a given bar file (exported from Bonita Open Solution Studio) o managementAPI.deploy(BusinessArchive) disableProcess: disable a process based on its ProcessDefinitionUUID o managementAPI.disable(ProcessDefinitionUUID) enableProcess: enable a process based on its ProcessDefinitionUUID o managementAPI.enable(ProcessDefinitionUUID) executeTask: execute a task based on its ActivityInstanceUUID o runtimeAPI.executeTask(ActivityInstanceUUID, assignTaskToUser) setActivityVariable: set a new value to a local variable based on the ActivityInstanceUUID, the name of the variable and the value to set o runtimeAPI.setActivityInstanceVariable(ActivityInstanceUUID, variableName, variableValue); setProcessVariable: set a new value to a global variable based on the ProcessInstanceUUID, the name of the variable and the value to set o runtimeAPI.setProcessInstanceVariable(ProcessInstanceUUID, variableName, variableValue);

home.jsp This page displays 3 tables:

tasks to perform o queryRuntimeAPI.getLightTaskList(ActivityState.READY) o returned objects are light objects as we do not need all information of the retrieved activities done tasks o queryRuntimeAPI.getLightTaskList(ActivityState.FINISHED) o returned objects are light objects as we do not need all information of the retrieved activities startable processes o queryDefinitionAPI.getLightProcesses(ProcessDefinition.ProcessState.ENABLE D) o returned objects are light objects as we do not need all information of the retrieved processes
BonitaSoft, 2010

Free download on www.bonitasoft.com

DRAW your processes CONNECT to your systems RUN in one clic

taskDetails.jsp This page displays 3 tables

task properties o queryRuntimeAPI.getTask(ActivityInstanceUUID) o using all task getters local variables o task.getLastKnownVariableValues() o also retrieve activity datafields to get type information activityDefinition = queryDefinitionAPI.getProcessActivity(ProcessDefinitionUUID, activityName) activityDefinition.getDataFields() global variables o queryRuntimeAPI.getProcessInstanceVariables(ProcessInstanceUUID) o also retrieve process datafields to get type information queryDefinitionAPI.getProcessDataFields(ProcessDefinitionUUID)

processes.jsp This page displays a form to deploy a new bar file and 2 tables:

processes of the journal (runtime database). This table is paginated: only the 20 first processes (by name) are retrieved o journalQueryDefinitionAPI = AccessorUtil.getQueryDefinitionAPI(AccessorUtil.QUERYLIST_JOURNAL_KEY) o journalQueryDefinitionAPI.getLightProcesses(0, 20) o returned objects are light objects as we do not need all information of the retrieved processes processes of the history (history database). This table is paginated: only the 20 first processes (by name) are retrieved o historyQueryDefinitionAPI = AccessorUtil.getQueryDefinitionAPI(AccessorUtil.QUERYLIST_HISTORY_KEY) o historyQueryDefinitionAPI.getLightProcesses(0, 20) o returned objects are light objects as we do not need all information of the retrieved processes

instances.jsp This page displays 2 tables:

instances of the journal (runtime database). This table is paginated: only the 20 first instances (by last update date) are retrieved o journalQueryRuntimeAPI = AccessorUtil.getQueryRuntimeAPI(AccessorUtil.QUERYLIST_JOURNAL_KEY) o journalQueryRuntimeAPI.getLightProcessInstances(0, 20)
BonitaSoft, 2010

Free download on www.bonitasoft.com

DRAW your processes CONNECT to your systems RUN in one clic

returned objects are light objects as we do not need all information of the retrieved instances instances of the history (history database). This table is paginated: only the 20 first instances (by name) are retrieved o historyQueryRuntimeAPI = AccessorUtil.getQueryRuntimeAPI(AccessorUtil.QUERYLIST_HISTORY_KEY); o historyInstances = historyQueryRuntimeAPI.getLightProcessInstances(0, 20); o returned objects are light objects as we do not need all information of the retrieved instances
o

Tips & performance As you can see in jsp files, light objects are used as much as possible. In fact this improves performance as light objects do not execute join tables in the database. I advise you to do such a thing as much as possible. Download source code and binaries You can download the bonita-application source code and the pre packaged version of this example.

9. Conclusion
As described in this paper, Bonita Execution Engine provides great flexibility for your custom application developments through the use of its APIs. Whether you just want to integrate BPM capabilities in a Portal based on a specific framework or you want to build complex applications making the most of the power and effectiveness of Bonita Execution Engine, the way to achievement is not paved with such a great complexity. Last but not least, Bonita Execution Engine is released under LGPL license, offering you multiple opportunities for developing simple to complex customized process-based applications.

About BonitaSoft
BonitaSoft is the leading provider of open source business process management (BPM) software. Created in 2009 by the founders of Bonita project, BonitaSoft democratizes the use of BPM in companies of all sizes with an intuitive and powerful solution with an optimum cost. The Bonita solution has been downloaded more than 370.000 times to date by companies and organizations worldwide. Sales inquiries : sales@bonitasoft.com | Partner inquiries : partners@bonitasoft.com www.bonitasoft.com bonitasoft.com/blog twitter.com/bonitasoft youtube.com/bonitasoft

Free download on www.bonitasoft.com

BonitaSoft, 2010