Contents
Introduction
I've finally got around to documenting how to create / use workflow in the Quest "product".
Our workflow branched from the old OpenACS workflow package acs-workflow long ago,
with many hacks for various projects along the way.
- Assignments have been changed at least twice. As of right now I haven't a clue how they work.
- A task is started automatically when a user views it (if the user is assigned to it).
- The action panel uses buttons based on attributes to progress the workflow. I think
we have to have an attribute for every arc in the WF!
Creating a test workflow
- Log in as a workflow admin
- Go to /admin off where ever workflow is mounted and click "New Advanced Process".
- Give it a name and click "Add". It will go to the graphic process editor.
- Click on the name of the workflow in the context bar to go to the main admin page for it. Click "Roles"
- Click "add role", enter "test_role" as the role name and click "Add"
- Click "Home" to return to the main admin page for this workflow.
- Click "graphic process editor"
- Add your transitions, arcs and places. To be really pedantic:
- Click "add task"
- Enter "initial task" as task name, "User" as trigger type, "test_role" as role and click "Add".
- Click "add task"
- Enter "2nd task" as task name, "User" as trigger type, "test_role" as role and click "Add".
- Click "add place", enter "place1" as the place name and click "Add"
- Select the start place, click "add arc", click "initial task"
- Select "initial task", click "add arc", click place "place1"
- Select place "place1", click "add arc", click "2nd task"
- Select "2nd task", click "add arc", click end place
- Your workflow should look like this:
- Click on the name of the workflow in the context bar to go to the main admin page for it. Click "Attributes"
- Click "add attribute", enter "initial_ok_pp" as the name, "Advance" as the pretty name, boolean as the datatype and click "Add"
- Click the assignments tab
- Select yourself from the list of parties next to "test_role" and click "Add"
- Click the home tab and click "graphic process editor"
- Click "initial task", click "add guard", enter "initial_task_ok" as plaintext description, "No other guards were satisfied" as the guard condition, "initial_ok_p" as the optional argument and click "Update". Important: the optional argument specifies which attribute to use. The pretty name of the attribute is what appears on the button on the task page.
- Click "attributes", select "advance" and click "Add". Click "Done".
Test a workflow without creating a ticket
- Log in as a workflow admin
- Go to /admin off where ever workflow is mounted and click on the name of the workflow.
- Click "start new case". In the standard system this can take a long time because it does a sort on all ACS_OBJECTS
- Select an arbitrary object and click "Initialize".
- Click "1 unassigned task", "initial task", "assign yourself". This will take you to the task page.
- Watchers have been messed around with. Don't know how this works.
What happens when the workflow moves?
- The user clicks a button in the action panel.
- Each button is a submit with the name "action.attributes.attribute name. Pressing one will submit the form to the current page (the task page).
- task.tcl processes the action array, creating another array called arributes. Each button has an element in attributes set to 't' or 'f' to indicate which was pressed.
- task.tcl calls wf_task_action
- wf_task_action:
- calls workflow_case.begin_task_action
- updates acs_attributes
- updates assignments
- calls workflow_case.end_task_action
- notifies watchers
How do I return a message to the user when a guard isn't satisfied?
Just raise an application exception in the guard with the text you want displayed.
The workflow will catch the exception and show the message.
Troubleshooting
Why doesn't my button show on the task page?
To add a button, you must have the following:
- attribute added to workflow
- attribute added to transition
- attribute referenced by guard on arc from transition
What moves the workflow?
If you look at workflow_case.fire_transition_internal
you'll see it consumes tokens for the input places for the current transition
and creates new ones at the output places where the guard is satisfied. This
is what "moves" the workflow. (This might be done elsewhere - I haven't checked yet).
Where is a case in the workflow?
Go to workflow admin -> your workflow -> x cases total
There is a breakdown of cases in places. Click on the relevant one for your case.
Select your case from the list.
This shows the case details, including a Graphviz representation of the workflow
with the current position in it highlighted in blue (Process State panel).
When a task is created it's state is 'enabled'. There will also be a token in the place
before the transition the task is for, whose state is 'free'.
There is a Quest hack that automatically starts a task for a user when they click on
the task in their inbox. Starting a task puts it into a state of 'started', and locks
the token at it's "in" place.
If a token's state is locked, the process state image highlights the transition.
If a token's state is free, the process state image highlights the place.
Automatic transitions
These are used for parts of the workflow that depend on your own callbacks
when you want to direct the workflow automatically. If you want your worklfow
to move automatically sometimes, but not others you shouldn't make the transition
auto because it will always fire. If no guards are satisfied no new tokens will
be created and there will be no active tasks on the workflow.
Glossary
- Case
- A case is an instance of a workflow. Stored in WF_CASES, identified by CASE_ID. Usually a case is tied to a ticket by the column WF_CASES.OBJECT_ID.
- Workflow
- A definition of a business process using places, transitions, attributes and roles.
