An event is an entry in the event log, where each entry is called an event record. The event log can contain many events. Each event can be tagged with one or more categories. Storage and retention rules are specified for each category.

The CMS creates event records in the event log, based on event notifications received from the following sources:

Messages reported on the IAP/MQ event channel.
Requests posted to the iap/log/ev topic, described in the POST method.

In addition to getting logs using the commands below you can also get the logs using WebSockets. Getting large amounts of data log records is much faster using WebSockets.

URI Definition

Method

URI and Fields

GET

/iap/log/ev/{event_id}

Returns event entries from the data and event log, subject to any specified filters. If the event_id is “*” or omitted, all events are returned, subject to the specified filters.

Parameter

event_id - can be specified as an ID of an event log, as an asterisk, or as a regular expression. For more information, see Queries and Parameters. The optional path parameters for event_id are listed in the table below, under Event Log Path Parameters.

Success Response

Collection of available event logs corresponding to specified parameters.

Examples

GET Example /iap/log/ev/{event_id}

https://localhost/iap/log/ev/1
https://localhost/iap/log/ev/*
https://localhost/iap/log/ev/*+severity==warning
https://localhost/iap/log/ev/*+id=+%5B2-9%5D
https://localhost/iap/log/ev/*+utc<=C2019-03-27T18:00


Example of success response:
[
    {
        "id": 1,
        "severity": "warning",
        "topic": "glp/0/2bzzwZs/rq/dev/cm/5",
        "message": "device not found",
        "data": null,
        "tags": [
            "error"
        ],
        "local": "2019-03-27 12:24:53.000 UTC",
        "utc": "2019-03-27 12:24:53.000 UTC",
        "language": "en",
        "urgent": false,
        "localization": null,
        "source": "cmx",
        "active": false,
        "acknowledged": false,
        "acknowledge": null,
        "location": null,
        "notes": null,
        "targetType": "DEVICE",
        "targetName": null,
        "modified": "2019-03-27 12:24:44.144"
    },
    {
        "id": 2,
        "severity": "warning",
        "topic": "glp/0/2bzzwZs/rq/dev/cm/5",
        "message": "device not found",
        "data": null,
        "tags": [
            "error"
        ],
        "local": "2019-03-27 12:25:15.000 UTC",
        "utc": "2019-03-27 12:25:15.000 UTC",
        "language": "en",
        "urgent": false,
        "localization": null,
        "source": "cmx",
        "active": false,
        "acknowledged": false,
        "acknowledge": null,
        "location": null,
        "notes": null,
        "targetType": "DEVICE",
        "targetName": null,
        "modified": "2019-03-27 12:25:05.807"
    }
]

POST

/iap/log/ev

Adds an entry to the data and event log.

Request Body

New log event in json format.

Success Response

Empty.

Example

POST Example /iap/log/ev

https://localhost/iap/log/ev


REQUEST BODY:
{
"id": 345,
"severity": "warning",
"topic": "glp/0/2bzzwZs/fb/dev/cm/5",
"message": "device not found",
"data": null,
"tags":[
"error"
],
"local": "2019-03-27 12:24:53.000 UTC",
"utc": "2019-03-27 12:24:53.000 UTC",
"language": "en",
"urgent": false,
"localization": null,
"source": "cmx",
"active": false,
"acknowledged": false,
"acknowledge": null,
"location": null,
"notes": null,
"targetType": "DEVICE",
"targetName": null,
"modified": "2019-03-27 12:24:44.144"
}


RESPONSE:  
empty

PUT

/iap/log/ev/{event_id}

Updates entries in the data and event log, subject to any specified filters. If event_id is “*” or omitted, all events are updated, subject to the specified filters.

Parameter

event_id - can be specified as an ID of an event log, as an asterisk, or as a regular expression. For more information, see Queries and Parameters. The optional path parameters for event_id are listed in the table below, under Event Log Path Parameters.

Success Response

Empty.

Examples

PUT Example /iap/log/ev/{event_id}

EXAMPLE 1 
https://localhost/iap/log/ev/1

REQUEST BODY:
{
    "id": 1,
    "severity": "alarm",
    "topic": "glp/0/2bzzwZs/fb/dev/cm/5",
    "message": "device not found",
    "data": null,
    "tags":[
        "error"
    ],
    "local": "2019-03-27 12:24:53.000 UTC",
    "utc": "2019-03-27 12:24:53.000 UTC",
    "language": "en",
    "urgent": false,
    "localization": null,
    "source": "cmx",
    "active": false,
    "acknowledged": false,
    "acknowledge": null,
    "location": null,
    "notes": null,
    "targetType": "DEVICE",
    "targetName": null,
    "modified": "2019-03-27 12:24:44.144"
}

RESPONSE:
Empty.


EXAMPLE 2 
https://localhost/iap/log/ev/*

REQUEST BODY:
{
    "severity": "warning"
}

RESPONSE:
Empty.

DELETE

/iap/log/ev/{event_id}

Deletes the core events according to the event ID.

Parameter

event_id - can be specified as an ID of an event log, as an asterisk, or as a regular expression. For more information, see Queries and Parameters. The optional path parameters for event_id are listed in the table below, under Event Log Path Parameters.

Success Response

Empty.

Example

https://localhost/iap/log/ev/1

Response

Empty.

Query Parameters

Optional query parameters can be used with your REST request. Specifying queries is described under Queries and Parameters, Path Parameters, and Query Parameters.

