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)

# Subscription and Notification Types

This page describes what a subscription is and how it is currently used.

This page also describes what is a notification and differences between two notification (C2D message) types that Device API is sending.

# Messaging patterns

The Device API implements two messaging patterns:

  • request-response
  • publish-subscribe

# Request-Response Pattern

This pattern is handled by the Device API as follows:

  • A user sends Device API request (D2C message) to the Platform
  • The Platform sends back a "request-response" notification (C2D message) to the user's device that sent the original request.

In a request-response pattern the target for a request-response notification is taken from the request. The request-response notification is sent using the same Device API version as the request.

# Publish-subscribe pattern

This pattern is handled by Device API as follows:

  • A user subscribes to receive "publish-subscribe" notifications for a model.
  • The Platform sends back a "publish-subscribe" notification (C2D message) with the last known state of the model when the subscription is created or re-created.
  • The Platform sends back a "publish-subscribe" notification (C2D message) to the user whenever the model has changed.

In the "publish-subscribe" pattern the target property for delivering a "publish subscribe" notification is taken from the subscription. The message is sent to the target.

The "publish-subscribe" notification is always sent using the Device API v1 format. This is done to maintain backwards compatibility.

The user cannot create any subscriptions via a Device API request. Currently the Device API has only limited support for subscriptions - only configuration models maintain an implicit subscription, where target is the owner of a device model of the same objectId, and more specifically its "connectivity provider" path.

# Examples for Device API v1

  1. When "Device.Created" Device API v1 request is sent for a device model, this request creates requested device model, related configuration model, and also creates implicit subscription for configuration model
    • "InformationModel.ObjectModelCreated" notification for device model is of "request-response" type - it is sent in Device API v1 format, with target taken from request
    • "InformationModel.ObjectModelCreated" notification for configuration model is of "publish-subscribe" type - it is sent in Device API v1 format, with target taken from subscription (device model owner)
  2. When configuration model is updated directly in the cloud, notification is propagated to the subscriber
    • "InformationModel.ObjectModelUpdated" notification for configuration model is of "publish-subscribe" type - it is sent in Device API v1 format, with target taken from subscription (device model owner)
  3. When "Device.Deleted" Device API v1 request is sent for device model, this request deletes requested device model and also deletes implicit subscription for configuration model
    • "InformationModel.ObjectModelDeleted" notification for device model is of "request-response" type - it is sent in Device API v1 format, with target taken from request
  4. When configuration model is updated directly in the cloud, notification is no longer propagated to the subscriber

# Examples for Device API v2

  1. When "model.create" Device API v2 action is sent for a device model, this request creates requested device model, related configuration model, and also creates implicit subscription for configuration model
    • "ObjectModel.Created" notification for device model is of "request-response" type - it is no longer sent
    • "InformationModel.ObjectModelCreated" notification for configuration model is of "publish-subscribe" type - it is sent in Device API v1 format, with target taken from subscription (device model owner)
  2. When configuration model is updated directly in the cloud, notification is propagated to the subscriber
    • "InformationModel.ObjectModelUpdated" notification for configuration model is of "publish-subscribe" type - it is sent in Device API v1 format, with target taken from subscription (device model owner)
  3. When "model.delete" Device API v2 action is sent for device model, this request deletes requested device model and also deletes implicit subscription for configuration model
    • "ObjectModel.Deleted" notification for device model is of "request-response" type - it is no longer sent
  4. When configuration model is updated directly in the cloud, notification is no longer propagated to the subscriber

# Device API v1 Message Formats

The request message varies between the Device API v1 and v2. The below set of request messages and response payloads are for the Device API v1.

# Request Message

{
  "Properties": {
    "ability-messagetype": "platformEvent",
    "eventType": "Abb.Ability.Device.Created"
  },
  "Body": {
    "type": "Test.TD.200505.052908.325409.68add2@1"
  }
}

# Request-Response Cloud Response Message

{
  "Properties": {
    "iothub-ack": "full",
    "ability-messagetype": "platformEvent",
    "id": "92072c9f-612f-4d85-9607-e36728bfc284",
    "eventType": "Abb.Ability.InformationModel.ObjectModelCreated",
    "version": "1",
    "timestamp": "2020-05-05T05:29:02.4558901Z",
    "target": "",
    "objectId": "e3b78f6e-2cae-41f5-8e9d-9e9df13c1610",
    "model": "abb.ability.device"
  },
  "Body": {
    "model": "abb.ability.device",
    "type": "Test.TD.200505.052908.325409.68add2@1",
    "ownerId": "c04ea080-a6f8-4a18-a12d-a38cd8edbf14",
    "path": "",
    "version": 1,
    "lastModified": "2020-05-05T05:29:00.517Z",
    "objectId": "e3b78f6e-2cae-41f5-8e9d-9e9df13c1610",
    "tenantId": "e24db62c-a9a4-4b33-96e1-9f2e3350a165"
  }
}

