Obsolete Pages{{Obsolete}}
The official documentation is at: http://docs.alfresco.com
Core Repository ServicesAuditing
Auditing (from V3.4)
Audit Filter
This page describes how Alfresco may be used to audit actions performed on your content and folders. A Technical Description is followed by examples of how the standard configuration may be customized.
The 4.0 nightly community build, contains an audit data producer and configuration to report actions performed against user content and folders. These actions are be at a level high enough to allow one to follow who has viewed, modified or deleted content.
Building on the auditing architecture (described in Auditing (from V3.4)) the data producer org.alfresco.repo.audit.access.AccessAuditor gathers together lower events into user recognisable events. For example the download or preview of content are recorded as a single read. Similarly the upload of a new version of a document is recorded as a single create version. By contrast the AuditMethodInterceptor data producer typically would record multiple events.
A default audit configuration file located at <alfresco.war>/WEB-INF/classes/alfresco/audit/alfresco-audit-access.xml is provided that persists audit data for general use. This may be enhanced to extract additional data of interest to specific installations. For ease of use, login success, login failure and logout events are also persisted by the default configuration.
Default audit filter settings (see Audit Filter) are also provided for the AccessAuditor data producer, so that internal events are not reported. These settings may be customized (by setting global properties) to include or exclude auditing of specific areas of the repository, users or some other value included in the audit data created by AccessAuditor.
No additional functionality is provided for the retrieve of persisted audit data, as all data is stored in the standard way, so is accessible via the AuditService search, audit web scripts, database queries and Alfresco Explorer show_audit.ftl preview.
The following is an example audit trail. The user actions from the Share interface were:
Example audit trail
1. /alfresco-access/transaction/action=CREATE
/alfresco-access/transaction/aspects/add=[cm:titled]
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents
/alfresco-access/transaction/properties/add=...
/alfresco-access/transaction/sub-actions=createNode updateNodeProperties addNodeAspect
/alfresco-access/transaction/type=cm:folder
/alfresco-access/transaction/user=admin
2. /alfresco-access/transaction/action=CREATE
/alfresco-access/transaction/aspects/add=[cm:titled, cm:author]
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
/alfresco-access/transaction/properties/add=...
/alfresco-access/transaction/sub-actions=createNode updateNodeProperties readContent createContent updateContent addNodeAspect
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
3. /alfresco-access/transaction/action=READ
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
/alfresco-access/transaction/sub-actions=readContent
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
4. /alfresco-access/transaction/action=updateNodeProperties
/alfresco-access/transaction/aspects/add=[cm:taggable]
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
/alfresco-access/transaction/properties/add=...
/alfresco-access/transaction/properties/from={cm:modified=Mon Jun 13 15:34:05 BST 2011}
/alfresco-access/transaction/properties/to={cm:modified=Mon Jun 13 15:39:35 BST 2011}
/alfresco-access/transaction/sub-actions=updateNodeProperties addNodeAspect readContent
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
5. /alfresco-access/transaction/action=CHECK IN
/alfresco-access/transaction/aspects/add=[cm:versionable]
/alfresco-access/transaction/copy/from/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox (Working Copy).odt
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
/alfresco-access/transaction/properties/add=...
/alfresco-access/transaction/properties/from=...
/alfresco-access/transaction/properties/to=...
/alfresco-access/transaction/sub-actions=updateNodeProperties addNodeAspect createVersion readContent deleteNodeAspect updateContent copyNode checkIn
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
/alfresco-access/transaction/version=2.0
6. /alfresco-access/transaction/action=COPY
/alfresco-access/transaction/aspects/add=[cm:titled, cm:copiedfrom, cm:author, cm:taggable]
/alfresco-access/transaction/copy/from/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Documents/cm:The fox.odt
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Pictures/cm:The fox.odt
/alfresco-access/transaction/properties/add=...
/alfresco-access/transaction/sub-actions=createNode readContent createContent updateNodeProperties addNodeAspect copyNode
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
7. /alfresco-access/transaction/action=DELETE
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:mysite/cm:documentLibrary/cm:My Pictures/cm:The fox.odt
/alfresco-access/transaction/sub-actions=deleteNode
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
The property values have been truncated to '...' as the made the page rather wide.
The audit trail of individual content may be viewed from within Alfresco Explorer. Locate the content and select the option 'Preview in Template', using the show_audit.ftl preview. The following is an example of some high level events.
There is also a Share audit dashlet project in Share Extras on GitHub that displays audit events. The source for the project may be found here and the pre-built jar for the latest release here. Currently, the latest release is 0.55. It may be configured to query, filter and limit the audit entries displayed. The following images show example output and configuration :
Audit-dashlet-configuration-dialog.png
Read the associated README file for more information on installation, configuration, and usage. It supersedes the previous wiki page previously found in Google Code.
To turn on auditing of these events and sub events add the following property to alfresco-global.properties:
Enable the alfresco-access audit application
# Enable audit in general
audit.enabled=true
# Enable the alfresco-access audit application
audit.alfresco-access.enabled=true
# Enable the auditing of sub-actions. Normally disabled as these values are
# not normally needed by audit configurations, but may be useful to
# developers
#audit.alfresco-access.sub-actions.enabled=true
The following properties are set by default to discard events where the user is null or 'System', the content or folder path is under '/sys:archivedItem' or under '/ver:' or the node type is not 'cm:folder', 'cm:content' or 'st:site'. These values result in events only being recorded for common actions initiated by users of the system. These values may be overridden if required.
Default Audit Filter Settings
audit.filter.alfresco-access.default.enabled=true
audit.filter.alfresco-access.transaction.user=~System;~null;.*
audit.filter.alfresco-access.transaction.type=cm:folder;cm:content;st:site
audit.filter.alfresco-access.transaction.path=~/sys:archivedItem;~/ver:;.*
Folder and content changes generate the following audit data structure. Elements are omitted if not changed by the transaction. The /sub-action/<sequence> structure holds cut down details of each sub-action, but are only included if the global property audit.alfresco-access.sub-actions.enabled=true.
Structure of Audit Data
/alfresco-access
/transaction
/action=<actionName>
/sub-actions=
/path=<prefixPath>
/type=<prefixType>
/node=<nodeRef>
/user=<user>
/copy
/from
/node=<nodeRef>
/path=<prefixPath>
/type=<prefixType>
/move
/from
/node=<nodeRef>
/path=<prefixPath>
/type=<prefixType>
/properties
/from=<mapOfValues>
/<propertyName>=<propertyValue>
...
/to=<mapOfValues>
/<propertyName>=<propertyValue>
...
/add=<mapOfValues>
/<propertyName>=<propertyValue>
...
/delete=<mapOfValues>
/<propertyName>=<propertyValue>
...
/aspects
/add=<mapOfNames>
/<aspectName>=null
...
/delete=<mapOfNames>
/<aspectName>=null
...
/version-properties=<mapOfValues>
/sub-action/<sequence>
/action=<actionName>
/copy
...
/move
...
/properties
...
/aspects
...
Example audit data
<pre>
Inbound audit values:
/alfresco-access/transaction/action=MOVE
/alfresco-access/transaction/node=workspace://SpacesStore/74a5985a-45dd-4698-82db-8eaeff9df8d7
/alfresco-access/transaction/move/from/node=workspace://SpacesStore/d8a0dfd8-fe45-47da-acc2-fd8df9ea2b2e
/alfresco-access/transaction/move/from/path=/app:company_home/st:sites/cm:abc/cm:documentLibrary/cm:folder1/cm:Word 123.docx
/alfresco-access/transaction/move/from/type=cm:folder
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:abc/cm:documentLibrary/cm:folder2/cm:Word 123.docx
/alfresco-access/transaction/sub-actions=moveNode readContent
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin
/alfresco-access/transaction/sub-action/00/action=moveNode
/alfresco-access/transaction/sub-action/00/move/from/node=workspace://SpacesStore/d8a0dfd8-fe45-47da-acc2-fd8df9ea2b2e
/alfresco-access/transaction/sub-action/00/move/from/path=/app:company_home/st:sites/cm:abc/cm:documentLibrary/cm:folder1/cm:folder1/cm:Word 123.docx
/alfresco-access/transaction/sub-action/00/move/from/type=cm:folder
/alfresco-access/transaction/sub-action/01/action=readContent
The default audit configuration file alfresco-audit-access.xml only copies the following audit data elements. It also adds login, loginFailure and logout persisted data.
Default Structure of Persisted Audit Data
<pre>
/alfresco-access
/login/user=<user>
/loginFailure/user=<user>
/logout/user=<user>
/transaction/
/action=<actionName>
/sub-actions=<sub action list>
/path=<prefixPath>
/type=<prefixType>
/user=<user>
/version=<version>
/copy/from/path=<prefixPath>
/move
/from/path=<prefixPath>
/properties
/from=<mapOfValues>
/to=<mapOfValues>
/add=<mapOfValues>
/delete=<mapOfValues>
/fromName=<oldName>
/toName=<newName>
/aspects
/add=<mapOfNames>
/delete=<mapOfNames>
The version value is sourced from either the add/cm:versionLabel or to/cm:versionLabel.
With the exception of the property 'name', individual property and aspect changes are not included, as it is not possible to know all possible names. The map values of all changes is however included. The individual property 'name' value is included as it is a well known property, which changes if content or a folder is renamed within the same parent folder.
The AccessAuditor provides log4j debug information (in the alfresco.log file) which is useful when creating custom audit configurations or even when developing other alfresco code. It logs persisted audit data and the full audit data that was generated.
Enable Access AuditorDebug
<pre>
log4j.appender.File.Threshold=debug
log4j.logger.org.alfresco.repo.audit.access.AccessAuditor=debug
When using the log output as a developer to see what is going on rather than to create a new audit application, it is generally better to use trace (rather than debug) level auditing as the log messages are cut down to make them more human readable.
<pre>
log4j.appender.File.Threshold=trace
log4j.logger.org.alfresco.repo.audit.access.AccessAuditor=trace
Very occasionally it is also useful to enable debug from the AuditFilter to see why it has rejected generated audit data. See (Audit Filter for details).
There are two customizations available.
The most common customization is to change the default audit filter values. These filter values are used to include or exclude selected events. Global property names identifies elements in the generated audit data. Each property value is a list of regular expressions that either accept or reject the generated data value. If any value is rejected in a set of data the whole set is rejected.
For example to audit the users 'jblogs' and any user that starts with 'temp' other than 'tempmanager', override the following global property value. If using tomcat, add a value to <tomcat>/shared/classes/alfresco-global.properties.
Example custom filter
<pre>
audit.filter.alfresco-access.transaction.user=~tempManager;test.*;jblogs
The list is semicolon separated. Any regular expression that starts with a '~' indicates that a matching value should be rejected. The list is evaluated from left to right until there is a match. If no match is made the value is rejected. If the list is empty (zero length) all values are accepted.It is possible to filter on any of the generated data values. For a more detailed description of filter properties see Audit Filter.
The most common reason to customize the audit configuration is if there is a need to extract individual property or aspect values that have special meaning to a particular Alfresco installation. For example, a security clearance level has been added to content and it is important to include that clearly in the persisted audit data, rather than having to find it deep within a map of all properties. The default configuration includes an example. It extracts the name property.
It is generally a good idea to create a new audit configuration file that includes a mapped path to avoid confusion with the default. If running under Tomcat place the audit configuration file in the <tomcat>/shared/classes/alfresco/extension/audit directory. The following example is simply a cut down version of the default with the path mapped to a new value.
myApp.xml
<pre>
<?xml version='1.0' encoding='UTF-8'?>
<Audit xmlns='http://www.alfresco.org/repo/audit/model/3.2'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.alfresco.org/repo/audit/model/3.2
alfresco-audit-3.2.xsd'>
<DataExtractors>
<DataExtractor name='simpleValue'
registeredName='auditModel.extractor.simpleValue'/>
</DataExtractors>
<PathMappings>
<PathMap source='/alfresco-access' target='/my-app' />
</PathMappings>
<Application name='my-app' key='my-app'>
<RecordValue
key='action' dataExtractor='simpleValue'
dataSource='/my-app/transaction/action'
dataTrigger='/my-app/transaction/action' />
<RecordValue
key='user' dataExtractor='simpleValue'
dataSource='/my-app/transaction/user'
dataTrigger='/my-app/transaction/user' />
<RecordValue
key='path' dataExtractor='simpleValue'
dataSource='/my-app/transaction/path'
dataTrigger='/my-app/transaction/path' />
</Application>
</Audit>
AccessAuditor debug for a move action
<pre>
Audit data:
/my-app/action=MOVE
/my-app/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:Word 123.docx
/my-app/user=admin
Inbound audit values:
/alfresco-access/transaction/action=MOVE
/alfresco-access/transaction/node=workspace://SpacesStore/90a398d1-8e0d-462a-8c3b-f0b17a2d1143
/alfresco-access/transaction/move/from/node=workspace://SpacesStore/a82446e9-4dca-49d2-9ce0-4526687fb310
/alfresco-access/transaction/move/from/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:folder1/cm:Word 123.docx
/alfresco-access/transaction/move/from/type=cm:folder
/alfresco-access/transaction/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:Word 123.docx
/alfresco-access/transaction/sub-action/00/action=moveNode
/alfresco-access/transaction/sub-action/00/move/from/node=workspace://SpacesStore/a82446e9-4dca-49d2-9ce0-4526687fb310
/alfresco-access/transaction/sub-action/00/move/from/path=/app:company_home/st:sites/cm:fred/cm:documentLibrary/cm:folder1/cm:Word 123.docx
/alfresco-access/transaction/sub-action/00/move/from/type=cm:folder
/alfresco-access/transaction/sub-action/01/action=readContent
/alfresco-access/transaction/sub-actions=moveNode readContent
/alfresco-access/transaction/type=cm:content
/alfresco-access/transaction/user=admin