Oracle Workflow API Reference Release 2.6.4 Part Number B15855-05

Contents

Previous

Next

Workflow Engine APIs

This chapter describes the APIs for the Workflow Engine. The APIs consist of views and PL/SQL and Java functions and procedures that you can use to access the Workflow Engine, the Workflow Monitor, and workflow data.

This chapter covers the following topics:

• Overview of the Workflow Engine
• Workflow Engine APIs
• Workflow Engine Bulk APIs
• Workflow Function APIs
• Workflow Attribute APIs
• Workflow Core APIs
• Workflow Purge APIs
• Workflow Monitor APIs
• Workflow Status Monitor APIs
• Oracle Workflow Views

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. Since the engine is embedded inside the Oracle Database, if the Workflow server goes down for any reason, the Oracle Database is able to manage the recovery and transactional integrity of any workflow transactions that were running at the time of the failure.

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 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. The API calls that update activity states are:

• WF_ENGINE.CreateProcess

• WF_ENGINE.StartProcess

• WF_ENGINE.CompleteActivity

• WF_ENGINE.CompleteActivityInternalName

• WF_ENGINE.AssignActivity

• WF_ENGINE.HandleError

• WF_ENGINE.SuspendProcess

• WF_ENGINE.ResumeProcess

• WF_ENGINE.AbortProcess

• WF_ENGINE_BULK.CreateProcess

• WF_ENGINE_BULK.StartProcess

• WF_ENGINE_BULK.FastForward

Based on the result of a previous activity, the engine attempts to execute the next activity directly. An activity may have the following status:

• Active - activity is running.

• Complete - activity completed normally.

• Waiting - activity is waiting to run.

• Notified - notification activity is delivered and open.

• Deferred - activity is deferred.

• Error - activity completed with error.

• Suspended - activity is suspended.

Important: 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. 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.

For environments such as database triggers or distributed transactions that do not allow savepoints, the Workflow Engine automatically traps "Savepoint not allowed" errors and defers the execution of the activity to the background engine.

Oracle Workflow components that continue workflow processing asynchronously, such as background engines and the Notification System, do issue commits when appropriate on behalf of the calling application.

Note: The Oracle Database supports autonomous transactions. By embedding the pragma AUTONOMOUS_TRANSACTION in your procedure, you can perform commits and rollbacks independently of the main transaction. Oracle treats this as a separate session; as such, you will not have access to any database changes that were made in the main session but are not yet committed. Consequently, you are restricted from updating workflow-specific data in an autonomous transaction; for instance, you cannot set item attributes. You cannot access this data because the item itself has not yet been committed, and because you may have lock contentions with the main session.

Oracle Workflow will not support autonomous commits in any procedure it calls directly. If you need to perform commits, then embed your SQL in a subprocedure and declare it as an autonomous block. This subprocedure must be capable of being rerun. Additionally, note that Oracle Workflow handles errors by rolling back the entire procedure and setting its status to ERROR. Database updates performed by autonomous commits cannot be rolled back, so you will need to write your own compensatory logic for error handling. For more information, see: Autonomous Transactions, Oracle Database Concepts.

Oracle Workflow Java Interface

The Oracle Workflow Java interface provides a means for any Java program to integrate with Oracle Workflow. The Oracle Workflow Engine and Notification APIs are accessible through public server PL/SQL packages and published views. The Oracle Workflow Java interface exposes those APIs as Java methods that can be called by any Java program to communicate with Oracle Workflow. The Java methods directly reference the WF_ENGINE and WF_NOTIFICATION PL/SQL package procedures and views and communicate with the Oracle Workflow database through JDBC.

The methods are defined within the WFEngineAPI class and the WFNotificationAPI class, in the Java package 'oracle.apps.fnd.wf.engine'. If a Workflow Engine or notification API has a corresponding Java method, its Java method syntax is displayed immediately after its PL/SQL syntax in the documentation. See: Workflow Engine APIs and Notification APIs.

Additionally, Java functions can be incorporated within Workflow processes as external Java function activities. This functionality is currently only available for the standalone version of Oracle Workflow. The custom Java classes for these activities are implemented as classes that extend the WFFunctionAPI class. The custom classes must follow a standard API format so that they can be properly executed by the Oracle Workflow Java Function Activity Agent. See: Standard API for Java Procedures Called by Function Activities, Oracle Workflow Developer's Guide and Function Activity, Oracle Workflow Developer's Guide.

The WFFunctionAPI class and the WFAttribute class also contain methods that can be called to communicate with Oracle Workflow. These classes are defined in the Java package 'oracle.apps.fnd.wf'. See: Workflow Function APIs and Workflow Attribute APIs.

Java programs that integrate with Oracle Workflow should include the following import statements to provide access to classes required by Oracle Workflow:

import java.io.*; 
import java.sql.*; 
import java.math.BigDecimal; 

import oracle.sql.*; 
import oracle.jdbc.*;

import oracle.apps.fnd.common.*; 
import oracle.apps.fnd.wf.engine.*; 
import oracle.apps.fnd.wf.*; 

Oracle Workflow Context

Each Oracle Workflow Java method that accesses the database requires an input of a WFContext object. The WFContext object consists of database connectivity information which you instantiate and resource context information that the WFContext class instantiates. To call one of these Workflow Java APIs in your Java program, you must first instantiate a database variable of class WFDB with your database username, password and alias. You can also optionally supply a JDBC string. Then you must instantiate the WFContext object with the database variable. You can retrieve the system property CHARSET to specify the character set for the database session. The following code excerpt shows an example of how to instantiate these objects.

WFDB myDB;
WFContext ctx;

myDB = new WFDB(m_user, m_pwd, m_jdbcStr, m_conStr);
m_charSet = System.getProperty("CHARSET");
if (m_charSet == null) { // cannot be null
  m_charSet = "UTF8";

}

try {
  ctx = new WFContext(myDB, m_charSet); 
  // m_charSet is 'UTF8' by default

  if (ctx.getDB().getConnection() == null) {
    // connection failed
    return;
  }

  // We now have a connection to the database.
}

catch (Exception e) {
// exit Message for this exception
}

If you have already established a JDBC connection, you can simply set that connection into the WFContext object, as shown in the following example:

WFContext ctx;

m_charSet = System.getProperty("CHARSET");
if (m_charSet == null) { // cannot be null
  m_charSet = "UTF8";
}

ctx = new WFContext(m_charSet); 
// m_charSet is 'UTF8' by default

ctx.setJDBCConnection(m_conn);  
// m_conn is a pre-established JDBC connection

The Oracle Workflow Java APIs can be used safely in a thread, with certain restrictions:

• Each thread should have its own WFContext object, meaning you should not instantiate WFContext before starting threads. Because each context keeps track of an error stack, contexts cannot be shared.

• You should not use the same JDBC connection for different workflows, because using the same connection may cause problems with commits and rollbacks for unrelated transactions.

There is no synchronized code inside the Oracle Workflow Java APIs, but there are no shared resources, either.

There is also no connection pooling in the Oracle Workflow Java APIs. For Oracle Applications, connection pooling is implemented at the AOL/J level; after you get the JDBC connection, you use the WFContext.setJDBCConnection() API to set the connection. This approach lets you manage your JDBC connection outside of the Oracle Workflow APIs.

Sample Java Program

Oracle Workflow provides an example Java program that illustrates how to call most of the Workflow Engine and Notification Java APIs. The Java program is named WFTest. It calls the various Java APIs to launch the WFDEMO process, set and get attributes, and suspend, resume, and abort the process, as well as the APIs to send a notification, set and get notification attributes, and delegate and transfer the notification. Before running the WFTest Java program, make sure you define CLASSPATH and LD_LIBRARY_PATH for the Oracle JDBC implementation and a supported version of Oracle. For example, on UNIX, use the following commands:

setenv CLASSPATH 
<Workflow_JAR_file_directory>/wfapi.jar:${ORACLE_HOME}/jdbc/lib/classes111.zip

setenv LD_LIBRARY_PATH ${ORACLE_HOME}/lib:${LD_LIBRARY_PATH}

Note: If you are using the standalone version of Oracle Workflow, the Workflow JAR files are located in the <ORACLE_HOME>/jlib directory. If you are using the version of Oracle Workflow embedded in Oracle Applications, the Workflow JAR files are located in the <ORACLE_HOME>/wf/java/oracle/apps/fnd/wf/jar/ directory.

To initiate the WFTest program, run Java against oracle.apps.fnd.wf.WFTest. For example, on UNIX, enter the following statement on the command line:

$java oracle.apps.fnd.wf.WFTest

The source file for this program is also included in your Oracle Workflow installation so that you can view the sample code. The source file is named WFTest.java and is located in the <ORACLE_HOME>/wf/java/oracle/apps/fnd/wf/ directory.

Additional Workflow Engine Features

In addition to managing a process, the Workflow Engine also supports the following features:

• Completion Processing

• Deferred Processing

• Error Processing

• Looping

• Version/Effective Date

• Item Type Attributes

• Post-Notification Functions

• Synchronous, Asynchronous, and Forced Synchronous Processes

• Business Events

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 when you review your process status through the Workflow Monitor.

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.

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, Oracle Workflow Administrator's Guide, Activity Cost, Oracle Workflow Developer's Guide, and Deferring Activities, Oracle Workflow Administrator's Guide.

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 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, Oracle Workflow Developer's Guide.

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, Oracle Workflow Developer's Guide.

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

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.

Version / Effective Date

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, Oracle Workflow Developer's Guide.

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

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.

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.

Post-Notification Functions

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, Oracle Workflow Developer's Guide.

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 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, Oracle Workflow Developer's Guide.

  • 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 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.

Synchronous, Asynchronous, and Forced Synchronous Processes

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, in Oracle Applications, several 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, Oracle Workflow Administrator's Guide.

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, Oracle Workflow Administrator's Guide.

Business Events

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, Oracle Workflow Developer's Guide and Event Activities, Oracle Workflow Developer's Guide.

Workflow Engine APIs

The Workflow Engine APIs can be called by an application program or a workflow function in the runtime phase to communicate with the engine and to change the status of each of the activities. These APIs are defined in a PL/SQL package called WF_ENGINE.

Many of these Workflow Engine APIs also have corresponding Java methods that you can call from any Java program to integrate with Oracle Workflow. The following list indicates whether the Workflow Engine APIs are available as PL/SQL functions/procedures, as Java methods, or both.

Important: Java is case-sensitive and all Java method names begin with a lower case letter to follow Java naming conventions.

• CreateProcess - PL/SQL and Java

• SetItemUserKey - PL/SQL and Java

• GetItemUserKey - PL/SQL and Java

• GetActivityLabel - PL/SQL

• SetItemOwner - PL/SQL and Java

• StartProcess - PL/SQL and Java

• LaunchProcess - PL/SQL and Java

• SuspendProcess - PL/SQL and Java

• ResumeProcess - PL/SQL and Java

• AbortProcess - PL/SQL and Java

• CreateForkProcess - PL/SQL

• StartForkProcess - PL/SQL

• Background - PL/SQL

• AddItemAttribute - PL/SQL and Java

• AddItemAttributeArray - PL/SQL

• SetItemAttribute - PL/SQL and Java

• setItemAttrFormattedDate - Java

• SetItemAttrDocument - PL/SQL and Java

• SetItemAttributeArray - PL/SQL

• getItemTypes - Java

• GetItemAttribute - PL/SQL

• GetItemAttrDocument - PL/SQL

• GetItemAttrClob - PL/SQL

• getItemAttributes - Java

• GetItemAttrInfo - PL/SQL

• GetActivityAttrInfo - PL/SQL

• GetActivityAttribute - PL/SQL

• GetActivityAttrClob - PL/SQL

• getActivityAttributes - Java

• BeginActivity - PL/SQL

• CompleteActivity - PL/SQL and Java

• CompleteActivityInternalName - PL/SQL

• AssignActivity - PL/SQL

• Event - PL/SQL

• HandleError - PL/SQL and Java

• SetItemParent - PL/SQL and Java

• ItemStatus - PL/SQL and Java

• getProcessStatus - Java

Some Workflow Engine APIs use PL/SQL table composite datatypes defined in the WF_ENGINE package. The following table shows the column datatype definition for each PL/SQL table type.

Related Topics

Standard API for PL/SQL Procedures Called by Function Activities, Oracle Workflow Developer's Guide

CreateProcess

PL/SQL Syntax

procedure CreateProcess
  (itemtype in varchar2,
   itemkey in varchar2,
   process in varchar2 default '',
   user_key in varchar2 default null,
   owner_role in varchar2 default null);

Java Syntax

public static boolean createProcess
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String process)

Description

