Detect Incidents

Available in real-time and big data analytics.

The Detect Incidents tool evaluates features using a set of open conditions and optional close conditions and creates a unique incident for each continuous set of observations that satisfy the conditions.

Workflow diagram

Examples

• Each vehicle in a fleet sends its location and current speed at regular intervals. If a vehicle's reported speed exceeds the posted speed limit for the location indicated, Detect Incidents opens an incident. For each subsequent observation reported by the vehicle, if its current speed continues to exceed the speed limit, the incident is maintained in an open state. When the vehicle reports its speed within the posted speed limit, the incident is closed.
• A pressure sensor on a pipeline reporting the current measured pressure at a valve indicates a pressure out of normal operating range. Detect Incident opens an incident and continues to report an open incident each time the sensor indicates the pressure is out of normal range. When the pressure returns to normal, the incident is closed.
• A convoy of trucks is approaching a tunnel where vehicles carrying hazardous materials is prohibited. Each vehicle reports its location, and ArcGIS Velocity enriches the incoming information for each vehicle based on the current manifest of its cargo. One of the trucks is carrying oxidizers that are considered hazardous. Detect Incidents opens an incident based on the truck's proximity to the tunnel and its current cargo attributes. When the truck detours away from the tunnel, the incident is closed.
• A delivery vehicle assigned to a specified route area goes outside the area for a period of time. Detect Incidents opens an incident when the vehicle exits the assigned area and closes the incident when the vehicle reenters the area.

Usage notes

• The Open Condition parameter is required; however, the Close Condition parameter is optional. If a close condition is not explicitly set, the logical NOT of the open condition is implicitly used as the close condition. An exception to this is if a value for Spatial Relationship is set to either Enter or Exit, the implicit Close Condition value is Exit or Enter, respectively.
• In a real-time analytic, if the value for Spatial Relationship is set to either Enter or Exit, for the Open Condition or Close Condition parameters, the tool will operate in a stateful manner. This enables it to compare sequential observations to one another to detect a change in state; for example, if the current condition is different from that of the previous observation. With other spatial relationships in real-time analytics, the tool does not need to compare any observations with previous ones, so it can run in a stateless manner, which is less resource intensive.
• When operating in a stateful manner, the Detect Incidents tool maintains a state store of the current observation for each Track ID. When a new observation is received it is compared to the current observation of the same Track ID, if present. If the new observation has a newer timestamp than the current observation in the state store, the current observation is replaced. If it has an identical timestamp to the current observation for the same Track ID, the tool does not distinguish between the two observations. This means the tool will not replace the current observation in the state store with the new observation, the new observation will not be added to the state store and future observations for this Track ID will be compared to the current observation that remained in the state store until a new observation arrives with a later timestamp. A warning will be logged by the tool when this occurs.
• The tool has two inputs; however, the Join Layer parameter is only required if choosing Spatial Relationship for the Open Condition or Close Condition parameters.
• The Open Condition and Close Condition parameters are specified using Arcade expressions. For an overview of Arcade expressions and supported functions, see the ArcGIS Arcade documentation.
• In a real-time analytic, if the Close on Expiration parameter is set to Yes, any open incidents are closed when the time set for Target Time Window expires. If set to No, any open incidents are discarded.
• For the Open Condition parameter, if choosing Spatial Relationship and using either the Enter or Exit spatial operator, checking the First observation can trigger enter or First observation can trigger exit check box indicates that the first target feature received or processed for each Track ID can open an incident if it is inside any join feature in the case of enter, or outside all join features in the case of exit, despite having no prior target feature to which to compare the current target feature's location. The default is unchecked.
• In a real-time analytic, the Target Time Window parameter value should be at least as long as the longest anticipated interval between observations for any given track. Observations older than this duration will be removed from memory to manage resources.
• The IncidentDuration value that is calculated for output incidents is in milliseconds.
• If a feed is connected to the join port, incident detection is done dynamically based on the changing features in both target and join feeds.
• If performing dynamic geofencing, the Join Time Window parameter must be set. If the join feed does not have a field tagged as the End Time key field and the last known observation for a join feature is older than this window, it will be purged from the tool's memory and will not be included in the analysis. If the join feed has a field tagged as the End Time key field, the feature will age out of the geofence store according to the value in the field tagged as End Time or at the close of the join time window, whichever comes first.
• If dynamic geofencing is being performed,Arcade expressions are only valid for the target feature.

