7 registered users
in last 24 hours
Workflow Maintainer's Guide
Original Text by Lars Pind
This document describes the internal details of the workflow package. It is aimed at developers continuing the development of the package.
Other documents related to the ]project-open[ workflow include:
For Workflow Designers:
The workflow package consists of five major components:
|Major components of the Workflow Package
The Engine is the heart of the system. It's the part that determines what actions you can perform on a case, and keeps track of the state of the case as actions are performed. It also stores the process definitions and the state of all the cases on the system.
The Worklist is what the normal end-user sees. It's where the user goes to see the list of tasks he or she is assigned to, and interacts with the system to let us know he's done.
The Process Builder lets you define and share processes. The Process Adapter lets you customize assignments and special side-effects of your process to your situation. And finally, the Process Monitor lets you monitor the performance of a process.
Transitions and Tasks
When a transition becomes enabled, a row representing the enabled transition is inserted into
wf_tasks. This table may have more than one row per transition for a number of reasons. If the user starts the task, then decides to cancel, a new row is inserted, as the same transition becomes enabled again. If there's an iteration in the workflow definition, so the same transition becomes enabled more than once, a new row is inserted each time.
Each task has a state. It starts out as 'enabled'. It moves to 'started', then possibly to 'canceled' or 'finished' in response to user actions. If the transition is part of an implicit or-split (where two transitions share one input place), the task may become 'overridden' if the other task is triggered.
Assignments can be done in three different ways:
The actual assignment occurs when the transition is enabled. At that point, a row is inserted into
- Programmatic: You supply a callback to do the assignment. The callback will get called when the transition becomes enabled. Put the name of your callback in the
assignment_callback column in
- Manual: Assignment for one case. This is implemented as rows in
wf_case_assignments. You're encouraged to use the API:
- Static: Fixed assignment for all cases of a given workflow. This is implemented as rows in
wf_tasks and the actual assignment is determined, and copied over into
wf_task_assignments. The logic is this:
- First, we see if there are any manual assignments in
wf_case_assignments. If there is, we copy these over to
wf_task_assignments. (We used to check for a callback first, but this way if a task is reassigned, the reassignment persists for subsequent instances of the transition.)
- If there are no manual assignments and a callback is registered, that callback procedure is executed, and is expected to use the
workflow_case.add_task_assignment API to add the actual assignment for this task.
- Otherwise, we resort to the static assignment by copying over the rows from
In every event, a number of rows are created in
wf_task_assignments. This is the authoritative version of who's assigned to this task. You're free to change the assignment of a task by altering the contents of
wf_task_assignments through the API or directly. If you use the workflow UI, this change will be persistent. However, if you don't want reassignment to persist in your application, changing
wf_task_assignments alone will accomplish this.
wf_user_tasks returns one row per task and per user assigned to a task. This is the view to query to get the list of tasks on a user's plate, and to get information about assignments for a task. It does the job of traversing the parties hierarchy to expand groups.
Users can start, cancel and finish tasks. Since you can set workflow attributes as part of an action, for each of these actions, you have to make the following sequence of API calls:
(We would just accept a list of key/value pairs for the attributes, but we couldn't figure out a way to do that with PL/SQL).
workflow_case.set_attribute_value zero or more times.
action argument to the procs are 'start', 'cancel', 'finish' or 'comment'. Comment doesn't alter the state of the task, and can be used for either adding a comment on the case, and/or to set a workflow attribute without finishing the task.
It's perfectly okay to finish a task without explicitly starting it. If there are multiple users assigned to the same task, however, it's strongly recommended that the user starts the task first, as that will remove it from the worklist of other users, so we don't have multiple users working on the same task.
Data Model Changes
Whenever there's a data model change, don't forget to propagate that change to:
sql/wf-core-drop.sql DDL script.
sql/upgrade/*.sql DDL upgrade scripts.
tcl/workflow-procs.tcl file, proc
wf_export_workflow (at the bottom).
- ... and of course any UI pages that are affected must be changed too.
Related Workflow Topics
Related Object Types