Creates a new runtime process instance for an application item.

For example, a Requisition item type may have a 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.

Caution: Although you can make a call to CreateProcess() and StartProcess() from a database trigger to initiate a workflow process, you should avoid doing so in certain circumstances. For example, if a database entity has headers, lines and details, and you initiate a workflow process from an AFTER INSERT trigger at the header-level of that entity, your workflow process may fail because some subsequent activity in the process may require information from the entity's lines or details level that is not yet populated.

Important: The Workflow Engine always issues a savepoint before executing each activity in a process so that it can rollback to the previous activity in case an error occurs. For environments such as database triggers or distributed transactions that do not allow savepoints, the Workflow Engine automatically traps "Savepoint not allowed" errors and defers the execution of the activity. If you initiate a workflow process from a database trigger, the Workflow Engine immediately defers the initial start activities to a background engine, so that they are no longer executing from a database trigger.

Note: To create several instances of the same workflow process at once, call WF_ENGINE_BULK.CreateProcess instead. See: WF_ENGINE_BULK.CreateProcess.

Arguments (input)

Example

The following code excerpt shows an example of how to call createProcess() in a Java program. The example code is from the WFTest.java program.

// create an item
if (WFEngineAPI.createProcess(ctx, iType, iKey, pr))
  System.out.println("Created Item");
  else
{
  Systm.out.println("createProcess failed");
  WFEngineAPI.showError(ctx);
}

SetItemUserKey

PL/SQL Syntax

procedure SetItemUserKey
  (itemtype in varchar2,
   itemkey in varchar2,
   userkey in varchar2);

Java Syntax

public static boolean setItemUserKey
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String userKey)

Description

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.

Arguments (input)

GetItemUserKey

PL/SQL Syntax

function GetItemUserKey
  (itemtype in varchar2,
   itemkey in varchar2)
  return varchar2;

Java Syntax

public static String getItemUserKey
  (WFContext wCtx,
   String itemType,
   String itemKey)

Description

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.

Arguments (input)

GetActivityLabel

PL/SQL Syntax

function GetActivityLabel
  (actid in number)
  return varchar2;

Description

Returns the instance label of an activity, given the internal activity instance ID. The label returned has the following format, which is suitable for passing to other Workflow Engine APIs, such as CompleteActivity and HandleError, that accept activity labels as arguments:

<process_name>:<instance_label> 

Arguments (input)

SetItemOwner

PL/SQL Syntax

procedure SetItemOwner
  (itemtype in varchar2,
   itemkey in varchar2,
   owner in varchar2);

Java Syntax

public static boolean setItemOwner
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String owner)

Description

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.

Arguments (input)

Example

The following code excerpt shows an example of how to call setItemOwner() in a Java program. The example code is from the WFTest.java program.

// set item owner
if (WFEngineAPI.setItemOwner(ctx, iType, iKey, owner))
  System.out.println("Set Item Owner: "+owner);
else
{
  System.out.println("Cannot set owner.");
  WFEngineAPI.showError(ctx);
}

StartProcess

PL/SQL Syntax

procedure StartProcess
  (itemtype in varchar2,
   itemkey in varchar2);

Java Syntax

public static boolean startProcess
  (WFContext wCtx,
   String itemType,
   String itemKey)

Description

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 item type and item key before calling StartProcess().

Caution: Although you can make a call to CreateProcess() and StartProcess() from a trigger to initiate a workflow process, you should avoid doing so in certain circumstances. For example, if a database entity has headers, lines and details, and you initiate a workflow process from an AFTER INSERT trigger at the header-level of that entity, your workflow process may fail because some subsequent activity in the process may require information from the entity's lines or details level that is not yet populated.

Caution: The Workflow Engine always issues a savepoint before executing each activity so that it can rollback to the previous activity in case an error occurs. Because of this feature, you should avoid initiating a workflow process from a database trigger because savepoints and rollbacks are not allowed in a database trigger.

If you must initiate a workflow process from a database trigger, you must immediately defer the initial start activities to a background engine, so that they are no longer executing from a database trigger. To accomplish this:

• Set the cost of the process start activities to a value greater than the Workflow Engine threshold (default value is 0.5)

  or

• Set the Workflow Engine threshold to be less than 0 before initiating the process:

  begin
    save_threshold := WF_ENGINE.threshold;
    WF_ENGINE.threshold := -1;
    WF_ENGINE.CreateProcess(...);
    WF_ENGINE.StartProcess(...);
  --Always reset threshold or all activities in this
  --session will be deferred.
    WF_ENGINE.threshold := save_threshold;
  end
  

  (This method has the same effect as the previous method, but is more secure as the initial start activities are always deferred even if the activities' costs change.

Note: To begin execution of several instances of the same workflow process at once, call WF_ENGINE_BULK.StartProcess instead. See: WF_ENGINE_BULK.StartProcess.

Arguments (input)

Example

The following code excerpt shows an example of how to call startProcess() in a Java program. The example code is from the WFTest.java program.

// start a process
if (WFEngineAPI.startProcess(ctx, iType, iKey))
  System.out.println("Process Started successfully");
  else
{
  System.out.println("launch failed");
  WFEngineAPI.showError(ctx);
}

LaunchProcess

PL/SQL Syntax

procedure LaunchProcess
  (itemtype in varchar2,
   itemkey in varchar2,
   process in varchar2 default '',
   userkey in varchar2 default '',
   owner in varchar2 default '');

Java Syntax

public static boolean launchProcess
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String process,
   String userKey,
   String owner)

Description

Launches a specified process by creating the new runtime process and beginning its execution. This is a wrapper that combines CreateProcess and StartProcess.

Caution: Although you can make a call to CreateProcess() and StartProcess() from a database trigger to initiate a workflow process, you should avoid doing so in certain circumstances. For example, if a database entity has headers, lines and details, and you initiate a workflow process from an AFTER INSERT trigger at the header-level of that entity, your workflow process may fail because some subsequent activity in the process may require information from the entity's lines or details level that is not yet populated.

Important: The Workflow Engine always issues a savepoint before executing each activity in a process so that it can rollback to the previous activity in case an error occurs. For environments such as database triggers or distributed transactions that do not allow savepoints, the Workflow Engine automatically traps "Savepoint not allowed" errors and defers the execution of the activity. If you initiate a workflow process from a database trigger, the Workflow Engine immediately defers the initial start activities to a background engine, so that they are no longer executing from a database trigger.

Note: To create several instances of the same workflow process at once and begin execution of the processes at a specified start activity, call WF_ENGINE_BULK.FastForward instead. See: WF_ENGINE_BULK.FastForward.

Arguments (input)

SuspendProcess

PL/SQL Syntax

procedure SuspendProcess
  (itemtype in varchar2,
   itemkey in varchar2,
   process in varchar2 default '');

Java Syntax

public static boolean suspendProcess
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String process)

Description

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().

Arguments (input)

<parent_process_internal_name>:<label_name>

Example

The following code excerpt shows an example of how to call suspendProcess() in a Java program. The example code is from the WFTest.java program.

// suspend, status should become SUSPEND
System.out.println("Suspend Process " + iType +"/"+ iKey +
    " ...");
if (WFEngineAPI.suspendProcess(ctx, iType, iKey, null))
  System.out.println("Seems to suspend successfully");
else
{
  System.out.println("suspend failed");
  WFEngineAPI.showError(ctx);
}

ResumeProcess

PL/SQL Syntax

procedure ResumeProcess
  (itemtype in varchar2,
   itemkey in varchar2,
   process in varchar2 default '');

Java Syntax

public static boolean resumeProcess
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String process)

Description

Returns a suspended process to normal execution status. Any activities that were transitioned to while the process was suspended are now executed.

Arguments (input)

<parent_process_internal_name>:<label_name>

Example

The following code excerpt shows an example of how to call resumeProcess() in a Java program. The example code is from the WFTest.java program.

// resume process and status should be ACTIVE
System.out.println("Resume Process " + iType +"/"+ iKey +
    " ...");
if (WFEngineAPI.resumeProcess(ctx, iType, iKey, null))
  System.out.println("Seems to resume successfully");
else
{
  System.out.println("resume failed");
  WFEngineAPI.showError(ctx);
}

AbortProcess

PL/SQL Syntax

procedure AbortProcess
  (itemtype in varchar2,
   itemkey in varchar2,
   process in varchar2 default '',
   result in varchar2 default eng_force);

Java Syntax

public static boolean abortProcess
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String process,
   String result)

Description

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.

This API also raises the oracle.apps.wf.engine.abort event. Although Oracle Workflow does not include any predefined subscriptions to this event, you can optionally define your own subscriptions to this event if you want to perform custom processing when it occurs. See: Workflow Engine Events, Oracle Workflow Developer's Guide and To Define an Event Subscription (for standalone Oracle Workflow), Oracle Workflow Developer's Guide or To Create or Update an Event Subscription (for Oracle Applications), Oracle Workflow Developer's Guide.

Arguments (input)

<parent_process_internal_name>:<label_name> 

Example

The following code excerpt shows an example of how to call abortProcess() in a Java program. The example code is from the WFTest.java program.

// abort process, should see status COMPLETE with result 
// code force
System.out.println("Abort Process ..." + iType + "/" + 
    iKey);
if (!WFEngineAPI.abortProcess(ctx, iType, iKey, pr, null))
{
  System.out.println("Seemed to have problem aborting...");
  WFEngineAPI.showError(ctx);
}

CreateForkProcess

PL/SQL Syntax

procedure CreateForkProcess
  (copy_itemtype in varchar2,
   copy_itemkey in varchar2,
   new_itemkey in varchar2,
   same_version in boolean default TRUE);

Description

Forks a runtime process by creating a new process that is a copy of the original. After calling CreateForkProcess(), you can call APIs such as SetItemOwner(), SetItemUserKey(), or the SetItemAttribute APIs to reset any item properties or modify any item attributes that you want for the new process. Then you must call StartForkProcess() to start the new process.

Use CreateForkProcess() when you need to change item specific attributes during the course of a process. For example, if an order cannot be met due to insufficient inventory stock, you can use CreateForkProcess() to fork a new transaction for the backorder quantity. Note that any approval notification will be copied. The result is as if two items were created for this transaction.

Caution: Do not call CreateForkProcess() and StartForkProcess() from within a parallel branch in a process. These APIs do not copy any branches parallel to their own branch that are not active.

Note: When you fork an item, Oracle Workflow automatically creates an item attribute called #FORKED_FROM for the new item and sets the attribute to the item key of the original item. This attribute provides an audit trail for the forked item.

Arguments (input)

StartForkProcess

PL/SQL Syntax

procedure StartForkProcess
  (itemtype in varchar2,
   itemkey in varchar2);

Description

Begins execution of the new forked process that you specify. Before you call StartForkProcess(), you must first call CreateForkProcess() to create the new process. You can modify the item attributes of the new process before calling StartForkProcess().

If the new process uses the same version as the original, StartForkProcess() copies the status and history of each activity in the forked process, activity by activity. If the new process uses the latest version, then StartForkProcess() executes StartProcess().

If you call StartForkProcess() from within a process, any function activity in the process that had a status of 'Active' is updated to have a status of 'Notified'. You must call CompleteActivity() afterwards to continue the process.

StartForkProcess() automatically refreshes any notification attributes that are based on item attributes. Any open notifications in the original process are copied and sent again in the new process. Closed notifications are copied but not resent; their status remains remains 'Complete'.

Any Wait activities in the new process are activated at the same time as the original activities. For example, if a 24 hour Wait activity in the original process is due to be eligible in two hours, the new Wait activity is also eligible in two hours.

Caution: Do not call CreateForkProcess() and StartForkProcess() from within a parallel branch in a process. These APIs do not copy any branches parallel to their own branch that are not active.

Arguments (input)

Background

PL/SQL Syntax

procedure Background
  (itemtype in varchar2 default '',
   minthreshold in number default null,
   maxthreshold in number default null,
   process_deferred in boolean default TRUE,
   process_timeout in boolean default TRUE,
   process_stuck in boolean default FALSE);

Description

Runs a background engine for processing deferred activities, timed out activities, and stuck processes using the parameters specified. The background engine executes all activities that satisfy the given arguments at the time that the background engine is invoked. This procedure does not remain running long term, so you must restart this procedure periodically. Any activities that are newly deferred or timed out or processes that become stuck after the current background engine starts are processed by the next background engine that is invoked. You can run a script called wfbkgchk.sql to get a list of the activities waiting to be processed by the next background engine run. See: Wfbkgchk.sql, Oracle Workflow Administrator's Guide.

