# Device.SyncModel

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.

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

Supports fetching of additional child models (recursively) by references (either by reference names or by isContainment attribute). Supports fetching of additional object models that share the same objectId (i.e. related models).

Abb.Ability.Device.SyncModel 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 same responses being sent back.

# Prerequisites

(Information Model) Requested model must exist

# Message Format

Abb.Ability.Device.SyncModel 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.SyncModel",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "ack": "<ack>",
    "target": "<connected device path>"
  },
  "body": {
    "hierarchical": true, //or false, accepts booleans
    "references": ["array of outgoing reference names to follow and collect models for"],
    "contained": true, //or false, accepts booleans
    "recursive": true, //or false, accepts booleans
    "related": ["array of model definition identifiers to collect as a part of this request"]
  }
}

# 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.SyncModel`
`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.
`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 ObjectModel.Updated notifications for all fetched models.

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

Property	Mandatory?	Description
`objectId`	Mandatory	Must be in GUID format
`model`	Mandatory	Model definition identifier. Case sensitive. May be present either in message properties or body. Any model, including `abb.ability.device`, is supported.

# Message Body

Property	Mandatory?	Description
`hierarchical`	Optional	Boolean. Mutually exclusive with `references` and `contained`
`references`	Optional	Array of strings containing reference names
`contained`	Optional	Boolean. Mutually exclusive with `references` and `hierarchical`
`recursive`	Optional	Boolean. Mutually exclusive with `hierarchical` and `contained`
`related`	Optional	Array of strings containing model definition identifiers

# Validation Rules

DCS validates all message properties, that message body is in proper JSON format, and all message body properties as specified below.

# Functionality

# Description

Information Model is queried for latest object model versions. Following object models are fetched:

Requested model, specified with objectId and model in requested message
Requested model's child models, targeted by outgoing hierarchical references (within requested model's modelId)
- If hierarchical is true, all references are traversed
- Otherwise, if contained is true, only references with 'isContained=true' are traversed
- Otherwise, if references are specified in requested message, only references with matching reference names are traversed
- Otherwise, no child models are fetched
- If recursive is true, references are traversed recursively, i.e. for each object model targeted by an outgoing link, repeat the above steps
If related is specified, also object models matching the specified model definition identifiers are fetched, both for the requested model and its child models
For each fetched object model, 'request-response' model notification c2d message 'Abb.Ability.InformationModel.ObjectModelUpdated' is sent back to directly connected device where it can also be propagated further if needed (based on target)
- target is reused from requested message
For further details, please read the Device API Notifications page
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 messages

{
  "properties": {
    "ability-messagetype": "platformEvent",
    "eventType": "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

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

# Error Handling

When an error occurs:

A Device.SyncModel 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.Updated (V1) Global ID Generator API service →