The Content Engine APIs provide task-related classes for coordinating and tracking content-centric workflows, consisting of multiple steps and user roles, such as in claim- and loan-processing applications. A task is a single work item to be completed as part of a process, which might involve multiple related or independent work items.
A single task is represented by a CmTask object. A CmTask object has a content-based coordinator, such as a Folder, Document, or CustomObject that associates the task to a business object in a process. A CmTask object also has a changeable state to reflect the status of a work item in a process (see Task State Machine). Typically, a CmTask object drives and responds to state changes through events and subscriptions.
A CmTask object can have successor and predecessor tasks, which, collectively, define the order that all tasks execute in a process. Predecessor-successor associations are specified by CmTaskRelationship objects.
A predecessor task in a task relationship can be either a required task or an alternate task. A successor task can have required predecessors, alternate predecessors, or a mix of both. In order for a successor task to advance, all of it's required predecessor tasks must complete, and at least one of its alternate predecessor tasks must also complete.
For example, if task relationships associate successor taskX with required predecessors taskA and taskB and with alternate predecessors taskC and taskD, then taskX can advance when both taskA and taskB are completed, and when either taskC or taskD is completed.
Note that CmTask is a base class that does not allow instances. You can only create instances from a subclass of CmTask. For code examples, see Working with Task Objects.
Task State Machine
As shown in the following diagram, CmTask has internal states, indicating how a task is progressing towards completion.
State changes are made automatically by the Content Engine or manually by a client. A CmTask object can be promoted (left to right in the diagram) to a new state, or it can be demoted (right to left) to a previous state. The states are defined in the TaskState constant class.
Pre- and post-conditions can be set on a CmTask object, and the conditions are tested when an attempt is made to manually promote a state. Promotion fails if the condition evaluates to false.
Manual state changes are invoked with the changeState (LifecycleChangeFlags flags) method on CmTask. Every state change, whether manual or automatic, generates a ChangeStateEvent, to which you can subscribe and configure for auditing. For manual changes, the LifecycleOperation property of the ChangeStateEvent object directly reflects the flag value given in the changeState method call. For automatic changes, the LifecycleOperation property is either PROMOTE or DEMOTE, depending on the direction of the state change.
Each of the states, and the transitions into and out of the states, is described below.
Waiting (Precondition)
Indicates that the task has yet to satisfy its pre-condition, but is not blocked by any incomplete predecessors. This is the initial state for all newly created task instances, irrespective of whether the precondition is immediately satisfied, or whether there is a precondition set on the task.
This state can be reentered in the following circumstances:
- From WAITING_ALL
- When the last incomplete predecessor task enters COMPLETE state.
- Upon deletion of a task relationship for which this task is the successor, removing the only predecessor constraint holding this task back.
- Upon creation of a task relationship for which this task is the successor, where the predecessor task is in the COMPLETE state.
- From READY
- By a demote operation.
The task can move from this state in the following circumstances:
- To WAITING_ALL
- When a predecessor task moves from COMPLETE to WORKING state.
- Upon deletion of a task relationship for which this task is the successor, removing an alternate predecessor task that is in the COMPLETE state.
- Upon creation of a task relationship specifying this task as the successor, and the state of the predecessor task is not COMPLETE.
- To READY
- By a promote operation, subject to the pre-condition being satisfied. (An exception will be thrown on an attempted promote if the pre-condition is not satisfied.)
Waiting (All)
Indicates that the task is blocked by both incomplete predecessors and an unsatisfied pre-condition.
This state can be entered in the following circumstances:
- From WAITING_PRECONDITION
- When a predecessor task moves from COMPLETE to WORKING state.
- Upon deletion of a task relationship for which this task is the successor, removing an alternate predecessor task that is in the COMPLETE state.
- Upon creation of a task relationship specifying this task as the successor, and the state of the predecessor task is not COMPLETE.
- From WAITING_PREDECESSORS
- By a demote operation.
The task can move from this state in the following circumstances:
- To WAITING_PRECONDITION
- When the last incomplete predecessor task enters COMPLETE state.
- Upon deletion of a task relationship for which this task is the successor, removing the only predecessor constraint holding this task back.
- Upon addition of a task relationship for which this task is the successor, where the predecessor task is in the COMPLETE state.
- To WAITING_PREDECESSORS
- By a promote operation, subject to the pre-condition being satisfied.
Waiting (Predecessors)
Applies when the task has satisfied its precondition but is blocked by incomplete predecessors.
This state can be entered in the following circumstances:
- From READY
- When a predecessor task moves from COMPLETE to WORKING state.
- Upon deletion of a task relationship for which this task is the successor, removing an alternate predecessor task that is in the COMPLETE state.
- Upon creation of a task relationship specifying this task as the successor, and the state of the predecessor task is not COMPLETE.
- From WAITING_ALL
- By a promote operation, subject to the pre-condition being satisfied. (An exception will be thrown on an attempted promote if the pre-condition is not satisfied.)
The task can move from this state in the following circumstances:
- To READY
- When the last incomplete predecessor task enters COMPLETE state.
- Upon deletion of a task relationship for which this task is the successor, removing the only predecessor constraint holding this task back.
- Upon addition of a task relationship for which this task is the successor, where the predecessor task is in the COMPLETE state.
- To WAITING_ALL
- By a demote operation.
Ready
Indicates that the task is no longer blocked either by incomplete predecessors or by a pre-condition, and, therefore, it is ready to be worked on.
This state can be entered in the following circumstances:
- From WAITING_PREDECESSORS
- When the last incomplete predecessor task enters COMPLETE state.
- Upon deletion of a task relationship for which this task is the successor, removing the only predecessor constraint holding this task back.
- Upon addition of a task relationship for which this task is the successor, where the predecessor task is in the COMPLETE state.
- From WAITING_PRECONDITION
- By a promote operation, subject to the pre-condition being satisfied.
- From WORKING
- By a demote operation.
The task can move from this state in the following circumstances:
- To WAITING_PREDECESSORS
- When a predecessor task moves from COMPLETE to WORKING state.
- Upon deletion of a task relationship for which this task is the successor, removing an alternate predecessor task that is in the COMPLETE state.
- Upon creation of a task relationship specifying this task as the successor, and the state of the predecessor task is not COMPLETE.
- To WAITING_PRECONDITION
- By a demote operation.
- To WORKING
- By a promote operation.
Working
Signifies that the task is now being actively worked on, such as a workflow having been launched as a result of the change into the WORKING state.
In this state, an attempt to create a task relationship specifying this task as the successor will be disallowed unless the state of the predecessor task for that task relationship is COMPLETE. (Blocking dependencies cannot be introduced once a task has started.)
This state can be entered in the following circumstances:
- From READY by a promote.
- From COMPLETE by a demote operation.
- From FAILED by a clear exception operation.
The task can move from this state in the following circumstances:
- To READY by a demote operation.
- To COMPLETE by a promote operation.
- To FAILED by a set exception operation.
Complete
Indicates that the task has been successfully completed. It can be reached only by a promote operation from the WORKING state, subject to validation of the post-condition. The promote operation will receive an exception if the post-condition is not satisfied, and the state will be unchanged.
A successful transition to COMPLETE might release successor (dependent) tasks from a WAITING_ALL or WAITING_PREDECESSORS state as described above.
A task in COMPLETE state can be moved back to WORKING by a demote operation, but this is only permitted if the task has no successors that have already moved beyond READY. If permitted, successors in READY state can be moved to WAITING_PREDECESSORS, and those in WAITING_PRECONDITION can be moved to WAITING_ALL, subject to the conditions for moving to those states as described above.
In this state, an attempt to create a task relationship specifying this task as the successor will be disallowed unless the state of the predecessor task for that task relationship is COMPLETE.
Failed
Applied when execution of a task fails for some reason, and is reached only by a set exception operation from the WORKING state. If the error condition is resolved, the task can be moved back to WORKING by a clear exception operation.
In this state, an attempt to create a task relationship specifying this task as the successor will be disallowed unless the state of the predecessor task for the task relationship is COMPLETE.