Workflow Requirements

This document is the requirements document for the Workflow Package to be released with ACS 4.0.

Related documents include:

For Deciders:
For Workflow Designers: For Developers:

I. Vision Statement

Many web sites define non-trivial processes for creating and manipulating classes of objects that represent some higher level concept, like a task to be performed, or a document or something.

In  OpenACS , we have several modules that define such processes, including:

  • The ticket tracker has issues that transition from open to closed through various states.
  • The bboard system allows content to be moderated in various ways.
  • The user registration system allows site administrators to control registration in various ways.
  • The content management system must allow users to add content, and for editors to approve or update content before, say, the content is made "live".
These processes all have the following form:
  • The process acts upon objects of a certain type.
  • The process is the same for every objects of this type. Currently this feature is not supported.
  • For each instance of the object type, the process can be characterized as a series of possibly conditional and otherwise complex transitions that move the object from some initial state to one or more final states, after which the process is over. In this way, we can think of processes as types related to the object type, and we can think of a single *instance* of a process being implicitly created whenever an object of the related type is created.
For example, the ticket tracker defines a process for handling each ticket. When a new ticket is inserted into the system, in the abstract, a new instance of this process is created. The ticket starts in the "open" state, or whatever, and can transition into various intermediate states before becoming "closed". As long as the ticket exists, the process instance connected to that ticket also exists. But, the process instance is a purely abstract object, it has no concrete representation outside the ticket itself.

In the current system, the rules for the state transitions are encoded in the logic of the pages that make up the module that defines both the object type and the process.

The motivation for the workflow module is to define a more abstract and reusable mechanism for describing these processes.

II Glossary

Given this, and the above examples, we will use the following terminology:
a formal definition of a type of process for handling all objects of a certain type, e.g. the process for dealing with a ticket in the ticket-tracker.
a single instance of a workflow, operating on a single object of a given type. For example, a ticket is a case.
a single atomic step in a workflow, for example the tasks "fix bug" and "acknowledge fix" in the ticket-tracker workflow.
a list of tasks that have been assigned to a given user in the system. For example, the list of "fix"-tasks for the tickets you're assigned to fix, and the "approve fix"-tasks for the tickets you've opened and that have been fixed in the meantime.

III. System Overview

The workflow package consists of three separate parts.
  1. The engine is the subsystem that stores the workflow definitions and manages the workflow of individual cases. It should be defined in a way that is independent of the user interface parts of the system, so other modules don't have to buy into the workflow package UI in order to employ the engine.

  2. The end-user interface which will let the users see their work list and provide mechanisms for the user to give feedback on their actions to the system.

  3. The administrative user interface, which will let an administrator design and maintain workflow definitions and their application to different types of cases.

IV. Related Links

V. User-Scenarios

There are two classes of users for the Workflow package:
  1. Normal users use the workflow package to see what tasks they should perform and give feedback on their progress.
  2. Administrators define and maintain the workflow definitions that governs the tasks executed by normal users.
Annie Administrator is the administrator of a technical support knowledge library. For each item in the library, a moderator needs to figure out the subject and designate two qualified reviewers to review the item. Those reviewers will independently review the item, which may then have to go back to the original author for revision. After both reviewers are satisfied, it goes to the uber-categorization-meister, which will determine what categories and keywords to attach to it.

Annie Administrator uses the administrative user interface to formally define her workflow, and she defines that objects in the technical support knowledge library will be processed according to this workflow.

Tracy Techsupporter submits a new item to be included in the library. The workflow package (triggered by a hook in ACS Core) will start a new workflow case around the item. This in turn will trigger an email notification to Mike Moderator (and other moderators, if there is more than one person capable of performing the moderator task), informing him that he now has a new item on his work list. The email will contain the URLs for both his work list and the new item.

When Mike Moderator visits his work list, he'll see the list of tasks that he has reported to be currently working on, and a list of tasks he is capable of performing, ordered by priority. When he clicks on one of these tasks, he'll get to a page with information about the task to perform like this:

Task #: Task Name
Input (Required Items) Logic or Aids Output or Action
Extreme Actions
Mike Moderator decides to work on this task and clicks the Start task button. The output pane now changes to look like this:
Output or Action

Reviewer 1:

Reviewer 2:

