Ability™ Developer Portal v23.1
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Information Model Overview

Before we discuss information modeling in detail, let's make sure we understand why it is needed and why it was created.

When you think about the IIoT platform, bear in mind that it is going to store lots of data. Now imagine that such platform allows you to input anything you like, without adhering to any schema or rules of any kind. From the perspective of the device that produces the data, this doesn't matter. However, a huge data dump would make it very difficult to know what to look for when fetching information from the system.

As an example, let's say we had a motor connected to the cloud. The motor would produce various timeseries values and send them to the cloud. If our IIoT system did not incorporate a modeling approach, it would be up to the motor (or actually its producer) to define a set of data to be sent, its format, etc. There would be no defined set of rules of what should actually be sent. Another motor could be set up by another person, perhaps sending data in a completely different format than the first motor. This situation becomes truly problematic when performing fleet analytics based on the data from said motors. First you'd need to contact the persons who set up the motors to learn their configuration, then based on their feedback, develop your (needlessly complex) solution.

The hypothetical situation described above was meant to show that the lack of a contract can lead to - basically a mess. This is the problem that ABB Ability™ Information modeling was created to solve. With this in mind, you should better understand why we need modeling constructs. Modeling introduces structure and order for managing your data.

Video doesn't load?

The embedded video is shared via Microsoft Stream platform. If you can't view it, most likely you do not have access to MS Stream. You can request access via ABB ToolFinder. While waiting for the request to be fulfilled, feel free to watch the video on ABB TV

Learning Materials

We recommend you to see the following materials to gain a better understanding of the topic:

The listing of all webinars can be found here

# Common Cases Where Models Are Needed

You might ask - in what situations would you actually make use of the models that you create for your solution? To answer this question, let's look at the most common cases that you will likely encounter when using the ABB Ability™ Platform:

  • writing data to the cloud - While sending your telemetry, creating new cloud identities, etc. - you need to adhere to the models of your solution. Example of that could be an Edge device that acts as a gateway between your devices and the cloud - it needs to know (from the model) how the data should be sent (should the voltage be called "voltage" or maybe "measuredVoltage"?)
  • configuring your devices - The information model allows you to create a special model for your device's configuration needs. Maybe your sensor is able to collect the measurements in different intervals. Since both the device and you know the configuration schema, you are able to update some settings (by updating the information model object - information about it will be delivered to your device automatically by the platform).
  • reading data from the platform - Since your devices adhere to your modeling, you know exactly what to look for when querying for data. As an example, if you are about to fetch speed measurements from all of your motors, you know that you need to query for "rotoSpeed" of "abb.lowVoltageMotor" instances.
  • invoking some action on your device - The Data Access API allows you to invoke commands on your IoT devices - since there is a model/contract, you know that "start" method will start your sensor to collect measurements.

# Specifics of the ABB Ability™ Modeling Approach

The ABB Ability™ Platform implements a 3-layer modeling approach. Looking from the bottom to the top, we have:

  1. Model definitions
  2. Type definitions
  3. Information model objects

Let's look at each of these to understand their responsibilities.

# Model Definitions

The bottom layer, from the platform user's perspective, is the model definition. It allows us to define a set of semantics that the higher layers are allowed to use. A 'fresh' platform comes by default with two model definitions: abb.ability.device and abb.ability.configuration. Here are their representations:

  1. abb.ability.device
{
    "modelId": "abb.ability.device",
    "components": {
        "properties": {
            "hubName": {
                "dataType": "string"
            },
            "deviceId": {
                "dataType": "string"
            }
        },
        "variables": {},
        "methods": {},
        "attributes": {},
        "references": {}
    }
}
  1. abb.ability.configuration
{
    "modelId": "abb.ability.configuration",
    "components": {
        "properties": {},
        "attributes": {}
    }
}

Without going into great detail, the above model definitions signal that abb.ability.device-based type definitions can use all of the allowed semantics (properties, variables, methods, attributes, references), additionally predefining: hubName and deviceId (both having a data type of string).

To gain a better understanding of what this means, let's continue with a look at type definitions.

# Type Definitions

TIP

Type definitions are described in greater detail here. For the purposes of this discussion, we will limit ourselves to a high level overview.

In the previous section, we established that model definitions are a kind of base for type definitions. Let's start with an exemplary type definition:

{
    "typeId": "abb.lowVoltageMotor",
    "version": "1.0.0",
    "model": "abb.ability.device",
    "properties": {
        "manufacturer": {
            "dataType": "string",
            "description": "Manufacturer of the motor",
            "isMandatory": true
        }
    },
    "variables": {
        "rotorSpeed": {
            "dataType": "number",
            "description": "Rotating speed of the motor",
            "unit": "rpm"
        },
        "armatureCurrent": {
            "dataType": "number",
            "description": "Armature current of the motor",
            "unit": "mA"
        }
    },
    "methods": {
        "start": {
            "description": "Start the motor"
        },
        "stop": {
            "description": "Stop the motor"
        },
    }
}

The presented JSON defines a contract to be used by low-voltage motors. This means that:

  • Each low-voltage motor will be characterized by its manufacturer - this property is marked as isMandatory.
  • Each low-level motor is able to report its rotorSpeed and armatureCurrent.
  • Each low-level motor is able to be started and stopped.

