Skip to content

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

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.

ParameterTypeDescription
auditTrailEntryOmit<AuditTrailEntryData, 'actionName' | 'actionIcon'>The entry. Only the fields listed below are stored.
withoutUserInfobooleanOptional. true saves the entry without an author. Default: false.

AuditTrailEntryData fields

FieldTypeRequiredDescription
relatedToTypestringRequired__type of the instance the entry belongs to.
relatedToIdstringRequiredid 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.
actionTypeAuditTrailActionTypeOptionalThe 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.
messagestringRequiredText of the entry.
isHtmlbooleanOptionalWhether message is HTML. Default: plain text.
attachmentsAuditTrailEntryAttachmentData[]OptionalFiles 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(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.

ParameterTypeDescription
entityInstanceanyThe Entity instance. It must have an id, so save it first.
auditTrailEntryOmit<AuditTrailEntryData, 'actionName' | 'actionIcon' | 'relatedToType' | 'relatedToId'>The entry: type, actionType, message, isHtml and attachments as in addAuditTrailEntry().
withoutUserInfobooleanOptional. true saves the entry without an author. Default: false.

Returns: Promise<void> · Availability: Server

// server-side
addAuditTrailMessageForEntityInstance(entityInstance: any, message: string, attachments?: AuditTrailEntryAttachmentData[], userOrId?: User | string | null): Promise<void>
// client-side
addAuditTrailMessageForEntityInstance(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.

ParameterTypeDescription
entityInstanceanyThe Entity instance. It must have an id.
messagestringText of the message.
attachmentsAuditTrailEntryAttachmentData[]Server-side only. Optional. Files attached to the message. Default: none.
userOrIdUser | string | nullServer-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(relatedToType: string, relatedToId: string): Promise<AuditTrailEntry[]>

Reads all audit trail entries linked to the given type and ID.

ParameterTypeDescription
relatedToTypestring__type of the instance.
relatedToIdstringid 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(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.

ParameterTypeDescription
entityInstanceanyThe 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(uuid: string): Promise<AuditTrailEntry[]>

Reads all audit trail entries whose relatedToId is the given UUID, whatever their relatedToType.

ParameterTypeDescription
uuidstringThe 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.

ParameterTypeDescription
uuidstringThe UUID the entries were recorded under. It must not be empty: an empty value transfers every entry.
entityInstanceanyThe saved Entity instance that receives the entries.

Returns: Promise<AuditTrailEntry[]>, the transferred entries · Availability: Server

An audit trail entry as read back from the database. It has all fields of AuditTrailEntryData plus:

FieldTypeDescription
idnumberID of the entry.
userIdAndNameUserIdAndNameThe author as userId and name, or null if the entry has no author.
timestampDateWhen the entry was saved.
attachmentsAuditTrailEntryAttachment[]The attachments, each with id, entryId, content, mimeType and previewImage.
actionNamestringRead-only. Display name of actionType, for example Approved.
actionIconstringRead-only. Material icon name of actionType, for example verified.

Availability: Both