# Model.Create

The model.create event's purpose is to create or update an object model (aka requested model) in IM. If the model you are creating with this event already exists in the cloud it will be updated. The platform determines if a model exists in the information model service by checking if the objectId and model, or type and unique properties are present.

When creating any object model, the requested object model's type definition must already exist in the Type Definition Registry. The owner identity must already exist and must be connected via a directly connected device as well.

The Ability Platform allows the creation or update of a model with the latest type version when the type version is not specified in the payload.

# Idempotency

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

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

Idempotency fulfilment

There is one case where idempotency is not fulfilled: When neither an objectId nor any unique properties are provided in the payload, a new model is always created. For each model.create request, a model will be created, each with a different objectId.

# Validation Rules

DCS validates all message properties, the message body is in proper JSON format. DCS does not validate any message body properties. The message body is then passed to Device API PUT /objects/{objectId}/models/{modelId} endpoint where the remaining validation is performed.

# Event Properties

# Unique Message Header

Property	Mandatory	Description
owner	Optional	An owner of this new model, as a relative path. If absent, a directly connected device is presumed to be the owner.

# Message Body Properties

Property	Mandatory	Description
name	Optional
objectId	Optional	If provided, must be a string in a GUID format.
model	Mandatory	Model definition identifier (modelId), any model including "abb.ability.device" is supported (case sensitive).
type	Mandatory	Type definition ID (type identifier + major version after @ symbol, i.e. "abb.ability.deviceControllerType@1"). Specifying the type definition version is optional (case sensitive).
properties	Optional
variables	Optional

# Message Format

The event message format has the following structure when it is received from a directly connected device and it is ready for processing.

{
  "properties": {
    "iothub-connection-device-id": "<authenticated device id>",
    "msgType": "action",
    "action": "model.create",
    "version": 2,
    "correlationId": "<correlation id>",
    "ack": "<ack>",
    "target": "<connectivity path>",
    "timeout": "<integer>",
    "owner": "<owner>"
  },
  "body": {
      "name": "<name>",
      "objectId": "<GUID>",
      "model": "<model definition>",
      "type": { "typeId@version" },
      "properties": {"instance specific properties"},
      "variables": {"instance specific variables"}
  }
}

# Functionality

The existence of an object model in the Information Model Service is checked by searching the service for a combination of:

objectId and model: if the objectId property is part of the request
Note: DCS will find the existing model of the same typeId or different typeId, regardless of the major version.
typeId and unique properties: if the objectId property is not part of the request
Note: DCS will find the existing model only of the same typeId, regardless of the major version.

If these properties are found in an object model in the service, then the Platform determines if the object model is being created or updated by this event. There are two sets of expected results upon receipt of the event:

For an object model that is created:

If 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 IM is increased by 1.

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

DEFINING SUCCESSFUL OPERATIONS

A successful operation is measured only by creation of a requested model. Failure to create related models still constitutes success.

# Handling of Type Definition Version

Depending on whether the model is to be created or updated, the DCS uses the info model endpoints POST /object or PUT /objects/{objectId}/models/{modelId}, respectively.

Both of these info model endpoints accept a type with or without a version, and so does the DCS.

Whether with or without a version, the model.create payload body will include a type property of the info model.

When a type without a version is used in a model.create request payload, all processing is performed by the info model service alone.

For a discussion on how the info model service endpoints POST /object and PUT /objects/{objectId}/models/{modelId} function with and without a type version specified, see Information Model Service Use Case for Type Versioning.

# Switching to Different Type Definition

It is possible using model.create message to switch existing object model to different Type Definition.
Switching to different Type Definition means:

Explicit upgrade/downgrade of type version, or
Explicit change to different type/subtype (in scope of the same unique group)

To switch between type definitions, Type Version has to be specified in request payload.
More info about unique group You can find here

# Cloud to Device Messages (C2D)

Model notification C2D messages are sent back to directly connected devices from the platform where they can be propagated further if needed (based on the target property sent in the message).

