Bonita World

New Year, New Post, New Bonita

2009-12-31T14:55:00.004-06:00

After being away for a long time, I am trying to restart work on this blog. A lot of things have happened and the best way to restart is to list some of them. For those of you following the Bonita project most of the things mentioned here will be already known, but it's always good to put them together.

The Bonita team and Bull chose to follow separate paths last September. That led to the creation of the BonitaSoft company. This is very good for the project, since the BPM/workflow solution will be the main product and focus of the new company.
The BonitaSoft company joined the OW2 consortium in October.
A new community website was launched in October, 23. This has more features than the existing OW2 forge, including a source code navigator, a bug tracking tool, a blog, some forums and sections with documentation and downloads.
Several milestone versions of the new major overhaul of the Bonita platform (now called Bonita Open Solution) were released. Bonita Open Solution 5.0 M5 is the latest available release. The final version is expected around February of 2010.

Here are some useful/interesting links in the new Bonita ecosystem:

BonitaSoft community site.
BonitaSoft corporate site where you should go if your employer is interested in hiring their value added services.
You can follow the latest developments by the Bonita team in Twitter, their corporate blog and their community blog. Among the interesting things you can find there are a several videos with demonstrations of the tool.

Please join me in wishing them the best for their newly formed company and contribute to the project to make the Bonita Open Solution a world class first order BPM solution, not just when compared to other open source solutions but among the commercial ones as well.

Transactional and Non-Transactional Hooks

2009-08-19T16:54:00.002-06:00

Every method call in the Bonita API, that updates the process instance state, is executed in a transactional context. That allows the Bonita engine to roll back the whole operation if one of its steps raises an exception, guaranteeing the workflow database will remain in a consistent state and the client application will not have to deal with partially executed operations (e.g.: a task was finished but the following one was not properly initiated).

Hooks are executed in the transactional context of the calling operation. It means the Bonita engine will need to know how to process them during a roll back. The workflow developer must provide that information by identifing them as transactional or non-transactional hooks.

Non-transactional Hooks

Non-transactional hooks are safe from the point of view of the Bonita engine. They do not perform any actions that need to be rolled back in case of an error in the hook itself or somewhere else in the operation and they don’t perform any updates to the workflow database. To enforce this policy, they only expose the read access APIs of the Bonita Platform: QueryDefinitionAPI and QueryRuntimeAPI to the hook programmer. It's important to note they are safe only if the hook developer respects the policy and does not perform any tasks that need to be reverted in case of error using this kind of hook.

They are ideal for operations that do not need or cannot be undone, like sending e-mails. To properly deal with situations where an operation fails after executing a non-transactional hook, the workflow developer must rely on verifications as part of the business logic, either in the business model or in the hook code itself. For example, if a non-transactional hook is used to distribute an e-mail notification, the hook itself might need to query the e-mail system about any e-mail distribution request received from that same activity before or the client application programmer might need to include code to instruct the e-mail system to stop the distribution if the API call raised an exception.

Non-transactional hooks might be run more than once, when the same operation is retried after receiving the exception and (hopefully) cleaning the situation that lead to the error in the first place. This situation must be considered and accounted for by the hook developer.

If an exception is raised during the execution of a non-transactional hook, the Bonita engine will catch it, log it and ignore it. All other changes done as part of the same activity will be completed as if no error had happened.

To include a non-transactional hook in your business process you need to follow these steps:

Create a new non-transactional hook class in ProEd, by selecting the File -> New -> Other -> Bonita BPM -> New Bonita Hook option. Please notice this sequence of commands assumes you have an open Bonita BPM project in Eclipse.
Click on Next and specify a Package name and a class name in the Java Class form and click on the Finish button. This will create a new Java class in the project, implementing the org.ow2.bonita.definition.Hook interface.
Replace the // TODO Auto-generated method stub text with your business logic for this hook.
Go to the project’s process model (XPDL file) and double click on the activity where you want to associate the hook.
Click on the Hooks tab.
Click on the Add button
In the Call Point frame, select the kind of hook you want to specify. The different kinds of hooks and their relationship with the task’s life cycle are discussed here.
In the Hook Name text field type the fully qualified name (package name plus class name) of the Java class created in steps 1 to 3.
Make sure the rollback checkbox remains unchecked. This will indicate to the workflow engine that it will be dealing with a non-transactional hook.
Click on the Ok buttons of the Add Hook and the task’s properties windows.
Complete and deploy the process in your Bonita Engine (e.g.: Bonita Console)

Transactional Hooks

Transactional hooks expose both read and write APIs to the hook programmer. They perform operations in the instance of the business process that will need to be reverted if an exception is raised. Both, exceptions raised by the hook itself and by other operations performed by the same API call will cause the hook’s operations to be rolled back.

Any changes done in external systems cannot be reverted by the workflow engine itself. If the error was raised during the hook’s execution, the hook itself is responsible for catching the exception and doing the cleaning work. If the hook’s execution finished and the exception is raised by the API call later on, those changes to the external systems won’t be undone.

To include a non-transactional hook in your business process you need to follow these steps:

Create a new transactional hook class in ProEd, by selecting the File -> New -> Other -> Bonita BPM -> New Bonita Transactional Hook option. This will create a new Java class in the project, implementing the org.ow2.bonita.definition.TxHook interface.
Perform the steps from 2 to 8 of the instructions to add a non-transactional hook to your business process. Those steps are the same for both transactional and non-transactional hooks.
Make sure the rollback checkbox is checked. This will indicate to the workflow engine that it will be dealing with a transactional hook.
Perform the steps from 10 to 11 of the instructions to add a non-transactional hook to your business process. Those steps are the same for both transactional and non-transactional hooks.

Basics of Automatic Activities

2009-07-27T06:10:00.001-06:00

When modeling business processes some activities will be assigned to a person, group, department or organizational unit. Those activities are usually named Manual Activities or Tasks. Their life cycle and the mechanisms provided by Nova Bonita to work with them were briefly described here and here.

Additionally, there are other types of activities that will not be assigned to individuals or groups but that will help the business analysts to model work that needs to be done by the workflow engine itself or by other enterprise systems (like ERPs, CRMs, mail platforms, etc.). Those activities are called Automatic Activities and the Bonita Platform implements them using hooks.

Modeling / Definition

To incorporate automatic activities into your processes you need to follow the next steps:

Create a Java class implementing the org.ow2.bonita.definition.Hook interface. This class will be responsible for performing the work associated with the automatic activity. The Bonita Engine also supports transactional hooks with the org.ow2.bonita.definition.TxHook interface. They will be discussed in an upcoming post.
Add a basic activity to the process model (XPDL) in ProEd as described in section 3.1.3 of the Bonita Quick Start tutorial.
Make sure the Performer combo box remains empty (no process participant is assigned to the activity). The process editor (ProEd) and the Bonita Engine will consider activities without a performer assigned as Automatic Activities and activities with performers associated as Manual Activities.
Select the Add button in the Hooks tab of the New Activity form.
In the Hook Name field of the Add Hook form, type the fully qualified name of the class implemented in step number one. For automatic activities the only kind of hook that can be specified is the OnEnter hook. The other kinds of hooks are not necessary since all the life cycle phases of the activity are controlled by the workflow engine, without manual intervention.
Click in the Ok buttons of the Add Hook and New Activity forms.
Complete and deploy the process in your Bonita Engine (e.g.: The Bonita Console).

Execution

The automatic activities are executed by the Bonita engine when the finishTask() method is called on the previous manual activity. For example, in the process shown below, if the finishTask() is called on an instance of Manual Activity 1, the engine will not just execute the OnFinish hook of that activity. It will also execute the OnEnter hook of Automatic Activity and the OnReady hook of Manual Activity 2.