You must not call Background() from within application code. If you want to call this procedure directly, you can run it from SQL*Plus. Otherwise, if you are using the standalone version of Oracle Workflow, you can use one of the sample background engine looping scripts described below, create your own script to make the background engine procedure loop indefinitely, or use the Oracle Workflow Manager component of Oracle Enterprise Manager to schedule a background engine. If you are using the version of Oracle Workflow embedded in Oracle Applications, you can use the concurrent program version of this procedure and take advantage of the concurrent manager to schedule the background engine to run periodically. You can also use the Workflow Manager component of Oracle Applications Manager to submit the background engine concurrent program. See: To Schedule Background Engines, Oracle Workflow Administrator's Guide.

Arguments (input)

Example Background Engine Looping Scripts

For the standalone version of Oracle Workflow you can use one of two example scripts to run the background engine regularly.

The first example is a SQL script stored in a file called wfbkg.sql in the ORACLE_HOME/wf/admin/sql directory. To run this script, go to the directory where the file is located and type the following command at your operating system prompt:

sqlplus <username/password> @wfbkg <min> <sec> 

Replace <username/password> with the Oracle Database account username and password where you want to run the background engine. Replace <min> with the number of minutes you want the background engine to run and replace <sec> with the number of seconds you want the background engine to sleep between calls.

The second example is a shell script stored in a file called wfbkg.csh in the ORACLE_HOME/bin directory. To run this script, go to the directory where the file is located and type the following command at your operating system prompt:

wfbkg.csh <username/password> 

Replace <username/password> with the Oracle Database account username and password where you want to run the background engine.

AddItemAttribute

PL/SQL Syntax

procedure AddItemAttr
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   text_value in varchar2 default null,
   number_value in number default null, 
   date_value in date default null);

Java Syntax

public static boolean addItemAttr
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName)

public static boolean addItemAttrText
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   String aValue)

public static boolean addItemAttrNumber
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   BigDecimal numberVal)

public static boolean addItemAttrDate
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   String aValue)

Description

Adds a new item type attribute variable to the process. Although most item type attributes are defined at design time, you can create new attributes at runtime for a specific process. You can optionally set a default text, number, or date value for a new item type attribute when the attribute is created.

If you are using Java, choose the correct method for your attribute type. To add an empty item type attribute, use addItemAttr(). When adding an item type attribute with a default value, use addItemAttrText() for all attribute types except number and date.

Note: If you need to add large numbers of item type attributes at once, use the AddItemAttributeArray APIs rather than the AddItemAttribute APIs for improved performance. See: AddItemAttributeArray

Arguments (input)

Example

The following example shows how API calls can be simplified by using AddItemAttr() to set the default value of a new item type attribute at the time of creation.

Using AddItemAttr() to create the new attribute and SetItemAttrText() to set the value of the attribute, the following calls are required:

AddItemAttr('ITYPE', 'IKEY', 'NEWCHAR_VAR');
SetItemAttrText('ITYPE', 'IKEY', 'NEWCHAR_VAR', 
                'new text values');

Using AddItemAttr() both to create the new attribute and to set its value, only the following call is required:

AddItemAttr('ITYPE', 'IKEY', 'NEWCHAR_VAR', 
            'new text values');

AddItemAttributeArray

PL/SQL Syntax

procedure AddItemAttrTextArray
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in Wf_Engine.NameTabTyp,
   avalue in Wf_Engine.TextTabTyp);

procedure AddItemAttrNumberArray
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in Wf_Engine.NameTabTyp,
   avalue in Wf_Engine.NumTabTyp);

procedure AddItemAttrDateArray
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in Wf_Engine.NameTabTyp,
   avalue in Wf_Engine.DateTabTyp);

Description

Adds an array of new item type attributes to the process. Although most item type attributes are defined at design time, you can create new attributes at runtime for a specific process. Use the AddItemAttributeArray APIs rather than the AddItemAttribute APIs for improved performance when you need to add large numbers of item type attributes at once.

Use the correct procedure for your attribute type. All attribute types except number and date use AddItemAttrTextArray.

Arguments (input)

SetItemAttribute

PL/SQL Syntax

procedure SetItemAttrText
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   avalue in varchar2);

procedure SetItemAttrNumber
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   avalue in number);

procedure SetItemAttrDate
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   avalue in date);

procedure SetItemAttrEvent
  (itemtype in varchar2,
   itemkey in varchar2,
   name in varchar2,
   event in wf_event_t);

Java Syntax

public static boolean setItemAttrText
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   String aValue)

public static boolean setItemAttrNumber
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   BigDecimal aValue)

public static boolean setItemAttrDate
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   String aValue)

public static boolean setItemAttrDate
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String attributeName,
   java.util.Date attributeValue)

Description

Sets the value of an item type attribute in a process. Use the correct procedure for your attribute type. All attribute types except number, date, and event use SetItemAttrText.

In Java, there are two implementations of setItemAttrDate(). One lets you provide the date value as a Java String object, while the other lets you provide the date value as a Java Date object.

Note: If you need to set the values of large numbers of item type attributes in the same work item at once, use the WF_ENGINE.SetItemAttributeArray APIs rather than the WF_ENGINE.SetItemAttribute APIs for improved performance. See: SetItemAttributeArray.

If you need to set the values of item type attributes in several work items at once, use the WF_ENGINE_BULK.SetItemAttrText, WF_ENGINE_BULK.SetItemAttrNumber, and WF_ENGINE_BULK.SetItemAttrDate APIs rather than the WF_ENGINE.SetItemAttribute APIs. See: WF_ENGINE_BULK.SetItemAttrText, WF_ENGINE_BULK.SetItemAttrNumber, and WF_ENGINE_BULK.SetItemAttrDate.

Arguments (input)

Examples

Example 1

The following code excerpt shows an example of how to call setItemAttrText() in a Java program. The example code is from the WFTest.java program.

if (WFEngineAPI.setItemAttrText(ctx, iType, iKey, 
    "REQUESTOR_USERNAME", owner))
  System.out.println("Requestor: "+owner);
  else
{
  WFEngineAPI.showError(ctx);
}

Example 2

If an event message is stored within an item attribute of type event, you can access the event data CLOB within that event message by creating an item attribute of type URL for the event data. The following sample PL/SQL code shows how to set the value of the URL attribute in the standalone version of Oracle Workflow to reference the event data.

l_eventdataurl := Wfa_html.base_url||'Wf_Event_Html.
EventDataContents?P_EventAttribute=EVENT_MESSAGE'||'&'||
'P_ItemType='||itemtype||'&'||'P_ItemKey='||itemkey||'&'||
'p_mime_type=text/xml';

WF_ENGINE.SetItemAttrText('<item_type>', '<item_key>', 
          'EVENTDATAURL', l_eventdataurl);

If you have applied a stylesheet to the event data XML document to create HTML, set the p_mime_type parameter in the URL to text/html instead.

If you omit the p_mime_type parameter from the URL, the MIME type defaults to text/xml.

Related Topics

Event Message Structure

setItemAttrFormattedDate

Java Syntax

public static boolean setItemAttrFormattedDate
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String attributeName,
   String attributeValue
   String dateFormat)

Description

Sets the value of an item type attribute of type date in a process with a date value provided as a formatted string.

Arguments (input)

SetItemAttrDocument

Important: Document management functionality is reserved for future use. This description of the SetItemAttrDocument API is provided for reference only.

PL/SQL Syntax

procedure SetItemAttrDocument
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   documentid in varchar2);

Java Syntax

public static boolean setItemAttrDocument
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String aName,
   String documentId)

Description

Sets the value of an item attribute of type document, to a document identifier.

Arguments (input)

DM:<node_id>:<doc_id>:<version>

SetItemAttributeArray

PL/SQL Syntax

procedure SetItemAttrTextArray
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in Wf_Engine.NameTabTyp,
   avalue in Wf_Engine.TextTabTyp);

procedure SetItemAttrNumberArray
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in Wf_Engine.NameTabTyp,
   avalue in Wf_Engine.NumTabTyp);

procedure SetItemAttrDateArray
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in Wf_Engine.NameTabTyp,
   avalue in Wf_Engine.DateTabTyp);

Description

Sets the values of an array of item type attributes in a process. Use the SetItemAttributeArray APIs rather than the SetItemAttribute APIs for improved performance when you need to set the values of large numbers of item type attributes at once.

Use the correct procedure for your attribute type. All attribute types except number, date, and event use SetItemAttrTextArray.

Note: If you need to set the values of item type attributes in several work items at once, use the WF_ENGINE_BULK.SetItemAttrText, WF_ENGINE_BULK.SetItemAttrNumber, and WF_ENGINE_BULK.SetItemAttrDate APIs rather than the WF_ENGINE.SetItemAttributeArray APIs. See: WF_ENGINE_BULK.SetItemAttrText, WF_ENGINE_BULK.SetItemAttrNumber, and WF_ENGINE_BULK.SetItemAttrDate.

Arguments (input)

Example

The following example shows how using the SetItemAttributeArray APIs rather than the SetItemAttribute APIs can help reduce the number of calls to the database.

Using SetItemAttrText():

SetItemAttrText('ITYPE', 'IKEY', 'VAR1', 'value1');
SetItemAttrText('ITYPE', 'IKEY', 'VAR2', 'value2');
SetItemAttrText('ITYPE', 'IKEY', 'VAR3', 'value3');

// Multiple calls to update the database.
 

Using SetItemAttrTextArray():

declare
  varname   Wf_Engine.NameTabTyp;
  varval    Wf_Engine.TextTabTyp;
begin
  varname(1) := 'VAR1';
  varval(1)  := 'value1';
  varname(2) := 'VAR2';
  varval(2)  := 'value2';
  varname(3) := 'VAR3';
  varval(3)  := 'value3';
Wf_Engine.SetItemAttrTextArray('ITYPE', 'IKEY', varname, varval);
exception
  when OTHERS then
    // handle your errors here
    raise;
end;

// Only one call to update the database.

getItemTypes

Java Syntax

public static WFTwoDArray getItemTypes
  (WFContext wCtx)

Description

Returns a list of all the item types defined in the Oracle Workflow database as a two-dimensional data object.

Arguments (input)

GetItemAttribute

PL/SQL Syntax

function GetItemAttrText
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   ignore_notfound in boolean default FALSE) 
  return varchar2;

function GetItemAttrNumber
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   ignore_notfound in boolean default FALSE) 
  return number;

function GetItemAttrDate
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   ignore_notfound in boolean default FALSE) 
  return date;

function GetItemAttrEvent
  (itemtype in varchar2,
   itemkey in varchar2,
   name in varchar2) 
  return wf_event_t;

Description

Returns the value of an item type attribute in a process. Use the correct function for your attribute type. All attribute types except number, date, and event use GetItemAttrText.

For GetItemAttrText(), GetItemAttrNumber(), and GetItemAttrDate(), you can specify TRUE for the ignore_notfound parameter to ignore the exception encountered if the specified item type attribute does not exist. In this case the function returns a null value but does not raise an exception. For example, you can use this parameter if a new item type attribute is added to an item type, and your code needs to handle both the earlier version and the upgraded version of the item type.

Arguments (input)

Related Topics

Event Message Structure

GetItemAttrDocument

Important: Document management functionality is reserved for future use. This description of the GetItemAttrDocument API is provided for reference only.

PL/SQL Syntax

function GetItemAttrDocument
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2,
   ignore_notfound in boolean default FALSE) 
  return varchar2;

Description

Returns the document identifier for a DM document-type item attribute. The document identifier is a concatenated string of the following values:

DM:<nodeid>:<documentid>:<version>

<nodeid> is the node ID assigned to the document management system node as defined in the Document Management Nodes Web page.

<documentid> is the document ID of the document, as assigned by the document management system where the document resides.

<version> is the version of the document. If a version is not specified, the latest version is assumed.

You can specify TRUE for the ignore_notfound parameter to ignore the exception encountered if the specified item type attribute does not exist. In this case the function returns a null value but does not raise an exception. For example, you can use this parameter if a new item type attribute is added to an item type, and your code needs to handle both the earlier version and the upgraded version of the item type.

Arguments (input)

GetItemAttrClob

PL/SQL Syntax

function GetItemAttrClob
  (itemtype in varchar2,
   itemkey in varchar2,
   aname in varchar2) 
  return clob;

Description

Returns the value of an item type attribute in a process as a character large object (CLOB).

Arguments (input)

getItemAttributes

Java Syntax

public static WFTwoDArray getItemAttributes
  (WFContext wCtx,
   String itemType,
   String itemKey)

Description

Returns a list of all the item attributes, their types, and their values for the specified item type instance as a two-dimensional data object.

Arguments (input)

GetItemAttrInfo

PL/SQL Syntax

