The Incident Detector Processor is 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 that is reporting vehicle positions and their current speed, the processor can 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.
Examples
The following are example uses of the Incident Detector Processor:
- The 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 service (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
Keep the following in mind when working with the Incident Detector Processor:
- Use cases for incident detection should not be confused with filtering. Incident detection actively maintains the state of each incident in memory and will change the schema of events as they pass through.
- The structure (or schema) of event records sent from the processor will match the incident GeoEvent Definition created when GeoEvent Server is installed. The schema of the incident GeoEvent Definition is illustrated in the table below.
- If the Keep Source Fields parameter is set to Yes, the schema will maintain the original event fields while appending the incident fields below. This new GeoEvent Definition may contain multiple geometry fields. Original source event field names will be modified in order to avoid naming conflicts with the field names in the incident schema. GeoEvent Server tags, specifically the TRACK_ID, TIME_START, and GEOMETRY tags, will be moved from source attribute fields to incident attribute fields as described 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 that, when observed, triggers the creation of a new incident or an update of an existing incident. | String |
| closeCondition | A logical condition that, when observed, triggers an existing incident to be closed. If omitted, the closing condition is assumed to be the logical negation of the opening condition. | String |
| description | The description of the incident’s status, the date and time it occurred, the date and time it started, or duration (in seconds) produced by the processor. | String |
| timestamp | The date and 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 as the 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. Intermediate vertices are not kept when the output geometry type is point. When the selected output geometry type is multipoint or polyline, intermediate vertices for continuous incidents are included. | Geometry |
| duration | The number of milliseconds 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 is not 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 or spatial conditions to detect, generate new, and update ongoing incidents. An event record’s Track ID uniquely identifies trackable assets, determines if an existing incident can be updated, or determines 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 Maximum number of opened incidents global setting for more information at Manage global 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 associated with that asset. 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 that satisfies the opening condition is received, triggering the incident manager to update the incident.
- The Opening Condition parameter must be specified. 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 as well as 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 to be true and either open a new incident, update an existing incident, or close an existing incident (when the closing condition evaluates true).
- 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 that 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 Ended value.
- 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 send 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 incident type is Cumulative, to configure the processor to collect vertices and output an updated multipoint or a polyline geometry. If the Keep Source Fields parameter is set to Yes, the incident will include the original event's geometry fields as well.
Parameters
The following are the parameters for the Incident Detector Processor:
| Parameter | Description |
|---|---|
|
Name |
A descriptive name for the processor used for reference in GeoEvent Manager. |
|
Processor |
Specifies the processor selected. |
| 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. Note:The incident name can be defined using the value from a field. For example, if an event record contains the field GeoTags from the GeoTagger Processor, ${GeoTags} can be specified as the incident name. This will assign the incident the name of the geofence that was potentially used to open the incident. |
| 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. See the following example:
Note:For details on spatial relationship operators and how to construct the attribute and spatial expressions used for opening and closing conditions, see Introduction to 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 the logical opposite of the opening condition. See the following example:
Note:For details on spatial relationship operators and how to construct the attribute and spatial expressions used for opening and closing conditions, see Introduction to 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. When configured using Point in Time, the processor should only output a point geometry. When configured using Continuous, the processor 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. 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:You can specify a value of zero (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. |
| Keep Source Fields | Specifies whether or not the original source fields will be appended to the outgoing event incident.
|
| Output GeoEvent Definition suffix name |
If the Keep Source Fields parameter is set to Yes, a copy of the incoming event's GeoEvent Definition will be made and this suffix will be appended to the original GeoEvent Definition's name. The original name and this suffix will be separated by a hyphen (-) character. |
Considerations and limitations
There are several considerations to keep in mind when using the Incident Detector Processor:
- Incidents monitored by an Incident Detector Processor should be short in duration, the processor is not designed to be used to detect or monitor long duration incidents.
- If the Keep Source Fields parameter is set to No, event records emitted from the 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, set the Keep Source Fields parameter to Yes and provide a suffix name for the new GeoEvent Definitions name.
- In some use cases, particularly when a notification output such as Send an Email or Send a Text Message output 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 sent 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 that satisfy the opening condition arrive once every 10 minutes and the expiry time default of 5 minutes (300 seconds) is used, incidents will regularly expire before they ever receive an update. This will result in false positives as incidents expire and transition from started to and ended state 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.