Important Note: This document is a work-in-progress and should not be considered complete. Last update July 10, 2010.

This document describes the Billfish BPM product architecture, BPMN basics, process workflow design, data modeling, process scripting, forms and integration of Billfish BPM with external software systems. It catalogs Billfish BPM capabilities - while other product documentation illustrates how to use the product components in more detail.

The Billfish BPM Suite Product Editions BPM Server Architecture The Billfish BPM Repository Distributed Computing Cloud Computing Process Data Base Data Types Compound Data Types Arrays Data Spaces Server Context

Process Attachments BPMN Support The Billfish BPM Process Events Start Events HTTP Start Events Intermediate Events Tasks User Tasks Work Queues Forms Auto Forms

Custom Forms Gateways Connectors Conditional Expressions Sub-Processes Lanes Artifacts Performers Server Privileges Dynamic Tasks Dynamic Performers Process States

JavaScript Integration With Plugins SQL Database Support Connecting to a Database Process Design Modes Process Validation Process Deployment

The Billfish BPM product suite consists of four integrated component applications: BPM Studio, BPM Server, BPM Portal and BPM Mobile.
 
BPM Studio is an all-in-one authoring environment used to graphically design business process models, user forms and process data models. It is based on the Business Process Modeling Notation (BPMN) standard and produces an XML-based process description that is uploaded - i.e., deployed - to the BPM Server where it may instantiated. BPM Studio is a modern, pure Java-based application that runs equally well on Windows Vista, Windows XP, Windows 7, Apple Mac OS X (including Snow Leopard), Linux SUSE and Linux Fedora.
 
BPM Server is the engine component of the Billfish BPM suite that executes the process models created with BPM Studio. It is a J2EE-based solution and supports all J2EE-compliant application servers including JBOSS, BEA WebLogic, Oracle Application Server, IBM WebSphere and Apache Geronimo as well as lightweight Servlet containers such as Tomkat and Jetty. It runs on all major OS platforms including Windows XP, Windows Vista, Windows 7, Linux, and Apple Mac OS X. It is extendable in the form of Java-based server extensions called "plugins" which allow the BPM Server to integrate with other computing systems. There are built-in plugins for email, file, and SQL database functions. All major SQL database platforms are supported - including SQL Server, Oracle, Sybase, DB2 and MySQL.
 
BPM Portal is a "rich internet application" (RIA) based on Adobe Flex that runs in any standard web browser including Microsoft Internet Explorer, Mozilla Firefox, Apple Safari and Google Chrome. It requires Adobe Flash Player 9.0 or later. Users can launch processes, manage inboxes, complete tasks, manage documents and interact with other team members via process chat. Administrators can use BPM Portal to setup up users, groups, departments, assign roles, administer and query Data Spaces. Department Managers can use BPM Portal to view performance dashboards and generate reports. BPM Portal employs a unique "desktop-within-a-browser-window" interface that enables users to work on multiple tasks at a time. The forms rendering component of BPM Portal can dynamically create one - or two-column "auto" forms or it can render custom forms that have been manually designed in BPM Studio.
 
BPM Mobile is a component of the Billfish BPM suite which provides portal functionality on mobile devices. Users can start processes, manage inboxes, open form tasks, and more. Currently the Apple iPhone, iPod Touch and Google Android-based devices are supported. Since BPM Mobile is server-based and requires no software to be downloaded to the phone, all that needs to be done to access its functionality is to open the www.billfishbpmcloud.com URL using the mobile device and log in. The Billfish BPM suite is available in "Cloud' and "On-Premise" editions. It is helpful to know something about the underlying architecture of Billfish BPM in order to understand its capabilities and to facilitate hardware planning and distributed computing strategies (see Distributed Computing Capabilities). The BPM Server consists of the following core web applications:

Component Name	Description
Workflow Engine	Manages process execution, task routing and user interaction.
Data Space Engine	Manages independent data models shared by multiple processes (see Data Spaces).
Content Engine	A JSR 170-compliant content management system.
Integration Engine	Manages script execution and plugins modules for integration.

Billfish BPM stores all information about process definitions, forms, Data Spaces, process instance data, performers, permissions, etc. in a database repository. The On-Premise Edition (see Product Editions) allows the repository to be installed on any datasource for which a JDBC driver is available - including MySQL, Microsoft SQL Server, Oracle and DB2.
 
The repository data structure is not intended to be administered or altered in any way by third-party products. All administrative functions are accomplished through the BPM Portal or BPM Studio. A Database Administrator (DBA) merely needs to backup the repository database as part of daily administration procedures.
 
The repository database may be installed on a different computer from the BPM Server. However, if the network connection fails - BPM Server will be unable to function (see Distributed Computing Capabilities).
 
Process models are file-based in Billfish BPM. This means that models can be worked on without a persistent connection to the repository. A future version of Billfish BPM will allow process diagrams to be checked-in and checked-out of the repository thus providing complete version control of process models - however, process diagrams will remain file- based. The Billfish BPM back-end components (BPM Portal and BPM Server) can be installed in a distributed fashion by placing various software components on different host computers. It may be necessary to use the distributed computing abilities of Billfish BPM to achieve better performance.
 