procedure GetItemAttrInfo
  (itemtype in varchar2,
   aname in varchar2,
   atype out varchar2,
   subtype out varchar2,
   format out varchar2);

Description

Returns information about an item type attribute, such as its type and format, if any is specified. Currently, subtype information is not available for item type attributes.

Arguments (input)

GetActivityAttrInfo

PL/SQL Syntax

procedure GetActivityAttrInfo
  (itemtype in varchar2,
   itemkey in varchar2,
   actid in number,
   aname in varchar2,
   atype out varchar2,
   subtype out varchar2,
   format out varchar2);

Description

Returns information about an activity attribute, such as its type and format, if any is specified. This procedure currently does not return any subtype information for activity attributes.

Arguments (input)

GetActivityAttribute

PL/SQL Syntax

function GetActivityAttrText
  (itemtype in varchar2,
   itemkey in varchar2,
   actid in number,
   aname in varchar2,
   ignore_notfound in boolean default FALSE) 
  return varchar2;

function GetActivityAttrNumber
  (itemtype in varchar2,
   itemkey in varchar2,
   actid in number,
   aname in varchar2,
   ignore_notfound in boolean default FALSE) 
  return number;

function GetActivityAttrDate
  (itemtype in varchar2,
   itemkey in varchar2,
   actid in number,
   aname in varchar2, 
   ignore_notfound in boolean default FALSE) 
  return date;

function GetActivityAttrEvent
  (itemtype in varchar2,
   itemkey in varchar2,
   actid in number,
   name in varchar2) 
  return wf_event_t;

Description

Returns the value of an activity attribute in a process. Use the correct function for your attribute type. If the attribute is a Number or Date type, then the appropriate function translates the number/date value to a text-string representation using the attribute format.

Note: Use GetActivityAttrText() for form, URL, lookup, role, attribute, and document attribute types.

For GetActivityAttrText(), GetActivityAttrNumber(), and GetActivityAttrDate(), you can specify TRUE for the ignore_notfound parameter to ignore the exception encountered if the specified activity attribute does not exist. In this case the function returns a null value but does not raise an exception. For example, you can use this parameter if a new activity attribute is added to an activity, and your code needs to handle both the earlier version and the upgraded version of the activity.

Arguments (input)

Related Topics

Event Message Structure

GetActivityAttrClob

PL/SQL Syntax

function GetActivityAttrClob
  (itemtype in varchar2,
   itemkey in varchar2,
   actid in number,
   aname in varchar2) 
  return clob;

Description

Returns the value of an activity attribute in a process as a character large object (CLOB).

Arguments (input)

getActivityAttributes

Java Syntax

public static WFTwoDArray getActivityAttributes
  (WFContext wCtx,
   String itemType,
   String itemKey,
   BigDecimal actID)

Description

Returns a list of all the activity attributes, their types, and their values for the specified activity as a two-dimensional data object.

Arguments (input)

BeginActivity

PL/SQL Syntax

procedure BeginActivity
  (itemtype in varchar2,
   itemkey in varchar2,
   activity in varchar2);

Description

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. See: CompleteActivity.

Arguments (input)

<parent_process_internal_name>:<label_name>

Example

/* Verify that a credit check can be performed on an order.  If it 
 * is allowed, perform the credit check, then notify the Workflow 
 * Engine when the credit check completes. */

begin
  wf_engine.BeginActivity('ORDER', to_char(order_id),
    'CREDIT_CHECK');
  OK := TRUE;
exception
  when others then
    WF_CORE.Clear;
    OK := FALSE;
end;

if OK then
  -- perform activity --
  wf_engine.CompleteActivity('ORDER', to_char(order_id),
    'CREDIT_CHECK' :result_code);
end if;

CompleteActivity

PL/SQL Syntax

procedure CompleteActivity
  (itemtype in varchar2,
   itemkey in varchar2,
   activity in varchar2,
  result in varchar2);

Java Syntax

public static boolean completeActivity
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String activity,
   String result)

Description

Notifies the Workflow Engine that the specified activity has been completed for a particular item. This procedure can be called for the following situations:

• To indicate a completed activity with an optional result - This signals the Workflow Engine that an asynchronous activity has been completed. This procedure requires that the activity currently has a status of 'Notified'. An optional activity completion result can also be passed. The result can determine what transition the process takes next.

• To create and start an item - You can call CompleteActivity() for a 'Start' activity to implicitly create and start a new item. 'Start' activities are designated as the beginning of a process in the Workflow Builder. The item type and key specified in this call must be passed to all subsequent calls that operate on this item.

  Use CompleteActivity() if you cannot use CreateProcess() and StartProcess() to start your process. For example, call CompleteActivity() if you need to start a process with an activity node that is mid-stream in a process thread and not at the beginning of a process thread. The activity node you specify as the beginning of the process must be set to 'Start' in the Node tab of its property page or else an error will be raised.

  Note: Starting a process using CompleteActivity() differs from starting a process using CreateProcess() and StartProcess() in these ways:

  • The 'Start' activity called with CompleteActivity() may or may not have incoming transitions. StartProcess() executes only 'Start' activities that do not have any incoming transitions.

  • CompleteActivity() only completes the single 'Start' activity with which it is called. Other 'Start' activities in the process are not completed. StartProcess(), however, executes every activity in the process that is marked as a 'Start' activity and does not have any incoming transitions.

  • CompleteActivity() does not execute the activity with which it is called; it simply marks the activity as complete. StartProcess() does execute the 'Start' activities with which it starts a process.

  • When you use CompleteActivity() to start a new process, the item type of the activity being completed must either have a selector function defined to choose a root process, or have exactly one runnable process with the activity being completed marked as a 'Start' activity. You cannot explicitly specify a root process as you can with StartProcess().

Arguments (input)

<parent_process_internal_name>:<label_name>

Examples

Example 1

/* Complete the 'ENTER ORDER' activity for the 'ORDER' item type.  
 * The 'ENTER ORDER' activity allows creation of new items since 
 * it is the start of a workflow, so the item is created by this 
 * call as well. */

wf_engine.CompleteActivity('ORDER', to_char(order.order_id),
  'ENTER_ORDER', NULL);

Example 2

/* Complete the 'LEGAL REVIEW' activity with status 'APPROVED'.  
 * The item must already exist. */

wf_engine.CompleteActivity('ORDER', '1003', 'LEGAL_REVIEW',
  'APPROVED');

Example 3

/* Complete the BLOCK activity which is used in multiple 
 * subprocesses in parallel splits. */

wf_engine.CompleteActivity('ORDER', '1003', 
  'ORDER_PROCESS:BLOCK-3', 'null');

CompleteActivityInternalName

PL/SQL Syntax

procedure CompleteActivityInternalName
  (itemtype in varchar2,
   itemkey in varchar2,
   activity in varchar2,
   result in varchar2);

Description

Notifies the Workflow Engine that the specified activity has been completed for a particular item. This procedure requires that the activity currently has a status of 'Notified'. An optional activity completion result can also be passed. The result can determine what transition the process takes next.

CompleteActivityInternalName() is similar to CompleteActivity() except that CompleteActivityInternalName() identifies the activity to be completed by the activity's internal name, while CompleteActivity() identifies the activity by the activity node label name. You should only use CompleteActivityInternalName() when you do not know the activity node label name. If you do know the activity node label name, use CompleteActivity() instead. See: CompleteActivity.

Note: Unlike CompleteActivity(), you cannot use CompleteActivityInternalName() to start a process. Also, you cannot use CompleteActivityInternalName() with a synchronous process.

When CompleteActivityInternalName() is executed, there must be exactly one instance of the specified activity with a status of 'Notified'. If there are multiple instances of the activity with 'Notified' statuses, the process enters an 'ERROR' state.

Arguments (input)

<parent_process_internal_name>:<activity_internal_name>

AssignActivity

PL/SQL Syntax

procedure AssignActivity
  (itemtype in varchar2,
   itemkey in varchar2,
   activity in varchar2,
   performer in varchar2);

Description

Assigns or reassigns an activity to another performer. This procedure may be called before the activity is transitioned to. For example, a function activity earlier in the process may determine the performer of a later activity.

If a new user is assigned to a notification activity that already has an outstanding notification, the outstanding notification is canceled and a new notification is generated for the new user by calling WF_Notification.Transfer.

Arguments (input)

<parent_process_internal_name>:<label_name>

Event

PL/SQL Syntax

procedure Event
  (itemtype in varchar2,
   itemkey in varchar2,
   process_name in varchar2 default null,
   event_message in wf_event_t);

Description

Receives an event from the Business Event System into a workflow process.

If the specified item key already exists, the event is received into that item. If the item key does not already exist, but the specified process includes an eligible Receive event activity marked as a Start activity, the Workflow Engine creates a new item running that process.

Within the workflow process that receives the event, the procedure searches for eligible Receive event activities. For an activity to be eligible to receive an event, its event filter must either be set to that particular event, set to an event group of which that event is a member, or left blank to accept any event. Additionally, the activity must either be marked as a Start activity, or it must have an activity status of NOTIFIED, meaning the process has transitioned to that activity and is waiting to receive the event.

For each eligible Receive event activity, Event() stores the event name, event key, and event message in the item type attributes specified in the event activity node, if they have been defined. Additionally, the procedure sets any parameters in the event message parameter list as item type attributes for the process, creating new item type attributes if a corresponding attribute does not already exist for any parameter. It also sets the subscription's globally unique identifier (GUID) as a dynamic item attribute so that the workflow process can reference other information in the subscription definition. Then the Workflow Engine begins a thread of execution from the event activity.

If no eligible Receive event activity exists for a received event, the procedure returns an exception and an error message.

Note: If an event arrives at a Start activity to launch a new process instance, the Workflow Engine also searches for all other receive event activities that are marked as Start activities and that do not have any incoming transitions, regardless of their event filter. For these activities, the Workflow Engine sets the activity status to NOTIFIED so that they will be ready to receive an event if any more events are sent to this process. This feature lets you design a workflow process that requires multiple events to be received when you do not know in advance the order in which the events will arrive.

Note: If the event received by a Receive event activity was originally raised by a Raise event activity in another workflow process, the item type and item key for that process are included in the parameter list within the event message. In this case, the Workflow Engine automatically sets the specified process as the parent for the process that receives the event, overriding any existing parent setting.

Arguments (input)

<parent_process_internal_name>:<label_name>

HandleError

PL/SQL Syntax

procedure HandleError
  (itemtype in varchar2,
   itemkey in varchar2,
   activity in varchar2,
   command in varchar2,
   result in varchar2);

Java Syntax

public static boolean handleError
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String activity,
   String command,
   String result)

Description

This procedure is generally called from an activity in an ERROR process to handle any process activity that has encountered an error.

You can also call this procedure for any arbitrary activity in a process, to roll back part of your process to that activity. The activity that you call this procedure with can have any status and does not need to have been executed. The activity can also be in a subprocess. If the activity node label is not unique within the process you can precede the activity node label name with the internal name of its parent process. For example:

<parent_process_internal_name>:<label_name>

This procedure clears the activity specified and all activities following it that have already been transitioned to by reexecuting each activity in CANCEL mode. For an activity in the 'Error' state, there are no other executed activities following it, so the procedure simply clears the errored activity.

Once the activities are cleared, this procedure resets any parent processes of the specified activity to a status of 'Active', if they are not already active.

The procedure then handles the specified activity based on the command you provide: SKIP or RETRY.

This API also raises the oracle.apps.wf.engine.skip event or the oracle.apps.wf.engine.retry event, depending on the command you provide. Although Oracle Workflow does not include any predefined subscriptions to these events, you can optionally define your own subscriptions to these events if you want to perform custom processing when they occur. See: Workflow Engine Events, Oracle Workflow Developer's Guide and To Define an Event Subscription (for standalone Oracle Workflow), Oracle Workflow Developer's Guide or To Create or Update an Event Subscription (for Oracle Applications), Oracle Workflow Developer's Guide.

Note: An item's active date and the version number of the process that the item is transitioning through can never change once an item is created. Occasionally, however, you may want to use HandleError to manually make changes to your process for an existing item.

If the changes you make to a process are minor, you can use HandleError to manually push an item through activities that will error or redirect the item to take different transitions in the process.

If the changes you want to make to a process are extensive, then you need to perform at least the following steps:

• Abort the process by calling WF_ENGINE.AbortProcess().

• Purge the existing item by calling WF_PURGE.Items().

• Revise the process.

• Recreate the item by calling WF_ENGINE.CreateProcess().

• Restart the revised process at the appropriate activity by calling WF_ENGINE.HandleError().

Arguments (input)

<parent_process_internal_name>:<label_name>

SetItemParent

PL/SQL Syntax