Event Log Path Parameters

The following list describes the optional path parameters for the event-id path element used in Event Log endpoints.

Path Parameter	Description
acknowledge	Topic for an alarm to publish “ack” to acknowledge this alarm.
acknowledged	Indicator for an alarm to indicate whether explicit acknowledgement is required; set to “true” if acknowledgement is required. Default value: “false”
active	Indicator for an alarm to indicate whether the alarm is active (set to “true”) or passive (set to “false”). Default value: “false”
data	Data value to which the event applies. Encoded as a single value or a JSON object. Typically used with datapoint update events (monitoring) or alarm events. A value for data is required if a value for the message field is not supplied. For Example: “{ h: 0.48, l: 0.6, s: 0.68, b: 0.8 }”
ele	Elevation.
geozone	ID of the geozone, where the device th at produced the event is located.
Id	A monotonic unique event record ID.
language	ISO 639 code to indicate the language used with the message field. Default value: “en”
lat	Lattitude of the device.
local	The local date and time the event was captured. For Example: "2020-08-23T11:34:22.123+01:00"
localization	Localization object that can be used by visualizing and reporting applications to localize the message to alternate languages. For Example: “{ id: "8000010200000000-4/3-1", map: { position: 4, value: 123.456 } }”.
localZoneId	ID of the time zone, such as UTC, BST, etc.
lon	Longitude of the device.
message	Message describing the event. A value for message is required if a value for the data field is not supplied.
modified	The UTC date and time the event record was last modified. The value is updated automatically by the CMS whenever an event record is created or updated, and is initially set to the date and time the event record was created in the event log. For Example: "2017-08-25 11:44:22.123 UTC"
notes	Notes with additional details about the event.
severity	One of the following severity indicators: alarm critical (for a critical fault) maintenance major (for a major fault) minor (for a minor fault) notification warning
source	Name of the source component. For Example: “Scheduler”
tags	Tags added to events.
targetEntity	ID of the entity associated with the event.
targetType	Type of the entity associated with the event. Supported types are: Device Group Schedule Block
topic	The resource of the item to which the event relates. For Example: “glp/0/boardwalk/fb/dev/lt/1”
urgent	Urgency indicator. The event is urgent if “true”. Default value: “false”
utc	UTC date and time the event was captured. For Example: 2017-08-23T11:34:22.123

Examples

Set log level for the datapoint /iap/devs/8/if/LightSensor/0/nvoLuxLevel/value:

PUT /iap/devs/8/if/LightSensor/0/nvoLuxLevel/value/logs {"interval":10}

Get all logged data (assuming that only /iap/devs/8/if/LightSensor/0/nvoLuxLevel/value is being logged):

event_id can be an asterisk or a regular expression.

GET /iap/log/ev/*

GET /iap/log/ev/25

GET /iap/log/ev/*+severity==notification

GET /iap/log/ev/*+utc<=C2018-08-31T18:00

Response:

{
"id":25,
"severity":"notification",
"topic":"glp/0/T6tWycd/fb/dev/lon/8/if/LightSensor/0",
"message":"nvoLuxLevel/value",
"data":844,
"tags":["data"],
"local":null,
"utc":"2018-08-31 13:22:42.266 UTC",
"language":"en",
"urgent":false,
"localization":null,
"source":"lon",
"active":false,
"acknowledged":false,
"acknowledge":null,
"location":null,
"notes":null,
"modified":"2018-08-31 14:22:42.344"
}

Return Logged Data With a Query:

To find all events between 2018-09-01T20:40:01.000 UTC & 2018-09-01T20:50:01.000 UTC for the datapoint:

/iap/devs/8/if/LightSensor/0/nvoLuxLevel/value

which has had logging set up with:

PUT /iap/devs/8/if/LightSensor/0/nvoLuxLevel/value/logs {"interval":10}

First you need to know the SID of the SmartServer IoT which can be found using /iap/devs, then you need to convert to a topic and message using IAP/MQ syntax.

Using an example a SID of "T6tWycd" yields:

Topic == glp/0/T6tWycd/fb/dev/lon/8/if/LightSensor/0

Message == nvoLuxLevel/value

Then all "/" in the topic and message need to be replaced with "%2F%

Thus the query is as follows:

/iap/log/ev/*+utc>2018-09-01T20:40:01.000&utc<=2018-09-01T20:50:01.000&topic== glp%2F0%2FT6tWycd%2Ffb%2Fdev%2Flon%2F8%2Fif%2FLightSensor%2F0&message==nvoLuxLevel%2Fvalue

First Result From Returned Data:

{
"id":11168,
"severity":"notification",
"topic":"glp/0/T6tWycd/fb/dev/lon/8/if/LightSensor/0",
"message":"nvoLuxLevel/value",
"data":38,
"tags":["data"],
"local":null,
"utc":"2018-09-01 20:40:05.665 UTC",
"language":"en",
"urgent":false,
"localization":null,
"source":"lon",
"active":false,
"acknowledged":false,
"acknowledge":null,
"location":null,
"notes":null,
"modified":"2018-09-01 21:40:05.732"
}

EnOcean Edge Portal

Log Events

URI Definition

Parameter

Success Response

Examples

Request Body

Success Response

Example

Parameter

Success Response

Examples

Parameter

Success Response

Example

Query Parameters

Event Log Path Parameters

Examples

Response:

Return Logged Data With a Query:

First Result From Returned Data: