Auditing of configuration changes in SmartSpace
Use the ubisense_audit_archive command-line tool to capture SmartSpace configuration changes, and who made them, to a named file. You can get messages for configuration changes made by users, either in SmartSpace Config or in command-line tools used for configuration. This includes changes to types and their associated properties defined in the TYPES / OBJECTS tab of SmartSpace Config in the User data model class. Changes that normally happen as a result of RTLS tracking or business rule execution are not logged, for example object location or property value changes.
You can see all available classes of message by running ubisense_audit_archive with the list-message-classes parameter. An archive file can include all auditable changes, or you can restrict its contents to one class of message.
Audit data is written to a file which lists a time, message class, user and description for each logged change. At the end of the file, the last archived message time is recorded so that subsequent changes can be appended to the file without duplication.
Requirements
The ability to audit SmartSpace configuration requires SmartSpace version 3.10 or later. The following are also required.
ubisense_audit_archive Tool
See How to get ubisense_audit_archive for information on downloading the ubisense_audit_archive command-line tool.
Ubisense Services
Audit logging is available when the Audit log data service is enabled in Service Manager.
Service security Configuration
To identify users who have made changes, you must configure schema-level security, and add a list of users, using Security Manager. Otherwise, you will see only "default" in place of user names in the audit log.
See Ubisense Security Manager for further information.
How to get ubisense_audit_archive
You can download ubisense_audit_archive using the Ubisense Application Manager. It can be found in the DOWNLOADABLES task under Ubisense > Platform > Audit admin tools.
Help for downloading the tool >>
Using ubisense_audit_archive
Usage
ubisense_audit_archive [OPTIONS] <file>
or
ubisense_audit_archive list-message-classes
Parameters and Options
| Parameter | |
|---|---|
| file | The archive file to create or append to |
| Options | |
|---|---|
| -c, --class <message class> |
Only consider messages from the given class Enclose multi-word message classes in double quotes |
| -d, --delete | Delete archived messages from the audit server |
| -e, --end-time <YY-MM-DD-hh-mm-ss> | Include messages before the given time (default = now) |
| -s, --start-time <YY-MM-DD-hh-mm-ss> | Include messages after the given time (default = existing file end time, otherwise include all) |
| -u, --utc-offset <+/-hh:mm> | Assert that the times entered are local times at the given UTC offset (default = current UTC offset) |
| --help | Display help for the command and exit |
| --version | Display version information and exit |
Running ubisense_audit_archive
To create or update an archive file, run ubisense_audit_archive with a filename. If the command runs successfully, a message displays indicating the number of messages archived between two times. For example:
C:\Ubisense>ubisense_audit_archive full-audit.txt Archived 184 messages from Thu Jan 1 00:00:00 1970 to Wed Jul 9 09:40:27 2025.
If the archive file is new and no start time is requested (using the --start-time option), the start time will be 00:00:00 on Jan 1 1970. For an existing archive file if no start time is given, the start time will be the time of the last logged message in the file.
The archive file is in CSV format.
"Time","Class","User","Message","Created by user?" "Wed Jun 25 10:36:58 2025","Config Params","default","created Logging / LogRootDirectoryDefault with value","n" "Wed Jun 25 10:36:59 2025","Config Params","default","created External Object Information Transfer / ForwardingRole with value source","n" "Wed Jun 25 10:36:59 2025","Config Params","default","created Product Data Aggregator / LogRootDirectory with value","n" ... ... ... "Wed Jun 25 11:25:28 2025","User data model","default","property [Custom]extent<[Custom]Person> was created","n" "Wed Jun 25 11:25:28 2025","Spatial properties","default","spatial role UDM::Role::[Custom]extent<[Custom]Person> was created","n" "Wed Jun 25 11:26:18 2025","Spatial properties","default","UDM::Role::[Custom]extent<[Custom]Person> shape was added for UserDataModel::[Custom]Person","n" "Wed Jun 25 11:27:48 2025","Cells","default","ULocation::Cell:04007zeG4143hxYj0001tW0005Z extent was changed","n" "Wed Jun 25 11:27:53 2025","Cells","default","USpatial::Cell:04007zeG2kT5KVdI000Ljm000Qj extent was changed","n" ... ... ... "Tue Jul 1 11:27:32 2025","Users and roles","default","Ubisense.SmartSpace.Administrator role permission to view UCell::Cell:04007zeDS6oB7EC4000VRG00002 was added","n" "Tue Jul 1 11:27:40 2025","Users and roles","default","Ubisense.SmartSpace.Administrator role permission to use Tags search was added","n" 1751970896808759701
For each message a time, message class, user and description are given. (The final column "Created by user?" can only be 'y' for a message manually created by a user in ACS.)
The final line of the archive file gives the time of the last audit message (in UTC) to enable new messages to be appended without duplication on subsequent use of the command with this file.
To limit the contents of an archive file to a single class, use the --class option. For example, changes to the user data model only can be logged using:
ubisense_audit_archive --class "User data model" UDM-audit.txt
As in the example above, any message class names containing spaces must be contained within double quotes.
Listing Available Message Classes
Running the command ubisense_audit_archive list-message-classes displays a table of message classes and descriptions:
C:\Ubisense>ubisense_audit_archive list-message-classes | Message Class | Description | ---------------------------------------------------------------------------------------------------- | Assertion store | Changes to the assertion store configuration | | Business rules | Changes to published business rules | | Cells | Changes to cell configuration | | Co-located objects | Co-located objects service parameter changes | | DIMENSION4 | Changes to the DIMENSION4 RTLS configuration | ... ... ... | Tags | Changes to tag types and tag associations | | User data model | Changes to the user data model of object types and properties | | Users and roles | Changes to users and roles | | Web forms | Changes to web form configuration |
Managing Audit Data
By default, the server cleans up audit data internally and limits the amount of audit data stored to a maximum of 20 MB. In general, you can ignore the fact that auditing exists and the system should work without intervention. However, you can change the maximum amount of audit data that is stored, and also manually remove data as it is archived.
Setting the Maximum Size of the Audit Log
To prevent the audit file becoming excessively large, you can specify a maximum size using the audit_log_max_bytes configuration parameter. By default, this is 20000000 (20 MB). To change the maximum size of the audit file, use the ubisense_configuration_client command-line tool. For example, to set the maximum size to 5 MB, use the command:
ubisense_configuration_client set audit_log_max_bytes 5000000
Deleting Audit Messages when Adding to an Archive File
In addition to the automatic clean up of the audit file, described above, you can also delete archived messages from the server when you run ubisense_audit_archive. Running the command with the --delete option means that when this invocation of the tool writes a message to the output file, it permanently deletes that same message from the Ubisense dataset.
C:\Ubisense>ubisense_audit_archive --delete full-audit.txt Archived 200 messages from Thu Jan 1 00:00:00 1970 to Wed Jul 9 13:08:39 2025.
Excluding Users' Activity from the Audit Log
You can also exclude the activities of a user, or several users, from the audit process using a configuration parameter, audit_ignore_user_substring. By default, changes made by any authenticated user whose name is, or contains, [Automated] are not logged. Use the command:
ubisense_configuration_client set audit_ignore_user_substring <username_to_be_ignored>
to change the parameter so that changes made by all users whose user names contain <username_to_be_ignored> are excluded from audit.