Workflow Engine for egroupware

Maintained by regis_leroy

Basics

This was first a port from Galaxia workflow, a project from the TikiWiki group. most of the documentation about Galaxia is still valid on this workflow.

The workflow in egroupware consists of two things:

• the workflow app, which is used to create and manage workflow processes through a GUI. It is located in /workflow. The goal of this app is to provide a reference implementation, stable and complete to what can be done with this API. It's the most secure and comfortable way to use the workflow.
• an API, for developers, to be used by any app in egroupware that wishes to have workflow functionalities, such as the new TTS that is currently under development. It was first located in /phpgwapi/inc/galaxia_workflow, but it is now in the /workflow/inc/engine directory. There is an excellent doxygen documentation about this API located here, but we'll need to document the real API soon, with the changes we made. If you want to write your own app you'll have to read the code and use the GUI and WfRuntime? objects of the library. To be honest the real goal of this API is to be portable on other groupware, there's no need to rewrite a new application on it for egroupware.

To fully understand what processes, activities and instances are I strongly recommend that you read Galaxia Introduction.pdf and Galaxia_manual.pdf.

To be able to generate the process diagrams you must have installed the Graphviz tools (rpm is here, it works in unix/linux and mac, but I dont't know if there's a port for windows)

To work the workflow app store the processes on the vfs of egroupware, outside home, in a workflow subdirectory, so you should have a working filesystem application before using the workflow app.

Actually there's no automated form creator for the workflow. Yous should use examples joined in workflow/doc/examples/ and browse this wiki to understand how to write your workflow processes. For someone with a basic knowledge of PHP this shhould be easy.

Note for activities coders
In the activities codes, the user has at its disposition the entire egroupware api in the object $GLOBALS['egw'], a database object in $GLOBALS['egw']->ADOdb, and a template object (phplib's) in $GLOBALS['egw']->template (well the best way to access theses 2 lest items things is simply $this->db and $this->template). When you add functions in your own PHP code with activities you should be aware that theses functions are nested function, and one effect of such thing is that $this cannot be used inside nested functions, if you want to use the $template and $db you should make a function foo(&$template, &$db) where theses 'objects' are given as parameters (and the & is there if you want to give the real object, not a local copy).

Workflow FAQ

If you are developing a process you should have a look at this WorkflowFAQ

Examples

The better to understand or test the workflow is to start with process examples.
You will find some of them on the WorkflowExample page. Look at your workflow directory, you'll find example in workflow/doc/examples

Roadmap

Actually this app is considered stable.
Consult the WorkflowRoadmap for future improvments

Devel Guide

Here you'll find some explanations of how it works. We'll try to extend it as much as possible, but the reading source is still a way to understand things. The code is documented, or at least we try to document it.
Anyway consult the WorkflowDevelGuide

Migration

If you where using previous version of the workflow code, egroupware's automatic updates are handled correctly by setup functions. All database table updates should work well and old process code should be working well in new versions of the workflow app. Most of the new functionnalities add some behaviour on activities and let you code your process in a simplier way.
there are some known upgrade issue actually:

• if one of your activity created before the version 1.1.01.000 of the workflow app contained a number in her name (like '02editFoo') you should be carefull when making new major or minor version of the process which contains this activity (lets say process bar 1.4). The new process version (bar 1.5) will normalize the activity name with numbers ('02editFoo') but the old version of the workflow was normalizing the name without numbers (like '_editFoo'). The source code for 02editFoo won't be find in the version 1.5, he wants a code named 02editFoo and is not finding it. Rename manually theses files, they are stored in <your virtual filesystem root directory>/workflow/bar_15/code/activities/ and instead of _editFoo.php rename it 02editFoo.php.
• beware property names are normalized as well after the 1.1.04.000 version. Strange chars aren't allowed in properties names.
• properties were serialized and they are now serialiazed AND encoded in Base64. this was done in migration from 1.1.05.000 to 1.2.00.000. But this was not done well with MySQL, it's fixed in 1.2.00.001. You should rerun the upgrade 1.1.05.000=>1.2.00.000 (setting your version number to 1.1.05.000 for the workflow in the egw_applications table) if you already did it just after the RC1 release and if you run on MySQL (but only on theses cases, it's now fixed).
• beware on the change to egroupware 1.2 that the egroupware API is moving. If your activities contains code refering to egroupware's API you should have a look at the egroupware/doc/modernize.php script for changes (mostly references th 'phpgw' became 'egw').

If you used an original Galaxia engine and defined a process on it the migration should be avaible, have a look at the file /workflow/setup/tables_update.inc.php, it contains instructions for the database, and look at /workflow/setup/tables_update.inc.php it contains the actual database schema. Changes between this version of the Galaxia engine and the original one can be find in WorkflowDevelGuide .