The core components of Billfish BPM are distributed in the following web application archive (WAR) files:

Package File Name	Description
billfishWorkflow.war	Workflow Engine Package
billfishContent.war	Content Engine Package
billfishData.war	Data Space Engine Package

Billfish BPM was built from its inception with cloud computing in mind. The BPM Server component has a multi-tenant architecture that allows a single cloud-based instance to serve multiple client organizations thus providing virtual partitioning in which each client organization (or tenant) has its own Data Spaces, process definitions, process data, users, groups, departments and general configuration.
 
Setting up new tenants can be done two ways: manually, via the BPM Portal (using the BPM Server "root" password) - and - programmatically, using a service. SaaS (Software-as-a- Service) providers who base their offerings on the Billfish BPM platform will want to use the programmatic interface coupled with a web-page "sign-up" interface to create and configure new tenants.
 
Selection of the appropriate tenant context at run-time is done via the BPM Portal login mechanism. The tenant context is specified as part of the login id using a familiar email style. For example, the login id of "administrator@acmeconstruction" would select the appropriate context for the Acme Construction client (see Server Context).
 
In addition to multi-tenant capabilities, Billfish BPM has support for repository-based Data Spaces which can eliminate the need for additional external databases - thus simplifying cloud application development (see Data Spaces). Billfish BPM allows for the association of an unlimited number of data items - or variables - with a process. This data is private to each process instantiation - or execution occurrence - in the BPM Server. If a process is instantiated 100 times, then there will be 100 complete sets of process data recorded in the process repository database.

 

All data items can be viewed or modified by any task in the process. Data can be modified by direct user entry through a User Task form or programmatically by using a Script Task. At the completion of each task in the process, any data that was modified is immediately written to the process repository database.

 

Process data items can be base data types (see Base Data Types) or compound data types (see Compound Data Types).

 

When integrating Billfish BPM with external business applications, initial process data values are supplied by using a Script Task to read the external application data into process data variables. Conversely, process data can be written out to the external business application database in the same way.

Billfish BPM supports the following base data types:

Data Type		Data Type Description	Form Bindings
	Boolean	A boolean data type can only have two values: true or false.	Can be bound to either check box, radio button group or label form controls.
	Counter	A counter data type is an integer that is automatically incremented by the BPM Server for each instance of the process. A counter has an initial value that is set at design time (in BPM Studio) and which defaults to 1. A counter datatype cannot be modified by the process.	Can only be bound to a label form control.
	DateTime	A datetime data type can contain a date, time or both.	Can be bound to date picker, time picker or label form controls.
	Decimal	A decimal data type can contain numbers having a decimal point.	Can be bound to text field or label form controls.
	File	A file data type is used to specify a path to a file that is uploaded to the Billfish BPM Server as a process attachment. If a default file name value is specified for the data type at design time (in BPM Studio), then the file is uploaded to the BPM Server when the process definition is deployed. If the data type variable is bound to a forms control in a user task form, then the file will be uploaded during run-time when the user presses the OK button on the BPM Portal form (see Process Attachments).	Can only be bound to a file picker form control.
	Integer	An integer data type can only contain numbers without a decimal point.	Can be bound to text field or label form controls.
	List	A list data type contains an array of value-label pairs.	Can be bound to either combo box, list box, or radio button group form controls.
	Performer	A performer data type may contain the name of a process performer.	Can be bound to combo box or label form controls. The combo box is populated with performers by the server.
	String	A string data type can contain a sequence of alphanumeric characters with the maximum length of 255.	Can be bound to label or text field form controls.
	Text	A text data type can contain a sequence of alphanumeric characters with the practical maximum length of 32767 (depending on the target underlying database).	Can be bound to text area or label form controls.
	URL	A URL data type can contain a string representing a Uniform Resource Locator - or webpage address. It is intended to be displayed as a static link in a BPM Portal form.	Can only be bound to a link form control.

Billfish BPM allows for the creation of compound data types. Compound types are essentially objects having a name and consisting of one or more member data items. In Billfish BPM, these compound types are called Data Objects - and their members are called Attributes.
 
Objects are modelled in BPM Studio and stored centrally on BPM Server in containers called Data Spaces (see Data Spaces). Once they are defined in a data space, they can be used by multiple process models. Data Objects may contain the following base attribute types: Boolean, Counter, Datetime, Decimal, File, Integer, List, Performer, String, and Text.
 
An example data object called "Applicant" having four attributes:

Object Name: Applicant
Label	Name	Data Type	Default	Allow Null
First Name	FirstName	String		No
Last Name	LastName	String		No
Birth Date	BirthDate	DateTime		No
Gender	Gender	List		No

 

Data Objects can be used two ways in a process:

Method		Description	Usage in User Task Forms (BPM Portal)
	Instantiation	To instantiate an object means to create it. Declaring a data type of type object will cause the creation of a new object.	Each attribute in the object will be bound to the appropriate default form control type for its data type. See the instantiation example below.
	Reference	To reference an object means to point to an existing object value. Declaring a data type of type reference will store a pointer to an existing object instance.	Can be bound to label, combo box or lookup form controls.

 

