Detect Incidents

The Detect Incidents tool 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

Detect Incidents tool 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 selecting 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 selecting Spatial Relationship and using either the Enter or Exit spatial operator, checking First observation can trigger enter or First observation can trigger exit checkboxes 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 will be 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.
  • Adding a join feed to a tool must be done in the model view. Analytics with tools using join feeds cannot be viewed or edited in the workflow view.

Parameters

ParameterDescriptionData 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—Defines 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 selected 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).
  • Time Range—The time range in which the observation must take place. Choices include Between, Before, and After specified times.
  • 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 selected, 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.
  • Time Range—The time range in which the observation must take place. Choices include Between, Before, and After specified times.
  • 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 selected, 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 nameDescriptionField 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