Building your BPM applications with Bonita Runtime - Part 1

Blog
1

As you may know, process based applications generated with Bonita Open Solution Studio and Bonita Open Solution User Experience use Bonita Runtime. Bonita Runtime is an open source BPM engine written in Java. It is a very powerful and lightweight library that allows you to define, deploy, execute and manage your processes.

If you don’t want to leverage the existing interfaces of the process based applications and User Experience to interact with the Bonita Runtime and prefer to do it the hard way :slight_smile: to and implement your own application and interfaces directly, this series of articles will give you basic knowledge to get started quickly.

Bonita Runtime has been designed to provide a lot of flexibility through service injection. It is completely configurable using an XML file called “environment”. This configuration describes all services used. You can change all of them or replace them with your own implementation.

In addition, Bonita Runtime is non intrusive, meaning it requires only Java. You can install it in any JVM of your choice, in any web/JEE container or use it as a simple Java library.

Another cool feature of Bonita Runtime is support for command injection that allows you to create your own operations in the Runtime.

In this series of articles, I’m going toI will deal with the following topics:

  1. Understanding object models
  2. Using APIs
  3. Configuring the Runtime
  4. Using EJBs
  5. Using commands
  6. Setting up your maven project and getting started with an example
For this first part, let’s take a look at the following:
  1. Understanding object models
  2. Using APIs

1 - Understanding object models

Bonita Runtime APIs use 2 different object models = 'Definition' and 'Runtime'.

‘Definition’ object model

‘Definition’ objects represent the process model. The root object of the hierarchy is ProcessDefinition. A ProcessDefinition is Java representation of a Process (i.e. pool) designed in Bonita Open Solution Studio. Technically, this object is built using the ProcessBuilder.

ProcessDefinition contains the following fields:

  • uuid
  • name
  • label
  • description
  • version
  • state
  • deployedBy
  • deployedDate
  • undeployedBy
  • undeployedDate
ProcessDefinition also contains a set of other entities: e.g. datafields, participants, activities, attachments, metadata. The entities most used are activities, datafields and participants.

All major elements in the ‘Definition’ object model have the following common fields:

  • uuid to identify uniquely an object
  • name
  • label
  • description
All objects which are children of ProcessDefinition also have direct access to the parent process uuid.

A ProcessDefinition can be in one of the three following states:

  • enabled: the process is in the runtime repository and can be instantiated
  • disabled: the process is in the runtime repository and can not be instantiated (i.e. suspended)
  • archived: the process is no longer in the runtime repository. It has been moved to the history repository and can no longer be instantiated.
'Runtime' object model

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

ProcessInstance contains a set of fields including:

  • instanceUUID
  • processUUID
  • state
  • startedBy
  • startedDate
  • endedBy
  • endedDate
ProcessInstance also contains a set of other entities including:
  • activities
  • variables
  • attachments
  • involvedUsers
  • variableUpdates (history of all variables assignment during the process instance life)
  • stateUpdates (history of all states assignment during the process instance life)
The entities most used are activities and variables.

Activities need a few more words of explanation:
There are two types of activities. Automatic activities do not require a human contribution. Manual activities require a human contribution. The ‘Runtime’ object model makes the distinction between these by using inheritance. Automatic activities are of type ActivityInstance. Human activities are of type TaskInstance. A TaskInstance is an ActivityInstance with additional information.

A ProcessInstance can be in one of the following states:

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

2 - Using APIs

Bonita Runtime provides a very useful feature related to environment management. This feature ensures that your application is not dependent on the target deployment architecture. You can develop your application inside a simple web container and then deploy it on a JEE server without modifying your Java code. This is automatically done through AccessorUtil capabilities.

AccessorUtil (org.ow2.bonita.util.AccessorUtil) is the main entry point to Bonita Runtime APIs. Using this utility class, you get access to all available APIs.

Bonita Runtime provides different APIs organized by concept:

ManagementAPI
» operations related to process installation/removal, resources/filters management.
» e.g. deploy(businessArchive), deleteProcess(processUUID), addMetadata(key, value)

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

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

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

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

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

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

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

Simple, no? In my next blog post, you will discover how to configure the Runtime, use EJBs and Commands and I will describe the best way to set up your maven project and get started with an example.

Stay tuned and remember – have fun with Bonita!