Parameters

Parameter	Description	Data type
Input Layer	The features for which incidents will be detected using open and close conditions.	Features
Join Layer (optional)	Optionally, choose which dataset to process a spatial relationship with as part of an open or close condition.	Features
Open Condition	The set of conditions that define the start of an incident. This can include a spatial condition, time range, and a set of attribute expressions. Spatial Relationship—Specifies the criteria used to spatially filter the target features. The parameter only appears if a dataset has been connected to the join port. Spatial operators include Disjoint, Enter, Equals, Exit, Near Geodesic, Near Planar, Touches, and Within. First observation can trigger enter and First observation can trigger exit—Enabled if Enter or Exit are chosen as a spatial relationship and indicate that the first target feature received can open an incident if it is inside any join feature (in the case of Enter) or outside all join features (in the case of Exit), despite having no prior target feature to which to compare the current target feature's location. The default is false (not checked). Join Fields (optional) (real-time analytics only)—Specifies the fields from the join layer to add to the target features. For example, if a TUNNEL_ID field is chosen as the join field, the output schema will include the TUNNEL_ID field and its values. If an incident is detected at a tunnel with a TUNNEL_ID of 10, this value is added to the field in the target feature. If a closing condition with relevant spatial features is specified, the fields and values are also joined to the target feature. If any join fields are specified that enrich data from relevant spatial features using the disjoint spatial relationship, the field values will be set to null. Expression—An attribute expression to be evaluated to filter the incoming data. Attribute expressions are specified using Arcade expressions. Match all open conditions—Whether the spatial, temporal, and attribute conditions must all be satisfied to open an incident. If No is chosen, any one of the conditions will be sufficient to open an incident. Note: A target feature must satisfy its spatial relationship against all join features when disjoint or exit has been specified and there is more than one join feature. For any other spatial relationship and where there is more than one join feature, a target feature can satisfy its spatial relationship to any individual join feature.	Parameters
Close Condition (optional)	The set of conditions that define the end of an incident. As with Open Condition, this can include a spatial condition, a time range, and a set of attribute expressions. Spatial Relationship—Defines the criteria used to spatially filter the target features. This parameter only appears if a dataset has been connected to the join port. Spatial operators include Disjoint, Enter, Equals, Exit, Near Geodesic, Near Planar, Touches, and Within. Expression—An attribute expression to be evaluated to filter the incoming data. Attribute expressions are specified using Arcade expressions. Match all open conditions—Whether the spatial, temporal, and attribute conditions must all be satisfied to open an incident. If No is chosen, any one of the conditions will be sufficient to open an incident. Note: A target feature must satisfy its spatial relationship against all join features when disjoint or exit has been specified and there is more than one join feature. For any other spatial relationship and where there is more than one join feature, a target feature can satisfy its spatial relationship to any individual join feature.	Parameters
Return Incidents Only	Return only observations that relate to an incident (Yes) or return all observations (No).	Boolean
TRACK_ID Fields (big data analytics only)	Choose the fields to uniquely identify features to be processed. The parameter will be automatically populated if a Track ID key field is set on the input layer.	Fields
Target Time Window (real-time analytics only)	Set the time window to at least as long as the longest anticipated interval between observations for any given track. Observations older than this duration will be removed from memory to manage resources.	String
Join Time Window (real-time analytics only)	The time window for the join feed (dynamic geofences). If the last known observation for a join feature is older than the time window specified, it will be purged and will not be included in the analysis. If the join feed has a field tagged as End Time, this parameter is optional.	String
Close on Expiration (real-time analytics only)	If set to Yes, any open incident will be closed when the time set for Target Time Window expires. If set to No, any open incident will be discarded.	Boolean

Output layer

The output layer will have the schema of the incoming features and will be enriched with the fields below.

Field name	Description	Field type
IncidentId	The unique identifier for the incident.	String
IncidentStatus	The current status of the incident including Started and Ended.	String
IncidentDuration	The number of milliseconds the incident was open.	Integer