As you may know, process based applications generated with Bonita Open Solution Studio and Bonita Open Solution User Experience use Bonita Runtime. Bonita Runtime is an open source BPM engine written in Java. It is a very powerful and lightweight library that allows you to define, deploy, execute and manage your processes.
If you don’t want to leverage the existing interfaces of the process based applications and User Experience to interact with the Bonita Runtime and prefer to do it the hard way 
to and implement your own application and interfaces directly, this series of articles will give you basic knowledge to get started quickly.
Bonita Runtime has been designed to provide a lot of flexibility through service injection. It is completely configurable 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 Runtime is non intrusive, meaning 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 cool feature of Bonita Runtime is support for command injection that allows you to create your own operations in the Runtime.
In this series of articles, I’m going to deal with the following topics:
- Understanding object models
- Using APIs
- Configuring the Runtime
- Using EJBs
- Using commands
- Setting up your maven project and getting started with an example
In Part 2, I’m going to deal with:
3 - Configuring the Runtime
Bonita Runtime can be exported from Bonita Open Solution Studion 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 Runtime distribution. As you can see, it is mainly composed by 3 different folders: ‘conf’, ‘ear’ and ‘lib’.
Let’s start with one of the most important one: ‘lib’. It is composed by 2 folders ‘client’ and ‘server’ and it is a very important distinction you have to keep in mind when integrating Bonita Runtime 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 Runtime 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.
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
- org.ow2.bonita.environment=<absolute path to your bonita environment xml file>
Bonita Runtime Server configuration using Environment xml file
This file is embeded in bonita-server.jar and is also provided in Bonita Runtime distribution. This xml file defines all services used by the Runtime and you can configure all of them either by modifying the embeded bonita-default-environment.xml file either by defining bonita environment Java System property on the server side and link your own bonita-environment.xml (e.g. the one provided in the distribution).Let me explain the main configurations you can be interested in:
- 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').
- hibernate-configuration: this entries define 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 embeded 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 you can update the environment file to link an external file: don't forget to rename 'resource' attribute to 'file' in that case. In addition, be careful on Windows OS, you need to replace a Linux '/' by '\\'. You can also watch this video to get started configuring a new database: http://www.youtube.com/BonitaSoft#p/a/u/2/ct5uRIzzosk.
- large-data-repository: this entry defines the implementation of the large data repository. By default, artifacts (bar files, classes, 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'
Bonita Runtime security mechanism
Bonita Runtime only needs to know which is the current logged user to store this information in history. To get the userID, Bonita Runtime is calling a service described in the environment xml file called 'security'. By default, 'org.ow2.bonita.facade.AutoDetectSecurityContext'. This class uses an algorith 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 in a tiers application which for example stores the userId in a session, you can write your own implemntation 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 Runtime distribution comes with a set of default JAAS configuration files for widely used architectures either in local, with JBoss or JOnAS applications servers. On the client side, you have to login against the default login Module (called Bonita) or one of your choice. Don’t forget to set Java System property to this JAAS file (java.security.auth.login.config: see above).
4 - Using EJBs
Bonita Runtime distribution contains an 'ear' folder. In this folder, all necessary artifacts are provided to build an ear containing Bonita Runtime ejbjar and all its dependencies. The generated ear is build using the 'conf' folder, i.e. if you modify hibernate.properties fles 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 prefered 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
- Don't forget to use the correct JAAS file (probably one of the configurations you can find in the distribution)