Auditing Concepts

Auditing is the tracking of events (operations) that occur on Content Engine classes. Most events on Content Engine classes can be audited. If configured for auditing, Content Engine creates event objects that are stored in an audit log (the Event table in the object store's database). From an event object, you can get the creation date, originating user, result status, source object of the event, and other information.

NOTES

This topic provides an overview of auditing functionality: auditing setup requirements, auditable classes and events, and source object persistence to the audit log. For auditing code samples, see Working with Auditing-related Objects. For information on auditing as implemented in the Enterprise Manager, see Concepts: Audit Logging.

Auditing Setup Requirements

You can enable and configure auditing through the Content Engine API as described here, or with the Enterprise Manager. Auditing is enabled at the object store level; you can examine an ObjectStore object's AuditLevel property to determine if auditing is enabled. If auditing is disabled, no events are recorded to the audit event log.

Specific auditable events are configured on a per-class basis, represented by a SubscribableClassDefinition object. Audit configuration information is described in an AuditDefinition object, with properties that specify:

You can set and get the values of these properties by calling accessor methods on the AuditDefinition object.

Auditable Classes and Events

The following table lists the auditable Content Engine classes; that is, system and custom events triggered on instances of these classes can be audited. Subclasses of these classes are also auditable. You can retrieve audit history information on instances of these classes by getting an object's AuditedEvents property, or by performing a query on the audit log.

Action ActionConsumer Annotation ChoiceList ClassDefinition
ComponentRelationship Containable IndexArea Link PropertyTemplate
PublishRequest Relationship StorageArea StoragePolicy SecurityPolicy
Subscribable VersionSeries

The next table lists and describes the Content Engine events that you can configure for auditing. It also lists classes whose instances can trigger audited events. Note that subclasses of the listed classes behave in the same way. For example, a CancelCheckoutEvent event can be triggered by CodeModule, PublishTemplate, WorkflowDefinition, and XMLPropertyMappingScript objects as well as by the parent Document object.

Event Logged when Triggered by
(subclasses of listed classes also apply)
AuditConfigurationEvent auditing configuration of an object store is changed. ObjectStore

NOTE Instances of AuditConfigurationEvent cannot be administered via AuditDefinition objects. These audits always occur regardless of the AuditLevel property value of an ObjectStore.

CancelCheckoutEvent a reservation on a document is canceled. Document
ChangeClassEvent the class of an object is changed. Annotation, CustomObject, Document, DocumentClassificationAction, DocumentLifecycleAction, DocumentLifecyclePolicy, EventAction, Folder, Link, ReferentialContainmentRelationship, Subscription
ChangeStateEvent the lifecycle state of a document is changed. Document
CheckinEvent a document is checked in. Document
CheckoutEvent a document is checked out. Document
ClassifyCompleteEvent a document has been processed by a classifier. Document
CreationEvent an instance of a class is created and saved. All auditable classes listed above in this table
CustomEvent a user-defined event is raised. Subscribable
DeletionEvent an object is deleted from the object store. All auditable classes listed above in this table
DemoteVersionEvent a document is demoted to a minor version. Document
FileEvent an object is filed in a folder (includes creating a subfolder). Folder
FreezeEvent the freeze method is called on an object. Document
GetContentEvent the content of a content-carrying object is retrieved. Document
GetObjectEvent an object is retrieved. All auditable classes listed above in this table
LockEvent the lock method is called on an object. Document, Folder, CustomObject
PromoteVersionEvent a document is promoted to a major version. Document
PublishCompleteEvent a document-publishing request has completed. Document
PublishRequestEvent a request has been made to publish or republish a document. Document
QueryEvent a query is performed. All auditable classes listed above in this table except VersionSeries
UnfileEvent an object is removed (unfiled) from a folder (includes deleting a subfolder). Folder
UnlockEvent the unlock method is called on an object. Document, Folder, CustomObject
UpdateEvent an object's properties are changed. All auditable classes listed above in this table
UpdateSecurityEvent the security of an object is changed (which includes changes to owner and permissions with the appropriate properties modified). All auditable classes listed above in this table except ReferentialContainmentRelationship and VersionSeries

Source Object Persistence

The source object of an audited event (that is, the object that generated an 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 prior to the event. By default, both the modified and original objects are persisted in an audit record.

NOTE Persisting audited modified and original objects in a database can result in substantial consumption of large object (LOB) storage. To control the size of audited records in a database, use the AuditDefinition.ObjectStateRecordingLevel property to specify the level of object persistence 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 from an ObjectChangeEvent subobject.

Source original objects can be persisted for most events of type ObjectChangeEvent. The ObjectChangeEvent subobjects listed below provide the OriginalObject property for retrieving the original object.

ChangeClassEvent ChangeStateEvent CheckinEvent CheckoutEvent ClassifyCompleteEvent
CustomEvent DemoteVersionEvent FreezeEvent LockEvent PromoteVersionEvent
PublishCompleteEvent TakeFederatedOwnershipEvent UnlockEvent UpdateEvent UpdateSecurityEvent

If you retrieve an object-valued property from a source original object, the objects referenced (as the value of the object-valued property) will be 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 will be 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 Found" exception.