Skip To Content

Configure a trace

Tracing a utility network is done to discover answers and solve problems with regard to the state of your network at any moment. To trace a utility network, use the Trace tool.

There are many types of traces provided with the Trace tool:

Along with these trace types, the Trace tool also includes a comprehensive set of advanced configurations used to refine each provided trace type. These configurations allow you to constitute traversability, distinguish what features should be returned, and set up calculations to be performed. ModelBuilder can be used to save complex configurations and also allows you to reduce the number of parameters presented on the model tool interface. This helps you and others rerun advanced traces with just one click.

For example, you have been tasked to draw up a report on the number of customers fed by each transformer with a voltage over 60 for a specific feeder. In the report, you must include the total load for those transformers and mark which ones are on wooden poles over 25 years-old, with the last inspection being over 5 years ago to indicate a pole inspection is required. You run a single preconfigured trace that returns all of this information to you.

Setting subnetwork trace configurations within the subnetwork definition allows the Trace tool to be auto-populated when executing a trace against a specific tier. This applies for subnetwork-based traces. For example, you always want your subnetwork traces to stop at protective devices, effectively indicating the end of the feeder. You also always want to calculate the total load for each feeder. You probably do not want to set these parameters every time you run a subnetwork-based trace, which is why a standard subnetwork definition can be defined for all subnetworks within a tier. A subnetwork definition is set by the administrator when a tier is created (before subnetworks are added to it). When the tier is specified in the Trace tool, the advanced parameters are auto-populated with the subnetwork trace definition set for the input tier. Any trace configuration parameters that are populated can be overwritten manually in the tool before executing the trace.

During the setup of a trace, you can modify or add onto the subnetwork trace definition. You can do such things as control the types of features traced (pipe diameter greater than 6 inches), pick what types of features you want returned (all open valves), and perform calculations using network attributes (total the length of the AB-phase lines).

Each configuration component is examined in the following sections. See the Trace tool for parameter options and usage information.

Define the trace region

In the Trace tool, you must specify where the trace is allowed to travel within your network. Defining a traceable area helps to ensure the intended part of the network is traced. It is also used to restrict traversal to other tiers for certain trace types. Three pieces of information are used to denote the extent of a traceable area: domain network, tier, and subnetwork. The type of trace determines the required pieces of information, therefore not all traces will have these parameters.

Specifying a domain network restricts a trace to only that domain network. All traces require a domain network to be set. Some traces require a tier and optionally a subnetwork to be specified. Other types of traces require a tier and a target tier to be set (upstream and downstream). A target tier allows you to trace across multiple tiers within a domain network.

The Tier parameter is used to restrict tracing to a particular tier when specified in the Trace tool. It is also used to automatically populate trace configuration parameters with values set for the subnetwork definition. When starting points are used in conjunction with the Tier parameter, the starting points must reside within the specified tier. The Target Tier parameter is used for Upstream and Downstream traces and indicates the boundary of the traceable network; a trace can traverse within but not beyond the target tier.

When tracing across multiple tiers trace configuration settings are loaded for the initial tier. The following trace configuration settings are loaded for each new tier the trace encounters:

  • Traversability scope
  • Condition barriers
  • Arcade expression barriers
  • Function barriers
  • Propagators

For Subnetwork traces, selecting a Subnetwork Name value allows you to specify what subnetwork to trace instead of using starting points. This uses the subnetwork controller or controllers for the specified subnetwork as the starting point for the trace.

Include containers, content, structures, and barriers in results

This set of configurable options on the Trace tool allows you to configure the features that are included in the results based on their association role or barrier status. Association features can include containers, content, and structures. By default, everything but containers, their content, and structures are returned in the results of a trace.

Include Containers

Include containers in the results of a trace. Any container features for the content features that are traced will also be included in the trace results. This configuration can also be used to trace a structure network; for example, returning connected underground ducts.

Configuration optionDescription

Include Containers

  • Checked—the trace results will include containers.
  • Unchecked—the trace results will not include containers. This is the default.

Include Content

Include content features in the results of a trace. This encompasses content from containers that are included in the trace results. To disambiguate between the different types of containers, use an Output to filter your results.

Configuration optionDescription

Include Structure Line/Junction Container Content

  • Checked—the trace results will include content (Structure Line/Junction Container).
  • Unchecked—the trace results will not include content (Structure Line/Junction Container). This is the default.

Include Structures

Include structures in the results of a trace. This is helpful for such tasks as reporting structural assets.

Configuration optionDescription

Include Structures

  • Checked—the trace results will include structures.
  • Unchecked—the trace results will not include structures. This is the default.

