Below are some important API’s frequently used in workflow development / customizations.
WF_ENGINE API’s
WF_ENGINE. CreateProcess CreateProcess (itemtype in varchar2,itemkey in varchar2,process in varchar2 default );
Creates a new runtime process for an application item. For example, a Requisition item type may havea Requisition Approval Process as a top level process. When a particular requisition is created, an application calls
CreateProcess to set up the information needed to start the defined process.
WF_ENGINE. SetItemUserKey SetItemUserKey (itemtype in varchar2,itemkey in varchar2, userkey in varchar2);
Lets you set a user–friendly identifier for an item in a process, which is initially identified by an item type and item key. The user key is intended to be a user–
friendly identifier to locate items in the Workflow Monitor and other user interface components of Oracle Workflow.
WF_ENGINE. GetItemUserKey GetItemUserKey (itemtype in varchar2,itemkey in varchar2) return varchar2;
Returns the user–friendly key assigned to an item in a process, identified by an item type and item key. The user key is a user–friendly identifier to locate items in the Workflow Monitor and other user interface components of Oracle Workflow.
WF_ENGINE. SetItemOwner SetItemOwner (itemtype in varchar2,itemkey in varchar2,owner in varchar2);
A procedure to set the owner of existing items. The owner must be a valid role.
Typically, the role that initiates a transaction is assigned as the process owner, so that any participant in that role can find and view the status of that process instance in the Workflow Monitor.
WF_ENGINE. StartProcess StartProcess (itemtype in varchar2,itemkey in varchar2);
Begins execution of the specified process. The engine locates the activity marked as START and then executes it. CreateProcess( ) must first be called to define the itemtype and itemkey before calling StartProcess( ).
WF_ENGINE. LaunchProcess LaunchProcess (itemtype in varchar2,itemkey in varchar2,process in varchar2 default'',userkey in varchar2 default '',owner in varchar2 default '');
Launches a specified process by creating the new runtime process and beginning its execution. This is a wrapper that combines CreateProcess and StartProcess.
WF_ENGINE. SuspendProcess SuspendProcess (itemtype in varchar2,itemkey in varchar2,process in varchar2 default '');
Suspends process execution so that no new transitions occur. Outstanding notifications can complete by calling CompleteActivity( ), but the workflow does not transition to the next activity. Restart suspended processes by calling ResumeProcess( ). ResumeProcess(itemtype in varchar2,itemkey in
varchar2,process in varchar2 default ''); Returns a suspended process to normal execution status. Any activities that were transitioned to while the process was suspended are now executed.
WF_ENGINE. AbortProcess AbortProcess (itemtype in varchar2,itemkey in varchar2,process in varchar2 default '',result in varchar2 default eng_force);
Aborts process execution and cancels outstanding notifications. The process status is considered COMPLETE, with a result specified by the result argument.
Also, any outstanding notifications or subprocesses are set to a status of
COMPLETE with a result of force, regardless of the result argument.
WF_ENGINE. AddItemAttr AddItemAttr (itemtype in varchar2,itemkey in varchar2,aname in varchar2);
Adds an empty item type attribute variable to the process. Although most item type attributes are defined at design time, developers can create new
attributes at runtime for a specific process.
WF_ENGINE. SetItemAttrText SetItemAttrText(itemtype in varchar2,itemkey in varchar2,aname in varchar2,avalue in varchar2);
WF_ENGINE. SetItemAttrNumber SetItemAttrNumber(itemtype in varchar2,itemkey in varchar2,aname in varchar2,avalue in number);
WF_ENGINE. SetItemAttrDate SetItemAttrDate (itemtype in varchar2,itemkey in varchar2,aname in varchar2,avalue in date);
WF_ENGINE. GetItemAttrText GetItemAttrText(itemtype in varchar2,itemkey in varchar2,aname in varchar2) return varchar2;
WF_ENGINE. GetItemAttrNumber GetItemAttrNumber(itemtype in varchar2,itemkey in varchar2,aname in varchar2) return number;
WF_ENGINE. GetItemAttrDate GetItemAttrDate(itemtype in varchar2,itemkey in varchar2,aname in varchar2) return date;
WF_ENGINE. BeginActivity BeginActivity (itemtype in varchar2,itemkey in varchar2,activity in varchar2);
Determines if the specified activity can currently be performed on the process item and raises an exception if it cannot. The CompleteActivity() procedure automatically performs this function as part of its validation. However, you can use BeginActivity to verify that the activity you intend to perform is currently allowed before actually calling it.
WF_ENGINE. CompleteActivity CompleteActivity(itemtype in varchar2,itemkey in varchar2,activity in varchar2,result_code in varchar2);
Notifies the workflow engine that the specified activity has been completed for a particular item.
WF_ENGINE. ItemStatus ItemStatus(itemtype in varchar2,itemkey in varchar2,status out varchar2,result out varchar2);
Returns the status and result for the root process of the specified item instance. Possible values returned for the status are: ACTIVE, COMPLETE, ERROR, or SUSPENDED. If the root process does not exist, then the item key does not exist and will thus cause the procedure to raise an exception.
Workflow core APIs: PL/SQL procedures called by function activities can use a set of core Oracle Workflow APIs to raise and catch errors. When a PL/SQL procedure called by a function activity either raises an unhandled exception, or returns a result beginning with 'ERROR:', the Workflow Engine sets the function activity's status to ERROR and sets the columns ERROR_NAME, ERROR_MESSAGE, and ERROR_STACK in the table WF_ITEM_ACTIVITY_STATUSES to reflect the error.
WF_CORE. CLEAR CLEAR Clears the error buffers.
WF_CORE. GET_ERROR GET_ERROR(err_name out varchar2,err_message out varchar2 err_stack out varchar2);
Returns the name of a current error message and the token substituted error message. Also clears the error stack. Returns null if there is no current error.
WF_CORE. RAISE RAISE (name in varchar2);
Raises an exception to the caller by supplying a correct error number and token substituted message for the name of the error message provided.
Workflow Directory Service APIs:
WF_DIRECTORY. GetRoleUsers GetRoleUsers(role in varchar2,users out UserTable);
Returns a table of users for a given role.
WF_DIRECTORY. GetUserRoles GetUserRoles(user in varchar2,roles out RoleTable);
Returns a table of roles that a given user is assigned to.
WF_DIRECTORY. GetRoleInfo GetRoleInfo(Role in varchar2,Display_Name out varchar2,Email_Address out
varchar2,Notification_Preference out varchar2,Language out varchar2,Territory out varchar2);
Returns the following information about a role:
• Display name
• Email address
• Notification Preference ('QUERY', 'MAILTEXT', 'MAILHTML','MAILATTH', 'SUMMARY')
• Language
• Territory
WF_DIRECTORY. IsPerformer IsPerformer (user in varchar2,role in varchar2);
Returns true or false to identify whether a user is a performer of a role.
WF_DIRECTORY. GetRoleName GetRoleName (p_orig_system in varchar2,p_orig_system_id in varchar2,p_name out varchar2,p_display_name out varchar2);
Returns a Workflow display name and role name for a role given the system information from the original user and roles repository.
WF_DIRECTORY.
SetAdHocUserStatus SetAdHocUserStatus (user_name in varchar2,status in varchar2 default 'ACTIVE');
Sets the status of an ad hoc user as 'ACTIVE' or 'INACTIVE'.
WF_DIRECTORY.
SetAdHocRoleStatus SetAdHocRoleStatus (role_name in varchar2,status in varchar2 default 'ACTIVE');
Sets the status of an ad hoc role as 'ACTIVE' or 'INACTIVE'.
WF_DIRECTORY. CreateAdHocUser CreateAdHocUser (name in out varchar2,display_name in out varchar2, language in varchar2 default null, territory in varchar2 default null, description in varchar2 default null, notification_preference in varchar2 default 'MAILHTML', email_address in varchar2 default null, fax in varchar2 default null, status in varchar2 default 'ACTIVE', expiration_date in date default sysdate);
Creates a user at runtime by creating a value in the WF_LOCAL_USERS table.
This is referred to as an ad hoc user.
WF_DIRECTORY. CreateAdHocRole CreateAdHocRole (role_name in out varchar2, role_display_name in out varchar2, language in varchar2 default null, territory in varchar2 default null, role_description in varchar2 default null, notification_preference in varchar2 default'MAILHTML', role_users in varchar2 default null, email_address in varchar2 default null, fax in varchar2 default null, status in varchar2 default 'ACTIVE',expiration_date in date default sysdate);
Creates a role at runtime by creating a value in the WF_LOCAL_ROLES table.
This is referred to as an ad hoc role.
WF_DIRECTORY.
AddUsersToAdHocRole AddUsersToAdHocRole (role_name in varchar2,role_users in varchar2);
Adds users to a existing ad hoc role.
WF_DIRECTORY.
RemoveUsersFromAdHocRole RemoveUsersFromAdHocRole (role_name in varchar2,role_users in varchar2 default null);
Removes users from an existing ad hoc role.