procedure SetItemParent
  (itemtype in varchar2,
   itemkey in varchar2,
   parent_itemtype in varchar2,
   parent_itemkey in varchar2,
   parent_context in varchar2);

Java Syntax

public static boolean setItemParent
  (WFContext wCtx,
   String itemType,
   String itemKey,
   String parentItemType,
   String parentItemKey,
   String parentContext)

Description

Defines the parent/child relationship for a master process and a detail process. This API must be called by any detail process spawned from a master process to define the parent/child relationship between the two processes. You make a call to this API after you call the CreateProcess API, but before you call the StartProcess API for the detail process.

Arguments (input)

ItemStatus

PL/SQL Syntax

procedure ItemStatus
  (itemtype in varchar2,
   itemkey in varchar2,
   status out varchar2,
   result out varchar2);

Java Syntax

public static WFTwoDArray itemStatus
  (WFContext wCtx,
   String itemType,
   String itemKey)

Description

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.

Arguments (input)

Example

The following code excerpt shows an example of how to call itemStatus() in a Java program. The example code is from the WFTest.java program.

// get status and result for this item
dataSource = WFEngineAPI.itemStatus(ctx, iType, iKey);
System.out.print("Status and result for " + iType + "/" + 
    iKey + " = ");
displayDataSource(ctx, dataSource);

getProcessStatus

Java Syntax

public static WFTwoDArray getProcessStatus
  (WFContext wCtx,
   String itemType,
   String itemKey,
   BigDecimal process)

Description

Returns the process status for the given item type instance as a two-dimensional data object.

Arguments (input)

Workflow Engine Bulk APIs

The Workflow Engine bulk APIs can be called by an application program in an Oracle Applications installation to launch multiple work items at once in bulk and to set values for item attributes in bulk across multiple work items. These APIs are defined in a PL/SQL package called WF_ENGINE_BULK.

Note: This package is only available if your database version is Oracle9i Database or higher.

• WF_ENGINE_BULK.CreateProcess

• WF_ENGINE_BULK.StartProcess

• WF_ENGINE_BULK.FastForward

• WF_ENGINE_BULK.SetItemAttrText

• WF_ENGINE_BULK.SetItemAttrNumber

• WF_ENGINE_BULK.SetItemAttrDate

Some Workflow Engine bulk APIs use PL/SQL table composite datatypes defined in the WF_ENGINE_BULK package. The following table shows the column datatype definition for each PL/SQL table type.

Some Workflow Engine bulk APIs also use PL/SQL table composite datatypes defined in the WF_ENGINE package. See: PL/SQL Table Types in WF_ENGINE.

WF_ENGINE_BULK.CreateProcess

PL/SQL Syntax

procedure CreateProcess
  (itemtype in varchar2,
   itemkeys in wf_engine_bulk.itemkeytabtype,
   process in varchar2,
   user_keys in wf_engine_bulk.userkeytabtype,
   owner_roles in wf_engine_bulk.ownerroletabtype,
   parent_itemtype in varchar2 default null,
   parent_itemkey in varchar2 default null,
   parent_context in varchar2 default null,
   masterdetail in boolean default null);

Description

Creates multiple new runtime process instances of the specified item type at once, based on the specified array of workflow item keys. You can optionally specify one existing work item as the parent for all the new work items.

Note: You cannot use WF_ENGINE_BULK.CreateProcess() to create forced synchronous processes.

If processing fails for any work items, then WF_ENGINE_BULK.CreateProcess() adds those item keys to a global PL/SQL table called g_FailedItems within the WF_ENGINE_BULK package. The procedure then continues processing the remaining items. When processing is complete, the procedure raises an exception for any failed items.

Arguments (input)

Related Topics

WF_ENGINE.CreateProcess

Synchronous, Asynchronous, and Forced Synchronous Processes

WF_ENGINE_BULK.StartProcess

PL/SQL Syntax

procedure StartProcess
  (itemtype in varchar2,
   itemkeys in wf_engine_bulk.itemkeytabtype);

Description

Begins execution of multiple new runtime process instances at once, identified by the specified item type and array of workflow item keys. The Workflow Engine locates the activity marked as a Start activity in the process definition and then defers that activity for each of the new work items. Ensure that you run a background engine to process the deferred activities and continue executing the work items.

You must call either WF_ENGINE.CreateProcess() or WF_ENGINE_BULK.CreateProcess() to define the item type and item keys before calling WF_ENGINE_BULK.StartProcess().

Note: You cannot use WF_ENGINE_BULK.StartProcess() to start forced synchronous processes.

If processing fails for any work items, then WF_ENGINE_BULK.StartProcess() adds those item keys to a global PL/SQL table called g_FailedItems within the WF_ENGINE_BULK package. The procedure then continues processing the remaining items. When processing is complete, the procedure raises an exception for any failed items.

Arguments (input)

Related Topics

WF_ENGINE.StartProcess

Setting Up Background Workflow Engines, Oracle Workflow Administrator's Guide

Synchronous, Asynchronous, and Forced Synchronous Processes

WF_ENGINE_BULK.FastForward

PL/SQL Syntax

procedure FastForward
  (itemtype in varchar2,
   itemkeys in wf_engine_bulk.itemkeytabtype,
   process in varchar2,
   activity in varchar2,
   activityStatus in varchar2 default null,
   parent_itemtype in varchar2 default null,
   parent_itemkey in varchar2 default null,
   parent_context in varchar2  default null,
   masterdetail in boolean default null);

Description

Creates multiple new runtime process instances of the specified item type at once, based on the specified array of workflow item keys, and begins execution of the new work items at the specified activity. You can optionally specify one existing work item as the parent for all the new work items.

The activity at which execution begins must be marked as a Start activity. However, it can have incoming transitions. The activity must be a direct child of the process in which execution of the work item begins. It cannot be part of a subprocess.

The Workflow Engine first calls WF_ENGINE_BULK.CreateProcess() to create the new work items and then sets the Start activity for each work item to the specified status, either 'DEFERRED' or 'NOTIFIED'.

• 'DEFERRED' - The Workflow Engine defers the Start activity for each work item. Ensure that you run a background engine to process the deferred activities and continue executing the work items.

• 'NOTIFIED' - The Workflow Engine waits for the Start activity for each work item to be completed. Ensure that you complete these activities to continue executing the work items. For example, you can call WF_ENGINE.CompleteActivity() or WF_ENGINE.CompleteActivityInternalName(), or, for a receive event activity, send an event to the activity.

Note: You cannot use WF_ENGINE_BULK.FastForward() to start forced synchronous processes.

If processing fails for any work items, then WF_ENGINE_BULK.FastForward() adds those item keys to a global PL/SQL table called g_FailedItems within the WF_ENGINE_BULK package. The procedure then continues processing the remaining items. When processing is complete, the procedure raises an exception for any failed items.

Arguments (input)

<parent_process_internal_name>:<label_name>

Related Topics

WF_ENGINE.LaunchProcess

WF_ENGINE.CompleteActivity

WF_ENGINE.CompleteActivityInternalName

WF_ENGINE.Event

Setting Up Background Workflow Engines, Oracle Workflow Administrator's Guide

Synchronous, Asynchronous, and Forced Synchronous Processes

WF_ENGINE_BULK.SetItemAttrText

PL/SQL Syntax

procedure SetItemAttrText
  (itemtype in varchar2,
   itemkeys in Wf_Engine_Bulk.ItemKeyTabType,
   anames in Wf_Engine.NameTabTyp,
   avalues in Wf_Engine.TextTabTyp);

Description

Sets the values of an array of item type attributes of type text in multiple work items, identified by the specified item type and array of item keys. You can also use this API to set attributes of type role, form, URL, lookup, or document.

This API sets the value of one item type attribute in each work item. Consequently, the array of item keys must correspond on a one-to-one basis with the array of item type attribute names and with the array of item type attribute values.

Note: If you need to set the values of large numbers of item type attributes in the same work item, use WF_ENGINE.SetItemAttrTextArray() rather than WF_ENGINE_BULK.SetItemAttrText().

If processing fails for any work items, then WF_ENGINE_BULK.SetItemAttrText() adds those item keys to a global PL/SQL table called g_FailedItems within the WF_ENGINE_BULK package and also adds the corresponding item type attribute names to a global PL/SQL table called g_FailedAttributes. The procedure then continues processing the remaining items. When processing is complete, the procedure raises an exception for any failed items.

Arguments (input)

Related Topics

WF_ENGINE.SetItemAttributeArray

WF_ENGINE.SetItemAttribute

WF_ENGINE_BULK.SetItemAttrNumber

PL/SQL Syntax

procedure SetItemAttrNumber
  (itemtype in varchar2,
   itemkeys in Wf_Engine_Bulk.ItemKeyTabType,
   anames in Wf_Engine.NameTabTyp,
   avalues in Wf_Engine.NumTabTyp);

Description

Sets the values of an array of item type attributes of type number in multiple work items, identified by the specified item type and array of item keys.

This API sets the value of one item type attribute in each work item. Consequently, the array of item keys must correspond on a one-to-one basis with the array of item type attribute names and with the array of item type attribute values.

Note: If you need to set the values of large numbers of item type attributes in the same work item, use WF_ENGINE.SetItemAttrNumberArray() rather than WF_ENGINE_BULK.SetItemAttrNumber().

If processing fails for any work items, then WF_ENGINE_BULK.SetItemAttrNumber() adds those item keys to a global PL/SQL table called g_FailedItems within the WF_ENGINE_BULK package and also adds the corresponding item type attribute names to a global PL/SQL table called g_FailedAttributes. The procedure then continues processing the remaining items. When processing is complete, the procedure raises an exception for any failed items.

Arguments (input)

Related Topics

WF_ENGINE.SetItemAttributeArray

WF_ENGINE.SetItemAttribute

WF_ENGINE_BULK.SetItemAttrDate

PL/SQL Syntax

procedure SetItemAttrDate
  (itemtype in varchar2,
   itemkeys in Wf_Engine_Bulk.ItemKeyTabType,
   anames in Wf_Engine.NameTabTyp,
   avalues in Wf_Engine.DateTabTyp);

Description

Sets the values of an array of item type attributes of type date in multiple work items, identified by the specified item type and array of item keys.

This API sets the value of one item type attribute in each work item. Consequently, the array of item keys must correspond on a one-to-one basis with the array of item type attribute names and with the array of item type attribute values.

Note: If you need to set the values of large numbers of item type attributes in the same work item, use WF_ENGINE.SetItemAttrDateArray() rather than WF_ENGINE_BULK.SetItemAttrDate().

If processing fails for any work items, then WF_ENGINE_BULK.SetItemAttrDate() adds those item keys to a global PL/SQL table called g_FailedItems within the WF_ENGINE_BULK package and also adds the corresponding item type attribute names to a global PL/SQL table called g_FailedAttributes. The procedure then continues processing the remaining items. When processing is complete, the procedure raises an exception for any failed items.

Arguments (input)

Related Topics

WF_ENGINE.SetItemAttributeArray

WF_ENGINE.SetItemAttribute

Workflow Function APIs

The WFFunctionAPI Java class is the abstract class from which the Java procedures for all external Java function activities are derived. This class contains methods for accessing item type and activity attributes, as well as the execute() method which forms the main entry point function of the external Java function activity being implemented.

The WFFunctionAPI class is stored in the oracle.apps.fnd.wf Java package. The following list shows the APIs available in this class.

Important: Java is case-sensitive and all Java method names begin with a lower case letter to follow Java naming conventions.

• loadItemAttributes

• loadActivityAttributes

• getActivityAttr

• getItemAttr

• setItemAttrValue

• execute

Related Topics

Standard API for Java Procedures Called by Function Activities, Oracle Workflow Developer's Guide

Function Activity, Oracle Workflow Developer's Guide

loadItemAttributes

Java Syntax

public void loadItemAttributes
  (WFContext pWCtx) throws SQLException

Description

Retrieves the item attributes from the database for the item type from which the external Java function was called. The item attributes are not loaded by default due to the performance impact that could occur if the item type contains a large number of item attributes. You can use this method to load the item attributes explicitly before accessing them in your function.

If a database access error occurs, this method throws a SQLException.

Arguments (input)

loadActivityAttributes

Java Syntax

public void loadActivityAttributes
  (WFContext pWCtx,
   String iType,
   String iKey,
   BigDecimal actid) throws SQLException

Description

Retrieves the activity attributes from the database for the specified activity. This method is called by default when the function activity is instantiated and before the execute() function is called.

If a database access error occurs, this method throws a SQLException.

Arguments (input)

getActivityAttr

Java Syntax

public WFAttribute getActivityAttr
  (String aName)