If you go back for a moment to the model definition section, you will see that one of the models available in the platform is abb.ability.device. The type definition above uses this as its model, making it possible to define all available semantic components for this type. If this type was using abb.ability.configuration instead, we would be limited to just properties and attributes components - which is perfectly fine for models containing some configuration values, but not for a model of a motor device.

# Information Model Objects

The last layer of the ABB Ability™ modeling approach is the information model object. We'll start with the following example:

{
    "objectId": "00027713-6d3f-4a45-b430-ab339f34cfd2",
    "type": "abb.lowVoltageMotor@1",
    "model": "abb.ability.device",
    "properties": {
        "manufacturer": {
            "value": "ABB"
        }
    },
    "version": 1
}

What we see is an instance of the previously defined abb.lowVoltageMotor type definition. This could be an actual representation of a real motor installed somewhere in the factory. Note that every thing in the ABB Ability™ IoT Platform has a digital representation and that every device connected to the platform must have its identity in the cloud. These functions are served by information model objects. Two attributes bear mentioning:

  • Every object model in the cloud has a unique identity described by an objectId and model pair. In addition, identity can be defined by typeId and unique properties, if defined.
  • Every object is an instance of some type definition that must exist in the Type Definition Registry. This means that the object can use all components defined in its type definition.

Object-oriented Programming Analogy

You can treat a type definition as a class and an information model object as an instance of that class.

You might wonder, where are the rotorSpeed and armatureCurrent? After all, they were defined in the type definition, so the information model object should have those as well, right? It does, however, you need to realize that those are variables. The information model object is a JSON that defines your instance. It is not a place to store time-series data. Note, however, that each data point of your telemetry is bound to the right information model object via a reference to objectId. This allows you to link each piece of data to its source.

Querying

Ability Platform offers a custom Domain Specific Language for querying information model objects. You can read about it in Information Model DSL Queries.

# Object Model Uniqueness and Corresponding ObjectId

Since the initial deployment of the Ability Platform, the uniqueness of object model properties has been defined by two constructs:

  1. ObjectId + model
  2. TypeId@version + unique properties

Verification of the paired TypeId@version and unique properties is performed for each object model. In the present version of the platform, the general check for uniqueness becomes mandatory within the type and properties regardless of type definition version (major and minor). Verification of uniqueness of the ObjectId and model remains as in prior platform versions.

# Required Migrations

The mandatory check for uniqueness described above results in several operating behaviors that may require corresponding changes in both the Type Definitions Registry and in the Information Model for local solutions running on the present version of the Ability Platform. Details of how this feature behaves and how local solutions may be impacted are described below.

For the Type Definitions Registry:

  • Any attempt to change unique properties within the Type Definitions Registry will be refused with a 400 Bad Request response.
  • Established scenarios that rely for verification on a change in unique properties within the Type Definitions Registry will be invalidated.
  • Semantic versioning reflects this new constraint.

For the Information Model:

  • The unique identity of the object model must consist of at least one of the following:
    • objectId and model
    • unique properties and type (without version)

NOTE

The changes described above constitute a change of validation behavior, with no changes required in user payloads. Feature design research determined that in 99% of cases the new uniqueness model was already fulfilled in users' solutions, i.e. users were utilizing only object models with one specific type version. If you have designed your solution around this constraint, solution operability should not be affected.

Following are two hypothetical scenarios of how the unique object model feature may trigger or avoid triggering a conflict.

  1. An object model of typeId and major version 1 and unique properties exists, triggering a conflict when trying to upload a new object model of the same typeId but major version 2 and the same unique properties.
  2. An object model of typeId and major version 1 and unique properties exists, resolving in success when trying to upload a new object model of the same typeId but major version 2 and different unique properties.

ABB Ability™ Platform developers have identified several contingencies in which the unique object model feature has produced conflicts. Following is a review of these conflicts and the associated workarounds up to and including the present platform release.

# Migration Guidelines

When upgrading from 19.09 and prior versions of the Ability platform, there may be residual object models in a database that have the same unique properties and typeId, but different versions (hereafter called duplicates). This situation was determined to be a highly unlikely scenario. There may, however, be rare situations in which this condition must be resolved. Following are the established protocols for addressing this situation.

# Duplicated Object Model Is Known by objectId

The user must remove duplicate object models from the API, using the endpoint: DELETE /objects/{objectId}/models/{modelId}.

Infomodel Delete Endpoint

# Duplicated typeId Is Known

  1. Find all object models with the same typeId but different versions.

  • Use the DSL query: models().ofType(startingWith('typeId@')).

  • Use the QEL filter on the GET /objects endpoint: type starts_with 'typeId@'.

  1. Remove all duplicated object models as described above.

# Duplicated Types Are Unknown

In the event duplicated types are not known, please contact your CST or operations team representative. They will be able to assist you to ensure a seamless upgrade.

# Summary

We hope you now understand how type definitions are defined based on model definitions and how information model objects are created based on their type definitions. For a detailed discussion of type definitions in the Ability Platform, review topics listed under Type Definitions. For more on object models, see Object Model Validation Rules. To understand how to use information model APIs, go to the APIs section of the portal.

Author: Marcin Jahn
Last updated: 12/7/2021, 2:18:42 PM

← Type Definitions →

Feedback