The sequence of events for the previous process, when calling the finishTask() method for an instance of Manual Activity 1, will be as follows:

Manual Activity 1: OnFinish Hook
Automatic Activity: OnEnter Hook
Manual Activity 2: Role Mapper
Manual Activity 2: Performer Assigner
Manual Activity 2: OnReady Hook

Once the execution of the OnReady hook of Manual Activity 2 is completed the finishTask() method will return control to the caller.

Exceptions

Code executed in the context of hooks can raise exceptions for various reasons. For example, an SMTP server might be down when trying to send an e-mail. The Bonita Engine will catch all exceptions raised by non-transactional hooks (those implementing the org.ow2.bonita.definition.Hook interface), report them to the Bonita logs and will them for any other purpose. That means their impact on the execution of the processes will be minimal and the API calls will return successfully. In the case of automatic activities, that means the engine will mark them as successfully finished, even if their OnEnter hooks raised an exception.

Sending E-Mails

2009-07-06T09:54:00.006-06:00

Workflow systems usually interact with people using e-mail notifications. These e-mails help to let people know about pending tasks, approaching deadlines, events affecting them or other activities according to the nature of the business processes that were automated.

Since the Bonita engine focuses on the workflow functions and many enterprise systems already have built in e-mail functionality, there are no specific features in the engine itself to model and distribute e-mails (like an e-mail activity). This allows the workflow developers to interact with any e-mail system already deployed in their environment or to use the Java Mail API that is available in all J EE application servers.

However, for those not having an e-mail notification system already in place or unfamiliar with the Java Mail API a more simple option might be desirable. To satisfy that need, the development team has included in Nova Bonita 4.1.1 a class that makes use of the Java Mail API and the new connectors feature to allow for easy set up and distribution of e-mails.

The EmailConnector is one of the built-in connectors included with the distribution but is not hardwired in the engine itself. This allows the developers using Bonita to rely on their own e-mail solution if they what to. The connector can be called from any kind of hook and in future releases of Bonita it will be possible to set up and configure it directly from the upcoming BPM Studio.

Please notice that the connector infrastructure is just a technology preview at this time. Because of that the API can change in upcoming releases of Nova Bonita.

E-Mail Connector Set Up and usage

Create a new hook in ProEd (Eclipse), which you will use to send the e-mail. If you have defined already a hook, you can perfectly add the e-mail sending logic to the existing hook.
Import the bonita-server-4.1.1.jar library to your Eclipse project. The e-mail connector classes are not included in the bonita-client-4.1.1.jar library (imported by default when a new Bonita project is created). If the bonita-server-4.1.1.jar library is not imported to the project, Eclipse will report in-line errors (EmailConnector class cannot be resolved to a type) and the Bonita engine will generate runtime exceptions when trying to create an instance of the connector.
Import the e-mail connector class:
import org.ow2.bonita.connector.email.EmailConnector;
Create a new instance of the connector:
EmailConnector email = new EmailConnector();
Set the connector properties with the values necessary to connect to your SMTP server and the information part of the e-mail you are generating. You can see all the available properties in the connector’s source code. The Bonita Cookbook shows an example with a minimum set of properties:
email.setSmtpHost("127.0.0.1"); // Your SMTP server IP. email.setSmtpPort(25); // Your SMTP server port. email.setTo(“receiver@bonitaworld.org”); // Destination address. email.setSubject("It works!"); // The e-mail’s subject.
Validate the connector configuration is correct. The validation method will return a list of errors if the parameters were not set correctly. For example, the To field was set with an invalid e-mail address. The validation is run before the execution of the connector (next step). However, the execution method will not return the list of error and will not raise an exception because of them so you will not know the execution was not done. The list returned by the validate() method must be empty for the execute() method to run the connector logic.
List<ConnectorError> errors = email.validate();
Execute the e-mail connector. If the validate() method returned an empty list of errors, the connector will proceed to execute the e-mail sending logic. If the e-mail distribution was successful, the method will return normally. If there were any problems during the process (for example the SMTP server was down) an exception will be raised. You must catch those exceptions and add code for handling those error conditions.
email.execute();

Accessing Bonita Console's identity services

2009-06-23T06:13:00.003-06:00

Nova Bonita 4.1.1 interacts with external identity services using role mappers and performer assigners. Role mappers' function is to connect to an external service (like LDAP, ActiveDirectory, etc.) and return a list of candidates for performing a task. Performer Assigners (if specified) receive a list of candidates from the workflow engine and select the one responsible for performing the task. The selected candidate will be the only one with the task on his/her task list.

An external identity service must be provided and custom role mappers must be written as part of a Nova Bonita implementation project. However, if you are using the Bonita Console for demonstration purposes it's very likely you will want to access the eXo Platform identity services from your business processes. This will allow you to assign tasks to the eXo Platform groups and users.

The procedure to access the Bonita Console identity services (summarized below) was discussed in the Bonita forums here and here. It is composed of two main steps: the creation of the group structure in the Bonita Console and the set up of the business process model to access the service.

Creating the group structure

The following steps describe the process to create a user and group structure using the Bonita Console's user management function.

Create the necessary users. You can see a step by step description in the section Creating new users of the previous post.
Create the group structure that match or organizational needs. To create the groups you need to:
1. Select the Page Navigations button from the Doc Bar at the bottom of the page.
2. Select the Administration page from the list of pages shown.
3. Select the Community Management button from the Doc Bar.
4. Select the Group Management Option.
5. Navigate to the desired location of your group. It can be at the root of the structure or nested in another groups (e.g.: /Platform)
6. Click on the Add new group option, located in the header of the Group frame, with a + sign as icon.
7. Complete the fields in the Add new group frame and click on the Save button.
Assign the users created in step 1 to the groups created in step 2. You can see a step by step description in the section Providing access to the Users Worklist portlet of the previous post. The only difference is that in step 5 you will need to navigate to the desired group rather than to the /Platform/Console/Bonita group.

Set up the business process model

To access the group structure created in the previous section you need to define the process participants in ProEd, with the following restrictions:

The participant name must follow this format: *:<group>. For example if you created a group called /Org/BonitaWorld/Publishers and you want to assign a task to its members (set them as candidates), the task's performer must be a participant with name *:/Org/BonitaWorld/Publishers
The participant Type must be Role
The participant Mapper Type must be Custom
The participant mapper Class Name must be org.ow2.novabpm.admin.service.bonita.ExoOrganizationMapper

Warning

This mechanism to access the eXo Platform identity service will only work on processes deployed in the Bonita Console or from applications running on the same Tomcat instance than the console. Otherwise, the Bonita engine will not be able to locate the necessary classes during the role mapping phase.

Membership type

The eXo Platform identity service allows the users to specify different kinds of membership to a group. By default there are 4 membership types configured in the Bonita Console: user, member, manager and operator. If you want to assign a task to a subset of a group's members with a given membership type, you need to replace the * at the beginning of the participant name with the desired membership type.

For example, if you want to assign a task only to the managers in the /Org/BonitaWorld/Publishers group you need to set the participant name as manager:/Org/BonitaWorld/Publishers.

User management on Bonita Console

2009-06-15T06:52:00.003-06:00

The Nova Bonita console has three main functions available to the users: Users Worklist, BPM Management and User Administration. The Users Worklist allows users to create new instances of deployed processes, execute tasks in their TODO list and review the history of completed tasks. The BPM Management function allows users to manage business processes (deploy, undeploy, start, remove, etc.) process instances and activities. User Management allows the creation and management of users and their assignment to groups.

Access to these functions can be manged from the Console itself using the User Management function built-in as part of the eXo Platform. The steps below describe the processes necessary to create a new Console user and grant it the necessary access rights for each one of the functions. You will be able to find further details and screenshots in the Bonita's Cookbook document, section 8.9

