Migrating from Insights Hub Version 2 to Version 3¶
Introduction¶
The target user of this document is a developer of Insights Hub Version 2. The document is intended to help transfer knowledge from Insights Hub Version 2 (V2) to Version 3 (V3). The scope of this guide is for Insights Hub Version 2 Cloud Foundry applications using Northbound APIs. Currently not for applications using Southbound APIs.
In Insights Hub Version 3 most operational steps are the same as on the Version 2 platform. As a Version 2 developer, you mainly need to focus on the following aspects:
Major Changes¶
Minor Changes¶
Prerequisites¶
Generating an access token to invoke APIs¶
All Insights Hub endpoints are secured and can only be reached after a successful authentication. There are two ways to get an access token:
- Get an access token to call Insights Hub from your application. Refer to section Authentication & Authorization.
- Get an access token after Global Technical Access Center (GTAC) approved your request. Refer to section Self-Hosted Application.
Generating URLs for accessing APIs¶
Refer to section URL schemes on how to build appropriate URLs for Gateway.
IoT model¶
Concept¶
The IoT model between V2 and V3 is quite different. Overall, the aspect type and asset type are now templates. This makes it easy for user to manage assets. An aspect type is attached to an asset type, while an asset is created based on an asset type.
- In V3 the aspect type is a collection of variables, like an aspect in V2. However, it's a template and can be reused. An aspect type has no hierarchy and can be categorized as static or dynamic.
- Static aspects have variables with mostly stable values that do not differ so much. They can be used when searching for an asset.
- Dynamic aspects are managed with timestamps and have values differing over time. That is, they are for time series data.
- An asset type include aspect types and variables. When aspect types are attached to asset types, the aspects types are fully reflected inside the asset type with all parameters (including variables).
- An asset type has a hierarchy. A newly created type inherits all variables and aspects defined in the parent type.
- Assets are the same as in V2, but can only be created from an asset type.
Changes between V2 and V3¶
- IoT model changes:
V2 | V3 | Change |
---|---|---|
Asset | Asset | Almost the same, but based on an asset type now. |
Asset Type | Is a template now. | |
Aspect | Aspect Type | Is a template now. |
- Different workflow for creating an IoT model:
Creating a new IoT model¶
For each step an example is attached. It shows the creation of an asset for an e-bike. For details on the API endpoints used in the examples, have a look the V3 API Reference.
Overview¶
- Create (or update) an aspect type
- Create (or update) an asset type
- Create an asset
- Query the asset structure for validation
Note
- The steps 1 & 2 to create an aspect type and an asset type are optional. They can be ignored if suitable types exist.
- You can query all existing types by using the endpoints
GET /aspecttypes
andGET /assettypes
.
1. Create (or update) an aspect type (optional)¶
This step creates an aspect type running
. The aspect type cares about the power consumption in running state. It has two variables and can be reused by other electronic running devices.
put https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/casmcne.running
{
"name": "running",
"category": "dynamic",
"scope": "private",
"description": "running state",
"variables": [
{
"name": "voltage",
"dataType": "DOUBLE",
"unit": "V",
"searchable": true,
"length": null,
"qualityCode": true
},{
"name": "current",
"dataType": "DOUBLE",
"unit": "A",
"searchable": true,
"length": null,
"qualityCode": true
}
]
}
- Upon successful creation, an HTTP response
201 The aspect type has been created
is returned with a JSON body holding additional data about the newly created aspect type. - Use
GET
on the same endpoint to check for the newly created aspect:
{
"parentTypeId": "core.basicasset",
"instantiable": true,
"tenantId": "casmcne",
"name": "Electric-Bicycle",
"description": "the device of the Electric-Bicycle",
"scope": "private",
"variables": [
{
"name": "speed",
"unit": "km/h",
"searchable": true,
"dataType": "DOUBLE",
"length": null
}
],
"aspects": [
{
"name": "running",
"aspectType": {
"id": "casmcne.running",
"tenantId": "casmcne",
"name": "running",
"category": "dynamic",
"scope": "private",
"description": "running state",
"variables": [
{
"name": "current",
"unit": "I",
"searchable": false,
"qualityCode": false,
"dataType": "DOUBLE",
"length": null
},
{
"name": "voltage",
"unit": "V",
"searchable": false,
"qualityCode": false,
"dataType": "DOUBLE",
"length": null
}
],
"etag": 0,
"_links": {
"self": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/aspecttypes/casmcne.running"
}
}
}
}
],
"etag": 0,
"_links": {
"self": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/casmcne.elecbike"
},
"parent": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/core.basicasset"
}
},
"id": "casmcne.elecbike"
}
Tip
- It's recommended to check all existing aspect types for reference.
id
will be of format[tenant prefix id].[aspect type]
.- When updating a model,
if-match
should be set in the header. - Existing variables and aspect names can no longer be changed.
2. Create (or update) an asset type (optional)¶
This step creates an asset type for an electric bicycle. It includes a variable and an aspect. The variable is the speed of the bicycle. The aspect is included to get the power consumption when running.
put https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/casmcne.elecbike
asset type:
https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assettypes/casmcne.elecbike
json:
{
"name": "Electric-Bicycle",
"description": "the device of the Electric-Bicycle",
"parentTypeId": "core.basicasset",
"scope": "private",
"variables": [
{
"name": "speed",
"dataType": "DOUBLE",
"unit": "km/h",
"searchable": true,
"length": null
}
],
"aspects": [
{
"name": "running",
"aspectTypeId": "casmcne.running"
}
]
}
- Upon successful creation, an HTTP response
201 The asset type has been created
is returned with a JSON body holding additional data about the newly created asset type.
Tip
id
will be of format[tenant prefix id].[asset type]
.aspectTypeId
is created in step 1.- Be aware that asset types are created in a hierarchical model.
- When
parenttypeid
points to an asset type, it means that you create that asset type as a child. Child asset types inherit their parent and can extend the parent's aspects and variables.
3. Create an asset¶
This step creates the e-bike asset elecbike_No.1
:
post https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets
{
"typeId": "casmcne.elecbike",
"t2Tenant": null,
"parentId": "1ad478aa9e7f4d1196cbe3d0dd44f002",
"name": "elecbike_No.1",
"externalId": "",
"description": "elecbike No.1",
"location": {
"country": "China",
"region": "Sichuan Province",
"locality": "Chengdu",
"streetAddress": "XiXin Avenue No.07",
"postalcode": "610000",
"longitude": 103.9602020,
"latitude": 30.7429640
},
"variables": [],
"aspects": []
}
- Upon successful creation, an HTTP response
201 The asset is created
is returned with a JSON body holding additional data about the newly created asset:
{
"assetId": "696126dda1714921b3715cce46300fbe",
"tenantId": "casmcne",
"name": "elecbike_No.1",
"etag": 0,
"externalId": "",
"t2Tenant": null,
"description": "elecbike No.1",
"parentId": "1ad478aa9e7f4d1196cbe3d0dd44f002",
"typeId": "casmcne.elecbike",
"location": {
"country": "China",
"region": "Sichuan Province",
"locality": "Chengdu",
"streetAddress": "XiXin Avenue No.07",
"postalCode": null,
"longitude": 103.960202,
"latitude": 30.742964
},
"variables": [],
"aspects": [],
"deleted": null,
"_links": {
"self": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe"
},
"aspects": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/aspects"
},
"variables": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/variables"
},
"location": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/location"
},
"parent": {
"href": "https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/1ad478aa9e7f4d1196cbe3d0dd44f002"
}
}
}
Tip
- Be aware that assets are created in a hierarchical model.
parentid
is the category of the asset.
4. Query the asset structure for validation¶
Get the structure of the asset's aspects or variables by using the links of the response in step 3, e.g.:
Get https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/variables
Get https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets/696126dda1714921b3715cce46300fbe/aspects
Insights Hub APIs¶
The reference documentation of the current Insights Hub Version 3 APIs can be found in section APIs & Services.
The following is an overview about the differences between Insights Hub Version 2 and 3 APIs.
Access token scopes in V3¶
Compared to V2, the authorization control is much more detailed than in V3. See Roles & Scopes for concepts and specific roles and permissions for using the API of the Insights Hub services.
New APIs in V3¶
The following APIs are new in V3:
- Agent Management Service
- Identity Management Service
- IoT File Service
- IoT Time Series Service
- IoT TS Aggregates Service
- KPI Calculation Service
- MindConnect API
- OAuth Authorization Server API
- Signal Validation Service
- Usage Transparency Service
See also the Service Index for an overview and a short description of the services.
API comparison between V2 and V3¶
The following table shows the changes of API names between V2 and V3:
V2 API name | V3 API name |
---|---|
Asset Management API | Asset Management API |
Event Management API | Event Management API |
CommunicationService MessageQueueProducer | Notification API |
Recipients | Notification API |
Template | Notification API |
CommunicationChannel | Notification API |
CommunicationCategory | Notification API |
Application registration¶
In V3 there is an additional step before registering your application:
- Configuring the roles and scopes of your application.
See Running a Cloud Foundry-Hosted Application for details.
Except where otherwise noted, content on this site is licensed under the Development License Agreement.