Audit Log

The Audit Log - when enabled - streams messages and information about AdapTable activity to an HTTP Channel, or other destination.

Every single action in AdapTable can, optionally, be fully audited for internal review purposes: each Function activity, menu click, configuration setting, data edit and ticking data change.

This provides admins and support with complete oversight over everything that ever happens in AdapTable.

tip

Audit Log allows developers to create reports showing a particular user's activity, or how data has changed over any time period.

Audit Log Scope

important

AdapTable has no knowledge of the messages Audit Log sends, nor where they are sent.

All Information sent to Audit Log lives entirely within users' systems at a internal destination specified by them.

Likewise, AdapTable has no ability to access Audit Log messages: they are only visible to, and accessible by, our users.โ€‹โ€‹

How Audit Log Works

Audit Log is set up via the Audit Options section of Adaptable Options.

There are 3 main concepts in the Audit Log:

  • Audit Triggers - what happened in AdapTable which caused the Audit Log to be invoked
  • Audit Destination - the location(s) to which an Audit Message can be dispatched
  • Audit Messages - a description of the actual Audit Event packaged as a simple JSON object

There are 5 available AuditTriggers and 4 available AuditDestinations.

tip

As many Audit Triggers can be set as required; and for each Audit Trigger, as many Audit Destinations can be selected as needed. Each of these will receive an Audit Message.

note

If no AuditTriggers are set, then AuditLog will be turned off.

Audit Triggers

The 5 Audit Triggers which cause an Audit Log Message to be created and dispatched are:

Cell Edit

This is triggered whenever a cell in AdapTable is edited as a direct result of user action.

note

The Audit Meassage generated contains details of the edit, before and after values and the user involved

Ticking Data Update

This is triggered when data in the underlying vendor grid's data set is updated as a result of external action.

caution

Audit Log should NOT be used as a ticking database so this option should be used sparingly if you have very high-frequency ticking data.

The primary use case for this is where underlying data changes rarely in the underlying data set but the user wishes to be notified (presumably) by Alert when that does happen.

important

This excludes direct Cell Edits which are covered in the 'Cell Edit' trigger.

Function Applied

This is triggered whenever an AdapTable Function is applied directly (e.g. Quick Search is run, a Smart Edit is invoked, a report is run in Export or a Layout is selected etc.)

note

There is some occasional overlap between the Function Applied trigger and the User State Change trigger (see below). For example both will fire when a Layout is selected or a Theme is applied.

User State Change

This is triggered whenever a change is made to the User's persisted state.

This includes whenever AdapTable objects (e.g. Conditional Styles) are created, edited or deleted or when something persistable is selected (e.g. Layout).

tip

To listen to State changes that are not persisted, use Internal State Changes (see below)

Internal State Change

This is triggered whenever a change is made to AdapTable's internal state (e.g. a popup is displayed).

This is rarely used as most internal changes to AdapTable state are not of interest to the user.

warning

This will trigger very often so use sparingly

Audit Destinations

Audit Destinations are the locations to which an Audit Message can be dispatched.

note

Audit Messages can be sent to multiple Audit Destinations - the most common are Http Channel and Event

caution

The default for each option for each Audit Type is false - meaning that audit is only triggered if you set at least one destination for one trigger to true.

The 4 available Audit Destinations are:

Http Channel

Audit Messages will be sent to an HTTP channel set up by developers at design-time.

important

Audit messages will be received via the users' own internal reporting software (e.g. the Elastic Stack)

When this option is used, 2 additional properties need to be set in Audit Options:

  • httpChannel sets the name of the Http Channel to use
  • pingInterval is the frequency (in seconds) Audit Log will ping to check the Http Channel is running
caution

If no value is set for this property the default value of' /auditlog' will be used.

Event

Audit Messages will be fired as standard Adaptable Events.

Users can subscribe to the Audit Event using the Audit Event Api the same way as to other Adaptable Events:

adaptableApi.auditEventApi.on('AuditCellEdited', auditLogEventArgs => {
// All Audit Events contain an AuditLogEntry as the main args
// The data it contains will differ depending on which Audit Event was triggered
const auditLogEntry: AuditLogEntry = auditLogEventArgs.data[0].id;
const details: DataChangedDetails = auditLogEntry.data_change_details;
}
);

Alert

Audit Messages will be displayed as AdapTable Alerts.

When this option is used, 2 additional properties need to be set in Audit Options:

  • alertMessageType specifies what kind of Alert it is i.e. 'Success', 'Info', 'Warning' or 'Error'
  • alertShowAsPopup sets whether the Alert displays a popup (as well as in Alert toolbar and tool panel)

Console

Audits messages will be sent directly to the browser's console.

tip

This option is very useful for testing and debugging purposes but less so in a production environment

Audit Messages

An Audit Message provides all the information related to an Audit Event via an auditLogEntry object.

This contains details of the time of the event, user and AdapTable instance and is defined as follows:

