Audit History in Order Management

An Oracle WhitePaper

November 2010

Oracle Order Management enables you to audit the changes in order attributes from the Sales Orders, Quick Sales Order, Order Organizer, Quick Order Organizer forms or Process Order API. This is achieved by utilizing the Processing Constraints framework, OM Lookups, an OM system parameter and the Audit Trail Consolidator concurrent program. Order Management application gives the flexibility to audit only the required attributes based on the business requirements.

Each business can decide what order attributes are critical and an audit needs to be maintained. Queries can be run or reports produced to show what actual changes have been made to auditable attributes, who made the changes and when.

The attributes of the following entities can be audited: Order Header, Order Line, Order Sales Credit, Order Line Credit, Order Price Adjustment, Line Price Adjustment.

Audit History Data Model

Audit History functionality uses the following tables that store history information about fields (attributes) from Order Header, Order Line, Price Adjustments and Sales Credit.OE_ORDER_HEADER_HISTORY - Table that stores history of attribute change for Order HeadersOE_ORDER_LINES_HISTORY - Table that stores history of attribute change for Order LinesOE_PRICE_ADJS_HISTORY – Table that stores history of attribute changes of Entity Price.OE_SALES_CREDIT_HISTORY - Table which stores history of attribute changes of Entity Sales Credits

When OM system parameter: Audit Trial is enabled and proper processing constraints are defined for the auditable attributes, the relevant history tables are populated with the history data.OE_AUDIT_ATTR_HISTORY - Table which holds the consolidated history data in a format needed for viewing and reporting history. This table is populated with the history data by Audit History Consolidator concurrent program.

OE_AUDIT_ATTR_DESC_V - internal view that returns consolidated history data in a format needed for viewing and reporting history. OE_PC_ENTITIES_V –internal view used by Audit History Consolidator program to select entity ids that requires history consolidation. OE_PC_ATTRIBUTES_V – internal view used by Audit History Consolidator program to select audited attributes that requires history consolidation.

OE_LOOKUPS - view which returns the Order Management QuickCodes values from base table FND_LOOKUP_VALUES.

All the Audit History related calls are within OE_AUDIT_HISTORY_PVT package (OEXPPCHB.pls). This is a private API.

Setup and simple test cases with Audit History

It is assumed that you have access to a Vision instance, version 11.5.10 or comparable training instance. In order to use the Audit History functionality, it is necessary to do the following:

1. Setup Processing Constraints 2. Create Lookups (in the case you need to capture the reasons for change the

value of the audited fields). This is an optional step. 3. Enable Audit Trial system parameter4. Add function security View Audit History on the application menu for the

responsibilities that need to view Audit History form. 5. Enter and process sales orders as usual.6. Submit Audit History Consolidator concurrent program (OEXAUGEN)7. Run Audit History Report (OEXAUDHR.rdf) or query the Audit History

window (OEXAUDHF.fmb) in order to see the changes of audited attribute.

1. Setup Processing Constraints

Define new processing constraints that specify when, and for what attributes of an order, audit trail updates are recorded, having the appropriate action: a) Required Reason and Historyb) Require Historyc) Require Reason, History and Raise Integration Events*

a) If the option Requires Reason and History is selected: when the field is changed, a reason window will always appear and a reason code must be entered. History will be captured.b) If the option Requires History is selected, a reason window will not appear when making a change and history will be captured. There is always the flexibility of entering a reason code by navigating to Tools > Change Reason.c) If the option Require Reason, History and Raise Integration Events is selected:when the field is changed, a reason window will always appear and a reason code must be entered. History is captured but is not consolidated in the table OE_AUDIT_ATTR_HISTORY and, therefore, the changes will not be displayed in Audit History form or Audit History Report.

