Event API

The Event API is used to find and manage Rule Engine and Lifecycle Events.

An event looks like this:

{
  id: 'ec324d9c-8ab2-47b0-af07-fd4eb26fadd4',
  timestamp: 1506228307763,

  // The message for Lifecycle Events is set by Managed IoT Cloud but for Rule Engine Events
  // the message can contain anything. If you format the message as a JSON object this can
  // even be used to capture the state of the thing at the time of the event or anything else
  // that you may need included in your event.
  message: 'Rule "TestRule" triggered for 00000001, temp=15',

  // INTERNAL is used when the event is only going to be stored for searching. If the event
  // should be shown in the event popup in AppBoard, use ALARM, WARNING or NOTIFICATION instead.
  classification: "INTERNAL"

  // For Rule Engine Events the rule may specify that the events require acknowledgment.
  acknowledgementRequired: true,
  acknowledgedAt: 1506228307764,
  acknowledgedBy: "superuser",

  // Always RULE for Rule Engine Events. For Lifecycle Events the name is used (i.e. THING.CREATE).
  type: "RULE",

  // For rule engine events the rule may specify a category that will show up here. Use this to make your rule triggers searchable.
  category: 'YOUR.CATEGORY',

  // The source is used to store as much structured information about the context in which
  // the event was created as possible. The actual content will vary for different events.
  source: {
    thingName: "000001",
    thingType: "1",
    domain: "root"
    resource: "temp"
    rule: "TestRule"
  }
}

ACKNOWLEDGE

Required role: ReadWrite
Required privilege: Events.UPDATE on the domain of the source that generated the event

If the event requires acknowledgement, this action acknowledges the event.

API Endpoint: [POST]: /events/{id}/acknowledge

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Query Parameters

  • id: The id of the event to acknowledge, set in query path. required

Response

  • id: The id of the acknowledged event.
  • timestamp: The time when the acknowledged event was created.
  • message: The message of the acknowledged event.
  • classification: The classification of the acknowledged event.
  • acknowledgementRequired: true if the acknowledged event required acknowledgement.
  • acknowledgedAt: The time when the event was acknowledged.
  • acknowledgedBy: The user name of the user who acknowledged the event.
  • type: The type of the acknowledged event.
  • source: The source properties of the acknowledged event.
    • ...

Errors

Key Params Property Description
NOT_AUTHORIZED_DOMAIN Returned if the user tries to acknowledge an event that belongs to a domain that the user is not authorized to see.

FIND

Required role: Read
Required privilege: Events.READ

Executes an Elasticsearch 5.6 query to find events.
Note that only the events which are located in the domains that user has privilege to read from, can be listed.

API Endpoint: [POST]: /events/find

Request

Headers

  • Authorization: The Authorization token returned from /auth/login
  • x-api-key: The API Key to identify the request

Body

  • query: The query to run on Elasticsearch specified using Elasticsearch Query DSL. required

  • sort: The event attribute to sort by. optional

    Most event attributes can be used for sorting. However, the message attribute is a special case where you should use the message.lowercase field instead:

      query: {"match_all": {}},
  sort: [ {"message.lowercase": "asc"}]
Filter context

Consider using a filter context if possible. In filter context, a query clause answers the question “Does this document match this query clause?” The answer is a simple Yes or No — no scores are calculated. Filter context is mostly used for filtering structured data, e.g.

  • Does this timestamp fall into the range 2015 to 2016?

  • Is the status field set to “published”?

    Any query and any aggregations are permitted to use but since Managed IoT Cloud prevents the user from seing events on domains that the user is not authorized to see the query must satisfy the following requirements:

    • The query cannot contain global aggregations.

Example payload

{
  "query": {
    "size": 1000,
    "query": {
      "bool": {
        "filter": [
          {
            "range": {
              "timestamp": {
                "gte": 1460661813164,
                "lte": 1460705013163
              }
            }
          },
          {
            "term": {
              "type": "THING.CREATE"
            }
          }
        ]
      }
    }
  }
}

Response

The output from the Elasticsearch query.

Errors

Key Params Property Description
INVALID_ARGUMENTS query Returned if the query includes a global aggregations.
PROPERTY_REQUIRED query Returned if no query was provided.

REALTIME

Required role: Read Required privilege: Events.READ and ThingPubSub.READ on the specified domain

It is possible to receive events in realtime using WebSockets over MQTT on the topic name event<domainPath> using Cognito credentials.

The topic names available for subscriptions follow the same structure as Thing Update API using the domain path, which can be found on the user returned from the LOGIN action in Auth API.

For example, if the user belongs to the domain sub11 that is a sub domain of sub1 that is a sub domain of root, the user can subscribe to events on the topic event/sub1/sub11/#.

Note: strict MQTT clients may need to subscribe to two topics when using wildcard, see Thing Update API .