Asset Management Service – Using Default Values in Asset Types¶
The following example illustrates how to create an asset type and define default values for one of its properties using the Asset Management Service. Here, an asset type Valve, which has a property named color, is created. A new valve shall be gray by default, but as this example shows, the default value can be overwritten, if required.
Defining Default Values for an Asset Type¶
Create the asset type using the following request - replace {tenantId} by your tenant's ID:
PUT /assettypes/{tenantId}.Valve
Include the following JSON structure in the payload to define the asset type and its default value for the color property:
{
"name": "Valve",
"description": "General purpose valve",
"parentTypeId": "core.basicdevice",
"instantiable": true,
"scope": "private",
"variables": [
{
"name": "color",
"dataType": "STRING",
"searchable": true,
"length": 10,
"defaultValue": "gray"
}
]
}
Create an asset instance of the newly created asset type using the following request:
POST /assets/
Include the following JSON structure in the payload to define the asset - replace {tenantID} by your tenant's ID and {parentAssetId} by the ID of your preferred parent asset:
{
"name": "Valve-001",
"externalId": "SN 123456-123-123456",
"description": "Valve 001 installed somewhere",
"typeId": "{tenantId}.Valve",
"parentId": "{parentAssetId}",
"timezone": "Europe/Berlin"
}
The response of the call contains the newly created asset instance so you can validate the correct creation:
{
"assetId": "{assetId}",
"tenantId": "{tenantId}",
"name": "Valve-001",
"etag": "{etagValue}",
"externalId": "SN 123456-123-123456",
"t2Tenant": null,
"subTenant": null,
"description": "Valve 001 installed somewhere",
"timezone": "Europe/Berlin",
"parentId": "{parentAssetId}",
"typeId": "{tenantId}.Valve",
"location": null,
"fileAssignments": [],
"variables": [
{
"name": "color",
"value": "gray"
}
],
"aspects": [],
"locks": [],
"hierarchyPath": [
{
"assetId": "{assetId}",
"name": "{tenantId}"
}
],
"deleted": null,
"_links": {
"self": {
"href": "{link}"
},
"aspects": {
"href": "{link}"
},
"variables": {
"href": "{link}"
},
"location": {
"href": "{link}"
},
"parent": {
"href": "{link}"
}
}
}
The response shows that the color property for Valve-001 is set to gray.
Overwriting the Default Value of an Asset¶
Change the color property from gray to white using the following request - replace {id} by the asset ID:
PATCH /assets/{id}
Provide the {CurrentEtagValue} for the If-Match parameter and the following JSON structure to define the asset:
{
"variables": [
{
"name": "color",
"value": "white"
}
]
}
Verify the result in the response body:
{
"assetId": "{assetId}",
"tenantId": "{tenantId}",
"name": "Valve-001",
"etag": "{etagValue}",
"externalId": "SN 123456-123-123456",
"t2Tenant": null,
"subTenant": null,
"description": "Valve 001 installed somewhere",
"timezone": "Europe/Berlin",
"parentId": "{parentAssetId}",
"typeId": "{tenantId}.Valve",
"location": null,
"fileAssignments": [],
"variables": [
{
"name": "color",
"value": "white"
}
],
"aspects": [],
"locks": [],
"hierarchyPath": [
{
"assetId": "{assetId}",
"name": "{tenantId}"
}
],
"deleted": null,
"_links": {
"self": {
"href": "{link}"
},
"aspects": {
"href": "{link}"
},
"variables": {
"href": "{link}"
},
"location": {
"href": "{link}"
},
"parent": {
"href": "{link}"
}
}
}
Resetting the Default Value of an Asset¶
When a default property is removed from the instance, it is automatically reset to the default value.
Remove the asset's properties using the following request - replace {id} by the asset ID:
PATCH /asset/{id}
Provide the {CurrentEtagValue} for the If-Match parameter and the following JSON structure to define the asset:
{
"variables": [
]
}
The return validates that the default value is restored in the asset instance:
{
"assetId": "{assetId}",
"tenantId": "{tenantId}",
"name": "Valve-001",
"etag": "{etagValue}",
"externalId": "SN 123456-123-123456",
"t2Tenant": null,
"subTenant": null,
"description": "Valve 001 installed somewhere",
"timezone": "Europe/Berlin",
"parentId": "{parentAssetId}",
"typeId": "{tenantId}.Valve",
"location": null,
"fileAssignments": [],
"variables": [
{
"name": "color",
"value": "gray"
}
],
"aspects": [],
"locks": [],
"hierarchyPath": [
{
"assetId": "{assetId}",
"name": "{tenantId}"
}
],
"deleted": null,
"_links": {
"self": {
"href": "{link}"
},
"aspects": {
"href": "{link}"
},
"variables": {
"href": "{link}"
},
"location": {
"href": "{link}"
},
"parent": {
"href": "{link}"
}
}
}
Changing the Default Value of Multiple Assets¶
You can change the default value of already existing assets of the same asset type by updating the asset type. This automatically overwrites the default values of the derived assets.
Use the following request - replace {id} by the {tenantId}.Valve, where {tenantID} is your tenant's ID:
PATCH /assettypes/{id}
Provide the {currentEtagValue} for the If-Match parameter and the following JSON structure to define the asset type:
{
"variables": [
{
"name": "color",
"dataType": "STRING",
"searchable": true,
"length": 10,
"defaultValue": "black"
}
]
}
Note
You need to add the complete "variables" instance for PATCH.
Use the following request - replace {assetID} by your asset's ID:
GET /assets/{assetID}
In the response the color is changed to black:
{
"assetId": "{assetId}",
"tenantId": "{tenantId}",
"name": "Valve-001",
"etag": "{etagValue}",
"externalId": "SN 123456-123-123456",
"t2Tenant": null,
"subTenant": null,
"description": "Valve 001 installed somewhere",
"timezone": "Europe/Berlin",
"parentId": "{parentAssetId}",
"typeId": "{tenantId}.Valve",
"location": null,
"fileAssignments": [],
"variables": [
{
"name": "color",
"value": "black"
}
],
"aspects": [],
"locks": [],
"hierarchyPath": [
{
"assetId": "{assetId}",
"name": "{tenantId}"
}
],
"deleted": null,
"_links": {
"self": {
"href": "{link}"
},
"aspects": {
"href": "{link}"
},
"variables": {
"href": "{link}"
},
"location": {
"href": "{link}"
},
"parent": {
"href": "{link}"
}
}
}
Finding out the parentID of an Asset¶
parentId is the ID of the asset one hierarchy level above the actual asset. In the example above the root asset was used as the parent. Inquire the root asset's ID using the following request:
GET /assets/root
If the parent is not the root asset then you can see the direct parent of an asset in the `"hierarchyPath" list. It's always the last item in the list. This is also known as "breadcrumbs".
When creating a new asset you need to add the parent asset's ID in the payload. If you do not remember it you can query it using the endpoint shown below and filter for any attribute you know.
GET /assets