glp/0/{SID}/ev/{event}

IAP event objects provide live event reporting of diagnostics, alarms, and other types of events as they occur.

The diagnostic event objects (debug, info, warning, and error) provide alphanumeric diagnostics in ascending levels of severity. These events are related to the processing that occurs within the segment, such as IAP parse errors, requests to manage a non-existent device, etc. Note that debug and info events do not normally reach IAP/MQ. The reporting event categories can be configured with the segment configuration and those below "warning" should normally be disabled.
Another event category, alarm, delivers event messages raised by user-defined alarm conditions.
A special event category, join, provides event messages when a device releases a join notification on the edge protocol. Not all protocol drivers can publish a join event.
There are three app-related events that are issued by protocol processors:
- A created event is reported when a new device is created. This event is reported for all devices.
- A deleted event is reported when a device is deleted. This event is reported for all devices.
- An updated event is reported when a datapoint within a device is updated. This event can be limited to applicable devices.

IAP publishes all events using QoS 1, retain False. That is, previously connected clients receive these events when they reconnect, but new clients cannot receive events from the past through this method. To control data consumption on the WAN or LAN connection between the edge server and the CMS, forwarding events is enabled or disabled with the edge server provisioning message (see Segment Provisioning).

Events are reported on these topics:

glp/0/{SID}/ev/debug

glp/0/{SID}/ev/info

glp/0/{SID}/ev/warning

glp/0/{SID}/ev/error

glp/0/{SID}/ev/alarm

glp/0/{SID}/ev/join

glp/0/{SID}/ev/data

glp/0/{SID}/ev/discovery/device

glp/0/{SID}/ev/created/dev/{Protocol}/type/{Application_Type}

glp/0/{SID}/ev/deleted/dev/{Protocol}/type/{Application_Type}

glp/0/{SID}/ev/updated/dev/{Protocol}/type/{Application_Type}

A typical configuration forwards error and alarm events as they occur, and logs the other diagnostics on request. The join event is handled as described in Join Event below.

Event categories are not limited to those listed above. For example, a future service could introduce a new traffic category for reporting and logging of traffic counting related events. Custom event categories are generally used between specialized pairs of apps executing in the edge server and widgets or similar forms or plug-in components used by front-facing tools.

Diagnostics in relation to the MQTT client-to-server connection and communication are not generally reported as live events, even if the corresponding event category is enabled for live reporting. This prevents loops, for example for MQTT-related debug and info messages and prevents attempts to report an MQTT malfunction over a malfunctioning connection.

Data Events

Data Events usage for SmartServer 2.8 and higher.

When a datapoint is updated, an event (ev/data) is produced to provide feedback about the update, in the following manner:

When a new value is written to a datapoint, the new value is published on ev/data, regardless of the monitoring rules.
The first time a value is written to a datapoint after a provision, the value is published on ev/data, even when the datapoint's value does not change.

In either case, the update is NOT published on the feedback channel, regardless of the inFeedback flag. However, feedback on the feedback channel is still provided in the following cases:

When the datapoint's priority array is updated for a priority of 1..16.
When the updated datapoint is a property datapoint, feedback can be provided (driver dependent).

Join Events

Devices generally release their join notification when a suitable hardware input is asserted, but some devices also support other inputs, such as a button on a touch-screen display. Some device types can also release this notification with the device join() action described in the Device Do Actions properties table.

Publication and receipt of a join event has no intrinsic consequence. It is merely a notification of the existence or presence of a device, given its edge protocol, its application type, and unique ID.

Join events are typically used with device installation procedures. These events allow an operator to explicitly nominate a specific physical device, often by virtue of pressing a physical button on the device.

Join events are also often used to confirm basic communication, but are generally uni-directional. See the device test() action, detailed in the Device Do Actions properties table, for a better tool to verify good communication.

Publishing the join event is optional. Some edge protocols can never trigger this event while the ability to trigger this event may vary between device types in other protocols. A third group of edge protocol drivers may support triggering the join event for all devices, but with varying methods of triggering this event across different device types.

Generic tools that support device installation with unique ID values obtained from join events must support a way to cancel the unique ID acquisition. Tools should validate the application type received with the event against the application type expected for the given device, if known.

The join event is reported using a standard Event object, but join uses only the following subset of fields, as described in the Properties table below:

cat
data
id
message
topic
ts

Tracing

Tracing is provided with event category trace. Tracing records every change to the IAP feedback and requests channels within an edge server. Because of the potentially significant data volume and performance impact due to processing this data, tracing is disabled by default. Tracing can be enabled (and disabled) with the tracing property in the edge server's configuration object (see Segment Configuration).

Event Object Properties

The Event object has the following properties:

