Assets

Structuring your hierarchy

In this example we'll model the fictional System 11 that looks like this;

SYSTEM 11
└───Pump A
│   └───Heating cable
└───Pump B
1
2
3
4

Outlined in csv

name description refId parentRefId
SYSTEM 11 Sea water system SYSTEM_11
Pump A Main pump for system 11 PUMP_A SYSTEM_11
Heating cable Heating cable for pump A HEATING_CABLE PUMP_A
Pump B Backup pump for system 11 PUMP_B SYSTEM_11

When constructing an asset hierarchy, you can send all assets in one single request. When doing this, you can give every asset a referable ID (refId) that CDP will create as hard links when posted. Let's post the following request;

POST /api/0.5/projects/<project>/assets
Host: api.cognitedata.com
1
2

Post body

{
  "items": [
    {
      "name": "SYSTEM 11",
      "description": "Sea water system",
      "refId": "SYSTEM_11"
    },
    {
      "name": "Pump A",
      "description": "Main pump for system 11",
      "refId": "PUMP_A",
      "parentRefId": "SYSTEM_11" // this refers to the object with refId = SYSTEM_11 as its parent,
    },
    {
      "name": "Pump B",
      "description": "Backup pump for system 11",
      "parentRefId": "SYSTEM_11"
    },
    {
      "name": "Heating cable",
      "description": "Heating cable for pump A",
      "parentRefId": "PUMP_A"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

The response body should look like this;

{
  "data": {
    "items": [
      {
        "id": 229468419218757,
        "path": [229468419218757],
        "depth": 0,
        "name": "SYSTEM 11",
        "description": "Sea water system",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      },
      {
        "id": 4652973256993338,
        "path": [229468419218757, 4652973256993338],
        "depth": 1,
        "name": "Pump A",
        "parentId": 229468419218757,
        "description": "Main pump for system 11",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      },
      {
        "id": 1184192428522618,
        "path": [229468419218757, 4652973256993338, 1184192428522618],
        "depth": 2,
        "name": "Heating cable",
        "parentId": 4652973256993338,
        "description": "Heating cable for pump A",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      },
      {
        "id": 8652613591094498,
        "path": [229468419218757, 8652613591094498],
        "depth": 1,
        "name": "Pump B",
        "parentId": 229468419218757,
        "description": "Backup pump for system 11",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

As you can see, the refId and parentRefId has been replaced with id and parentId, and now everything is referencing their unique identifiers. Additionally we now have a path field which tells us the full path to the particular asset including itself.

Exploring your hierarchy

Now let's explore our hierarchy. Let's get all assets on the root level and their children by leveraging the depth query parameter. Setting depth=1 will give us all assets at the root level (depth=0) as well as depth=1.

GET /api/0.5/projects/<project>/assets?depth=1
Host: api.cognitedata.com
1
2

The response yields;

{
  "data": {
    "items": [
      {
        "id": 4652973256993338,
        "path": [229468419218757, 4652973256993338],
        "depth": 1,
        "name": "Pump A",
        "parentId": 229468419218757,
        "description": "Main pump for system 11",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      },
      {
        "id": 8652613591094498,
        "path": [229468419218757, 8652613591094498],
        "depth": 1,
        "name": "Pump B",
        "parentId": 229468419218757,
        "description": "Backup pump for system 11",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      },
      {
        "id": 229468419218757,
        "path": [229468419218757],
        "depth": 0,
        "name": "SYSTEM 11",
        "description": "Sea water system",
        "createdTime": 1541161763250,
        "lastUpdatedTime": 1541161763250
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

Next steps

Assets are the backbone of CDP. All resource types should be linked to at least one asset, and all resource types are queriable by their respective assetId.

See the asset API documentation for more information about how to query assets.

Then start linking some data to your assets, by adding time series, events, files or 3d models!

Last Updated: 11/12/2018, 9:22:06 AM