Auditing

Setup Requirements

You configure auditing on a per class basis, at the object store level. To set up auditing:

• Enable auditing for the object store. You can examine an ObjectStore object's AuditLevel property to determine whether auditing is enabled. If auditing is disabled, no events are recorded to the audit event log.
• Get an auditable class, represented by a Subscribable object.
• For each event that you want to audit on a class, configure an AuditDefinition object and set it on the class. An AuditDefinition object includes the following properties:
  • The system or custom event to audit. An audited event is represented by an EventClassDefinition object. For a list of auditable events, see Subscribable and Auditable Events.
  • The option to record the source objects (modified, post-event object and original, pre-event object) in the audit record. For more information, see Source Object Persistence.
  • The option to apply a filter expression to the source object of the event, which determines whether the event is audited. For example, a filter expression can test if a property on the source object has changed; if not, the event is not audited. Filter expressions are applied only for successful operations.
  • The option to name an audit definition to associate it with an audit processing client or client function.
  • The option to disable an audit definition that is no longer of interest to an audit processing client.

You can also place multiple AuditDefinition objects for the same event type on a class, such as two audit definitions set on the Document class, both for the update event. For more information, see Configuring Multiple Audit Definitions for the Same Event.

Source Object Persistence

The source object of an audited event (that is, the object that generated the event) can be persisted to the audit log. There are two types of source objects: the modified, post-event object, and the original, pre-event object. The permissions, properties, and content of a modified object reflect the current state of the object, whereas an original object provides a snapshot of the object before the event. By default, both the modified and original objects are persisted in an audit record.

Source modified objects can be persisted for events of type ObjectChangeEvent. You can retrieve a source modified object from the audit event log by getting the SourceObject property of an ObjectChangeEvent object.

If you retrieve an object-valued property from a source original object, the objects referenced (as the value of the object-valued property) are the appropriate objects at the time the event was recorded. However, these objects might have changed since the event. Any method calls to one of these referenced objects are to the object as it currently exists. If the referenced objects have since been deleted, attempts to access those objects result in an Object Not Foundexception.

Source original objects can be persisted for most events of type ObjectChangeEvent. You can retrieve a source original object from the audit event log by getting the OriginalObject property from an ObjectChangeEvent object. Note, however, that you cannot retrieve source original objects from the following events: CancelCheckoutEvent, CreationEvent, DeletionEvent, FileEvent, PublishRequestEvent, and UnfileEvent.

Configuring Multiple Audit Definitions for the Same Event

You can configure multiple audit definitions for the same event type on a class, supporting an environment where multiple applications that require differing auditing criteria can coexist. Typically, audit definitions with duplicate events are distinguished with different filter expressions, accommodating the differing requirements of the applications. When there are multiple audit definitions for the same event type on a class, the same event is audited under different triggering conditions. When the event is triggered on a class instance, Content Engine performs only one audit operation for that event; that is, it uses only one of the audit definitions for that event.

For audit definitions with duplicate events on the same class, the following logic determines which audit definition the Content Engine uses:

1. The audit definition that is enabled. If none are enabled, none are used.
2. If two or more audit definitions are enabled, the audit definition that has the highest ObjectStateRecordingLevel value (the ORIGINAL_AND_MODIFIED_OBJECTS value is the highest) are considered first. Of those audit definitions, the one with no filter expression is used.

   If two or more audit definitions are enabled that have equal ObjectStateRecordingLevel values and have filter expressions, then the first filter expression that returns true is used.

   If all filter expressions return false, this step is repeated at decreasing levels of the ObjectStateRecordingLevel property, with the non-filtered audit definitions taking precedence.

Property Auditing

As an alternative to persisting source objects on an audited event, you can audit individual source object properties, persisting granular information on the event. You can audit individual properties of the source object of an event. For example, if you need type, status, and adjustor information for documents of the Claim class, you can audit the ClaimStatus, ClaimType, and AdjustorID properties. The capability to audit individual properties is especially useful to client applications that collect analytical or historical data, or to any client that does not require all of the data that is contained within the source object of an audited event. Source objects that are recorded in the Event table can result in substantial consumption of large object (LOB) storage.

