# Device.Created

# Abb.Ability.Device.Created

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.

Create or update an object model (aka requested model) in the information model.

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

if an object model does not exist yet, it will be created.
if an object model already exists (determined via objectId + model or type + unique properties), it will be updated.

There is one case when idempotency is not fulfilled, when no objectId or unique properties are provided in the payload a new model is always created. For such Abb.Ability.Device.Created messages there will be several models created each with a different objectId.

# Prerequisites

When creating/updating any object model:

(Type Registry Service) Type definition for the requested model's type must exist
When requested model is to be connected to a parent, (Information Model) the parent's object model (with the same modelId as the requested model) must exist
Owner identity must already exist and must be connected via this directly connected device

# Register a Device

Registration of a directly connected device in the IoT hub is necessary before the device can transmit messages to or receive messages from the ABB Ability™ Platform.

# Publishing a Device Created Event

Publish the Abb.Ability.Device.Created platform event in order to register your device in ABB Ability™ (Ideally this should be performed only on the first boot sequence. Thereafter, the objectId can be stored in the device storage)

# Message Format

Abb.Ability.Device.Created event message has the following format when it is received and ready for processing. Only data relevant for DCS is shown.

{
  "properties": {
    "iothub-connection-device-id": "<device id>",
    "ability-messagetype": "platformEvent",
    "eventType": "Abb.Ability.Device.Created",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "ack": "<ack>",
    "target": "<connected device path>",
    "owner": "<relative path>"
  },
  "body": {
    "name": "<name>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "type": {"typeId@version"},
    "properties": {
      //... - other instance specific properties
    },
    "variables": {"instance specific attributes"},
    "parent": {
      "objectId": "<GUID>",
      "reference": "<reference name>"
    }
  }
}

# Register a Device

Registration of a directly connected device in the IoT hub is necessary before the device can transmit messages to or receive messages from the ABB Ability™ Platform.

Publish the Abb.Ability.Device.Created platform event in order to register your device in the ABB Ability™ Platform (Ideally this should be performed only on the first boot sequence. Thereafter, the objectId can be stored in the device storage).

After the registration completes, your device will receive an Abb.Ability.InformationModel.ObjectModelCreated platform event message (or Abb.Ability.InformationModel.ObjectModelUpdated message if your device has already been registered).

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

Property	Mandatory?	Description
`objectId`	Optional	May be present either in message properties or body. 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`.
`owner`	Optional	An owner of this new model in the form of a relative path. If absent, a directly connected device is presumed to be the owner.

# Message body

Property	Mandatory?	Description
`name`	Optional
`objectId`	Optional	May be present either in message properties or body. 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'
`type`	Mandatory	Type definition (type identifier + major version after @ symbol, i.e. 'abb.ability.deviceControllerType@1'). Case sensitive. Specifying type definition version is optional
`properties`	Optional	Case sensitive. The properties of the object model include any defining information.
`variables`	Optional
`parent`	Optional	When the requested model should be connected to a parent the parent must be specified in the request message. This operation only creates a reference to the parent for user purposes. The reference is no longer used by the platform for authorization, connectivity or ownership. When the requested model should not be connected to a parent the parent must not be specified in the request message.
`parent.objectId`	Mandatory	Must be in GUID format
`parent.reference`	Mandatory	Reference name (must match reference name specified in parent's type definition)

# Validation rules

DCS validates all message properties, that the message body, and the message body properties objectId, model, type, parentObjectId and parentReference as specified below. The message body is then passed to the Instance API POST /objects/{objectId} or PUT /objects/{objectId}/models/{modelId} endpoint where the remaining validation is performed.

# Functionality

The existence of an object model in the information model service is verified when the objectId is provided in request message otherwise it is checked by unique properties. The object model is either created, or updated, in the information model service, depending on whether the object model already existed in information model service before the request. For an object model that is created:

If the objectId was not provided in the request message, a new objectId is generated
The object model's version in the information model service is set to 1
Related object models are also created (if missing)

For an object model that is updated:

The object model's version in the information model service is increased by 1

When an object model already exists in the information model service within your tenant and it does not have an owner, the device API will perform an ownership claim on the object model before updating it.

WHAT IS AN OWNERSHIP CLAIM?

An ownership claim is when the previously unowned model in a tenant will be owned by the principal manager of the connected object. This claim is represented by the ownerId and path attributes in a model.

For request messages that contain a parent, a reference between an object model and the parent object model is created, within the requested model's modelId:

If reference to a parent already existed in the information model service before the request, the parent's objectId and name must be matching (changing the parent is not supported)

Model notification C2D messages are sent back to the directly connected device where they can also be propagated further if needed (based on target). Depending on the case, notifications for following object models can be sent via:

'request-response' notification for the requested model
- This notification is sent in all cases
- eventType is either 'Abb.Ability.InformationModel.ObjectModelCreated' or 'Abb.Ability.InformationModel.ObjectModelUpdated', depending on whether the requested model's object model was created or updated in IM
- target is reused from requested message
'publish-subscribe' notification for the abb.ability.configuration model
- This notification is sent only when requested model's modelId is 'abb.ability.device'
- target is taken from the subscription, the connectivity path of the device model owner. For more details about notifications see the reference page for notifications

TIP

All model notification C2D messages described above are generated by the DCS. Any platform events generated by the IM, related to this request, are ignored by the DCS and 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
- target is reused from the requested message

TIP

A successful operation is measured only by creation of a requested model and a reference to a parent (if applicable). Failure to create related models still constitutes success.

# Format of returned model notification C2D messages

{
  "properties": {
    "ability-messagetype": "platformEvent",
    "eventType": "Abb.Ability.InformationModel.ObjectModelCreated", //or "Abb.Ability.InformationModel.ObjectModelUpdated"
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "target": "<connected device path>"
  },
  "body": {"full object model"}
}

# Format of returned acknowledgement C2D message

When an unsuccessful acknowledgement of this platform event is returned, the objectId is not sent.

{
  "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 this model (and a reference to a parent, if applicable) creation was successful
    "code": "<error code>",
    "details": "<error detail>",
    "relatedModels": [ //for each related model, specifies an error or a success
      {
        "model": "<model definition>",
        "success": true, //whether this object model was successfully created or found based on unique mapping
        "code": "<error code>", //if success = false, must contain an error code, expressed as a string value, i.e. validation_error, not_authorized. Same list of error codes as above
        "details": "<error detail>" //human-readable explanation specific to this occurrence of the problem
      }
    ]
  }
}

# Error handling

When an error occurs:

Device.Created message is completed inside the platform (on ServiceBus)
Error information is logged inside the platform (in Application Insight)
If a response can be delivered back to the device - acknowledgments are sent back to the device, if requested. More details can be found here: Acknowledgement Handling
If a response cannot be sent back to the device - message is completed and only errors are logged.

← Batch.Execute (V2) Device.Deleted (V1) →

# Device.Created

# Abb.Ability.Device.Created

# Prerequisites

# Register a Device

# Publishing a Device Created Event

# Message Format

# Register a Device

# Message Properties

# Added by IoTHub

# Common for all Platform Events

# Specific to Abb.Ability.Device.Created Platform Event

# Message body

# Validation rules

# Functionality

# Format of returned model notification C2D messages

# Format of returned acknowledgement C2D message

# Error handling

# Specific to `Abb.Ability.Device.Created` Platform Event