Exporting Online Audit Data

ThingWorx Model Definition in Composer > System > Subsystems > Audit Subsystem > Using the Direct Persistence Implementation > Exporting Online Audit Data

When the Direct Persistence implementation is active, use the ExportOnlineAuditData service to export a localized version of audit messages from the online data store. Since the ExportOnlineAuditData service is available only for the Direct Persistence implementation, the data store is the database configured as the Persistence Provider for the ThingWorx Platform, either PostgreSQL or MS SQL.

The ExportOnlineAuditData service constructs localized audit messages from the online data. This service takes a locale, a repository name, a target path, a target file name, a start date, and an end date. The locale is used for the translation of the audit messages. When invoked, the service exports the audit entries matching the given criteria from the online storage to a zip file at the given target path, using the given target file name. The export is sorted by audit date. The service and its inputs follow:

ExportOnlineAuditData(locale[STRING],
targetRepositoryName[THINGNAME],
targetPath[STRING],
targetFileName[STRING],
startDate[DATETIME],
endDate[DATETIME],
query[QUERY])

The following table lists the input parameters, briefly describes them and shows their ThingWorx base type:

Parameter	Description	Base Type
locale	The abbreviation of the language name in which to return the results. (STRING). For example, fr for French or zh_CN for Chinese (China). For a list of locales supported by ThingWorx, refer to Supported Locales.	STRING
targetRepositoryName	The name of the file repository Thing where the output file containing localized audit entries should be stored.	THINGNAME
targetPath	The location to which the output file should be written.	STRING
targetFileName	The name of the output file in which the localized audit data should be stored.	STRING
startDate	The date and time of the first audit entry that you want to export. All audit entries with a timestamp after the date and time of the first exported audit entry and before the endDate are exported.	DATETIME
endDate	The date and time of the last audit entry that you want to export. All audit entries with a timestamp before the date and time of the last exported audit entry and after the startDate are exported.	DATETIME
query	A JSON-formatted query for filtering and sorting the audit data. There is no default value for this parameter. For an example, refer to the section, Example of Exporting Online Audit Data, below.

Example of Exporting Online Audit Data

Here is an example of a call to this service:

AuditSubsystem.ExportOnlineAuditData("en", myExportRepository, "/auditExport/",
"export_02-03_one_hour", 2020-02-03 18:50:03.000, 2020-02-03 19:50:03.000,
{
"filters": {
"type": "OR",
"filters": [{
"type": "EQ",
"fieldName": "user",
"value": "Administrator",
"isCaseSensitive": false
},
{
"type": "Between",
"fieldName": "timestamp",
"from": 1570195753953,
"to": 1570195753961
},
{
"type": "IN",
"fieldName": "source",
"values": ["test_tt", "test"],
"isCaseSensitive": false
},}
]
},
"sorts": [
{
"fieldName": "source",
"isAscending": true,
"isCaseSensitive": true
},
{
"fieldName": "timestamp",
"isAscending": true,
"isCaseSensitive": true
}
]
})

This example creates an export in English in myExportRepository at /auditExport/export_02-03_one_hour.zip. The contents will be all of the online audit messages, based on the start and end dates specified. The size of the exported zip file depends on how much data was collected between the start and end dates. The following table shows the content of the export, based on the start and end dates:

Start Date	End Date	Content of Export
2020-02-03 18:50:03.000 (a specific date and time)	2020-02-03 19:50:03.000 (a specific date and time)	All of the online data from the start date to the end date, which for this example, are the same date (2020–02–03), and an hour’s worth of data (from 18:50:03.000 through 19:50:03.000.
null	2020-02-03 19:50:03.000 (a specific date and time)	All of the online data that is older than the end date and time (2020-02-03 19:50:03.000). With the start date set to null, the export may contain a large volume of audit data, depending on the quantity of audit messages in the database storage and the online data retention policy.
2020-02-03 18:50:03.000 (a specific date and time)	null	All of the online data between the start date and time and the current date and time, which is specified by setting the end date to null.
null	null	ALL online audit data. Not recommended, as this could take a very long time.

Continuing the example, the export_02-03_one_hour.zip file creates an archive file, named AuditArchiveDirectPersistence/export/export_02-03_one_hour.json.

Here is an example of the JSON in the export file,AuditArchiveDirectPersistence/export/export_02-03_one_hour.json:

{
"rows":[
{
"auditCategory":"Modeling",
"application":"ThingWorxCore",
"sourceType":"Thing",
"id":"4164",
"source":"ExampleThing",
"message":"Created Thing \"ExampleThing\"",
"user":"ExampleUser",
"timestamp":1580773803
},
...
...
]
}

The information returned for this Direct Persistence example includes the following details:

Property	Description
auditCategory	The name of the category of audit message. In the example above, it is the Modeling category. For information about audit categories, see Audit Categories.
application	The name of the application that generated the audit message. For audit messages generated by the core ThingWorx Platform, the value is set to ThingworxCore.
sourceType	The type associated with the application that generated this audit message (Thing).
source	The ThingWorx application or an executable that generated this audit message. In the example, the source is ExampleThing.
id	This is a unique, auto-generated identifier for the audit entry. In this example, the id is 4164.
message	The text of the audit message.
user	The login name of the user who was running the application when the audit message was generated.
timestamp	In epoch time, the date and time that the audit message was generated.

What Happens to Online Data After an Export?

Online data remains in the online storage after an export. Data may be deleted manually from the online storage by running the ArchiveAuditHistory service, or automatically by setting up the AuditArchiveScheduler.