Include Barrier Features

Include barriers in the results of a trace. This encompasses feature barriers set in the Trace Locations pane as well as dynamically configured barriers: condition barriers, function barriers, filter barriers, and filter function barriers. The subnetwork definition can be used to configure whether barriers are included in trace results as part of the subnetwork trace configuration.

Configuration optionDescription

Include Barrier Features

  • Checked—the trace results will include barrier features. This is the default.
  • Unchecked—the trace results will not include barrier features.

This trace configuration option is also influenced by the subnetwork trace configuration for subnetwork-based trace types. This is loaded when the Tier parameter is specified.


The Include Barrier Features configuration option does not apply to device features with terminals.

Ignore Barriers At Starting Points

Ignore barriers in the trace configuration if they are starting points. This may be useful when performing an upstream protective device trace and using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices.

Configuration optionDescription

Ignore Barriers At Starting Points

  • Checked—the trace results will ignore barriers at starting points.
  • Unchecked—the trace results will honor barriers at starting points. This is the default.

Ensure network consistency

A consistent area of a network is one that does not have any dirty areas; the network topology has been validated. This is the only way to guarantee a trace is reading the latest information about your network from the network topology. Some trace types require the subnetworks you trace to be clean as well. To learn more see Dirty subnetworks.

The Validate Consistency configuration option on the Trace tool allows you to ensure the trace results are consistent with the network topology. The trace operation fails if any dirty areas are encountered when Validate Consistency is set to true. To remove dirty areas, the network topology must be validated.


Only dirty areas created from delete operations or updates to existing network features will cause an error to be raised about inconsistencies in the trace results. Dirty areas from newly created features will not cause a failure in the Validate Consistency check.

Not having the Validate Consistency check box checked can lead to unexpected trace results; for example, a feature is deleted from a network that breaks the only path between location A and location B. A dirty area is created for the deleted feature. Before the network topology is validated, a trace is executed to find connected features starting at location A, with the Validate Consistency option unchecked. The trace reaches location B and the tool completes with no warnings. Location B was reached because the deletion of the feature connecting A to B has not been reflected in the network topology by executing a validate operation.

If the Validate Consistency option is checked in the example above, when the trace reaches the dirty area marking the deleted feature, the error mentioned above is returned in the tool to let you know a dirty area was encountered and the trace fails. After the topology is validated for the area being traced, the trace cannot reach location B, as the deleted feature is now reflected in the network topology. If the network topology is not validated for the entire extent of the area that will be traced other dirty areas could be encountered.

Even though information in the network topology is up to date for the traceable area, the subnetworks may be dirty. Ensure the traceable subnetworks are updated as well. To learn more, see Update subnetworks.

Configuration optionDescription

Validate Consistency

When this option is checked, the tool returns an error if any dirty areas intersect the traced features. If this option is not checked, dirty areas are ignored. This option is checked by default.

Control what is traced

Barriers are used during a trace to denote a stopping location; features beyond that location are not traced. The results of a trace will not include features past a barrier, but they can optionally include the barrier itself.

The Traversability section of the Trace tool includes condition barriers and function barriers to control the traversability of a trace. Condition barriers are expressions based on network attributes or network categories to define where a trace should stop. Function barriers define when a trace should stop when a condition is satisfied.

Traversability scope is further controlled by the traversability_scope parameter that is labeled Apply Traversability To in the Trace tool. This parameter determines whether traversability is applied to both junctions and edges, junctions only, or edges only. For example, if traversability is applied to junctions only and an edge satisfies the condition specified in a condition barrier, the trace will not stop at the edge due to the traversability scope.

To learn more, see Barriers.

Set up functions

A function is a trace configuration that allows you to run calculations on network attributes associated with traced features; for example, the sum of the length of all the wire traced. More than one function can be specified for a trace.

In addition, an optional network attribute filter may be added to each function; when specified, the function will only be applied to features that satisfy the network attribute filter.

An optional network attribute filter may be added to each function. When specified, the function will only be applied to features that satisfy the network attribute filter. Filters in functions are used to introduce a conditional requirement. For example, add up the length of all the lines where the Phases Current attribute includes the values ABC.


Trace configurations that use apportioned network attributes with functions (Add, Average, Count, Max, Min, and Subtract) return apportionable results based on edge elements. For example, using a function within a connected trace to count the shape length attribute returns a count based on the individual edge features and not the entire line. See Apportionable network attributes for more details.

Control what is returned

