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:
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:
| Property | Description |
|---|---|
| adaptable_id | Current AdapTable Id |
| adaptable_state_key | Current Adaptable State Key |
| audit_trigger | What caused the Audit Log message to be sent |
| client_timestamp | time on user's computer when message was sent |
| data_change_details | Additional information sent if Audit Trigger is Cell Edit or Ticking Data |
| function_applied_details | Additional information sent if Audit Trigger is 'Grid Applied' |
| number_of_missed_ping | How many pings have been missed |
| state_change_details | Additional information sent if Audit Trigger is User or Internal State change |
| username | Name 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:
| Property | Description |
|---|---|
| actionType | Redux action that was invoked when State was changed |
| name | Name 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:
| Property | Description |
|---|---|
| state | The 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.
Property Description newValue New value for Property oldValue Previous value for Property propertyName Name 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
Property Description objectChanged Adaptable object which has been changed objectChangeTrigger Whether object has been created, updated or deleted
Internal State Change Message
If the Audit Trigger is Internal State Change an `info' property is added:
| Property | Description |
|---|---|
| info | Details 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:
| Property | Description |
|---|---|
| column_id | Column being updated or edited |
| new_value | Values in the Cell after change was made |
| previous_value | Value in the Cell before change was made |
| primarykey_column_id | Current Primary Key Column in AdapTable |
| primarykey_column_value | Value in Primary Key Column for changed Row |
| row_data | All 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:
| Property | Description |
|---|---|
| action | Redux action that was invoked when State was changed |
| data | Data for the Function being applied (usually User State) |
| info | Additional information about what was applied |
| name | Name of AdapTable function that was applied |
Audit Options
| Property | Description | Default |
|---|---|---|
| alertMessageType | Message Type for when sending Audit messages as Alerts | |
| alertShowAsPopup | Whether Audit Alert will show a popup | |
| auditCellEdits | Audits cell edits (changes to cell data directy by user action) | all false |
| auditFunctionsApplied | Audits Functions being applied in AdapTable (e.g. 'Smart Edit Applied' | all false |
| auditInternalStateChanges | Audits 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 true | 1 |
| auditTickingDataUpdates | Audits all changes to Grid data (i.e. not caused by a user edit) | all false |
| auditUserStateChanges | Audits all changes to User State (e.g. objects created, edited or deleted) | all false |
| httpChannel | Http Channel to stream to; at least 1 Audit Option must have 'auditToHttpChannel' set to true | '/auditlog' |
| pingInterval | Frequency (in seconds) Audit Log will ping to check Http Channel is running; at least 1 Audit Option must have 'auditToHttpChannel' set to true | 60 |
Setting up Audit Log Example
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.