# Publish-Subscribe Cloud Response Message

{
  "Properties": {
    "iothub-ack": "full",
    "ability-messagetype": "platformEvent",
    "id": "92072c9f-612f-4d85-9607-e36728bfc284",
    "eventType": "Abb.Ability.InformationModel.ObjectModelCreated",
    "version": "1",
    "timestamp": "2020-05-05T05:29:02.785448Z",
    "target": "",
    "objectId": "e3b78f6e-2cae-41f5-8e9d-9e9df13c1610",
    "model": "abb.ability.configuration"
  },
  "Body": {
    "model": "abb.ability.configuration",
    "type": "Test.TD.200505.052907.145115.259b4c@1",
    "version": 1,
    "lastModified": "2020-05-05T05:29:01.586Z",
    "objectId": "e3b78f6e-2cae-41f5-8e9d-9e9df13c1610",
    "tenantId": "e24db62c-a9a4-4b33-96e1-9f2e3350a165"
  }
}

# Device API v2 Message Format

The below set of request messages and response payloads are for the Device API v2.

# Request Message

{
  "Properties": {
  "action": "model.create",
  "correlationId": "32beed3d-a81a-41c8-98c8-b03e45e566fd",
  "msgType": "action",
  "version": "2"
  },
  "Body": {
  "type": "Test.TD.200505.055426.207638.8a3cf0@1",
  "model": "abb.ability.device"
  }
}

# Request-Response Cloud Response Message

The Platform sends back an "Abb.Ability.ObjectModel.Created" notification for each created model, in Device API v2 format, with the target property taken from the request.

{
  "Properties": {
    "iothub-ack": "full",
    "msgType": "platformEvent",
    "correlationId": "32beed3d-a81a-41c8-98c8-b03e45e566fd",
    "eventType": "Abb.Ability.ObjectModel.Created",
    "version": "2",
    "timestamp": "2020-05-05T05:54:18.7260433Z",
    "target": "",
    "objectId": "b3264e4b-e167-478f-a079-01bf0a191dc7",
    "model": "abb.ability.device"
  },
  "Body": {
    "model": "abb.ability.device",
    "type": "Test.TD.200505.055426.207638.8a3cf0@1",
    "ownerId": "a06de1c3-f5dd-4048-a23d-93db454d291f",
    "path": "",
    "version": 1,
    "lastModified": "2020-05-05T05:54:17.166Z",
    "objectId": "b3264e4b-e167-478f-a079-01bf0a191dc7",
    "tenantId": "e24db62c-a9a4-4b33-96e1-9f2e3350a165"
  }
}

# Publish-Subscribe Cloud Response Message

{
  "Properties": {
    "iothub-ack": "full",
    "ability-messagetype": "platformEvent",
    "id": "32beed3d-a81a-41c8-98c8-b03e45e566fd",
    "eventType": "Abb.Ability.InformationModel.ObjectModelCreated",
    "version": "1",
    "timestamp": "2020-05-05T05:54:18.7509089Z",
    "target": "",
    "objectId": "b3264e4b-e167-478f-a079-01bf0a191dc7",
    "model": "abb.ability.configuration"
  },
  "Body": {
    "model": "abb.ability.configuration",
    "type": "Test.TD.200505.055425.367104.99cccf@1",
    "version": 1,
    "lastModified": "2020-05-05T05:54:18.014Z",
    "objectId": "b3264e4b-e167-478f-a079-01bf0a191dc7",
    "tenantId": "e24db62c-a9a4-4b33-96e1-9f2e3350a165"
  }
}

# Event Message Pattern Types

Version Device Message Notification Pattern
v1 Abb.Ability.Device.Created request-response/publish-subscribe
v1 Abb.Ability.Device.Updated request-response
v1 Abb.Ability.Device.Deleted request-response
v1 Abb.Ability.Device.SyncModel request-response
v2 model.create request-response/publish-subscribe
v2 model.update request-response
v2 model.delete request-response
v2 model.query request-response
Last updated: 9/6/2021, 1:25:50 PM

← Infinite Processing of Device API Messages →

Feedback