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.
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.
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 that defines the location of the point along the line.
The following example uses the GeometryEngine to get the fraction of a tap location 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’
list of barriers, which is returned by getBarriers().
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
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.
Modify any of these properties as required.
The following example illustrates using the preceding steps to get the configuration for a tier in the network.