Oracle Purchasing POERROR Workflow Setup and Usage Guide

An Oracle White Paper

November, 2002 (Reviewed February, 2009)

Oracle Purchasing POERROR Workflow Setup and Usage Guide

INTRODUCTION Improved document error handling was introduced in Oracle Applications 11.5.6 in Procurement Family Pack F that allows users better control over the Document Approval Manager errors that can occur during the approval process of a purchasing document. This feature provides flexibility that is not available in earlier versions to handle some of the errors that result when the Document Approval Manager fails. ABSTRACT Currently, when the Document Approval Manager fails during the approval process of a purchasing document; the user who performs the last action on the document receives a notification. This notification states the error encountered is because of the Document Approval Manager and users must figure out the error and fix the problem causing the Document Approval Manger to fail. The users also do not have an option for resubmitting the document since the status of the document remains ‘In Process’. This new feature automatically resubmits the document(s) failing because of Document Manager failures due to Doc Mgr Error 1 (Document Approval Manager Timeout) or to Doc Mgr Error 2 (Document Approval Manager Not Active). The new feature is a new workflow item type called POERROR. The display name of the new workflow is PO Approval Error.

BACKGROUND When a purchasing document is submitted for approval, the Approval Workflow starts the approval process for that document. The Approval Workflow process moves the document from one sub-process to another, making various checks on the document. The Document Approval Manager is a concurrent manager that executes the code needed to perform these various checks called by the Approval Workflow. This concurrent manager needs to be Active for the Approval Workflow process to complete successfully. The Document Approval Manager is setup and maintained like any other concurrent manager by the System Administrator. Since the Document Approval Manager is required for the Approval Workflow pro cess to complete successfully, if the Document Approval Manager fails, times out, or is not active, the Approval Workflow process also errors and halts without resetting the status of the document being processed. This causes the document to remain in ‘In Process’ status and inaccessible via the Oracle Purchasing application. The Document Approval Manager returns three error codes. These are explained in detail below in Figure 2.0.

Figure 2.0 – Document Approval Manager Error Descriptions Error Number Meaning

1 Document Approval Manager timed out. This error occurs when the Approval Workflow process has been waiting for the Document Approval Manager for more than the allocated time allowed (set by profile "PO: Approval Timeout Value") to finish execution and return a result to the PO/Req Approval Workflow.

2 Document Approval Manager is not Active.

3 Exception in the Document Approval Manager code. Any other Document Approval Manager failure other than a Timeout (Error 1) or Not Active (Error 2) results in this Document Approval Manager Error 3 code. When this error occurs, the Document Approval Manager provides more details about the exact code error in an error message. Approval workflow then sets the value of attribute SYSADMIN_ERROR_MSG to this message.

Whenever one of the above errors occurs, the document that the Workflow is processing remains in status ‘In Process’. Prior to Procurement Family Pack F, a purchasing document in ‘In Process’ status can only be viewed in Oracle Purchasing from the Purchase Order Summary form. No actions can be taken on a document in this status. This made it difficult to approve a document successfully if there was a Document Approval Manager failure since the document could not be submitted via workflow or via Oracle Purchasing application once the error was resolved. The only methods available to resubmit a document for approval when the document is in ‘In Process’ status due to Document Approval Manager error was using PL/SQL scripts to manually resubmit for approval. This is not an efficient solution if there are large numbers of documents that are ‘In Process’ status.

After Procurement Family Pack F the new POERROR workflow can be configured to resubmit documents automatically that failed due to Document Approval Manager Errors 1 or 2. For Document Approval Manager Error 3 a Notification is sent that allows the System Administrator to retry the document approval directly from the Notification

POERROR WORKFLOW SETUP Workflow item attributes for the POERROR Workflow have to be configured to use this improved error handling. Access to Oracle Workflow Builder is required to setup and maintain the POERROR Workflow. Just like any other workflow process, POERROR also consists of function activities that are viewable in the Oracle Workflow Builder as a diagram. It is important to remember that whenever a workflow is modified, only those documents that are submitted for approval after the changes have been made are affected by the modified workflow.

Please reference the EXAMPLES section at the end of the document for clear case studies that illustrate how these setups will affect the Document Approval process in scenarios where

Document Approval Manager Error 1 and Document Approval Manager Error 2 occurs. Setup Steps

