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"
}

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.