For any given item type, you can define a single function that operates as both a selector and a callback function. A selector function is a PL/SQL procedure that automatically identifies the specific process definition to execute when a workflow is initiated for a particular item type but no process name is provided. Oracle Workflow also supports using a callback function to reset or test item type context information. You can define one PL/SQL procedure that includes both selector and callback functionality by following a standard API.
Oracle Workflow can call the selector/callback function with the following commands:
RUN - to select the appropriate process to start when either of the following two conditions occur:
A process is not explicitly passed to WF_ENGINE.CreateProcess.
A process is implicitly started by WF_ENGINE.CompleteActivity with no prior call to WF_ENGINE.CreateProcess.
SET_CTX - to establish any context information for an item type and item key combination that a function activity in the item type needs in order to execute. The Workflow Engine calls the selector/callback function with this command each time it encounters a new item type and item key combination, to ensure that the correct context information is always set.
TEST_CTX - to determine if the current item type context information is correct before executing a function, such as during background processing.
The standard API for the selector/callback function is as follows. The example in this section is numbered with the notation (1) for easy referencing. The numbers themselves are not part of the procedure.
(1) procedure <procedure name>
(item_type in varchar2,
item_key in varchar2,
activity_id in number,
command in varchar2,
resultout in out varchar2) is
(2) <local declarations>
(3) begin
if ( command = 'RUN' ) then
<your RUN executable statements>
resultout := '<Name of process to run>';
return;
end if;
(4) if ( command = 'SET_CTX' ) then
<your executable statements for establishing
context information>
return;
end if;
(5) if ( command = 'TEST_CTX' ) then
<your executable statements for testing
the validity of the current context information>
resultout := '<TRUE or FALSE or NOTSET> ';
return;
end if;
(6) if ( command = '<other command>' ) then
resultout := ' ';
return;
end if;
(7) exception
when others then
WF_CORE.CONTEXT ('<package name>', '<procedure name>',
<itemtype>,<itemkey>,
to_char(<actid>), <command>);
raise;
(8) end <procedure name>;
(1) When the Workflow Engine calls the selector/callback function, it passes four parameters to the procedure and may expect a result when the procedure completes. The parameters are defined here:
| itemtype | The internal name for the item type. Item types are defined in the Oracle Workflow Builder. |
| itemkey | A string that represents a primary key generated by the workflow-enabled application for the item type. The string uniquely identifies the item within an item type. |
| actid | The ID number of the activity that this procedure is called from. Note that this parameter is always null if the procedure is called with the 'RUN' command to execute the selector functionality. |
| command | The command that determines how to execute the selector/callback function. Either 'RUN', 'SET_CTX', or 'TEST_CTX'. Other commands may be added in the future. |
| resultout | A result may be returned depending on the command that is used to call the selector/callback function. If the function is called with 'RUN', the name of the process to run must be returned through the resultout parameter. If the function is called with 'SET_CTX', then no return value is expected. If the function is called with 'TEST_CTX', then the code must return 'TRUE' if the context is correct, 'FALSE' if the context is incorrect, or 'NOTSET' if the context has not been initialized yet. If any other value is returned, Oracle Workflow assumes that this command is not implemented by the callback. |
(2) This section declares any local arguments that are used within the procedure.
(3) The procedure body begins in this section with an IF statement. This section contains one or more executable statements that make up your selector function. It executes if the value of command is 'RUN'. One of the executable statements should return a result for the procedure that reflects the process to run. For example, a result can be 'REQUISITION_APPROVAL', which is the name of an example process activity.
(4) This section contains one or more executable statements that set item type context information if the value of command is 'SET_CTX'. The Workflow Engine calls the selector/callback function with this command each time it encounters a new item type and item key combination, before executing any function activities for that combination. This command is useful when you need to set item type context information in a database session before the activities in that session can execute as intended. For example, you might need to set up the responsibility and organization context for function activities that are sensitive to multi-organization data.
(5) This section contains one or more executable statements that validate item type context information if the value of command is 'TEST_CTX'. The Workflow Engine calls the selector/callback function with this command to validate that the current database session context is acceptable before the Workflow Engine executes an activity, such as during background processing. The code in this section should return 'TRUE' if the context is correct, 'FALSE' if the context is incorrect, or 'NOTSET' if the context has not been initialized yet.
Note: The selector/callback function should return'NOTSET' only when none of the context variables has been initialized. If one or more context variables are set but not all the required variables are set, then the selector/callback function should return 'FALSE'. Likewise, if any context variable is set to an invalid value, then the selector/callback function should return 'FALSE'.
Many context variables for Oracle E-Business Suite, such as FND_GLOBAL.user_id and FND_GLOBAL.resp_id, are already initialized by the Oracle Forms, Oracle Application Framework, or concurrent processing connection. Consequently, with such connections a selector/callback function should usually return 'FALSE' if the context is incorrect, rather than 'NOTSET'. The selector/callback function should return 'NOTSET' only when none of the required context variables is set, which may be the case with a SQL*Plus or patching connection that does not initialize Oracle E-Business Suite context variables.
If the result is 'TRUE', the Workflow Engine keeps the current context.
If the result is 'NOTSET', the Workflow Engine runs the function in 'SET_CTX' mode to set the context.
If the result is 'FALSE' and the Workflow Engine permits context switching at this point in its processing, it runs the function in 'SET_CTX' mode to set the correct context. However, if the result is 'FALSE' but the Workflow Engine requires the current context to be preserved, it defers the activity to be processed by a background engine instead.
Note: The Workflow Engine permits context switching during background processing, such as workflow background engine processing, workflow mailer response processing, agent listener processing, and so on. The Workflow Engine requires the current context to be preserved during online sessions, such as when a user is logged into Oracle E-Business Suite and responding to a notification from the worklist.
(6) This section handles execution modes other than 'RUN', 'SET_CTX' or 'TEST_CTX' as others may be added in the future. Since your function does not need to implement any of these other possible commands, it should simply return null.
(7) This section calls WF_CORE.CONTEXT() if an exception occurs, so that you can include context information in the error stack to help you locate the source of an error. See: CONTEXT.