ThingWorx Audit Messages
This topic provides details about the content of ThingWorx audit messages in the following sections:
Types of Audit Messages
The Audit Subsystem generates messages for different activities in the ThingWorx Platform. The messages fall into the following general types:
• Changes to an Object—Auditing of changes such as creation, deletion, or modification of an entity. The entity may be a Thing or a non-Thing, such as a subsystem or organization.
• Changes to Users—Auditing of changes such as creation or modification of a user or application key.
• Operations on an Object—Auditing of operations on an entity. Examples include remote session activity (tunneling) on a Thing.
• Operations on the System—Audits where no target object exists for the message, such as user login and import/export operations.
Audit messages contain audit entries, which provide the information about the activity.
 |
For information on auditing a switch in security context, see Auditing the Switching of Security Context .
|
Audit Entries
Each audit entry is comprised of two components, an Audit Category Key and an Audit Message Key:
• The Audit Category Key is a localization token that specifies the functional area, or category, with which the audit message is associated. This key is a STRING. For a list of categories, see .Audit Categories
• The Audit Message Key is a localization token that points to the text of the audit message. This key is a STRING.
The value for each component is pulled from the corresponding, built-in event definition or instance. Note that auditing of user-defined events is not supported.
Audit Message Arguments
The audit message provides arguments that are used to generate a localized text message and the name of the entity that performed the operation. A ValueCollection of substitution name/value pairs is used to generate the localized text message. This information is retrieved from the eventData fields of the event instance. A ThingWorx entity, such as a Thing or a user, is associated with an audit message, including who or what performed the operation that is the subject of the audit message.
Audit Categories
All audit entries are associated with an audit category. Audit categories make it very easy to filter audit data and look at a trend of activities for a certain category of operations. In addition, audit categories can help you to detect attempts at unauthorized access or problems with an edge device not being able to connect to your ThingWorx Platform.
Each audit entry has a single category, which is stored as a string with the audit entry. The displayed audit category string is localized. Based on the user's preferred locale, the audit category is displayed in the appropriate language.
The following table lists and briefly describes the categories available in the audit subsystem.
|
Category
|
Description
|
Examples
|
Localization Token
|
||
|---|---|---|---|---|---|
|
ANALYTICS
|
Actions related to analytics entities. Operations performed by ThingWorx Analytics.
|
Create, edit, delete operations on data analysis definitions.
Other actions within ThingWorx Analytics.
|
audit.AuditCategory.Analytics
|
||
|
AUTHENTICATION
|
Actions related to authentication.
|
Successful and unsuccessful user login, user locked out, and errors related to using application keys. For example: Login successful for user: Administrator.
|
audit.AuditCategory.Authentication
|
||
|
COLLABORATION
|
Actions related to collaboration entities.
|
Create, edit, and delete operations on blogs and wikis.
|
audit.AuditCategory.Collaboration
|
||
|
DATA_MANAGEMENT
|
Actions related to managing or using data.
|
Delete operations on data.
|
audit.AuditCategory.DataManagement
|
||
|
DATA_STORAGE
|
Actions related to data storage entities and related subsystems.
|
Create, edit, and delete operations on data tables, streams, and other data storage entities.
|
audit.AuditCategory.DataStorage
|
||
|
DEVICE_COMMUNICATION
|
Action related to communication with edge devices.
|
The CloseWebSocketSessions service of the WSCommunicationSubsystem is audited. For details about the service, refer to the "Services" section of the topic, WebSocketCommunications Subsystem.
.
|
audit.AuditCategory.DeviceCommunication
|
||
|
FILE_TRANSFER
|
Actions and events related to file uploads and downloads.
|
For file transfers, successful completion of a transfer, cancellation of a transfer, and generation of errors during a transfer.
|
audit.AuditCategory.FileTransfer
|
||
|
IMPORT_EXPORT
|
Actions related to import and export of data to and from ThingWorx.
|
Model and data import/export operations.
Import of an extension.
|
audit.AuditCategory.ImportExport
|
||
|
LIFECYCLE
|
Actions related to a Thing-specific event, such as ThingStart
|
ThingStart event
|
audit.AuditCategory.Lifecycle
|
||
|
MODELING
|
Actions related to Modeling entities. When an entity is created, the system generates an audit message that includes the Owner assigned to the new entity. Note that the Owner of an entity is set automatically to the user name that created the entity.
The system generates the audit message when any of the ways to create an entity is used:
• Through PUTcall in Composer
• Through a call to a Create API, a Clone API, or to the SetOwnerAPI
Any user who is authorized to view the Audit subsystem can view reports regarding changes in ownership.
|
Create, edit, delete operations on Things, Thing Templates, Thing Shapes, Data Shapes, networks, projects, models, tags.
The format of the audit message is:
"Created <Source Type> <Source> with owner <username of owner>."
Where:
• Source Type is the kind of entity created. For example, a Thing.
• Source is the name of the new entity.
• The owner shows the username of the user performing the create action.
|
Category Key: audit.AuditCategory.Modeling
Message key is: audit.EntityLifecycle.Create.
|
||
|
REMOTE_ACCESS
|
Actions related to remote access (tunneling).
|
Session start/end (TunnelSession event), cancel session.
|
audit.AuditCategory.RemoteAccess
|
||
|
SCM (Software Content Management)
|
Actions related to packages, deployments, and configuration changes.
|
Create, edit, publish, and delete packages. Create, start, transition, and delete deployments. Includes test and actual deployments, assets specified for a test deployment, and the success or failure of package installation. Configuration changes for automatic purging and for concurrent deployments.
|
audit.AuditCategory.SoftwareManagement
|
||
|
SECURITY_CONFIGURATION
|
Actions related to security entities and permissions, including users, user groups, Thing Groups, organizations, application keys, directory services, and authenticators.
Whenever the ownership changes for an entity, an audit message is generated. An Owner can be changed through Composer, through an API call, or through an import of an entities XML file
An ownership audit message is not generated in the following cases:
• The Audit subsystem is disabled.
• The entity has been updated without ownership changes.
• The SetOwner API call set the same owner that was already the owner of the entity.
|
Create, edit, and delete operations on users, user groups, Thing Groups, organizations, application keys, directory services, and authenticators.
Enables tracking of UserGroup changes. The audit.Groups.Added entry is generated whenever a User or UserGoup is added as a member of another User Group. The audit.Groups.Removed entity is generated whenever a User or User Group is removed from a User Group.
Entity permission changes (all entity types). Refer to the section above, Auditing the Switching of Security Context..
The general format of the ownership change audit message follows:
"Owner for <Source Type> <Source> changed from <original owner username> to <new owner username>."
Where:
• Source Type is the kind of entity whose owner has changed. For example, a Thing.
• Source is the name of the entity whose owner has changed.
• The original owner username shows the username of the user performing the change action.
• The new owner username is the username of the new owner.
|
Category Key: audit.AuditCategory.SecurityConfiguration
Message Keys:
• audit.Groups.Added
• audit.Groups.Removed
• audit.entity.ownership.change
|
||
|
Administrator enabling and disabling Thing Group visibility permission delegation in User Management Subsystem
|
The audited operations and audit messages follow:
• Administrator enabled Thing Group visibility permission delegation in User Management Subsystem — audit message is "Thing Group visibility permission delegation enabled."
• Administrator disabled Thing Group visibility permission delegation in User Management Subsystem — audit message is "Thing Group visibility permission delegation disabled."
|
Category Key: audit.AuditCategory.SecurityConfiguration
Message Keys:
• com.thingworx.thinggroups.ThingGroup.VisibilityPermissionDelegationEnabled
• com.thingworx.thinggroups.ThingGroup.VisibilityPermissionDelegationDisabled
|
|||
|
SYSTEM
|
Actions related to system entities.
|
Create, edit, and delete operations on localization tables, resources, subsystems, and logs.
Subsystem configuration changes and actions, including start, stop, and restart. All subsystem-related entries are in this category and will not appear at all in other categories.
|
audit.AuditCategory.System
|
||
|
VISUALIZATION
|
Actions related to Visualization entities.
|
Create, edit, and delete operations on mashups, masters, gadgets, dashboards, menus, media entities, style definitions, and state definitions.
|
audit.AuditCategory.Visualization
|
