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

The following are example uses of the Detect Incidents tool:

• Each vehicle in a fleet sends its location and speed at regular intervals. If a vehicle's reported speed exceeds the posted speed limit for the location indicated, the Detect Incidents tool opens an incident. For each subsequent observation reported by the vehicle, if its speed continues to exceed the speed limit, the incident is maintained in an ongoing 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 the incident is maintained in an ongoing state as long as 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 are prohibited. Each vehicle reports its location, and ArcGIS Velocity updates 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. An incident is opened based on the truck's proximity to the tunnel and its 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. An incident is opened when the vehicle exits the assigned area, and the incident is closed when the vehicle reenters the area.

Usage notes

Keep the following in mind when working with the Detect Incidents tool:

• The Open Condition parameter is required, while the Close Condition parameter is optional. If the Close Condition parameter value is not explicitly set, the NOT logical operator of the Open Condition parameter is used as the close condition.
  • If the Spatial Relationship option is set to Intersects, the implicit Close Condition value is Disjoint.
  • If the Spatial Relationship option is set to Enter or Exit, the implicit Close Condition value is Exit or Enter, respectively.
• In a real-time analytic, this tool operates in a stateful manner when Enter or Exit are used for the Spatial Relationship in the Open Condition or Close Condition. While operating in a stateful manner, the tool can compare sequential observations to detect a change in state between observations. This tool runs in a stateless manner when using other spatial relationship options because it does not need to compare current to previous observations. Running in a stateless manner is much 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 time stamp than the current observation in the state store, the current observation is replaced. If it has an identical time stamp to the current observation for the same track ID, the tool does not distinguish between the two observations. This means the tool does not replace the current observation in the state store with the new observation, the new observation is not added to the state store, and future observations for this track ID are compared to the current observation that remains in the state store until a new observation arrives with a later time stamp. The tool logs a warning when this occurs.
• The tool has two inputs; however, the Join data parameter is only available if you choose Spatial Relationship for the Open Condition or Close Condition parameters.
• An Arcade expression can be configured for the Open Condition of Close Condition parameters.
• 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 remain open. If the time set for Target Time Window expires, a new incident is created if the spatial relationship or attribute expression in the Open Condition parameter is met.
• For the Open Condition parameter, if you choose Spatial Relationship and use either the Enter or Exit spatial operator, you can check the First observation can trigger enter or First observation can trigger exit check box to indicate 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 previous 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 should be set to the longest duration of time that an incident should remain open or longer. Observations older than this duration are deleted from memory to manage resources. It is recommended that you set the value higher than the longest expected incident duration. For example, if the longest an incident is expected to stay open is 20 hours, this value could be set to 24 hours to ensure that no incidents are closed prematurely.
• The IncidentDuration value that is calculated for output incidents is in milliseconds.
• If a feed is connected to the join port, incident detection is based on the changing features in both target and join feeds.
• When performing dynamic geofencing, the Join Time Window parameter must be set. If the join feed does not have a key field specified for the End time option and the last known observation for a join feature is older than this window, it is deleted from the tool's memory and excluded from the analysis. If the join feed has a key field specified for the End time option, the feature expires from the geofence store according to the value in the field that is the end time or at the close of the join time window, whichever comes first.
• When dynamic geofencing is being performed, Arcade expressions are only valid for the target feature.
• The following table outlines the available spatial relationship methods based on input and join geometry types:

Input and join geometry types	Contains	Crosses	Disjoint	Enter	Equals	Exit	Intersects	Near geodesic	Near planar	Overlaps	Touches	Within
Point and point
Point and polyline
Point and polygon
Polyline and point
Polyline and polyline
Polyline and polygon
Polygon and point
Polygon and polyline
Polygon and polygon

Parameters

The following are the parameters for the Detect Incidents tool:

