Oracle Workflow Engine API

The Oracle Workflow Engine:

• Manages the state of activities for each process instance.

• Is implemented in server-side PL/SQL. Combination of Tables/Views/Packages and procedures

• Determines the next activity once a prerequisite activity completes.

• Executes function activities automatically.

• the Notification System to send notification messages

• Supports results-based branches, parallel branches, loops, and sub-processes.

• Can execute activities from non-savepoint environments such as database triggers and distributed transactions.

• Can defer activities too costly to execute in real time to background engines for processing.

• Maintains a history of completed activities.

• Detects error conditions and executes error processes.

Initiating a Workflow Process
We Call the Workflow Engine APIs to initiate a workflow process.
Use the CreateProcess and StartProcess APIs if you want to perform additional tasks, such as setting item attributes, after creating and before starting the process.
If you do not need to perform any additional tasks, you can use the LaunchProcess API, which is a wrapper combining the CreateProcess and StartProcess APIs.

The procedure that executes the Workflow Engine APIs to initiate a process must identify the item type and item key of the process for these APIs. The item type and item key passed to these APIs uniquely identify an item and must be passed to subsequent API calls for each specific process.


Workflow Engine Processing
Upon starting a process, the Workflow Engine:

• Identifies and executes the Start activity node

Executes the Start node if it is a function, notification, or process activity

• Determines the next activity to transition to after completing the prerequisite activity or activities

• Drives through the process

Automatically executes function activities and Send or Raise event activities
Pauses when it encounters a notification activity or blocking activity

• Calls the Notification System to notify a performer

Transitions to the next activity after the performer completes the notification,
the blocking activity is completed, or the event message is received

• when it encounters an End activity

Exception Handling
Use WF_CORE APIs to raise and catch errors in your PL/SQL procedures.

The Workflow Engine sets the status of the function activity to “ERROR” if:
The PL/SQL procedure raises an unhandled exception
The PL/SQL procedure returns a result beginning with “ERROR:”

If an activity encounters an error, information about the error is stored in the following columns in the WF_ITEM_ACTIVITY_STATUSES table, which are viewable from the Workflow Monitor.

• ERROR_NAME

• ERROR_MESSAGE

WORKFLOW ENGINE API’s
To start or run a workflow process

• WF_ENGINE.CreateProcess creates a new runtime process for a work item.

• WF_ENGINE.StartProcess begins execution of the specified process.

• WF_ENGINE.LaunchProcess launches a specified process by creating the new runtime process and beginning its execution.

• WF_ENGINE.SetItemOwner sets the owner of an existing item.

• WF_ENGINE.SetItemUserKey sets a user-friendly identifier for an item.

• WF_ENGINE.GetItemUserKey returns the user-friendly identifier assigned to an item.

• WF_ENGINE.SetItemParent defines the parent/child relationship for master/detail processes.

• WF_ENGINE.Event receives an event from the Business Event System into a workflow process.

• WF_ENGINE.Background runs a background engine to process deferred and timed out activities and stuck processes.

• WF_ENGINE.CreateForkProcess forks a runtime process by creating a new process that is a copy of the original.

• WF_ENGINE.StartForkProcess begins execution of the specified new forked process.

To communicate attribute information to the Workflow Engine

• WF_ENGINE.SetItemAttrText, WF_ENGINE.SetItemAttrNumber, WF_ENGINE.SetItemAttrDate, and WF_ENGINE.SetItemAttrEvent set the value of an item type attribute in a process.

• WF_ENGINE.SetItemAttrTextArray, WF_ENGINE.SetItemAttrNumberArray, and WF_ENGINE.SetItemAttrDateArray set the values of an array of item type attributes in a process.

• WF_ENGINE.GetItemAttrText, WF_ENGINE.GetItemAttrNumber, WF_ENGINE.GetItemAttrDate, and WF_ENGINE.GetItemAttrEvent return the value of an item type attribute in a process.

• WF_ENGINE.GetItemAttrInfo returns information about an item attribute, such as its type and format.

• WF_ENGINE.AddItemAttr adds a new item attribute to the runtime process.

• WF_ENGINE.AddItemAttrTextArray, WF_ENGINE.AddItemAttrNumberArray, and WF_ENGINE.AddItemAttrDateArray add an array of new item type attributes to the runtime process.

• WF_ENGINE.GetActivityAttrText, WF_ENGINE.GetActivityAttrNumber, WF_ENGINE.GetActivityAttrDate, and WF_ENGINE.GetActivityAttrEvent return the value of an activity attribute in a process.

• WF_ENGINE.GetActivityAttrInfo returns information about an activity attribute, such as its type and format.

To communicate state changes to the Workflow Engine

• WF_ENGINE.CompleteActivity notifies the engine that the specified activity has been completed for the item, identifying the activity by the activity node label name.

• WF_ENGINE.CompleteActivityInternalName notifies the engine that the specified activity has been completed for the item, identifying the activity by its internal name.

• WF_ENGINE.BeginActivity determines if the specified activity can currently be performed and raises an exception if it cannot.

• WF_ENGINE.AssignActivity assigns an activity to another performer.

• WF_ENGINE.GetActivityLabel returns the instance label of an activity, given the internal activity instance identification.

• WF_ENGINE.AbortProcess aborts process execution and cancels outstanding notifications.

• WF_ENGINE.SuspendProcess suspends process execution so that users cannot transition items to new activities.

• WF_ENGINE.ResumeProcess returns a suspended process to normal execution status.

• WF_ENGINE.HandleError handles any activity that has encountered an error. This API can also be called for any arbitrary activity in a process to roll back part of the process to that activity.

• WF_ENGINE.ItemStatus returns the status and results for the root process of the specified item instance.