# Type.Create Request

This message is used to create a type definition in the TDR of the given model definition. The 'type.create' action message is sent to the platform by a directly connected device (i.e. Edge) via the IoT hub. This is a completely new message in Device API v2 format.

The Device API of the Ability platform allows a BL developer to create, read, update, and delete (CRUD) data for managing types from directly connected devices using the Device API. Specifically, the feature supports the type.create message type.

NOTE

At present, the IoT Hub restricts C2D message size to 64kB. This means that a single type definition larger than 64kB will not be properly handled by the Device API. This limitation will be addressed in a future platform release.

# Idempotency

This request is idempotent, meaning that sending several identical requests will result in the type being successfully created in TDR. One of the two following outcomes will occur due to this design:

If a type does not exist yet, it will be created
If a type already exists (determined via typeId and version), it will be rejected
- Types of a specific version cannot be updated. Instead, new type version must be created.

# Event Properties

# Unique Message Headers

Property	Mandatory	Description
model	Optional	Source model definition identifier (modelId). Case sensitive. If not provided, defaults to "abb.ability.device".

# Message Body

The body is composed of a well-formed JSON compliant to the request payload format of a POST /modelDefinitions/{modelId}/types operation.

# Message Format

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

# Validation Rules

DCS validates all message properties and that the message body is in proper JSON format as specified in the summary of all v2 Device API messages. DCS does not validate any message body properties. The message body is then passed to the Instance API POST /modelDefinitions/{modelId}/types endpoint where the remaining validation is performed.

# Functionality

# Description

The type definition is created in the TDR.
A type notification C2D message is not sent back.

NOTE

DCS will never send back a 'request-response' notification message. Any platform events generated by the IM service related to this request are ignored by the DCS.

If requested, an acknowledgement C2D message is sent back to the directly connected device where it can be propagated further, as needed (based on target). Note that the target is reused from the requested message. For more, see Acknowledgement Handling.
The target is reused from the requested message.

# Format of Returned Acknowledgement C2D Message

The general format of a Device API v2 acknowledgement message is described in Acknowledgement Handling.
CorrelationId and target should be reused from the input action.
The format of a successful acknowledgement includes a header and the boolean property true in the body. Note the following:
- Header - contains:
  - a timestamp with a required string data type. The timestamp is rendered in simplified extended ISO format (YYYY-MM-DDTHH:mm:ss.sssZ) and must be a zero UTC offset, as denoted by the suffix "Z".

Successful Acknowledgement:

{
  "properties": {
    "msgType": "ack",
    "action": "type.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": "",
    "typeId": "<typeId>",
    "model": "<model>",
    "version": "<version>"
    }
}

The format of a failed acknowledgement includes a header and the boolean property false in the body. Note the following:
- Header - contains:
  - a timestamp with a required string data type. The timestamp is rendered in simplified extended ISO format (YYYY-MM-DDTHH:mm:ss.sssZ) and must be a zero UTC offset, as denoted by the suffix "Z".
- Body - contains:
  - success (false), code, and details

Failed acknowledgement:

{
  "properties": {
    "msgType": "ack",
    "action": "type.create",
    "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>"
    }
}

← Model.Patch (V2) Type.Delete (V2) →