Also, an integration event will be raised: oracle.apps.ont.oi.xml_int.status. This event is presently used by XML processing and can be used by any other product. Important:Actions of Requires History and Requires Reason and History for Audit Historyare supported for UPDATE operation.2. Define Lookups for the Reasons used (for the case where you choose Required Reason and History option). This is optional. Navigation: OM responsibility > Setup > QuickCodes > Query for lookup type: CANCEL_CODEApplication: Order ManagementMeaning: Cancel/Audit/Versioning ReasonsIn this form, you can add new Reason Codes based on your business requirements or you can use the existing ones.

Figure 1 – OM Lookups where the Reason Codes are defined

Here you can define additional reason codes based on your business requirements. These Reason Codes are available in the list of values from Reason window (see the testcase2: Figure 16 – Reason window with reason code and comment). The lookup codes are stored in the table FND_LOOKUP_VALUES and can be found with the following query:SELECT * FROM FND_LOOKUP_VALUES WHERE lookup_type = 'CANCEL_CODE' and view_application_id = 660 order by lookup_code;

3. Setup the OM System parameter: Audit TrailNavigation: OM responsibility > Setup > System Parameters> ValuesThe audit trail parameter is used in order to capture audit history at either order entry or booking. The possible values are: Disable – no audit history is recordedEnable when Order is Entered or Enable when Order is Booked.

Figure 2 – Audit Trial system parameter

After Audit Trial system parameter and appropriate processing constraints are enabled, the history tables are populated with the audited data. Currently, there is no purging routine available to purge the data from the history tables.

4. Add the function View Audit History on the application menuUnder System Administrator responsibility > Application > MenuQuery for the menu associated with the user’s responsibility. For example, in a Vision Instance, under the Order Management SuperUser, Vision Operations(USA) responsibility, the menu is ADS_OM_SUPERMENU. In the submenu ONT_SALES_ORDERS, there is the function security View Audit History.

Figure 3 – Function View Audit History added to the submenu ONT_SALES_ORDERS

5. Enter and process orders as usual.See the test case with the Sales Orders and an example of audited attribute.

6. Run the Audit History Consolidator concurrent program. In order to consolidate order audit trail history via the concurrent program use the following navigation path:OM responsibility >Requests> Submit a new request> choose from the list of values Audit History Consolidator

Figure 4 – Parameters of Audit History Consolidator

Enter the History Date From. This field is optional.Enter the History Date To.This field is optional.Enter the Order Number From. This field is optional.

Enter the Order Number To. This field is optional.Enter a numeric value in the Changes in Last N days field to capture audit historychanges captured over a period of days. For example, if you wish to consolidate order changes captured for audit purposes during the last 7 days, enter the value 7.Select OK, and then submit the concurrent request.

The Audit History Consolidator concurrent program, when submitted, populates anOrder Management table (OE_AUDIT_ATTR_HISTORY) with consolidated audit trail details recorded for orders and lines. Each subsequent submission of the program updates any additional order audit trail details that have been captured since the previous successful submission of the program.

Order Management consolidates the following order entities within the table:• Order Header• Order Line• Sales Credit (Order and Line)• Price Adjustment (Order and Line)The data within the table can be viewed within Oracle Applications via the View Audit History window or printed for display via the Audit History Report.Note: In Release 11i, when running Audit History Consolidator based on the history date or order number parameter, the concurrent program will consolidate all the audit data present in all operating units. In Release 12,a new parameter called Operating Unit is available so that audit data can be consolidated based on Operating Unit also. This feature is not available in Release 11i.

7. Query Audit History form (OEXAUDHF.fmb) or run Audit History Report (OEXAUDHR.rdf).

The Audit History form is available if the function View Audit History (ONT_OEXAUDHF_FORM) is added on the menu attached to the user’s responsibility.

This form consists of a Find window and a Results window. The Audit History Results window displays the following 6 tabs, which display the following order or line attributes:Tabs: Orders, Order Sales Credits, and Order Price Adjustments Tabs display the attributes:• History Date and Time• Order Number• Attribute Name• Old Value• New Value• User

Tabs: Lines, Line Sales Credits, and Line Price Adjustments Tabs display the attributes:

• History Date and Time• Order Number• Line Number• Item• Attribute Name• Old Value• New Value• User

