Skip to content

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:

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:

image

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

  1. Create (or update) an aspect type
  2. Create (or update) an asset type
  3. Create an asset
  4. 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 and GET /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:

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.


Last update: December 6, 2023

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