Creating new users

Login as an user with user administration rights. By default only the root user has user management capabilities.
Select the Page Navigations button from the Doc Bar at the bottom of the page.
Select the Administration page from the list of pages shown.
Select the New Account button from the Doc Bar.
Complete all the required fields in the Account Setting tab of the portlet shown and optionally the fields from the User Profile tab.
Click on the Save button. The console will show a pop-up button with the result of the operation. If the user name was not in use before, the account will be added and the console will report that “You have registered a new account successfully!”
Click on the Ok button of the pop up frame.

Providing access to the Users Worklist portlet

Select the Page Navigations button from the Doc Bar at the bottom of the page.
Select the Administration page from the list of pages shown.
Select the Community Management button from the Doc Bar.
Select the Group Management Option
Navigate to the /Platform/Console/Bonita group
In the User Name text field of the Add Member frame, type the name of the user to receive access to the Users Worklist portlet.
In the Membership combo-box of the Add Member frame, select user as membership type.
Click on the Save button.

Providing access to the BPM Management portlet

Repeat the steps followed to grant access to the Users Worklist portlet, but in step 7 select operator rather than user as membership type.

Providing access to the user management functions

Repeat the steps followed to grant access to the Users Worklist portlet, but in step 5, navigate to the /Platform/Administrators group and in step 7 select manager as membership type.

Task execution in Nova Bonita (part 2)

2009-06-05T18:13:00.001-06:00

The previous post describes some basic principles related to task management in the Nova Bonita BPM platform. Hook execution, the life cycle of the tasks and the API calls necessary to manage them where among the items discussed.

A minimal application that applies those principles is provided and discussed in this post. This Java class can be compiled and run as is. Information on how build the application and set up the persistence environment can be found on previous posts. Please note some posts were written for previous versions of the Bonita platform. You will need to adjust the instructions to accommodate the changes introduced by newer versions.

Full Code

package org.bonitaworld;

import java.util.Iterator;
import javax.security.auth.login.*;
import org.ow2.bonita.facade.*;
import org.ow2.bonita.facade.exception.*;
import org.ow2.bonita.facade.runtime.*;
import org.ow2.bonita.facade.uuid.*;
import org.ow2.bonita.util.*;

public class TaskExecutionExample {

  public static void main(String[] arguments)
    throws LoginException, 
           TaskNotFoundException,
           IllegalTaskStateException,
           ActivityNotFoundException,
           VariableNotFoundException{

    TaskUUID taskUUID;
    String whatAction;
    LoginContext loginContext;
    ActivityInstance currentActivity;
  
    loginContext = 
      new LoginContext("Bonita",
                       new SimpleCallbackHandler("john", "bpm"));

    loginContext.login();
        
    RuntimeAPI runtimeAPI = AccessorUtil.getRuntimeAPI();
    QueryRuntimeAPI queryRuntimeAPI = AccessorUtil.getQueryRuntimeAPI();

    Iterator<ActivityInstance<TaskInstance>> myIterator =
      queryRuntimeAPI.getTaskList(ActivityState.READY).iterator();
     
    while (myIterator.hasNext()){

      currentActivity = myIterator.next();
      taskUUID = currentActivity.getBody().getUUID();
      runtimeAPI.startTask(taskUUID, true);

      whatAction = 
        (String)queryRuntimeAPI.getVariable(currentActivity.getUUID(),
                                            "Action");
       
      if (whatAction.compareTo("SUSPEND") == 0){
        runtimeAPI.suspendTask(taskUUID, true);
      }else {

        runtimeAPI.setVariable(currentActivity.getUUID(),
                               "Action",
                               "SUSPEND");
        
        runtimeAPI.finishTask(taskUUID, true);

      }
    }

    loginContext.logout();

  }
}

Line by Line Explanation

public static void main(String[] arguments) throws LoginException, TaskNotFoundException, IllegalTaskStateException, ActivityNotFoundException, VariableNotFoundException

Exceptions are not properly managed in this example to reduce the complexity. In production applications, each kind of exception must be managed with try/catch blocks at the points where they are originated.

loginContext = new LoginContext("Bonita", new SimpleCallbackHandler("john", "bpm")); loginContext.login();

The default identity service included in the Bonita Platform distribution requires the applications to log in using the JAAS standard API. This sample application uses a very simple login module provided with the distribution, and the JAAS configuration file jaas-standard.cfg, located in the bonita-runtime-4.1.1/conf folder.

RuntimeAPI runtimeAPI = AccessorUtil.getRuntimeAPI();

This code provides the programmer with access to the Runtime API

QueryRuntimeAPI queryRuntimeAPI = AccessorUtil.getQueryRuntimeAPI();

This code provides the programmer with access to the Query Runtime API

Iterator<ActivityInstance<TaskInstance>> myIterator = queryRuntimeAPI.getTaskList(ActivityState.READY).iterator();

The getTaskList(ActivityState.READY) returns all the activities assigned to the currently logged in user that are in READY status. This function can be used to get a list of activities in any other status or assigned to different users if that is necessary. The method returns a java.util.Collection with elements of ActivityInstance type. This instruction directly retrieves the java.util.Iterator to process the tasks, but any other manipulation of the Collection object is allowed. All activities in this list were processed previously by the BPM engine. That preprocessing included the execution of the OnReady hook, the Role Mapper and the Performer Assigner.

taskUUID = currentActivity.getBody().getUUID();

Tasks are the body of manual activities in the Bonita API. This function retrieves the UUID (Universal Unique IDentifier) of the task. This object is necessary to manage the task's life cycle.

runtimeAPI.startTask(taskUUID, true);

The startTask() function signals to the Bonita Engine that it needs to move a task from the READY status to the EXECUTING one. This allows the system to know when a user started to work on one of the items on his/her TODO list. As part of this function call, the engine executes the OnStart hook.

whatAction = (String)queryRuntimeAPI.getVariable(currentActivity.getUUID(), "Action");

One important function that allows the communication between front-end applications and the instances of the business processes managed by the Bonita Engine is the retrieval of variable values. The getVariable() method implements that function. In this case the value of a variable called Action is retrieved to take business decisions later on.

