In addition to managing a process, the Workflow Engine also supports the following features:
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 when you review your process status through the Workflow Monitor.
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.
Each activity has a user-defined processing cost. You can set this cost to be small if the activity merely sets an item attribute, or you may set it to be very high if the activity performs a resource-intensive operation. If the result of a completed activity triggers the execution of a costly function, you might want to defer the execution of that costly function to a background engine.
The Workflow Engine integrates with Oracle Advanced Queues to carry out deferred processing. If a function activity has a cost that exceeds the main threshold cost, the Workflow Engine marks that activity with a status of 'DEFERRED' in the workflow status tables and enqueues the deferred activity to a special queue for deferred activities. A special queue processor called the background engine checks and processes the activities in the 'deferred' queue. The order in which the deferred activities are processed are based on the first in, first out ordering of an activity's enqueue time. At least one background engine must be set up to run at all times. Some sites may have multiple background engines operating at different thresholds or item type specifications, to avoid tying up all background processing with long-running operations.
See: Setting Up Background Engines, Activity Cost, and Deferring Activities.
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 processing you want to occur in case of an error. Use Oracle Workflow Builder to assign the Default Error Process associated with the System:Error item type or create your own custom error process. See: Error Handling for Workflow Processes.
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, 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. 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 occurs when the completion of an activity causes a transition to another activity that has already been completed. The first activity that gets detected as a revisited activity is also called a loop point or pivot activity. The Workflow Engine can handle a revisited activity in one of three ways:
Ignore the activity, and stop further processing of the thread, so in effect, the activity can only run once.
Reset the loop to the loop point before reexecuting by first running logic to undo the activities within the loop.
Reexecute the loop point and all activities within the loop without running any logic.
Every activity has an On Revisit poplist field in its Oracle Workflow Builder Details property page. The On Revisit poplist lets you specify the behavior of the Workflow Engine when it revisits the activity in a workflow process. You can set the field to Ignore, Reset, or Loop.
Setting On Revisit to Ignore 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 you to implement a "logical OR" type of activity which is transitioned to multiple times, but completes after the first transition only.
Setting On Revisit to Reset for an activity is useful when you want to reexecute activities in a loop, but you want to first reset the status of the activities in the loop. Reset causes the Workflow Engine to do the following:
Build a list of all activities visited following the pivot activity.
Traverse the list of activities, cancelling each activity and resetting its status.
Cancelling an activity is similar to executing the activity, except that the activity is executed in "CANCEL" mode rather than "RUN" mode. You can include compensatory logic in "CANCEL" mode that reverses any operation performed earlier in "RUN" mode.
If you set On Revisit to Reset for the pivot activity of a loop that includes an FYI notification activity, the Workflow Engine cancels the previous notification before reexecuting the loop and sending a new notification to the current performer of the notification activity.
Setting On Revisit to Loop for an activity is useful when you want to simply reexecute activities in a loop without resetting the status of the activities in the loop. Loop causes the Workflow Engine to reexecute the activity in "RUN" mode without executing any "CANCEL" mode logic for the activity.
If you set On Revisit to Loop for the pivot activity of a loop that includes an FYI notification activity, previous notifications remain open when the Workflow Engine reexecutes the loop and sends a new notification to the current performer of the notification activity.
Certain workflow objects in a process definition are marked with a version number so that more than one version of the object can be in use at any one time. These objects are:
Activities - notifications, functions, and processes
Note: Although function activities support versioning, the underlying PL/SQL code does not, unless implemented by your developer. You should avoid adding references to new activity attributes or returning result lookup codes not modelled by existing activities in your PL/SQL code.
Activity attributes
Process activity nodes
Activity attribute values
Activity transitions
If you edit and save any of the above objects in Oracle Workflow Builder to the database, Oracle Workflow automatically creates a new version of that object or the owning object by incrementing the version number by one. If you save edits to any of the above objects to an existing file, then the original objects are overwritten. If you have a process instance that is still running and you upgrade the underlying workflow definition in your Workflow server, the process instance continues to run using the version of the workflow object definitions with which it was originally initiated.
An effective date controls which version of a definition the engine uses when executing a process. When you edit a process, you can save it with an immediate or future effective date. Any new process instance that is initiated always uses the version that is specified to be effective at that point in time. See: Opening and Saving Item Types.
Note that Oracle Workflow does not maintain versions for other workflow objects. Any modifications that you save to the following objects overwrites the existing definition of the object:
Item attributes
Messages
Lookup types
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.
When you define item type attributes at runtime, you can add either individual attributes or arrays containing several attributes of the same type, using the appropriate Workflow Engine APIs. Similarly, you can set the values of existing attributes either individually or in arrays containing several attributes of the same type.
Use the array APIs whenever you need to add or set the values of large numbers of item type attributes at once. These APIs improve performance by using the bulk binding feature in the Oracle Database to reduce the number of database operations. See: AddItemAttributeArray and SetItemAttributeArray.
Note: These array APIs handle arrays that are composed of multiple item type attributes grouped together by type. Oracle Workflow does not support individual item type attributes that consist of arrays themselves.
You can associate a post-notification function with a notification activity. The Workflow Engine executes the post-notification function in response to an update of the notification's state after the notification is delivered. For example, you can specify a post-notification function that executes when the notification recipient forwards or transfers the notification. The post-notification function could perform back-end logic to either validate the legitimacy of the forward or transfer or execute some other supporting logic.
The post-notification function should be a PL/SQL procedure written to the same API standards required for function activities. See: Standard API for PL/SQL Procedures Called by Function Activities.
When you specify a post-notification function, the Workflow Engine first sets the context information to use with the function through the following global engine variables. In some cases the values of the variables differ depending on the mode in which the post-notification function is called.
WF_ENGINE.context_nid - The notification ID. For RUN or TIMEOUT mode, if the Expand Roles property is checked for the notification activity, then this variable contains the notification group ID for the notifications sent to the individual members of the role.
WF_ENGINE.context_user - The user who is responsible for taking the action that updated the notification's state.
For RESPOND, FORWARD, TRANSFER, QUESTION, or ANSWER mode, if the user was acting on his or her own behalf, then the value of WF_ENGINE.context_user varies depending on the notification interface. If the user acted through the Notification Details Web page, then WF_ENGINE.context_user is set to the user name of the logged in user. If the recipient acted through e-mail, then this variable is set to 'email:'<email_address>.
For RESPOND, FORWARD, TRANSFER, QUESTION, or ANSWER mode, if the user was acting on behalf of another user by accessing that user's Worklist Web page through the proxy user worklist access feature, then WF_ENGINE.context_user is set to the user name of that other user, to whom that worklist belongs.
For RUN or TIMEOUT mode, WF_ENGINE.context_user is set to the role assigned as the performer of the notification activity.
WF_ENGINE.context_user_comment - Comments appended to the notification.
For RESPOND mode, this variable is set to any comments entered in the special WF_NOTE Respond message attribute, if that attribute is defined for the notification.
For FORWARD or TRANSFER mode, this variable is set to any comments entered when the notification was reassigned.
For QUESTION mode, this variable is set to the request details entered when the request for more information was submitted.
For ANSWER mode, this variable is set to the answering information provided in response to the request for more information.
WF_ENGINE.context_recipient_role - The role currently designated as the recipient of the notification. This value may be the same as the value of the WF_ENGINE.context_user variable, or it may be a group role of which the context user is a member.
WF_ENGINE.context_original_recipient - The role that has ownership of and responsibility for the notification. This value may differ from the value of the WF_ENGINE.context_recipient_role variable if the notification has previously been reassigned.
WF_ENGINE.context_from_role - The role currently specified as the From role for the notification. This variable may be null if no From role is specified.
For RESPOND mode, the From role may be null or may be set by special logic in the workflow process. See: #FROM_ROLE Attribute.
For FORWARD or TRANSFER mode, the From role is the role that reassigned the notification.
For QUESTION mode, the From role is the role that sent the request for more information.
For ANSWER mode, the From role is the role that sent the answering information.
WF_ENGINE.context_new_role - The new role to which the action on the notification is directed.
For RESPOND mode, this variable is null.
For FORWARD or TRANSFER mode, this variable is set to the new recipient role to which the notification is being reassigned.
For QUESTION mode, this variable is set to the role to which the request for more information is being sent.
For ANSWER mode, this variable is set to the role that sent the request for more information and is receiving the answer.
WF_ENGINE.context_more_info_role - The role to which the most recent previous request for more information was sent. This variable may be null if no such request has previously been submitted for this notification.
WF_ENGINE.context_user_key - If the notification was sent as part of a workflow process, and a user key is set for this process instance, then WF_ENGINE.context_user_key is set to that user key. Otherwise, this variable is null.
WF_ENGINE.context_proxy - For RESPOND, FORWARD, TRANSFER, QUESTION, or ANSWER mode, if the user who took that action was acting on behalf of another user through the proxy user worklist access feature, then the value of WF_ENGINE.context_proxy is the user name of the logged in user who took the action. Otherwise, this variable is null.
You can reference these global engine variables in your PL/SQL function.
Note: For RUN mode and TIMEOUT mode, only the WF_ENGINE.context_nid and WF_ENGINE.context_user variables are set.
Note: The WF_ENGINE.context_text variable from earlier versions of Oracle Workflow is replaced by the WF_ENGINE.context_user and WF_ENGINE.context_new_role variables. The current version of Oracle Workflow still recognizes the WF_ENGINE.context_text variable for backward compatibility, but moving forward, you should only use the new WF_ENGINE.context_user and WF_ENGINE.context_new_role variables where appropriate.
Then when the notification's state changes, a notification callback function executes the post-notification function in the mode that matches the notification's state: RESPOND, FORWARD, TRANSFER, QUESTION, or ANSWER.
When a recipient responds, the Workflow Engine initially runs the post-notification function in VALIDATE mode which allows you to validate the response values before accepting the response. Then the Workflow Engine runs the post-notification function in RESPOND mode to record the response. Finally, when the Notification System completes execution of the post-notification function in RESPOND mode, the Workflow Engine automatically runs the post-notification function again in RUN mode. In this mode, the post-notification function can perform additional processing such as vote tallying.
If a notification activity times out, the Workflow Engine runs the post-notification function for the activity in TIMEOUT mode. For a Voting activity, the TIMEOUT mode logic should identify how to tally the votes received up until the timeout.
If a notification activity is reset to be reexecuted as part of a loop, the Workflow Engine runs the post-notification function in CANCEL mode.
When the post-notification function completes, the Workflow Engine erases the global engine variables.
As a final step, if the post-notification function is run in TRANSFER mode and Expand Roles is not checked for the notification activity, the Workflow Engine sets the assigned user for the notification to the new role name specified.
Important: If the post-notification function returns ERROR:<errcode> as a result or raises an exception, the Workflow Engine aborts the operation. For example, if the post-notification function is executed in FORWARD mode and it raises an exception because the role being forwarded to is invalid, an error is displayed to the user and the Forward operation is not executed. The notification recipient is then prompted again to take some type of action.
See: Notification Model.
A workflow process can be either synchronous or asynchronous. A synchronous process is a process that can be executed without interruption from start to finish. The Workflow Engine executes a process synchronously when the process includes activities that can be completed immediately, such as function activities that are not deferred to the background engine. The Workflow Engine does not return control to the calling application that initiated the workflow until it completes the process. With a synchronous process, you can immediately check for process results that were written to item attributes or directly to the database. However, the user must wait for the process to complete.
An asynchronous process is a process that the Workflow Engine cannot complete immediately because it contains activities that interrupt the flow. Examples of activities that force an asynchronous process include deferred activities, notifications with responses, blocking activities, and wait activities. Rather than waiting indefinitely when it encounters one of these activities, the Workflow Engine sets the audit tables appropriately and returns control to the calling application. The workflow process is left in an unfinished state until it is started again. The process can be restarted by the Notification System, such as when a user responds to a notification; by the background engine, such as when a deferred activity is executed; or by the Business Event System, such as when an event message is dequeued from an inbound queue and sent to the workflow process. With an asynchronous process, the user does not have to wait for the process to complete to continue using the application. However, the results of the process are not available until the process is completed at a later time.
In addition to regular synchronous and asynchronous processes, the Workflow Engine also supports a special class of synchronous processes called forced synchronous processes. A forced synchronous process completes in a single SQL session from start to finish and never inserts into or updates any database tables. As a result, the execution speed of a forced synchronous process is significantly faster than a typical synchronous process. The process results are available immediately upon completion. However, no audit trail is recorded.
There may be cases when your application requires a forced synchronous process to generate a specific result quickly when recording an audit trail is not a concern. For example, several Oracle E-Business Suite products require Account Generator workflows to generate a meaningful flexfield code derived from a series of concatenated segments pulled from various tables. The Account Generator workflows are forced synchronous processes that compute and pass back completed flexfield codes to the calling applications instantaneously.
To create a forced synchronous process, you need to set the item key of your process to #SYNCH or to wf_engine.eng_synch, which returns the #SYNCH constant, when you call the necessary WF_ENGINE APIs. Since a forced synchronous process never writes to the database, using a non-unique item key such as #SYNCH is not an issue. Your process definition, however, must adhere to the following set of restrictions:
No notification activities are allowed.
Limited blocking-type activities are allowed. A process can block and restart with a call to WF_ENGINE.CompleteActivity only if the blocking and restarting activities:
Occur in the same database session.
Contain no intervening calls to Oracle Workflow.
Contain no intervening commits.
No error processes can be assigned to the process or the process's activities.
Each function activity behaves as if On Revisit is set to Loop, and is run in non-cancelling mode, regardless of its actual On Revisit setting. Loops are allowed in the process.
No Master/Detail coordination activities are allowed.
No parallel flows are allowed in the process, as transitions from each activity must have a distinct result. This also means that no <Any> transitions are allowed since they cause parallel flows.
None of the following Standard activities are allowed:
And
Block (restricted by the conditions stated in the Limited Blocking bullet point above.)
Defer Thread
Wait
Continue Flow/Wait for Flow
Role Resolution
Voting
Compare Execution Time
Notify
No use of the background engine, that is, activities are never deferred.
No data is ever written to the Oracle Workflow tables and as a result:
The process cannot be viewed from the Workflow Monitor.
No auditing is available for the process.
Only the following WF_ENGINE API calls are allowed to be made, and in all cases, the item key supplied to these APIs must be specified as #SYNCH or wf_engine.eng_synch:
WF_ENGINE.CreateProcess
WF_ENGINE.StartProcess
WF_ENGINE.GetItemAttribute
WF_ENGINE.SetItemAttribute
WF_ENGINE.GetActivityAttribute
WF_ENGINE.CompleteActivity (for the limited usage of blocking-type activities)
WF_ENGINE API calls for any item besides the current synchronous item are not allowed.
Important: If you encounter an error from a forced synchronous process, you should rerun the process with a unique item key in asynchronous mode and check the error stack using the Workflow Monitor or the script wfstat.sql. If the synchronous process completes successfully, the error you encountered in the forced synchronous process is probably due to a violation of one of the above listed restrictions. See: Wfstat.sql.
Note: The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.
See: Synchronous, Asynchronous, and Forced Synchronous Workflows.
Events from the Business Event System are represented within workflow processes as event activities. An event activity can either raise, send, or receive a business event.
A Raise event activity raises an event to the Event Manager, triggering any subscriptions to that event. The Workflow Engine calls the WF_EVENT.Raise API to raise the event. See: Raise.
A Send event activity sends an event directly to a Business Event System agent without raising the event to the Event Manager. The Workflow Engine calls the WF_EVENT.Send API to send the event. See: Send.
A Receive event activity receives an event from the Event Manager into a workflow process, which then continues the thread of execution from that activity. The Workflow Engine can receive an event into an activity in an existing process instance that is waiting for the event, using the correlation ID in the event message to match the event with the process to which it belongs. The Workflow Engine can also receive an event into a Receive event activity that is marked as a Start activity to launch a new workflow process. The WF_ENGINE.Event API is used to receive an event into a workflow process. See: Event.
See also: Managing Business Events and Event Activities.