Event structure

All events follow the base model outlined below:

• A universally unique identifier (string:UUIDv6)
• A timestamp (string:RFC3339)
• A code indicating the type (string)
• A code indicating the topic (string)
• A verbal description of the event (string)
• A context data object whose fields depend on the topic and the code (object)

In JSON, the base model looks as follows:

{
    "eventTopic": "topic-code",
    "eventCode": "event-code",
    "eventDescription": "A verbal description of the event",
    "eventOccurred": "2023-09-07T10:18:41+02:00",
    "eventId": "1ee4d572-7b62-6136-86c8-35b55032bfe2",
    "eventData": {...}
}

WARNING

The eventDescription attribute should never be used for string matching as the description sent is subject for change. For integration purposes, use the eventCode and build your own translation table, and use the eventDescription only as a fallback.

Topic specifics

Different topics carry different data attributes. For example, the device topic carries information about the device emitting the event, and it's surrounding layers, as explained in the introduction. The outer the layer, the less information.

The topic specific information is provided as attributes on the data object in base model.

Alarm group topic

The alarm group topic provides the following information as attributes on the data object of the base model:

• The group ID (string:UUIDv6)
• The group name (string)
• The group description (string)
• The group state (string)
• The group active status (boolean)
• The site ID (string:UUIDv6)
• The site name (string)
• The site description (string)

In JSON, it looks like follows:

{
    "eventTopic": "alarmgroup",
    "eventCode": "event-code",
    "eventDescription": "A verbal description of the event",
    "eventOccurred": "2023-09-07T10:18:41+02:00",
    "eventId": "1ee4d572-7b62-6136-86c8-35b55032bfe2",
    "eventData": {
        "groupId": "078b0128-ee14-11ef-87f5-d7635ca21f87",
        "groupName": "The alarm group name",
        "groupDescription": "The alarm group description",
        "groupActive": true,
        "groupState": "schedule|armed|disarmed",
        "siteId": "078b0128-ee14-11ef-87f5-d7635ca21f87",
        "siteName": "The site name",
        "siteDescription": "The site description",
    }
}

WARNING

Events are evaluated post-change. This means that if the event code is armed, groupActive will evaluate to true.

NOTICE

Some alarm group events may carry additional data attributes. Refer to the individual events in the catalog.

Device topic

The device topic provides the following information as attributes on the data object of the base model:

• The device ID (string:UUIDv6)
• The device name (string)
• The device description (string)
• The group ID (string:UUIDv6)
• The group name (string)
• The group description (string)
• The group state (string)
• The group active status (boolean)
• The site ID (string:UUIDv6)
• The site name (string)
• The site description (string)

In JSON, it looks like follows:

{
    "eventTopic": "device",
    "eventCode": "event-code",
    "eventDescription": "A verbal description of the event",
    "eventOccurred": "2023-09-07T10:18:41+02:00",
    "eventId": "1ee4d572-7b62-6136-86c8-35b55032bfe2",
    "eventData": {
        "deviceId": "6630e036-ee13-11ef-bc15-b33a54d715fa",
        "deviceName": "CAM-1",
        "deviceDescription": "Above main entrance",
        "groupId": "078b0128-ee14-11ef-87f5-d7635ca21f87",  # may be unset
        "groupName": "The alarm group name",                # may be unset
        "groupDescription": "The alarm group description",  # may be unset
        "groupActive": true,                                # may be unset
        "groupState": "schedule|armed|disarmed",            # may be unset
        "siteId": "078b0128-ee14-11ef-87f5-d7635ca21f87",
        "siteName": "The site name",
        "siteDescription": "The site description",
    }
}

WARNING

Including a device in an alarm group is optional. If device is not part off an alarm group, the group-attributes will be unset.

NOTICE

Some device events may carry additional data attributes. Refer to the individual events in the catalog.

Barrier topic

The barrier topic provides the following information as attributes on the data object of the base model:

