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 and objects 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, through aggregated geometry in multipart feature classes, or as a connectivity graph. The trace result 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. The aggregated geometry of trace results could also be reviewed using different filters to compare results. A connectivity graph can be used to build your own index or representation of the data in another application.

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

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. 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 network feature such as a device or junction object. A network feature that is defined as a subnetwork controller must have a terminal assigned with one port designated as the upstream. You can choose whether to enforce terminals on nonsubnetwork controller key features, such as valves. Using terminals gives you control over the internal paths of a network feature, promoting more accurate trace results. For example, a tristate switch device is 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 coincident-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, by using either 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 geoprocessing tool is used to run traces on your network and includes a set of standard traces that can be configured to create 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 which features and objects 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 to access cached information about network features. By reading cached information from the topology instead of the map, 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 subnetwork errors in the traceable area. The network topology for the traceable area must be validated and the subnetwork must be updated to ensure it reflects the most recent edits or updates made to the utility network.

Work with named trace configurations

Named trace configurations allow you to store complex traces in a utility network for reuse and sharing across an organization using ArcGIS Pro and web maps to be consumed by web and field applications. Introduced with version 5 of the utility network, the use of named trace configurations in an organization simplifies the user experience associated with tracing and allows users to discover information or answer questions using a trace without the need to understand all configuration details.

Named trace configurations can be consumed in ArcGIS Pro by using the Use Trace Configuration parameter on the Trace geoprocessing tool as well as the Named Configurations tab in the Trace pane.

Learn more about how to work with named trace configurations

Usage notes

The following are items for consideration when tracing a utility network.

Note:
When working with nonspatial objects, trace results may be impacted if editing tools are active when executing a trace. For example, if the Move tool is active when executing a trace, the results do not include junction and edge objects.

Scripting

When a subnetwork-based trace is run using the Trace tool through Python, the subnetwork trace configuration for the input tier is not applied automatically 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 you run a trace from a script or model, use the Set Trace Locations geoprocessing tool. With the tool, you can create trace locations in either the default feature classes created in your project or in a new class at a location you specify. This is similar to using the Trace pane when working within an active map view. If you define a new class and location, the Trace path to the feature class must be provided using the Starting Points and Barriers parameters on the Trace tool, only available through a script or model.

Work with multiple conditional expressions

When configuring barriers, filters, or outputs with multiple conditional expressions, it is important to note that the Boolean operator AND holds higher precedence than the Boolean operator OR.

As an example, consider you have three conditions, X, Y, Z, and want a barrier to stop a trace meeting the condition X AND Y OR Z. This could be interpreted in different ways. Trace uses disjunctive normal form (DNF) when processing multiple conditional expressions. Consequently, if the trace configuration input does not conform to DNF, trace results may be different than expected. Because DNF gives the Boolean operator AND higher precedence, this expression would be interpreted as (X AND Y) OR Z. If the alternate interpretation of X AND (Y OR Z) is desired, the expression would be written as (X AND Y) OR (X AND Z).