Create/Update asset instances

When creating an asset instance, you always begin by instantiating the root node of the asset (e.g., site, powerplant, vessel). All child systems are created beneath this root.

API

Base URL: https://api.veracity.com/veracity/mms/ingest

Explore the API.

Each request operates within a tenant, and therefore {tenant} must be included in the path of every endpoint. In all examples below, replace {tenant} with your tenant alias.

Authentication and a subscription key are required for each API request, see details..

Create root node

When creating an asset instance in the Asset Registry, the root node must always be created first. To create a new root node asynchronously, use:

POST {baseurl}/{_tenant_}/api/v1/roots
request body:
{
  "externalRootId": "string",
  "name": "string",
  "dwWorkspaceId": "string",
  "type": "string",
  "technology": "string",
  "properties": [
    {
      "name": "string",
      "unit": "string",
      "value": "string"
    }
  ],
  "signals": [
    {
      "name": "string",
      "signalId": "string",
      "alternativeId": "string",
      "unit": "string"
    }
  ],
  "childSystems": [
    {
      "externalId": "string",
      "name": "string",
      "type": "string",
      "properties": [
        {
          "name": "string",
          "unit": "string",
          "value": "string"
        }
      ],
      "signals": [
        {
          "name": "string",
          "signalId": "string",
          "alternativeId": "string",
          "unit": "string"
        }
      ],
      "childSystems": [
        "string"
      ]
    }
  ]
}

Request property	Description
externalRootId	ID of the root system from the source system. Must be unique. If omitted, an ID is generated and can later be used for updates.
name	Name of the root system (e.g., Site, Powerplant).
type	System type. Must exist in taxonomy
technology	Technology defined in the taxonomy (e.g., Solar, Wind).
dwWorkspaceId	Workspace ID (GUID) from Data Workbench for access control
properties	Array of property values based on the taxonomy. Each property must reference a valid property name. value must be provided in a unit allowed by the datatype.
signals	Optional. Array of timeseries metadata (defined in taxonomy). SignalId is id from source system. signalId may be null; if omitted, a signal ID is generated. Alternative id is optional. Unit represents the unit used for the timeseries
childSystems	Optional. Array of child systems with the same structure as the root.

Response:

• 201 Created with Location header
• 409 Conflict if externalRootId already exists
• Returns a job ID for asynchronous processing

Create root node synchronous

To create a new root with a synchronous call, use this endpoint:

POST {baseurl}/{_tenant_}/api/v1/roots/sync

Use the same request body as for the asynchronous endpoint. Returns 201. Returns 409 Conflict if externalRootId already exists.

Update asset instance root node

Updates an existing root system.

To update a root node, use this endpoint:

PUT {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}
request body
{
  "name": "string",
  "type": "string",
  "technology": "string",
  "properties": [
    {
      "name": "string",
      "unit": "string",
      "value": "string"
    }
  ],
  "signals": [
    {
      "name": "string",
      "signalId": "string",
      "alternativeId": "string",
      "unit": "string"
    }
  ]
}

rootNodeId accepts either external or internal ID. Response:

• 204 No Content on successful update
• 404 Not Found if root node does not exist

Create a child system

To create a child system beneath a root node:

POST {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}/systems
Request body
{
  "externalId": "string",
  "name": "string",
  "type": "string",
  "technology": "string",
  "parentSystemId": "string",
  "dwWorkspaceId": "string",
  "properties": [
    {
      "name": "string",
      "unit": "string",
      "value": "string"
    }
  ],
  "signals": [
    {
      "name": "string",
      "signalId": "string",
      "alternativeId": "string",
      "unit": "string"
    }
  ]
}

rootNodeId accepts either external or internal ID.

Request body	Description
externalId	ID of the system from the source system. Must be unique within the asset. If omitted, an ID is generated.
name	Name of component (i.e. Inverter 1)
type	System type defined in taxonomy.
technology	Technology defined in taxonomy.
parentSystemId	ID of the parent node. If omitted, the root becomes the parent.
properties	array of properties from taxonomy where name is property name from taxonomy. value is actual value and unit is one of allowed units
signals	Array of time-series metadata (defined in taxonomy) that exists on this instance. SignalId is id from source system. signalId may be null; if omitted, a signal ID is generated. Alternative id is optional. Unit represents the unit used for the time series

Update a child system

When updating a child system, you may update one or multiple properties or one or multiple signals.

rootNodeId accepts either external or internal ID. systemId accepts either external or internal ID.

Patch a single property by name

PUT {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}/systems/{systemId}/properties/{name}
{
  "unit": "string",
  "value": "string"
}

name is property name (name or shortId from taxonomy)

Patch multiple properties

PUT {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}/systems/{systemId}/properties

{
  "properties": [
    {
      "name": "string",
      "unit": "string",
      "value": "string"
    }
  ]
}

Patch a single signal by name

PUT {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}/systems/{systemId}/signals/{name}

{
  "signalId": "string",
  "alternativeId": "string",
  "unit": "string"
}

name is signal name (name or shortId from taxonomy)

Patch multiple signals

PUT {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}/systems/{systemId}/signals/update

{
  "signals": [
    {
      "name": "string",
      "signalId": "string",
      "alternativeId": "string",
      "unit": "string"
    }
  ]
}

Delete

Deleting a system removes the system and all of its descendant nodes.

rootNodeId accepts either external or internal ID.

To delete a root system use endpoint:

DELETE {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}

To delete any child in an asset model use endpoint:

DELETE {baseurl}/{_tenant_}/api/v1/roots/{rootNodeId}/systems/{systemId}

systemId accepts either external or internal ID.