ADZ stream notifications

When updates are made to a catalog via ADZ, stream notifications about the changes are sent in an envelope object from the data-updates streaming layer. A sample envelope is below.

Detailed information about the change can be found in the envelope's payload array. Each payload will contain certain key-value pairs describing what attributes were changed, how they were changed, and if they were added or removed.

Example envelope

📘
Each envelope has its own unique envelopeID number.
For performance reasons, an envelope may contain several messages. Ensure you read and understand each message bundled in an envelope.

{
  "envelopeId": "e82ismwe3ms0",
  "targetRctSpace": {
    "herePlatformOrganizationId": "olp-example-organization",
    "spaceCode": "11"
  },
  "auditInfo": {
    "createdAtUtc": "2025-01-18T00:51:18.371",
    "creatorId": ""
  },
  "payload": [/*Action-specific messages are listed in this array.*/]
}

User action messages

Message	Description	Message content
`attributes-change`	An ODD attribute was added, removed, or updated.	For updated attributes, the message indicates the `previous` and `current` states of the attribute. `current` also includes newly added attributes, while `previous` lists deleted attributes.
`attributes-read`	Returns information about an attribute.	The message lists information about an attribute.
`request-result`	An action has successfully finished.	The message includes execution statistics, with the total count of the modified segment.
`invalid-request`	The requested action is invalid or impossible.	The message includes information about why the request was invalid.

Map update messages

📘
The content of an attributes-change message varies depending on the type of attribute and the action that was applied. For more information, see Attribute change messages

Event	Message	Change Type	Description	Message content
Addition of a new map element	`attributes-change`	`new-element`	A map was loaded containing segments with new IDs, indicating the presence of new elements	All map attributes of the newly added element in the current field
Updated an existing map element	`attributes-change`	`metadata-update`	Only occurs if a geometry or graph topology of the segment has changed.	TODO
Updated an existing map element	`attributes-change`	Occurs if any change was applied to any map attribute, including additions, removals, or updates, or a combination of changes	For updated attributes, the message indicates the `previous` and `current` states of the attribute. `current` also includes newly added attributes, while `previous` lists deleted attributes.
Removed an existing map element	`attributes-change`	`delete-element`	A map was loaded that no longer contains segments present in the previous version of the map.	Attributes of the deleted map element are included in the `previous` field

Attributes change messages

Attribute change (general)

Purpose

Notify users of changes to a map or attributes.

Event

This message is issued after the following events:

An action is submitted to the ADZ API (intake catalog), such as Insert or Move actions.
An action is submitted via the ADZ UI (webapp): e.g., Insert, Move actions.
Delta map update with changes in map attributes
An ODD attribute reached its expiration time or date.

Scope

One message per element affected by changes.

Content notes

Value	Description
`reason`	A URN that identifies the reason for the change. In the case of a message related to an action, the `resource` will be the URN, or id number, of the action message.
`type`	This will always be `ATTRIBUTE_UPDATE`.
`previous`	A list of attributes affected by the change, and their previous values. This also includes attribtues deleted by the change.
`current`	A list of attributes affected by the change, and their current values. This also includes attribtues added by the change.

Sample Payload