Field Name	Type	Description
active	Boolean	(Optional) Used with arbitrary alarms and is not always present. active indicates whether the alarm is active (True) or passive (False).
acknowledge	String	(Optional) Used with arbitrary alarms and is not always present. acknowledge provides a topic to publish “ack” to acknowledge this alarm For Example: glp/0/boardwalk/rq/alarm/22
acknowledged	Boolean	(Optional) Used with arbitrary alarms and is not always present. acknowledged indicates whether the alarm awaits explicit acknowledgment. Indicates True or False.
cat	String	Either “debug”, “info”, “warning”, “error”, “alarm”, "join", "data", "created", "deleted", or "updated". (This property is redundant for live reporting.)
data	JSON object or value	(Optional) Contains data to which an event applies. Usually used with data (monitoring) or alarm events. For data events: The data property reports the datapoint value, subject to the monitor preferences object's focus. For join events: Events can also contain an optional data item, typically used to communicate the value of a datapoint captured by a data monitoring event, or a value that triggered an alert. The data property reports an object with the following fields: data.unid reports the originator device’s unique ID using the same value and presentation as with the Device Status object. data.type reports the originator device’s application type ID using the same value and presentation as with the Device Status object. data.protocol reports the originator device’s edge protocol or driver ID. For example, a device managed by the LonWorks subsystem will report protocol: “lon”. The edge protocol identifier is the same as used with topics when addressing the device.
health	String	(Optional) health is used with data events. The supported values are normal, suspect, and down. down indicates that the reported datapoint value is a copy of the most recently retrieved value because the datapoint is currently inaccessible. The default is normal. For related information, see Reporting a Captured Value, under the monitor Datapoint Object property.
id	Number	A monotonic unique event record ID, used for pagination. Generated by the unit responsible for live reporting and retrieval of history events. For join events: The id property always reports 0 (zero) where a monotonic event record ID is unavailable.
language	String	ISO 639 code to indicate the language used with the message property. The language used with message is configured with the segment’s configuration object (see language property in Segment Configuration). The actual language used in the message is indicated with the language property, using an ISO 639 language code, with added country codes where applicable. The reported language may differ from the language preference, for example if a translation is not available for this particular diagnostic. The optional localization object can be used to localize the diagnostic later. This allows a CMS to display the same diagnostic to users with different language preferences in their local language.
local	String	(Optional) local provides a timestamp. See the description for utc below. Events can report the time with the ts, utc and local properties. All three are optional but at least one of the three must be included. When more than one timestamp is included, they must not differ by more than 250 ms difference after normalizing to the same timezone. The local event timestamp always uses the format detailed in Timestamps in IAP. For Example: "2016-08-23 10:34:22.123 UTC"
localization	Object	(Optional) The localization object can be used to localize the diagnostic later. This allows a CMS to display the same diagnostic to users with different language preferences in their local language.
message	String or JSON object	The freeform messages provided with each of the events (debug, info, warning, error, alarm, and join). See the description for language above. For data events: The message property provides the path within the interface object that contains the datapoint that is the subject of this report. Also see *topic* description below. For join events: The message property carries the same information as data, preformatted in a human-readable string, such as “Join message received from <PROTOCOL> device with sunique ID <UNID>, application type <TYPE>”.
severity	String	(Optional) A string with a user-defined severity, typically used with Alarms.
source	String	(Optional) Used to identify the source component. For Example: “Scheduler”
topic	String	The IAP/MQ topic to which the event applies, if known. For data events: topic reports the feedback topic of the interface block that contains the datapoint that is the subject of this data event. For join events: The topic is null if the originator device is not yet known by the reporting protocol driver. If the originator device is known, topic reports the device’s feedback topic such as `glp/0/SID/fb/dev/lon/nc.0`. For Example: "glp/0/boardwalk/fb/dev/lon/1"
ts	String	(Optional) Date and time is reported as is when the event occurs. Subsequent changes to clock, timezone, or daylight savings do not affect the timestamp. However tools can rely on the monotonic id for chronological ordering, if id is non-zero. Events can report the time with the ts, utc and local properties. All three are optional but at least one of the three must be included. When more than one timestamp is included, they must not differ by more than 250 ms difference after normalizing to the same timezone. The ts timestamp is presented with a simplified extended ISO 8601 timestamp in the YYYY-MM-DDTHH:mm:ss.sssZ format, always in UTC.
urgent	Boolean	The distinction between urgent and non-urgent events is subject to interpretation by the edge server's event reporting service. In a system where the edge server is always connected, the urgency is reported with the event, if live reporting for the event category is enabled. But has little effect on the edge server. The CMS might treat this urgent event different from non-urgent ones, however. In a system which uses non-permanent network connectivity, such as one which periodically “dials in” and connects to the CMS broker, an urgent event can trigger an immediate connection attempt even if the next scheduled connection is not yet due.
utc	String	(Optional) A timestamp. Date and time is reported as is when the event occurs. Subsequent changes to clock, timezone or daylight savings do not affect the timestamp, but tools can rely on the monotonic id for chronological ordering, if necessary. Events can report the time with the ts, utc and local properties. All three are optional but at least one of the three must be included. When more than one timestamp is included, they must not differ by more than 250 ms difference after normalizing to the same timezone. The utc event timestamp always uses the format detailed in Timestamps in IAP. For Example: "2016-08-23 10:34:22.123 UTC"