History data displayed by Audit History Report is illustrated in Figure 14 - Output of Audit History Report

Figure 5 – The parametes of Audit History Report

The Audit History report has a mandatory parameter: History Date(From).The other input parameters are optional. If you leave any of the non-required parameters blank, this report displays the history changes of all attributes. However, it is recommended to run this report at least with History Date (From), Entity Name and Attribute Name input parameters in order to reduce report processing run times.Important: Audit History tracks the changes on order attributes when they are produced on Sales Order, Quick Sales Orders, Order Organizer or Quick Order Organizer forms. If the audited attributes are updated through SQL Plus, Audit History cannot capture this change.

Test cases to demonstrate the Audit History functionality

Test case1: tracking changes of the salesperson field from the Sales Orders form, header level (record the changes without specifying a reason code).

Assumption: You must have access to an Oracle Application 11.5.10 Vision database or comparable training or test instance at your site. 1. Enable the Require History option in Processing Constraints form, for the field Salesperson from Sales Order form, Header level.

Navigation: OM responsibility > Setup> Rules>Security>Processing Constraints

Figure 6- Processing Constraints form with the setup for Salesperson field

Important: In the case the Audit History is not captured even though Require History constraint is dened, check if there is a versioning constraint for the same operation. Versioning takes precedence and version is captured instead of the audit record.Example: You have processing constraints defined for:• Update of Salesperson with action Require History• Update of Salesperson with action Generate VersionThe versioning will take precedence.

2. Go to the Sales Order form:Navigation: OM responsibility > Orders, Returns > Sales Orders form.

Create a new sales order and set a value in the field Salesperson. Save the change.

Figure 7 – Sales Order header form with the original value of the Salesperson

3. After you saved the Sales Order, try to change the value of the Salesperson field from Albert Apex to Ambers, Ralph. Save the changes.

Figure 8 – Sales Order header with the changed value of the field Salesperson

4. Run Audit History Consolidator concurrent program for the changes from the last days. Navigation: OM responsibiliyt > Requests> Submit a new requestChoose from the list of values: Audit History Consolidator

5. Query Audit History form based on the desired criteria. Navigation: OM responsibility > Orders, Returns> View Audit HistoryYou must select a value in the Entity field prior to selecting any value in the Attribute field.

Figure 9 – The query criteria in the Audit History form

The result is as follows :

Figure 10 – The recorded changes of the Salesperson field

The system recorded the old value of the field Salesperson and the new value. The username who operated the changes is MFG.

Note: The Audit History window currently does not support the use of Folders to customize display information.

If a new change is operated in the same field, for example, from Ambers, Ralph to a new salesperson : Gregory Donaldson, this new change will be recorded too.

Figure 11 – The Sales Order form with the third change of the Salesperson field

6. Make sure that you run the Audit History Consolidator program prior to query the Audit History form to see the results. The Audit History form displays the attribute changes operated untill the latest run of Audit History Consolidator concurrent program.

7. See the new results in Audit History form:

Figure 12 – the new results of the recorded changes in Salesperson field from Sales Order form

Alternatively, the audit history data can be viewed by running the report Audit History Report . Navigation : OM responsibility > Reports, Requests> Run Reports > choose from the list of values Audit History Report

Figure 13 – Audit History Report parameters

The output of this report shows the following:

Figure 14 – Output of Audit History Report

The report output is always sorted by effectivity date changed, order number, entity, and attribute. Also, the report displays the responsibility name associated with the user who changed the audited attribute.

Test case: tracking changes of the salesperson field from the Sales Orders form, header level (record the changes by specifying a reason code).

1. In the case the Require Reason and History option is selected in Processing Constraints ( see Figure 6- Processing Constraints form with the setup for Salesperson field), any change on the audited attribute requires a Reason Code.

2. In the Sales Orders form, when trying to modify the value from Salesperson field at header level and save the change, the following window will be opened, requiring to enter a Reason Code:

Figure 15 – Reason window is automatically opened when trying to save the changed value

