Exporting Audit Data
For both implementations of the Audit Subsystem, use the ExportAuditData service to export a localized version of audit messages, whether from the offline (archived) data or the online data. This service constructs localized audit messages from the offline and online data. This service takes a locale, a repository name, target path, target file name, a start date, and an end date. When invoked, the service exports all the matching entries from the offline storage to a zip file at the given target path, using the given target file name. The export is sorted by audit date.
 |
If the Direct Persistence implementation is active, you can also export online audit data from the database, using the ExportOnlineAuditData service. This service has a query option that you can use to filter and sort the exported data.
|
The ExportAuditData service and its inputs follow:
ExportAuditData(locale[String],
targetRepositoryName[THINGNAME],
targetPath[STRING],
targetFileName[STRING],
startDate(dateTime),
endDate(dateTime))
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 this 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 this audit entry and after the startDate are exported.
|
DATETIME
|
Here is an example of a call to this service:
AuditSubsystem.ExportAuditData("en", myExportRepository, "/auditExport/",
"export_02-03_one_hour", 2020-02-03 18:50:03.000, 2020-02-03 19:50:03.000)
This example will create an export in English in myExportRepository at /auditExport/export_02-03_one_hour.zip. The contents will be all of the online audit messages as well as all of the offline 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 and offline 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 and any offline 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 actual date that offline data started being retained.
|
|
2020-02-03 18:50:03.000 (a specific date and time)
|
null
|
All of the online data and any offline 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 audit data, online and offline. Not recommended, as this could take a very long time.
|
Depending on the active implementation, the export_02-03_one_hour.zip file will contain either of the following files:
• Direct Persistence — AuditArchiveDirectPersistence/export/export_02-03_one_hour.json.
• Data Table — AuditArchive/export/export_02-03_one_hour.json.
Here is an example of the JSON in the export file when the Direct Persistence implementation is active.:
{
"rows": [ {
"auditCategory": "System",
"application": "ThingWorxCore",
"sourceType": "Subsystem",
"id": "1002",
"source": "AuditSubsystem",
"message": "Updated Subsystem \"AuditSubsystem\"",
"user": "Administrator",
"timestamp": 1582194488947
}]
}
Here is an example of the JSON in the export file when the Data Table implementation is active:
{
"rows": [
{
"auditCategory": "Modeling",
"sourceType": "ModelTagVocabulary",
"source": "IntegrationTesting",
"id": "12345678-0123-4567-8901-123457890123",
"message": "Created ModelTagVocabulary \"IntegrationTesting\"",
"user": "Administrator",
"timestamp": 1580773803
},
...
...
]
}
Note that the format of the id differs between the two implementations and that the Direct Persistence export file contains an additional property, called application. The following table describes the properties in the export files, with notes about these differences:
|
Property
|
Implementation?
|
Description
|
|---|---|---|
|
auditCategory
|
Both
|
The name of the category of audit message. The examples above show different categories:
• Direct Persistence — System category
• Data Table — Modeling category
For information about audit categories, see Audit Categories.
|
|
application
|
Direct Persistence only
|
The name of the application that generated the audit message. In the Direct Persistence example above the audit messages are generated by the core ThingWorx Platform, so the value is set to ThingworxCore.
|
|
sourceType
|
Both
|
The type associated with the application that generated this audit message (source). The examples above show different source types, which reflect the auditCategory for both implementations and for Direct Persistence the application:
• Direct Persistence — Subsystem
• Data Table — ModelTagVocabulary
|
|
source
|
Both
|
The ThingWorx application or an executable that generated this audit message. The examples above show different ThingWorx applications:
• In the Direct Persistence example, the source is Audit Subsystem.
• In the Data Table example, the source is IntegrationTesting.
|
|
id
|
Both, with format differences
|
Direct Persistence implementation — The auto-generated database id for the application that generated the audit message.
Data Table implementation — The GUID for the application that generated the audit message.
|
|
message
|
Both
|
The text of the audit message.
|
|
user
|
Both
|
The login name of the user who was running the application when the audit message was generated.
|
|
timestamp
|
Both
|
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 PurgeAuditData service, or automatically by setting up the AuditPurgeScheduler.