Custom Audit Categories
The Audit Subsystem provides a fixed set of available Audit Categories. Audit messages that are triggered by events in ThingWorx Platform have been assigned to these categories. You cannot change these assignments. However, if you require a category that is not in this set, you can create a custom category and assign your custom events and audit messages to the category.
How to Add a Custom Audit Category Through Localization Table
Both implementations of the Audit Subsystem provide the following ways to add a custom audit category:
Through a ThingWorx localization table, modified using ThingWorx Composer.
By creating a new back end Java extension for ThingWorx Platform. To create a custom audit category using the ThingWorx Java SDK to create an extension for this purpose, refer to Creating Custom Audit Categories Using an Extension. This method still uses localization tables, but the creation of the tokens can be programmatic or interactive through the Composer user interface, as explained here.
This section explains how to add a custom category on the ThingWorx Platform side through the localization tables user interface. If you have never worked with ThingWorx localization tables, take a few minutes to read the topic, Localization Tables, in this help center.
When ready, follow these steps to add a custom audit category to localization tables:
1. Log in to ThingWorx Composer and click (Browse).
2. Under System in the Browse navigation panel, select Localization Tables, as indicated in the following figure:
The list of Localization Tables appears:
3. Select the check box for the Default localization table, and when it becomes active, click the Edit button to display that table in Edit mode, as indicated here:
The Localization Tokens page for the Default localization table appears in Edit mode:
4. As indicated in the following figure, click + Add to add the localization token for your custom audit category:
The New Localization Token page appears on the right side of your screen:
5. In the Name field, you first must type the prefix for an Audit Category localization token, audit.AuditCategory., then type a unique name. The names you use for custom categories must be unique. For example, audit.AuditCategory.CustomAlertCategory.
* 
As long as the token is valid, the QueryAuditHistory and QueryAuditHistoryWithQueryCriteria services return custom audit messages, with or without the prefix. However, if you do not use the prefix, the subsystem cannot differentiate between Audit Category tokens and "other" tokens. Further, for the Audit Subsystem to display a custom audit category in the list of categories in the audit log user interface, every custom Audit Category must use the prefix, audit.AuditCategory..
6. In the Token Value field, you can use whatever you think is appropriate for the category. For example, use the part of the name that you typed after the prefix. You can also use any alphanumeric characters, spaces, and underscores.
Note that the Token Value becomes the Reference Value for this token in the localization tables for other languages.
7. To save this localization token and then create the localization token for your audit message click and continue to the next step. If you want to stop here click to save and close the page.
* 
If you query without defining this localization token in other localization tables, the query service returns only what you have created. Once you add the token to other localization tables, the results will include the other languages. If you have not defined the token for the custom audit message, the query cannot find it.
Next, you will add the localization token for your custom audit message to the Default localization table.
8. If you closed it, click +Add to display the New Localization Token page again. Otherwise, continue to the next step.
9. In the Token Name field, type a unique prefix and a unique name for the custom audit message token. Do not use audit.AuditCategory for the prefix. The names for custom audit messages must be unique. For example, myCustomAlertMessages.AlertEvent.
* 
The prefix audit.AuditCategory is reserved for categories only. If you use that prefix for a message, the message could be interpreted as a category and shown in the audit log user interface as a category and not a message.
For the custom audit message, you need additional information that is not available in the ThingWorx user interface. That information is the arguments of the custom audit message. For example, your arguments might be thingName and alertEventMsg, with sample values of mixer123 and overflow. You can specify such arguments in the Token Value for the message. The values are substituted when the custom audit message is generated and returned by an audit query. Simple messages, such as "Entity file import completed successfully", do not have any arguments to specify.
* 
For information about creating custom events, refer to Working with Events, Alerts, and Subscriptions and the ThingWorx API documentation.
10. In the Token Value field, add the arguments for the audit message. Each argument must be preceded by two underscores and followed by two underscores. For example, suppose a custom audit message for removing a User has the following arguments
username
entityType
entityName
You would enter the following in the Token Value field:
User __username__ removed __entityType__ named '__entityName__'
At runtime, the three arguments are replaced as long as there are corresponding values in the custom audit message arguments.
* 
Some messages do not need to use arguments. For example, a simple messages such as "Entity file import completed successfully" does not use replacements.
11. Click to save and close the page.
12. To test the addition of the custom audit category and message, trigger the event that generates the message, and then run the QueryAuditHistory or QueryAuditHistoryWithQueryCriteria service, specifying the locale to return. Keep in mind that you must use the localization token for the category with the QueryAuditHistoryWithQueryCriteria service.
Next, you need to add a localization token for your custom audit category and message to the localization table for each desired locale. For example, ja for Japanese or de for German.
Follow these steps:
1. Click the Browse tab to return to the list of localization tables, and choose a different locale. For example purposes, select ja (Japanese) and click Edit, as shown here:
2. In the Localization Tokens page for the ja locale, find the localization token that you just created for your custom audit category.
* 
To locate a token quickly, use the Filter at the top of the list. Start typing a word in the name of the token. For example, if you used "MyCustom" in the name, starting typing in the filter field, as shown below. All localization tokens that contain that word are displayed.
3. Click the name of the custom audit category token to display its editing page on the right side of the tab, as shown in the figure above.
4. In the Token Value field, enter the translated value of the Token Value that you used for this category in the Default locale.
5. Click to save and close the editing page.
6. In the list of localization tokens, use the Filter to locate the name of the token you created for the custom audit message in the Default locale, and click it to display its editing page on the right side of the tab.
7. In the Token Value field, add the translated part of the message and, if applicable, the translated argument names for the audit message. As with the token value for the Default locale, each argument must be preceded by two underscores and followed by two underscores.
8. Click to save and close the editing page.
9. To test the addition of the custom audit category and message, trigger the event that generates the message, and then run the QueryAuditHistory or QueryAuditHistoryWithQueryCriteria service, specifying the locale to return. Keep in mind that you must specify the localization token for the category, not a name.
* 
Using the ThingWorx Java API, you can do all of this in an extension. You create an event that you want to audit and then add the custom audit category and custom audit message to the localization tables, Default for universal English and then the table for any other locale you require. You can also import a localization table as part of importing your extension.
For information on adding events programmatically, refer to Working with Events, Alerts, and Subscriptions in the section, "Best Practices for Developing Applications", in this help center. You should also refer to the Javadoc for the ThingWorx APIs, API Documentation.
For information on packaging extensions with localization tables, refer to Packaging Extensions with Localization Tables.
Was this helpful?