Skip to content

Event Management – Best Practices

This document provides best practices for querying and creating events or event types in Event Management.

General Remarks

  • The size of a page should be as small as possible (default page size is 20).
  • If real time data about events is not required, set the polling cycle as high as possible.
  • If an application uses retry strategy, it should wait for some time after receiving a gateway timeout.
  • For the following severities default apps like Fleet Manager or the MindSphere Web Components show the depending icon. For other severities only the number is displayed.
Severity Icon Description
20 error Error
30 warning Warning
40 info Information

Filterable Properties for Custom Events

Enum

If a custom event type field stores only allows a few values, consider using ENUM as type of that field.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "name": "volatileEventType",
  "ttl": 1,
  "fields": [
    {
      "name": "risk",
      "filterable": true,
      "required": true,
      "updatable": true,
      "type": "ENUM",
      "values" : ["LOW", "MEDIUM", "HIGH"]
    }
  ]
}

UUID vs String

If a custom event type field stores only UUID values, consider using UUID as type of that field instead of STRING.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
  "name": "volatileEventType2",
  "ttl": 1,
  "fields": [
    {
      "name": "code",
      "filterable": true,
      "required": true,
      "updatable": false,
      "type": "UUID"
    }
  ]
}

Filtering

HTTP GET /events API uses filter parameter to filter custom events list. Please refer to Listing Custom Events for sample.

Filtering by Timestamp

When filtering by timestamp the time interval should be as small as possible. It should not exceed 1 month. If no timestamp is specified for the filter, only events from the last week are retrieved.

1
2
3
4
5
{
  "timestamp": {
    "between": "[1970-01-01T07:25:07.166Z,2018-11-05T10:25:07.166Z)"
  }
}

1
2
3
4
5
{
  "timestamp": {
    "between": "[2018-11-01T07:25:07.166Z,2018-11-05T10:25:07.166Z)"
  }
}

Filtering by Type ID

Provide the typeId for the filter to search among events of a particular event type.

1
2
3
4
5
{
  "timestamp": {
    "after": "2018-11-01T07:25:07.166Z"
  }
}

1
2
3
4
5
6
{
  "typeId": "3868feab-9ae6-44a8-9d9e-d20da848afb8",
  "timestamp": {
    "after": "2018-11-01T07:25:07.166Z"
  }
}

Filtering by other Fields

Filter by custom fields rather than standard ones, if possible.

1
2
3
4
5
6
7
8
{  
   "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
   },
   "entityId":"e7a12da7b60c4402a0a14dce547206ed",
   "acknowledged":false,
   "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

1
2
3
4
5
6
7
8
9
{  
   "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
   },
   "entityId":"e7a12da7b60c4402a0a14dce547206ed",
   "acknowledged":false,
   "typeId":"3f690adf-edc8-447f-b1c8-4758aa7924ba",
   "risk": "LOW"
}

Drilldown

Sometimes it is faster to do a drilldown, i.e. the filtering is done in multiple steps. For example, the filter expression below filters for a typeId which refers to a custom event type. However, the other filter parameters refer to fields defined in the parent event type. This can make the filtering more expensive.
In such cases it is advised to first replace the typeId by the parent type. Afterwards a drilldown to the for filtering by fields of the custom event type can be done.

1
2
3
4
5
6
7
8
{  
   "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
   },
   "entityId":"e7a12da7b60c4402a0a14dce547206ed",
   "acknowledged":false,
   "typeId":"b7f9a843-a530-4159-989e-20645e2b647d"
}

1
2
3
4
5
6
7
8
{  
   "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-10-05T14:53:07.534Z)"
   },
   "entityId":"e7a12da7b60c4402a0a14dce547206ed",
   "acknowledged":false,
   "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

Filtering with PageCache

For better performance, set enablePageCache to true along with the filter while retrieving the events. When there are huge number of events satisfying the filter criteria, many subsequent calls are needed for traversing all the pages and retrieving the events. For such cases, we have introduced a new query parameter enablePageCache which can be used as below:

  • Set enablePageCache to false for first request. For all subsequent request for different pages, set enablePageCache to true.
  • Set enablePageCache to true for all requests if the new events are getting generated less frequently, i.e. having intervals of more than 10 mins.

When this parameter is set to true, total count of events satisfying the filter criteria will be cached for 10 mins and same cached value will be returned in response resulting in near to accurate value. The event information returned will always be the latest.

1
2
3
{  
   enablePageCache : false
}

1
2
3
{  
   enablePageCache : true
}

Sorting

For better performance, sort by fields that are present in the filter expression.

1
2
3
{  
   "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

1
2
3
4
5
6
{  
   "timestamp":{  
      "between":"[2018-10-01T00:00:00.001Z,2018-11-01T14:53:07.534Z)"
   },
   "typeId":"com.siemens.mindsphere.eventmgmt.event.type.MindSphereStandardEvent"
}

1
sort: timestamp,desc

Any questions left?

Ask the community

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