> ## 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.

# Getting Started: Mastering Your Connected Assets

> Learn to define, manage, and visualize your asset hierarchies in SensorUp's Connected Assets module. Understand asset IDs, lifecycles, hierarchy views, and their role in contextualizing observations.

# 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.

<Info>
  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.
</Info>

## 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:

<AccordionGroup>
  <Accordion title="Comprehensive Asset Definition & Identification" icon="lucide:tag" defaultOpen={true}>
    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.
  </Accordion>

  <Accordion title="Asset Lifecycle Management" icon="lucide:recycle">
    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.
  </Accordion>

  <Accordion title="Hierarchical Asset Structuring" icon="lucide:network">
    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).
      <Note>Hierarchical relationships are primarily managed via `parentId`. Use `location.properties` for descriptive attributes of a coordinate, not for defining hierarchy.</Note>
  </Accordion>

  <Accordion title="Flexible Hierarchy Views & Traversal" icon="lucide:eye">
    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.
  </Accordion>

  <Accordion title="Context for Observations & Measurements" icon="lucide:ruler">
    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.
  </Accordion>

  <Accordion title="API-Driven Management (GraphQL Focused)" icon="lucide:code-2">
    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.
      <Info>While this guide focuses on concepts, detailed GraphQL schema, queries, and mutations are available in the [Connected Asset Management API Reference](/api/graphql/subgraphs/assets).</Info>
  </Accordion>
</AccordionGroup>

## Conceptual Workflow: Building Your Asset Registry

Here's a typical process for establishing and managing your assets—from facilities down to components—in SensorUp:

<Steps titleSize="h3">
  <Step title="1. Define Asset Types & Attributes" icon="lucide:pencil-ruler">
    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.
  </Step>

  <Step title="2. Create or Import Assets" icon="lucide:database-zap">
    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.
    <Note>Assets are assigned a unique, immutable SensorUp `assetId` upon creation.</Note>
  </Step>

  <Step title="3. Build Hierarchies" icon="lucide:git-fork">
    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`.
  </Step>

  <Step title="4. Manage Lifecycle & Status" icon="lucide:history">
    As assets are commissioned, become active, undergo maintenance, or are decommissioned, update their `status`, `activeDate`, and `inactiveDate` using the `updateAsset` API operation.
  </Step>

  <Step title="5. Define & Use Hierarchy Views (Optional)" icon="lucide:layout-list">
    For frequently accessed parts of your hierarchy (e.g., all equipment within a specific CGL), create `NamedHierarchyView`s to simplify querying and visualization.
  </Step>

  <Step title="6. Link Observations to Assets" icon="lucide:bar-chart-3">
    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.
  </Step>

  <Step title="7. Query & Analyze" icon="lucide:search">
    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.
  </Step>
</Steps>

## 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.

<Info>
  For complete details on what each role can do across the platform, see the [User Roles and Permissions](/use-sensorup/user-management/User-roles-permissions) guide.
</Info>

## 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:

<CardGroup cols={2}>
  <Card title="Assets Technical Model" icon="cube" href="/use-sensorup/assets/assets-model">
    Understand the complete asset data model and technical specifications.
  </Card>

  <Card title="Connected Assets API Reference (GraphQL)" icon="book" href="/api/graphql/subgraphs/assets">
    Detailed documentation for all GraphQL queries and mutations.
  </Card>

  <Card title="CAM Assets Guide" icon="code" href="/api/graphql/guides/cam-assets">
    Learn how to work with the Connected Asset Management API.
  </Card>
</CardGroup>