Here's an Instantiation example:

1. Declare a process data item of type "Applicant".
2. Drag the new data item onto a task form in the BPM Studio forms designer.
3. Deploy the process and invoke BPM Portal.
4. Note that BPM Portal renders a form like the one below which allows for the creation of a new "Applicant".

   

Here's a Reference example:

1. Declare a process data item of type "Reference to Applicant".
2. Drag the new data item onto a task form in the BPM Studio forms designer.
3. Deploy the process and invoke BPM Portal.
4. Note that BPM Portal renders a form like the one below which allows for the creation of a pointer to an existing "Applicant".

   

Billfish BPM supports arrays for the following base types: DateTime, Decimal, Integer, String, and Text. Also, you may create arrays of compound types (data objects).

 

A particular powerful use of arrays is an array of objects. Here's an example:

1. Declare a process data item of type "Array of Applicant".
2. Drag the new data item onto a task form in the BPM Studio forms designer.
3. Deploy the process and invoke BPM Portal.
4. Note that BPM Portal renders a form like the one below which allows for the creation of multiple new "Applicants".

      

5. Also note that BPM Portal dynamically creates add/edit form windows like the one below to create and edit "Applicants".

      

A Data Space is a container for process data which is stored in the Billfish BPM repository. It is used for the permanent storage of process data. Data Spaces are independent of any process model. They are intended to be shared by multiple business processes.
 
The usage of a Data Space by a process is optional. A process may simply read-and-write data to-and-from an external business application database using a Script Task. However, there are several advantages to utilizing a Data Space:

• Data Spaces enable the use of Compound Data Types (see Compound Data Types).
• Data Spaces enable data to be easily shared between processes.
• Data Spaces can be used for querying and reporting in BPM Portal.
• Data Spaces can be defined once and reused - thus saving work.
• Data Spaces eliminate the need for external databases and the necessity of writing script tasks to access them.
• Data Spaces are well suited for cloud-based process applications where external database integration may be more difficult.

The following rules also apply to Data Spaces:

• A process can use only one Data Space.
• A user must have Architect server privileges to create and maintain Data Spaces (see Server Privileges).

A Server Context is a named region within the BPM Server which represents a complete and independent process execution environment. Each context contains its own process definitions, process data, data spaces, users, groups and departments. Processes and data may not be shared across contexts which are completely isolated from each other. Users of a given context are typically not aware of the existence of other contexts unless they possess login privileges there.
 
A BPM engine with support for multiple defined Server Contexts is said to have multi-tenant support. There are various ways that the multi-tenant capability may be used:

Usage Type	Description
Default	A BPM Server has one default Server Context called "Default". It may not be deleted. The root user of the Default Server Context is the only user who may create other Server Contexts.
Application Platform	Server Contexts can be defined for Development, Test, Production, Maintenance, etc.
Divisional	Server Contexts can be defined up for different divisions within a company.
Software-As-A-Service	Server Contexts can be defined for multiple companies (Billfish BPM Cloud).

Setting up new Server Contexts can be done two ways:

Setup Method	Description
Manual	The Server Context is created in BPM Portal using the Server Administration window. Only the root user of the Default Server Context may do this.
Automatic	The Server Context is created programmatically using a service. Billfish BPM Cloud usee the programmatic interface coupled with a web-page "sign-up" interface to create and configure new tenants.

Selection of the appropriate Server Context at run-time is done via the BPM Portal login mechanism. The context is specified as part of the login id using a familiar email style with the following format:
 
            user@context
Billfish BPM supports the uploading of process file attachments either at deployment-time using BPM Studio or during process run-time using BPM Portal. There are four methods to upload attachments:

Type	When Uploaded	Description
General Model Attachment	Deploy-Time (BPM Studio)	File attachments can be specified in BPM Studio which are uploaded to the BPM Server at the time that the process model is deployed. These attachments can then be viewed by all performers of a process.
File Datatype Default Attachment	Deploy-Time (BPM Studio)	File attachments can be declared as a default value for any file data types declared in BPM Studio. These are then are uploaded to the BPM Server at the time that the process model is deployed. The advantage of using this method of deploy-time file upload is that a document can be made available only to certain process performers.
File Datatype Input Attachment	Run-Time (BPM Portal)	File attachments can be uploaded at run-time in BPM Portal whenever a user specifies a file path when inputting a file datatype value on a user task form. The file uploads when the user presses OK to submit the form.
Adhoc User Attachment	Run-Time (BPM Portal)	File attachments can be uploaded on an ad-hoc basis in BPM Portal by process performers. These attachments can then be viewed by all performers of a process.

 
Important Note: Attachments are limited in size to 10mb.
Business Process Modeling Notation (BPMN) is the graphical notation standard for designing business process diagrams. It is maintained by the Object Management Group. Its key advantage is that allows business analysts and other less technical users to design business process diagrams that can subsequently be enhanced and completed by technical personnel before deployment. A very good tutorial for learning BPMN is at http://www.diveintobpm.org/.
 
