How to create a business entity that supports auditing

Example of an ABL business entity which logs application audit events. The example includes application context and an application event group. Based on the sample code in "OpenEdge Development: ProDataSets".

 In "OpenEdge Getting Started: Core Business Services - Security and Auditing, Appendix A, Audit Data Tables", the entry for "_Audit-event-group" in Table 15 states:
 

"Business entity", "business object" and "data object" are concepts or ideas rather than implemented features of the OpenEdge ABL. They come from the OpenEdge Reference Architecture (OERA). For more information about OERA, see OpenEdge Getting Started: Guide for New Developers, Chapter 2, "Understanding OpenEdge Reference Architecture" and the Progress Community OpenEdge Architecture Group at https://community.progress.com/community_groups/openedge_architecture/default.aspx.

One example of a business entity in the OpenEdge documentation is the OrderEntity.p procedure that is developed in "OpenEdge Development: ProDataSets, Chapter 10, Advanced Update Operations > Building a business entity procedure to support the ProDataSet". This procedure defines temp-tables and a dataset to hold orders, orderlines, and related items from the corresponding tables in the Sports2000 sample database, which represents all the data for a complete "order" data object. Then it adds code to do all the operations one would need to do with an order, making it a complete "business object". Although the "object-oriented" features of ABL such as classes are a good fit for this type of task, it is not necessary to use them; this simple example of a "business object" was implemented as an ordinary procedure. The code is available in the OpenEdge documentation download, in the directory src/prodoc/prodatasets. All the source files included or run within OrderEntity.p are also in this directory. The sample code can also be downloaded from https://community.progress.com/community_groups/openedge_general/w/openedgegeneral/1162.download-11-0-documentation-example-procedure-and-sample-files.aspx.

The OrderEntity.p business entity as included in the documentation does not implement auditing. The procedure Order EntityWithAuditing.p in the attached file 000012679.zip adds code to audit order modification events that require special handling (those coded in internal procedure ttOlineModify). In this example there is only one event, the application of a quantity discount; the discount is increased by 20% when the order quantity is doubled.. However, the single auditing context is placed in a group of one event to demonstrate how audit event groups are used. Note that database updates are audited without any special code when auditing is enabled in the database and the audit policies specify that updates to the table are audited.

In addition to OrderEntityWithAuditing.p, 000012679.zip contains:

• _aud-event.ad: This is an event definition file that can be imported into an audit-enabled copy of the Sports2000 sample database to define the events used in OrderEntityWithAuditing.p.
• _audit-policies.xml: This is an audit policy file that can be imported into an audit-enabled copy of the Sports2000 sample database to enable the events used in OrderEntityWithAuditing.p.
• dsOrderWinAdvWithAuditing.w: This is a GUI procedure, based on dsOrderWinAdv.w from the ProDataSets documentation example. It can be used to change quantites and discounts in order lines, to demonstrate how OrderEntityWithAuditing.p works.

To configure auditing as needed for running dsOrderWinAdvWithAuditing.w, perform the following steps:

1. Unpack 000012679.zip into the OpenEdge work directory 
2. Create a copy of the Sports2000 sample database in the OpenEdge work directory.
3. Enable the database for auditing using the instructions in OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 9, "Configuring OpenEdge Auditing > Getting started > Enabling an OpenEdge database for auditing".
4. Import events from _aud-event.ad:
   1. Open the GUI Procedure Editor, Data Dictionary tool or Data Administration tool.
   2. Connect the audit-enabled copy of Sports2000.
   3. From main menu, select Tools > Audit Policy Maintenance.
   4. From the main menu, select File > Events Maintenance....
   5. In the Events Maintenance dialog, click Import, navigate to _aud-event.ad and click OK.
   6. An alert-box message stating that 2 records were imported will display. Click OK to dismiss the message.
   7. The imported events can now be seen in the Events Maintenance browse. Click the window close button or select File > Exit from the main menu.
5. Import the attached _audit-policies.xml file using the Audit Policy Maintenance tool. See article  What is the best way to move audit policies from one database to another? for instructions.

To generate audit events using the example code:

1. Open the GUI Procedure Editor.
2. Connect the Procedure Editor to the audit-enabled copy of Sports2000.
3. Add the src/prodoc/prodatasets directory from the OpenEdge documentation download to the Propath.
4. Run dsOrderWinAdvWithAuditing.w.
5. In the "Order Num" fill-in, enter "1" and press Tab. The second row of fill-ins and the order line grid will be populated with data for order number 1.
6. In the order line grid, change the quantity from 30 to 60 click Save Changes. The discount will increase from 10% to 12%, reflecting the quantity discount increase that will be audited.

​To see the audit records that are generated, choose "Database > Reports > Auditing Reports > Custom Audit Data Filter Report" from the Data Administration tool main menu and filter on events from 32000 to 32001. See OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 13, "Querying and Reporting on Audit Data > Generating a custom filtered report" for detailed instructions.

The dsOrderWinAdvWithAuditing.w example program, the Audit Maintenance tool, and the GUI Data Administration tool can only be run on Windows. However, all the underlying audit functionality in the database, and the example business entity OrderEntityWithAuditing.p, can run on a Unix system as well.

References to Other Documentation:

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 9, "Configuring OpenEdge Auditing > Getting started"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 9, "Configuring OpenEdge Auditing > Setting up OpenEdge auditing context > Auditing context architecture > Audit-event group"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 9, "Configuring OpenEdge Auditing > Setting up OpenEdge auditing context > Recording auditing context information"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 9, "Configuring OpenEdge Auditing > Setting up OpenEdge auditing context > How auditing context is referenced by audit event records"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 13, "Querying and Reporting on Audit Data > Audit data querying and reporting > Logically grouping related audit data in an audit event group"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 13, "Querying and Reporting on Audit Data > Audit data querying and reporting > Query guidelines"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Chapter 13, "Querying and Reporting on Audit Data > Generating a custom filtered report"

OpenEdge Getting Started: Core Business Services - Security and Auditing, Appendix A, "Audit Data Tables > Audit data table schema > Table 15: _aud-audit-data table > _Audit-event-group"

OpenEdge Development: Programming Interfaces, Chapter 5, "Auditing > Recording application events"

OpenEdge Development: ABL Reference, "Handle Reference > AUDIT-CONTROL system handle"

OpenEdge Development: ProDataSets, Chapter 10, "Advanced Update Operations > Building a business entity procedure to support the ProDataSet"

OpenEdge Development: ProDataSets, Chapter 11, "Data Access and Business Entity Objects"

OpenEdge Getting Started: Guide for New Developers, Chapter 2, "Understanding OpenEdge Reference Architecture"

Progress Community OpenEdge Architecture Group
https://community.progress.com/community_groups/openedge_architecture/default.aspx

Progress Articles:

 What is the best way to move audit policies from one database to another?
 How to report on audited data?