Acknowledgement Handling

For a Device API message, a user can request an acknowledgement that message processing has been completed (successfully or unsuccessfully).

Characteristics

Every incoming platform event that is included in the following list can contain a new header field, the ack field - responsible for sending the acknowledgement messages back to the device:

Device API v1

• Abb.Ability.Device.Created
• Abb.Ability.Device.Updated
• Abb.Ability.Device.SyncModel
• Abb.Ability.Device.Deleted

Device API v2

• identity.create
• identity.delete
• model.create
• model.query
• model.update
• model.patch
• model.delete
• reference.create
• reference.delete
• type.create
• type.query
• type.delete
• owner.remove
• extension.create
• extension.get

Acknowledgement Field Characteristics

The ack field is of an string type with four possible values:

• none
• positive
• negative
• all

DEFAULT VALUE

if no value provided, the default value is "none" if value does not exist (for backward compatibility)

The ack field defines how DCS will behave and if the "acknowledgement" C2D message will be sent to the device. The following list explains how setting the value of the ack field will propagate through the platform:

Value	Description
none	DCS will not propagate the "acknowledgement" C2D messages at all
positive	DCS will propagate only the "acknowledgement" C2D indicating the successful processing of the incoming platform event
negative	DCS will propagate only the "acknowledgement" C2D indicating the failures during the incoming platform event processing
all	Will propagate all "acknowledgement" C2D messages

The C2D acknowledgement message will contain the following information in return:

Headers

• for Device API v1:
  • the ability-messagetype identifier is set to platformEventAck
  • header eventType is set to the original value
• for Device API v2:
  • the msgType identifier is set to ack
  • version is set to 2
  • headers action, correlationId, target are set to the original value
• have current information filled in (objectId, model, type, etc.) as available in original platform event

Payload

Message payloads are defined per each incoming platform event separately. The payloads contain common pieces which are available in each response from the platform:

Property	Data Type	Description
success	boolean	contains "true" or "false"
code	string	if success = false, must contain an error code, expressed as a string value, i.e. validation_error, not_authorized
details	string	contains a larger text, human-readable explanation specific to this occurrence of the problem

The list of all possible codes is described under page: Business Codes.

An acknowledgement will be generated if deviceId can be successfully extracted from the message headers (this is a header that is added by IoT Hub by default, which is the usual case (when extraction fails it is usually a critical platform error).

Example Ack Message Content

This section describes an example ack message content. Properties section is mapped to custom properties of message itself, and body contains the payload.

{
  "properties": {
    "ability-messagetype": "platformEventAck",
    "eventType": "Abb.Ability.Device.Created",
    "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
}

#