At the same time, the task dissappears from the other moderators' work lists. Mike Moderator does his work and picks two reviewers, then hits "Finish task". This pushes the case to the next step, which will add two tasks, one for each reviewer, to review the item.

Randy Reviewer and Rick Reviewer will do essentially the same thing as Mike Moderator: They'll receive an email that there's stuff for them to review, go to the task page info page to see what to do, and do their jobs. Their "action" pane will look like this:

Output or Action



The reviewer chooses "Author must revise item", which causes a new task to be created for Tracy Techsupporter to revise her item. She does, and when she says she's finished, new tasks are created for the reviewers to re-review the item. This time, they're happy, and a task is created for Charlie Categorizer to categorize the item. He does, and the workflow ends with the item being included in the library.

VI Requirements

VI.A Requirements: Engine and Model

There should be a well-defined mathematical model underlying the workflows. Why? Because that's the best way we can ensure that the workflow engine will have clear semantics. We will inevitably come to face a situation where we're not certain how to interpret and act on a given situation. The mathematical model will tell us.


  • 10.0 Routing Constructs

    The system must support the following forms of routing

    • 10.1 Sequential Routing

      Two tasks are to be performed one after the other. This is the most common routing construct in real-world workflows.

    • 10.2 Parallel Routing

      Two tasks are to be performed simultaneously or in no particular order. This is essential for improving the throughput of a workflow, since performing two tasks in parallel are likely to be faster than performing them sequentially.

    • 10.3 Iterative Routing

      A set of tasks can be performed one or more times. The ticket-tracker has an example of this routing, in that the ticket can go to "fixed, awaiting approval" and back to "open" as many times as is necessary to finally reolve and close the ticket.

    • 10.4 Conditional Routing

      One or another task is to be performed, depending on some condition. This is often used to implement iterative routing, in that the condition determines whether we should perform one more iteration or not. Also, take approval of expenses as an example. It would be common to make the approval process different, depending on the amount in question, e.g. if it's a small amount, the applicant's supervisor can approve the expense, or if it's a very large amount, both the CEO and the chairman must approve it.

    • 10.4.1 Explicit and Implicit Condition Routing

      The decision can be made either as we're finishing the prior task, or as we execute one of the two conditional tasks. The above example is one of explicit conditional routing. An example of Implicit conditioning, is a restaurant owner purchases perishable goods, such as meat and vegatables. The food items sit in a queue waiting to be processed into meals or wait for 15 days (meat and vegatables tastes change after 15 days). If the task "wait for 15 days" is completed, then the food item is thrown away. The routing is determined by the first task to execute.


  • 40.0 Inputs

    The item that the workflow is about will always be part of the input, but there should be the option of presenting other information. Static text will do for now.

  • 50.0 Algorithms and work aids

    Each task will contain more detailed information on what is expected to be done and instructions to the person executing the task on how to go about executing it. Static text will do for now.

  • 60.0 Outputs

    A task can have a number of values as output. Examples include "review_comments", "review_conclusions" as above. We should be able to use these values in conditions for conditional routing.

  • 70.0 Transactional execution

    The execution of a task must be atomic to the system. Either the task completes or it doesn't do anything. But in the real world, a task takes time, so we must have a "start", "commit", "rollback" meachanism.

  • 70.1 There should be a date, such that, if the user has stared, but not committed or rolled back the task before that timeout date, the task is automatically rolled back and the task is created again. There should be a callback to calculate that date.

  • 80.0 Assignments

    Tasks are not assigned directly to users, instead we associate roles with a task. A role is granted to a single or a group of users. Users belonging to that role have execute privileges on the task associated with role.

    1. Static assignment: while defining the workflow
    2. Manual assignment: assignment of tasks to users is part of the workflow process, as in the user-scenario above. Only users with the role associated with task are available for selection.
    3. Programmatic assignment: The assignment is made automatically based on some condition, e.g. a category. It should be done with a call-back in the RDBMS layer, so another package that uses the workflow package can provide their own logic, without having to use the same webserver as the workflow package might.

  • 90.0 Prioritizing

    There should be some mechanism of prioritizing tasks in the work list. How to do this is yet undefined. A call-back seems desirable, but we need to determine when or how often the call-back should be executed (i.e. how often will we allow priorities to change).

    90.1 Deadline

    Each task can have a deadline, a date by which is must be performed. This is determined by a call-back as the task is created.

    90.5 Completion time A task has an entry to estimate how long it will take for completion.

    Note: Defintion of deadline is unclear: is it per case or per task? I.e., if a task is entered twice, will it have the same deadline both times, or will it have a new deadline the second time around? Or option of both?

  • 100.0 Email notification

    The users should automatically be alerted when there's a new task for them to perform.

    100.1 Not fully specified: It should also alert them when the deadline is nearing, when the priority changes, and possibly on other conditions.

  • 110.0 Side-effects

    There should be a callback mechanism allowing for side-effects at certain points in time.

    1. When a new task arrives
    2. When a task is finished.
    3. When a task gets unassigned
    4. When a task is started
    5. When a task is finished (committed)
    6. When a task is canceled (rolled back)
    7. When a task times out and is canceled.
  • 120.0 Automatic tasks

    A task can be "automatic" in the sense, that it is only there for the side-effects. It is automatically finished as soon as it is created.

    120.1 Timed automatic tasks

    Alternatively, we can specify a specific point in time, the automatic task should finish. This is useful for timeouts, e.g. when waiting for a client to return a form, we may cancel the case if we don't hear back within a month. The point in time is determined via a call-back.

    120.5 Message tasks

    A message from an external source can be passed to the task. The task is executed upon receiving the message and all the criteria placed on the message are satisfied.

  • 125.0 Commentability

    The user can post a comment on a task at any time during the life-cycle of the case . The comments are shown to the users, so they can use them as a guidance in processing the case.


  • 130.0 Workflow Contexts

    The same workflow definition may be applied in several different departments of the same company. In this case, the department will be the context of the workflow. In other situations, the same workflow definition may be applied within separate companies running on the same site. In this case, the company is the context.

    The things that are dependent on the context are:

    • Static assignment
    • The number of minutes estimated to complete the task
    • The side effect events that trigger a callback
    • Roles associated with a task.

    Note! It may or may not be the case that a context will always also be a subsite, in which case we don't need any additional concept to model this situation.

