Trace a utility network

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.

To trace a utility network you need to:

Use ArcGIS Pro to create a utility network.
Access the utility network in your app.
Define the trace parameters:
a. Decide which trace type to perform.
b. Define the starting and barrier locations.
c. Specify the trace configuration.
Run the trace.
Examine the results.

Access a utility network

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.

Diagram of objects loaded when loading a utility network with a map with layers for all network sources.

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.

Load the utility network

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.

Use dark colors for code blocksCopy
        utilityNetwork.load().getOrElse { error ->
            return showError("Error loading utility network: ${error.message}")
        }
        Log.i(localClassName, "The utility network schema version is ${utilityNetwork.definition?.schemaVersion}")

Define the trace parameters

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

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).

Use dark colors for code blocksCopy
        // build trace parameters
        val traceParameters = UtilityTraceParameters(UtilityTraceType.Upstream, utilityElementStartingLocations)

Start and barrier locations

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:

Create a UtilityElement using a feature.

Use dark colors for code blocksCopy
        // create a utility element for the feature.
        val utilityElement: UtilityElement = utilityNetwork.createElementOrNull(arcGISFeature)
            ?: return@onSuccess showError("Null utility element.")

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.

Use dark colors for code blocksCopy
        utilityElement.fractionAlongEdge = GeometryEngine.fractionAlong(
            line = GeometryEngine.createWithZ(geometry, null) as Polyline,
            point = location,
            tolerance = -1.0
        )

If the feature represents a device with terminals, you must specify which terminal you want to use as the starting point.

Use dark colors for code blocksCopy
        // get the terminals for the feature.
        utilityElement.apply {
            terminal = assetType.terminalConfiguration?.terminals?.first()
        }

Add the utility element to the utility trace parameters’ list of starting locations, which is returned by getStartingLocations().

Use dark colors for code blocksCopy
        traceParameters.startingLocations.add(utilityElement)

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().

Trace 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.
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.

Use dark colors for code blocks

Copy

ArcGIS Maps SDK for Kotlin