Oracle Purchasing POERROR Workflow Setup and Usage Guide White Paper [ID

224028.1]

Modified 08-MAR-2011 Type WHITE PAPER Status PUBLISHED

Applies to:

Oracle Purchasing - Version: 11.5.6 to 12.0.6 - Release: 11.5 to 12

Linux x86
HP-UX PA-RISC (64-bit)
IBM AIX on POWER Systems (64-bit)
HP-UX PA-RISC (32-bit)
Oracle Solaris on SPARC (64-bit)
Obsolete Linux Intel (64-bit)
IBM AIX on POWER Systems (32-bit)
Oracle Solaris on SPARC (32-bit)
HP Tru64 UNIX

Abstract

Document error handling is available in Oracle Purchasing that allows users better control
over the Document Approval Manager errors that can occur during the approval process of a
purchasing document.

Oracle Purchasing POERROR Workflow Setup and Usage Guide White Paper

ABSTRACT

The POERROR workflow 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 display name of the
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 process
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:

Error Number Meaning

Document manager error #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 option "PO: Approval Timeout Value") to finish
execution and return a result to the PO/Req
Approval Workflow.

Document manager error #2 Document Approval Manager is not Active

Document manager error #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’. The 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 error
handling functionality. 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

The table below provides details on the POERROR workflow item attributes that
must be configured in order to use this workflow process.

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 DOC_MGR_WAIT_RELATIVE_TIME Length of time, in minutes,

Document Manager processes will have to wait
before getting picked again.
Default = 0

Auto retry for Document RETRY_COUNT Number of attempts to get

Manager document manager for approval.
Default = 0

System Administrator User SYSADMIN_USER_NAME Application user (typically the

Name System Administrator) who will
receive notifications for
document manager-related
errors. This must be defined
manually as a valid UserID in
the system. There is not default
value.

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.

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

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

Summary

This whitepaper explains how the application 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 feature is a
workflow item type called POERROR. The display name of the new workflow is PO Approval
Error.

Copyright � 2002 Oracle Corporation. All rights reserved. Oracle is a registered trademark of Oracle Corporation.
Various product and service names referenced herein may be trademarks of Oracle Corporation. All other
product and service names mentioned may be trademarks of their respective owners.

Disclaimer: This document is provided for information purposes only and the contents hereof are subject to
change without notice. Oracle Corporation does not warrant that this document is error-free, nor does it
provide any other warranties or conditions, whether expressed orally or implied in law, including implied
warranties and conditions of merchantability or fitness for a particular purpose. Oracle Corporation
specifically disclaims any liability with respect to this document and no contractual obligations are formed
either directly or indirectly by this document. This document may not be reproduced or transmitted in any
form or by any means, electronic or mechanical, for any purpose, without the prior written permission of
Oracle Corporation.

Attachments

attributes.jpg (155.55 KB)

doc_mgr_wait.jpg (36.65 KB)
itemtype.jpg (39.12 KB)
poapproval.jpg (83.28 KB)
retrycount.jpg (36.5 KB)
sysadminusername.jpg (34 KB)
 timeoutvalue.jpg (34.1 KB)
workflowbackgroundprocess.jpg (84.35 KB)
workflowbackgroundprocess2.jpg (105.77 KB)
Related

Products

 Oracle E-Business Suite > Procurement > Procurement > Oracle Purchasing

Keywords

PO REQUISITION APPROVAL; REQAPPRV; DOCUMENT MANAGER ERROR; PO

APPROVAL; POAPPRV; POERROR; DOCUMENT MANAGER FAILED WITH ERROR
NUMBER 3; PO STUCK IN PROCESS
Errors

ERROR HANDLING; ERROR 1; ERROR 5; ERROR 2; ERROR 3

Back to top