# Device.Deleted

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.

Delete an object model (aka requested model) in IM.

Abb.Ability.Device.Deleted 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 deleted in IM. One of the two following outcomes will occur due to this design:

First delete of an existing object model (determined via objectId + model) will be successful
Following deletes of this object model will be rejected

# Prerequisites

(Information Model) Requested model must exist

# Message Format

Abb.Ability.Device.Deleted 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 and the messages needed to follow the authorization guidelines. Now, the principle 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.Deleted",
      "id": "<correlation id>",
      "objectId": "<GUID>",
      "model": "<model definition>",
      "ack": "<ack>",
      "target": "<connected device path>"
    }
  }

# 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.Deleted`
`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 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.Deleted` Platform Event

Property	Mandatory?	Description
`objectId`	Mandatory	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`

# Validation Rules

DCS validates all message properties as specified below. DCS does not validate message body because it is empty.

# Functionality

# Description

Object model is deleted in IM (including children with isContainment flag)
'request-response' model notification c2d message 'Abb.Ability.InformationModel.ObjectModelDeleted' is sent back to directly connected device where it can also be propagated further if needed (based on target)
- Message is only sent for the requested model itself, not for child models
- For further details see Device API Notifications
- target is reused from requested message
  Model notification c2d
  
  The message described above is generated by DCS. Any platform events generated by IM, related to this request, are ignored by DCS and not propagated
If requested, acknowledgement c2d message is sent back to 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.ObjectModelDeleted",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "target": "<connected device path>"
  }
}

MESSAGE BODY

Body in this message is empty.

# Format of returned acknowledgement c2d message

{
  "properties": {
    "ability-messagetype": "platformEventAck",
    "eventType": "Abb.Ability.Device.Deleted",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "target": "<connected device path>"
  },
  "body": {
    "success": true, //or false, this accepts booleans
    "code": "<error code>",
    "details": "<error detail>"
  }
}

# Error Handling

When an error occurs:

A Device.Deleted 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.

← Device.Created (V1) Device.Updated (V1) →