Ignored platform events

Any platform events related to this request that are generated by the Information Model Service are ignored by the DCS and are not propagated.

Depending on the case, notifications for the following classifications of object models can be sent:

# Requested Model

In all cases, a 'request-response' notification will not be sent. For more, see request-response Notification Conditions, below.

# Requested Model's Subscribed Models

This 'publish-subscribe' notification is sent only when the requested model's modelId is abb.ability.device. A subscribed model can be identified as any model with a modelId equal to abb.ability.configuration that shares its objectId with the requested model.

The eventType is either Abb.Ability.InformationModel.ObjectModelCreated or Abb.Ability.InformationModel.ObjectModelUpdated, depending on whether the subscribed model was created or already exists in IM.

Backwards compatibility

This notification is sent in Device API v1 format to maintain backwards compatibility.

target contains the model owner's connectivity path.

# Format of returned model notification C2D messages 'Abb.Ability.InformationModel.ObjectModelCreated' and 'Abb.Ability.InformationModel.ObjectModelUpdated'

{
  "properties": {
    "ability-messagetype": "platformEvent",
    "eventType": "Abb.Ability.InformationModel.ObjectModelCreated", //or "Abb.Ability.InformationModel.ObjectModelUpdated",
    "id": "<correlation id>",
    "objectId": "<GUID>",
    "model": "<model definition>",
    "target": "<target matches the target in the corresponding action>"
  },
  "body": {"full object model"}
}

# Format of Returned Acknowledgment C2D Message

# Format of a Successful Acknowledgment

{
  "properties": {
    "msgType": "ack",
    "action": "model.create",
    "version": 2,
    "correlationId": "<correlation id>",
    "target": "<target matches the target in the corresponding action>",
    "timestamp": "<YYYY-MM-DDTHH:mm:ss.sssZ>"
  },
  "body": {
    "success": true,
    "code": "ok",
    "details": "",
    "objectId": "<objectId>",
    "relatedModels": [ //for each related model
      {
        "model": "<model definition>",
        "success": true,
        "code": "<error code>",
        "details": "<error detail>"
      }
    ]
  }
}

# Format of a Failing Acknowledgment

{
  "properties": {
    "msgType": "ack",
    "action": "model.crete",
    "version": 2,
    "correlationId": "<correlation id>",
    "target": "<target matches the target in the corresponding action>",
    "timestamp": "<YYYY-MM-DDTHH:mm:ss.sssZ>"
  },
  "body": {
    "success": false,
    "code": "<error code>",
    "details": "<error details>",
    "relatedModels": [ //for each related model
      {
        "model": "<model definition>",
        "success": true, // orfalse,
        "code": "<error code>",
        "details": "<error detail>"
      }
    ]
  }
}

# request-response Notification Conditions

The Device API will not send a C2D 'ObjectModel.Created/Updated' notification message for a requested model. To request a notification message, use the model.query action.

In general, it is recommended that the user not request such a notification unless necessary, due to the additional C2D bandwidth required. See also Requested Model, above.

The Device API will send:

a 'publish-subscribe' notification for the configuration model (if the requested model is 'abb.ability.device')

If requested by the user, the Device API will also send:

a 'request-response' acknowledgement

When a 'request-response' acknowledgement is requested with a model.query message, the user may use a batch of model.create + model.query messages. This allows the user to send only one D2C message rather than each message individually. For more information on batch message loading, see Batch.Execute (V2).

'Request-response' notification

The Edge can still use the Device API v1 Device.Created message, which still sends back a 'request-response' notification for the requested model.

# Error Handling

When an error occurs, the following processes occur in the platform to log relevant information:

A model.create message is completed inside the platform on the Azure ServiceBus.
Error information is logged inside the platform in Application Insights.
If a response can be delivered back to the device, acknowledgments are sent back to the device, if requested.
If a response cannot be sent back to the device, the message is completed and only the error is logged.

← Identity.Delete (V2) Model.Query (V2) →