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 Insights Hub. 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:
PUT /assettypes/{id}
Here, the {id} is named {tenantId}.WindTurbine1000 and the body of the request is:Request
{
"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
{
"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:
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
{
"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
{
"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
Manufacturerneeds to be renamed toVendor, thedefaultValueneeds to be changed toVendorZand its length needs to be increased to20. - The variable
Typeneeds to be renamed toVolumeand unit needs to be changed tocc.
It can be done by using below asset type variables update API:
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.
{
"Manufacturer": {
"name": "Vendor",
"defaultValue": "VendorZ",
"length": 20
},
"Type": {
"name": "Volume",
"unit": "cc"
}
}
Successful Response:
204 No Content
Response Header:
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.
GET /assettypes/{id}
Here, the {id} is named {tenantId}.WindTurbine1000.Response
{
"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:
{
"Manufacturer": {
"name": "Type"
},
"Type": {
"name": "Volume"
}
}