public WFAttribute getActivityAttr
  (WFContext pWCtx,
   String aName) throws SQLException

Description

There are two implementations of getActivityAttr(). These methods return the activity attribute information for the specified activity attribute.

• If you call getActivityAttr(String aName) with only the activity attribute name, this method returns the activity attribute value but does not attempt to resolve any reference to an item attribute. If an activity attribute does point to an item attribute, this method returns the internal name of the item attribute. With the item attribute name, you can then perform additional processing based on the item attribute.

  For example, if you want to write information back to the item attribute, you can first use getActivityAttr(String aName) to retrieve the item attribute name. Then use setItemAttrValue(WFContext pWCtx, WFAttribute pAttr) to set the item attribute value, which also becomes the activity attribute value. See: setItemAttrValue.

• If you call getActivityAttr(WFContext pWCtx, String aName) with both the Workflow context and the activity attribute name, this method returns the activity attribute, and if the activity attribute points to an item attribute, the method attempts to resolve the reference by retrieving the value of that item attribute. You can use getActivityAttr(WFContext pWCtx, String aName) when you want to obtain the actual activity attribute value, and you do not need to know which item attribute it references. This method attempts to resolve the reference within the previously loaded item attributes, or if the item attributes have not been loaded, the method calls loadItemAttributes(WFContext pWCtx) to load them. See: loadItemAttributes.

  If a database access error occurs, this method throws a SQLException.

Arguments (input)

getItemAttr

Java Syntax

public WFAttribute getItemAttr
  (String aName)

Description

Returns the item attribute information for the specified item attribute.

Arguments (input)

setItemAttrValue

Java Syntax

public void setItemAttrValue
  (WFContext pWCtx, 
   WFAttribute pAttr) 
  throws NumberFormatException, WFException

Description

Sets the value of the specified item attribute in the database.

This method throws a NumberFormatException if it cannot convert the value to the appropriate format for an attribute of type number or date. The method throws a WFException if it encounters an error while setting an attribute of type document or text.

Arguments (input)

execute

Java Syntax

public abstract boolean execute
  (WFContext pWCtx)

Description

This abstract method is implemented by the extending class and forms the main entry point function of the external Java function activity being implemented. See: Standard API for Java Procedures Called by Function Activities, Oracle Workflow Developer's Guide.

Arguments (input)

Workflow Attribute APIs

The WFAttribute Java class contains descriptive information for an item or activity attribute, including the internal name of the attribute, attribute value, attribute data type, format information, and default value type. The attribute value is stored as an Object type. This class also contains methods for accessing the attribute information, which can be called by a Java application or the Java procedure for an external Java function activity.

The WFAttribute class is stored in the oracle.apps.fnd.wf Java package. The following list shows the APIs available in this class.

Important: Java is case-sensitive and all Java method names, except the constructor method names, begin with a lower case letter to follow Java naming conventions.

• WFAttribute

• value

• getName

• getValue

• getType

• getFormat

• getValueType

• toString

• compareTo

WFAttribute Class Constants

The WFAttribute class contains several constants. The following table shows the constants that can be used to represent the data type of an attribute.

The following table shows the constants that can be used to represent the type of the default value for an attribute. The default value can be either a constant or, for an activity attribute, a reference to an item type attribute.

Related Topics

Standard API for Java Procedures Called by Function Activities, Oracle Workflow Developer's Guide

WFAttribute

Java Syntax

public WFAttribute()

public WFAttribute
  (String pName
   String pType,
   Object pValue,
   String pValueType)

Description

There are two constructor methods for the WFAttribute class. The first constructor creates a new WFAttribute object. The second constructor creates a new WFAttribute object and initializes it with the specified attribute name, attribute type, value, and value type.

Arguments (input)

value

Java Syntax

public void value
  (Object pValue)

Description

Sets the value of the item or activity attribute within a WFAttribute object. The value must be cast to the Object type.

Important: Using value() to set the attribute value within a WFAttribute object does not set the attribute value in the database. To set the value of an item attribute in the database, use WFFunctionAPI.setItemAttrValue(). See: setItemAttrValue.

Arguments (input)

getName

Java Syntax

public String getName()

Description

Returns the internal name of the item or activity attribute.

getValue

Java Syntax

public Object getValue()

Description

Returns the value of the item or activity attribute as type Object.

getType

Java Syntax

public String getType()

Description

Returns the data type of the item or activity attribute. See: Attribute Types, Oracle Workflow Developer's Guide.

getFormat

Java Syntax

public String getFormat()

Description

Returns the format string for the item or activity attribute, such as the length for an attribute of type text or the format mask for an attribute of type number or date. See: To Define an Item Type or Activity Attribute, Oracle Workflow Developer's Guide.

getValueType

Java Syntax

public String getValueType()

Description

Returns the type of the default value for the item or activity attribute. The default value can be either a constant or, for an activity attribute, a reference to an item type attribute. See: To Define an Item Type or Activity Attribute, Oracle Workflow Developer's Guide.

toString

Java Syntax

public String toString()

Description

Returns the internal name and the value of the item or activity attribute as a string in the following format:

<name>=<value>

This method overrides the toString() method in the Object class.

compareTo

Java Syntax

public int compareTo
  (String pValue) throws Exception

Description

Compares the value of the item or activity attribute with the specified value. compareTo() returns 0 if the two values are equal, -1 if the attribute value is less than the specified value, or 1 if the attribute value is greater than the specified value.

This method throws an Exception if it cannot convert the specified value to the appropriate format for an attribute of type number or date.

Arguments (input)

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.

The columns ERROR_NAME and ERROR_MESSAGE get set to either the values returned by a call to WF_CORE.RAISE(), or to the SQL error name and message if no call to RAISE() is found. The column ERROR_STACK gets set to the contents set by a call to WF_CORE.CONTEXT(), regardless of the error source.

Note: The columns ERROR_NAME, ERROR_MESSAGE, and ERROR_STACK are also defined as item type attributes for the System: Error predefined item type. You can reference the information in these columns from the error process that you associate with an activity. See: Error Handling for Workflow Processes, Oracle Workflow Developer's Guide.

Oracle Workflow also provides a core API that lets you substitute HTML character entity references for special characters in a text string, as a security precaution.

The following APIs can be called by an application program or workflow function in the runtime phase to handle error processing. These APIs are stored in the PL/SQL package called WF_CORE.

• CLEAR

• GET_ERROR

• TOKEN

• RAISE

• CONTEXT

• TRANSLATE

• SubstituteSpecialChars

Related Topics

Standard API for PL/SQL Procedures Called by Function Activities, Oracle Workflow Developer's Guide

CLEAR

Syntax

procedure CLEAR;

Description

Clears the error buffers.

Related Topics

GET_ERROR

GET_ERROR

Syntax

procedure GET_ERROR
  (err_name out varchar2,
   err_message out varchar2
   err_stack out varchar2);

Description

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.

Example

/* Handle unexpected errors in your workflow code by raising 
 * WF_CORE exceptions.  When calling any public Workflow API, 
 * include an exception handler to deal with unexpected 
 * errors.*/

declare
  errname varchar2(30);
  errmsg varchar2(2000);
  errstack varchar2(32000);

begin
  ...
  Wf_Engine.CompleteActivity(itemtype, itemkey, activity, 
    result_code);
  ...

exception
  when others then
    wf_core.get_error(err_name, err_msg, err_stack);
    if (err_name is not null) then
      wf_core.clear;
      -- Wf error occurred.  Signal error as appropriate.
    else
      -- Not a wf error.  Handle otherwise.
    end if;
end;

Related Topics

CLEAR

TOKEN

Syntax

procedure TOKEN
  (token_name in varchar2,
   token_value in varchar2);

Description

Defines an error token and substitutes it with a value. Calls to TOKEN() and RAISE() raise predefined errors for Oracle Workflow that are stored in the WF_RESOURCES table. The error messages contain tokens that need to be replaced with relevant values when the error message is raised. This is an alternative to raising PL/SQL standard exceptions or custom-defined exceptions.

Arguments (input)

Related Topics

RAISE

CONTEXT

RAISE

Syntax

procedure RAISE
  (name in varchar2);

Description

Raises an exception to the caller by supplying a correct error number and token substituted message for the name of the error message provided.

Calls to TOKEN() and RAISE() raise predefined errors for Oracle Workflow that are stored in the WF_RESOURCES table. The error messages contain tokens that need to be replaced with relevant values when the error message is raised. This is an alternative to raising PL/SQL standard exceptions or custom-defined exceptions.

Error messages for Oracle Workflow are initially defined in message files (.msg). The message files are located in the ORACLE_HOME/wf/res/<language> directory for standalone Oracle Workflow or in the $FND_TOP/import/<language> directory for Oracle Applications. During the installation of Oracle Workflow, a program called Workflow Resource Generator takes the designated message files and imports the messages into the WF_RESOURCES table.

Note: If you want to use custom error messages, you can define your messages in .msg files, load them to the WF_RESOURCES table, and then raise them using RAISE(). A custom error message must have an error number of 90000 or higher.

Arguments (input)

To run the Workflow Resource Generator:

The standalone version of Oracle Workflow provides scripts to run the Workflow Resource Generator. In Oracle Applications, run the Workflow Resource Generator as a concurrent program.

For standalone Oracle Workflow:

To run the Workflow Resource Generator, run the wfresgen.sh script on UNIX or the wfresgen.bat script on Windows. These scripts are located in the ORACLE_HOME/wf/admin directory.

To upload seed data from a message source file (.msg) to the database table WF_RESOURCES, enter the following command at your operating system prompt.

• On Unix:

  wfresgen.sh /mode loadresourcetodb  [/debug true] [/validate on] /user <user> /connectstring <connectstring> /language <language> /messagefile <message file>

• On Windows:

  wfresgen.bat /mode loadresourcetodb  [/debug true] [/validate on] /user <user> /connectstring <connectstring> /language <language> /messagefile <message file>

Specify the following parameters for the script:

• /mode - Specify the loadresourcetodb mode to upload seed data from a message source file to the database table WF_RESOURCES.

• /debug - Optionally include this parameter with the value true to report more extensive debugging information in the program output.

• /validate - Optionally include this parameter with the value on to validate the message source file against the database.

• /user - Specify the user name of your Oracle Workflow database account.

• /connectstring - Specify the Oracle Net connect string for the database.

• /language - Specify the language of the seed data to load, using a language abbreviation supported by the Oracle Database. For example, specify JA for Japanese. See: Locale Data, Oracle Database Globalization Support Guide.

• /messagefile - Specify the full path and name of the message source file you want to upload. You can include this parameter multiple times to specify multiple message source files. For example:

  /messagefile <message file1> /messagefile <message file2>

After starting, the Workflow Resource Generator prompts you to enter the password for your Oracle Workflow database account.

The following command shows an example of how to start the Workflow Resource Generator on Windows.

wfresgen.bat /mode loadresourcetodb /user OWF_MGR /connectstring 
"(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=wfhost.oracle.com)
(PORT=1521))(CONNECT_DATA=(SERVER=DEDICATED)
(SERVICE_NAME=orawf)))" /language US /messagefile 
D:\Temp\wffile1.msg /messagefile D:\Temp\wffile2.msg

For Oracle Applications:

1. The Workflow Resource Generator program is registered as a concurrent program. You can run the Workflow Resource Generator concurrent program from the Submit Requests form or from the command line.

2. To run the concurrent program from the Submit Requests form, navigate to the Submit Requests form.

   Note: Your system administrator needs to add this concurrent program to a request security group for the responsibility that you want to run this program from. See: Overview of Concurrent Programs and Requests, Oracle Applications System Administrator's Guide.

3. Submit the Workflow Resource Generator concurrent program as a request. See: Running Reports and Programs, Oracle Applications User's Guide.

4. In the Parameters window, enter values for the following parameters:

   Variable	Description
   Destination Type	Specify "Database", to upload seed data to the database table WF_RESOURCES from a source file (.msg), or "File", to generate a resource file from a source file.
   Destination	If you specify "File" for Destination Type, then enter the full path and name of the resource file you wish to generate. If you specify "Database" for Destination Type, then the program automatically uses the current database account as its destination.
   Source	Specify the full path and name of your source file.

5. Choose OK to close the Parameters window.

6. When you finish modifying the print and run options for this request, choose Submit to submit the request.

7. Rather than use the Submit Requests form, you can also run the Workflow Resource Generator concurrent program from the command line using one of two commands. To generate a resource file from a source file, type:

   WFRESGEN apps/pwd 0 Y FILE res_file source_file
   

   To upload seed data to the database table WF_RESOURCES from a source file, type:

   WFRESGEN apps/pwd 0 Y DATABASE source_file
   

   Replace apps/pwd with the username and password to the APPS schema, replace res_file with the file specification of a resource file, and replace source_file with the file specification of a source file (.msg). A file specification is specified as:

   @<application_short_name>:[<dir>/.../]file.ext
   

   or

   <native path>
   

