Skip to content

Event Management

Idea

The Event Management Service manages different types of events created by users in MindSphere. It enables users to create, update and delete events associated to entities.

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.

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.

Events

There are two different 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). 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.

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.

Limitations

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

  • request parameters
  • query parameters
  • error responses

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 MindSphere Development License Agreement.