In ArcGIS, utility networks offer a framework for modeling utility systems, such as electric, gas, water, storm water, wastewater, and telecommunications systems. Each utility network shows how features are connected and how dynamic devices are configured. This topic describes how to build apps that can trace the flow of resources, such as gas, water, and electricity, through its network. For an overview of utility networks, see ArcGIS Pro's help topic What is a utility network?.
You can explore how a network is affected by real-world events such as storms, outages, or equipment failure, by asking questions such as:
How is my utility's network connected?
What path does electricity/gas/water take in order to reach a specific neighborhood?
If a device is disabled, what section of the network will be out of power?
To help answer these questions, use the following utility trace types:
Upstream—In a source-based network (gas or electric), an upstream trace is against the flow and toward the source, such as a circuit breaker or generator (subnetwork controller). In a sink-based network (sewer or storm water), an upstream trace is against the flow and away from the sink such as a sewage treatment (subnetwork controller). For more information, see ArcGIS Pro's help discussion on upstream traces.
Downstream—In a source-based network, a downstream trace is with the flow and away from the source, such as a circuit breaker or generator. In a sink-based network, a downstream trace is with the flow and toward the sink. For more information, see ArcGIS Pro's help discussion on downstream traces.
Subnetwork—A trace that discovers all features participating in a subnetwork. This trace type is useful for validating whether subnetworks, such as circuits or zones, are defined or edited appropriately. The trace begins at one or more starting points and spans outward along connected features to find subnetwork controllers that are traversable. A subnetwork trace stops when it encounters a barrier, when it encounters a feature that is not traversable, or when there are no more connected features. For more information see ArcGIS Pro's help discussion on subnetwork trace.
Isolation—A trace used to determine the minimum set of operable assets (point and line features) required to stop a network's resource from traveling/flowing, effectively isolating an area of the network. For instance, when a leak occurs on a water network, particular valves must be closed to eliminate water flow at the leak location. This prevents damage and allows field crews to safely start the repair process. For more information, see ArcGIS Pro's help discussion on locating isolating features.
Connected—A trace that begins at one or more starting points and spans outward radially along connected features. A trace stops when a barrier is encountered or there are no more connected features. Can be used for validating newly edited features to ensure they are connected as expected. For more information, see ArcGIS Pro's help discussions on connectivity and finding connected features.
Shortest path—Identify the shortest path between two starting points using a shortest path trace. The shortest path is calculated using a numeric network attribute such as shape length. Cost- or distance-based paths can both be achieved using this type of trace. For more information, see Discover the shortest path tool in the ArcGIS Pro help.
Loops—Loops are areas of the network where flow direction is ambiguous. Within a loop, resources can flow in either direction. Loops are expected with mesh networks but usually indicate error conditions in radial networks. You can also discover loops using a shortest path trace. For more information, see Discover network loops in the ArcGIS Pro help.
Utility networks are implemented in service-based geodatabases as network controller datasets. These datasets contain a network's service feature tables along with the network's domains, sources, tiers, assets, terminals, rules and associations. This utility network is accessible via these service feature tables stored in a single feature service.
You can display and share a complete utility network with a user via a web map if the map includes one feature layer for every network source.
To display and share the utility network, create a utility network object from a feature service URL and a web map that contains all the layers that participate in the utility network.
The feature service provides access to the topological network in the utility network. So, you could provide a map that contains just a subset of the feature layers, for a specific workflow. Any tracing would be performed using the full topological network provided by the feature service. If you need to add additional utility network layers you can create them from the individual network sources, as required. You can also access a utility network and run a trace completely without a map. Just provide the feature service URL when you create the utility network. If needed, you can create a completely new map by creating feature layers from the network sources.
Utility Network version 2 and later is supported. This is provided from ArcGIS Pro 2.2 and later. For details see utility network upgrade history.
Loading the utility network loads the entire utility network schema (information about the datasets that participate in the network). Once loaded, your app can navigate this network schema to discover the Domain networks it contains and any further details about the network.
Trace parameters define how the trace analysis proceeds across the utility network. These are the essential trace parameters:
Trace type
Start and barrier locations
Trace configuration
Result types
Trace type
The trace types described above (upstream, downstream, and so on) are supported.
Use the utility trace type to create the parameters
Create a set of UtilityTraceParameters by providing a UtilityTraceType of upstream, along with a collection of starting locations (if known at this stage).
Each trace requires one or more locations from which to initiate the trace. Optionally, you can also include barrier locations. Starting and barrier locations are defined using instances of UtilityElement which are added to the trace configuration's starting locations and barriers collection respectively.
You can create a starting location using steps like the following:
If the feature represents a line, you can optionally specify a location along the line to use as the starting location. This value is expressed as a percentage of the length of the line, beginning from the line's from point.
Set the fractionAlongEdge value to define the location of the point along the line.
If you need to add a barrier, complete step 1 above then add the utility element representing a barrier to the utility trace parameters’ barriers.
Result type
The following types of results can be returned when you execute the trace:
Elements—Element results provide the utility elements that are found by a trace. Use these results when you need access to individual utility elements, their corresponding features, and their attributes. This is the default type of trace results.
Geometry—Geometry results contains multipart geometries that represent the union of the geometry for all elements returned. These results are best for displaying the trace result on a map.
Functions—A function is a trace configuration that allows you to run calculations on network attributes associated with traced features. A function output is returned for every function defined in the configuration.
If you don't want to use the trace configuration as created in ArcGIS Pro, you can either modify it or you can override it with settings. A trace configuration is set on the UtilityTraceParameters.
These settings allow you to do things like:
Stop the trace at protective devices if they are open. For example, the flow of electricity in a network will be stopped if a fuse is open.
Control the types of features traced. For example, trace only pipes with a diameter greater than six inches.
Filter the types of features returned as trace results. For example, only return elements identified by the trace that represent wooden poles.
Define functions to run calculations on network attributes associated with traced features. For example, the sum of the length of all the wire traced. Several functions can be specified for a trace.
Request different types of trace results. These can include geometry (for easy display on the map), network elements (if you need more information about individual features), and output functions (for calculating values based on network attributes).
Each trace configuration manages basic properties such as:
Include barriers in trace results
Include containers in trace results
Include content in trace results
Include structures in trace results
Add filter barriers, which are required for isolation traces
Ignore barriers if they are the starting points
Domain network
Source tier
For more advanced properties, such as traversability, output filters, propagators, and target tiers, see the advanced trace configuration section.
When a utility network administrator creates a new tier in ArcGIS Pro, a subnetwork trace configuration is created and populated as described in Configure a trace.
You can choose if your app uses the trace configuration as defined by an administrator, a modified version of the configuration, or your own trace configuration.
Use a trace configuration defined in a utility network tier
To obtain the trace configuration from a utility network tier, you need to know the name of the Domain network and the tier.
Obtain the utility network definition from the utility network.
Get the domain network from the utility network definition.
Obtain the tier from the domain network.
Pass the tier's trace configuration to the utility trace parameters.
A named trace configuration is a set of tracing parameters that is built with ArcGIS Pro, stored on ArcGIS Enterprise, and published with a web map. Named trace configurations allow you to create utility applications that are independent of individual customer data models. Using this workflow, tracing capabilities can be configured rather than customized.
Execute the trace
Run the trace by calling the trace method on the utility network object. Use the utility trace parameters defined in the previous section. Depending on the trace parameters, results may be returned as one or more trace result types: utility element, output function, or geometry. If not specified, utility element trace results are returned by default.
If the trace fails you can examine why. For example, failure could be due to dirty areas in the network topology.
Examine the results
The trace results can contain element, geometry and/or function type results as configured in the trace parameters. The default trace result type is UtilityElementTraceResult.
If you need fine-grained access to the results, such as the ability to work with individual utility elements from the trace, you need to obtain the corresponding features for these elements from the utility element results.
Filter the utility element trace results to find those that are part of the map, and group them by network source name.
For every group (network source with utility elements), make sure there is a layer in the map for the features. Next find the features corresponding to the utility elements.