Skip to content

Event

An Event is a virtual representation of an operation, an event, or an action that occurs in the platform.

This Event can be used for:

  • Audit Log: register all major events that occur in the platform. Example: device creation, device deletion, platform technical error ...
  • Standard business purpose: business events managed directly by the platform. Example: battery level warning, ...
  • Custom business purpose: all events generated by a custom app that can be used for dedicated scenarios.

Event Details

  • Tenant ID: ID of the Tenant in which the Event occurred
  • Target Entity Type: Records the Entity Type for which the event occurred. Can be a Device, Folder, User, Tenant ...
  • Target Entity ID: ID of the Entity for which the event occurred
  • Criticality: a predefined range of levels to classify the importance of the Event
    • 0: Not applicable
    • 1: CRITICAL
    • 2: HIGH
    • 3: MEDIUM
    • 4: LOW
    • 5: TRIVIAL
  • Event Code: Text based value identifying the event type. Example: device_created
  • Internal:
    • internal Events can only be generated by the platform, they use system Event codes
    • custom Events (non-internal) can be created in the platform with any code
  • Message: a free-form, human-readable description of the Event (a text string). Example: Device WISE-4010 created
  • Payload: structured detail of the operation, stored as a JSON object and searchable. It may be empty. This allows a precise filtering of the events based not only on the action performed but also on the parameters of the action. Examples:
    • for an update, the fields that changed mapped to their new values (e.g. { "name": "New name", "description": "New description" })
    • for a command, the command name, its parameters and its result
  • Principal: the User or Service Account that caused the Event. It is absent for internal events that have no attributed actor.

Searching Events

There are two ways to read events. The search route is the recommended one; the legacy list route is kept for backward compatibility and is deprecated.

Route

  • POST .../events/search

Permission

  • read event.{Entity Type} (on Tenant level, or on Folder level if applicable)

Feature

  • Principals can search Events by sending complex criteria in the request body.
  • Supported filter parameters:
    • Date Range (mandatory); if only the start date is specified, the range runs from that date to NOW.
    • Criticality
    • Event Code
    • Target Entity Type (mandatory)
    • Target Entity ID
    • Payload filters: restrict to events whose Payload matches; every entry must match (logical AND). An entry is either a key name (string) — matching events whose payload contains that key, where a dotted name such as specs.vendorName matches a nested key — or a key/value pair (object) — matching events whose payload contains those exact pairs with exact value typing, e.g. { "network.ipAddress": "0.0.0.0" }.
  • Each returned Event exposes both its Message and its structured Payload.
  • The response is paginated and ordered by date DESC.

List Events (deprecated)

Route

  • GET .../events

Permission

  • read event.{Entity Type}

Feature

  • Deprecated — use Search Events instead. Kept unchanged for existing integrations.
  • Same filters as before, passed as query parameters: Date Range (mandatory), Criticality, Event Code, Target Entity ID, Target Entity Type. It does not support payload filters.
  • In the response, each Event's payload field carries the Message string (the legacy shape); the structured payload is not exposed by this route.
  • The response can be paginated and ordered by date ASC or DESC.

Generate an Event

Permission

  • create event.tenant

Feature

  • Principals can generate Events to keep track of actions or events that occurred in the platform.
  • A generated Event is described by its Event Code, Message, Criticality, Target Entity Type, Target Entity ID, and an optional structured Payload.