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 establish traversability, distinguish what features or objects should be returned, and set up calculations to be performed. ModelBuilder can be used to save complex configurations and reduce the number of parameters presented on the model tool interface. Named trace configurations can be used to create and store complex traces that can be shared across an organization. This helps you and others rerun advanced traces with just one click.
Setting subnetwork trace configurations in the subnetwork definition allow the Trace tool to be autopopulated 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 in 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 autopopulated 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 and objects traced (pipe diameter greater than 6 inches), choose what types of network 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.
Run a trace asynchronously
Starting with ArcGIS Pro 2.9 and ArcGIS Enterprise 10.9.1, the Run in asynchronous mode on the server parameter provides the option to process trace operations asynchronously using the UtilityNetworkTools geoprocessing service. This option is only available when the utility network is in an enterprise geodatabase. Trace operations process synchronously by default.
| Configuration option | Description |
|---|---|
Run in asynchronous mode on the server |
|
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
- 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 in the Trace tool allows you to configure the network 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 is returned in the results of a trace.
Include Containers
Include containers in the results of a trace. Any containers for the content features and objects 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 option | Description |
|---|---|
Include Containers |
|
Include up to First Spatial Container
Specifies whether to limit the containers returned to include only those encountered up to, and including, the first spatial container for each network element in the trace results. If no spatial containers are encountered but nonspatial containers are present for a given network element, all nonspatial containers will be included in results. This parameter is only available when Include Containers is enabled.
| Configuration option | Description |
|---|---|
Include up to First Spatial Container |
|
Include Content
Include content features and objects in the results of a trace. This encompasses content from containers that are included in the trace results. To clarify between the different types of containers, use an Output filter to filter your results.
| Configuration option | Description |
|---|---|
Include Content |
|
Include Structures
Include structures in the results of a trace. This is helpful for such tasks as reporting structural assets.
| Configuration option | Description |
|---|---|
Include Structures |
|
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.
Note:
The selection set returned by a trace may display unexpected results when barriers are placed on edge features with midspan connectivity and the Include Barrier Features option is unchecked. If any part of the feature is returned by the trace, the entire feature is selected and displayed in the trace result.
| Configuration option | Description |
|---|---|
Include Barrier Features |
Note: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. |
Note:
The Include Barrier Features configuration option does not apply to 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 option | Description |
|---|---|
Ignore Barriers At Starting Points |
|
Ensure network consistency
A consistent area of a network is one that does not have any dirty areas. Validating the network topology 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 Subnetwork life-cycle.
The Validate Consistency option in the Trace tool allows you to ensure the trace results are consistent with the network topology. When Validate Consistency is set to true, the trace operation fails if any dirty areas intersect the trace path. When this occurs, the tool returns an error that includes the class name and global ID of any features or objects in the trace path that are found to be dirty, as shown in the example below:
ERROR 002041: One or more dirty areas were discovered.
[[ElectricDistributionLine: {C0060506-AG17-4B64-B2E0-9162BE613C05}]]
Failed to execute (Trace).
The following scenarios do not cause an error to be raised about inconsistencies in the trace results:
- Dirty areas from newly created features.
- Dirty areas from associated containers or structures when the Include Containers or Include Structures options are not enabled.
To clean and remove dirty areas, validate the network topology.
Executing a trace without 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 trace fails and an error is returned to let you know a dirty area was encountered. 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 option | Description |
|---|---|
Validate Consistency | When this option is checked, the trace fails, and the tool returns an error if any dirty areas intersect the trace path. If this option is not checked, dirty areas are ignored. This option is checked by default. |
Ensure locatability of nonspatial objects
Associations are used to determine the location of, and visually represent nonspatial junction and edge objects on a map. If this association is deleted, this can create a scenario in which the junction or edge object is unlocatable. The Validate Locatability option in the Trace and Set Subnetwork Definition tools provides the ability to identify objects without the necessary containment, attachment, or connectivity association in their association hierarchy of the traversed objects.
When Validate Locatability is set to true, the trace operation fails and an error is displayed when unlocatable objects are discovered in the path of a trace. When this occurs, the tool returns an error that includes the class name and global ID of the unlocatable objects in the trace path, as shown in the example below:
ERROR 003326: Unlocatable objects discovered.
[[GasDistributionJunctionObject: {4F860903-PK17-5c15-Y2W0-3512BP436C00}]]
Failed to execute (Trace).
The Modify Associations pane can be used to create the necessary associations for the object to be considered locatable.
To learn more, see Locatability.
| Configuration option | Description |
|---|---|
Validate Locatability | When this option is checked, the trace fails, and the tool returns an error if any unlocatable objects are discovered. If this option is not checked, a check is not performed for unlocatable objects. This option is unchecked by default. |
Control what is traced
Barriers are used during a trace to denote a stopping location; network features beyond that location are not traced. The results of a trace do not include network features past a barrier but can optionally include the barrier itself. Other parameters, such as Allow Indeterminate Flow and those found within the Traversability section, help to define what controls the traversability of network paths.
Allow Indeterminate Flow
When performing an upstream, downstream, or isolation trace, flow direction for the subnetwork is determined first, then features and objects upstream or downstream to the starting points are returned. In some cases, a specific flow direction cannot be determined, such as scenarios with loops. In cases such as this, the flow is known as indeterminate. By default, features and objects with indeterminate flow are included in the trace results and the Allow Indeterminate Flow parameter is checked. If this option is unchecked, these network features with indeterminate flow stop traversability and are not included in the trace results. This parameter is only honored when running an upstream, downstream, or isolation trace.
| Configuration option | Description |
|---|---|
Allow Indeterminate Flow |
|
Traversability
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 does not stop at the edge due to the traversability scope.
To learn more, see Barriers.
Set up functions
A function is a trace configuration property that allows you to run calculations on network attributes associated with traced network 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 can be added to each function; when specified, the function will only be applied to the network 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 A, B, and C.
Note:
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 and result types are used.
Output filters
An output filter screens every network feature encountered during a trace to determine whether it meets the criteria specified in the filter. For example, a trace returns all upstream protective devices from a starting point in an electrical network.
There are two types of Output filters available in 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 and only include poles in the results.
The Output Conditions filter supports network categories and network attributes. For example, an output condition uses a specific network category name to return all isolating devices in a gas network. This operation returns all features and objects with the Isolating network category assigned. A trace on a gas network could return emergency valves, bypass valves, system valves, or short stops. Features and objects without this network category are still traced, but they are not included in the results.
Network attributes are stored in the network topology and are associated with a field in one or more network classes. In an output condition, the name of the network attribute, an operator, and a value that is 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 named Pinchable. This field is associated with a network attribute named Pinchable. The Output Conditions parameter is configured to look for classes with the Pinchable network attribute where the value is equal to True. The results of the trace include features and objects from a class with this field and the value True, as well as network 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.
Result Types
The optional Result Types parameter allows you to control the type of results returned by the trace.
The Aggregated Geometry, Selection, Connectivity, Elements, Features, and Containment and attachment associations result types can be specified independently or concurrently to generate output geometries, create a selection set for a trace operation, return a connectivity graph of network features connected through either geometric coincidence or connectivity associations, return feature-based information, return feature-based information with geometry, network attribute, and field information, or return features that are associated through containment and structural attachment associations to a .json file, respectively.
| Parameter | Options |
|---|---|
Result Types |
Note:When working with enterprise geodatabases, the following requirements must be met:
|
The Aggregated Geometry option enables trace results to be returned as multipart geometry in a feature class. This honors the location of starting points and barriers placed midspan on edge features to return partial feature results.
Review the images below to compare the differences between the selection and aggregated geometry result type options in a downstream trace. The network below contains five line features (represented as f1, f2, f3, f4, and f5) that are composed of nine edge elements (represented as e1, e2, e3, and so on).
In this example, which includes barrier features, the selection result returns seven point features and five line features consisting of nine edge elements (f1::e1,e2,e3, f2::e1,e2, and f5::e1,e2). The aggregated geometry result returns the same features but excludes edge elements f1::e1,e2 and f5::e2.
When a barrier is placed along an edge with the Include Barrier Features configuration option checked, the trace will stop at the barrier feature and return partial feature geometry for the edge in the trace results. If the Include Barrier Features option is unchecked, the trace will stop at the prior line end or junction encountered with midspan connectivity.
The examples below show the difference in trace results when using the Include Barrier Features option to include or exclude barrier features in the trace results. In this example, both the starting point and barrier are placed along an edge. With this option enabled, the selection result returns six point features and five line features consisting of nine edge elements (f1::e1,e2,e3, f2::e1,e2, f3::e1, f4::e1, and f5::e1,e2). The aggregated geometry result will return the same five line features but excludes edge elements f1::e1 and f5::e2. Partial geometry is returned for the edge element f1::e2. The selection result would not change if you were to exclude barrier features with Include Barrier Features unchecked; however, the aggregated geometry results would additionally exclude f1::e2.
When the Aggregated Geometry option is selected for the result type, five additional parameters are provided to define the trace output behavior:
- Clear All Previous Trace Results
- Trace Name
- Aggregated Points
- Aggregated Lines
- Aggregated Polygons
The Clear All Previous Trace Results check box provides an option to truncate or append to the contents of the feature classes chosen to store aggregated geometry.
| Parameter | Options |
|---|---|
Clear All Previous Trace Results |
|
The optional Trace Name parameter enables the creation of a string identifier for the trace operation to assist with identification of trace results. When used with the Clear All Previous Trace Results parameter check box unchecked, this parameter allows you to run multiple trace operations and compare the results in the output aggregated geometry feature classes.
The Aggregated Points, Aggregated Lines, and Aggregated Polygons parameters enable you to specify feature classes for storage of the aggregated result geometry. By default, each parameter is populated with a system-generated feature class stored in the project's default geodatabase:
- Trace_Results_Aggregated_Lines—A line feature class
- Trace_Results_Aggregated_Points—A multipoint feature class
- Trace_Results_Aggregated_Polygons—A polygon feature class
These feature classes are created automatically if they do not exist. Existing feature classes can also be used to store aggregated geometry. If a feature class other than the default is used, it must contain a String field named TRACENAME and match the geometry type of the output.
The generation of output geometry with partial feature results provides a more accurate representation of the trace and enables comparison and reuse of trace results for other tasks.
Note:
Disabling the geoprocessing option Allow geoprocessing tools to overwrite existing datasets can cause tool validation issues if the output feature classes for aggregated geometry result types exist in the default geodatabase for the project. This can be addressed by enabling the geoprocessing option or by renaming the aggregated point, line, and polygon feature classes in the default geodatabase of the project.
When the Selection option is selected for the result type, an additional Selection Type parameter is provided to define how the selection will be applied and what action to perform if a selection already exists.
| Parameter | Options |
|---|---|
Selection Type |
|
The Connectivity result types option returns trace results as a connectivity graph of network features connected through geometric coincidence or connectivity associations. When this option is selected, connectivity is output to a .json file in the specified location that can be parsed and imported into other systems to build your own graph representation of the data. Connectivity information is only returned for network features returned by the trace. The output .json file contains the following information for all traversed network features under connctivity:
- fromNetworkSourceId
- fromGlobalId
- fromObjectId
- fromTerminalId
- fromGeometry
- viaNetworkSourceId
- viaGlobalId
- viaObjectId
- viaPositionFrom
- viaPositionTo
- viaGeometry
- toNetworkSourceId
- toGlobalId
- toObjectId
- toTerminalId
- toGeometry
The Elements result types option returns trace results as feature-based information in a specified output .json file that can be used as an input to perform additional analysis. The output .json file contains the following information for all traversed network features under elements:
- networkSourceId
- globalId
- objectId
- assetGroupCode
- assetTypeCode
Additional information is returned for point features and junction objects:
- terminalId
Additional information is returned for line features and edge objects:
- positionFrom
- positionTo
The Features result types option returns trace results as feature-based information in a specified output .json file. Similar to the Elements option, this option enables you to include additional information in the output for use with other applications, such as feature geometry, information about network attributes, and values from attribute fields. The output .json file contains the same information returned by Elements above for all traversed network features under featureElements along with the following additional information:
Information returned with Include geometry (not present for junction and edge objects):
- geometry
Information returned with Include domain descriptions:
- networkSourceName
- assetGroupName
- assetTypeName
- networkAttributeDescriptions(when Result Network Attributes are specified)
Additional information is returned for point features and junction objects:
- terminalName
Information returned with Result Network Attributes:
- networkAttributeValues
Information returned with Result Fields:
- fieldValues
The Containment and attachment associations result types option returns association information for the traversed network features that are associated through containment and structural attachment associations in a specified output .json file. The output .json file contains the following information for all traversed network features under associations:
- associationType
- fromNetworkSourceID
- fromGlobalId
- fromTerminalId
- toNetworkSourceID
- toGlobalId
- toTerminalId
Information returned with Include domain descriptions:
- fromNetworkSourceName
- fromTerminalName
- toNetworkSourceName
- toTerminalName
Additional parameters are enabled when certain Result Types options are selected:
- When the Connectivity, Elements, Features, or Containment and attachment associations option is selected, an additional Output JSON parameter is provided to give the location of the output .json file.
- When the Features or Containment and attachment associations options are selected, an additional Include domain descriptions parameter is provided to include domain descriptions for the traversed network features.
- When the Features option is selected, the Include geometry, Result Network Attributes, and Result Fields parameters are additionally provided to output feature geometry, network attribute information, and field level information for the traversed network features.
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 determine whether they are equal, less than, or greater than a value.
Standard operators used in the trace configuration are 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 include the following:
- 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 is 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 in 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 piece to determine whether 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.
| Binary | Bit value | Phase value |
|---|---|---|
001 | 1 | C |
010 | 2 | B |
100 | 4 | A |
011 | 3 | BC |
101 | 5 | AC |
110 | 6 | AB |
111 | 7 | ABC |
For example, to find all network 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 and objects that do not include phase A from the trace result. To ensure that the barrier features are not included in the trace results, the Include Barrier Features trace configuration option 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 functionality known as attribute propagation that is used when a subnetwork is updated or traced.
Attribute substitution is handled by configuring a network attribute for a database field. Substitution is a type of network attribute whose value is 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 the next connected feature. To use attribute substitution, attribute propagation must be configured.
For more information, see Attribute propagation and Attribute substitution.
Load named trace configurations
Named trace configurations allow complex traces to be created for sharing and reuse. The Trace tool enables you to load an existing named trace configuration to define the properties for a trace. This simplifies the user experience associated with tracing and provides consistency through the reuse of common traces in an organization.
| Parameter | Options |
|---|---|
Use Trace Configuration |
|
A Trace Configuration Name parameter is provided to specify the name of the trace configuration that will be used to define the properties of the trace. This parameter is only available when Use Trace Configuration is enabled.