Cognite

The Cognite connection connects to a Cognite Data Fusion (CDF) project. It reads assets and time series from CDF data models, and writes Intelligence Hub models and instances to CDF as time series, views, and assets.

Connection Settings

The connection authenticates with the OAuth 2.0 client credentials flow.

SettingDescription
Base URLThe base URL of the CDF cluster (ex. https://api.cognitedata.com or https://westeurope-1.cognitedata.com).
ProjectThe CDF project to connect to.
Token URLThe OAuth 2.0 token endpoint of the identity provider used to authenticate with CDF. For Microsoft Entra ID this is https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token. The token is requested with the scope <Base URL>/.default (ex. https://api.cognitedata.com/.default).
Client IDThe OAuth 2.0 client ID of the application registered with the identity provider.
Client SecretThe OAuth 2.0 client secret of the application registered with the identity provider.

Inputs

Inputs read time series or assets. Both input types read back the latest value, and can optionally include metadata

Read Type: Time Series

Reads the latest value of one or more time series. The result is an object keyed by the time series external ID.

SettingDescription
Instance SpaceThe space that holds the time series.
Time SeriesThe external IDs of the time series to read.
Include MetadataWhen enabled, each time series is returned as an object with its value under value and its metadata under _metadata.
{
  "Pump_1_pressure": 41.7,
  "Pump_1_motor_speed": 1785
}

A time series that does not exist in the space is returned with bad quality. A time series that exists but has no datapoints is returned as good with no data.

When Include Metadata is enabled, each time series is returned with the properties of its CogniteTimeSeries node (ex. name, description, unit, type) under _metadata. Time series created by the Intelligence Hub also include their extractedData.

{
  "Pump_1_pressure": {
    "value": 41.7,
    "_metadata": {
      "name": "Pump_1_pressure",
      "description": "Discharge pressure",
      "type": "numeric",
      "isStep": false,
      "extractedData": {
        "location": "Line 1"
      }
    }
  }
}

Read Type: Assets

Reads assets through a view. The result contains the properties of the view. Properties that are relations to time series are replaced with the latest value of the time series, and all other properties are returned as is.

SettingDescription
Instance SpaceThe space that holds the assets.
External IDThe external ID of the asset to read. Leave blank to read every asset in the space that has data in the view, up to 1000. A single asset is returned as an object, and multiple assets as an array of objects. If the asset is not found or has no data in the view, the read fails.
ViewThe external ID of the view to read the assets through.
View SpaceThe space that holds the view. Defaults to the Instance Space when left blank.
View VersionThe version of the view. Defaults to the latest version when left blank.
Include MetadataWhen enabled, each asset is returned as an object with its value under value and its metadata under _metadata.

Below is an example read of an asset written by the Asset output.

{
  "_name": "Pump_1",
  "_model": "Pump",
  "pressure": 41.7,
  "motor_speed": 1785
}

When Include Metadata is enabled, the asset’s space and external ID are returned under _metadata, along with its parent’s space and external ID when it has a parent.

{
  "value": {
    "_name": "Pump_1",
    "_model": "Pump",
    "pressure": 41.7,
    "motor_speed": 1785
  },
  "_metadata": {
    "space": "plant_instances",
    "externalId": "Pump_1",
    "parentSpace": "plant_instances",
    "parentExternalId": "Line_1"
  }
}

Outputs

Outputs write to time series, write metadata to existing time series, or write models and instances as views and assets linked to their time series. Time series, views, and assets can optionally be created when they don’t exist.

Write Type

Specifies the type of write. The different types are described below.

Write TypeDescription
Time SeriesWrites each attribute of the payload to a time series, and optionally creates the time series.
AssetWrites each attribute of the payload to a time series, and optionally creates the view for the model and an asset for each instance, linked to its time series.
Time Series MetadataWrites metadata (ex. description, unit) to existing time series.

Write Type: Time Series

Time Series writes flatten the payload and write each attribute to a time series. The time series external ID is the instance name (_name) followed by the attribute path, joined by the Delimiter. If the payload has no _name, the external ID is only the attribute path. No views or assets are created.

SettingDescription
Create OptionWhen set to Off, datapoints are written to existing time series by external ID and nothing is created. When set to Create, the instance space and any missing time series are created. Existing time series are never changed.
Instance SpaceThe space that holds the time series.
DelimiterThe delimiter used to join the instance name and attribute names into time series external IDs. Defaults to an underscore (_).

As an example, the following payload writes to the time series Pump_1_pressure and Pump_1_motor_speed.

{
  "_name": "Pump_1",
  "_model": "Pump",
  "pressure": 41.7,
  "motor": {
    "speed": 1785
  }
}

Write Type: Time Series Metadata

Writes metadata to existing time series. Metadata can only be written to time series that already exist in the space. If one of the time series is not found, the write fails.

SettingDescription
Instance SpaceThe space that holds the time series.

The payload must be an object keyed by time series external ID, where each value is an object of the metadata to write. Keys that match a CogniteTimeSeries property set that property. These include name, description, isStep, unit, sourceUnit, sourceId, tags, and aliases. The unit is the external ID of a unit in the CDF unit catalog (ex. pressure:bar). All other keys are written to the time series’ extractedData, replacing what it had. Only the properties in the payload are changed.

{
  "Pump_1_pressure": {
    "description": "Discharge pressure",
    "unit": "pressure:bar",
    "location": "Line 1"
  },
  "Pump_1_motor_speed": {
    "description": "Motor speed",
    "sourceUnit": "rpm"
  }
}

In the example above, location is written to extractedData.

Write Type: Asset

Asset writes first write each attribute to a time series, the same as Time Series writes, and then convert Intelligence Hub models and instances into CDF views and assets. The model becomes a view with a time series relation per attribute, and each instance becomes an asset whose relations point to its time series. See How Asset Writes Work below for details.

SettingDescription
Create OptionWhen set to Off, datapoints are written to existing time series by external ID and nothing is created. When set to Create, missing spaces, the container and view, assets, and time series are created, and new model attributes are added to the container, view, and existing assets.
Schema SpaceThe space that holds the container and view generated for each model. Only used when Create Option is set to Create.
Instance SpaceThe space that holds the time series and assets. This can be the same as the Schema Space.
Asset NameThe name of the asset. Used as the asset external ID, and as the prefix of its time series external IDs. When left blank the instance name (_name) in the payload is used. The write fails if neither is set.
View VersionThe version of the view created for the model. Defaults to 1 when left blank. Only used when Create Option is set to Create.
Parent SpaceThe space of the parent asset. Defaults to the Instance Space when left blank. Only used when Create Option is set to Create.
Parent IDThe external ID of the parent asset. When set, it prefixes the external IDs of the written assets and their time series (ex. Line_1_Pump_1). The parent is only set when the asset is created. Leave blank to write assets without a parent.
DelimiterThe delimiter used to join the parent ID, asset name, and attribute names into asset and time series external IDs. Defaults to an underscore (_).

Below is an example Asset write. This payload could come from a raw input or be generated by the models and instances configured in the Intelligence Hub.

{
  "_name": "Pump_1",
  "_model": "Pump",
  "pressure": 41.7,
  "motor": {
    "speed": 1785
  }
}

With Create Option set to Create, Schema Space set to plant_schema, Instance Space set to plant_instances, Parent ID set to Line_1, and the default Delimiter, the following happens.

  1. The datapoints are written to the time series Line_1_Pump_1_pressure and Line_1_Pump_1_motor_speed in plant_instances. The spaces and any missing time series are created first.
  2. The container and view Pump (version 1) are looked up in plant_schema. If they don’t exist they are created, with a time series relation for each attribute, pressure and motor_speed. If they exist but are missing attributes, the new attributes are added. Container and view property names always use an underscore, regardless of the Delimiter, because of CDF’s property naming rules.
  3. The asset Line_1_Pump_1 is looked up in plant_instances. If it doesn’t exist it’s created with the name Pump_1, the parent Line_1, and relations to its time series. Each time series is also linked back to the asset, so it appears on the asset in CDF. If the asset exists but is missing attributes, the new relations are added.

With Create Option set to Off, only step 1 is performed, and the write fails if the time series do not exist.

The model name (_model) of the first instance in the payload is used as the container and view external ID. The write fails if the payload has no model name and Create Option is set to Create.

All changes to containers, views, and assets are additive. Existing properties are never removed, renamed, or retyped.

Data Types and Timestamps

The Asset and Time Series writes support the following data types.

Data TypeWritten As
NumbersNumeric time series. Values are written as doubles.
BooleanNumeric step time series. Values are written as 1 (true) or 0 (false).
StringString time series.

Arrays, date times, files, and null values are skipped. The time series type is set from the first value written when the time series is created, and Boolean and string time series are created as step time series. Created time series are named after their external ID.

The timestamp of each datapoint is the timestamp of the value. When the value has no timestamp, the time of the write is used. Arrays of objects are supported, and each object in the array is written as its own set of datapoints.