# Identity.Update (V2)

Update indirectly or directly connected device properties in Principal Manager (PM).

'identity.update' action message is sent to the platform by a connected device via IoTHub.

# Idempotency

This request is idempotent:

sending several identical requests will result in the identity properties being successfully updated in PM
- first update of an existing identity (determined via identity in the context of a parent) properties will be successful
- following updates of this identity properties will also be successful

# Prerequisites

Identity of the directly connected device (i.e., Edge) is created by tenant admin during bootstrap process.
(Principal Manager) The identity must exist and must be connected via the directly connected device (Edge)

# Event properties

# Unique Message Headers

| Key | Mandatory/Optional | Value Type | Allowed Values | Description | |-----------|:----------------------😐:--------------😐:------------------😐:---------------😐 |"parent"| Optional | String | Any string | A parent of an identity, as a relative path. This identity must already exist and must be connected via this directly connected device. If absent, a directly connected device itself is the parent of identity that is being updated. Relevant only if identity is provided.|

# Message body

Well-formed JSON compliant to the request payload format of PM PUT/devices/{deviceId} operation containing among others:

Key	Mandatory/Optional	Value Type	Allowed Values	Description
"identity"	Optional	String	Any string	Identity, must be unique within the parent. If identity is not provided then update is performed on directly connected device's properties.
"publicKey"	Optional	String	Any string	Key that need to be stored in the platform in order to be used for encryption of secret values.

# Validation rules

DCS validates all message properties as specified above.
DCS validates that message body is in proper JSON format. DCS also validates message body property identity as specified above. Message body is then passed to PM PUT /devices/{deviceId} endpoint where remaining validation is performed.
If the header size is too large, unsuccessful acknowledgement is sent back with a "platform_event_validation_error" error code and a detailed message: "Request message header properties size limit of 32 kB exceeded"

# Functionality

# Description

The device principal for a requested identity is updated in the PM. If there is no identity, the directly connected device will be updated in the PM instead
The 'request-response' identity notification c2d message is not sent back
- Note: Any platform events generated by IM, related to this request, are ignored by DCS and not propagated
If requested, 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 requested message

# Format of returned acknowledgement c2d message

# Format of successful acknowledgement

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "identity.update",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<some target>",
      "context": "<user context data>"
    },
    "body": {
      "success": true,
      "code": "ok",
      "details": "",
      "parent": "<parent from the identity.update message>",
      "identity": "<identity from the identity.update message>"
    }
}

# Format of successful compressed acknowledgement

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "identity.update",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<some target>",
      "content-encoding": "gzip",
      "context": "<user context data>"
    },
    "body": "H4sIAAAAAAAA/22MQQqDMBBF955Csm4kE6MGV9120ztkzAgpESVGQcS7Nyp01Q+zefP+37M8ZyN+qIsvy9qcCasImkbzvlc1V1oLjpUSXIBUoABLaQ17nK1htOTPikEsDDrv4lZYWl1HtxC3if7/i0hzfMKtTWGcKERHc5L3RBKbKTjj38uAFH408dX45dqUQtRQgaw0lFykSMUu6cjOO74y+pET2AAAAA=="
}

# Format of failing acknowledgement

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "identity.update",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<some target>",
      "context": "<user context data>"
    },
    "body": {
      "success": false,
      "code": "<error code>", 
      "details": "<error detail>"
    }
}

# Format of failing compressed acknowledgement

{
    "properties": {
      "msgType": "ack",
      "timestamp": "YYYY-MM-DDTHH:mm:ss.sssZ",
      "action": "identity.update",
      "correlationId": "<correlation id>",
      "version": 2,
      "target": "<some target>",
      "content-encoding": "gzip",
      "context": "<user context data>"
    },
    "body": "H4sIAAAAAAAA/22MQQqDMBBF955Csm4kE6MGV9120ztkzAgpESVGQcS7Nyp01Q+zefP+37M8ZyN+qIsvy9qcCasImkbzvlc1V1oLjpUSXIBUoABLaQ17nK1htOTPikEsDDrv4lZYWl1HtxC3if7/i0hzfMKtTWGcKERHc5L3RBKbKTjj38uAFH408dX45dqUQtRQgaw0lFykSMUu6cjOO74y+pET2AAAAA=="
}

# Error handling

When an error occurs:

Error information is logged inside platform (in Application Insight)
If response can be delivered back to device - acknowledgments are sent back to device, if requested. More details can be found here: Acknowledgement Handling

← Identity.Create (V2) Identity.Delete (V2) →