Accessing a Bonita J EE deployment with the Console

The Bonita Console is configured to deploy and work with processes in an embedded instance of the BPM engine.

If you deployed the Bonita engine as a J EE application you will have to either develop your own administrative console from scratch, use the provided Ant tasks for management (described in the Bonita Cookbook, section 7.4) or reconfigure the console to access the remote engine instead of the embedded one.

The following steps show how to reconfigure the console to access a Bonita engine deployed in an application server:

1. Set the API Type variable.
2. Set the initial context properties.
3. Include the client libraries.
4. JAAS settings to propagate the client security identity.
5. Changing the console's default port (optional)

I will further discuss each one of those steps in the following sections.

Set the API Type variable

For the Bonita classes in the console to work as a facade to an engine deployed in a remote server rather than as an embedded solution you need to set the API type variable (org.ow2.bonita.api-type) with either EJB2 or EJB3 values (depending on the EJB environment you are using).

The easiest way to do it is by editing the bpm.bat or bpm.sh file (in the bonita-console-4.1/bin folder). There you can change the value of the BONITA_OPTS variable from -Dorg.ow2.bonita.environment=bonita-environment.xml to -Dorg.ow2.bonita.api-type=EJB2 or -Dorg.ow2.bonita.api-type=EJB3. Since the org.ow2.bonita.environment variable is used only in the server side of the Bonita engine, it will not be necessary anymore and can be safely replaced with the settings for the API type variable.

Set the initial context properties

Since the Bonita Engine will be running in a different Java virtual machine than the Bonita Console, the latter needs to know the network location of the former, even if it is in the same physical machine.

This is done by setting 2 standard JNDI properties: java.naming.factory.initial and java.naming.provider.url. The best way to provide the values for those variables is by editing the WEB-INF/conf/common/common-configuration.xml file, located in the bonita-console-4.1/webapps/portal.war application. At the beginning of that file, you will find commented XML elements that will set the properties with the values for each one of the environments supported by default (Jonas, JBoss and EasyBeans). You just need to uncomment the pair of properties for your environment and update the IP and port of Bonita Engine's location in the value of the java.naming.provider.url property. Steps 1 to 6, 9 and 10 of this post will give you detailed instructions on how to modify and rebuild the WAR file.

Include the client libraries

The Bonita Console will needed additional libraries with the code necessary to connect to the application server were the engine is deployed, that can be included in the classpath by adding them to the bonita-console-4.1/lib folder.

Those libraries need to be provided by your application server vendor. For example, for Jonas 5 you will have to include a client.jar file, for JBoss 4.0 you will have to include a file called jbossall-client.jar and for JBoss 5.0 you will have to provide several different JAR files. Most of the time those files are provided with the AS distribution.

Since Tomcat, Exo and the Bonita Console make use of some common libraries (like Log4J) you will need to check the libraries you are adding from your application server are not already provided in the bonita-console-4.1/lib folder or you will have classloading or API version issues. Ideally, you should keep the newer version of the library in case of conflicts.

JAAS settings to propagate the client security identity

For the Bonita Engine to know what user is currently logged in the Console, you will need change the Console's JAAS settings to include a login module that can propagate the client's security identity to the application server.

That login module needs to be included as the last module of the exo-domain section in the bonita-console-4.1/conf/jaas.conf file.

The actual login module to use depends on the application server that you are using. However, you can find sample settings for the environments supported out of the box in the bonita-runtime-4.1/conf/jaas-*.cfg files.

Changing the console's default port (optional)

If you are running the application server and the console in the same machine, make sure they are not using the same port to publish the web applications (for example, both Bonita Console and JBoss use 8080 as the default port). You can change the console's default port by editing the bonita-console-4.1/conf/server.xml file as described here.