> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sensorup.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Asset Audit History
> Complete audit trail tracking all changes to assets and their operational status for regulatory compliance and troubleshooting.
## What is Asset Audit History?
Asset Audit History provides a comprehensive, immutable record of every change made to your assets and their operational status. This complete audit trail ensures regulatory compliance, enables troubleshooting, and provides full transparency into who made what changes and when.
Every change tracked and logged
Audit-ready documentation
Know who changed what and when
## Why Use Asset Audit History?
**Without audit history tracking:**
No visibility into who changed asset data or status
Can't investigate why assets are excluded from reports
No compliance trail for regulatory audits
Risk of unauthorized changes going unnoticed
**With Asset Audit History:**
Complete record of all asset and status changes
Clear audit trail showing who, what, when
Quick investigation of data changes
Audit-ready compliance documentation
## Core Capabilities
Asset Audit History automatically captures every change to your assets, including:
**Asset Property Changes**
* Asset creation and initial configuration
* Updates to asset properties (name, location, type, etc.)
* Changes to extension properties and custom fields
* Asset geometry modifications
* Asset type changes
**Status Changes**
* Status creation (initial operational status)
* Status updates (active/inactive transitions)
* Status deletion (removal of status periods)
* Status overlap resolution
**Automatic Tracking:** All changes are automatically recorded by the system - no manual logging required. The audit trail is immutable and cannot be altered after creation.
Each audit entry provides comprehensive information for investigation and compliance:
| Field | Description | Purpose |
| -------------------- | ------------------------------------------------ | ------------------------------------ |
| **Event Type** | Type of change (Created, Updated, Deleted, etc.) | Understand what action occurred |
| **Event Time** | Precise timestamp of the change | Track when changes happened |
| **User** | Who made the change (user ID and name) | Accountability and investigation |
| **Property Changes** | Detailed before/after values for each property | See exactly what changed |
| **Status Changes** | Complete status change history by status ID | Track operational status transitions |
| **Version** | Sequential version number | Understand change sequence |
| **Correlation ID** | Link related changes together | Track bulk operations |
See exactly what changed with detailed before-and-after comparison:
### Old and New Values
* **Old Value**: The property value before the change (null for newly created properties)
* **New Value**: The property value after the change (null for deleted properties)
* **Property Type**: Data type (string, number, boolean, datetime, geometry, JSON)
### Property Source Identification
* **Asset Properties**: Grouped by asset type (site, well, facility, etc.)
* **Status Properties**: Grouped by status ID for status changes
* **Extension Properties**: Custom fields and extensions tracked separately
**Status Changes:** When an asset is set to "Inactive," the audit history provides the critical trail showing who made the change and when, explaining why detections from that asset are excluded from reports.
## Common Use Cases
**Investigating Excluded Assets**
When an asset's detections aren't appearing in reports, check the audit history to see who set it to "Inactive" status and when. This helps you understand whether the exclusion is correct or needs to be addressed.
**Regulatory Compliance**
Generate complete audit trails showing all asset and status changes for regulatory submissions. The immutable audit log provides defensible documentation for compliance audits.
**Troubleshooting Data Issues**
When asset data appears incorrect or inconsistent, review the audit history to see what changes were made, by whom, and when. This helps identify the source of data issues quickly.
**Tracking Integration Changes**
Monitor changes made by system integrations (marked as "System" user) to ensure your source-of-truth systems are correctly synchronizing asset data.
**Annual Data Audits**
Review the complete history of asset status changes and property updates to maintain comprehensive compliance records and verify data integrity.
## Viewing Asset Audit History
**Access Requirements:** Audit history is available to all authenticated users who have permission to view the asset.
From the **Assets** section, select the asset you want to investigate to open its details page.
Select the **History** tab to view the complete audit trail for this asset.
The history shows all changes in reverse chronological order (most recent first).
Each audit entry shows:
* **What Changed**: Event type and property changes
* **When**: Precise timestamp of the change
* **Who**: User who made the change (or "System" for automated changes)
* **Details**: Before and after values for each changed property
Use filters to narrow down the audit trail:
* Filter by event type (e.g., only status changes)
* Filter by date range (e.g., changes in last quarter)
* Filter by user (e.g., changes by specific person)
### Understanding Change Events
**ASSET\_CREATED**
* Recorded when an asset is first created
* Shows all initial property values
* Old values are null (no previous state)
**ASSET\_UPDATED**
* Recorded when any asset property is modified
* Shows before and after values for changed properties
* Includes property name, type, and source partition
**ASSET\_DELETED**
* Recorded when an asset is removed
* Shows all final property values
* New values are null (no new state)
**STATUS\_CREATED**
* Recorded when a new status period is added
* Shows all status properties (start date, end date, reason, etc.)
* Critical for understanding when assets became active/inactive
**STATUS\_UPDATED**
* Recorded when an existing status period is modified
* Shows before and after values for changed status properties
* Includes status ID for identifying which period changed
**STATUS\_DELETED**
* Recorded when a status period is removed
* Shows all properties of the deleted status
* Provides audit trail for removed status periods
**Key Insight:** Status changes are grouped by status ID, making it easy to track the complete lifecycle of each operational status period.
**System Changes**
* Made by automated integrations
* User shown as "System" or integration name
* Typically property updates from source systems
**User Changes**
* Made by authenticated users
* Shows user ID and full name
* Typically manual updates or status changes
**Critical Status Changes**
* Setting assets to "Inactive" (most important user action)
* Creates audit trail explaining why detections are excluded
* Essential for compliance and troubleshooting
## Using Audit History via API
### Query Asset Audit History
```graphql theme={null}
query GetAssetAuditHistory($assetId: ID!, $assetTypeId: ID!) {
asset(id: $assetId, assetTypeId: $assetTypeId) {
id
name
auditing {
history(
assetId: $assetId
assetTypeId: $assetTypeId
filter: {
eventTypes: [ASSET_UPDATED, STATUS_UPDATED]
fromTime: "2024-01-01T00:00:00Z"
toTime: "2024-12-31T23:59:59Z"
}
) {
eventType
version
eventTime
user {
userId
userName
}
correlationId
assetPropertyChanges {
propertySourcePartition
propertyName
propertyType
oldValue {
... on StringValue { value }
... on NumberValue { value }
... on BooleanValue { value }
}
newValue {
... on StringValue { value }
... on NumberValue { value }
... on BooleanValue { value }
}
}
statusChanges {
id
propertyChanges {
propertyName
propertyType
oldValue { ... on StringValue { value } }
newValue { ... on StringValue { value } }
}
}
}
}
}
}
```
### Query Only Status Changes
```graphql theme={null}
query GetAssetStatusHistory($assetId: ID!, $assetTypeId: ID!) {
asset(id: $assetId, assetTypeId: $assetTypeId) {
id
auditing {
history(
assetId: $assetId
assetTypeId: $assetTypeId
filter: {
eventTypes: [STATUS_CREATED, STATUS_UPDATED, STATUS_DELETED]
}
) {
eventType
eventTime
user {
userName
}
statusChanges {
id
propertyChanges {
propertyName
oldValue { ... on StringValue { value } }
newValue { ... on StringValue { value } }
}
}
}
}
}
}
```
**GraphQL Federation:** Asset Audit History is available through the GraphQL API with full federation support. See [GraphQL API documentation](/api/graphql/overview) for authentication and query details.
## FAQ / Troubleshooting
Assets created before the audit history feature was implemented may not have historical data. The system automatically initializes audit tracking when you first access the history for legacy assets, creating a baseline event. All changes going forward will be tracked.
1. Go to the asset's **History** tab
2. Filter by event type: **STATUS\_CREATED** or **STATUS\_UPDATED**
3. Look for entries where the status changed to "INACTIVE"
4. The **User** field shows who made the change
5. The **Event Time** shows exactly when it happened
6. Review **Property Changes** to see the status reason
This information is critical for understanding why an asset's detections are excluded from reports.
No. The audit trail is immutable by design. Once a change is recorded, it cannot be altered or deleted. This ensures the integrity of your audit records for regulatory compliance and forensic investigation.
* **System changes**: Made by automated integrations syncing data from your source-of-truth systems (e.g., Maximo, SAP). Most asset property updates come from these integrations.
* **User changes**: Made by authenticated users manually updating asset data or status. The most important user action is setting assets to Active/Inactive status.
For assets created after the audit history feature was deployed, the complete history is available from the asset's creation. For legacy assets, history begins when the audit system was initialized for that asset (typically when first accessed) or when the audit history feature was activated.
* **Old value is null**: The property was newly created (e.g., ASSET\_CREATED event or new property added)
* **New value is null**: The property was deleted (e.g., ASSET\_DELETED event or property removed)
* This is normal and helps distinguish between creation, updates, and deletions
A correlation ID links related changes together, especially during bulk operations or batch imports. When you see the same correlation ID on multiple audit entries, it means those changes were part of the same operation or transaction. This helps you understand the context of changes.
Yes. You can use the GraphQL API to query audit history and export the data to your preferred format for compliance reporting. The API provides complete access to all audit trail information including timestamps, users, and property changes.
## System Architecture
Asset Audit History uses an **event sourcing pattern** with immutable event logs:
* **Event Store:** DynamoDB table stores all audit events as immutable records
* **Automatic Tracking:** Every asset mutation automatically creates audit events
* **Event Types:** Comprehensive coverage of all asset and status lifecycle events
* **Property-Level Changes:** Detailed before/after tracking for every property
* **Performance Optimized:** Efficient querying with indexed event streams
## Event Sourcing Benefits
* **Complete History:** Every state change is preserved permanently
* **Immutable Records:** Audit trail cannot be altered after creation
* **Temporal Queries:** Query asset state at any point in time
* **Compliance Ready:** Audit trail meets regulatory requirements
* **Debugging Power:** Full history available for troubleshooting
## Data Retention
Audit history is retained indefinitely by default. All events are stored in the event store with:
* Sequential version numbers for ordering
* Precise timestamps for temporal analysis
* Complete property change information
* User attribution and correlation IDs
This architecture ensures reliable, audit-ready data while maintaining excellent query performance.
## Key Benefits
**Regulatory Confidence**
Meet regulatory requirements with complete, immutable audit trails documenting every asset and status change with full user attribution.
**Quick Investigation**
Rapidly troubleshoot data issues by reviewing exactly what changed, who made the change, and when it occurred, eliminating guesswork.
**Data Integrity**
Ensure accountability and prevent unauthorized changes with comprehensive tracking of all asset modifications and status updates.
**Transparency**
Provide full visibility into asset data lifecycle for auditors, compliance officers, and operational teams with detailed change history.
***
## Next Steps
Learn about managing operational status and how status changes appear in audit history.
Understand the complete asset data model and what properties are tracked in audit history.
Access audit history programmatically through the GraphQL API for custom integrations.