PropertyDescription
adaptable_idCurrent AdapTable Id
adaptable_state_keyCurrent Adaptable State Key
audit_triggerWhat caused the Audit Log message to be sent
client_timestamptime on user's computer when message was sent
data_change_detailsAdditional information sent if Audit Trigger is Cell Edit or Ticking Data
function_applied_detailsAdditional information sent if Audit Trigger is 'Grid Applied'
number_of_missed_pingHow many pings have been missed
state_change_detailsAdditional information sent if Audit Trigger is User or Internal State change
usernameName of current AdapTable user

State Changes

The state_change_details property is populated when the Audit Trigger is User or Internal State Change.

The base object contains the following properties:

PropertyDescription
actionTypeRedux action that was invoked when State was changed
nameName of the AdapTable Function where State was changed

User State Change Message

If the Audit Trigger is User State Change a `state' property is added:

PropertyDescription
stateThe entry in User State which has been changed

Further information is also added to the AuditLogEntry depending on the type of User State Change:

  • State Property Change - used when a property set in Config is changed in User State.

    note

    Examples are Current Layout, Quick Search Text etc.

    PropertyDescription
    newValueNew value for Property
    oldValuePrevious value for Property
    propertyNameName of property in Config that was changed
  • State Object Change

    note

    This is used when an AdapTable Object has been created, edited or deleted in State

    PropertyDescription
    objectChangedAdaptable object which has been changed
    objectChangeTriggerWhether object has been created, updated or deleted

Internal State Change Message

If the Audit Trigger is Internal State Change an `info' property is added:

PropertyDescription
infoDetails of the Internal State Change

Data Changes

The data_change_details property is populated when the Audit Trigger is Cell Edit or Ticking Data Update.

It contains the following properties:

PropertyDescription
column_idColumn being updated or edited
new_valueValues in the Cell after change was made
previous_valueValue in the Cell before change was made
primarykey_column_idCurrent Primary Key Column in AdapTable
primarykey_column_valueValue in Primary Key Column for changed Row
row_dataAll the data in the Row which was edited

Function Applied Messages

The function_applied_details property is populated when the Audit Trigger is Function Applied.

It contains the following properties:

PropertyDescription
actionRedux action that was invoked when State was changed
dataData for the Function being applied (usually User State)
infoAdditional information about what was applied
nameName of AdapTable function that was applied

Audit Options

PropertyDescriptionDefault
alertMessageTypeMessage Type for when sending Audit messages as Alerts
alertShowAsPopupWhether Audit Alert will show a popup
auditCellEditsAudits cell edits (changes to cell data directy by user action)all false
auditFunctionsAppliedAudits Functions being applied in AdapTable (e.g. 'Smart Edit Applied'all false
auditInternalStateChangesAudits all changes to Internal State (e.g. popup opened, cells selected)all false
auditLogsSendInterval'Batch' time (in seconds) for pushing Audit messages; at least 1 Audit Option must have 'auditToHttpChannel' set to true1
auditTickingDataUpdatesAudits all changes to Grid data (i.e. not caused by a user edit)all false
auditUserStateChangesAudits all changes to User State (e.g. objects created, edited or deleted)all false
httpChannelHttp Channel to stream to; at least 1 Audit Option must have 'auditToHttpChannel' set to true'/auditlog'
pingIntervalFrequency (in seconds) Audit Log will ping to check Http Channel is running; at least 1 Audit Option must have 'auditToHttpChannel' set to true60

Setting up Audit Log Example

auditOptions = {
auditCellEdits: {
auditToHttpChannel: true,
},
auditFunctionsApplied: {
auditAsAlert: true,
},
auditInternalStateChanges: {
auditAsEvent: true,
auditAsAlert: true,
},
auditUserStateChanges: {
auditAsEvent: true,
auditToHttpChannel: true,
auditAsAlert: true,
},
auditTickingDataUpdates:{
auditToConsole: true,
}
httpChannel: '/MyChannel',
pingInterval: 120,
auditLogsSendInterval: 3,
};

FAQ

Can we filter which audit messages are sent via Audit Log?

Yes, the Audit Options section of Adaptable Options allows you to specify which of the Audit Categories you want to enable (CellEdits, FunctionEvents, UserStateChanges and InternalStateChanges).

In addition, most reporting software will allow you to filter the messages that you receive so that you only report and save the ones in which you are interested.

Where do you store the Audit Log messages?

We don't store them anywhere - AdapTable simply streams all Audit Log messages. Its your responsibility to listen to this stream and persist the messages where most appropriate.

There is an option in Audit Options to send these messages just to the Console though most users prefer for them to be streamed to the Http Channel so that they can use software like the Elastic Stack to listen to them in advanced ways.

What information is sent in an Audit Log message?

That depends on the type of message. All messages have some common properties but others are added if its a function change or a cell edit.

Can we turn off Audit Log if we don't need it?

Yes that is straightforward to do and indeed its turned off by default.

If none of the 5 Audit Triggers in Audit Options are set to true then Audit will not be enabled.

More Information