You can audit properties for events of type ObjectChangeEvent and its subclasses. When you configure an event class for a source object property to be audited, the Content Engine extends the Event table with a column corresponding to the property. When an audited event is triggered on its source object, the Content Engine stores an instance of the event in the table, and copies the value of the property that is audited from the source object to the applicable column in the event instance.

You retrieve an audited source object property from an Event object as you would retrieve any value from an Event object, for example:

String monitoredProperty = myUpdateEvent.getProperties().getStringValue("myMonitoredProperty");

In addition to the basic audit setup requirements, property auditing requires configuration of the event class and the class of the source object, as follows:

1. To audit a custom property, get its PropertyTemplate object.

   To audit a system property, create a new PropertyTemplate object.

2. Using the PropertyTemplate object, create a custom PropertyDefinition object on an event of type ObjectChangeEvent.
3. On the source object class, get the PropertyDefinition object for the property that you want to audit.
4. On the PropertyDefinition object, set the AuditAs property to the PropertyTemplate object that you used to create the custom PropertyDefinition object on the event class.

Whenever possible, use the same data type for the property to be audited and for the custom property on the event where the audited value is stored. For example:

The PropertyDefinition data type of the source object class == the AuditAs property data type == the PropertyDefinition data type of ObjectChangeEvent or subclass.

If necessary, however, you can map audited properties of one data type to event properties of another data type. The following data type coercions are supported: integer to string, date to string, object to string (GUID format), and Boolean to string.

One scenario that requires data type coercions is to audit properties from multiple source object classes, with each audited property mapped to a single property on an event class. For example, you might have a date property on class A and an object-valued property on class B, both of which are audited to the event's propertyZ, a string type. In both cases, the audited values would be converted to strings and stored in propertyZ.

Audit Disposition

Because unregulated auditing can adversely affect server resources, you can enable audit disposition to automate deletion of event records from the audit log. Audit disposition is a subsystem for automatic deletion of audited events in the Content Engine audit log (Event table). Audit disposition runs as a background thread within the Content Engine. It is recommended that you use this feature for prolonged periods of auditing, especially if you persist source objects to the audit log.

An administration client application can configure the audit disposition thread with the following classes:

• CmAuditingConfiguration sets the disposition schedule, which is defined through one or more CmTimeslot objects, which specify when and how long disposition occurs. A CmAuditingConfiguration object can be assigned to objects of the server hierarchy (Domain, Site, VirtualServer, and ServerInstance.)
• CmAuditDispositionPolicy sets the disposition rule, the criteria in which audit records are identified for disposition. One or more CmAuditDispositionPolicy objects can be specified at the object store level.

For an audit disposition thread to run, you need the following objects:

• A CmAuditingConfiguration object that is enabled, and contains one or more CmTimeslot objects.
• At least one enabled CmAuditDispositionPolicy object that is defined on an object store.

If you use CmAuditingConfiguration and CmAuditDispositionPolicy objects, you might, for example, configure the disposition thread to remove update events after three months, and to run in a four-hour time slot that starts at 2 a.m. every Tuesday and Thursday, and in a 48-hour time slot that starts at 12 a.m. every Saturday.

Setting Bookmarks

To support efficient operation of audit disposition, and to accurately process records in the audit log, an audit processing client application needs to use the bookmark mechanism that is provided by the Content Engine APIs. Represented by a CmAuditProcessingBookmark object, a bookmark is a leave-off point in the audit log, which indicates the last record that is processed by the audit processing client. When an audit processing client ends a session, it sets its bookmark with an audit sequence number; when it later starts a new session, it retrieves its bookmark and resumes processing at the next audit sequence number.

There can be multiple bookmarks, each reflecting a different audit processing client. Audit disposition considers only records with audit sequence numbers less than the lowest-valued bookmark, with the intention of deleting only audited events that were previously processed by clients.

If your audit processing client neglects to create its CmAuditProcessingBookmark object, audit disposition is controlled solely by the CmAuditDispositionPolicy objects, and unprocessed audited records might get deleted prematurely. If your client neglects to update its CmAuditProcessingBookmark object, the disposition thread might skip previously processed records that are meant to be deleted. If you permanently discontinue running your audit processing client, delete the bookmark that is associated with your client, or request that the Content Engine administrator delete it.