Skip to content

Event Management

Idea

The Event Management Service is used to capture events generated by devices in MindSphere. An event is an unexpected circumstance such as leakage in motor pump or a freezer exceeding pre-defined temperature limits which need special attention. The service enables users to create, update and delete events associated to entities. It provides flexibility to model events based on user defined event-types with custom fields to capture all the required details based on user's custom use case and acknowledge the event once corrective action is performed on device.

Access

The Event Management is exposed to developers as a REST API. For accessing this service you need to have the respective roles listed in Event Management roles and scopes.

For accessing the Secure Data Sharing (SDS) protected APIs you need to have appropriate Policy Definitions in place. Please refer here for the list of supported APIs and Required Actions.

Basics

Users can use predefined event types or create their own templates for generating new events. The user is able to filter, update or delete the events or event types.

Info

For advice on how to use this service, refer to the Best Practices.

Events

There are two kinds of events: standard events and custom events. Both inherit the following fields from a common ancestor:

  • id
  • correlationId
  • timestamp (required)
  • entityId (required)

The following additional fields are available:

  • Standard Events
    A standard event is created from a predefined event type, for which the following base properties are available:

    • description
    • severity
    • code
    • source
    • acknowledged

  • Custom Events
    A custom event is created from a user-defined event type. The available properties are defined in the event type.

Event types

Custom events are created from user-defined event types. These define a set of custom fields which hold the properties of the custom event.

Each custom field of an event type has a data type and can be defined to be required and/or filterable.

An event type has a global or local scope and a time to live (TTL in days). Both are applied to all instantiated events.

Event types can be derived from other (parent) event types. An inheritance hierarchy of up to 4 levels is allowed. Every event type inherits all fields from its ancestor event types.

Filtering and sorting

Events can be filtered and sorted by all assigned base properties except description. Additionally, if the event type is set as filter parameter, events can be filtered and sorted by all custom fields specified as filterable. Events can also be filtered and sorted by all inherited custom fields.

The filter syntax can be customized using operators like and, or, not equals, contains or startsWith. Be aware that only a single, not negated event type can be used as filter parameter.

Updating

Events can be updated. There are two ways to update an event: A PUT request overwrites an event and a POST request creates a history. This means the original event remains in the database and a new event is created with the same entityId and correlationId but a different id.

Listing events returns only the latest of an event's history. The whole history of the event is listed with history query parameter set to true.

Deleting

Events can be deleted based on a custom filter asynchronously via POST request. If the latest event instance in a history of an event is deleted then the history of the event will be deleted.

Features

The Event Management Service exposes its API for realizing the following tasks:

  • Create an event.
  • Get a single event.
  • List filtered and sorted events.
  • Update an existing event (PUT).
  • Create a historic event while updating an event (POST).
  • Create, update, delete an event type.
  • Get a single event type.
  • List filtered and sorted event types.
  • Delete events asynchronously based on custom filter.
  • Create events asynchronously.
  • Sharing of the events between collaborating tenants.

Limitations

  • All limitations and restrictions are documented in the API specification. For details refer to the definitions for:

    • request parameters
    • query parameters
    • error responses

  • If there are too many API requests, the service throttles them temporarily with a 429 status code. A Retry-After header might be included with this response, indicating how long in seconds to wait before making a new request.

  • Custom Event type creation will have following restrictions:

    • Maximum number of custom 'fields' should not be more than 100.
    • Total STRING fields in custom eventtype should not be more than 40.
    • Total LINK fields in custom eventtype should not be more than 1.
    • Total ENUM fields in custom eventtype should not be more than 3.
    • ENUM constants per ENUM type should not be more than 50
    • Field name should always start with lowercase letter. For example, if we want field name as temperature then "Temperature" is invalid name, correct name is "temperature".

  • By default, legacy value plan tenant can create maximum of 2.5 million events. Beyond that more events can be purchased via Upgrade.

Example Scenario

The manager of a brewery wants to track machine faults of the brewery's production line.

The manager uses the Event Management Service to create an event with an error code.

Any questions left?

Ask the community

Except where otherwise noted, content on this site is licensed under the Development License Agreement.

Last update: March 17, 2023