Re: [Coefficient-devel] How to Extend Workflows?

[Thomas F. <tfo...@us...>]

On Mon, 2005-06-06 at 12:33 -0400, Enrique Nunez wrote:
> I've downloaded Coefficient, gotten it to run and started playing
> around with it. 

Glad to hear it :)

> I've gone through all the documentation and noticed the "Workflow
> Howto" has yet to be written. 
>  
> Has anyone written down exactly how to write your own workflows? 
> Also, what doctype is simpleWorkflow.xml?

I can't remember offhand (I didn't write the workflow code). What I do
remember (and what I can surmise from studying simpleworkflow.xml) is
the following:
* workflows definitions are done in an xml - see simpleWorkflow.xml (no
DTD written, as far as I know, but there may have been some effort made
defining a schema)
* Workflow definitions are uploaded via the WorkflowAdmin module

Each workflow definition has a name and description. I'm not sure about
this, but I assume the list of <module/> elements (under the root)
implies that the workflow must also declare which coefficient modules it
will use.

I have no idea what the <comparator/> element under the root does ???

The workflow engine is really more of a state transition engine, so each
workflow.xml must define a set of states, one of which must be a
starting state. It also defines one or more stop states (terminal states
for the workflow - processing end in these states). Each state has a
unique name and a description. The optional <start-state/> element sets
whether or not a state is the start state, and the <stop-state/> sets
whether it is a terminal state.

Transitions between states are defined by stipulating rules/conditions
in the xml file. Each transition is defined as:
* destination state: name of the state to which we move if the
conditions are met
* rules: a set of rules to determine whether to make the transition or
not.

If I remember correctly, given the current state, the engine scans it's
list of transitions, until it finds one whose rules are satisfied. The
first transition found is "executed". I don't think multiple transitions
and forking are supported; hence a workflow follows a single path
through a set of states.

The anatomy of the <rules> for a <state-transition> element is as
follows:
The <rules> element contains a set of <rule> elements. It also contains
a <logical-operator> element, which determines how to evaluate rules
when >1 of them are defined (i.e. when <rules> has >1 <rule> children).
<operator-name>and</operator-name><rule>...</rule><rule>...</rule>
matches if all the <rule> elements evaluate to true
<operator-name>or</operator-name><rule>...</rule><rule>...</rule>
matches if any of the <rule> element evaluate to true
etc.

Each <rule> is defined as:
* a <comparator> element, which essentially defines the
operator/operation used to evaluate . can be ==, =>, <=, etc
or it can be "boolean", which simply matches the boolean value of it's
one parameter. Not sure what else is supported?
* a list of <paramater-element> elements, which define the operands

A <paramater-element> contain one of the following:
* a <paramater> element, for specifying a simple parameter. It has a
<value> and a <type>. <type> is the Java type/classname of the
parameter. <value> is the string representation of it's value. It can
also have a <name>
* an <action> element, which wraps the return value of a method call as
a parameter. It has a <clazz> and a <method> elements, with optional
<parameter-element> elements (so you can nest actions).
* a <property> element, used to define a parameter that is the value of
some property of an object. <action> declares the method to invoke to
obtain a reference to the object, and <prop> is used to declare the
property we're interested in.
For instance,
<property>
  <prop>members.size()</prop>
  <name>membersSize</name>
  <action>
    <clazz>Project</clazz>
    <method>getProject</method>
  </action>
</property>
getProject() is called to get a Project instance, and then the
members.size() property is invoked (actually, the members property is
obtained via getMembers, and then size() is called on it).

A <state> also declares a <visibile-modules> element which declares
which modules are visible while in this state (and, by implication,
which are hidden).

The <state> can also declare an <entry-state-actions> element that
allows you to specify what must be done when this state is entered. In
simpleworkflow.xml, for instance, the "readme task completion phase"
updates the issue in the IssueTracker with information about the
creation of the readme file.

Similarly, one can define <exit-state-actions> for a state.

Hopefully, what I've written above is accurate, and will help you to get
going started. I should probably spend time to distill this into a
proper howto (but really don't have much time right now :)

Please contribute any corrections/additions to what I've written above
(as this thread will probably form the basis of the howto).

> This seems like a great product and I'd definitely consider it for my
> clients if I could become more proficient in its use. 

Excellent, that is good news! We're hoping to release an update soon,
with some changes to the Dithaka (http://dithaka.sourceforge.net) and
email integration. Will post an announcement to the developers + users
lists when we do.

Regards
T




-- 
This message has been scanned for viruses and
dangerous content by MailScanner, and is
believed to be clean.
MailScanner thanks transtec Computers for their support.