# Model.Patch Request

The Ability Platform supports sending info model patches using the model.patch API endpoint. The model.patch action message is sent to the platform by a directly connected device (i.e. Edge) via the IoTHub. All C2D messages (acks and notifications) sent in response to a model.patch action are sent in Device API v2 format.

The requested info model must exist.

# Idempotency

The model.patch message is Idempotent. This means that sending several identical requests will result in the model being updated successfully in the Info Model Service:

The first partial update of an existing object model (determined via objectId + model) will be successful.
Subsequent partial updates of this object model will be rejected due to an object model version mismatch.

# 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 body must consist of a well-formed JSON compliant with the request payload format of a PATCH /objects/{objectId}/models/{modelId} operation.

Property	Mandatory	Data Type	Description
version	Mandatory	integer	Must be equal to or higher than the version of the model existing in the IM database.

# Message Format

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

# Validation Rules

DCS validates all message properties, message body is in proper JSON format,and message body property version as specified in the list of v2 device apis. The message body is then passed to Instance API PATCH /objects/{objectId}/models/{modelId} endpoint where the remaining validation is performed.

# Functionality

# Description

The object model is partially updated in the info model service.
In case of version gaps, the DCS will perform a patch operation multiple times.
After all patches are completed, the patched model version in the IM is equal to the request message version + 1.
A model notification C2D message is not sent back.

NOTE

Any platform events generated by the info model service 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 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": "model.patch",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>"
    },
    "body": {
       "success": true,
       "code": "ok",
       "details": "''",
       "objectId": "<objectId>",
       "model": "<model>",
       "version": "<version>"
    }
}

Description of body properties

Property	Mandatory	Data Type	Description
objectId	Mandatory	JSON object	ObjectId of patched model.
model	Mandatory	JSON object	Model identifier of patched model.
version	Mandatory	JSON object	Version of patched model.

# Format of a Failing Acknowledgment

{
    "properties": {
      "msgType": "ack",
      "action": "model.patch",
      "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 Ability Platform (in Application Insights). If a response can be delivered to a device, an acknowledgment will be sent, if requested. For more details see Acknowledgement Handling.

← Model.Update (V2) Type.Create (V2) →