# Extension.Get

The Device API of the Ability Platform uses the information model service to allow a user to retrieve type extensions for a specific model.

# Idempotency

The extension.get action is idempotent. Sending several identical extension.get requests will result in same the responses being sent back.

# Event Properties

# Unique Message Headers

Property	Mandatory	Description
objectId	Mandatory	Source object identifier. Must be in GUID format.
model	Optional	Source model definition identifier (modelId). Case sensitive. If not provided, defaults to "abb.ability.device".
extensionVersion	Optional	Integer. Specified version of type definition extension for object model.

# Message Body

There is no message body.

# Message Format

{
  "properties": {
    "iothub-connection-device-id": "<authenticated device id>",
    "msgType": "action",
    "action": "extension.get",
    "version": 2,
    "correlationId": "<correlation id>",
    "model": "<model definition>",
    "objectId": "<GUID>",
    "extensionVersion": "<version>",
    "ack": "<ack>",
    "target": "<connectivity path>",
    "timeout": "<integer>"
  },
  "body": "none"
}

# Message Properties

# Added by the IoTHub

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

# Common for All v2 Requests

Property	Mandatory	Description
msgType	Mandatory	Must be equal to "action"
action	Mandatory	Must be equal to "extension.get"
version - Mandatory	Must be equal 2
correlationId	Optional	Correlation ID. Should be included to track correlation of platform components. If not present, the DCS will generate a new one.
ack	Optional	Initialized to a "none" value if the value missing. Indicates an additional acknowledgement message to be sent to the device. For more details, see Acknowledgement Handling. Note that for this action, only the values "all" and "positive" are valid. Providing a different value will result in a validation error and the request will not be processed.
target	Optional	If not provided, defaults to an empty string. Represents the path to a connected device that wishes to receive the acknowledgement (if requested).
timeout	Optional	If not provided, defaults to a 300 integer. Represents the parameter that will be used to indicate the maximum number of seconds available for processing the D2C message until the timeout occurs. This excludes sending back response C2D messages.

# Specific to an `extension.get` Request

Property	Mandatory	Description
objectId	Mandatory	Source object identifier. Must be in GUID format.
model	Optional	Source model definition identifier (modelId). Case sensitive. If not provided, defaults to "abb.ability.device".
extensionVersion	DEPRECATED	Integer. Specified version of type definition extension for object model. From platform version 20.10 forward this property is no longer in use and should be removed from any requests.

# Validation Rules

DCS validates all message properties as specified in the summary of all v2 Device API messages. DCS does not validate message body because it is empty.

# Functionality

# Description

The extension is fetched from the IM.
A model notification C2D message is not sent back.

NOTE

Any platform events generated by the info model, related to this request, are ignored by the DCS and are not propagated.

If requested, an acknowledgement C2D message is sent back to the directly connected device where it can also be propagated further if needed (based on the target). For more details see Acknowledgement Handling.
The target is reused from the requested message.

NOTE

Since the acknowledgement also contains the extension, not requesting a positive acknowledgement means that the user will not be able to get it. This implies that the request must contain the "ack" property value "all" or "positive" to be valid. Providing a different "ack" value will result in a validation error and the request will not be processed.

# Format of a Returned Acknowledgment C2D Message

# Format of a Successful Acknowledgment

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "extension.get",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>"
    },
    "body": {
       "success": true,
       "code": "ok",
       "details": "",
       "extension": {
         //type extension
         }
    }
}

# Description of Body Properties

Property	Mandatory	Data Type	Description
extension	Mandatory	JSON object	type extension

# Example Message when Extension was not Found

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "extension.get",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>"
    },
    "body": {
       "success": true,
       "code": "ok",
       "details": "''",
       "extension": {}
    }
}

# Format of a Failing Acknowledgment

{
    "properties": {
      "msgType": "ack",
      "action": "extension.get",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>"
    },
    "body": {
      "success": false,
      "code": "<error code>",
      "details": "<error detail>"
    }
}

# Error Handling

When an error occurs:

Error information is logged inside the platform (in Application Insights).
If a response can be delivered to a device, an acknowledgment will be sent, if requested. For more, see Acknowledgement Handling.

← Extension.Create (V2) Batch.Execute (V2) →