Related Topics

TOKEN

CONTEXT

CONTEXT

Syntax

procedure CONTEXT
  (pkg_name  IN VARCHAR2,
   proc_name IN VARCHAR2,
   arg1      IN VARCHAR2 DEFAULT '*none*',
   arg2      IN VARCHAR2 DEFAULT '*none*',
   arg3      IN VARCHAR2 DEFAULT '*none*',
   arg4      IN VARCHAR2 DEFAULT '*none*',
   arg5      IN VARCHAR2 DEFAULT '*none*');

Description

Adds an entry to the error stack to provide context information that helps locate the source of an error. Use this procedure with predefined errors raised by calls to TOKEN() and RAISE(), with custom-defined exceptions, or even without exceptions whenever an error condition is detected.

Arguments (input)

Example

/*PL/SQL procedures called by function activities can use the 
 * WF_CORE APIs to raise and catch errors the same way the 
 * Workflow Engine does. */

package My_Package is

procedure MySubFunction(
  arg1 in varchar2,
  arg2 in varchar2)
is
...
begin
  if (<error condition>) then
    Wf_Core.Token('ARG1', arg1);
    Wf_Core.Token('ARG2', arg2);
    Wf_Core.Raise('ERROR_NAME');
  end if;
  ...

exception
  when others then
    Wf_Core.Context('My_Package', 'MySubFunction', arg1, arg2);
    raise;
end MySubFunction;

procedure MyFunction(
  itemtype in varchar2,
  itemkey in varchar2,
  actid in number,
  funcmode in varchar2,
  result out varchar2)
is
...
begin
  ...
  begin
    MySubFunction(arg1, arg2);
  exception
    when others then
      if (Wf_Core.Error_Name = 'ERROR_NAME') then
        -- This is an error I wish to ignore.
        Wf_Core.Clear;
      else
        raise;
      end if;
   end;
   ...
exception
  when others then
    Wf_Core.Context('My_Package', 'MyFunction', itemtype, itemkey,
                    to_char(actid), funcmode);
    raise;
end MyFunction;

Related Topics

TOKEN

RAISE

TRANSLATE

Syntax

function TRANSLATE
  (tkn_name IN VARCHAR2)
  return VARCHAR2;

Description

Translates the string value of a token by returning the value for the token as defined in WF_RESOURCES for your language setting.

Arguments (input)

SubstituteSpecialChars

PL/SQL Syntax

function SubstituteSpecialChars
  (some_text in varchar2) 
  return varchar2;

Pragmas

pragma RESTRICT_REFERENCES(SubstituteSpecialChars,WNDS);

Description

Substitutes HTML character entity references for special characters in a text string and returns the modified text including the substitutions.

You can use this function as a security precaution when creating a PL/SQL document or a PL/SQL CLOB document that contains HTML, to ensure that only the HTML code you intend to include is executed. If you retrieve any data from the database at runtime for inclusion in the document, use SubstituteSpecialChars() to replace any HTML tag characters in that data, so that those characters will not be interpreted as HTML code and executed.

Note that you should not substitute entity references for HTML tags that you include in the document yourself. Otherwise, the document will not be displayed with your intended HTML formatting. You only need to perform this substitution for data that is retrieved from the database at runtime, which may be entered from an external source.

The following table shows each special character and the entity reference with which it is replaced.

Arguments (input)

Workflow Purge APIs

The following APIs can be called by an application program or workflow function in the runtime phase to purge obsolete runtime and design data. These APIs are defined in the PL/SQL package called WF_PURGE.

WF_PURGE can be used to purge obsolete runtime data for completed work items, obsolete runtime data not associated with work items, and design information for obsolete activity versions that are no longer in use and expired users and roles. You may want to periodically purge this obsolete data from your system to increase performance.

A PL/SQL variable called "persistence_type"in the WF_PURGE package defines how most of the WF_PURGE APIs behave, with the exception of TotalPerm(). When the variable is set to TEMP, the WF_Purge APIs only purge data associated with Temporary item types, whose persistence, in days, has expired. The persistence_type variable is set to TEMP by default and should not be changed. If you need to purge runtime data for item types with Permanent persistence, you should use the procedure TotalPerm(). See: Persistence Type, Oracle Workflow Developer's Guide.

Important: You cannot run any WF_PURGE API for a future end date. By entering a future end date, you may inadvertently violate the persistence period for Temporary item types. The WF_PURGE APIs will display an error message if you enter a future end date.

The three most commonly used procedures are:

• WF_PURGE.ITEMS - purge all runtime data associated with completed items, their processes, and notifications sent by them.

• WF_PURGE.ACTIVITIES - purge obsolete design versions of activities that are no longer in use by any item.

• WF_PURGE.TOTAL - purge both item data and activity design data.

The other auxiliary routines purge only certain tables or classes of data, and can be used in circumstances where a full purge is not desired.

The complete list of purge APIs is as follows:

• Items

• Activities

• Notifications

• Total

• TotalPERM

• Directory

  Note: The AdHocDirectory() API from earlier versions of Oracle Workflow is replaced by the Directory() API. The current version of Oracle Workflow still recognizes the AdHocDirectory() API for backward compatibility, but moving forward, you should only use the new Directory() API where appropriate.

In Oracle Applications, you can also use the "Purge Obsolete Workflow Runtime Data" concurrent program to purge obsolete item type runtime status information. See: Purge Obsolete Workflow Runtime Data.

In standalone Oracle Workflow, you can use the standalone Oracle Workflow Manager component available through Oracle Enterprise Manager to submit and manage Workflow purge database jobs. For more information, please refer to the Oracle Workflow Manager online help.

Related Topics

Standard API for PL/SQL Procedures Called by Function Activities, Oracle Workflow Developer's Guide

Purging for Performance, Oracle Workflow Administrator's Guide

Items

Syntax

procedure Items
  (itemtype in varchar2 default null,
   itemkey in varchar2 default null,
   enddate in date default sysdate, 
   docommit in boolean default TRUE,
   force in boolean default FALSE);

Description

Deletes all items for the specified item type, item key, and end date, including process status information, notifications, and any comments associated with these notifications. In Oracle Applications, any electronic signature information associated with these notifications is deleted as well. Deletes from the tables WF_NOTIFICATIONS, WF_COMMENTS, WF_DIG_SIGS, WF_ITEM_ACTIVITY_STATUSES, WF_ITEM_ATTRIBUTE_VALUES and WF_ITEMS.

Note: Oracle Workflow cannot purge work items that have circular parent/child relationships. That is, if a parent item has a child item that in turn is the parent of another child, and so on, a lower-level item in the parent/child hierarchy cannot be set as the parent of a higher-level item. To purge such items, you must first remove the parent/child relationship by calling WF_ENGINE.SetItemParent with null values for the parent item type and parent item key.

Arguments (input)

Activities

Syntax

procedure Activities
  (itemtype in varchar2 default null,
   name in varchar2 default null,
   enddate in date default sysdate);

Description

Deletes old design versions of eligible activities from the tables WF_ACTIVITY_ATTR_VALUES, WF_ACTIVITY_TRANSITIONS, WF_PROCESS_ACTIVITIES, WF_ACTIVITY_ATTRIBUTES_TL, WF_ACTIVITY_ATTRIBUTES, WF_ACTIVITIES_TL, and WF_ACTIVITIES that are associated with the specified item type, have an END_DATE less than or equal to the specified end date, and are not referenced by an existing item as either a process or activity.

Note: You should call Items() before calling Activities() to avoid having obsolete item references prevent obsolete activities from being deleted.

Arguments (input)

Notifications

Syntax

procedure Notifications
  (itemtype in varchar2 default null,
   enddate in date default sysdate,
   docommit in boolean default TRUE);

Description

Deletes old eligible notifications from the tables WF_NOTIFICATION_ATTRIBUTES and WF_NOTIFICATIONS that are associated with the specified item type, have an END_DATE less than or equal to the specified end date, and are not referenced by an existing item. Also, any comments associated with these notifications are deleted from the WF_COMMENTS table. In Oracle Applications, any electronic signature information associated with these notifications is deleted from the WF_DIG_SIGS table as well. You can use this procedure to delete notifications that are not associated with any work item, such as notifications that were sent by calling WF_NOTIFICATION.Send() rather than through a workflow process.

Note: You should call Items() before calling Notifications() to avoid having obsolete item references prevent obsolete notifications from being deleted.

Arguments (input)

Total

Syntax

procedure Total
  (itemtype in varchar2 default null,
   itemkey in varchar2 default null,
   enddate in date default sysdate, 
   docommit in boolean default TRUE,
   runtimeonly in boolean default null);

Description

Deletes all eligible obsolete runtime item type data that is associated with the specified item type and has an END_DATE less than or equal to the specified end date. In Oracle Applications, this procedure also deletes any Oracle XML Gateway transaction information associated with the items being purged.

If the RUNTIMEONLY parameter is set to TRUE or left null, Total() deletes only runtime data associated with work items. However, if the RUNTIMEONLY parameter is set to FALSE, Total() also deletes these types of data:

• All eligible obsolete activity design data that is associated with the specified item type and has an END_DATE less than or equal to the specified end date. See: Activities.

• Expired users and roles in the Workflow local tables that are no longer in use. See: Directory.

• All eligible notifications that are associated with the specified item type, have an END_DATE less than or equal to the specified end date, and are not referenced by an existing item. See: Notifications.

• For Oracle Applications only, Oracle XML Gateway transaction information that is not associated with any existing work item. This information is purged using the ECX_PURGE.Purge_Items API. See: Oracle XML Gateway User's Guide.

Because Total() purges additional design data and runtime data not associated with work items when you set the RUNTIMEONLY parameter to FALSE, it is more costly in performance than Items(). If you want to purge a specific item key, use Items(), or set the RUNTIMEONLY parameter to TRUE when you run Total() to enhance performance. Run Total() with the RUNTIMEONLY parameter set to FALSE as part of your routine maintenance during periods of low activity. See: Items.

Arguments (input)

TotalPERM

Syntax

procedure TotalPERM
  (itemtype in varchar2 default null,
   itemkey in varchar2 default null,
   enddate in date default sysdate, 
   docommit in boolean default TRUE,
   runtimeonly in boolean default null);

Description

Deletes all eligible obsolete runtime data that is of persistence type 'PERM' (Permanent) and that is associated with the specified item type and has an END_DATE less than or equal to the specified end date. In Oracle Applications, this procedure also deletes any Oracle XML Gateway transaction information associated with the items being purged.

If the RUNTIMEONLY parameter is set to TRUE or left null, TotalPERM() deletes only runtime data associated with work items. However, if the RUNTIMEONLY parameter is set to FALSE, TotalPERM() also deletes these types of data:

• All eligible obsolete activity design data that is associated with the specified item type and has an END_DATE less than or equal to the specified end date. See: Activities.

• Expired users and roles in the Workflow local tables that are no longer in use. See: Directory.

• All eligible notifications that are associated with the specified item type, have an END_DATE less than or equal to the specified end date, and are not referenced by an existing item. See: Notifications.

• For Oracle Applications only, Oracle XML Gateway transaction information that is not associated with any existing work item. This information is purged using the ECX_PURGE.Purge_Items API. See: Oracle XML Gateway User's Guide.

TotalPERM() is similar to Total() except that TotalPERM() deletes only items with a persistence type of 'PERM'. See: Total.

Arguments (input)

Directory

Syntax

procedure Directory
   (end_date in date default sysdate);

Description

Purges all users and roles in the WF_LOCAL_ROLES and WF_LOCAL_USER_ROLES tables whose expiration date is less than or equal to the specified end date and that are not referenced in any notification.

Note that although users and roles whose expiration date has passed do not appear in the seeded WF_USERS, WF_ROLES, and WF_USER_ROLES views, they are not removed from the Workflow local tables until you purge them using Directory(). You should periodically purge expired users and roles in order to improve performance.

Arguments (input)

Purge Obsolete Workflow Runtime Data Concurrent Program

If you are using the version of Oracle Workflow embedded in Oracle Applications, you can submit the Purge Obsolete Workflow Runtime Data concurrent program to purge obsolete runtime work item information, including status information and any associated notifications and Oracle XML Gateway transactions. Use the Submit Requests form in Oracle Applications to submit this concurrent program.