{
  "type": "attributes-change",
  "id": "3543808984853988995",
  "updateTimestamp": "2025-01-18T00:59:17.474",
  "reason": {
    "urn": "urn:olp-demo-organization:11:request:segment-update:-ki1iepb2mz9k"
  },
  "updatedBy": {
    "urn": "urn:olp-demo-organization:11:::"
  },
  "segments": [
    {
      "segmentId": 835908416,
      "tileId": "321689015",
      "current": [
        {
          "id": "map:slope",
          "attributes": [
            {
              "properties": [
                {
                  "propertyDetailIndex": -1,
                  "key": "value",
                  "value": {
                    "type": "Property.Value.PropertyInt",
                    "propertyInt": 415
                  }
                }
              ],
              "metadata": {
                "elementLocation": {
                  "type": "percentage",
                  "from": 29,
                  "to": 40
                }
              }
            }
          ]
        }
      ],
      "type": "ATTRIBUTE_UPDATE",
      "previous": [
        {
          "id": "map:curvature",
          "attributes": [
            {
              "properties": [
                {
                  "propertyDetailIndex": -1,
                  "key": "value",
                  "value": {
                    "type": "Property.Value.PropertyInt",
                    "propertyInt": 1280
                  }
                }
              ],
              "metadata": {
                "elementLocation": {
                  "type": "percentage",
                  "from": 0,
                  "to": 11
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

New segment

Purpose

Notifies ADZ space users that a new segment was added to the space via a map update.

Event

This message is issued after a segment addition event.

Scope

One message per newly-added element.

Content notes

Value	Description
`type`	This will always be `NEW_SEGMENT`
`current`	A list of attributes affected by the change, and their current values. This also includes attributes added by the change

Sample Payload

{
  "type": "attributes-change",
  "id": "9144799545391925502",
  "updateTimestamp": "2025-01-18T00:12:27.414",
  "reason": {
    "urn": "urn:olp-demo-organization:11:request:segment-add:12pyz465fk23l"
  },
  "updatedBy": {
    "urn": "urn:olp-demo-organization:11:::"
  },
  "segments": [
    {
      "segmentId": 905709482,
      "tileId": "315977042",
      "current": [
        {
          "id": "map:complex-intersection",
          "attributes": [
            {
              "properties": [
                {
                  "propertyDetailIndex": -1,
                  "key": "value",
                  "value": {
                    "type": "Property.Value.PropertyString",
                    "propertyString": "Na"
                  }
                }
              ],
              "metadata": {
                "elementLocation": {
                  "type": "percentage",
                  "from": 0,
                  "to": 100
                }
              }
            }
          ]
        }
      ],
      "type": "NEW_SEGMENT",
      "previous": []
    }
  ]
}

Delete segment

Purpose

Notifies ADZ space user that a segment has been deleted from the space due to map update.

Event

This message is issued after a segment deletion event.

Scope

One message per deleted element

Content notes

Value	Description
`type`	This will always be `DELETE_SEGMENT`
`previous`	A list of attributes affected by the change, and their previous values. This also includes attributes deleted by the change.

Sample payload

{
  "type": "attributes-change",
  "id": "5753125935282737006",
  "updateTimestamp": "2025-01-18T00:51:18.274",
  "reason": {
    "urn": "urn:olp-demo-organization:11:request:segment-discard:xpg9vgb820y2"
  },
  "updatedBy": {
    "urn": "urn:olp-demo-organization:11:::"
  },
  "segments": [
    {
      "segmentId": 875609111,
      "tileId": "327440080",
      "current": [],
      "type": "DELETE_SEGMENT",
      "previous": [
        {
          "id": "map:curvature",
          "attributes": [
            {
              "properties": [
                {
                  "propertyDetailIndex": -1,
                  "key": "value",
                  "value": {
                    "type": "Property.Value.PropertyInt",
                    "propertyInt": 49
                  }
                }
              ],
              "metadata": {
                "elementLocation": {
                  "type": "percentage",
                  "from": 0,
                  "to": 50
                }
              }
            },
            {
              "properties": [
                {
                  "propertyDetailIndex": -1,
                  "key": "value",
                  "value": {
                    "type": "Property.Value.PropertyInt",
                    "propertyInt": 48
                  }
                }
              ],
              "metadata": {
                "elementLocation": {
                  "type": "percentage",
                  "from": 50,
                  "to": 100
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

Metadata update

Purpose

Notifies ADZ space user that the geometry or topology of a segment has changed. This message does not contain any attribute changes.

Event

This message is issued after a map update event to metadata.

Scope

One message per newly0added element

Content notes

Value	Description
`type`	This will always be `METADATA_UPDATE`

Sample Payload

  {
    "type": "attributes-change",
    "id": "6333063768339007169",
    "updateTimestamp": "2025-01-18T00:03:07.498",
    "reason": {
      "urn": "urn:olp-demo-organization:11:request:segment-update:-nkjc1vaxadcu"
    },
    "updatedBy": {
      "urn": "urn:olp-demo-organization:11:::"
    },
    "segments": [
      {
        "segmentId": 481054858,
        "tileId": "321454294",
        "current": [],
        "type": "METADATA_UPDATE",
        "previous": []
      }
    ]
  }