Skip to main content

​
Getting Started with Connected Assets

Welcome to SensorUp’s Connected Assets module! This is where you define, organize, and manage the digital representations of all your physical and logical entities. A well-structured asset registry is the foundation for accurate emissions tracking, contextual data analysis, and streamlined operational workflows across the entire SensorUp platform.
Connected Assets allows you to build a comprehensive digital twin of your operational landscape—from individual components and equipment within a CPF or CGL, to entire facilities and wells—and understand their relationships and status over time.

​
What is an Asset in SensorUp?

In SensorUp, an Asset represents any physical or logical entity that you need to track, manage, or associate data with. This can include:
  • Facilities: Such as a Central Processing Facility (CPF), Central Gas Lift (CGL), or a well site.
  • Equipment: Pumps, compressors, separators, tanks, flares, engines located within a facility.
  • Components: Motors, seals, valves that are parts of larger equipment.
  • Wells: Production wells, injection wells, or disposal wells.
  • Linear Assets: Pipeline segments.
  • Locations & Areas: Specific operational areas, measurement points, or inspection zones.

​
Core Capabilities of Connected Assets

Connected Assets provides a rich set of features to manage your asset information effectively:
lucide:tag

Comprehensive Asset Definition & Identification

Define detailed information for each asset and identify them uniquely within SensorUp and in relation to your external systems.
  • Core Asset Attributes: Define essential properties like name, description, and assetType (e.g., “CPF”, “Pump”, “Well”).
  • Dual ID System:
    • assetId (Internal ID): A system-generated, unique, and unchangeable identifier (UUID) used by SensorUp for all internal references. This is the primary key within the platform.
    • externalIds (External IDs): A flexible list of your own identifiers (e.g., ERP IDs, legacy asset tags, Functional Location Codes - FLOCs). Each external ID has a type (e.g., “FLOC_5_PART”, “SERIAL_NO”) and a value. These can be updated and used for integration with your existing systems.
  • Detailed Characteristics: Capture rich metadata such as manufacturer, modelNumber, serialNumber, installationDate, and custom key-value customProperties specific to your needs.
  • Tagging: Apply descriptive tags (e.g., “critical-facility”, “gas-processing”, “area-A”) for easier searching, filtering, and grouping.
Track and manage the complete lifecycle of your assets from creation to disposal.
  • Status Tracking: Assign a clear operational status to each asset (e.g., DRAFT, PENDING_ACTIVATION, ACTIVE, INACTIVE, MAINTENANCE, DECOMMISSIONED).
  • Activation & Inactivation Dates:
    • activeDate: The date and time when an asset becomes (or became) operational.
    • inactiveDate: The date and time when an asset is no longer operational or is taken out of service.
  • Reason for Inactivity: Optionally record an inactiveReason for assets that are not active.
  • Versioning & Audit Trail: Track changes to asset information over time with createdAt, updatedAt, and version fields.
Organize your assets into logical hierarchies to represent physical assemblies (like equipment within a CPF), functional systems, or spatial relationships.
  • Parent-Child Relationships: Define hierarchies by assigning a parentId to an asset, linking it to another asset (e.g., a “Pump” asset linked to its parent “CPF” asset). Assets with no parentId are top-level.
  • Global Asset Hierarchy: All parent-child links form a comprehensive structure of your entire asset ecosystem.
  • Location Context: Associate assets with location information (geographic coordinates, civic addresses).
    Hierarchical relationships are primarily managed via parentId. Use location.properties for descriptive attributes of a coordinate, not for defining hierarchy.
View and interact with specific portions or perspectives of your global asset hierarchy.
  • Dynamic Hierarchy Traversal: Query the global hierarchy starting from any asset (e.g., a specific CGL), navigate up or down to a specified depth, and see summarized child counts for levels beyond the query depth.
  • Named Hierarchy Views: Define, save, and reuse specific “views” of the hierarchy. A named view can pre-set parameters like a starting rootAssetId (e.g., a particular facility) and a default depth, simplifying access to commonly used perspectives.