Parameter	Description	Data type
Target Data	The data for which incidents are detected using the Open Condition and Close Condition parameters.	Features
Join Data (optional)	The data to be used with a spatial relationship in the Open Condition or Close Condition parameters.	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. Time Range (big data analytics only)—Specifies the time range used to detect incidents. Spatial Relationship—Specifies the criteria used to spatially detect incidents. This option only appears if a dataset has been connected to the join port. Spatial operators include the following: Disjoint: If one geometry does not intersect another geometry. Enter: If one geometry enters the space of another geometry. Equals: If the base and comparison geometries are of the same shape type. Exit: If one geometry moves out of the space occupied by another geometry. Near Geodesic: If one geometry is near a vertex or edge within a given geodesic distance of another geometry. Near Planar: If one geometry is near a vertex or edge within a given planar distance of another geometry. Touches: If one geometry touches another geometry if they have an intersecting vertex, but the geometries do not overlap. Contains: If one geometry contains another geometry. Crosses: If the two geometries intersect in a geometry of a lesser shape type. Intersects: If one geometry intersects another geometry. Overlaps: If one geometry overlaps another geometry. None: If no spatial relationship exists between two geometries. Within: If one geometry is fully within another geometry. First observation can trigger enter/exit—This option is available if Enter or Exit is chosen for a spatial relationship. This indicates that the first target feature received can open an incident, despite having no previous target feature to which to compare the current target feature's location. For Enter, the incident opens if the target feature is inside any join feature. For Exit, the incident opens if the target feature is outside any join feature. The default is unchecked for both. Join Fields (optional) (real-time analytics only)—Specifies the fields from the join features to add to target features. Fields chosen as join fields are present in the output schema. If the disjoint spatial relationship is used, the field values are set to null. Arcade Expression—An attribute expression that sets criteria for incidents. Match all open conditions—If Yes, spatial, temporal, and attribute conditions must all be satisfied to open an incident. If No, any one of the conditions is sufficient to open an incident. Note: When Disjoint or Exit is used as the spatial relationship for the Open Condition parameter, the target features must be fully disjointed from any features from the Join Dataparameter source for an incident to be opened. For all other spatial relationship options, the target feature only needs to satisfy the spatial relationship with any one of the features from the Join Data parameter source to open an incident.	Parameters
Close Condition (optional)	The set of conditions that define the end of an incident. As with the Open Condition parameter, this can include a spatial condition, a time range, and a set of attribute expressions. Time Range (big data analytics only)—Specifies the time range used to detect incidents. 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 the following Disjoint: If one geometry does not intersect another geometry. Enter: If one geometry enters the space of another geometry. Equals: If the base and comparison geometries are of the same shape type. Exit: If one geometry moves out of the space occupied by another geometry. Near Geodesic: If one geometry is near a vertex or edge within a given geodesic distance of another geometry. Near Planar: If one geometry is near a vertex or edge within a given planar distance of another geometry. Touches: If one geometry touches another geometry if they have an intersecting vertex, but the geometries do not overlap. Contains: If one geometry contains another geometry. Crosses: If the two geometries intersect in a geometry of a lesser shape type. Intersects: If one geometry intersects another geometry. Overlaps: If one geometry overlaps another geometry. None: If no spatial relationship exists between two geometries. Within: If one geometry is fully within another geometry. Arcade Expression—An attribute expression that needs to be evaluated to detect incidents. Match all close conditions— If Yes, spatial, temporal, and attribute conditions must all be satisfied to close an incident. If No, satisfying any one of the conditions is sufficient to close an incident. Note: When Disjoint or Exit is used as the spatial relationship for the Close Condition parameter, the target features must be fully disjoint from any features from the Join Data parameter source for an incident to be opened. For all other spatial relationship options, the target feature only needs to satisfy the spatial relationship with any one of the features from the Join Data parameter source to open an incident.	Parameters
Return Incidents Only	If Yes—Returns observations that only relate to an incident. If No—Returns all observations.	Boolean
Tracking	Fields used to uniquely identify features to be processed. If the target feature layer has a track ID field specified, the Track ID value is automatically set.	Fields
Target Time Window (real-time analytics only)	Observations older than this duration are deleted from memory to manage resources. This value should be set to the longest duration that an incident should remain open or longer. It is recommended that you set this value higher than the longest expected incident time.	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 is deleted and is not included in the analysis. If the join feed has a key field specified for the End time option, this parameter is optional. Note: This parameter is only available if both the target and join layers are feeds.	String
Close on Expiration (real-time analytics only)	If Yes—Any open incident closes when the Target Time Window value expires. If No— Any open incident remains open even if the Target Time Window value expires. Upon expiration of the Target Time Window value, a new incident is created if the spatial relationship or attribute expression is met.	Boolean

Output layer

The output layer has the schema of the incoming features in addition to the fields below:

Field name	Description	Field type
IncidentId	The unique identifier for the incident.	String
IncidentStatus	The current status of the incident. The status can be Started, Ongoing, or Ended.	String
IncidentDuration	The number of milliseconds the incident is open.	Integer