Overview of the Workflow Engine
The Workflow Engine manages all automated aspects of a workflow process for each item. The engine is implemented in server-side PL/SQL and is activated whenever a call to a workflow procedure or function is made.
Additionally, Workflow Engines can be set up as background tasks to perform activities that are too costly to execute in real time.
The Workflow Engine performs the following services for a client application:
- It manages the state of all activities for an item, and in particular, determines which new activity to transition to whenever a prerequisite activity completes.
- It automatically executes function activities (execution is either immediate or else is deferred to a background engine) and sends notifications.
- It maintains a history of an activity's status.
- It detects error conditions and executes error processes.
The state of a workflow item is defined by the various states of all activities that are part of the process for that item. The engine changes activity states in response to an API call to update the activity family of calls. The API calls that update activity states are:
Based on the result of a previous activity, the engine also attempts to execute the next activity directly. An activity may have the following status:
Completion Processing
Engine processing is triggered whenever a process activity completes and calls the Workflow Engine API. The engine then attempts to execute (or mark for deferred execution) all activities that are dependent on the completed activity.
Note: A process as a whole can complete but still contain activities that were visited but not yet completed. For example, a completed process may contain a standard Wait activity that is not complete because the designated length of time to wait has not yet elapsed. When the process as a whole completes, the Workflow Engine marks these incomplete activities as having a status of COMPLETE and a result of #FORCE. This distinction is important if you need to include this information in your process status reports.
Deferred Processing
The engine has a deferred processing feature that allows long-running tasks to be handled by background engines instead of in real time. Deferring the execution of activity functions to background engines allows the Workflow Engine to move forward to process other activities that are currently active. The engine can be set up to operate anywhere on a continuum between processing all eligible work immediately, to processing nothing and marking all transitions as deferred.
Associated with each activity is a user-defined processing cost. This cost may be small if the activity merely sets an item attribute, or it may be very high if the activity performs a resource-intensive operation. Since the engine operates within the CompleteActivity procedure call, its execution is synchronous, meaning the engine must finish processing before control returns to the caller (for example, a form). If the result of a completed activity triggers the execution of a costly function, the caller might want to defer the execution of that costly function to a background engine.
To implement the deferred behavior, the engine recognizes a threshold cost above which it will simply mark an activity as DEFERRED rather than attempting to execute it. A background engine can be set up to poll for deferred activities and to process them. Some sites may have multiple background engines operating at different thresholds, so that there would be no chance of tying up all background processing with long operations.
Error Processing
Errors that occur during workflow execution cannot be directly returned to the caller, since the caller generally does not know how to respond to the error (in fact, the caller may be a background engine with no human operator). You can use Oracle Workflow Builder to define the events you want to occur in case of an error. Use Oracle Workflow Builder to modify the Default Error Process associated with the System:Error item type or create your own custom error process. See: Default Error Process.
The error process can include branches based on error codes, send notifications, and attempt to deal with the error using automated rules for resetting, retrying, or skipping the failed activity. Once you define an error process, you can associate it with any activity. The error process is then initiated whenever an error occurs for that activity. See: To Define Optional Activity Details.
The Workflow Engine traps errors produced by function activities by setting a savepoint before each function activity. If an activity produces an unhandled exception, or returns an invalid result, the engine performs a rollback to the savepoint, and sets the activity to the ERROR status.
Note: For this reason, you should never commit within the PL/SQL procedure of a function activity. In general, the Workflow Engine never issues a commit as it is the responsibility of the calling application to commit.
The Workflow Engine then attempts to locate an error process to run by starting with the activity which caused the error, and then checking each parent process activity until an associated error process is located.
Looping
Looping occurs when the completion of an activity causes a transition to another activity that has already been completed. This can be handled in two ways: 1) Ignore the transition (a "run once" activity) or 2) Reset the process to the loop point (undo the activities within the loop). Every activity has a Loop Reset check box in Oracle Workflow Builder so the you can specify the behavior for the activity if a loop occurs.
Turning Loop Reset off is useful for implementing activities that should only run once, even though they can be transitioned to from multiple sources. For example, this mode allows the implementation of a "logical OR" activity, which is transitioned to multiple times, but completes after the first transition. This mode would only be useful in user defined activities when implementing some other OR-like function.
Turning Loop Reset on for an activity causes the engine, upon transitioning to that completed activity, to transition backwards through the completed loop and reset that part of the process so that the engine can begin execution again from the reset point. An example of this behavior is if a process contained a loop where a purchase order were returned to the requester for modification and resubmission.
The engine clears the activities in a loop by:
- Building a list of all activities visited following the loop reset point, and
- Traversing the list in reverse order, cancelling each activity and resetting its status.
Cancelling an activity is similar to running the activity, except that the activity is executed in "CANCEL" mode instead of in "RUN" mode. The activity can then reverse any operation it performed to allow for reexecuting the loop. For example, if an activity sent out a notification, the notification would be canceled.
Version / Effective Date
Activities and processes are marked with a version number so that more than one version of an activity or a process definition can be in use at any one time. An effective date controls which version of the definition the engine uses when executing a process (the engine uses the latest eligible version). When you edit a process and save it to the database, you can save it with an immediate or future effective date. The version number is then increased by one. See: Retrieving and Saving Item Types.
Item Type Attributes
A set of item type attributes is defined at both design-time and runtime for each item. These attributes provide information to the function and notification activities used in the processes associated with the item type.