3. After entering a reason code(mandatory) and a comment (optional), the change of the Salesperson field is allowed.

Figure 16 – Reason window with reason code and comment

Press OK and then save the changes in Sales Orders form.

4. Run Audit History Consolidator concurrent request.

5. Go to Audit History form and see the new history results:

Figure 17 – Audit History form with the recorded reason code and comment

Also, the same data can be viewed in the Audit History Report Navigation :

OM responsibility > Reports, Requests> Run Reports > choose from the list of values Audit History Report

Figure 18 – Audit History Report showing the Reason Code and Comment

Note: If the order number has more than 10 characters (like in the example below for SO 100000000000) then the order number in the Audit History Report is displayed as *********.

Figure 19 - Audit History Report for a sales order number with more than 10 characters.

Investigating issues with Audit History

1. Check the version of the following files: OEXAUDHR.rdf, OEXPPCHB.pls , OEXPPCHS.pls and OEXAUDHF .fmb using the following commands in Unix:

strings -a $ONT_TOP/reports/US/OEXAUDHR.rdf | grep -i '$Header'

strings -a $ONT_TOP/patch/115/sql/OEXPPCH*.pls | grep '$Header'

strings -a $ONT_TOP/forms/US/OEXAUDHF.fmx | grep -i '$Header'or run the concurrent request of Diagnostics: AppsCheck for Order Management.2. Check Note 453944.1:Order Management Cumulative Patches for 11.5.9 & 11.5.10for the latest rollup OM patches that include bug fixes for Audit History functionality.3. Search Knowledge Base for a similar issue.4. Raise a Service Request with Oracle Support.

Known issues with Audit History

BUG 8681001 : AUDIT HISTORY ORDERED QTY HAS DUPLICATE RECORDS FROM DIFFERENT DATESSolution: Download and review the readme and pre-requisites for Patch 8780150Confirm the following file versions:OEXPPCHB.pls 115.43.11510.20Retest the issue.(per note 958654.1)

Bug 8637771 - AUDIT TRAIL ASSISTANCE FOR THE CALCULATE PRICE FLAG ON ORDER LINESSolution: Download and review the readme and pre-requisites for Patch 8637771 - After applying this patch the old values of calculate price flag will be shown correctly in view audit history form.Confirm the following file versions:OEXVCHGB.pls, version 115.40.11510.3OEXVCHGS.pls, version 115.9.11510.15. Retest the issue(per note 864899.1 ).

Bug 5546660: FP 11I9 - 11I10: AUDIT HISTORY CONSOLIDATOR PERFORMANCESolution: 1. Download and review the readme and pre-requisites for Patch 7694994 .2. Ensure that you have taken a backup of your system before applying the recommended patch.3. Apply the patch in a test environment.4. Confirm the following file versions:OEXPPCHB.pls, version 115.43.11510.105. Retest the issue. (per note 864886.1 )

BUG 8206655 - AUDIT HISTORY CONSOLIDATOR PROGRAM HAS PERFORMANCE ISSUESSolution: . Download and review the readme and pre-requisites for Patch 8206655 .2. Ensure that you have taken a backup of your system before applying the recommended patch.3. Apply the patch in a test environment.4. Confirm the following file versions:OEXPPCHB.pls-115.30.1159.31OEXPPCHS.pls-115.5.1159.45. Retest the issue ( per note 861358.1 )

BUG 6120595 - CODE FIX: AUDIT HISTORY FAILING WITH THE UNIQUE INDEX VIOLATIONSolution : To implement the solution, please execute the following steps:

1. Download and review the readme and pre-requisites for Patch 61205952. Ensure that you have taken a backup of your system before applying

the recommended patch.3. Apply the patch in a test environment.4. Confirm the following file versions:

-> patch/115/odf/onttab.odf 115.176.11510.13-> patch/115/sql/OEXPPCHB.pls 115.43.11510.16-> patch/115/sql/OEXPPCHS.pls 115.6.11510.3

