Generating audit event groups

Audit event groups work in a similar fashion to application context. You can also nest a series of application contexts within an audit event group or nest a series of audit event groups within an application context.

OpenEdge generates a new audit event group record with each call to the BEGIN-EVENT-GROUP( ) method on the AUDIT-CONTROL system handle. When you want to end the scope of the current audit event group, call the END-EVENT-GROUP( ) method.

The syntax for these methods follows:

Syntax

grp-id = AUDIT-CONTROL:BEGIN-EVENT-GROUP 
                       (audit-event-ctx[ , event-detail[ , user-data]])
 
logical = AUDIT-CONTROL:END-EVENT-GROUP( )

The grp-id is an audit event group ID that is a UUID returned as a Base64 character value (with pad characters removed). This audit event group ID is recorded in all audit event records until the event group context is changed or ended. Each invocation of the BEGIN-EVENT-GROUP( ) method generates a new audit event group ID that replaces the previous one in all subsequent audit event records. Thus, only one audit event group can be active at a time and no nesting of audit event groups is possible.

The input parameters to BEGIN-EVENT-GROUP( ) are all character values that allow you to specify different levels and types of detailed information about the audit event group context, as appropriate for the application. The first, required, parameter specifies an alternate index to the audit event record. So, its length is limited to the maximum size of an index value. Thus, you can use this value as a key for reporting purposes.

If you want to stop recording any audit event group ID values in audit event records, you must invoke the END-EVENT-GROUP( ) method. You can test its logical value for a successful invocation. At no time does the ABL session ever implicitly invoke the END-EVENT-GROUP( ) method. Therefore, you must ensure that all code paths (especially error handling code paths) end the audit event group correctly. You can also begin another audit event group at any point after ending the current audit event group.

If at any point in the ABL session you need to determine the current audit event group ID, you can examine the value of the EVENT-GROUP-ID attribute on the AUDIT-CONTROL system handle. This attribute returns the Unknown value (?) if no audit event group context is currently active.

The following code fragments show use of these methods and attributes, in this example, creating an audit event group with nested application context:

DEFINE VARIABLE user-task AS CHARACTER NO-UNDO.
DEFINE VARIABLE ctx-id    AS CHARACTER NO-UNDO.
DEFINE VARIABLE grp-id    AS CHARACTER NO-UNDO.
...
user-task = "Salary adjustments".
...
grp-id = AUDIT-CONTROL:BEGIN-EVENT-GROUP 
  ("Payroll app", "tax calculations", user-task).
...
ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT 
  ("Payroll app", "Federal tax calculation", user-task).
...
AUDIT-CONTROL:LOG-AUDIT-EVENT (34122, ctx-data).
...
ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT 
  ("Payroll app", "FICA calculation", user-task).
...
AUDIT-CONTROL:LOG-AUDIT-EVENT (34123, ctx-data).
...
AUDIT-CONTROL:CLEAR-APPL-CONTEXT.
...
AUDIT-CONTROL:END-EVENT-GROUP.
...
IF grp-id <> AUDIT-CONTROL:EVENT-GROUP-D THEN ...

In this example, two application contexts are invoked in sequence for a different series of audit events, and both are nested within the audit event group. You can also invert this nesting, with a single application context nesting a series of audit event groups. The choice depends entirely upon your application design preferences.