Oracle Workflow API Reference|
Part Number B12163-02
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.
You can reference these global engine variables in your PL/SQL function.
- 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.
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.
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.
Attention: 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.
Copyright © 2003, 2004, Oracle. All rights reserved.