Event Management¶

Idea¶

There are many devices that are connected to Insights Hub. Sometimes, devices show an unexpected behavior (for example, leakage in a motor pump or freezer exceeding the temperature limit) which demands special attention. These situations are known as events which can be digitally represented in Insights Hub.

To capture these generated events, we have the Event Management Service that allows users to create, update, and delete events associated with the configured Assets. The service offers flexibility in modeling events, allowing users to define event types and include custom fields to capture all the necessary details according to their specific use case. Additionally, users can acknowledge an event once the necessary corrective action has been taken on the device.

EventType is metadata used to create events in system. Events are associated with assets/entity.

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.

Consider the given scenario to understand Event Management Service.
A freezer is required to maintain a temperature of approximately 36 degrees to preserve the freshness of stored food. If the temperature exceeds this limit, there is a risk of food spoilage. To address this concern and protect our food, an event needs to be generated when the freezer temperature rises above 36 degrees. This event can be captured using the Event Management Service, which allows for the creation and management of events associated with devices. The service enables users to define custom event types with relevant details, facilitating appropriate actions to rectify the situation and ensure the safety of stored food.

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. For the list of supported APIs and required actions, refer here.

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 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¶

EventType is metadata used to create events in system. Events are associated with assets/entity. There are two kinds of event types:

1. Standard Event Type
   It is a predefined event type in the system with a time-to-live (TTL) of 35 days.
2. Custom Event Type
   It is the event type which is defined by the user and created by them in system.
   Events created using custom event types are called custom events. 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.
   Users can use standard event types or create their own custom event types for generating new events. The user is able to filter, update or delete the events or event types. An event type has a global or local scope and a time to live (TTL in days). TTL is applied to all instantiated events and expiry time of event is calculated at time of creation. 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. Event types of other tenants with scope as global would only be seen if the package or application of those tenants have been purchased or subscribed, or they are a part of PNP capability packs. Event Types can also be shared via tenant collaboration

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:

Event Operations:

• 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).
• Delete events asynchronously based on custom filter.
• Create events asynchronously.
• Sharing of the events between collaborating tenant
• Get notification on event create/delete/update

EventType Operations:

• Create, update, delete an event type
• Get a single event type.
• List filtered and sorted event types.
• Sharing of the EventType between collaborating tenants

Sharing: All event Types are shared between collaborating tenants. Events can be shared by asset sharing 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.
• API rate limits for EventManagement are applicable as technical rate limits.
• 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.
• Currently, Child eventtype LOCAL scope can be updated to GLOBAL having LOCAL scope for parent eventtype.
• Eventtype creation is allowed even though values definition is empty in case of ENUM field type.

Example Scenario¶

Suppose a Brewery owner is using thermometer to measure the temperature while making beer and the temperature must not cross the defined temperature limit, let's assume it as 60 degree Celsius. Brewery owner wants to generate event as soon as the temperature increases above 55 degree Celsius. Brewery owner has to follow below steps for that

1. Add the thermometer as an asset in Insights Hub. Let's assume assetId/EntityId is 'abcd'

2. Create an EventType for the same. Let's assume EventType is 'pqrs'.

   {
     "id": "pqrs",
     "name": "temperatureAlert",
     "parentId": "parentEventTypeId",
     "ttl": 3,
     "scope": "LOCAL",
     "fields": [
       {
         "name": "temperature",
         "filterable": true,
         "required": true,
         "updatable": false,
         "type": "integer",
       }
     ]
   }
   

3.Brewery owner has to collect the Data using timeseries and create Rule to generate events for temperature value greater than 55 degree Celsius. 4.After this events will be automatically created when the temperature increases above 55 degree Celsius.

Related Links¶

• Best Practices
• Asset Management