# Reference.Create Request

This message is used to create a reference. The Device API of the Ability platform allows a BL developer to create, read, update, and delete (CRUD) data for managing references from directly connected devices using the Device API. Specifically, the feature introduces support for the reference.create message type initiated by a directly connected device.

# Idempotency

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

If a reference does not exist yet, it will be created
If a reference already exists (determined via objectId + model), its attributes will be updated

# Event Properties

# Unique Message Headers

Property	Mandatory	Description
objectId	Mandatory	Source object identifier. Must be in GUID format.
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 /objects/{objectId}/models/{modelId}/references/out operation.

# Message Format

{
  "properties": {
    "iothub-connection-device-id": "<authenticated device id>",
    "msgType": "action",
    "action": "reference.create",
    "version": 2,
    "correlationId": "<correlation id>",
    "ack": "<ack>", 
    "target": "<connectivity path>",
    "timeout":"<integer>",
    "objectId": "<objectId>",
    "model": "<model>"
  },
  "body": [
    {
      "name": "isMountedTo",
      "to": {
        "objectId": "objectId",
        "model": "<model>"
      },
      "attributes": {"instance-specific attributes"
      }
    }
  ]
}

# Validation Rules

DCS validates all message properties and that the message body is in proper JSON format as specified in the summary page 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 /objects/{objectId}/models/{modelId}/references/out endpoint where the remaining validation is performed.

# Functionality

# Description

The reference is created in the IM.
If the reference already exists then its attributes are updated.
A reference 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.

# Format of Returned Acknowledgement C2D Message

Successful acknowledgement:

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "reference.create",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>"
    },
    "body": {
      "success": true,
      "code": "ok",
      "details": ""
    }
}

Failed acknowledgement:

{
    "properties": {
      "msgType": "ack",
      "action": "reference.create",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<target matches the target in the corresponding action>"
    },
    "body": {
      "success": false,
      "code": "<error code>",
      "details": "<error detail>"
    }
}

← Type.Query (V2) Reference.Delete (V2) →