Connected Assets provides the essential context for sensor data, inspection results, and other observations.
  • Asset as the Subject of Observation (FeatureOfInterest): Each managed Asset in Connected Assets is typically the “thing” an observation is about (often referred to as the FeatureOfInterest). The asset’s assetId (or a dedicated featureOfInterestId if used by your observation system) is the unique identifier linking observations to the specific asset they describe.
  • Enriching Sensor Data: While time-series observation data is managed in SensorUp Datastreams, Connected Assets provides the crucial metadata (name, type, location, status, hierarchical relationships of a well, piece of equipment, or facility) to understand and interpret these observations correctly.
  • Standardized Asset Typing: Use consistent assetType values and customProperties to map to your internal or industry-specific asset classifications, enhancing data interoperability.
Programmatically manage your assets through a robust GraphQL API.
  • Core CRUD Operations: Create, read (retrieve by assetId or query lists with filters), update, and delete (decommission) assets such as facilities, equipment, or components.
  • Hierarchy Queries: Specifically query the assetHierarchy starting from root assets or named views, controlling depth and filtering.
  • Named View Management: Create, read, update, and delete NamedHierarchyView definitions.
  • Bulk Operations: Perform bulkCreateAssets, bulkUpdateAssets, and bulkDeleteAssets for efficient management.
    While this guide focuses on concepts, detailed GraphQL schema, queries, and mutations are available in the Connected Asset Management API Reference.

​
Conceptual Workflow: Building Your Asset Registry

Here’s a typical process for establishing and managing your assets—from facilities down to components—in SensorUp:
lucide:pencil-ruler

1. Define Asset Types & Attributes

Identify the different types of assets you need to manage (e.g., “CPF”, “CGL”, “Well”, “Pump”, “Compressor”, “Valve”) and the key attributes for each. Consider your externalId systems.
lucide:database-zap

2. Create or Import Assets

Use the createAsset API operation (or bulkCreateAssets) to populate your asset registry. Provide names, types, external IDs, parent IDs, locations, and other metadata for each facility, piece of equipment, well, etc.
Assets are assigned a unique, immutable SensorUp assetId upon creation.
lucide:git-fork

3. Build Hierarchies

Establish relationships: link equipment assets to their parent facility (e.g., a CPF), components to their parent equipment, and wells to their parent site or facility by setting the parentId.
lucide:history

4. Manage Lifecycle & Status

As assets are commissioned, become active, undergo maintenance, or are decommissioned, update their status, activeDate, and inactiveDate using the updateAsset API operation.
lucide:layout-list

5. Define & Use Hierarchy Views (Optional)

For frequently accessed parts of your hierarchy (e.g., all equipment within a specific CGL), create NamedHierarchyViews to simplify querying and visualization.
lucide:bar-chart-3

6. Link Observations to Assets

When ingesting sensor data or inspection results (Observations) into SensorUp Datastreams, use the assetId from Connected Assets as the primary identifier (FeatureOfInterest) to link that data to the correct facility, equipment, or well.
lucide:search

7. Query & Analyze

Utilize API queries to retrieve asset information, explore hierarchical relationships (e.g., all components of a specific pump within a facility), and provide context for data from Connected Operations and Connected Markets.

​
Role-Based Access Control

Asset management capabilities vary based on your assigned user role.
  • Viewer: Can view all assets but cannot create, update, or delete any asset information.
  • Editor: Can view all assets and manage their own assets (assets they created or are assigned to).
  • Administrator: Full CRUD (Create, Read, Update, Delete) access to all assets including facilities, equipment, components, and wells.
  • Super Admin: Complete access to all asset management features across all organizations.
For complete details on what each role can do across the platform, see the User Roles and Permissions guide.

​
Key Benefits of Connected Assets

  • Single Source of Truth: A centralized registry for all your facilities, CGLs, CPFs, wells, equipment, and components.
  • Improved Data Context: Hierarchies and rich metadata provide deep context for emissions and operational data.
  • Enhanced Analytics: Consistent asset data enables more accurate and reliable analysis.
  • Streamlined Operations: Easy access to asset information supports maintenance, inspection, and compliance workflows.
  • Foundation for Scalability: A robust asset model supports the growth of your emissions management program.

​
Next Steps

To effectively utilize Connected Assets:

Assets Technical Model

Understand the complete asset data model and technical specifications.

Connected Assets API Reference (GraphQL)

Detailed documentation for all GraphQL queries and mutations.

CAM Assets Guide

Learn how to work with the Connected Asset Management API.