Published on Bonita Documentation (http://documentation.bonitasoft.

com)

Getting started tutorial

Product version:
6.5, 6.4, 6.3, 6.2, 6.1, 6.0
Product edition:
Community
Teamwork
Efficiency
Performance
This tutorial explains how to create and run a simple process, all the way from creating your
diagram to running the process and filling in a form. The example that we will use is a simple
travel request. An employee fills in a form to request travel. Then, unless the travel is
preapproved, the request is sent to the employee's manager. The manager reviews the
request and approves or refuses it. The example is very simple, but the best way to create
your first process is to start with the simplest case and then build it up by adding details
iteratively. We can suppose that this is the first iteration of the process, and leave the details
until later. This tutorial was created with version Bonita BPM 6.4. You can follow it using either
a Subscription edition or the Community edition of Bonita BPM. If you are using an earlier
version that 6.4, there are some slight differences in user interface but the steps are the same.
Create the diagram
Define variables
Create forms
Specify actors
Configure the process
Run the process
There is also a video version of this tutorial. Note that the video uses Bonita BPM 6.0
Community edition, so there are some small differences in the user interface compared with
this tutorial.

Create the diagram

The first stage is to create the new diagram, which you do using Bonita BPM Studio. While
you are working on a diagram, save you work from time to time, by clicking the Save icon in
the coolbar or typing Ctrl-S. Create the diagram as follows:
1. Click New diagram on the Bonita BPM Studio Welcome page. This creates an almost
empty diagram for you to start updating.

2. The first thing to do is to give the diagram a more descriptive name. Select the diagram
outside the pool, then go to the Details panel and click Edit next to the Name field.
Enter the new name in the popup, for example Simple Travel Request and click OK.
You can see in the tab at the top of the whiteboard that the diagram name has changed.
3. Now give the Pool a more descriptive name. Select the pool, then go to the Details
panel and click Edit next to the Name field. Enter the new name in the popup. When
you have renamed the diagram and the pool, the diagram looks like this:

4. Now add the tasks and decision points to the diagram. This process starts when an
employee fills in a request form. You do not need to create a task for this because it is
this action that triggers the process to start. This is known as process initiation. A
form for process initiation is defined at the pool level.
5. The next thing that happens in this simple process is a branch depending on whether
the request preapproved. This is defined as a gateway (an exclusive or, or XOR
gateway). To add this to the diagram:
a. Select the Step1 element that was added automatically. To do this, right-click on
the task icon, and choose delete from the pop-up menu.
b. Select the XOR gateway icon from the palette and drag it on to the whiteboard.
c. Change the name of the gateway by clicking on it and typing the new name.
d. Connect the gateway to the process flow. To do this, select the start icon, which
displays the context palette. Then, with the mouse, click and hold the flow arrow in
the context palette (the mouse pointer changes to a flow arrow with a round end),
the drag the pointer onto the gateway icon and release the mouse button. The flow
line is added from the start icon to the gateway.
6. Define what happens after the gateway. You can think of an exclusive gateway as a
question. In this case, the question is "Is this travel preapproved?" so there are two
possible answers, Yes and No.
7. If the response is No, the next task is for the manager to review the travel request and
approve or refuse it. Add a task by dragging the icon for a human task from the palette.
Click on the task name and change it to a descriptive name, for example Manager review
. Then add a flow element from the gateway to the task.
8. In a future evolution of this process, the next task would be to send the travel request
details to the admin team so they can handle the booking. For now, though we are just
interested in getting the first part of the process working, so add an end after the
approval task. You can do this by dragging the end icon from the palette to the
whiteboard, and then connecting to the Manager review task with a flow element.

9. Add the other flow out of the gateway. For now, this also just goes to an end. You can
do this as you did in the previous step, but as an alternative, you can use the context
palette of the preceding element, as follows:
a. Select the gateway. The context palette is displayed.
b. Drag and drop the event icon from the context palette (circle icon). When you drop
the icon, a popup of event types is displayed.
c. Select the end event, which is the solid red icon at the bottom right. The end event
is added, and the flow element connecting the gateway to the end is added
automatically.
10. Finally, label the flows out of the gateway Label so that it is clear when each one is
taken. To do this, select each flow in turn flow, and enter the name in the Details panel,
General pane.
Now the diagram is complete, but there is an icon that indicates an error on the gateway. We
cannot fix this until some variables are defined so we will come back to it later. This diagram
looks like this:

Define variables
In this stage, we define the variables needed for the process. In a real process, you define a
data model that takes account of data from external sources, and of how business data is
used across all your business applications. For this tutorial, if you are using a Subscription
edition version 6.3 or later, you will use business data. If you are using the Community edition
(as in the video) or an older version of a Subscription edition, you use process data.