VI.B Requirements: API

Controlling the Workflow Process

  • 200.0 Start workflow

    Start a new instance of the workflow around an object. Currently it is not possible to have a callback in the kernel upon new object creation. This requires programmically calling the method to start a new case.

  • 210.0 Cancel/Suspend/Resume workflow

    Cancel/suspend/resume the overall workflow process, e.g. if an applicant backs out of the process, or the administrator decides the processing must wait a while before continuing.

  • 220.0 Start/Finish/Cancel task

    The API must provide for starting/finishing/canceling tasks.

    220.1 Finishing the task includes storing the output of the task in attributes attached to the workflow instance.

  • 230.0 Workflow Attributes

    Attributes for a process to use for branching and keeping state properties.

    230.10 Add and Edit attributes attributes per case

    230.20 Access to those attributes values in the callback procedures

Creating Workflows

  • API for defining workflows would be nice.

VI.C Requirements: Web Interface for Interacting with the Workflow Process

  • 300.0 Work list

    The user should have a work list page showing all the tasks he's supposed to perform. It should be ordered by priority/deadline.

  • 310.0 Task information and management

    See the user-scenario for a sample page.

  • 320.0 Workflow overview

    A page where you can get an overview of how a particular workflow is going overall, i.e., how all the workflow instances are doing. It's tough to come up with a good visual design of this that will give the quick overview. Needs to be thought more about. Probably not a first version thing.

VI.D Requirements: Web Interface for Defining Workflows

  • 400.0 Simple Process Wizard

    Step by step directions for creating a new workflow process. Do not expose process designer to more advance features such as addition parallel routing.

  • 410.0 Advanced Process Builder
    Exposes all the glory details of each entity within the workflow.


The initial version of this text has been written by Lars Pind and Khy Huang. Thank you Lars and Khy!


Related Workflow Topics

Related Object Types

  • [ Workflow Object Type]

Related Packages


  Contact Us
  Project Open Business Solutions S.L.

Calle Aprestadora 19, 12o-2a

08902 Hospitalet de Llobregat (Barcelona)


 Tel Europe: +34 609 953 751
 Tel US: +1 415 200 2465