Device.Updated

WARNING

This request is part of Device API V1. It is recommended to use V2 requests instead. V1 API will be deprecated in one of the upcoming platform releases.

Update an object model (aka requested model) in Information Model Service.

Fully replace object model's properties and variables with the provided ones and update version.

'Abb.Ability.Device.Updated' request event message is sent to the platform by a directly connected device (i.e. Edge) via IoTHub.

This request is idempotent, meaning that sending several identical requests will result in the model being successfully updated in IM. One of the two following outcomes will occur due to this design:

• First update of an existing object model (determined via objectId + model) will be successful
• Following updates of this object model will be rejected due to object model version mismatch

Prerequisites

First, the requested information model must exist in the database.

Message Format

Abb.Ability.Device.Updated event message has following format when it is received and ready for processing. Only showing data relevant for DCS.

Previously, messages had been authorized by the Device Configuration Service (DCS) and the messages needed to follow the authorization guidelines. Now, the principal manager handles the authorization and the guidelines are now applied on that service

  {
    "properties": {
      "iothub-connection-device-id": "<device id>",
      "ability-messagetype": "platformEvent",
      "eventType": "Abb.Ability.Device.Updated",
      "id": "<correlation id>",
      "objectId": "<GUID>",
      "model": "<model definition>",
      "ack": "<ack>",
      "target": "<connected device path>"
    },
    "body": {
      "objectId": "<GUID>",
      "model": "<model definition>",
      "type": "<type definition>",
      "properties": {"instance specific attributes and values"},
      "variables": {"instance specific attributes"},
      "version": <version>
    }
  }

Message Properties

Added by IoTHub

Property	Mandatory?	Description
iothub-connection-device-id	Mandatory	Device id of the directly connected device. May be any string

Common for all Platform Events

Property	Mandatory?	Description
ability-messagetype	Mandatory	Must be equal to 'platformEvent'
eventType	Mandatory	Must be equal to Abb.Ability.Device.Updated
id	Optional	Correlation id. Should be included to track correlation of Platform components. If not present, DCS will generate a new one
ack	Optional	Initialized to none value if value is missing. Indicates an additional acknowledgement message to be sent to device. For more details see Acknowledgment Handling
target	Optional	If not provided, defaults to empty string. Represents the path to a connected device that wishes to receive the acknowledgement (if requested) and an ObjectModelCreated/Updated notification for the requested model.

Specific to Abb.Ability.Device.Updated Platform Event

Property	Mandatory?	Description
objectId	Mandatory	May also be present in message body. Must be in GUID format
model	Optional	Model definition identifier. Case sensitive. May be present either in message properties or body. Any model, including abb.ability.device, is supported. If not provided, defaults to abb.ability.device

Message body

Property	Mandatory?	Description
objectId	Optional	Must be present in message properties. Must be in GUID format
model	Optional	Model definition identifier. Case sensitive. May be present either in message properties or body. Any model, including abb.ability.device, is supported. If not provided, defaults to abb.ability.device
type	Mandatory	Type definition (type identifier + major version after @ symbol, i.e. abb.ability.deviceControllerType@1). Case sensitive
version	Mandatory	Must be equal or higher than version of model existing in Information Model Service database

Validation Rules

DCS validates all message properties, the message body is in proper JSON format, and the message body properties objectId, model, type and version as specified below. The message body is then passed to the Instance API endpoints PUT /objects/{objectId}/models/{modelId} endpoint where the remaining validation is performed.

Functionality

Description

• Object model is updated in Information Model Service, in case of version gaps update is performed multiple times
• After all updates are completed, Information Model version equals to request message version + 1
• Model notification c2d message Abb.Ability.InformationModel.ObjectModelUpdated is not sent back

  WARNING

  Any platform events generated by Information Model Service, related to this request, are ignored by DCS and not propagated

• If requested, acknowledgement c2d message is sent back to the directly connected device where it can also be propagated further if needed (based on target). For more details see \ref DCS-AcknowledgementHandling
  • target is reused from requested message

Format of returned model notification c2d message

{
  "properties": {
    "ability-messagetype": "platformEvent",
    "eventType": "Abb.Ability.InformationModel.ObjectModelUpdated",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "target": "<connected device path>"
  },
  "body": {"full object model"}
}

Format of returned acknowledgement c2d message

{
  "properties": {
    "ability-messagetype": "platformEventAck",
    "eventType": "Abb.Ability.Device.Updated",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "target": "<connected device path>"
  },
  "body": {
    "success": true, //whether the request was successful
    "code": "<error code>",
    "details": "<error detail>",
    "version": <version> //model version from the request
  }
}

Error Handling

When an error occurs:

• A Device.Updated message is completed inside the Platform (on ServiceBus).
• Error information is logged inside the Platform (in Application Insights).
• If the response can be delivered back to the device, then acknowledgments are sent back to the device, if requested. More details can be found here: \ref DCS-AcknowledgementHandling
• If the response cannot be sent back to the device, then the message is completed and only an error is logged.