Subscription edition
If you are using a Subscription edition (Performance, Efficiency, or Teamwork), there are two
stages: first you define the business data model, and then you specify how the process
handles objects of the model. The model is defined as Java objects, and the process uses
instances of objects. If you are not familiar with the terminology, all you need to remember is
that the model is the global definition, with a collection of structured variables. For your
process, you select the subset that is relevant.

First, we will create the business data model, which will then be available for all processes.
We will use a model with two objects:
Employee identifies the person submitting the travel request. In a real process, the
employee information could be stored in an external database and accessed using a
connector, but for this first example, we will use a business object as a temporary
shortcut.
TravelRequest contains the details of the travel that is being requested and its approval
status.
To define the business data model:
1. Go to the Development menu, choose Business Data Model, and then choose
Manage.... This opens the dialog to manage the business data model.
2. Beside the list of business object types, click Add. A temporary type name, such as
BusinessObject1 is added to the list.
3. Click on the temporary name, and change it to Employee.
4. Select the Employee business object type, and add its attributes:
a. In the Attributes tab, click Add. A temporary attribute name is added to the Name
column.
b. Change the temporary name to name.
c. Verify that the Type is STRING
d. Check the box to specify that this attribute is mandatory.
The Employee object type is now created.
5. Create the TravelRequest object type, by clicking the Add button that is beside the list of
business object types.
6. Specify these attributes of the TravelRequest object type:
Variable

Data type

Mandatory

depatureDate

Date

yes

numberOfNights

Integer

yes

hotelNeeded

Boolean

no

destination

String

yes

reasonForTravel

String

yes

isPreApproved

Boolean

no

approvalNumber

Long

no

approval

Boolean

no

responseReason

String

no

7. Click Finish to save the business data model.

Now that you have defined the data model, you need to specify how the model is applied to
this process. We need to define two objects, traveller, which is an instance of the Employee
object type, and request, which is an instance of the TravelRequest object type. Follow
these steps:

1.
2.
3.
4.
5.
6.
7.
8.

Select the pool.

Go to the Details panel, Data pane and click Add beside the Business data box.
In the Name field, type traveller.
Add a description if you want to.
Open up the Business Object list, and choose Employee.
Then click Finish.
Click Add again.
Create the request object, choosing the TravelRequest from the list, then click Finish.

You have now defined the variables that will be used in the process. You can complete the
diagram.

Community edition
To add a variable:
1. Select the pool.
2. Go to the Details panel, Data pane and click Add beside the Process data box.
3. For each variable, specify the name, a description (optional), set the datatype, and enter
the default value if there is one. Then click Finish & Add (or Finish for the last variable).
The table below shows the variables to add, with their data types and default values:
Variable

Description

Data type

name

The name of the person submitting the

travel request.

Text

depatureDate

Start of travel period.

Date

numberOfNights

Number of overnight stays during travel

period.

Integer

hotelNeeded

Whether or not a hotel booking is required. Boolean

destination

Destination of travel

Text

reasonForTravel

Reason why travel is required.

Text

isPreApproved

Whether or not travel is preapproved.

Boolean

approvalNumber

Tracking number for approval (added by

manager on approval).

Long

approval

Whether the manager approves the travel

request. Used in the manager's form.

Boolean

responseReason

The reason given by the manager for

approving or refusing the travel request.
Used in the manager's form.

Text

Default
value

0
no

no

You have now defined the variables that will be used in the process. You can go to the next
section and complete the diagram.

Complete the diagram

When you have defined all the variables, you can go back to the diagram and add the missing
information that is causing the error on the gateway. The gateway is asking whether the travel
is preapproved. The value of the isPreApproved variable answers this, so you need to
define a condition on the flow out of the gateway. There are two possible answers and two
outbound flows, so set the condition on one flow and make the other the default. Follow these
steps:
1. In the diagram, select the No flow. This is the flow from the gateway to the Manager
review task.
2. In the Details panel, check the Default flow box.
3. In the diagram, select the Yes flow.
4. In the Details panel, check the Use expression radio button.
5. Now define the expression. The form of the definition depends on the edition you are
using:
For a Subscription edition:
a. Click the pencil icon to open the expression editor for the Condition field.
b. In the Expression type list, click Java.
c. In the Name list, select the request object.
d. In the Java object content, select isIsPreApproved.
e. Click OK to save the expression and close the editor.
For the Community edition:
a. In the Condition field, click the Comparison icon.
b. Click the down-arrow, which displays a list of variables.
c. Double-click isPreApproved. This creates an expression that checks that
the Boolean isPreApproved is set.
6. Go to the Details panel, Validation status tab, and click Refresh. In the diagram, the
error indicator is no longer displayed on the gateway.