Step 1: Set item attributes of POERROR item type using Oracle Workflow Builder. Step 2: Schedule Workflow Background Process to run periodically for POERROR workflow item type Step 3: Schedule Workflow Background Process to run periodically for POAPPRV and REQAPPRV workflow item types

Step 1: Set item attributes of POERROR item type using Oracle Workflow Builder Figure 3.0 below provides details on the POERROR workflow item attributes that must be configured in order to use this workflow process.

Figure 3.0 - POERROR Workflow Item Attributes Attribute Internal Name Usage

Timeout Value TIMEOUT_VALUE

Length of time, in minutes, for the notification to

automatically close itself. Default = 0

Relative Time of Auto Retry for Document Manager

DOC_MGR_WAIT_RELATIVE_TIME Length of time, in minutes, processes will have to wait before getting pickedagain.

Default = 0

Auto retry for Document Manager

RETRY_COUNT Number of attempts to get document manager for approval.

Default = 0

System Administrator User Name

SYSADMIN_USER_NAME Application user (typically the System Administrator) who will receive notifications for document manager-related errors. This must be defined manually as a valid UserID in the system.

Default = null

1. Choose Open from the File menu and connect to the database as the APPS user. See: Opening and Saving Item Types, Oracle Workflow Guide. The Display name of the PO Approval workflow is PO Approval Error. The name of its Workflow definition file is poxwfpoe.wft. Reference Figure 4.1

Figure 4.1 - poxwfpoe.wft

2. Expand the data source, and then the PO Approval Error item type branch within that data source. 3. Expand the Attributes branch within the PO Approval Error branch. 4. Double click on the attribute ‘Timeout Value’. The Properties window will open. Set the value of the attribute in the Value field as shown below. Reference Figure 4.2 below

Figure 4.2 – Timeout Parameter

5. Similarly, change the values of other three attributes as shown below in Figures 4.3, 4.4, and 4.5.

Figure 4.3 – Relative Time

Figure 4.4 – Retry Count

Figure 4.5 – System Administrator

6. Choose Save from the File menu to save the changes in the database as the APPS user (if not saved to the database the changes will be saved to a flat file on the PC and will not be used by the Application) 7. Choose Close Store from the File menu to close the workflow builder. Step 2: Schedule Workflow Background Process for POERROR Workflow 1. Log into Oracle Applications and choose the System Administrator responsibility. 2. From the Navigator window navigate to Requests > Run 3. On the Submit Request form select ‘Workflow Background Process’. 4. In the parameters window, enter the following parameters and click on OK button. Reference Figure 5.1 below.

Item Type = ‘PO Approval Error’ Process Deferred = Yes Process Timeout = No Process Stuck = blank

Figure 5.1 – PO Approval Error

5. Click on the ‘Schedule’ button on the form. 6. On the Schedule form, choose the interval at which this program is preferred to run for this item type and click OK. See Figure 5.2 below.

Figure 5.2 – Schedule

7. Click on ‘Submit’ button. Step 3: Schedule Workflow Background Process to run periodically for POAPPRV and REQAPPRV item types 1. Log into Oracle Applications and choose System Administrator responsibility. 2. From the Navigator window navigate to Requests -> Run 3. On the Submit Request form select ‘Workflow Background Process’. 4. In the parameters window, enter the following parameters and click on OK button. Reference Figure 6.1 below.

Item Type = ‘PO Approval’ Process Deferred = Yes Process Timeout = No Process Stuck = blank

Figure 6.1 – PO Approval

5. Click on the ‘Schedule’ button on the form. 6. On the Schedule form, choose the interval at which this program is preferred to run for this item type and click OK. See Figure 6.2 below.

Figure 6.2 – Schedule

7. Click on ‘Submit’ button. 8. Repeat steps 1 – 7 for item type ‘PO Requisition Approval’. LIMITATIONS

1. The document is automatically submitted again for approval only when the Document Approval Manager fails with error number 1 (Timed Out) and error number 2 (Not Active).

2. When the Document Approval Manager fails with error number 3 (Unknown Error), a notification is sent to SYSADMIN_USER_NAME with a retry option. This document will not be automatically submitted again for approval and the notification sent will not time out. This will allow the System Administrator to communicate to the Users to correct the issue and allows the System Administrator to retry the document approval without having to access the database to use wfretry.sql.

3. When a document fails approval process due to a Generic or PL/SQL error, a FYI notification will be sent to SYSADMIN_USER_NAME. This document will not be automatically submitted again for approval and does not have a retry option.

