# Extension.Create

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

The requested information model must exist.

# Idempotency

The extension.create action is idempotent. Sending several identical extension.create requests will result in the type extension being successfully created/updated in the info model.

If a type extension does not exist yet, it will be created.
If a type extension already exists (determined via objectId + model), it will be updated.

# 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".

# Message Body

The message should be composed of a well-formed JSON compliant to the request payload format of a PUT /objects/{objectId}/models/{modelId}/extension operation.

Example body payload:

  {
     "properties": {
       "someProperty": {
         "dataType": "string"
      }
    }
  }

# Message Format

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

# Validation Rules

DCS validates all message properties and the message body is in proper JSON format as specified in the summary of all v2 Device API messages. DCS does not validate any message body properties. The message body is then passed to the Instance API PUT /objects/{objectId}/models/{modelId}/extension endpoint where the remaining validation is performed.

# Functionality

# Description

The type extension is created by the info model service.
If the extension already exists then it is updated.
There is no need to provide a version for the info model endpoint. Version handling is performed by the IM/TDR.
For an type extension that is created, the type extension's version is set to 1.
For an type extension that is updated, the type extension's version is increased by 1.
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.

# Format of a Returned Acknowledgment C2D Message

# Format of a Successful Acknowledgment

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

# Description of Body Properties

Property	Mandatory	Data Type	Description
objectId	Mandatory	String	Source object identifier of created/updated model extension
model	Mandatory	String	Source model definition identifier of created/updated model extension

# Format of a Failing Acknowledgment

{
    "properties": {
      "msgType": "ack",
      "action": "extension.create",
      "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.

← Owner.Remove (V2) Extension.Get (V2) →