Basics of Oracle Workflows Engine | Print | E-mail

Written by Sudhakar Jukanti

Tuesday, 20 February 2007
Please find yet another article written by Oracle Workflow Expert Mr Sudhakar
Jukanti, whereby he explains the key API's of Oracle Workflow Engine.
Thanks Sudhakar for yet another contribution to Oracle Apps Community.
Sudhakar also happens to be a CSCP (certified supply chain professional)

The Oracle Workflow Engine:

--> Is implemented in server-side PL/SQL.
Combination of Tables/Views/Packages and procedures
--> Manages the state of activities for each process instance.
--> Determines the next activity once a prerequisite activity completes.
--> Executes function activities automatically.
--> Calls 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
--> Stops 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.