• The barrier ID (string:UUIDv6)
• The barrier name (string)
• The barrier description (string)
• The device ID (string:UUIDv6)
• The device name (string)
• The device description (string)
• The group ID (string:UUIDv6)
• The group name (string)
• The group description (string)
• The group state (string)
• The group active status (boolean)
• The site ID (string:UUIDv6)
• The site name (string)
• The site description (string)

In JSON, it looks like follows:

{
    "eventTopic": "barrier",
    "eventCode": "event-code",
    "eventDescription": "A verbal description of the event",
    "eventOccurred": "2023-09-07T10:18:41+02:00",
    "eventId": "1ee4d572-7b62-6136-86c8-35b55032bfe2",
    "eventData": {
        "barrierId": "6630e036-ee13-11ef-bc15-b33a54d715fa",
        "barrierName": "The barrier name",
        "barrierDescription": "The barrier description",
        "deviceId": "6630e036-ee13-11ef-bc15-b33a54d715fa",
        "deviceName": "The controller name",
        "deviceDescription": "The controller description",
        "groupId": "078b0128-ee14-11ef-87f5-d7635ca21f87",  # may be unset
        "groupName": "The alarm group name",                # may be unset
        "groupDescription": "The alarm group description",  # may be unset
        "groupActive": true,                                # may be unset
        "groupState": "schedule|armed|disarmed",            # may be unset
        "siteId": "078b0128-ee14-11ef-87f5-d7635ca21f87",
        "siteName": "The site name",
        "siteDescription": "The site description",
    }
}

WARNING

Including a barrier in an alarm group is optional. If a barrier is not part off an alarm group, the group-attributes will be unset.

NOTICE

Some barrier events may carry additional data attributes. Refer to the individual events in the catalog.

Peripheral topic

The peripheral topic provides the following information as attributes on the data object of the base model:

• The peripheral ID (string:UUIDv6)
• The peripheral name (string)
• The peripheral description (string)
• The device ID (string:UUIDv6)
• The device name (string)
• The device description (string)
• The group ID (string:UUIDv6)
• The group name (string)
• The group description (string)
• The group state (string)
• The group active status (boolean)
• The site ID (string:UUIDv6)
• The site name (string)
• The site description (string)

In JSON, it looks like follows:

{
    "eventTopic": "peripheral",
    "eventCode": "event-code",
    "eventDescription": "A verbal description of the event",
    "eventOccurred": "2023-09-07T10:18:41+02:00",
    "eventId": "1ee4d572-7b62-6136-86c8-35b55032bfe2",
    "eventData": {
        "peripheralId": "6630e036-ee13-11ef-bc15-b33a54d715fa",
        "peripheralName": "The peripheral name",
        "peripheralDescription": "The peripheral description",
        "deviceId": "6630e036-ee13-11ef-bc15-b33a54d715fa",
        "deviceName": "The controller name",
        "deviceDescription": "The controller description",
        "groupId": "078b0128-ee14-11ef-87f5-d7635ca21f87",  # may be unset
        "groupName": "The alarm group name",                # may be unset
        "groupDescription": "The alarm group description",  # may be unset
        "groupActive": true,                                # may be unset
        "groupState": "schedule|armed|disarmed",            # may be unset
        "siteId": "078b0128-ee14-11ef-87f5-d7635ca21f87",
        "siteName": "The site name",
        "siteDescription": "The site description",
    }
}

WARNING

Including a peripheral in an alarm group is optional. If a peripheral is not part off an alarm group, the group-attributes will be unset.

NOTICE

Some peripheral events may carry additional data attributes. Refer to the individual events in the catalog.

Gotchas

As a device and its child things may exist in different alarm groups, the passed alarm group attributes are referring to the alarm group of the resource emitting the event, whose type is represented by the topic. For example:

• If an event on the device topic is referring an alarm group, it's the alarm group of the device resource.
• If an event on the barrier topic is referring an alarm group, it's the alarm group of the barrier resource.
• If an event on the peripheral topic is referring an alarm group, it's the alarm group of the peripheral resource.