Bonita - Using the REST API

Submitted by ben.stewart on Fri, 01/21/2011 - 16:11

Before we get started with this article I need to make sure that I have the right audience.

This is a technical article, if you do not have experience in deploying applications in Tomcat, dealing with war and jar files then this article is probably not for you.

Then again the web is a wonderful place and everything you need to know is out there, you just need to find it.

For the record, I am using;

Bonita 5.3.2

Tomcat 6.0.20

Java 1.6.0_22 (from apple)

Mac OSX 1.6.6

Apache Ant version 1.8.1

Mysql 5.1.33 (from XAMPP)

Its all pretty standard install so minor variations on this should work fine. We deploy our production systems to linux and rarely have trouble moving directly from mac to unix.

Windows, should be the same, but you will need to adjust slashes and other "windowsy" things as appropriate.

I will assume that you know the basics of Bonita, how to use the interface, build a basic BPM Diagram, and execute it in the provided runtime.

Step1.

Export the Runtime, UserXP. Use the Embeded War export Mode (embeded mode will make sure all the jar's etc needed to run the User XP are included).

I will refer to the directory that you export to as the <export dir>

Step 2.

Create bonita_core database and bonita_history database.

For the purposes of my dev system running on my machine I just use the root user as it is quick and easy.

Commands along the line of this should be used;

create database bonita_journal;

create database bonita_history;

Step 3

Modify the following files out of the export in step1 and move them to somewhere sensible (in my case /bstewart/Bonita/config/

<export dir>/conf/Bonita/server/default/conf/Bonita-history.properties

<export dir>/conf/Bonita/server/default/conf/Bonita-journal.properties

<export dir>/conf/Bonita/server/default/conf/Bonita-server.xml

Step 3.1 - Bonita-history.properties - Tell hibernate to use the local mysql database that was created in step 2 rather than h2.

Make changes as follows

#hibernate.dialect org.hibernate.dialect.H2Dialect

#hibernate.connection.driver_class org.h2.Driver

#hibernate.connection.url jdbc:h2:file:${java.io.tmpdir}/Bonita-db/bonita_history.db;FILE_LOCK=NO;MVCC=TRUE;DB_CLOSE_ON_EXIT=TRUE

#hibernate.connection.shutdown true

#hibernate.connection.username sa

#hibernate.connection.password

#hibernate.hbm2ddl.auto update

hibernate.dialect org.hibernate.dialect.MySQLInnoDBDialect

hibernate.connection.driver_class com.mysql.jdbc.Driver

hibernate.connection.url jdbc:mysql://localhost:3306/bonita_history

hibernate.connection.shutdown true

hibernate.connection.username root

hibernate.connection.password root

Step 3.2 - Bonita-journal.properties - Tell hibernate to use the local mysql database that was created in step 2 rather than h2.

Make changes as follows

#hibernate.dialect org.hibernate.dialect.H2Dialect

#hibernate.connection.driver_class org.h2.Driver

#hibernate.connection.url jdbc:h2:file:${java.io.tmpdir}/Bonita-db/bonita_core.db;FILE_LOCK=NO;MVCC=TRUE;DB_CLOSE_ON_EXIT=TRUE

#hibernate.connection.shutdown true

#hibernate.connection.username sa

#hibernate.connection.password

#hibernate.hbm2ddl.auto update

hibernate.dialect org.hibernate.dialect.MySQLInnoDBDialect

hibernate.connection.driver_class com.mysql.jdbc.Driver

hibernate.connection.url jdbc:mysql://localhost:3306/bonita_journal

hibernate.connection.shutdown true

hibernate.connection.username root

hibernate.connection.password root

Step 3.3 - Change Bonita-environment.xml - Modify the properties for the hibernate config's to point to new directory.

<hibernate-configuration name='hibernate-configuration:core' >

<properties file='/Users/bstewart/Bonita/config/Bonita-journal.properties' />

<cache-configuration resource='Bonita.core.cache.xml' usage='read-write' />

</hibernate-configuration>

<hibernate-configuration name='hibernate-configuration:history' >

<properties file='/Users/bstewart/Bonita/config/Bonita-history.properties' />

<cache-configuration resource='Bonita.history.cache.xml' usage='nonstrict-read-write' />

</hibernate-configuration>

Step 3.3.1 Create a work folder in the <export_dir>\conf\Bonita\server\default\ folder

<large-data-repository name='large-data-repository' class='org.ow2.Bonita.services.impl.FileLargeDataRepository'>
<arg><string value='${BONITA_HOME}/server/default/work' /></arg>
   </large-data-repository>

        -->

        <large-data-repository name='large-data-repository' class='org.ow2.Bonita.services.impl.FileLargeDataRepository'>
   <arg><string value='${BONITA_HOME}\server\default\work' /></arg>
   </large-data-repository>

Step 3.4 - Modify the Large data repository to point to actual directory

<large-data-repository name='large-data-repository' class='org.ow2.Bonita.services.impl.FileLargeDataRepository'>

<arg><string value='/Users/bstewart/tmp' /></arg>

</large-data-repository>

Step 4. Build the war from files that were exported in step 1 (in my case /Users/bstewart/Bonita/runtime_xp/runtime)

execute the following command;

ant war

Shutdown tomcat if you have it running.

Copy the generated Bonita-server-rest.war to tomcat webapps directory.

I have tomcat installed at in opt so the path is /opt/tomcat/webapps/

When you start the server again it will unpack the war and deploy (**dont start it yet**)

Step 5. Initiate the databases

Go to the <export dir> from the exported runtime in step 1. Enter the runtime directory and initiate the db's as follows;

Step 5.1 JDBC Driver

Make sure the mysql jdbc driver (will be named mysql-connector-java-5.1.6.jar or similar) is in the runtime/lib/server and client directory (probably not required in both)

Step 5.2 Start the init.

Enter the command

ant init-db

You will be asked for a domain, just hit enter (keep default entry)
Specify the location of the Bonita environment file. Make sure this is the same location as the config file that was modified above (in my case this is in /Users/bstewart/Bonita/config/Bonita-environment.xml)
You will then be asked to enter in which config to use to generate the database. Enter

hibernate-configuration:core

The build will then start. There will be a bit of a pause in the middle, it will finish though.

Once finished do the 5.2 again, except change the last step to read hibernate-configuration:history instead of core.

Step 6.

Copy Bonita.war (from the <export dir>/web directory of export in step 1) to tomcat webapps.

Step 7.

Copy jaas-standard.cfg (from the <export dir>/web/conf directory of export in step 1) to your conf directory where the other hibernate and Bonita configuration files are sitting (in my case /Users/bstewart/Bonita/config).

Step 8.

Modify the <CATALINA_HOME>/bin/catalina.sh (in my case /opt/tomcat/bin/catalina.sh)

Java variables must be set as follows;

-Dorg.ow2.Bonita.environment=/Users/bstewart/Bonita/config/Bonita-environment.xml -Djava.security.auth.login.config=/Users/bstewart/Bonita/config/jaas-standard.cfg

The files referenced should point to where copied previously (both in my case are in in /Users/bstewart/Bonita/config)

My JAVA_OPTS line looks like this (don't copy mym Xms settings etc as they are sepcific to my machine, just pay attention to the last 2 -D entries);

JAVA_OPTS=" -server -Xms1536m -Xmx1536m

-XX:NewSize=256m -XX:MaxNewSize=256m -XX:PermSize=256m

-XX:MaxPermSize=256m -XX:+DisableExplicitGC -Dorg.ow2.Bonita.environment=/Users/bstewart/Bonita/config/Bonita-environment.xml -Djava.security.auth.login.config=/Users/bstewart/Bonita/config/jaas-standard.cfg"

Step 9.

As of version 5.3.2 of Bonita the jaas-standard.cfg file should look like this.

BonitaAuth {

org.ow2.Bonita.identity.auth.BonitaIdentityLoginModule required;

};

BonitaStore {

org.ow2.Bonita.identity.auth.BonitaRESTLoginModule required restUser="restuser" restPassword="restbpm";

};

BonitaREST {

org.ow2.Bonita.identity.auth.BonitaRESTLoginModule required restUser="restuser" restPassword="restbpm";

};

BonitaRESTServer {

org.ow2.Bonita.identity.auth.BonitaRESTServerLoginModule required logins="restuser" passwords="restbpm" roles="restuser";

};

Further details on this can be found at this address;

http://www.bonitasoft.org/wiki/doku.php?id=rest_authentication

(Note the section at the very bottom of the page about using rest via web - without Java)

There are 2 sets of users. REST API users that use basic htt authentication to login to the API, and they then run services etc as a "final" user which is defined in the user XP.

Step 10.

Start tomcat server. (/opt/tomcat/bin/catalina.sh start on my machine)

Check the catalina.out for any errors. (/opt/tomcat/logs/catalina.out)

Step 11.

Testing.

Make sure that tomcat is up and running (try visiting http://127.0.0.1:8080 and see that you get the generic tomcat page).

Testing can be done in one of 2 ways. Create a web form that posts info to the correct api or use a rest plugin for one of the more useful browsers (chrome, firefox).

Using a form you can create the following html

</form>

by opening that page in a browser a submit button will be shown. Clicking on that submit button should return a list of users (although probably unformated an difficult to read).

Download one of the following clients;

https://chrome.google.com/webstore/detail/baedhhmoaooldchehjhlpppaieoglhml

https://chrome.google.com/extensions/detail/fhjcajmcbmldlhcimfajhfbgofnpcjmb

or for firefox

https://addons.mozilla.org/en-US/firefox/addon/poster/

https://addons.mozilla.org/en-US/firefox/addon/restclient/

Use the post method for all testing and enter in the following;

URL: http://localhost:8080/Bonita-server-rest/API/identityAPI/getAllUsers

METHOD: Post

HEADERS: Content-Type: application/x-www-form-urlencoded; charset=UTF-8

DATA: options=user:admin

After sending this you should get a response the same as the browser example previously (possibly formatted better).

Step 12. Deploy a workflow.

To deploy a Process you will need to have created one using the studio. I suggest a basic email sending workflow is the best way to go, i have created a generic one that can be tweaked and used for this example.

The process that I am providing is simply the exported BAR file.

In this case we have also installed the Bonita user experience to make deploying new workflows easy.

Visit the following address: http://localhost:8080/Bonita/

Click on the Processes option under the Administrator Menu.

Click on the Install button in the process list menu. Select the bar file and then click on install. The process should then appear in the list.

Then click on the tick box next to the process and enable the process.

You can use the REST client that was used for testing before to test and make sure that your Process is on the server. See the screen shot for my exact calling of;

http://localhost:8080/Bonita-server-rest/API/queryDefinitionAPI/getProcesses

In the result that is returned seach for the uuid, this is your key to running the process;

In my case;

<uuid>

<value>mailme--1.0--Start1</value>

</uuid>

You can use the REST client that was used for testing before to test and make sure that your Process is on the server. See the screen shot for my exact calling of;

http://localhost:8080/Bonita-server-rest/API/runtimeAPI/instantiateProcess/mailme--1.0

You will be passed back the instance UUID of the process that is running so that you can refer to it and see what it is up to later.

And that's it... now you can use rest in something PHP or any other language to make calls to Bonita processes, use Bonita connectors to talk back to your application and have all sorts of fun.

Hope this is helpful.

Comments

I have found a lot of useful

Submitted by ali503 on Tue, 02/14/2012 - 15:44.

I have found a lot of useful information from this platform. I must say that sharing your thoughts with one another is an easy way to relax yourself in the daily hectic routines. Each time a description of the change, there are always lots of talk about it anywhere. These are not exempt. I mean one must be up to date with the day to day change in the environment and in the technology as well. In my personal opinion, the world is turning into a global village and now you can get a lot of required information by just a click while sitting where ever you are. 312-50v7 braindumps// 156-315 braindumps// 642-811 braindumps// 642-415 braindumps// 1Y0-259 braindumps// 1Y0-A15 braindumps// 642-801 braindumps// EC0-479 braindumps//

Recent Blogs

Contact

Follow us on:

Bonita - Using the REST API

Comments

I have found a lot of useful