Generate audit trail on demand

You can generate the audit trail document at any time during an active workflow. With the APIs described in this article, you can inspect the data and progress of a transaction whenever necessary, e.g. in case of unexpected behavior.

Generating an audit trail involves the following steps:

1. Generate audit trail
2. Download audit trail document

Generate audit trail

The Generate Audit Trail API generates the audit trail document. When audit trail generation has finished, a notification will be sent. The generated document can then be downloaded (see Download audit trail document).

Syntax

POST /api/transactions/uuid: transaction_id/generate-audit-trail

Available parameters

Request parameters (generate audit trail)

Name	HTTP request data	Description
Authorization	Request header	Required. This is the authorization token. Format: Bearer token
force	Request parameter	Optional. Determines how the request will be handled in case the audit trail document has been generated before. Possible values: true: The document will be regenerated. false: The existing document version will be returned. If the requested document does not exist, the force value will be ignored, and the document will be generated. Default value: false

Examples

Example request

The following request does not include the force parameter:

1. curl --location --request POST 'https://host:port/api/transactions/00178a9e-0862-4055-88b8-94f49618b51b/generate-audit-trail' \
2. --header 'Authorization: Bearer token' \
3. --header 'Cookie: cookie'

The following request includes the force parameter set to true:

1. curl --location --request POST 'https://host:port/api/transactions/00178a9e-0862-4055-88b8-94f49618b51b/generate-audit-trail?force=true' \
2. --header 'Authorization: Bearer token' \
3. --header 'Cookie: cookie'

Example response

The response contains the link to the download location of the audit trail document. The link has the following format:

"sfs://shared_storage_id/tenant_id/transactions/transaction_id/docs/AuditTrailDocument_transaction_version_number_events/1"

Example response if audit trail document is generated:

1. {
2.   "build_status": "in_progress",
3.   "path": "sfs://my_db/default/dealflo/transactions/00178a9e-0862-4055-88b8-94f49618b51b/docs/AuditTrailDocument_11_40/1"
4. }

Example response if audit trail document already exists:

1. {
2.   "build_status": "already_exist",
3.   "path": "sfs://my_db/default/dealflo/transactions/00178a9e-0862-4055-88b8-94f49618b51b/docs/AuditTrailDocument_11_40/1"
4. }

Notifications

Generating the audit trail document is a time-consuming operation. The status is returned as part of the response (see Example response). If the status is in_progress, the document is being created, and the SFS link will be available as soon as the document generation is completed. A notification that the document has been successfully generated will be sent to the tenant endpoint.

The notification is sent when the requested document is available for download.

• If the document already exists before a request to generate the audit trail is sent, a notification will be sent as soon as the request is completed.
• If the requested document does not exist before the request is sent, a notification will be sent to the endpoint with some delay.

Notification event content

Properties of notification event lists the properties that are included in the notification event that is sent to the tenant endpoint when audit trail generation has finished.

Properties of notification event

Property	Description
timestamp	The current timestamp, required for NS MS.
type	The event type (notification).
transaction_id	The transaction UUID to which the event belongs.
trigger	The event trigger.
skip_common_ux_components	Instructs the back end to skip the workflow's common UX components such as header, footer, error, etc. when creating the view state. Default value: true This property is ignored for this event.
skip_view_state	Instructs the back end to skip the view state in the transaction status response. Default value: false This property is ignored for this event.
document_references	The list of document references that contains audit trail on-demand SFS URLs for each document.
message	The human-readable message.
fields	Additional event data. This list only holds the callback_type, which is ignored for this event.
version	The event version. This property is ignored for this event.

Example notification

1. {
2.   "timestamp": "2022-01-05T09:16:15.005Z",
3.   "type": "notification",
4.   "transaction_id": "00178a9e-0862-4055-88b8-94f49618b51b",
5.   "trigger": "callback_trigger",
6.   "skip_common_ux_components": true,
7.   "skip_view_state": false,
8.   "document_references": ["sfs://my_db/default/dealflo/transactions/00178a9e-0862-4055-88b8-94f49618b51b/docs/AuditTrailDocument_11_40/1"],
9.   "message": "An Audit trail has been successfully created.",
10.   "fields": [
11.     {
12.       "name": "callback_type",
13.       "value": "active"
14.     }
15.   ],
16.   "version": 0
17. }

Download audit trail document

The Download Audit Trail Document API downloads the audit trail document that was generated with Generate audit trail. The response of the generate-audit-trail request contains the link to the download location of the document. This link is included in the request to download the audit trail document.

Syntax

GET /api/transactions/uuid:transaction_id/data

Available parameters

Request parameters (download audit trail document)

Name	HTTP request data	Description
Authorization	Request header	Required. This is the authorization token. Format: Bearer token
url	Request parameter	Required. The link to the download location of the audit trail document. Format: sfs://shared_storage_id/tenant_id/transactions/uuid:transaction_id/­docs/AuditTrailDocument_transaction_version_number_events/1

Examples

Example request

1. curl --location --request GET 'https://host:port/api/transactions/00178a9e-0862-4055-88b8-94f49618b51b/data?url=sfs://my_db/default/dealflo/transactions/00178a9e-0862-4055-88b8-94f49618b51b/docs/AuditTrailDocument_11_40/1' \
2. --header 'Authorization: Bearer token' \
3. --header 'Cookie: cookie'