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. The figure below demonstrates the flow of the document during the approval process.
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 are inaccessible to the Oracle Purchasing application. The Document Approval Manager returns three error codes. These are explained in the table below.
Document Approval Manager Errors
| Error Number | Description |
|---|---|
| 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 180 seconds 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'. PO Approval Error 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.
Use the Oracle Workflow Builder to customize workflows. For the PO Approval Error workflow this is the set up. When you customize a workflow, only those documents that are created after you customize it are affected by the customized workflow.
To display the workflow in the Oracle Workflow Builder:
Choose Open from the File menu, and connect to the database.
See: Opening and Saving Item Types.
The Display name of the workflow is PO Approval Error. Its internal name, viewable through the Workflow Builder, is POERROR. The name of its Workflow definition file is poxwfpoe.wft.
Expand the data source, then the PO Approval Error item type branch within that data source.
Expand the Processes branch within the PO Approval Error branch, then double-click on its process activity to display the process diagram.
If you want to customize the PO Approval Error workflow, you must customize the default (original) workflow that Purchasing provides. Unlike the PO Approval, PO Requisition Approval, and PO Create Documents workflows in Purchasing, only one PO Approval Error workflow can be called from the application itself. You can't select a separate customization, like you can with the other workflows in the Document Types window. Therefore, you need to make your customizations to the default workflow. Create a backup to revert to, if you need, while you are testing your customizations.
There are no required modifications you need to make to the PO Approval Error workflow.
Following is a discussion of what you can and definitely cannot modify in the PO Approval Error workflow. For those things you can modify, the discussion includes important guidelines that you need to be careful of when making customizations.
For important information on how to customize workflows, see the Oracle Workflow Developer's Guide.
To further help you with your customizations, refer to the following sections, The PO Approval Error Item Type and Summary of the PO Approval Error Process. These sections describe the components of the notification process in the workflow. If you haven't already, see also: Customization Guidelines.
Attention: If a particular Workflow object does not appear in the following sections on the lists of things you can customize, do not modify it, regardless of its access level.
You can modify the following attributes only, by changing their Default Value:
Timeout Value
Relative Time of Auto Entry for Document Manager
Auto Retry Count for Document Manager
System Administrator User Name
There is one process, "PO Approval Error," in the PO Approval Error workflow, and you can modify it as your business needs require.
You cannot modify the notification in the PO Approval Error workflow. (You could remove it and replace it with your own.)
You can modify any of the messages in the PO Approval Error workflow, as your business needs require.
See: Message Result and To Create a Message.
| Display Name | Description | Type | Length/ Format/ Lookup Type |
|---|---|---|---|
| Timeout Value | Length of time, in minutes, for the notification to automatically close itself. Default value is 0. | Number | |
| Relative Time of Auto Entry for Document Manager | Length of time, in minutes, processes will have to wait before getting picked again. Default value is 0. | Number | |
| Auto Retry Count for Document Manager | Number of attempts to get document manager for approval. Default value is 0. | Number | |
| System Administrator User Name | Application user (typically the System Administrator) who will receive notifications for document manager-related errors in status 1 and 2. This must be defined manually as a valid UserID name in the system. | Text | 30 |
Once the document is submitted for approval, the Approval Workflow is launched and the various activities of the workflow are executed. Typically a PO Approval workflow activity makes a call to the Document Approval Manager and the Document Approval Manager returns an error causing this activity to fail. As soon as an activity fails due to Document Approval Manager Error, workflow will spawn another process for the PO Approval Error (POERROR) item type.
This new spawned POERROR process submits the document for approval only if the Document Approval Manager errors. The value of the POERROR workflow item attribute RETRY_COUNT determines the number of times this process will try to process the document. If at the end of all the attempts, the document is still in error, a notification is sent to the user name specified for the POERROR Workflow item attribute SYSADMIN_USER_NAME.
The notification sent to SYSADMIN_USER_NAME has an option of Retry, to allow the System Administrator to resubmit the document for approval after taking corrective action. If no action is taken on this notification, the notification times out based on the value defined by the attribute TIMEOUT_VALUE. If the notification is timed out, the document is submitted for approval once again. When the document is submitted for approval in this manner and fails again due to Document Approval Manager Error, the entire process is repeated.
Limitations
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).
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.
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.