Skip to content

Asset Management Service – Update Asset Type

This example illustrates how asset types variables can be updated or removed. In this example, a global wind power company which has multiple wind farms around the globe, creates their assets in MindSphere. For more information on the endpoints used in the example, refer to the API specification.

The company has one type of wind turbines, the WindTurbine1000, from which the electrical and mechanical metrics are collected. There are some static variables and aspects defined for the WindTurbine1000. Refer to the Modeling Assets.

After creating the required aspect types, the asset type for the WindTurbine1000 can be created using the following endpoint:

1
PUT /assettypes/{id}

Here, the {id} is named {tenantId}.WindTurbine1000 and the body of the request is:

Request
 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
    {
      "name": "WindTurbine1000",
      "description": "WindTurbine 1000 with best reliability.",
      "parentTypeId": "core.basicdevice",
      "instantiable": true,
      "scope": "private",
      "variables": [
        {
          "name": "Installation",
          "dataType": "TIMESTAMP",
          "searchable": true,
          "defaultValue": "1970-01-01T09:00:00+00:00"
        },
        {
          "name": "Manufacturer",
          "dataType": "STRING",
          "searchable": true,
          "length": 8,
          "defaultValue": "CompanyA"
        },
        {
          "name": "Type",
          "dataType": "STRING",
          "searchable": true,
          "length": 12,
          "defaultValue": "ScrewTurbine"
        },
        {
          "name": "Weight",
          "dataType": "INT",
          "searchable": true,
          "defaultValue": 20
        }
      ],
      "aspects": [
        {
          "name": "ElectricalMetrics",
          "aspectTypeId": "{{tenantId}}.ElectricalMetrics"
        },
        {
          "name": "MechanicalMetrics",
          "aspectTypeId": "{{tenantId}}.MechanicalMetrics"
        }
      ]
    }

The created asset type can be verified by checking the response:

Response
  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
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
  {
    "parentTypeId": "core.basicdevice",
    "instantiable": true,
    "tenantId": "{tenantId}",
    "name": "WindTurbine1000",
    "description": "WindTurbine 1000 with best reliability.",
    "scope": "private",
    "variables": [
        {
            "name": "Installation",
            "unit": null,
            "searchable": true,
            "dataType": "TIMESTAMP",
            "length": null,
            "defaultValue": "1970-01-01T09:00:00+00:00"
        },
        {
            "name": "Manufacturer",
            "unit": null,
            "searchable": true,
            "dataType": "STRING",
            "length": 8,
            "defaultValue": "CompanyA"
        },
        {
            "name": "Type",
            "unit": null,
            "searchable": true,
            "dataType": "STRING",
            "length": 12,
            "defaultValue": "ScrewTurbine"
        },
        {
            "name": "Weight",
            "unit": null,
            "searchable": true,
            "dataType": "INT",
            "length": null,
            "defaultValue": "20"
        }
    ],
    "aspects": [
        {
            "name": "ElectricalMetrics",
            "aspectType": {
                "id": "{tenantId}.ElectricalMetrics",
                "tenantId": "{tenantId}",
                "name": "ElectricalMetrics",
                "category": "dynamic",
                "scope": "private",
                "description": "Electrical metrics for wind turbines",
                "variables": [
                    {
                        "name": "PWR_OUT",
                        "unit": "MW",
                        "searchable": true,
                        "qualityCode": true,
                        "defaultValue": null,
                        "dataType": "DOUBLE",
                        "length": null
                    },
                    {
                        "name": "V_OUT",
                        "unit": "Volt",
                        "searchable": true,
                        "qualityCode": true,
                        "defaultValue": null,
                        "dataType": "DOUBLE",
                        "length": null
                    }
                ],
                "etag": 0,
                "sharing": {
                    "modes": []
                },
                "_links": {
                    "self": {
                        "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/{tenantId}.ElectricalMetrics"
                    }
                }
            }
        },
        {
            "name": "MechanicalMetrics",
            "aspectType": {
                "id": "{tenantId}.MechanicalMetrics",
                "tenantId": "{tenantId}",
                "name": "MechanicalMetrics",
                "category": "dynamic",
                "scope": "private",
                "description": "Mechanical metrics for wind turbines",
                "variables": [
                    {
                        "name": "V",
                        "unit": "RPM",
                        "searchable": true,
                        "qualityCode": true,
                        "defaultValue": null,
                        "dataType": "INT",
                        "length": null
                    },
                    {
                        "name": "VIB",
                        "unit": "Hz",
                        "searchable": true,
                        "qualityCode": true,
                        "defaultValue": null,
                        "dataType": "INT",
                        "length": null
                    }
                ],
                "etag": 0,
                "sharing": {
                    "modes": []
                },
                "_links": {
                    "self": {
                        "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/{tenantId}.MechanicalMetrics"
                    }
                }
            }
        }
    ],
    "fileAssignments": [],
    "sharing": {
        "modes": []
    },
    "etag": 0,
    "_links": {
        "self": {
            "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/{tenantId}.WindTurbine1000"
        },
        "parent": {
            "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/core.basicdevice"
        }
    },
    "id": "{tenantId}.WindTurbine1000"
  }

