$Id: README.txt,v 1.4 2007/05/30 20:01:06 fago Exp $

Workflow-ng Module
------------------------
by Wolfgang Ziegler, nuppla@zites.net

This README is an short introduction for interested developers. This module is 
not ready for use for end users, as it has no UI yet.
Stay tuned if you are interested in the UI...


Description
-----------
The workflow-ng module collects the events provided by modules. It also allows the
creation of configurable conditions and actions, which may be configured to be processed
on events.


Events
------
An event definition has to contain the machine readable and the human readable
event name, as well as a list of available arguments.

The module has to invoke the event when it occurs and pass the available arguments to
workflow-ng. But it can define further arguments, that will be generated at 
runtime with the help of a provided handler.

Currently workflow-ng does already implement some events itself, which cover only
basic events of drupal core.


Actions
--------
Each module can implement actions, which are working for specified arguments, e.g. for a node.
These actions can be configured to be used, when an event occurs.  Workflow-ng will pass the 
arguments to the action as configured.
For some known entities, currently nodes and users, an action may return modified arguments,
which will be saved automatically after execution of all actions. This makes sure, that each 
argument is only saved one time even if multiple actions modify it.

Actions work with a specified list of arguments, e.g. a "Send a mail to a user"
action might work with the single argument of one user object.
Then an action can be configured everywhere, where at least one user object is available. This
allows reusing actions, as often as possible. E.g. the "Send a mail to a user" action might be used
to thank node authors for their contribution or also to notify users, who's profile has been viewed.


Conditions
----------
A module may also provide conditions, which have to return a logical value (TRUE | FALSE).
These conditions can also be configured to be used, when an event occurs. So this allows one to
conditionally fire actions.

Like actions, conditions work also with a specified list of arguments, and can be used everywhere,
where the appropriate arguments are available.

Conditions can be interconnected with some logical operations, currently available are OR, AND, or
even a NOR, which can also be used as NOT.


Configurations
---------------
Each module may configure conditions and actions for a certain event. These configurations will be
handled by workflow-ng automatically, which means that workflow-ng evaluates the configured conditions,
if any, and only fires the actions if the conditions evaluate to TRUE.
Modules may specifiy some properties for configurations, so it will be possible for a module to
provide some default configurations, that can be customized by the UI module, but also to
provide some fixed configurations that can't be changed.

Unlike the existing workflow and actions module, workflow-ng obeys the ordering of configured elements
(conditions or actions).
So actions will be fired in the order they are configured. Furthermore, ordering is important
when working with conditions. E.g. an action "on top", will be fired for sure, while an action
behind some conditions, will be only fired if the conditions evaluate to TRUE.
The order of elements may by changed by using the #weight property, like it is known from the forms API.
If you don't specify any weight, actions will default to a weight of 1000, so that they are fired only
if the conditions are met.

Workflow-ng makes use of caching mechanism, so that the configurations can be loaded and processed quickly
when an event occurs.

If you are interested, check out workflow_ng_tests.inc, for some simple test configurations, or
have a look at workflow_ng_events.inc, for some basic event definitions for drupal core (uncompleted).


States
-------
The states module is a simple API module, that provides flexible state machines for other modules.
It works on the head of users and nodes. In conjunction with some conditions and actions, it will
be possible to build enhanced workflows.
The states module is fully working and can be considered as finished, however the useful workflow-ng
integration (conditions, actions and an event for a state change) is still missing as well as a bunch
of documentation.



TODO/ROADMAP
-------------
 * Try achieving compatibility with drupal 6 actions
 * Write a lot of conditions, actions, events.. for drupal core and states.
 * Write flexible, token module enabled conditions and actions.
 * Write docs, docs and more docs.
 * Write a simple UI, that allows the configuration of conditions and actions.
 * Write a states CCK field with configurable state changes and state changes permissions.

 