Creating Custom Audit Categories Using an Extension

ThingWorx Extensibility > Extensions > Creating Custom Audit Categories Using an Extension

Using the ThingWorx Java SDK, you can create custom audit events and messages. Although you cannot add custom events through ThingWorx Composer, there are two ways to add customer Audit categories and messages:

• Through Composer. For more information, see Custom Audit Categories .

• By creating a Java extension based on the ThingWorx Extension SDK, which is explained in this topic.This method requires use of localization tables as well, but creation of the tokens can be programmatic or interactive through the Composer user interface.

This topic covers the process of creating an extension that adds custom audit events, messages, and categories for audited events. You can add a custom audit category by creating a custom ThingWorx extension that includes an entity with the required attributes for the Audit event.

You can use the ThingWorx Extension SDK to create Java-based extensions. The SDK enables you to access supported ThingWorx Platform classes and APIs. This exposes built-in services and methods, which makes it easier to create and manage entities on the ThingWorx Platform. For more information about the available classes in the platform, refer to the Javadoc documentation.

To create an extension for Audit, follow these steps:

1. Download and install the required software.

2. Create a new extension project.

3. Create localization table entities and define tokens.

4. Import localization table entities to the extension.

5. Create a new Thing entity and a define an Audit event.

6. Enable auditing for the event.

7. Build the extension using Gradle or Ant.

8. Import the extension.

9. View the Audit message by triggering the event.

Before you Begin

Download the following software from the PTC Software Downloads page for the ThingWorx Foundation:

• Eclipse Plugin for ThingWorx Extensions

• ThingWorx Extension SDK

To install the Eclipse plug-in:

1. Open Eclipse and choose a workspace.

2. Click Help > Install New Software.

The Install window opens.

3. Click Add.

The Add Repository dialog box opens.

4. Extract the contents of the thingworxeclipse-plugin-[version].zip file to a folder with the same name, and then select the folder.

5. Under ThingWorx, select the ThingWorx Extension Builder check box, and then click Next.

6. Accept the license agreement, and then click Finish. A security message opens.

7. Click OK to confirm the installation.

8. Restart Eclipse when the installation is finished.

You can verify your installation by clicking File > New. The ThingWorx Extension Project option is available from the list.

Creating a New Extension Project

1. In Eclipse, click File > New > Project. The New Project window opens.

2. Expand ThingWorx, select ThingWorx Extension Project from the list, and then click Next.

3. Enter a name for the extension project and select the ThingWorxExtension-SDK-[version]-latest.zip file that you downloaded earlier.

4. Select Gradle or Ant as the build framework for the extension. This creates a gradle.build or a build-extension.xml file for the project, depending on your selection.

5. Enter a package version and a vendor name, and then click Finish.

The project is now listed in the Package Explorer pane.

Creating Localization Table Entities and Defining Tokens

Before you create the entity with the audit event, you must define tokens for the custom audit category and message. You can define tokens within Localization Table entities that you can include as part of the extension. When you import the extension, the specified tokens are automatically added to Localization Table entities in the ThingWorx Platform. You can create a Localization Table entity by exporting and modifying the default XML template for localization tables.

To export the Default Localization Table for English in the platform, perform the following steps:

1. In Composer, open the Import/Export menu, and then select Export.

2. Under Export Option, select To File from the drop-down list.

3. Under the Entity field, select the Default localization table.

4. Click Export.

After you exported the XML file for the Default Localization Table, open it an XML editor. You can add tokens manually to the Localization Table as Row elements under the Rows section. For example:

The following table describes the syntax of the Row element for the custom Audit category:

Element

Value

Description

name

<![CDATA[audit.AuditCategory.ExampleCustomCategory]]>

The audit.AuditCategory. part specifies the prefix to define a custom Audit category name. In this example, the prefix is followed by the following category name: ExampleCustomCategory

The category name must be unique for the platform. You cannot create two category tokens with the same name.

value

Defines the value of the custom category token. You can include alphanumeric characters, spaces, and underscores. In the example, the value is set to display the following string: Example Custom Category EN.

The following table describes the syntax of the Row element for the custom Audit message:

Element

Value

Description

name

<![CDATA[com.example.audit.ExampleCustomMessage]]>

Defines the message to display for the Audit category. You must define a prefix, and then provide a unique name for the message.

The message name must be unique for the server. You cannot create two messages with the same name.

value

<![CDATA[ExampleCustomMessageEN:Executedby__type__:__name__]]>

Defines the value of the custom category token. You can specify a simple message, or include parameters within the message. The parameters can reference a value and must be enclosed in two underscores as follows:

__type__

You should include a Localization Table for each language that your extension supports. For example, to include Japanese tokens, you must create a ja Localization Table entity and add the required tokens.

When you finish making changes to the Localization Tables, save them to a folder named LocalizationTables anywhere on your system.

Importing Localization Table Entities to the Extension

After you add the required tokens, you can import the Localization Table entities that you exported and modified in the previous section:

1. In Eclipse, open the extension project, and then click File > Import. The Import window opens.

2. Under ThingWorx, select Entities, and then click Next.

3. In the Source field, click Browse and select the LocalizationTables folder that contains your Localization Table entities.

4. Select the entities that you want to import, and then click Finish.

The entities that you selected are added under the /Entities/LocalizationTables/ folder for the extension project.

Creating a new Thing Entity and Adding an Audit Event

