Sys.Audit
Sys.Audit writes and reads the audit trail: a list of timestamped entries attached to an Entity instance, each recording an action (such as “Approved”) or a free-text message, and the user who made it. An entry is linked to its instance by the instance’s __type and id.
Server-side code can write any kind of entry. Client-side code can only read the entries of an instance and add messages to it as the logged-in End user.
Availability: Both
Functions
Section titled “Functions”addAuditTrailEntry()
Section titled “addAuditTrailEntry()”addAuditTrailEntry(auditTrailEntry: Omit<AuditTrailEntryData, 'actionName' | 'actionIcon'>, withoutUserInfo?: boolean): Promise<void>Saves an audit trail entry linked to whatever relatedToType and relatedToId say. Lowgile sets the timestamp and, unless withoutUserInfo is true, records the current user as its author.
| Parameter | Type | Description |
|---|---|---|
auditTrailEntry | Omit<AuditTrailEntryData, 'actionName' | 'actionIcon'> | The entry. Only the fields listed below are stored. |
withoutUserInfo | boolean | Optional. true saves the entry without an author. Default: false. |
AuditTrailEntryData fields
| Field | Type | Required | Description |
|---|---|---|---|
relatedToType | string | Required | __type of the instance the entry belongs to. |
relatedToId | string | Required | id of the instance the entry belongs to, or a UUID that the entry is later transferred from (see transferAuditTrailEntriesFromUuidToEntityInstance()). |
type | 'message' | 'action' | Required | 'action' for something that was done to the instance, 'message' for a comment. |
actionType | AuditTrailActionType | Optional | The kind of action. Lowgile has a name and icon for create, update, delete, submit, resubmit, undelete, review, approve, reject, removeApproval, open, close, reopen, assign and escalate; any other string is allowed but shows without them. |
message | string | Required | Text of the entry. |
isHtml | boolean | Optional | Whether message is HTML. Default: plain text. |
attachments | AuditTrailEntryAttachmentData[] | Optional | Files attached to the entry. Each has content (ArrayBuffer) and an optional mimeType. |
await Sys.Audit.addAuditTrailEntry({ relatedToType: request.__type, relatedToId: request.id, type: 'action', actionType: 'approve', message: 'Approved within budget',})Returns: Promise<void> · Availability: Server
addAuditTrailEntryForEntityInstance()
Section titled “addAuditTrailEntryForEntityInstance()”addAuditTrailEntryForEntityInstance(entityInstance: any, auditTrailEntry: Omit<AuditTrailEntryData, 'actionName' | 'actionIcon' | 'relatedToType' | 'relatedToId'>, withoutUserInfo?: boolean): Promise<void>Saves an audit trail entry for an Entity instance, like addAuditTrailEntry(), taking relatedToType and relatedToId from the instance’s __type and id.
| Parameter | Type | Description |
|---|---|---|
entityInstance | any | The Entity instance. It must have an id, so save it first. |
auditTrailEntry | Omit<AuditTrailEntryData, 'actionName' | 'actionIcon' | 'relatedToType' | 'relatedToId'> | The entry: type, actionType, message, isHtml and attachments as in addAuditTrailEntry(). |
withoutUserInfo | boolean | Optional. true saves the entry without an author. Default: false. |
Returns: Promise<void> · Availability: Server
addAuditTrailMessageForEntityInstance()
Section titled “addAuditTrailMessageForEntityInstance()”// server-sideaddAuditTrailMessageForEntityInstance(entityInstance: any, message: string, attachments?: AuditTrailEntryAttachmentData[], userOrId?: User | string | null): Promise<void>// client-sideaddAuditTrailMessageForEntityInstance(entityInstance: any, message: string): Promise<void>Saves a message (an entry of type 'message') for an Entity instance. On the client side, the message is sent to the server and recorded with the logged-in End user as its author.
| Parameter | Type | Description |
|---|---|---|
entityInstance | any | The Entity instance. It must have an id. |
message | string | Text of the message. |
attachments | AuditTrailEntryAttachmentData[] | Server-side only. Optional. Files attached to the message. Default: none. |
userOrId | User | string | null | Server-side only. Optional. The author, as a user or user ID. Default: no author. Unlike addAuditTrailEntry(), the current user is not recorded automatically. |
Returns: Promise<void> · Availability: Both
getAuditTrailEntries()
Section titled “getAuditTrailEntries()”getAuditTrailEntries(relatedToType: string, relatedToId: string): Promise<AuditTrailEntry[]>Reads all audit trail entries linked to the given type and ID.
| Parameter | Type | Description |
|---|---|---|
relatedToType | string | __type of the instance. |
relatedToId | string | id of the instance. |
Note
A null or undefined argument is not used as a filter. For example, with both left empty, the result is every audit trail entry.
Returns: Promise<AuditTrailEntry[]> · Availability: Server
getAuditTrailEntriesForEntityInstance()
Section titled “getAuditTrailEntriesForEntityInstance()”getAuditTrailEntriesForEntityInstance(entityInstance: any): Promise<AuditTrailEntry[]>Reads all audit trail entries of an Entity instance. On the client side, the entries are loaded from the server; any logged-in End user can read them.
| Parameter | Type | Description |
|---|---|---|
entityInstance | any | The Entity instance. |
Note
On the client side, an instance without id gives an empty list. On the server side, it gives every entry of that Entity type; check for an id first.
Returns: Promise<AuditTrailEntry[]> · Availability: Both
getAuditTrailEntriesForUuid()
Section titled “getAuditTrailEntriesForUuid()”getAuditTrailEntriesForUuid(uuid: string): Promise<AuditTrailEntry[]>Reads all audit trail entries whose relatedToId is the given UUID, whatever their relatedToType.
| Parameter | Type | Description |
|---|---|---|
uuid | string | The UUID the entries were recorded under. An empty value returns every entry. |
Returns: Promise<AuditTrailEntry[]> · Availability: Server
transferAuditTrailEntriesFromUuidToEntityInstance()
Section titled “transferAuditTrailEntriesFromUuidToEntityInstance()”transferAuditTrailEntriesFromUuidToEntityInstance(uuid: string, entityInstance: any): Promise<AuditTrailEntry[]>Links all audit trail entries recorded under a UUID to an Entity instance instead. Use it when entries are written before the instance is saved and has an id: record them under a UUID with addAuditTrailEntry(), then transfer them once the instance is saved.
| Parameter | Type | Description |
|---|---|---|
uuid | string | The UUID the entries were recorded under. It must not be empty: an empty value transfers every entry. |
entityInstance | any | The saved Entity instance that receives the entries. |
Returns: Promise<AuditTrailEntry[]>, the transferred entries · Availability: Server
AuditTrailEntry
Section titled “AuditTrailEntry”An audit trail entry as read back from the database. It has all fields of AuditTrailEntryData plus:
| Field | Type | Description |
|---|---|---|
id | number | ID of the entry. |
userIdAndName | UserIdAndName | The author as userId and name, or null if the entry has no author. |
timestamp | Date | When the entry was saved. |
attachments | AuditTrailEntryAttachment[] | The attachments, each with id, entryId, content, mimeType and previewImage. |
actionName | string | Read-only. Display name of actionType, for example Approved. |
actionIcon | string | Read-only. Material icon name of actionType, for example verified. |
Availability: Both
Related
Section titled “Related”- Entity
- Add Audit Trail
- Sys API overview