Deleting Variables

The asset type {tenantId}.WindTurbine1000 has four static variables, the variable Weight needs to be removed from the asset type. It can be removed by using the Asset Type update API as below:

1
PUT /assettypes/{id}

Here, the {id} is named {tenantId}.WindTurbine1000 and the body of the request is as below with the removed variable Weight, the If-Match header needs to have the value of etag from the Asset Type response.

Request
 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
  {
    "name": "WindTurbine1000",
    "description": "WindTurbine 1000 with best reliability.",
    "parentTypeId": "core.basicdevice",
    "instantiable": true,
    "scope": "private",
    "variables": [
      {
        "name": "Installation",
        "dataType": "TIMESTAMP",
        "searchable": true,
        "defaultValue": "1970-01-01T09:00:00+00:00"
      },
      {
        "name": "Manufacturer",
        "dataType": "STRING",
        "searchable": true,
        "length": 8,
        "defaultValue": "CompanyA"
      },
      {
        "name": "Type",
        "dataType": "STRING",
        "searchable": true,
        "length": 12,
        "defaultValue": "ScrewTurbine"
      }
    ],
    "aspects": [
      {
        "name": "ElectricalMetrics",
        "aspectTypeId": "{{tenantId}}.ElectricalMetrics"
      },
      {
        "name": "MechanicalMetrics",
        "aspectTypeId": "{{tenantId}}.MechanicalMetrics"
      }
    ]
  }

The updated asset type can be verified by checking the response, the variable is removed from the response and also from its Asset Instances:

Response
  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
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
    {
        "parentTypeId": "core.basicdevice",
        "instantiable": true,
        "tenantId": "{tenantId}",
        "name": "WindTurbine1000",
        "description": "WindTurbine 1000 with best reliability.",
        "scope": "private",
        "variables": [
            {
                "name": "Installation",
                "unit": null,
                "searchable": true,
                "dataType": "TIMESTAMP",
                "length": null,
                "defaultValue": "1970-01-01T09:00:00+00:00"
            },
            {
                "name": "Manufacturer",
                "unit": null,
                "searchable": true,
                "dataType": "STRING",
                "length": 8,
                "defaultValue": "CompanyA"
            },
            {
                "name": "Type",
                "unit": null,
                "searchable": true,
                "dataType": "STRING",
                "length": 12,
                "defaultValue": "ScrewTurbine"
            }
        ],
        "aspects": [
            {
                "name": "ElectricalMetrics",
                "aspectType": {
                    "id": "{tenantId}.ElectricalMetrics",
                    "tenantId": "{tenantId}",
                    "name": "ElectricalMetrics",
                    "category": "dynamic",
                    "scope": "private",
                    "description": "Electrical metrics for wind turbines",
                    "variables": [
                        {
                            "name": "PWR_OUT",
                            "unit": "MW",
                            "searchable": true,
                            "qualityCode": true,
                            "defaultValue": null,
                            "dataType": "DOUBLE",
                            "length": null
                        },
                        {
                            "name": "V_OUT",
                            "unit": "Volt",
                            "searchable": true,
                            "qualityCode": true,
                            "defaultValue": null,
                            "dataType": "DOUBLE",
                            "length": null
                        }
                    ],
                    "etag": 0,
                    "sharing": {
                        "modes": []
                    },
                    "_links": {
                        "self": {
                            "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/{tenantId}.ElectricalMetrics"
                        }
                    }
                }
            },
            {
                "name": "MechanicalMetrics",
                "aspectType": {
                    "id": "{tenantId}.MechanicalMetrics",
                    "tenantId": "{tenantId}",
                    "name": "MechanicalMetrics",
                    "category": "dynamic",
                    "scope": "private",
                    "description": "Mechanical metrics for wind turbines",
                    "variables": [
                        {
                            "name": "V",
                            "unit": "RPM",
                            "searchable": true,
                            "qualityCode": true,
                            "defaultValue": null,
                            "dataType": "INT",
                            "length": null
                        },
                        {
                            "name": "VIB",
                            "unit": "Hz",
                            "searchable": true,
                            "qualityCode": true,
                            "defaultValue": null,
                            "dataType": "INT",
                            "length": null
                        }
                    ],
                    "etag": 0,
                    "sharing": {
                        "modes": []
                    },
                    "_links": {
                        "self": {
                            "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/{tenantId}.MechanicalMetrics"
                        }
                    }
                }
            }
        ],
        "fileAssignments": [],
        "sharing": {
            "modes": []
        },
        "etag": 1,
        "_links": {
            "self": {
                "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/{tenantId}.WindTurbine1000"
            },
            "parent": {
                "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/core.basicdevice"
            }
        },
        "id": "{tenantId}.WindTurbine1000"
    }

