Online Croquet England Directory Help.

A workflow is a sequence of stages in a process and the corresponding transitions between those stages.

A workflow might be used to manage a new member's joining process - making sure they get a welcome pack, return any necessary documentation, etc., or for a complex membership renewal when perhaps a form has to be filled in and then processed upon its return.

A workflow is created and owned by a single organisation, can be edited and managed by any of the organisation's club officers or admins, and can be attached to any one item in the database (usually a club or a person, but could be anything). A particular workflow can be assigned to only one defined type of object (e.g. club), but to as many of those as needed.

Workflows may be modified, managed and actioned by any club officer.

A workflow is used by assigning it to an individual object (club, person, etc.) - called its target. This is accomplished through the edit dialogue, or mass-assigned through various processes (membership renewal being an example of usage: a workflow can be mass-assigned to members of the owner organisation). This creates a separate instance of the workflow for each item it is assigned to - each instance is managed independently as it progresses between its stages.

A workflow can be modified at any time and any changes take immediate effect on all instances, for example updating the instruction for what to do in any particular stage, or adding a transition button.

A workflow whose current stage expects action from the target appears in a workflow tab in the target's display (e.g. when viewing a particular club or person). If the target is an organisation, then the tab is visible to all the target's admins. The tab is not otherwise visible to the target (i.e. it is only visible to the target when requiring action by the target). The tab is always visible to the workflow owner (until the particular instance is terminated).

Where a club is the workflow's target, any club admin can action the transitions available to the target (other transitions might be reserved for the owner, which do not appear for the target).

Workflow actions assigned to a person are actionable only by them (and the workflow owner admins), not by admins of any other organisations of which they are a members.

If an action is expected of a viewer, then a link to the workflow also appears on the Directory home page.

An instance of the workflow has a current stage, a do-by date, and an organisation or individual responsible for the action at that stage (the target or the owner). The stage definition configures the responsibility for action (either Owner or Target).

Each workflow transition comprises a description, a legend for a button, and an interval (number of days) before the stage will appear on the owner's management list (to allow time for external events). Most importantly, it defines the next stage, which is entered when the transition button is pressed.

The transition may optionally be set as a Target Action, in which case the target (as well as the owner) can perform the action,

A transition can 'go to' the same stage it originates from, but with a new time-out (a kind of sleep function to perhaps acknowledge something has been chased but is not yet complete).

This number of days is used in the transition and displayed to the target as a please complete by date and keeps the instance off the owner's management list until expired. Thus, when a transition assigns a workflow stage to a target, the number of days should be sufficient for the target to complete their action; when a transition assigns the workflow back to the owner, the timeout should be zero so it is immediately on the owner's management list (and the owner may define a sleep transition to take it off the action list for an interval).

The stage definition comprises a name and an optional description of what is to be accomplished in the stage.

A workflow definition includes what is the initial stage and its time-out (effectively the initial transition).

At least one stage is defined as the terminal stage for the workflow, and a targeted instance becomes inactive on entering that stage. Transitions out of a terminal stage are not allowed.

The contents of any text describing the workflow, stages, or transitions are processed before display when an instance is viewed: the special string __TargetID__ (note double underscores each end) is replaced with the database ID of the target, allowing links in the explanatory texts to link direct to the specific related instances of any database app. This is most commonly useful when used in conjunction with forms to collect data¹.

When a workflow is used for collecting and processing data in a form, it may be linked to a particular form type - then all views of the workflow automatically show a form status icon and a link to the instance of the form, thus simplifying workflow setup. The form's state can be initial, filled, or locked (no longer modifiable).

A management interface, linked from the Directory home page, affords an overview of active workflows, separated into those timed out and requiring remedial action and those awaiting action.

Workflow Configuration

The view of a workflow's configuration starts with a description of the workflow, all updatable via the Workflow Settings button.

This section also allows assigning the workflow to a particular target instance. To assign a workflow to several targets, use the appropriate bulk action, for example, subscribers can be assigned from the list of subscribers.

Then follows each available stage, running from the initial stage first to the terminal stage(s) last.

The display shows the stage definition and a button (Stage Settings) to adjust its settings, followed by the list of transitions that are available from that stage (in a box) and finally (hidden by a twistie) those that might be used to get into that stage.

Colour coding is used to distinguish between stages that are the target's responsibility for action and those that are the owner's responsibility. Likewise, within a stage that is the target's responsibility, the transitions that the target can perform (and see) are distinguished from those the owner can see and perform.

A button is shown with the actual legend (transition name) as presented to the user when in use. Clicking the button in this configuration view allows updating the transition's settings.

An arrow shows to which stage the transition will take the workflow when the button is clicked in use (here it opens the transition settings window).

Then the timeout before appearing on the owner's to-do list (if any) is shown.

If a transition has associated HTML text, it's presented above the button exactly as it will be seen in use (except that substitution of double-underscore parameters is not made).

Email on Transition

A workflow can be configured to send emails when any transition is actioned - fill in the three fields: email address (can be a list), email subject, and email body.

The address list can include a special name __TargetEmail__ (note double underscore), which is replaced by the email address of the target (or main contact if an organisation, and taking into account that an organisation can be configured to use its own, rather than its main contact's personal email address).

The body is plain text and can include the special word __TargetID__ that is replaced with the TargetID of the actual workflow when the email is sent, facilitating a link to a particular form, or workflow, or other app.

If any of the email fields is not blank then the other fields must be filled and are defaulted if not, which affords a simple mechanism by filling in the subject to avoid having to figure out how to create a link or the special substitution string for target email address.

Technical Notes

1. In the stage's HTML, use the following code to pop up a form for completion by the target (in your case substituting XXX for your form's ID number):

   <a href="/?p=members/directory&action=form&TargetID=__TargetID__&formID=XXX" onclick="popup(event, this, 'form', 800, 900)">this form</a>