AuditEntryQuery interface
A JavaScript object implementing the AuditEntryQuery interface represents a query for AuditEntry objects and provides access as a read only Array of AuditEntry objects.
Only audit trail entries which have labels which permit the current user to read them are returned from queries.
Construction
Use O.audit.query().
Usage
Select the relevant audit entry criteria using the build query methods outlined below, then access the results. By default, the query is limited to 1000 results. This limit may be overridden, but care must be taken not to cause undue server load when querying the audit trail.
Execution is implicit when you use the Array-like interface, such as the length property or access an element with the [] operator.
The default sort order for results is by creationDate (most recent first). If an explicit sortBy column is selected, this ordering will be applied as a fallback (secondary) sort.
Performance notes
If you just need the most recent audit entry, based on the creationDate property of the AuditEntry, calling latest() will return it from your query without loading all the possible results.
If you wish to serve a large number of audit entries to the browser for tabular or graphical display, the table() method efficiently returns a JSON-encoded generator object (see Generators).
If you use any of the Array interface, such as length, all the matching WorkUnit objects will be loaded. Calling latest() after this will not make an additional load, but return the first object from the existing result set.
Interface (build query)
Every query function returns the object itself, making the query functions suitable for chaining.
Once the results have been accessed (including reading the length property), invoking any of the query functions will cause an exception.
function ref(ref)
Find audit entries relating to the object with Ref of ref.
function auditEntryType(type, [type, …])
Find audit entries that match any of the specified types. All arguments must be String.
System generated audit entry types are listed under Audit Entry Types.
function entityId(entityId)
Find audit entries relating to the entity entityId. Currently this will only every be
a SecurityPrincipal id.
function dateRange(from, to)
Find audit entries that were generated between the two dates: from and to.
function displayable(bool)
Find audit entries that are marked either as displayable (true) or not displayable (false). Call displayable(null) to find all audit entries (the default displayable option).
Displayable entries are visible in the Recent changes list, and typically relate to store objects. Not displayable entries relate to other operations such as login and logout events.
Note: care must be taken when requesting not displayable entries to ensure that only suitable information is displayed to the user, and that the user is authorised to view this information.
function userId(id)
Find audit entries generated by the SecurityPrincipal with this id.
If an audit entry was generated while impersonation was active, this matches the impersonated user.
function authenticatedUserId
Find audit entries generated by the SecurityPrincipal with this id.
If an audit entry was generated while impersonation was active, this matches the logged-in user (NOT the impersonated user).
function sortBy(fieldName)
Sort the results by fieldName.
fieldName may be any property provided by the AuditEntry interface. The field name may optionally have have _asc or _desc appended to it.
sortBy("userId") is equivalent to sortBy("userId_desc"), while sortBy("creationDate_asc") will return the earliest audit entry first.
The default sort order is descending. A fallback ordering by creationDate descending is always applied.
Sorting by any field other than creationDate is likely to only be useful for grouping purposes. For example, sorting by userId will sort based on the internal user ID, not the username.
function limit(count)
At most count results will every be returned by this query. count must be a positive integer.
Interface (results)
acts as Array
A WorkUnitQuery object acts as a read-only JavaScript Array. Use the [] operator to read rows.
function latest()
Returns the first audit entry that matches the query, in an efficient manner.
function first()
Alias of latest()