Billfish BPM implements the functional core of the BPMN specification as required for the orchestration of organizational processes. It supports the following BPMN object types:

 

BPMN Object Type		Description
	Task	A Task is an atomic activity within the process. Tasks can be carried out by performers or executed by the system.
	Start Event	A Start Event indicates the entry point of a process.
	Intermediate Event	Intermediate Events occur during a process after it has started - and before it has ended.
	End Event	An End Event indicates the end point of a process.
	Sub-Process	A Sub-Process is process that is called from within another process. Billfish BPM supports both embedded and independent sub-processes.
	Gateway	Gateways are used to make decisions about the direction of the sequence flow, to diverge a sequence flow into multiple parallel sequence flows or to merge multiple sequence flows together.
	Sequence Flow	Sequence Flow connectors are used to connect flow objects such as tasks, gateways and events to specify the order they will be executed.
	Association	Association connectors are used to associate artifacts with process flow objects such as tasks, gateways, events and sub-processes. They have no effect on process execution.
	Lane	Lanes are used to organize process diagrams. They are graphical constructs which have no effect on process execution and are normally used to divide a process into regions by performer.
	Text Annotation	Text annotations are used to attach notes to the diagram. They have no effect on process execution.
	Group	Groups are used to graphically organize process objects. They have no effect on process execution.

In Billfish BPM, a process is defined in the BPM Studio authoring application as a BPA (business process application) file. The BPA file contains the BPMN workflow diagram as well as data definitions, performers, task assignments, forms and process document attachments. If large documents are attached, the BPA file can grow large.
 
The workflow diagram must be validated before being deployed (see Process Deployment) to the BPM Server and must adhere to certain guidelines. Billfish BPM imposes a stricter version of BPMN than is called for in the official specification. This is due to the fact that the BPMN specification is largely silent on vendor implementation and the runtime execution of a diagram requires a greater degree of process clarity (see Process Validation for a list of process guidelines).

An event is an occurrence of something that happens during the course of a business process. There are three types of events:  

Event Type	Description
Start	A Start Event indicates where a process will begin. It cannot have an incoming sequence flow.
Intermediate	An Intermediate Event occurs during a process after it has started and before it has ended.
End	An End Event indicates where a process ends. It cannot have an outgoing sequence fow.

A Start Event indicates where a process will begin. It cannot have an incoming sequence flow. Billfish BPM supports two types of start event triggers:  

Trigger Type	Description
None	A None Start Event is an ordinary process starting point with no external trigger. A process that begins with a None Start Event must be manually started by a performer in BPM Portal.
HTTP	An HTTP Start Event allows a process to be started by an HTTP POST request from an HTML form to the Billfish BPM Server (see HTTP Start Events).

A process diagram may not contain more than one of each Start Event type. Only one None Start Event is allowed just as only one HTTP Start Event is allowed. However, multiple Start Events of different types (triggers) may be used. The example below is an example of a process that can be started in two ways:
 
 

An HTTP Start Event allows a process to be started by an HTTP POST request from an HTML form to the Billfish BPM Server.
 
There are three steps (*) to implementing a process that is started by an HTTP Start Event:

1. Use BPM Studio to create a process model containing an HTTP Start Event.
2. Obtain a security token from the administrator of your Server Context to allow HTTP access.
3. Create an HTML form which POSTs to the Server Context using the security token.

(*) Note: The "Create HTML Form" function for HTTP Start Events in BPM Studio will perform steps 2 & 3 automatically for you.
 