You can define new events by adding annotations to methods within a class. Annotated methods are imported as ThingWorx services that can be executed in the platform or the mashup at run time. To define the services for a ThingWorx entity in the Extension, perform the following steps:

1. In Eclipse, open the ThingWorx menu and select an entity type from the list.

2. Enter a source folder and a package.

3. Enter a name for the entity, and then click Next.

4. Select the Editable Extension Entity check box, and then click Finish.

The Java source file is created in the specified package under the /src folder, and the metadata.xml file is updated automatically.

Enabling Auditing for Events

You can define events in your extension that are triggered when a set of conditions is met. You can use events to trigger services with custom functionality. An event requires a predefined Data Shape. The Data Shape stores data associated with the event, which can be accessed by a subscription. You can configure ThingWorx events to log information for the Audit subsystem. To enable auditing for an event, you must assign the following aspects to the event:

• auditCategoryKey:customCategoryToken

• auditMessageKey:customMessageToken

You can only add those aspects by creating a Java code extension that adds new events, and then manually define the aspects for the event.

The next section provides an example for defining the aspects for an event.

Example: Creating Custom Audit Events

The following code shows an example for an audit event definition named ExampleAuditedEvent within a Thing Template. The event has standard properties defined, such as the name, description, category, and the implemented DataShape. The required aspects for Audit are defined in the aspects value.

For more information about the event definition, search the ThingWorx Javadoc API documentation for the following:

com.thingworx.metadata.annotations.ThingworxEventDefinition

The following code shows an event definition with the required aspects for Audit:

@ThingworxEventDefinitions{
events = {
@ThingworxEventDefinition(
name = "ExampleAuditedEvent",
description = "Event with Audit specific Aspects",
category = "Example",
dataShape = "EntityReference",
aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}
)
}
)
@ThingworxBaseTemplateDefinition(name = Thing.GENERIC_THING_TEMPLATE)
public class ExampleAuditedEventExtensionThingTemplate extends Thing {

// Customer business logic implementation

}

You can add new events to a ThingWorx entity within an extension by performing the following steps:

1. In Eclipse, right-click an entity under the src folder, and then select ThingWorx > Add Event from the context menu.

2. Enter the following information:

◦ An event name

◦ A category name

◦ The implemented Data Shape for the event. In the provided example, the value is set to EntityReference

3. Click Finish.

A new event is created for the entity and the specified annotations are added to the Java source file for the ThingWorx entity. By default, the required aspects for Audit are not defined. To enable auditing for the new event, you must define the aspects within the Java source manually as follows:

aspects = {
Aspects.ASPECT_AUDITCATEGORYKEY + ":" + "audit.AuditCategory.ExampleCustomCategory",
Aspects.ASPECT_AUDITMESSAGEKEY + ":" +
"com.example.audit.ExampleCustomMessage"
}

• audit.AuditCategory.ExampleCustomCategory—Specifies the token name for the custom category that you defined in the Default Localization Table.

• com.example.audit.ExampleCustomMessage—Specifies the token name for the custom message that you defined in the Localization Table.

Add Third-Party JAR Files

The /lib folder contains JAR files with custom Java classes written for the extension, and additional third-party JAR files that are required by the extension.

Make sure that the metadata.xml file contains an entry for each JAR file.

Do not add third-party JAR files, that are already included in the ThingWorx platform, to your extension.

Building the Extension Using Gradle

To build the extension, create a build task.

1. On the Eclipse toolbar, click the arrow next to the Run button, and select Run Configurations.

2. In the left navigation pane, right-click Gradle Task and select New Configuration.

3. Enter Build for the task configuration name.

On the Gradle Tasks tab, add the following tasks:

clean
build

You can add the task as a shortcut to the Run drop-down by selecting the Run check box on the Common tab within the Run Configurations window.

4. Select the working directory for your project, and then click Apply.

5. On the toolbar, click the Run command, and then select Build.

For older versions of Eclipse, you can also use the Gradle STS plug-in:

1. In Package Explorer, right-click the build.gradle file and select Run As > Gradle (STS) Build. A configuration window opens.

2. On the Gralde Tasks tab, add the following tasks:

clean
build

3. Click Run. A success message is logged in the Eclipse console area.

The extension ZIP file is created under the build > Distributions folder of your project. You can import this ZIP file as an extension in the ThingWorx Platform.

Building the Extension using Ant

If your extension is using Ant as a build framework, perform these steps:

1. In Package Explorer, right-click the build-extension.xml file and select Run As > Ant Build

2. Refresh your extension project.

A ZIP file is created under build > Distributions. You can import this ZIP file as an extension in the ThingWorx Platform.

Importing the Extension

1. In Composer, open the Import/Export menu, and then select Import. The Import dialog box opens.

2. Under Import Option, select Extension from the drop-down list.

3. Click Browse, then select the extension ZIP file that you created in the previous section.

4. Click Import.

The extension is imported.

Viewing the Audit Changes

In Composer, the following changes are visible:

• A new entity with an audit event is added.

• Localization tokens for the custom audit categories and messages are added to the localization tables.

To test the new custom audit category and message, execute the custom event for the entity that you added through the extension. You view the audit history by executing the QueryAuditHistory or QueryAuditHistoryWithQueryCriteria service with the appropriate parameters. For more information about the available parameters, see the topic for the implementation you are using (Direct Persistence or Data Table): Searching Audit Data (Queries, Direct Persistence) or Online and Offline Audit Data (Data Table).

Was this helpful?