By default, this program purges obsolete runtime information associated with work items as well as obsolete design information, such as activities that are no longer in use and expired users and roles, and obsolete runtime information not associated with work items, such as notifications or Oracle XML Gateway transactions that were not handled through a workflow process. You can optionally choose to purge only core runtime information associated with work items for performance gain during periods of high activity, and purge all obsolete information as part of your routine maintenance during periods of low activity.

Note: You can also use the Oracle Workflow Manager component of Oracle Applications Manager to submit and manage the Purge Obsolete Workflow Runtime Data concurrent program. For more information, please refer to the Oracle Applications Manager online help.

Additionally, in Oracle Applications you can use the Purge Obsolete ECX Data concurrent program to purge Oracle XML Gateway transactions according to Oracle XML Gateway-specific parameters. See: Purge Obsolete ECX Data Concurrent Program, Oracle XML Gateway User's Guide.

To Purge Obsolete Workflow Runtime Data:

1. Navigate to the Submit Requests form in Oracle Applications to submit the Purge Obsolete Workflow Runtime Data concurrent program. When you install and set up Oracle Applications and Oracle Workflow, your system administrator needs to add this concurrent program to a request security group for the responsibility that you want to run this program from. The executable name for this concurrent program is "Oracle Workflow Purge Obsolete Data" and its short name is FNDWFPR. See: Overview of Concurrent Programs and Requests, Oracle Applications System Administrator's Guide.

2. Submit the Purge Obsolete Workflow Runtime Data concurrent program as a request. See: Running Reports and Programs, Oracle Applications User's Guide.

3. In the Parameters window, enter values for the following parameters:

   Variable	Description
   Item Type	Item type associated with the obsolete runtime data you want to delete. Leave this argument null to delete obsolete runtime data for all item types.
   Item Key	A string generated from the application object's primary key. The string uniquely identifies the item within an item type. If null, the program purges all items in the specified item type.
   Age	Minimum age of data to purge, in days, if the persistence type is set to 'Temporary'. The default is 0.
   Persistence Type	Persistence type to be purged, either 'Temporary' or 'Permanent'. The default is 'Temporary'.
   Core Workflow Only	Enter 'Y' to purge only obsolete runtime data associated with work items, or 'N' to purge all obsolete runtime data as well obsolete design data. The default is 'N'.
   Commit Frequency	The number of records to purge before the program commits data. To reduce rollback size and improve performance, set this parameter to commit data after a smaller number of records. The default is 500 records. Note: After performing a commit, the program resumes purging work items with the next subsequent begin date. In some cases, if additional items have the same begin date as the last item that was purged before a commit, the program may not purge all eligible items. To purge these remaining work items, simply rerun the program.

4. Choose OK to close the Parameters window.

5. When you finish modifying the print and run options for this request, choose Submit to submit the request.

Workflow Monitor APIs

Call the following APIs to retrieve an access key or to generate a complete URL to access various pages of the Workflow Monitor in standalone Oracle Workflow, or to access various pages of the administrator version of the Status Monitor in Oracle Applications with guest access. The Workflow Monitor APIs are defined in the PL/SQL package called WF_MONITOR.

• GetAccessKey

• GetDiagramURL

• GetEnvelopeURL

• GetAdvancedEnvelopeURL

Note: The GetURL API from earlier versions of Oracle Workflow is replaced by the GetEnvelopeURL and GetDiagramURL APIs. The functionality of the previous GetURL API correlates directly with the new GetDiagramURL. API. The current version of Oracle Workflow still recognizes the GetURL API, but moving forward, you should only use the two new APIs where appropriate.

Note: Oracle Workflow also provides Java methods for accessing the Status Monitor in Oracle Applications, which are defined in the Java class called oracle.apps.fnd.wf.monitor.webui.Monitor. For more information about these methods, refer to the Javadoc for the oracle.apps.fnd.wf.monitor.webui.Monitor class.

Related Topics

Providing Access to the Status Monitor from Applications, Oracle Workflow Administrator's Guide

Guest Access in PL/SQL, Oracle Workflow Administrator's Guide

GetAccessKey

Syntax

function GetAccessKey
  (x_item_type varchar2,
   x_item_key varchar2,
   x_admin_mode varchar2)
  return varchar2;

Description

Retrieves the access key password that controls access to the Workflow Monitor. Each process instance has separate access keys for running the Workflow Monitor in 'ADMIN' mode or 'USER' mode.

Arguments (input)

GetDiagramURL

Syntax

function GetDiagramURL
  (x_agent in varchar2,
   x_item_type in varchar2,
   x_item_key in varchar2,
   x_admin_mode in varchar2 default 'NO')
  return varchar2;

Description

Can be called by an application to return a URL that allows access to a status diagram in the Workflow Monitor in standalone Oracle Workflow with an attached access key password, or to the Status Diagram page in the Status Monitor in Oracle Applications with guest access.

• In standalone Oracle Workflow, the URL displays the diagram for a specific instance of a workflow process in the Workflow Monitor operating in either 'ADMIN' or 'USER' mode.

  The URL returned by the function WF_MONITOR.GetDiagramURL() looks as follows:

  <webagent>/wf_monitor.html?x_item_type=<item_type>&x_item_key=
  <item_key>&x_admin_mode=<YES or NO>&x_access_key=<access_key>
  

  <webagent> represents the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.

  wf_monitor.html is the name of the PL/SQL package procedure that generates the Workflow Monitor diagram of the process instance.

  The wf_monitor.html procedure requires four arguments. <item_type> and <item_key> represent the internal name of the item type and the item key that uniquely identify an instance of a process. If <YES or NO> is YES, the monitor runs in 'ADMIN' mode and if NO, the monitor runs in 'USER' mode. <access_key> represents the access key password that determines whether the monitor is run in 'ADMIN' or 'USER' mode.

• In Oracle Applications, the URL displays the Status Diagram page for a specific instance of a workflow process in the administrator version of the Status Monitor, operating either with or without administrator privileges.

Arguments (input)

http://<server.com:portID>/<PLSQL_agent_path>

Example

Following is an example of how you can call GetDiagramUrl(). This example returns a URL that displays the diagram page for a process instance identified by the item type WFDEMO and item key 10022, in 'USER' mode or without administrator privileges:

URL := WF_MONITOR.GetDiagramURL
  (WF_CORE.Translate('WF_WEB_AGENT'),
   'WFDEMO',
   '10022', 
   'NO');

Related Topics

TRANSLATE

GetEnvelopeURL

Syntax

function GetEnvelopeURL
  (x_agent in varchar2,
   x_item_type in varchar2,
   x_item_key in varchar2,
   x_admin_mode in varchar2 default 'NO')
  return varchar2;

Description

Can be called by an application to return a URL that allows access to the Workflow Monitor Notifications List in standalone Oracle Workflow with an attached access key password, or to the Monitor Responses page in the Status Monitor in Oracle Applications with guest access.

• In standalone Oracle Workflow, the URL displays the Notifications List for a specific instance of a workflow process in the Workflow Monitor.

  The URL returned by the function WF_MONITOR.GetEnvelopeURL() looks as follows:

  <webagent>/wf_monitor.envelope?x_item_type=<item_type>&x_item_key=
  <item_key>&x_admin_mode=<YES or NO>&x_access_key=<access_key>
  

  <webagent> represents the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.

  wf_monitor.envelope is the name of the PL/SQL package procedure that generates the Workflow Monitor Notifications List for the process instance.

• In Oracle Applications, the URL displays the Monitor Responses page for a specific instance of a workflow process in the administrator version of the Status Monitor, operating either with or without administrator privileges.

Arguments (input)

http://<server.com:portID>/<PLSQL_agent_path>

Related Topics

TRANSLATE

GetAdvancedEnvelopeURL

Syntax

function GetAdvancedEnvelopeURL
  (x_agent in varchar2,
   x_item_type in varchar2,
   x_item_key in varchar2,
   x_admin_mode in varchar2 default 'NO',
   x_options in varchar2 default null)
  return varchar2;

Description

Can be called by an application to return a URL that displays the Workflow Monitor Activities List in standalone Oracle Workflow with an attached access key password, or to the Activity History page in the Status Monitor in Oracle Applications with guest access.

• In standalone Oracle Workflow, the URL displays the Activities List for a specific instance of a workflow process in the Workflow Monitor. The Activities List allows you to apply advanced filtering options in displaying the list of activities for a process instance.

  The URL returned by the function WF_MONITOR.GetAdvancedEnvelopeURL() looks as follows if the x_options argument is null:

  <webagent>/wf_monitor.envelope?x_item_type=<item_type>&x_item_key=
  <item_key>&x_admin_mode=<YES or NO>&x_access_key=<access_key>
  &x_advanced=TRUE
  

  <webagent> represents the base URL of the Web agent configured for Oracle Workflow in your Web server. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.

  wf_monitor.envelope is the name of the PL/SQL package procedure that generates the Workflow Monitor Notifications List for the process instance.

• In Oracle Applications, the URL displays the Activity History page for a specific instance of a workflow process in the administrator version of the Status Monitor, operating either with or without administrator privileges. All activity type and activity status filtering options are automatically selected by default.

Arguments (input)

http://<server.com:portID>/<PLSQL_agent_path>

Related Topics

TRANSLATE

Workflow Status Monitor APIs

Call the following APIs to retrieve parameters for use with the self-service functions that provide access to the Status Monitor from Oracle Applications forms. You can use these APIs to help integrate other applications with the Status Monitor.

The Workflow Status Monitor PL/SQL APIs are defined in the PL/SQL package called WF_FWKMON.

• GetEncryptedAccessKey

• GetEncryptedAdminMode

• IsMonitorAdministrator

Related Topics

Providing Access to the Status Monitor from Applications, Oracle Workflow Administrator's Guide

Guest Access from Oracle E-Business Suite Forms, Oracle Workflow Administrator's Guide

GetEncryptedAccessKey

PL/SQL Syntax

function GetEncryptedAccessKey
  (itemType in varchar2,
   itemKey in varchar2,
   adminMode in varchar2 default 'N')
  return varchar2;

Description

Returns an encrypted access key password that controls access to the specified workflow process instance in the Status Monitor with the specified administrator mode. The administrator mode lets you determine whether the user who accesses the Status Monitor with this access key should have privileges to perform administrative operations in the Status Monitor.

Arguments (input)

GetEncryptedAdminMode

PL/SQL Syntax

function GetEncryptedAdminMode
  (adminMode in varchar2)
  return varchar2;

Description

Returns an encrypted value for the specified administrator mode. The administrator mode lets you determine whether a user accessing the Status Monitor should have privileges to perform administrative operations in the Status Monitor.

Arguments (input)

IsMonitorAdministrator

PL/SQL Syntax

function IsMonitorAdministrator
  (userName in varchar2)
  return varchar2;

Description

Returns 'Y' if the specified user has workflow administrator privileges, or 'N' if the specified user does not have workflow administrator privileges. Workflow administrator privileges are assigned in the Workflow Configuration page. See: Setting Global User Preferences, Oracle Workflow Administrator's Guide.

For example, you can use this function to help determine what administrator mode to choose when calling GetEncryptedAccesKey() or GetEncryptedAdminMode() to retrieve parameters for use with the Status Monitor form functions.

Arguments (input)

Oracle Workflow Views

Public views are available for accessing workflow data. If you are using the version of Oracle Workflow embedded in Oracle Applications, these views are installed in the APPS account. If you are using the standalone version of Oracle Workflow, these views are installed in the same account as the Oracle Workflow server.

• WF_ITEM_ACTIVITY_STATUSES_V

• WF_NOTIFICATION_ATTR_RESP_V

• WF_RUNNABLE_PROCESSES_V

• WF_ITEMS_V

Note: These database views are public, meaning they are available for you to use for your custom data requirements. This description does not mean that any privileges for these views have been granted to PUBLIC.

WF_ITEM_ACTIVITY_STATUSES_V

This view contains denormalized information about a workflow process and its activities' statuses. Use this view to create custom queries and reports on the status of a particular item or process.

The following table describes the columns of the view.

Note: The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.

WF_NOTIFICATION_ATTR_RESP_V

This view contains information about the Respond message attributes for a notification group. If you plan to create a custom voting activity, use this view to create the function that tallies the responses from the users in the notification group. See: Voting Activity, Oracle Workflow Developer's Guide.

The following table describes the columns of the view.

WF_RUNNABLE_PROCESSES_V

This view contains a list of all runnable workflow processes in the ACTIVITIES table.

The following table describes the columns of the view.

WF_ITEMS_V

This view is a select-only version of the WF_ITEMS table.

The following table describes the columns of the view.

Note: The item key for a process instance can only contain single-byte characters. It cannot contain a multibyte value.

Copyright © 2003, 2006, Oracle. All rights reserved.