Summary
The Incident Detector Processor can be used to determine if a received event record satisfies some condition and an incident should be opened. Incidents identify where a condition occurred and potentially the duration of a condition. For example, if you are working with a data feed is reporting vehicle positions and their current speed, the processor could be used to open an incident when a vehicle exceeds a certain rate of speed or when a vehicle’s position intersects an area of interest (geofence). As updates are received for a tracked vehicle’s location and speed, GeoEvent Server will update the ongoing incident; the incident will be closed once an event record is received indicating the vehicle is no longer speeding or is no longer within a geofence area of interest.
Examples
- The Incident Detector Processor can be used to monitor a fleet of vehicles for speeding conditions. As vehicles exceed a certain speed, an incident can be generated that indicates when and where the speeding started. The processor can be configured to report speeding incidents as a point-in-time occurrence or as a cumulative (ongoing) event ending when the vehicle is no longer speeding. The latter can provide information on how long the speeding incident lasted.
- The processor can be used to monitor emergency responders in the field. As ambulances leave their designated area of coverage (geofence), incidents can be generated to indicate their departure. These incidents can then be acted upon by dispatch or an operations center. The same incidents can also be used to notify other emergency responders of a gap in coverage.
Usage notes
- Use cases for incident detection should not be confused with filtering. The Incident Detector Processor is different from other processors in that event records emitted from the processor are not copies (or derivatives) of event records received by the processor. The structure (or schema) of event records output from the processor match the incident GeoEvent Definition created when GeoEvent Server is installed. The schema of the incident GeoEvent Definition is illustrated below.
| Field Name | Description | Data Type |
|---|---|---|
| id | A unique identifier (GUID) created by the processor for each new incident. | String |
| name | A non-unique name chosen when configuring the processor to describe incidents created by the processor. | String |
| type | An incident’s type is either Point in Time or Cumulative. | String |
| status | An incident’s status is either Started, Ongoing, or Ended. | String |
| alertType | An incident’s alert type is either Notification, Warning, or Urgent. | String |
| openCondition | A logical condition which, when observed, triggers the creation of a new incident or an update of an existing incident. | String |
| closeCondition | A logical condition which, when observed, triggers an existing incident to be closed. | String |
| description | The description of the incident’s status, date/time occurred, date/time started, or duration (in seconds) produced by the processor. | String |
| timestamp | The date/time an incident was started or last updated. The value is expressed as a long integer in epoch milliseconds. The TIME_START tag is applied to this field. | Date |
| definitionName | The name of the GeoEvent Definition associated with the event record whose receipt created the incident. | String |
| definitionOwner | The owner of the GeoEvent Definition associated with the event record whose receipt created the incident. | String |
| trackId | The value used to uniquely identify trackable assets. Event records sent to an Incident Detector Processor must have a field tagged TRACK_ID. The TRACK_ID tag is applied to this field for incidents emitted from the processor. | String |
| geometry | The point, multipoint, or polyline geometry associated with an incident output from the processor. The GEOMETRY tag is applied to this field. | Geometry |
| duration | The number of seconds a cumulative incident is ongoing. This value is updated only as new observations are received. A point in time incident’s duration will always be zero. | Long |
| dismissed | A flag set to false indicates an incident has not been dismissed. A Field Calculator Processor can be used to change this attribute value, but an Incident Detector Processor will clear the attribute value to false for all incidents emitted from the processor. | Boolean |
| assignedTo | A value used to indicate a user or operator to whom an incident is assigned. A Field Calculator Processor can be used to change this attribute value, but an Incident Detector Processor will reset the attribute value to an empty string as updated incidents are emitted from the processor. | String |
| note | A value used to note information about a user or operator to whom an incident is assigned. A Field Calculator Processor can be used to change this attribute value, but an Incident Detector Processor will reset the attribute value to an empty string as updated incidents are emitted from the processor. | String |
- The Incident Detector Processor uses specified attribute and/or spatial conditions to detect, generate new, and update ongoing incidents. An event record’s TRACK_ID is used to uniquely identify trackable assets, determines if an existing incident can be updated, or if a new incident should be created.
- Incidents whose type is Point in Time are immediately closed and never enter a Started or Ongoing state for any period of time. A Point in Time incident’s duration will always be zero.
- Incidents whose type is Cumulative are typically closed only when an event record is received that satisfies the closing condition. Incidents in a Started or Ongoing state may be administratively closed when no event record associated with the incident has been received within a specified period of time – refer to the Expiry Time (seconds) parameter below.
- Incidents in a Started or Ongoing state will be administratively closed when more than a specified number of open incidents are actively being managed – refer to the GeoEvent Server global setting Maximum number of opened incidents. For details, see Incident Manager Settings.
- The Expiry Time (seconds) parameter specifies how long the processor should wait to receive an update for a tracked asset before administratively closing a started or ongoing incident. Incidents will expire and transition to a ended state, even if event records satisfying the closing condition have not been received, if an update from a tracked asset is not received before the expiry time reaches zero.
- Setting the Expiry Time (seconds) parameter to 0 disables the processor’s automatic expiry. For example, an open incident will remain in a started or ongoing state if the incident manager has room in its cache of open incidents. An incident’s duration will only be updated, however, when a subsequent event record which satisfies the opening condition is received, triggering the incident manager to update the incident.
- When configuring the processor, you must specify the Opening Condition parameter. If left unspecified, the optional Closing Condition parameter will default to the logical negation of the opening condition.
- An opening condition and closing condition can specify an attribute-based condition and/or a spatial relationship with a geofence. Like a filter, if the data associated with a received event record satisfies the specified expression, the processor will consider the condition True and either open a new incident or update an existing incident.
- The closing condition does not have to be the logical opposite of the opening condition. For example, an incident can be opened when an aircraft’s altitude is below a certain threshold and the incident can be closed when the aircraft is observed to be inside a specific geofence (like arriving at an airport gate) rather than requiring the aircraft rise above a specified altitude in order to close the incident.
- When an incident is first created its status will be set to Started. When a subsequent event record is routed to the processor which satisfies the opening condition, a started incident’s status will change to Ongoing. An incident will remain in the ongoing state until closed, either because an event record satisfying the closing condition is received, or because the incident is administratively closed. The status of a closed incident is assigned the value Ended.
- Each incident generated by the processor has an associated geometry. The type of geometry is specified when configuring the processor. The processor is typically configured to output a point geometry to model an incident as having occurred at a specific location at a specific time. It can also be useful, when working with incidents whose type is Cumulative, to configure the processor to collect vertices and output an updated multipoint or a polyline geometry.
Parameters
| Parameter | Description |
|---|---|
| Name | A descriptive name for the processor used for reference in GeoEvent Manager. |
| Processor | The name of the selected processor. |
| Incident Name | A descriptive name for incidents created by the processor. The processor will add the incident name to the incident record’s name field. This value is not necessarily unique. For example, you could configure the processor to detect incidents of speeding vehicles. Every vehicle observed to be speeding would generate an incident record whose descriptive name might be the string value Speeding Vehicle. |
| Opening Condition | The opening condition that must be satisfied to create a new incident or update an existing incident. The opening condition can be specified using attribute or spatial operators. For example:
Note:For details on spatial relationship operators and how to construct the attribute and spatial expressions used for opening and closing conditions, see Filters. |
| Closing Condition | The closing condition used to close or end an incident. The closing condition can be specified using spatial or attribute operators. If left undefined the closing condition for an incident is assumed to be the logical opposite of the opening condition. For example:
Note:For details on spatial relationship operators and how to construct the attribute and spatial expressions used for opening and closing conditions, see Filters. |
| Severity | The severity level associated with the incident type. Incidents are limited to a single severity level. The severity level is written to the alertType field as a part of the incident schema. Available severity levels include Notification, Warning, and Urgent. Note:The processor must be edited and the GeoEvent Service republished in order to change the severity level associated with incidents. |
| Incident Type | The type of incident created by the processor. Available incident types include Cumulative and Point in Time. The incident type is written to the type field as part of the incident schema. The default is Cumulative.
|
| Geometry Type | The geometry type of the incidents created by the processor. The available geometry types for incident records include Point, Multipoint, and Polyline. The default is Point. The processor is typically configured to associate a point geometry with incidents it creates to model an incident as having occurred at a specific location (point) at a specific time. The processor configured using Point in Time should only output a point geometry. The processor configured using Continuous may collect multiple points or locations over time and use these as vertices to update a multipoint or polyline. |
| Expiry Time (seconds) | The amount of time in seconds an incident in the Started or Ongoing state can exist, without receiving an update, before the incident will expire and be closed. The processor will only expire an incident if no event record satisfying the opening condition is received before the expiry time reaches zero (0). Incidents may expire and transition to an Ended state without an event record satisfying the closing condition being received. The default is 300 seconds. Note:Specify a value of 0 for the Expiry Time (seconds) parameter to disable automatic expiry for incidents. While incidents with this configuration will not expire, neither will their duration be updated as this requires a continuous flow of event records satisfying the opening condition be received by the processor. |
Considerations and limitations
- Event records emitted from the Incident Detector Processor are associated with the incident GeoEvent Definition; the schema or structure of the event record received by the processor is discarded. To enrich an incident event record with data from the original schema of the inbound event record, consider using an Event Joiner Processor immediately following an Incident Detector Processor. Incidents can be joined with their corresponding source event records using a common TRACK_ID as a field on which to perform an attribute join.
- In some use cases, particularly when a notification output such as Send an Email or Send a Text Message is used in a GeoEvent Service, it may not be desirable to be continuously notified of an incident’s ongoing status. An incident’s status field can have only one of three values; Started, Ongoing, or Ended. If you want to receive notifications only when an incident has started or ended, consider using an attribute filter which discards incident records emitted from an Incident Detector Processor whose status is Ongoing.
- Consider the event record velocity and frequency of updates when setting the Expiry Time (seconds) parameter. If event records which satisfy the opening condition arrive once every 10 minutes and the expiry time default of 5 minutes (300 seconds) is accepted, incidents will regularly expire before they ever receive an update. This will result in false positives as incidents expire and transition from Started to Ended without ever entering an Ongoing state. The duration of incident records will always be zero in this case because a second event record satisfying the opening condition was never received before the incident expired.