Create forms
Now that the process diagram is finished and the variables are defined, you need to create
the forms. A form is a collection of widgets. You can add each widget separately, or you can
pre-load your form with widgets corresponding to the variables that are relevant, which is what
we are going to do. This process has two forms, a request form for the person submitting the
travel request, which initiates the process, and a review form for the manager reviewing the
request and deciding whether to approve it.
This is how to define the request form:
1. Select the pool and go to the Details panel, Application tab.
2. Check the Pageflow and then click the Add button to add a form.
3. If some forms are already defined for the process, the popup gives you the choice of
creating a new form or duplicating an existing form. Check the box for Create a new
form, and then click Next to go to the Add a new form screen. If there are no existing
forms, there is no choice to make, and the Add a new form screen is displayed directly.
4. In the Add a new form, specify a name and (optionally) a description for the form.

5. Then select the variables to be used in the form. In the request form, all the variables
that you defined are used except for approval and responseReason. Select all the
variables except these two.
If you are using a Subscription edition, select the variables in the Business data
tab, by checking the box for each attribute, for example departureDate, not the
container (request).
If you are using the Community edition, select the variables in the Process data
list, by checking the box for each variable.
6. Then click Finish. A form layout is created, with a widget for each variable.

7. Change the form layout so that the arrangement of the widgets is more logical, and to
make it more attractive. To move a widget, drag it into an empty cell in the layout. To

change the column layout of the form, click the + and - icons. It is easier to see the form
layout if you use the whole screen, so click the expand icon at the top right corner of the
whiteboard.
8. Modify the widget labels. By default, the widget label is the name of the associated
variable. Change them to text that explains how to fill in the form. To change a widget
label, double-click on the label and type your new text. When you have entered the new
label, click elsewhere on the form.
This is what the finished form definition looks like:

The procedure for defining the manager review form is the same, but the form uses all the
variables except isPreApproved.
You have now defined all the forms needed for the process.

Specify actors
The next stage is to define who carries out the steps in the process. This is done by assigning
actors

. An actor is a placeholder for the person who will do a task. When you configure a process,
you make the connection between the actors defined in the process definition and the realworld people who will do process steps. Bonita BPM Studio comes with a test organization,
called ACME, which you can use for testing. In this example, we have two people, the
employee who initiates the process, and the employee's manager. The managers are also
employees, so I will use one actor for all steps, but use a filter to specify who does the
approval step. This is how it works:
1. In the diagram, select the pool. This is where you define all the actors for the process.
By default, there is already an Employee actor in the ACME organization, which is
defined for testing. You can change the organization and the actors later, but for initial
testing, this will work fine. The default settings mean that any employee in the
organization can start a case of the travel request process. You do not need to change
anything.
2. Next, select the review step and define who can do this. This step will be done by the
manager of the person who initiated the request. All the managers are also employees,
and the employee actor is defined for the lane, so check the button for Use the actor
defined in the lane.
3. To make sure that the review task is sent to the right manager, I use an actor filter:
a. Click the actor filter Set button.
b. Open up the list of process actor filters.
c. Select initiator-manager. This means that the review task is to be done by the
manager of the person who submitted the request that initiated the process.
d. Specify a name for the actor filter definition, and click Finish.
The process is now defined. The next section shows you how to configure and run it.

Configure the process

Before you can test the process, you need to configure it. In this tutorial, we will use the
default setting for almost everything for the first tests. There are just two things to configure for
this example process, the actor mapping and the name of the test user.
1. Open the Configuration dialog, by clicking Configure in the coolbar.
2. Click Actor mapping in the menu on the left of the popup. The actor mapping box lists
the actors and shows the default mapping: The Employee actor is mapped to a group
called acme, which contains all the employees of the example organization called
ACME. You do not need to change this.
3. Now specify the name of the test user. For this example, we can specify the user Helen
Kelly, in the ACME test organization. Her manager is William Jobs. Click Authentication
in the left menu, and specify Helen's username, hellen.kelly, and password, bpm.
4. The configuration is now complete, so click Finish.

Run the process

Now you are now ready to run the process. You will see how the process forms are displayed,
and how to use the Bonita BPM Portal. Follow these steps:

1. Click Run in the coolbar. This logs you in to the Bonita BPM Portal as the test user,
Helen Kelly, and displays the form to start a case of the process.

2. Fill in the form: for this test, suppose that the travel request is not preapproved. When
you have completed the form click Submit.
3. Click Logout. The Bonita BPM Portal login screen is displayed.
4. Log in with username william.jobs and password bpm.
5. William's list of tasks is displayed. Click on the Review request task to select it, and click
Do it. The form for travel request review is displayed, showing the information that
Helen entered in her form.
6. Complete the form and click Submit.
In this tutorial, you have seen how to create a process diagram, create forms, add variables,
specify who performs activities in the process, and how to configure and run a process for
testing. For a real process, the next steps are to define the data model, complete the diagram
to cover the whole process, and add connectors to external services such as email.

2015 Bonitasoft, Inc. All rights reserved.