To control what is returned in the results of a trace, Output filters are used. An output filter screens every feature encountered during a trace to see if it meets the criteria specified in the filter. For example, a trace to return all upstream protective devices from a starting point in an electrical network.

There are two types of Output filters available on the Trace tool: Output Asset Types and Output Conditions.

An Output Asset Types filter is used to include only the asset types specified in the trace results. For example, a pole report for an electric network would include an output asset type filter only include poles in the results.

The Output Conditions filter supports network categories and network attributes. For example, an output condition using a specific network category name to return all isolating devices in a gas network. This operation returns all features with the Isolating network category assigned. A trace on a gas network could return: emergency valves, bypass valves, system valves, or short stops. Features without this network category are still traced, but they are not included in the results.

Network attributes live in the network topology and are associated with a field in one or more feature classes. In an output condition, the name of the network attribute, an operator, and a value valid for the network attribute are specified. In the case of a leak in a water network, a network attribute is input to return pinchable pipes. In this case, the Line class has a field called Pinchable. This field is associated with a network attribute called Pinchable. The Output Conditions parameter is configured to look for feature classes with the Pinchable network attribute where the value is equal to True. The results of the trace include features from a feature class with this field and the value True, as well as features from classes without the Pinchable field.

Given the behavior of network attributes in output conditions, to return pinchable pipes, it is necessary to use an Output Asset Type filter. For example, in the Esri-provided Gas utility network, from the PipelineLine class, in the Distribution Pipe asset group, the Plastic PE asset type would be specified. With the two filters, IsPinchable = True AND AssetType = Plastic PE, the trace results will only include pinchable plastic PE pipes.

Multiple Output Conditions values can be implemented using the Combine Using parameter. Both types of outputs can be used and more than one output type can be set up. Combining output types allows you to do such things as return all 12-inch pinchable Plastic PE pipes that exceed 80 PSI.

Work with bitwise operators

The trace configuration uses a common set of operators that are used to define barriers, filters, functions, and outputs for the trace results. Standard operators are used to evaluate feature attributes to see if they are equal, less than, or greater than a value.

Standard operators used in the trace configuration: Is equal to, Does not equal, Is greater than, Is greater than or equal to, Is less than, and Is less than or equal to.

Bitwise operators incorporate the use of bits in their logic by analyzing a value's bitset. These operators provide power and flexibility and are more commonly used in advanced applications of tracing. The tracing framework can work with these bits independent of the meaning that the user defines.

Bitwise operators used in the trace configuration:

  • Includes the values—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • Does not include the values—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • Includes any—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • Does not include any—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

When modeling phase in an electric utility network, the dataset can be configured to use bitsets. A set of values are configured for each permissible phase combination and the bit representation (each bit has a meaning). A coded value domain is configured with the acceptable phase values and assigned to attributes that use phase. For use in the trace configuration, a network attribute is configured on the phase field.

The table below outlines how phase can be modeled using bitsets. The bit value is stored as the code, and the phase value is used for the description in the coded value domain. The binary column in the table shows the binary representation of each bitset. Bitwise operators deconstruct an attribute to assess each of the pieces to see if it satisfies the operational logic. If a network attribute is AC (101) and the value being compared is BC (011); the Includes the values operator would not evaluate to true because the middle bit (B) is not in AC, whereas using the Includes any operator would evaluate to true since bit C is in both AC and BC.

BinaryBit valuePhase value






















Phase coded value domain

For example: To find all features in the subnetwork with a phases current value that includes A, a subnetwork trace on an electric distribution domain network is performed. The starting point is set on a service point with a phases current value of A and the following trace configuration is specified as a filter barrier. The filter barrier is configured to exclude features that do not include phase A from the trace result. To ensure that the barrier features are not included in the trace results, the trace configuration option Include Barrier Features is set to false. The trace results include subnetwork features that have a phases current value of A or a phases current value that includes A.

Filter Barriers
Name: Phases Current
Operator: Does not include any (Bitwise AND equals False)
Type: Specific value
Value: 4 (code for A)

Perform calculations on traced network features

Utility networks provide an advanced function that allows you to manage values that change over distance. The change is measurable and therefore can be recalculated. For example, consider pressure in a pipe network: as the water flows away from the pump, pressure decreases due to friction. To model this behavior, propagators are used when a subnetwork is updated, exported, or traced. Propagators should only be configured and altered by the utility network administrator.

A substitution is a type of network attribute. It is a value used to calculate the propagated value for features with the attribute substitution category assigned to its asset type. The resulting substitution value is then used to calculate the value for next connected feature. To use attribute substitution, propagation must be configured.

For more information, see Attribute propagation and Attribute substitution.