5. Use the following commands to confirm the file versions 6. strings -a $ONT_TOP/patch/115/odf/onttab.odf | grep '$Header' strings -a

$ONT_TOP/patch/115/sql/OEXPPCH*.pls | grep '$Header' .7. Migrate the solution as appropriate to other environments.

(per note 550048.1 )

Bug 5643494 -CONCURRENT REQUEST AUDIT HISTORY CONSOLIDATOR/REPORT ARE RUNNING TOO LONGSolution: To implement the solution, please execute the following steps:1. Download and review the readme and pre-requisites for Patch 57415922. Ensure that you have taken a backup of your system before applyingthe recommended patch.3. Apply the patch in a test environment.4. Confirm the following file versions:OEXAUDHR.rdf 115.20.11510.65. Retest the issue.(per note 406506.1 )

BUG:4381559 - Oexaugen - Audit History Consolidator Running Long After Upgrade To 11.5.10Solution: To implement the solution, please execute the following steps:1. Please download and review the readme and pre-requisites for Patch 4381559.2. Please ensure that you have taken a backup of your system before applying the recommended patch.

3. Please apply the patch in a test environment.4. Please confirm the following file versions:OEXPPCHB.pls version 115.43.11510.5(per note 388543.1 )

Currently, the following Enhancement Requests are logged for Audit History:Enhancement Request 8432688 - CANNOT CAPTURE NEW LINES ON A BOOKED ORDER IN AUDIT HISTORY

Enhancement Request 7175989 - AUDIT HISTORY CONSOLIDATOR PROGRAM IS NOT MULTI-ORG COMPLIANT

Enhancement Request 5856222 - VIEW AUDIT HISTORY FORM DOES NOT ALLOW FOR QUERYING ON ORDER LINE.

Enhancement Request 5742201 OEXOEOED - HEADING CHANGE TO CANCELLATION HISTORY INSTEAD OF QUANTITY HISTORY

Enhancement Request 5750573 OEXOETEL NEED NEW FIELD FOR ORIGINAL ORDERED QUANTITY

Enhancement Request 5354630 AUDIT HISTORY SHOULD ALSO TRACK RECORD CREATE OPERATION

Enhancement Request 5331260 ORDER LINE REASON AND COMMENTS ARE NOT AVAILABLE TO VIEW AFTER THEY ARE SAVED

Enhancement Request 5042192 REASON HISTORY FOR ORDER LINE WASN'T MADE WHEN CHANGING SHIPMENT PRIORITY

Enhancement Request 4238210 REQUIRE LINE NUMBER AS SEARCH CRITERIA TO VIEW AUDITHISTORY FORM

Enhancement Request 3637457 USE ORDER TYPE AS PARAMETER FOR AUDIT CONSOLIDATOR REQUEST

Enhancement Request 3570433 UPGRADE THE FUNCTIONALITY OF VIEW AUDIT HISTORY FORM

Enhancement Request 3434435 CHANGES TO ATTRIBUTES ARE NOT PROPERLY DISPLAYED IN OEXAUDHF

Enhancement Request 3172693 NEED TO CAPTURE MULTIPLE REASON CODE/COMMENTS ENTERED FOR AUDIT HISTORY

Enhancement Request 2875558 OEXAUDHF, AUDIT REPORT/FORM LOVS DISPLAY DESCRIPTIVE FLEXFIELD ATTRIBUTEXX

Audit History in Order ManagementAuthor: Marian StanPrincipal Technical Support AnalystGlobal Software Support

Special thanks to Chidananda Pati, Project Leader in Order Management Development for the help in reviewing this whitepaper.

Oracle CorporationWorld Headquarters500 Oracle ParkwayRedwood Shores, CA 94065U.S.A.Worldwide Inquiries:Phone: +1.650.506.7000Fax: +1.650.506.7200www.oracle.comCopyright © 2008, Oracle and/or its affiliates. All rights reserved.

This document is provided for information purposes only and the contents hereof are subject to change without notice.This document is not warranted to be error-free, nor subject to 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. We specifically disclaim 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 our prior written permission.Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.