Updating Variables

The asset type {tenantId}.WindTurbine1000 has three static variables defined. Some updates are required on the variables as below:

  • The variable Manufacturer needs to be renamed to Vendor, the defaultValue needs to be changed to VendorZ and its length needs to be increased to 20.
  • The variable Type needs to be renamed to Volume and unit needs to be changed to cc.

It can be done by using below asset type variables update API:

1
PATCH /assettypes/{id}/variables

Here, the {id} is {tenantId}.WindTurbine1000 and the body of the request is a Variable Dictionary Map as below. The If-Match header in the request needs to have the value of etag of asset type. The Content-Type of the request has to be application/merge-patch+json. Only the variables and properties present in the payload will be updated and the other variables and its properties will not be updated. In case of validation failure, the request is failed without any updates.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
  {
    "Manufacturer": {
      "name": "Vendor",
      "defaultValue": "VendorZ",
      "length": 20
    },
    "Type": {
      "name": "Volume",
      "unit": "cc"
    }
  }

Successful Response:

1
204 No Content

Response Header:

1
ETag : 1

This is the etag of asset type. It can be used to further update asset type and its variables again. The updated asset type can be re-verified by checking the response asset type.

1
GET /assettypes/{id}

Here, the {id} is named {tenantId}.WindTurbine1000.

Response
  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
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
  {
    "parentTypeId": "core.basicdevice",
    "instantiable": true,
    "tenantId": "{tenantId}",
    "name": "WindTurbine1000",
    "description": "WindTurbine 1000 with best reliability.",
    "scope": "private",
    "variables": [
      {
        "name": "Installation",
        "unit": null,
        "searchable": true,
        "dataType": "TIMESTAMP",
        "length": null,
        "defaultValue": "1970-01-01T09:00:00+00:00"
      },
      {
        "name": "Vendor",
        "unit": null,
        "searchable": true,
        "dataType": "STRING",
        "length": 20,
        "defaultValue": "VendorZ"
      },
      {
        "name": "Volume",
        "unit": "cc",
        "searchable": true,
        "dataType": "STRING",
        "length": 12,
        "defaultValue": "ScrewTurbine"
      }
    ],
    "aspects": [
      {
        "name": "ElectricalMetrics",
        "aspectType": {
          "id": "{tenantId}.ElectricalMetrics",
          "tenantId": "{tenantId}",
          "name": "ElectricalMetrics",
          "category": "dynamic",
          "scope": "private",
          "description": "Electrical metrics for wind turbines",
          "variables": [
            {
              "name": "PWR_OUT",
              "unit": "MW",
              "searchable": true,
              "qualityCode": true,
              "defaultValue": null,
              "dataType": "DOUBLE",
              "length": null
            },
            {
              "name": "V_OUT",
              "unit": "Volt",
              "searchable": true,
              "qualityCode": true,
              "defaultValue": null,
              "dataType": "DOUBLE",
              "length": null
            }
          ],
          "etag": 0,
          "sharing": {
            "modes": []
          },
          "_links": {
            "self": {
              "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/{tenantId}.ElectricalMetrics"
            }
          }
        }
      },
      {
        "name": "MechanicalMetrics",
        "aspectType": {
          "id": "{tenantId}.MechanicalMetrics",
          "tenantId": "{tenantId}",
          "name": "MechanicalMetrics",
          "category": "dynamic",
          "scope": "private",
          "description": "Mechanical metrics for wind turbines",
          "variables": [
            {
              "name": "V",
              "unit": "RPM",
              "searchable": true,
              "qualityCode": true,
              "defaultValue": null,
              "dataType": "INT",
              "length": null
            },
            {
              "name": "VIB",
              "unit": "Hz",
              "searchable": true,
              "qualityCode": true,
              "defaultValue": null,
              "dataType": "INT",
              "length": null
            }
          ],
          "etag": 0,
          "sharing": {
            "modes": []
          },
          "_links": {
            "self": {
              "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/{tenantId}.MechanicalMetrics"
            }
          }
        }
      }
    ],
    "fileAssignments": [],
    "sharing": {
      "modes": []
    },
    "etag": 2,
    "_links": {
      "self": {
        "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/{tenantId}.WindTurbine1000"
      },
      "parent": {
        "href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/core.basicdevice"
      }
    },
    "id": "{tenantId}.WindTurbine1000"
  }

The above example illustrates that multiple variables can be updated using update variables API. Interchanging of variable names are not allowed in single request. This means that the name of existing variable should not be used to rename the another variable in the same request. In this scenario, below request payload will result in a failure:

1
2
3
4
5
6
7
8
{
    "Manufacturer": {
        "name": "Type"
    },
    "Type": {
        "name": "Volume"
    }
}

Any questions left?

Ask the community


Except where otherwise noted, content on this site is licensed under the MindSphere Development License Agreement.