The example below shows an HTML form which POSTs to a local Billfish BPM Server (http://localhost:8777):

Line	HTML Code
1	<html>
2	<form name="input" action="http://localhost:8777/billfish/event/process/start" method="post">
3	Field 1:<br/><input type="text" name="p_field1" /><br/>
4	Field 2:<br/><input type="text" name="p_field2" /><br/>
5	Field 3:<br/><textarea name="p_field3" rows="3"></textarea><br/>
6	<input type="hidden" name="redirect" value="http://www.google.com"/>
7	<input type="hidden" name="process" value="MyProcessId"/>
8	<input type="hidden" name="token" value="34343-3324-234"/>
9	<input type="submit" value="Submit" />
10	</form>
11	</html>

Notes on the example above:

• Proper syntax for the action attribute in Line 2 is serverurl/billfish/event/process/start
• In Line 2, the POST method must be used. A GET request is ignored by the BPM Server.
• In lines 3, 4 & 5, p_field1, p_field2 & p_field3 are the names of process data items specified in the HTTP Start Event setup.
• Line 6 is used to redirect the user to google.com after a succesful process start.
• Line 7 is used to specify the process id to start.
• Line 8 is used to specify the server context security token.

Intermediate Events occurs during a process after it has started and before it has ended. Billfish BPM supports three types of intermediate events:  

Trigger Type	Description
None	An Intermediate None Event is used at the conceptual modeling stage to represent an intermediate event without any determination of how the event is triggered. They are not supported by BPM Server at runtime.
Timer	An Intermediate Timer Event is used in two ways. It can be placed within the normal process sequence flow to cause the process to delay or wait for a specific amount of time or for a specific date/time. It can also be attached to the boundary of an activity (either a user task, embedded sub-process or independent sub-process) to optionally cause the activity to be interrupted when the timer trigger fires.   Example 1: A timer event used in the normal process flow to delay - or pause - the process.               Example 2: A timer event attached to a task which will interrupt in 24 hours unless the task is completed first.
Link	An Intermediate Link Event is used to connect different parts of a process diagram. It is essentially a "go-to" mechanism that is used to avoid long Sequence Flow connections and to create elegant looping diagram sections. To create a diagram link using link events, at least two link event objects must be used. One link event represents the process flow source - and the other represents the process flow target. The former is said to be throwing - while the latter is catching. Catch and throw link events are matched by having the same name. There can be multiple throwing link events with the same name - but only one catching event. Link Event pairs are also called "off-page connectors".   The table below summarizes the behavior of link events: Catch The catch link event indicates where process flow will go to. Throw The throw link event indicates where process flow originates.   The example below shows a typical use of link events:

A Task is an atomic activity within the process. Billfish BPM supports five types of tasks:  

Task Type	Description
	A None Task is used at the conceptual modeling stage to represent a process activity without any determination of how the task will be technically implemented. None Tasks have no associated data items, forms or performers and are not supported by BPM Server (see Process Validation).
	The User Task is the primary human-centric process task. It may represent a manual task to be completed by the user or it may be used to display a form in BPM Portal for the user to complete. A User Task must always be assigned to at least one performer (see User Tasks.)
	A Script Task is used to manipulate process data and/or to integrate Billfish BPM with third party systems and applications. Billfish BPM uses the web standard scripting language JavaScript to perform all programmatic tasks.
	An Email Task is a task that sends an email. Email tasks are script tasks with an easy-to-use graphical assistant that eliminates the necessity of writing JavaScript code. Email tasks can be easily converted to their underlying Script task types at any time.
	A Reference Task points to another task that has already been defined. If an identical task needs to be performed in 2 or more places in a process, it only needs to be defined once. The benefit of Reference Tasks is that a task can be created in one location but used in several.

The User Task is the primary human-centric process task. It can be used in three ways:

User Task Type	Description
Auto-Form User Task	If one or more data items have been assigned to the User Task, BPM Portal will dynamically create an "auto-form" at run-time to prompt for the data values. (see Auto Forms).
Custom Form User Task	If the process designer creates a custom data entry form using the BPM Studio forms designer and attaches the form to the User task, BPM Portal will display the custom form at run-time. (see Custom Forms).
Manual User Task	If no data has been assigned to the task and no custom form has been attached to the task, then the task is considered manual. A Manual Task causes the BPM Portal to create a work item that is closed by a performer by merely clicking a "Finish Task" button

Other important facts about User Tasks:

One or more performers must be assigned to a User Task. This is checked during validation (see Process Validation).

User Tasks are designated as either "Assigned" or "Shared" tasks (see Work Queues).

A User Task can have both assigned data items and an attached custom form which can override the auto-form generation at run-time

There are two kinds of work queues in Billfish BPM:

Type	Description
Assigned Queue	Contains tasks that have been directly assigned to one or more performers.   Additionally, Assigned tasks have two "Execution Types": Task is complete only when all performers have finished. Task is complete when the first performer has finished.
Shared Queue	Contains tasks that have been placed into a general queue for a group of performers to self-assign (Accept) in an informal manner.

BPM Portal displays forms associated with User Tasks in a process. Each form may contain one or more "pages". Form pages have automatically-supplied navigation buttons to select either the previous or next page. Only when the user clicks the OK button (or a process state-related button) is the form processed. Each form page may contain one or more form controls. Most form controls facilitate data entry. These form controls must be "bound" to a process data item. Form control bindings are checked during validation (see Process Validation).
 
Forms can be of two types:

• Auto Form

  If one or more data items have been assigned to the User Task, BPM Portal will dynamically create an "auto-form" at run-time to prompt for the data values. (see Auto Forms).

• Custom Forms

  If the process designer creates a custom data entry form using the BPM Studio forms designer and attaches the form to the User task, BPM Portal will display the custom form at run-time. (see Custom Forms).

The size of the form canvas area is fixed. The height is 490 pixels. The width is 890 pixels.
Auto Forms are an extremely useful feature that allows for rapid application development. Merely by dragging and dropping one or more data items onto a User Task in BPM Studio, you can create an Auto Task. When the process model is executed at run-time, BPM Portal will dynamically create a form containing the data items assigned to the User Task. Data items are presented in Auto Forms in the order that they are specified in the "Auto-Form" tab of the User Task editor in BPM Studio. You can configure Auto Forms (at design time) to display data items in one or two columns. Also, if the number of data items specified are too large to fit onto a single form page, BPM Portal will create multiple-page forms to accommodate all form data items.
 
By using Auto Forms in the early phases of process application development, the time required to create Custom Forms is saved - or at least deferred. As process development progresses, Custom Forms can be created for any User Task.
 
Another productivity feature is the ability to have both an Auto Form and a Custom Form specified for the same task. Typically, a Custom Form will override an Auto Form at run- time, however, you can configure (at design-time) to prevent this until you are ready to put the newly designed Custom Form into production.
The BPM Studio authoring environment contains a full-featured forms designer capable of designing multi-page forms that are connected via "Next" and "Previous" buttons at run-time in the BPM Portal.
 
The following form control types are supported:

Control Type	Form Bindings
Label	Accepts a text string - or may be bound to data items of type: Boolean, Counter, Datetime, Decimal, Integer, Performer, String, and Text.
Text Field	May be bound to data items of type: Decimal, Integer, and String.
Lookup	May only be bound to data items of type: Reference.
Text Area	May only be bound to data items of type: Text.
Combo Box	May only be bound to data items of type: List.
Check Box	May only be bound to data items of type: Boolean.
List Box	May only be bound to data items of type: List.
Radio Button Group	May be bound to data items of type: Boolean and List.
Date Picker	May only be bound to data items of type: Datetime.
Time Picker	May only be bound to data items of type: Datetime.
Link	Accepts a text string - or may be bound to a data item of type: URL.
Spinner	May only be bound to data items of type: Integer.
File Picker	May only be bound to data items of type: File.
Table	May only be bound to arrays (see Arrays).
Horizontal Separator	May not be bound to data items as it is a static form object.
Vertical Separator	May not be bound to data items as it is a static form object.
Group Box	May not be bound to data items as it is a static form object.
Section Grid Box	May not be bound to data items as it is a static form object.

Gateways are objects used to control sequence flow in a process. They are used to make decisions about the direction of the sequence flow, to diverge a sequence flow into multiple parallel sequence flows or to merge multiple sequence flows together. Gateways are represented by a diamond-shaped object and the type of the gateway is specified by a graphical marker inside the diamond. Billfish BPM supports three types of gateways: XOR (exclusive), OR (inclusive) and AND (parallel).
 
Gateways are essentially questions that have two or more alternative answers. Each possible answer is called a gate. Each gate is linked to a corresponding outgoing sequence flow object. Within each sequence flow definition is a boolean conditional expression that is evaluated as either TRUE or FALSE. While the BPMN standard does not specify the format or language that is used for conditional expressions, Billfish BPM uses the standard web scripting language JavaScript to specify conditional expressions. (See Conditional Expressions.)
 

Gateway Type	Description
XOR Gateway	An XOR (exclusive) gateway is a decision point where multiple outgoing sequence flows are possible, but only one will be selected.   In the example below, XOR Gateway evaluates the Gate 1 and Gate 2 condition expressions in an order specified by the process designer. If a conditional expression is evaluated as TRUE, then that gate is selected. The remaining gate will not be evaluated. If no gate conditional expression is evaluated as TRUE, then the default gate (Gate 2) is selected.
OR Gateway	An OR (inclusive) gateway is a decision point where multiple outgoing sequence flows are possible, and one or more will be selected. In the event that multiple sequences are selected, the process will spawn multiple sequence flows or tokens. An OR gateway can also be used to synchronize one or more sequence flows created earlier in the process.   In the example below, OR Gateway 1 evaluates the Gate 1, Gate 2 and Gate 3 conditional expressions in an order specified by the process designer. If any one of the conditional expression are evaluated as TRUE, then a token will be spawned that follows the sequence flow associated with that gate. If no gate conditional expression is evaluated as TRUE, then the default gate (Gate 3) is selected.   The example below also contains a second gateway, OR Gateway 2 which acts to synchronize multiple execution tokens. For example, if Gate1 and Gate 2 both evaluate as TRUE, two execution tokens will be generated resulting in both Task 2 and Task 3 being created. In the event that there are two execution tokens, OR Gateway 2 will wait for both Task 2 and Task 3 to complete before allowing execution to continue on to Task 5.
AND Gateway	An AND (or parallel) gateway can be used two ways: To create two or more parallel sequence flows which will execute concurrently. To synchronize two or more parallel sequence flows. In the example below, AND Gateway 1 causes the process to create two parallel sequence flows (or tokens). The result is that both Task 2 and Task 3 would be created.   The example below also contains a second gateway, AND Gateway 2 is acts to synchronize the two sequence flows. It causes the process to wait until both Task 2 and Task 3 have been completed before allowing execution to continue and for Task 4 to created.

 

The table below summarizes the behavior of gateways:

	XOR	Exclusive	Selects One Gate Only	Evaluates gate conditions until FIRST true is found. If none found true, selects default gate	Has Default Gate
	OR	Inclusive	Selects One or More Gates	Evaluates all gate conditions. If none found true, selects default gate	Has Default Gate
	AND	Parallel	Selects All Gates	Does not evaluate gate conditions	NO Default Gate

Billfish BPM supports two kinds of connectors: Sequence Flows and Associations.

Connector Type	Description
Sequence Flow	Sequence Flow connectors are used to connect flow objects such as tasks, gateways, events and sub-processes to specify the order they will be executed. Sequence Flows that are outgoing from XOR and OR gateways allow for the specification of an associated conditional expression which is evaluated by the BPM Server to determine process flow.
Association	Association connectors are used to associate artifacts with process flow objects such as tasks, gateways, events and sub-processes. Associations are used for documentation purposes only. They do not affect sequence order or process execution on the BPM Server. An example association connecting a text annotation with a task is presented below:

Conditional expressions are snippets of JavaScript code that are evaluated as either TRUE or FALSE. They are specified as part of a sequence flow that is outgoing from either an XOR or an OR gateway. The example below evaluates the boolean process data item CreditApproved:
 
process[CreditApproved]=='true';

Sub-Process Type	Description
	An Embedded Sub-Process does not exist separately from the parent process in which it is contained. It is instantiated (created) on the server when its parent process is instantiated. It does not have its own process data. The data items of the main process are all accessible by the sub-process. Note: An embedded sub-process cannot contain lanes.
	An Independent Sub-Process exists separately from the parent process which makes a call to it. It is not instantiated (created) on the server until the parent process calls it. When it is called, the parent waits to proceed until the child process completes before continuing. Independent sub-processes are not "spawned" - control always returns to the calling parent process.   Independent Sub-Processes have their own process data and do not share the process data of the calling parent procedure. In order for a child process to have access to data items in the parent process, data items must be "mapped" in BPM Studio. Data can be passed both to and from a child sub-process.
	A Reference Sub-Process points to another sub-process that has already been defined. If an identical sub-process needs to be performed in 2 or more places in a parent process, it only needs to be defined once. The benefit of Reference Sub-Processes is that a sub-process can be created in one location but used in several.

 

The table below summarizes the behavior of sub-processes:

Sub-Process Type	Data Space	Process Instantiation
	An embedded sub-process has no data space of its own - and shares all the data space items defined in the parent process.	An embedded sub-process is, in essence, a graphical construct - and does not cause a separate child process to be instantiated on the BPM Server.
	An independent sub-process has its own separate data space distinct from the data space of the calling (parent) process. In order to display, evaluate or manipulate data from the parent process, data items must be passed (mapped) back and forth between the parent and child process.	When an independent sub-process is called, BPM Server instantiates a new child process on the server. The parent process waits for the child process to complete and terminate before continuing.

Lanes are graphical, horizontal sub-partitions within a process diagram. They are used for organizational and documentation purposes and do not affect sequence order or process execution on the BPM Server. They are often used to represent roles or functions within an organization.

Artifacts are used to provide additional documentary information about a business process. Billfish BPM supports three kinds of artifacts:

Artifact Type	Description
Text Annotations	Text Annotations are small text boxes that can be placed on a diagram to document the process. They are often attached to specific objects via association connectors. They have no effect on process execution on BPM Server. An example text annotation is presented below:
Data Objects	Data Objects represent information flowing through the process such as documents, emails, image or video files, etc. They are often attached to specific objects via association connectors. They have no effect on process execution on BPM Server.
Groups	Groups are a graphical grouping mechanism to highlight sections of a process diagram. It is a essentially a box drawn around a collection of process objects. Groups have no effect on sequence flow or process execution on BPM Server. An example group is presented below:

A core function of BPM Server is the routing and assignment of work items to the correct persons in the organization. Billfish BPM calls the persons who perform tasks performers.
 
Billfish BPM supports three basic performer types that are defined in the BPM Server and can be used by all processes:

Performer Type		Description
	Named User	A named user is an individual user identified by a login and having an email address.
	Department	Departments are the basic hierarchical structure for organizing named users. The following rules apply to departments: A department must have at least one named user as a member. A named user may belong to zero or more departments. A department may have a parent department. A department may have a child department. A department must have a manager. A department may have an administrative assistant.
	Group	Groups are collections of named users. They are used to assign process tasks and Server Privileges to multiple named users. The following rules apply to groups: A group can have zero or more named users as members. A named user can belong to zero or more groups. There are two built-in groups (see also Server Privileges) used for assigning privileges. These groups may not be deleted and their names cannot be changed. Architect Administrator

Additionally, there are three run-time performer types that can be used in process models:

Performer Type		Description
	Role	A Role performer is essentially a reference to another performer. This can be useful for reporting purposes.
	Data	The "Performer" data type can be used in a process to store a performer name (see Basic Data Types). Once a process data item of type "Performer" has been defined, it can be assigned to a task. This allows tasks to be assigned to performers dynamically at run-time.
	Expression	Expression performers are determined at run-time by execution of Java Script. A good example is a task assigned to the manager of a another process performer:           RankAndFileUser.getDepartment().getManager()

There are four levels of security in Billfish BPM:

Level	Description	Notes
User	Can participate as a process task performer.	root/Administrator has assigned no privileges.
Architect	User level privileges plus the ability to deploy processes and manage data spaces.	User is member of group 'Architect'.
Administrator	Has the ability to manage named users, departments and groups.	User is member of group 'Administrator'.
root	Architect level privileges plus all other server configuration privileges.	Default password is 'pwd'.

THIS SECTION NOT COMPLETE
THIS SECTION NOT COMPLETE
A useful feature of Billfish BPM is the optional capability to create two or more process states for a given process model. An example would be a process with three defined states: "Pending", "Approved", "Rejected":

 

Once process states have been defined, the process model can change the process state in two ways:

1. By setting a sequence flow to change the currrent process state when the process token passes along it:

    

    

2. By specifying process state buttons in a User Task. These process state buttons will replace the 'OK' button in the BPM Portal form.

    

    

Once process states and transitions have been defined in the process model, its easy to set up state-based gateways:

 

 

 

This gateway object group (XOR gateway, gates sequences and target user tasks) is automatically created from the "Create State-Based XOR Gateway" dialog:

 

 

Billfish BPM uses the web standard scripting language JavaScript to manipulate process data, implement business rules, control process workflow, and to communicate with external systems. Typically, JavaScript is used on the web to program internet browsers using the browser's built-in object model. Using JavaScript with Billfish BPM however, is much easier due to the small and simpler Billfish BPM object model. Billfish BPM JavaScript in two ways:

• When specifying conditional expressions in sequence flows outgoing from XOR or OR gateways.
• In script tasks to manipulate process data or enable integration with external systems.

Here are some helpful Javascript links: (open in separate windows)

• Mozilla's Official JavaScript Documentation
• Mozilla: Re-introduction to JavaScript

One of the most powerful and flexible capabilities of Billfish BPM is its support for Java-based integration plugins. Plugins are essentially Java classes installed in a directory on the BPM Server and registered with the system in order to make their functionality available from any JavaScript task in a process. Plugins are used to enable BPM Server to communicate with external systems. Using plugins, you can send an email, create a file, insert data into a database, or create a document in a 3rd party content management system. Billfish BPM includes several built-in plugins:

• Email Plugin
• File Plugin
• Database Plugin
• PDF Template Plugin

Documentation for creating custom plugins will be available soon.

Processes are integrated with SQL databases through Script Tasks. Using JavaScript, the Billfish Database Plugin (see "Integration With Plugins") and the appropriate JDBC drivers, you can connect to a SQL database, retrieve and manipulate data. Billfish BPM supports any datasource for which a JDBC driver is available including Oracle, MS SQL Server, Sybase, MySQL, IBM DB2, PostgreSQL and HSQLDB.
 
The following JDBC drivers are installed with the Billfish BPM Server to provide built-in connectivity for Microsoft SQL Server, MySQL, Sybase and HSQLDB databases:

JDBC Database Driver	Databases Supported	Driver Class Name	Comments
jTDS	Microsoft SQL Server (6.5, 7.0, 2000, 2005, 2008) & Sybase (10,11,12,15)	net.sourceforge.jtds.jdbc.Driver	Open source JDBC driver for Microsoft and Sybase databases.
MySQL Connector/J	MySQL	com.mysql.jdbc.Driver	"Official JDBC Driver for MySQL"
HSQLDB	HSQLDB	org.hsqldb.jdbcDriver	Included with HSQLDB.

 
The following JDBC drivers are NOT installed with the Billfish BPM Server, but can be downloaded for connectivity to Oracle and SQL Server databases.

JDBC Database Driver	Databases Supported	Driver Class Name	Comments
Oracle JDBC	All Oracle versions	see comments at right	Oracle uses different drivers for different database versions.
Microsoft JDBC	SQL Server 2000, 2005 & 2008	com.microsoft.sqlserver.jdbc.SQLServerDriver	The included jTDS drivers are preferred as the Microsoft JDBC drivers have historically been slow and buggy.

THIS SECTION NOT COMPLETE.

The BPM Studio authoring environment may be used in either online or offline modes. Online use means that BPM Studio maintains a persistent connection with the BPM Server where process development is staged. Offline usage means that process design is taking place without a BPM Server connection.
 
The following tasks cannot be performed offline:

• Creating performers on the BPM Server.
• Linking process performers to server-based performers.
• Creating or maintaining data spaces.
• Creating process data items based on data space objects.
• Performing online process validation.
• Deploying processes.

Process validation is conducted in two phases: offline and online. If BPM Studio is connected to the BPM Server, both offline and online validation phases are executed. However, if BPM Studio is offline - then only the initial offline process validation phase is executed.
 

OFFLINE Validation Messages
Type	Message Text
Error	Process contains no Start Event.
Error	Process may not contain more than one of each type of Start Event (None, HTTP, Email).
Error	Process contains no End Event.
Error	Process must contain at least one Sequence Flow.
Error	"objectname" has no outgoing sequence flow.
Error	Process has no Executable Activities (Task or Sub-Process).
Error	None Task "taskname" is not supported by BPM Server. Please change to an executable task type.
Error	User Task "taskname" must have a least one Assigned Performer.
Error	control type on form "form name" on page "page no" is not bound to a process data item.
Warning	Gate Sequence "sequencename" does not have a Conditional Expression Defined.
Error	Email task "My Email Task" has no "To:" Address.
Error	Email task "My Email Task" has no Message Text.
Warning	Email task "My Email Task" has no Subject Line.

THIS SECTION NOT COMPLETE