if (whatAction.compareTo("SUSPEND") == 0){

This code makes use of a process variable value to instruct the application regarding the business logic to execute. In the case of this example, if the Action variable has the value SUSPEND, the task will be suspended. Otherwise, the task will be normally finished and the engine will move the process to the next activities.

runtimeAPI.suspendTask(taskUUID, true);

The suspendTask() function changes the status of the task refered with with UUID from EXECUTING to SUSPENDED. It will triger the execution of the OnSuspend hook as well.

runtimeAPI.setVariable(currentActivity.getUUID(), "Action", "SUSPEND");

The setVariable() function is the partner of QueryRuntimeAPI.getVariable(). It allows the front end application to change the value of the process and instance variables. It receives the UUID of the activity where the variable value is going to be updated, the variable name and the value to store.

runtimeAPI.finishTask(taskUUID, true);

Once the application users complete a human activity (task) the BPM engine needs to be notified. The finishTask() method allows the applications to do that. It moves the status of the provided task from the EXECUTING to the FINISHED status and it triggers the execution of the OnFinish hook. Additionally, it's during the execution of this method that the workflow engine works to determine the following activities to execute. Once it has reached the next manual activities, it creates the corresponding tasks, executes their Role Mappers, Performer Assigners and OnReady hooks.

Task execution in Nova Bonita (part 1)

2009-06-01T06:32:00.004-06:00

Task execution is one of the major functions to be performed by the applications implementing workflow capabilities with the Nova Bonita BPM engine. Tasks are instances of manual activities, assigned to a user or a group of users and can be managed by a set of 5 basic API calls in the Nova Bonita API. Those methods move the task across the different status of its life cycle and trigger the execution of the associated components set up in the ProEd editor.

The following table describes the relations between the API calls, the task’s status and the calling sequence for the components set up in the business process model. The table rows are sorted according to their execution order, from top to bottom.

Bonita API Calls	Components Called	Task Status
Previous task’s `finishTask()` call or `instantiateProcess()` call when the task is the first in the business process	Role Mapper Performer Assignment Hook: OnReady	READY
`startTask()`	Hook: OnStart	EXECUTING
`suspendTask()`	Hook: OnSuspend	SUSPENDED
`resumeTask()`	Hook: OnResume	EXECUTING or READY
`finishTask()`	Hook: OnFinish Next task’s Role Mapper Next task’s Performer Assignment Next task’s Hook: OnReady	FINISHED

Life Cycle (Task Status)

The life cycle of the tasks is composed of 4 main status: READY, EXECUTING, FINISHED and SUSPENDED. Tasks in READY status are those available for execution by one of the human users of the workflow system. The tasks in READY status, assigned to a user, form the TODO list (or worklist) of that user. A task status changes from READY to EXECUTING once it is selected from that list and the user starts working on it. At this point a task can be suspended, moving it temporally from EXECUTING to SUSPENDED state and the work can be resume moving it back from SUSPENDED to EXECUTING. Finally, the task moves to FINISHED status when the user has completed the task. You can see a graphical representation of the life cycle in the picture below, which is anotated with the API calls that execute the transitions.

Bonita API Calls

There are 5 main API calls that can be used to manage the life cycle of the tasks across the status mentioned above. Those calls have many variations and the methods themselves can perform the actions under a wider set of conditions than described here. However, for the sake of simplicity, this post focuses on their basic functionality. For more information you can check the Javadocs included with the bonita-runtime-4.1.1 package.

QueryRuntimeAPI.getTaskList(ActivityState.READY)
The getTaskList() method, when called with the ActivityState.READY parameter, returns the list of tasks that can be executed by the current logged in user. This list of tasks forms the TODO list for the user and once it is available to the client application, it can be iterated and the user can pick up a task to execute.
RuntimeAPI.startTask(TaskUUID, boolean)
The startTask() method moves the activity from the READY to the EXECUTING status, signaling the start of the work on the task by the human user of the system.
RuntimeAPI.suspendTask(TaskUUID)
RuntimeAPI.resumeTask(TaskUUID)
These methods allow the movement of the tasks between the EXECUTING and SUSPENDED status. The main purpose of the SUSPENDED status is to allow the application users to record that they will not work continually in a task, which is a common situation on long running process steps like the ones usually modeled as human activities. One of the main benefits of this status is that the system will be able to accurately record the time spent working on a task. The suspendTask() method can be called either after the startTask() method (while the task is in EXECUTING status) or before it (while the task is in READY status).
RuntimeAPI.finishTask(TaskUUID, boolean)
The finishTask() method moves the activity from the EXECUTING to the FINISHED status and indicates to the workflow engine that it needs to move the process to the next activity. Once the execution of this method is completed, the task is considered finished and the Bonita BPM engine will take care of identifying the next activities to execute and the responsible parties, in order to continue the execution of the process instance.

Components Called: Hooks

When modeling a business process with ProEd, the modeler is able to reference hooks (Java classes) to integrate the process with back end systems or to access services external to the client application or the workflow engine. There are 5 different types of hooks that can be associated with a manual activity in the business process: OnReady, OnStart, OnSuspend, OnResume and OnFinish.

The OnReady hook is called when the a task becomes available for the users to pick up and execute it. The hook is called as part of the finishTask() method when called in the previous manual activity or as part of the instantiateProcess() method, when the task is an instance of the first manual activity in a process. As the responsible to identify all the activities that need to be run after a task is completed, the finishTask() method takes care (among other things) of creating all the necessary tasks and calling their OnReady hooks.

The OnStart hook is called as part of the startTask() method, that signals the user’s intention to start working on the associated task, selected from his/her TODO list.

The OnSuspend and OnResume hooks are called as part of the corresponding API calls [suspendTask() and resumeTask()].

The OnFinish hook is the last piece of back end code that is executed as part of a task and is intended to allow for final processing after a task is completed (as specified by the client application by calling the finishTask() method) but before the next activities are determined by the system.

Role Mapper and Performer Assigners

The Bonita Workflow Engine uses Role Mappers and Performer Assigners to determine what user or group of users is responsible to perform a task. The code associated to these functions is executed before the task’s OnReady hook. The first of them is the Role mapper. This function provides the engine with a list of candidates to perform the task. Once the Role Mapper is executed the Engine proceeds to execute the Performer Assigner (if there is any) and it determines the assigned user that must perform the task. The TODO list of a user is formed by all the tasks where he or she was assigned as responsible and those tasks without assigned user that include him or her in the list of candidates.

Final Comments

The elements discussed here are only a high level review of the main concepts behind the task management function in the Bonita BPM Platform. Once you have being able to retrieve, process and finish tasks in your application code, you will want to refer to the documentation (Javadoc, Cookbook and Quick Start files) to take full advantage of the workflow engine capabilities.

Bonita 4.1.1 was released

2009-05-25T06:17:00.002-06:00

Last week the Bonita development team released the version 4.1.1 of the Nova Bonita platform. This version is a maintenance release with several bug fixes for all the components of the platform: the process editor, the console and the run-time environment.

In addition to the bug fixes, this version includes a preview of the connectors functionality that is under development by the team. With this new feature, the developers will be able to encapsulate functionality in Java classes called connectors and access it from the process hooks. In future versions, once the BPM Studio is released, it will be possible for the process designers to load, configure and use the connectors without the need to write any Java code.

The current version has several build-in connectors. The most notable of them are a SMTP connector for sending e-mails without the need to use the Java Mail API and a connector to perform searches on identity services that comply with the LDAP standard.

In the section 7.11 of the updated Cookbook document (located in bonita-runtime-4.1.1/doc), you will find instructions to use the existing connectors and to create new ones that suit your needs.

Accessing a Bonita J EE deployment with the Console

2009-04-08T06:50:00.000-06:00

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:

Set the API Type variable.
Set the initial context properties.
Include the client libraries.
JAAS settings to propagate the client security identity.
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.

Database settings for user management in the Bonita Console

2009-04-01T06:54:00.008-06:00

The user management of the Bonita Console is delegated to the Exo Platform application. Because of that no tables for users and roles are created when initializing the databases of the workflow engine.

Exo Platform has it's own Hibernate connection that creates a database for user management using the HSQLDB database engine. If that solution is not suitable to your needs, it can be reconfigured to use an alternative database engine, just like the Bonita engine.

These are the steps necessary to make that change:

If you haven't done it yet, download and unzip the Nova Bonita Console file (bonita-console-4.1.zip file)
Go to the bonita-console-4.1/webapps folder and delete the folder called portal if it is present. This will help to make sure the Tomcat application will redeploy the modified portal.war file.
Copy the portal.war file to an empty folder in a suitable location.
Open a command prompt/terminal window pointing to the folder were the portal.war file was copied in the previous step.
Extract the contents of the portal.war file. The default JAR utility included with the JDK can be used for this purpose:
> jar xvf portal.war
Delete the copied portal.war file.
Create a database in your database server for Exo to store the users and roles.
Change the database settings by following the instructions on the following page of Exo's knowledge base. The supported values for the dialect parameter described in section 3 are:
hsqldb, mysql, mysql-utf8, pgsql, oracle, oracle-oci, mssql, sybase, derby, db2, db2v8
Create a portal.war file with the modified files by using the JAR utility:
> jar cvf portal.war *
Copy the generated portal.war file to the deploy folder of Tomcat: bonita-console-4.1/webapps
Start the console for the Exo platform to create the necessary tables in the database and populate the default user's and roles.

Alternative Configuration Modes

The Exo platform comes bundled with support for LDAP and Active Directory. If you prefer to use those environments, you will need to follow the instructions in this page in addition to those specified in step 8.

Connecting to Bonita in an AS (part II)

2009-03-31T06:38:00.001-06:00

Once the Bonita Runtime engine is deployed in an application server, it can be accessed from a remote client or from applications running in the same server, like EJBs, Web Modules (JSPs, Servlets, JSF, etc.) or Web Services.

To access the engine from the same application server you need to:

Create the client J EE application
Include the Bonita Client library
Set the org.ow2.bonita.api-type variable
Deploy the client application

Create the client J EE application

First, you need to code your application, as described in the Cookbook document. The Bonita API is designed in such a way that your code will not need to change if you move from an embedded engine to one deployed in an application server or vice versa.

Include the Bonita Client library

The Bonita API classes need to be included in your application's classpath.

At this point, it is important to understand correctly the class loading policy configured in the target environment. If the classes of the deployed applications are isolated from each other you will need to include the bonita-client-4.1.jar library in your application's classpath.

However, if the target application server has a flat class pool (like JBoss' default settings), including the Bonita client library will generate exceptions (usually ClassCastException) when trying to use the Bonita API. This is because some of the classes in the client library are present as well in the bonita.ear file and the application server will not know which one to use.

In that case, you have 2 options. The first one is to make sure the bonita-client-4.1.jar library is NOT included in your application (avoiding the duplication of deployed classes). The other option is to reconfigure your environment to isolate the classes of different application packages.

Set the org.ow2.bonita.api-type variable

Since you are working with a Bonita engine deployed in an application server, you need to set the org.ow2.bonita.api-type system property to the corresponding value. It will be either EJB2 or EJB3, according to the type of EJB container that you are using. It should match the Ant task used to create the bonita.ear file: ear.ejb2 or ear.ejb3.

Deploy the client application

Once you have coded and build your application and your environment is ready, the final step is to deploy it. There are not special considerations required when using Bonita, so you just need to follow the instructions of your vendor. In JBoss, you will need to copy your application package (EAR, JAR or WAR) into the deploy folder and the server will take care of everything else.

Connecting to Bonita in an AS (part I)

2009-03-18T06:40:00.001-06:00

The Bonita platform can be deployed in an application server and accessed from a remote client. To archive that, the applications must run on an client application container but the set up details for that will change between environments.

To connect to a Bonita Runtime engine deployed in a JBoss server you need to:

Install the Bonita Runtime engine in an application server. You can see how to do that here.
Include the bonita-client-4.1.jar library in your application’s classpath. It can be found in the bonita-runtime-4.1/lib/client folder.
Include in your application’s classpath all the libraries that form part of your application server's client container. In the case of the JBoss AS, they are located in the ${jboss.home}/client folder.
Set up the properties required by the JNDI provider of your application server, so that your client code knows where the server lives. These properties will change between different application servers. In the case of JBoss those properties are:
java.naming.factory.initial=org.jnp.interfaces.NamingContextFactory java.naming.provider.url=jnp://localhost:1099 java.naming.factory.url.pkgs=org.jboss.naming:org.jnp.interfaces
The preferred method to set up those properties is including a jndi.properties file in your application’s classpath. You will need to change the host name (or IP) and port number in the java.naming.provider.url property to those of your application server installation.
Set the org.ow2.bonita.api-type system property with value EJB3 or EJB2 according to the EJB container supported by your application server.
Build and run your application.

Steps 3 and 4 are specific to JBoss, you will need to check your system's documentation to identify how to address those items. The other steps are general for Bonita and should not change between application servers.

Deploying Bonita in an application server

2009-03-16T07:12:00.005-06:00

The Nova Bonita 4.1 workflow engine can be deployed as a Java Enterprise application in any compliant server. The default distribution includes all the necessary files to deploy directly into the JBoss and Jonas application servers, in both EJB 2 and EJB 3 versions.

The following steps describe how to deploy the engine in the JBoss application server:

Unzip de the Bonita engine found in the bonita-runtime-4.1 file.
Update the hibernate-core.properties and hibernate-history.properties files in the bonita-runtime-4.1/conf folder with the settings necessary to connect to the databases you defined for your workflow systems. There are instructions on how to do that here and here.
Make sure the database drivers necessary to access your database are available in the server's classpath. In JBoss, you can do that by adding them to the ${jboss.home}/server/default/lib folder (assuming that you are using the default configuration) or you can put them in the bonita-runtime-4.1/lib/server folder. Since you need to add the drivers to the latter in order to create the database schemas, it is possible that they will be there at this point, so you need to check they are only in one of the two places mentioned above to avoid any possible class loading conflicts.
Install the Apache Ant tool in your system if you don’t have it already. It can be downloaded from here. Installation instructions can be found here.
Open the bonita-runtime-4.1 folder in a terminal window/command prompt and run the command:
> ant ear.ejb2
if you are planning to deploy to an EJB 2 server or:
> ant ear.ejb3
if you are planning to deploy to an EJB 3 server.
Deploy the bonita.ear file created in the previous step to your application server installation. It will be located in bonita-runtime-4.1/ear/ejb2 if you ran the first task or in bonita-runtime-4.1/ear/ejb3 if you ran the second one. To perform the deployment in JBoss you just need to copy the ear file to the deploy folder, usually ${jboss.home}/server/default/deploy (again, assuming that you are using the default configuration).

Security

It is necessary to consider that the default deployment (as described here) does not secure the services provided by the EJBs. You will need to secure them using standard J EE security mechanisms before using the Bonita runtime engine in a production environment.

Alternative application servers

Steps 3 and 6 will change if you are working with an application server other than JBoss AS but they will be required never the less.

Additionally, step 5 will create an EAR that can be deployed without change in the JBoss, Jonas and EasyBeans systems. If you are working in other environment (e.g.: IBM WebSphere, Oracle WebLogic, Apache Geronimo, etc.) it will be necessary to include any additional files required by your platform in the resulting package.

Setting up Bonita 4.1

2009-03-12T07:02:00.007-06:00

The new version of Nova Bonita is an incremental improvement, making it very similar to its predecessor. That makes the installation procedures almost the same as described before in this post. However, there are several differences that need to be taken in account when starting to work with this new version.

Business Process Editor (ProEd)

The Eclipse plugin version of ProEd comes with several bug fixes and improvements described before. However, from an installation point of view, the only notable difference is that the plugin is distributed as a JAR file rather than a folder like in Bonita 4.0.1. However, this change does not have any effect in the end user functionality.

When installing the new process designer, it is important to remove the previous version of the editor (org.ow2.proed_4.2.1) from Eclipse before deploying the new version (org.ow2.proed_4.2.2).

Database Engine

The default database engine was changed to H2 (rather than HSQLDB), that provides better performance and transactional support.

If you want to change the default engine (useful only for testing purposes), the database initiation can be performed exactly in the same way than in Bonita 4.0.1, except that the hibernate.properties file is no longer required, so you can skip step number 6 of this post.

One important difference is that the default settings in Bonita do not longer use the Hibernate cache functionality. This change helps to avoid problems when using different Bonita instances to access the same database, a use case discussed very often in the Bonita forums. Unless you are proficient in Hibernate, I would stick with the default settings, even if using only one Bonita instance to access the databases.

As with the previous version, to set up the Bonita Console to use your new databases you need to replace the Hibernate files in bonita_console_4.1/conf with your own and provide your database drivers in bonita-console-4.1/lib.

Embedding in Applications

When embedding Bonita in your own application (described here and here) there are 2 main changes that it is necessary to consider:

The environment.xml and environment-xml-history.xml files were merged, now you only need to provide a single file called bonita-environment.xml.
The packages hosting the security classes (sample JAAS login modules and identify services) were changed from org.ow2.novabpm.identity.auth to org.ow2.bonita.identity.auth. You need to verify your JAAS configuration file to make the necessary changes and make sure you include in your application's classpath the JAR files located in bonita-runtime-4.1/lib/easybeans in addition to the ones under bonita-runtime-4.1/lib/server.

Migration from Bonita 4.0.1

One final aspect to consider is that there are several changes to the database schema between versions 4.0.1 and 4.1. Because of that, it is not possible just make a Bonita 4.1 engine work with an existing Bonita 4.0.1 database. The recommended path here is to let the existing processes finish in their Bonita 4.0.1 environment and then code your application to start all new processes in a separated instance of Bonita 4.1

Nova Bonita 4.1

2009-03-09T07:13:00.007-06:00

Today the development team of the Bonita open source workflow engine released version 4.1 of the platform, including changes to the runtime engine, the process editor and the management console.

This new version has lots of bug fixes and new features. Among them:

The documentation was restructured in 2 different documents a Quick Start guide (like in Bonita 4.0.1) and a Cookbook that includes the information of the other three documents of the previous version (Console Guide, Development Guide and Reference Guide). This eliminates the existing duplication of concepts between the different documents.
The create project wizard in the Eclipse process designer (ProEd) was improved to allow the creation of an XPDL file directly from there (if the user wishes to do so), rather than having to create the project and then going to create the file. Additionally, the default transition from the start to end activities was removed.
The Bonita Runtime environment.xml and environment-xml-history.xml files were merged into a new bonita-environment.xml file.
Join XOR operations and asynchronous activities (with some limitations) are supported by the engine and the process editor.
Additionally, several bugs were fixed and the APIs were improved in several areas.

This is not the full list of improvements, but the ones I was more interested on. For the full list, please check the release notes. You can download Nova Bonita 4.1 from the files section of the project's forge in OW2.

The next major milestones will be the support for XPDL 2.0 and BPMN. You can check the full list in the project's roadmap page.

Embedding Bonita in web applications

2009-02-25T07:53:00.001-06:00

It is possible to embed Bonita 4.0.1 on web applications just line it can be done on desktop ones. The basic steps are the same. Here I will describe how to do the deployment on Tomcat 6.0.18:

Add the Bonita libraries in bonita-runtime-4.0.1/lib/server to the application's classpath, except for the servlet-api-2.3.jar library, since this one will conflict with Tomcat's own servlet library. In the case of applications deployed as WAR files in Tomcat, they must be located in the WEB-INF/lib folder.
Add the environment.xml, environment-history.xml, hibernate.properties, hibernate-core.properties and hibernate-history.properties files to the application's classpath. In WAR packages this can be done by adding the files to the WEB-INF/classes folder.
Add the JAR files with your database driver's to Tomcat's lib folder.
Configure your web application to use JAAS security with a login module of your choice. Detailed instructions on how to do that in Tomcat 6.0 are available here.
Modify your JAAS configuration to include the login module required by the Bonita Engine: org.ow2.novabpm.identity.auth.StorageLoginModule. It must be flagged as required and it must be the last in the chain of login modules you have configured for your application. No one of the login modules configured must be flagged as sufficient. If you do so and one of the login modules succeed, the control will return to the application before actually running Bonita's module. This will make the Bonita engine to raise a security exception.
Add the system property org.ow2.bonita.api-type with Standard value to the JAVA_OPTS environment variable. This can be done editing the catalina.bat file found in the bin folder of the Tomcat distribution.
Compile and deploy your application.

In general, Bonita is not affected if deployed embedded in a web application or in a desktop one, as long as the necessary resources are available in the classpath. The only limitation is imposed by the use of a system property to specify the API type (either EJB2, EJB3 or Standard) because it is system wide, meaning that you cannot have in the same Tomcat server an application with Bonita embedded and another with Bonita as a client to a server deployed somewhere else.

Standalone application set up

2009-02-18T07:33:00.005-06:00

Nova Bonita 4.0.1 can be deployed as an embedded library part of Java Standard Edition applications. To do that you need to follow the steps listed below:

Take the environment.xml and environment-xml-history.xml found in the bonita-runtime-4.0.1/conf folder and include them in your application's folder.
Customize the Hibernate properties files (hibernate.properties, hibernate-core.properties and hibernate-history.properties) according to your database settings (more details can be found on this post) and include them in the same folder you included the XML files mentioned in the previous step.
Add the folder that contains the configuration files provided in steps 2 and 3 to the classpath of your application.
Add the database drivers necessary to support the selected database engine (configured in step 2) to your application's classpath.
Add all the libraries (JAR files) found in the bonita-runtime-4.0.1/lib/server folder to your application's classpath.
Include in your application a JAAS configuration file. The bonita-runtime-4.0.1 package includes a sample file called jaas-standard.cfg (located in the bonita-runtime-4.0.1/conf folder) that can be use to get things up and running quickly, but it is not suitable for production use.
Set the system property java.security.auth.login.config with the path of the jaas-configuration.cfg file.
Set the system property org.ow2.bonita.api-type with the value Standard to signal the use of Bonita as an embedded engine.
Run the application!

Setting a security environment (steps 6 and 7) and performing a JAAS login in the application are necessary for the Bonita Engine to work properly. The default jaas-configuration.cfg file provided has a very simple implementation of security that lists the user names and passwords in the configuration file itself and must be replaced with a real login module for use with any production application.

Java objects for XPDL data types

2009-02-13T07:22:00.008-06:00

The Bonita workflow system allows the programmers to access the values of XPDL variables (both process and activity variables) by means of its application programming interface (API). That access is provided by 2 methods, part of the QueryRuntimeAPI object:

getVariable()
getActivityInstanceVariable()

They receive the UUID (Universally Unique IDentifier) of the activity to be used as a reference to get the data and a string with the name of the variable in the XPDL file (process model). In turn, they return a Java object of type java.lang.Object that must be cast to the appropriate Java type, according to the type defined for the variable.

In Nova Bonita 4.0.1, the match between XPDL variable types and Java objects is as follows:

XPDL Variable Type (ProEd)	Java Object (Bonita API)
Integer	`java.lang.Long`
Float	`java.lang.Double`
Boolean	`java.lang.Boolean`
Date	`java.util.Date`
String	`java.lang.String`
Enumeration	`org.ow2.bonita.facade.runtime.var.Enumeration`

The Enumeration Java object is part of the Bonita API and provides 2 methods to access of the Enumeration variables:

getPossibleValues(): Returns a java.util.Set of Strings with the list of possible values that this variable can take. Those values are the ones defined by the process developer or business analyst in the ProEd designer.
getSelectedValue(): This method returns a String with the value of the variable. It is always going to be one of the possible values defined in the ProEd designer and it will be part of the list of values returned by the getPossibleValues() method.

Example

As an example, the Java code to access an Integer variable called "myInteger" would look like as follows:

APIAccessor a = AccessorUtil.getAPIAccessor(); QueryRuntimeAPI q = a.getQueryRuntimeAPI(); Object o = q.getVariable(activityUUID, "myInteger"); Long l= (Long)o; long number = l.longValue();

How to change the database engine

2009-02-09T07:22:00.000-06:00

One of the first tasks that needs to be done when working with the Bonita workflow engine, is to change the default database. Both the Bonita Console and the Bonita Runtime packages come bundled with a default engine called HSQLDB that allows the users to quickly start working without the need to configure a database management system. HSQLDB is a very powerful tool when embedded databases are necessary, but it's not suitable when a full featured database is required.

To use an alternative database engine two main steps are required. The first one is to create the databases on the database management system and the second one is to configure the engine to use it. Here I will describe how to create the databases and how to configure the Bonita Console to use them. I will talk on how to configure custom made applications on later posts.

Creation of the Database Schema

Create 2 databases in your database management system. One for the definition and runtime information (called by default: bonita_core) and other for the history information (called by default: bonita_history). Their default names can be changed to others that match your naming conventions.
Download and unzip the Bonita Runtime package (bonita-runtime-4.0.1). This package includes the Ant script and the libraries required to create the database schemas.
Add the database driver files to the bonita-runtime-4.0.1/lib/server folder.
Update the hibernate-core.properties file (located in the bonita-runtime-4.0.1/conf folder) with the information of your bonita_core database and database management system. There are 3 properties in there that are specific to the database engine: hibernate.dialect, hibernate.connection.driver_class and hibernate.connection.url. At the top of the default properties file, there are sample values for all the supported systems (HSQLDB, MySQL, PostgreSQL and Oracle). Additionally, you need to update the database user name and password that the script will use to create the schema, using the properties hibernate.connection.username and hibernate.connection.password.
Update the hibernate-history.properties file with the information of your bonita_history database. This file is located too in the bonita-runtime-4.0.1/conf folder and the properties to modify are the same ones described in the previous step.
Create a hibernate.properties file as a copy of hibernate-core.properties
To create the core database, run the Ant script from the base of the runtime package folder: > ant init-db. When the script requests you to provide the Hibernate configuration to use, type hibernate-configuration:core
To create the history database, run the script like in the previous step, but provide hibernate-configuration:history as the Hibernate configuration to use.

Database Configuration for the Console

To use the new defined databases with the Bonita Console, you need to replace the default Hibernate properties files with the ones updated in steps 4 and 5 of the procedure listed above and restart the console. Those files are located in the conf folder of the console: bonita-console-4.0.1\conf.

Dynamic options in combo boxes

2009-02-03T06:50:00.002-06:00

As discussed previously, the forms automatically generated by the Bonita Console can be customized. One case where that customization feature is useful is when you need to load a dynamic list of options in a combo box component, rather than using a list statically defined at deployment time. This case was discussed in the Bonita Forums during January. Since the thread is a bit long and the final solution is described across many messages, I will post a summary here.

The Bonita Console application makes use of the eXo Platform Web UI toolkit. That means that just painting and defining HTML components as part of the form is not going to work. To modify them it is necessary to use the API of the Web UI Framework. With that API you need to perform the following steps:

Import the class for the combo box option object. The class is called SelectItemOption and its part of the libraries included by default in the Bonita Console. That means there is no need to provide any additional JAR files to use it.
import org.exoplatform.webui.core.model.SelectItemOption;
Define a list of options. It will store the different elements that will be displayed by the combo box and it's initially defined as empty.
def List<SelectItemOption<String>> comboBoxOptions = [];
Create the different combo box options you need and add them to the list. The method for retrieving the information that will be displayed in the options is specific to the application being develop, so it will not be described here.
comboBoxOptions << new SelectItemOption("First Item"); comboBoxOptions << new SelectItemOption("Second Item"); comboBoxOptions << new SelectItemOption("Third Item");
Retrieve the combo box component by using the variable name. The uiform variable (quickly described in another post) provides access to all of the form objects by using the name of the variable that they are going to display.
def comboBoxVariable = uiform.getUIFormSelectBox("variableName");
Add the new list of options to the combo box, replacing the default one.
comboBoxVariable.setOptions (comboBoxOptions);

Once all the previous steps have been performed the combo box component can be rendered using the standard mechanism.

Customization of Bonita Console forms (part 3)

2009-01-30T07:50:00.008-06:00

In the previous posts I described some tips to take in account while customizing the Bonita Console forms and the main objects and methods available to the programmer while writing Groovy templates to change the look and feel of the forms. Today I will provide a quick review of the structure of a minimal Groovy template for displaying the variables and actions defined in the forms.xml file.

The full code is shown below and then it is explaned line by line.

Full Code

<div>
  <% def translations = uicomponent.getWorkflowBundle(); %>
  <% uiform.begin(); %>
  <% for(inputInfo in uicomponent.getInputInfo()) { %>
    <p>
      <%=inputInfo.getLabel() %>:
      <% uicomponent.renderField(inputInfo.getInput()); %>
    </p>
  <% } %>
  <% def buttons = uicomponent.getSubmitButtons(); %>
  <% if(buttons.isEmpty()) { %>
    <p>
      <a href="<%=uicomponent.event("EndOfState")%>">
        <%=translations.getString("submit")%>
      </a>
    </p>
  <% } else { %>
    <% for(button in buttons) { %>
      <% buttonname = button.get("name") + ".submit"; %>
      <p>
        <a href="<%=uicomponent.event("Transition", button.get("name"))%>">
          <%=translations.getString(buttonname)%>
        </a>
      </p>
    <% } %>
  <% } %>
  <p>
    <a href="<%=uicomponent.event("Cancel")%>">
      <%=translations.getString("cancel")%>
    </a>
  </p>
  <% uiform.end(); %>
</div>

Line by Line Explanation

<div>

The Exo Platform mechanism requires the code to be enclosed in a div block to be able to properly separate it from the rest of the frame. Otherwise it will not be able to properly manage the frames and windows displayed at the same time. This tag must be properly closed at the end of the template.

<% def translations = uicomponent.getWorkflowBundle(); %>

This code retrieves a reference to the resource bundle that provides access to the labels to be used for internationalization purposes.

<%= translations.getString("title"); %>

This function allows you to retrieve any key present in the properties file of the customized task (e.g.: submit, cancel, title, etc.)

<% uiform.begin(); %>

The components corresponding to the variables defined in the forms.xml file must be drawn in a form. This function emits the HTML tags necessary to start that form.

<% for(inputInfo in uicomponent.getInputInfo()) { %>

As mentioned in the previous post, the getInputInfo() function returns a list of objects representing each one of the fields defined with the variable tag in the forms.xml file. This list is iterated, so that every component can be added to the user interface.

<%=inputInfo.getLabel() %>:

The getLabel() function returns the internationalized version of the label for the component. This information can be retrieved with the resource bundle as well; however, this utility method avoids the need for checking the variable name in the template code.

<% uicomponent.renderField(inputInfo.getInput()); %>

The renderField() functions is the utility method in charge of displaying the components. This function makes use of the information in the forms.xml file to identify the type of component and other information.

<% def buttons = uicomponent.getSubmitButtons(); %>

If there are any submit buttons defined in the forms.xml file, this function returns a list that gives access to their names, allowing their inclusion on the template.

<% if(buttons.isEmpty()) { %>

If no submit buttons were defined, it is necessary to provide a default submit action that will allow the users to move the process forward. If you are developing a template for an specific activity this checking might be unnecessary, since you will know beforehand if any submit buttons were defined.

<a href="<%=uicomponent.event("EndOfState")%>">

In case no submit buttons are defined in the forms.xml file, the event() function, called with the value "EndOfState" will return the link to the function that will complete the current task and move the process forward.

<% for(button in buttons) { %>

In case that some buttons were defined, the collection must be iterated, so that every button returned by the engine is displayed in the form.

<% buttonname = button.get("name") + ".submit"; %>

As specified in the Bonita Console guide, the button names are defined in the properties files with the name of the button plus the suffix ".submit"

<a href="<%=uicomponent.event("Transition", button.get("name"))%>">

To get the link to activate the corresponding function, the event() method must be called with the "Transition" value and the name of the button as an extra parameter.

<a href="<%=uicomponent.event("Cancel")%>">

The Bonita Console offers a predefined function that allows the user to get out of the task without making any changes to the status of the workflow or its variables. That function can be called providing "Cancel" as parameter for the event() method.

<% uiform.end(); %>

Generates the closing tag for the form (</form>)

Customization of Bonita Console forms (part 2)

2009-01-27T06:50:00.001-06:00

In the last post I mentioned that the Bonita Console allows customization of the automatically generated task forms by means of a forms.xml file, a set of language properties files and a template that mixes HTML and Groovy code.

Since the functions needed are not just plain old code, but are specific of the structure provided by the eXo platform Web UI Framework and the Bonita Console application, some comments on it's basics might be helpful for people customizing the forms.

Major Objects

There are 2 major objects available to the HTML fragment writer: uiform and uicomponent.

uiform object:

This object has 2 main methods that allow the definition of the form. begin() generates the HTML code necessary to start the form while end() generates the closing tag for the form. Calls to these functions must enclose the code that draws the different fields and actions in the form.

uicomponent object:

The uicomponent object gives access to the input fields for the variables and actions defined in the forms.xml file [getInputInfo(), getSubmitButtons()] and provides utility methods to draw the input fields [renderField()] and the actions [event()]. Additionally, the values defined in the properties file for internationalization purposes can be access from the object returned by the getWorkflowBundle() function, like in the example below:. For example:

uicomponent.getWorkflowBundle().getString("submit")

getInputInfo() collection:

The getInputInfo() method of the uicomponent variable returns an array of input fields. Each one of the input fields in that list provides 3 methods that allow the drawing of the components. The isMandatory() method lets the programmer know if the field was flagged as mandatory in the forms.xml file, the getLabel() method provides access to the internationalized label for the component (specified in the properties file) and the getInput() method returns a reference to the component, that allows the renderField() method of the uicomponent variable the rendering of the field.

getSubmitButtons() collection:

The getSubmitButtons() method of the uicomponent variable returns a list of objects representing the submit buttons configured in the forms.xml file. This list must be iterated to draw all the required action buttons. If no submit buttons were configured, the list will be empty and a default button must be provided. Each element of the list allows the programmer to call a get() method with the "name" string as a parameter, in order to get the name of the button, that needs to be provided to the event() method as a parameter.

renderField() method:

The render field method draws the different components in the user interface, as directed by the specification of the variable in the forms.xml file. This method must be provided a reference to the component to draw that can be obtained with the getInput() method of each one of the objects returned by the getInputInfo() function.

event() method:

The event() method returns a JavaScript link execute the actions required and has 2 parameters: an action type and an optional action name. There are 3 types of actions defined by the Bonita Console environment that are useful to the template writter. The first action is called Cancel and allows the rendering of a cancel button that will close the form without advancing the workflow or updating the variable values. The second action is called EndOfState and allows the inclusion of a default submit button if no one has been defined in the forms.xml file, this button will update the variables displayed in the form and advance the workflow. The last one is called Transition and requires an additional parameter with the name of the submit button that is going to be executed. This event updates a variable with the name of the button as specified by the corresponding submitbutton tag in the forms.xml file. All the actions/events return a link that must be put into an anchor tag (<a>) to allow the final user to trigger the action.

Those are the most important functions and objects available for the template writer. In the next post I will show the general structure of the form templates for the Bonita Console.

Customization of Bonita Console forms (part 1)

2009-01-20T07:07:00.001-06:00

The Bonita Console application allows rapid deployment of process models by automatically generating forms, that enable the users to edit the values of the different process and activity variables. Those forms can be customized as described in the chapter 11 of the Bonita Console User Guide. There are several items to take in account:

The resource-bundle element of the forms.xml file is described as optional, however it is required and it must reference an existing properties file. Otherwise the Bonita Console will not run properly when requested to display the form associate to the customized task.
The form customization files can be stored in the scr/forms folder of the Eclipse project. The build process will automatically move them to the root of the BAR file, where the Bonita Console will look for them.
The customization of the look and feel of the forms is done by providing custom Groovy templates. There is no example provided in the guide of a template to customize, however, the default template can be located in the following path:
bonita-console-4.0.1\webapps\bonita.portlet\groovy\UITaskForm.gtmpl
The file can be copied into the Eclipse project and changed as needed.

How to use Bonita out of the Box

2009-01-16T08:55:00.001-06:00

One of the things that make a product attractive is the ability to use it out of the box. In the case of workflow solutions, that capability is important to allow business analysts to start working on modeling the business processes and to see how they will flow through the different roles and people involved, without having to wait for the full programming tasks to be completed.

Bonita 4.0.1 (a.k.a Nova Bonita) allows for this capability with an easy installation of the process modeling tool, called ProEd, and the possibility to run the process models in a WebOS environment powered by the eXo Platform.

Prerequisites

To run both ProEd (the process modeling tool) and the administrative console, you need to have an installation in your machine of the Java Development Kit 1.5 and the corresponding runtime environment. You can find links to download it and installation instructions from Sun's website.
Some applications might have problems while processing paths that have white spaces. Because of that I recommend that the installation of all necessary software to be done in paths without white spaces.
The JAVA_HOME and JAVA_RTE variables must be properly set in your environment with the paths of the Java installation.
To run the ProEd tool you will need the Eclipse IDE application (ProEd has a standalone version for the use of business analysts that do not need the programming capabilities of Eclipse, however, it does not provide the build/deployment facilities present in Eclipse for a quick start up). It can be downloaded from the Eclipse website.

ProEd Installation in Eclipse

To install ProEd in Eclipse you have to:

Download the bonita-eclipseDesigner-4.0.1.zip file from the downloads page of the Bonita project.
Unzip the file. That will give you a folder called plugins.
Copy the folder inside it (called org.ow2.proed_4.2.1) to the plugins folder in your Eclipse installation path.
Start the Eclipse IDE and enjoy.

You can read the Bonita Development Guide for information on how to create and build a project in there. I will discuss that in upcoming posts.

Bonita Console Installation

The Bonita Console is a web application based on the eXo Platform that runs on top of the Tomcat application server. To install the Bonita console you need to:

Download the bonita-console-4.0.1.zip file from the downloads page of the Bonita project.
Unzip the file. That will give you a folder called bonita-console-4.0.1.
Inside that folder there is a subfolder called bin. To start the console you need to start the Tomcat application, by opening a command prompt/terminal window, navigate to that folder and running the command:
> bpm run
To access the application you need to open a browser window and go to the address: http://127.0.0.1:8080/portal. The application will show you a login page, you can use root as username and bpm as password to access it.

You can learn how to use the console and deploy business processes from the Bonita Console User Guide.

Links and resources

2009-01-13T07:07:00.003-06:00

Here are several links that will be useful for people looking to work with Bonita or with a workflow solution and have selected Bonita:

Bonita Home Page:

http://bonita.objectweb.org/

Project forge in ObjectWeb:

http://forge.objectweb.org/projects/bonita

Forums:

http://forge.objectweb.org/forum/?group_id=56

Issue list:

http://forge.objectweb.org/tracker/?group_id=56

Download page:

http://forge.objectweb.org/project/showfiles.php?group_id=56

Licenses:

For the runtime environment and the process designer:

GNU Lesser General Public License, version 2.1

For the administrative management console:

GNU Affero General Public License, version 3.0

Related projects or applications:

Other open source workflow applications:

Talking about Bonita Workflow Engine

2009-01-12T14:34:00.001-06:00

Hello!

I am a computer engineer and because of some projects I had to deal with in my work I became interested on Workflow technologies and after looking for several options on the Open Source world I found Bonita to be a very good workflow solution.

However, it has been challenging in some areas, I have decided to start this blog to document what I have learned about it and how to solve the most common problems I have had.

I hope this will be useful to some other people trying to start with it.