Incident Detector Processor

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 that 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. 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 output from the processor will match the incident GeoEvent Definition created when GeoEvent Server is installed. The schema of the incident GeoEvent Definition is illustrated 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. Tags, specifically TRACK_ID, TIME_START, and GEOMETRY 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 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. 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, 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. 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 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 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 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, 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 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. If the Keep Source Fields ? parameter is set to Yes, the incident will include the original event's geometry field(s) as well.

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. 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 give 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. For example: altitude > 20000 GEOMETRY INSIDE ANY Zone/.* 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: altitude <= 20000 GEOMETRY OUTSIDE ALL Zone/.* 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. Cumulative - Incidents have an opening and closing condition. The time between the incident’s generation and its expiry, or closing, is the incident’s duration. Cumulative incidents are monitored and updated by GeoEvent Server as additional event data is received. Point in Time - Incidents do not have a closing condition. They are considered instantaneous and are closed immediately after they are generated. The duration of a point in time incident is always zero (0).
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.
Keep Source Fields?	Specifies whether or not the original source fields will be appended to the outgoing event incident. Yes—Will append all the original source fields and their values to the outgoing incident event. The emitted event's GeoEvent Definition schema will be a combination of the incident schema and the original event schema. These original source fields will have a prefix added to them indicating they are derived from the source event. No—Will cause the processor to discard the original source event and emit a new event with the incident GeoEvent Definition schema.
Output GeoEvent Definition suffix name	If Keep Source Fields? 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 definition's name. The original name and this suffix will be separated by a - character.

Considerations and limitations

• Incidents monitored by an Incident Detector Processor should be short in duration, it is not designed to be used to detect or monitor long duration incidents.
• If Keep Source Fields? is set to No, 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, set Keep Source Fields? to Yes and provide a suffix name for the new GeoEvent Definition(s) name.
• 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.