Skip To Content

Trace utility networks

Proper network management involves tracing your network to optimize paths for resources to travel. The utility network's tracing function provides a framework that can be used to help deliver resources to customers, track the health of a network, and identify deteriorating areas.

How tracing works

A trace begins at one or more starting points or at the subnetwork controller for the specified subnetwork and spans outward in a radial fashion. It travels through the network along paths of connected features until it reaches an end location. The end location can be a barrier or the end of a path. Upon completion, the results of a trace are returned in the form of a selection set. The selection set returned after a tracing event can be used for a variety of things. For example, a resulting selection set could be used as input to a reporting function, propagated to other map or diagram views.

To learn more about these components, see Starting points, Barriers, and Trace results.


Trace results include the entire geometry of a feature. Results do not currently support the partial selection of a feature.

The tier definition of a domain network impacts how subnetwork-based traces are handled. For domain networks with partitioned tier definitions, subnetwork-based traces stop at subnetwork controllers. For domain networks with hierarchical tier definitions, subnetwork-based traces stop at subnetwork controllers that have a tier name that matches the tier specified in the trace.

Subnetwork-based traces require at least one subnetwork controller for each subnetwork to determine flow direction on the fly during a trace. Multiple subnetwork controllers are required for traces travelling in or through subnetworks with a mesh tier topology type. The direction of flow from subnetwork controllers is dependent on how the domain network is configured for the subnetwork controller type (source or sink).

To learn more, see Utility network trace types.

Terminals represent ports on a device feature. A device feature that is defined as a subnetwork controller must have a terminal assigned with one port designated as the upstream. You can choose whether or not to enforce terminals on nonsubnetwork controller key features, such as valves. Using terminals gives you control over the internal paths of a device, promoting more accurate trace results. For example, a tristate switch used to control the flow of electricity between one wire and another. Electricity enters through one terminal and can exit through one of the three other terminals, depending on the valid path set for the device.

To learn more about terminals, see Terminal management.

Connectivity and traversability

There are two terms used to describe how utility network features relate to one another. Connectivity describes the state in which two features have geometric coincidence-based connectivity or are connected via a connectivity association. Traversability describes the situation in which two features are connected or associated and have appropriate attributes. The attributes and attribute values considered during a trace are controlled by configurations set up through geoprocessing tools.

Tracing operations travel a network in one of two methods, either by using connectivity or traversability. The method a trace uses is controlled by the type of trace used. The advanced parameters in the Set Subnetwork Definition and Trace tools control the details of traversability traces.

To learn more, see Connectivity and traversability.

The Trace tool

The Trace tool is used to run traces on your network. The Trace tool comes with a set of standard traces that can be built on to encompass complex traces.

To learn more about the tool, see Trace. To learn more about the different types of traces, see Utility network trace types.

The building blocks provided with the Trace tool allow you to refine what features are traced and which ones are returned in the results. They also allow you to gather additional information about a subnetwork through the use of network attributes. For subnetwork-based traces, the trace configuration can be predefined for all subnetworks in a tier using the Set Subnetwork Definition tool. This is part of the utility network configuration that is performed by the owner of the utility network. Once the subnetwork definition is configured for a tier, the Trace tool loads the definition for subnetworks traced in that tier; this saves time and ensures consistent trace results.

To learn more about trace configurations set at the administrator level, see Configure a trace and Set or modify the subnetwork definition.

The Trace tool relies on the network topology; it reads cached information about features from it instead of from the map. By reading cached information, performance is improved during complex traces on large networks. Since the Trace tool relies on the network topology, the results of a trace are not guaranteed to be accurate if there are dirty areas or dirty subnetworks in the traceable area. The network topology for the traceable area must be validated and the subnetwork updated to ensure it reflects the most recent edits or updates made to the utility network.

Usage notes

When executing a subnetwork-based trace using the Trace tool via Python, the Subnetwork Trace Configuration of the subnetwork definition is not used for the input Tier and must be manually specified.

Certain parameters on the Trace tool are only available from a script or model environment. These parameters allow you to specify the location of the class you want to use for trace locations, as well as modify or configure propagation and substitution.

To learn more, see Attribute propagation and Attribute substitution.

When running a trace using the Trace tool, it is recommended that you use the Set Trace Locations pane to establish barriers and starting points for your trace. This workflow establishes trace locations within the UN_StartingPoints and UN_Barriers feature classes in the project’s default file geodatabase.

When you run a trace from a script or model, use the Set Trace Locations geoprocessing tool. With the tool, you can place your trace locations in either the UN_ feature classes or in a new class at a location you specify. If you define a new class and location, then the Trace path to the feature class must be provided. This is done using the Starting Points and Barriers parameters on the Trace tool, which are only available through a script or model.