Exporting Audit Data

ThingWorx Model Definition in Composer > System > Subsystems > Audit Subsystem > Audit Archive, Export, and Clean-up Operations > Exporting Audit Data

The ExportAuditData service is used 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 archived and online data. This service takes a repository name, target path, target file name, a start date, and an end date, and exports all entries from online or offline storage to a zip file at the given target path and in the given target file name. The export is sorted by audit date. The 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 two-letter abbreviation for the language in which to export the data. For example, “en” for English or “fr” for French.	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_11-03_one_hour", 2017-11-03 18:50:03.000, 2017-11-03 19:50:03.000)

This example will create an export in English in myExportRepository at /auditExport/export_11-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
2017-11-03 18:50:03.000 (a specific date and time)	2017-11-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 (2017–11–03), and an hour’s worth of data (from 18:50:03.000 through 19:50:03.000.
null	2017-11-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 (2017-11-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.
2017-11-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.

Continuing the example, the export_11-03_one_hour.zip file will contain the file, AuditArchives/export/export_11-03_one_hour.json. Here is an example of the JSON in the export:

{
"rows": [
{
"auditCategory": "Modeling",
"sourceType": "ModelTagVocabulary",
"source": "IntegrationTesting",
"id": "12345678-0123-4567-8901-123457890123",
"message": "Created ModelTagVocabulary \"IntegrationTesting\"",
"user": "Administrator",
"timestamp": 1490029001679
},
...
...
]
}

The information returned for this example includes the following details:

• 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.

• sourceType — The type associated with the application that generated this audit message (source).

• source — The ThingWorx application or an executable that generated this audit message. In the example, the source is IntegrationTesting.

• id — The GUID for the application that generated the audit message. The GUID is actually an application key that is generated by ThingWorx for the application.

• 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, as long as the following conditions are met:

• The age of the online data is younger than the specified number of days for the DaysOnline parameter of the audit subsystem. By default, this setting is 60 days.

• The online audit data table has fewer than the maximum number of rows specified for it (maxEntriesOnlineAuditData parameter of the audit subsystem). The default value is 500000 rows.

The export operation calls the ArchiveAuditHistory service, which copies audit data from the online storage to the AuditArchiveFileRepository for the scheduled export and leaves it online if both of these conditions are true. If either one of them is not true (data is older than the number of days or table has more rows than the maximum number of rows), the online data is removed from online storage after it has been archived to offline storage during the export.