EXAMPLES Example Setups The PO Approval Error (POERROR) workflow attributes are set as follows:

DOC_MGR_WAIT_RELATIVE_TIME 60 RETRY_COUNT 10 TIMEOUT_VALUE 300 SYSADMIN_USER_NAME JOHNDOE

In addition, the following workflow background processes are scheduled: Item Type = PO Approval Error Frequency = 1 min Deferred = Yes Time Out = No Stuck = blank

Item Type = Requisition Approval Frequency = 5 minutes Deferred = Yes Time Out = No Stuck = blank Item Type = PO Approval Frequency = 2 min Deferred = Yes Time Out = No Stuck = blank

Example 1: Document Approval Manager Times Out Example (Doc Mgr Error 1) A Requisition is submitted for approval. Due to system resources the workflow times out because the Document Approval Manager did not process the Activity within 180 seconds. The result is the document approval will fail with a Document Approval Manager Error 1. Assume that the time in which the document failed is 2:00 PM. Also assume this is the time that the two background processes begin their schedules. The PO Approval Error background process will run at 2:01 PM and submit the document for approval again. At 2:05 PM the Requisition Approval background process runs and reprocesses this Requisition for Approval. This time, system resources are not as busy, and the document continues with the Approval process. Without user intervention the document is reprocessed for approval. If for some reason the resources were still busy and the Activity timed out again, the document approval process would fail again with a Doc Mgr Error 1. Assuming this error occurs at 2:07 PM, then at 2:08 PM the PO Error workflow background process would pick up this errored process again. Then, at 2:10 PM, the Requisition Approval Process would reprocess the document for approval. This repeating process would continue for the value set in the POERROR workflow for the RETRY_COUNT (10 times in this example). At the end of these 10 retries a Notification would be sent to JOHNDOE (value of

SYSADMIN_USER_NAME). If JOHNDOE sees this notification he can choose the RETRY option on the notification or let the notification timeout at which time Workflow will resubmit the document again. If no Action take from the Notification after 300 seconds (value of TIMEOUT_VALUE) then the Notification would timeout and the document would be resubmitted for approval again. The RETRY_COUNT value is then reset and the process will repeat. Example 2: Document Approval Manager is Not Active Example (Doc Mgr Error 2) A PO submitted for approval and the Document Approval Manager is not Active. The document approval will fail due to Document Approval Manager Error number 2. Assume that the time at which the document failed was 12:00 AM. If we assume that this is also the time that the background processes also begin their schedule, then the PO Approval Error background process will run at 12:01 AM and submit the document for approval. At 12:02 AM when the background process for PO Approval runs, the document will be picked up for approval process and processed again. If the Document Approval Manager was started during this time the document will continue with the approval process. But lets assume that the Document Approval Manager was not started during the last 2 minutes and the document fails again due to Document Approval Manager error number 2. If the time at which the document failed the second time was 12:03 AM, then at 12:04 AM when the background process for PO Approval Error runs again, then it resubmits the document for approval. Now when the PO Approval background process runs at 12:06 AM, this document is processed again.This resubmitting of document for approval will take place 10 times, number of RETRY_COUNT. If after all the tries, the document is still not approved, a notification is sent to JOHNDOE. If there was no action taken on this notification, then the notification will timeout in 300 seconds (value of TIMEOUT_VALUE). Once the notification times out, the document is automatically submitted for approval again. When the document is submitted for approval from the notification, RETRY_COUNT is reset it is tried for another 10 times. If the error is still not resolved then another notification is sent to JOHNDOE at the end of these 10 tries. If JOHNDOE sees this notification and starts the Document Approval Manager, he can come back into the notification and choose the RETRY option on the notification or let the notification timeout, which will resubmit the document again.

Oracle Purchasing POERROR Workflow Setup and Usage Guide Novemeber 2002 (revised, February 2009) Author: Sonia Ahmed Contributing Authors: Mike Williams Copyright © Oracle Corporation 1995 All Rights Reserved Printed in the U.S.A. This document is provided for informational purposes only and the information herein is subject to change without notice. Please report any errors herein to Oracle Corporation. Oracle Corporation does not provide any warranties covering and specifically disclaims any liability in connection with this document. Oracle is a registered trademark and Enabling the Information Age Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065 U.S.A. Worldwide Inquiries: 415.506.7000 Fax 415.506.7200 Copyright © Oracle Corporation 1995 All Rights Reserved