Logically group related audit data in an audit event group

Audit event groups (_Audit-event-group) provide another means for applications to group related audit data according to specific application requirements, such as to group all audit data related to a specific business entity, task, or workflow, for example. Audit event groups have starting and ending events that can be used to establish a collection of related audit events that could span multiple databases (as each database that has the audit event group enabled through policy will receive the audit event group record).

ABL statements used to create and clear audit event groups are AUDIT-CONTROL:BEGIN-EVENT-GROUP and AUDIT-CONTROL:END-EVENT-GROUP. These work much the same way as the setting and clearing of application context. In SQL, the statement is AUDIT SET EVENT_GROUP passing in a string or NULL to clear it.

When the audit event group is set, a complete audit record will be created recording the details of the audit event group against the audit event group event ID 31999. The value of the _Audit-data-guid identifying field value for this event group audit data record will then be set in the _Audit-event-group field of all subsequent audit data records until the event group is cleared. It is, therefore, the responsibility of the application to correctly set and clear the audit event group at appropriate points. Be extremely careful to handle errors appropriately, and ensure that the resetting of the event group does not get skipped due to an error condition.

In order to report on the details of the audit event group, a secondary read back into the audit data table will be required, locating the audit data record where the _Audit-data-guid value matches the _Audit-event-group value.

In the event group record itself, the fields that could contain data passed in from the application and supported through the API are the following three character fields: _event-context, _event-detail, and _Audit-custom-detail. Other fields, such as the user or date and time, for example, will also be populated as normal.

Using the _Audit-event-group field itself makes it possible to read all audit data that resulted from the same event group.