The Open For Business Project: Workflow Engine Guide

Table of Contents

• Related Documents
• Introduction
• XPDL Extensions
• Client API
• Workflow Activities
• Usage

Related Documents:

• Core JavaDoc (including Workflow Engine)
• XPDL Definition DTD
• XPDL PDF
• WfMC References
• OMG References

Introduction

The Open for Business Workflow Engine is based on the WfMC and OMG spec; (See the related documents for information on these specs.) it is a member of the Services Framework, and is tightly integrated with the Entity Engine. It uses the entities found in entitymodel_workflow.XML for definition information and entitymode_workeffort for runtime storage. All changes to a process or activity are persisted real-time. Therefore, the engine does not run in a thread, it is simply a group of APIs and common objects which handle the flow. When a change to the workflow is made, the engine then processes that change. When finished, the engine returns. Hence, if the application does crash, or the system reboots, the workflow will continue right where it left off upon restart.

The Workflow Engine is not designed for processing flow of a web site. This is a common mis-conception. Web site flow is controlled by the Control Servlet. Workflow is the processing of manual and automatic activities to fulfill a specific goal.

OFBiz Workflow Engine uses XPDL as its process definition language. This is an open standard, and very flexible. In cases where the XPDL spec does not specifically state or leaves the implementation up to the vendor, we have noted them in the section XPDL Extensions.

XPDL Extensions

Workflows are designed using a processes definition language called XPDL. This document does not go into detail about XPDL, that is explained in a document created by the WfMC, see related documents.

There are a number of attributes the WfMC says is left to the vendor. Here we will document our extensions: (These are implemented as 'ExtendedAttributes')

• acceptAllAssignments - This ExtendedAttribute tells the workflow engine that ALL assignments must be accepted before an activity will begin. This is useful when there are multiple participants to an activity and everyone must accept their assignment prior to the activity beginning. (Default is NO)
• completeAllAssignments - Simular to the acceptAll, this tells the workflow engine that all assignments must be completed before the activity completes. This is helpful when implementing activities like payroll, when all employees must submit their time-sheets prior to moving to the next step. (Default is NO)
• limitService - When defining an activity, a limit can be set. This is the amount of time which is allowed before this activity is expected to be complete. A service can be set to run if the activity has not completed in the allocated amount of time. (No default)
• limitAfterStart - This tells the workflow engine that the limit checking should take place after the activity has begun. By setting this to NO, the limit is calculated from the time the assignment is created, rather then the time the activity started. (Default is YES)
• canStart - This attribute tells the workflow engine that the activity attached to this ExtendedAttribute is allowed to initiate the workflow. So rather then the workflow starting with the first activity, the workflow can begin with any activity which has this set to yes.

• runAsUser - This ExtendedAttribute will tell the TOOL (if it is a PROCEDURE) to run the defined service as this user. Specify the user's userLoginId as the value of the attribute. By default NO userLogin object will be passed.
• Actual Parameters:
• Expressions: You can use expressions inside ActualParameters to map context attributes to service parameters. You must specifiy expr: to note an expression. Example:

  <ActualParameter>expr:orderNumber=orderId</ActualParameter>

  will map the context attribute orderId to a buffered variable named orderNumber then if you did:

  <ActualParameter>orderNumber</ActualParameter>

  the parameter orderNumber would be passed to the service with the value of orderId.


• WorkEffort ID: You can use workEffortId as an ActualParameter, this will be mapped to the primary key of the current activity.

By default when a workflow is started, the first activity in the list is set as the default starting activity. This means that when a workflow is started normally, we will run the first activity first, then follow the transitions. This is the most common way to invoke a workflow. However, there may be times when the workflow should be invoked from a number of different starting points. In this case, the client API would be used to call the appropriate activity to begin. The transitions would follow from that point. Only activities with the 'canStart' ExtendedAttribute are allowed to initiate a workflow.

Client API

The client API for the OFBiz Workflow engine consists of a set of global services and a factory class. The factory class named org.ofbiz.core.workflow.WfFactory, can either create a new instance of a workflow component (process/activity/assignment) or it can locate an existing instance. Instances are stored in the WorkEffort entity and are loaded as necessary. The set of global services found in org.ofbiz.core.workflow.WorkflowServices are setup to make assigning, accepting and completing assignments/activities easier. It is not required to use these services, but it is highly recommended. You will want to review the JavaDocs for these classes.

The workeffort web application shows an example of a workflow web client. From this interface you can accept assignments which are currently assigned to your group/role and edit the state. Try http://localhost:8080/workeffort.

Workflow Activities

The combination of manual and automatic activities is what makes a workflow so powerful. The OFBiz Workflow Engine currently implements NO, ROUTE, TOOL:Procedure, and SUB-FLOW type activities. TOOL:Application type activities are not yet implemented but will be in a future release.

• NO - Just as is says, no activity. This describes a 'manual' activity.
• ROUTE - A route activity is used for simply routing to other activities via the transitions.
• TOOL -
• Application: An external application is invoked. - Not currently implemented.


• Procedure: OFBiz Workflow Engine implements procedures as internal service calls.
• SUB-FLOW - A sub-workflow is created and ran. These can be defined as synchronous or asynchronous.

The current version of the OFBiz Workflow Engine does not implement LOOPS. These too will be added in a future release.

Usage

To use the workflow engine you must first have a process you wish to invoke. Design your process in XPDL format. Once your design is complete, import the XPDL file into the workflow entities. You can do this from the webtools web interface. After the workflow is imported it can now be made available for execution. The easiest way to invoke a workflow is to define it as a service. Create a service definition for the workflow process and set its engine-type to 'workflow'. From there you can start a workflow process just like running any other service.

Documentation Notes

We know this documentation does not go into much detail. And we apologize for that. However, we spend a most of our time writing the code base, so documentation doesn't get full attention. We realize the need for good documentation, but our resources are limited. If you or anyone you know is interested in helping The Open For Business Project by contributing time writing better documentation, please contact the e-mail address at the top of this document. Thank you.