Skip To Content ArcGIS for Developers Sign In Dashboard

Analyze a utility network

You can analyze the content of an ArcGIS utility network. The current version of ArcGIS Runtime gives you access to a subset of utility network capabilities for use in your ArcGIS Runtime app. Those capabilities are:

An example of a utility network modeling real-world utility assets.

A ArcGIS utility network object provides a comprehensive functional framework in ArcGIS for modeling utility systems such as electric, gas, water, storm water, wastewater, and telecommunications. It is designed to model all of the components that make up your system—such as wires, pipes, valves, zones, devices, and circuits—and allows you to build real-world behavior into the features you model.

An ArcGIS utility network supports a utility's requirements for delivering resources to customers safely, reliably, and economically. It can serve as the system of record for the assets of a utility and provide information about the past, present, and planned future state of a utility network system. ArcGIS utility networks provide many benefits, including modeling significant components of your system and enabling advanced analysis of your network.

The ability to browse and analyze network data are provided by a service-based architecture that is callable from any device or app that supports web services. ArcGIS Runtime apps interact with services to access and analyze utility networks.

If you are not familiar with ArcGIS utility networks, refer to the topic What is a utility network? in the ArcGIS Pro documentation.

Load a utility network

An ArcGIS utility network object is instantiated by providing a URL to a feature service that contains a utility network. The current version of ArcGIS Runtime gives you access to the default version of the utility network.

A utility network object follows the loadable pattern for asynchronous resources. Loading the utility network loads the entire utility network schema (information about the datasets that participate in the network). Your app can navigate this schema to discover details of the utility network and all the domain networks it contains.

Some constructors take a map containing feature layers that display datasets from the utility network. Any other utility network tables not backing layers in the map will be created by the utility network. This gives you the flexibility to load the same utility network in several ways and to also automatically load certain map or network objects. The method you chose to access a utility network will depend what you need to do with your app.

Web maps used with the utility network should contain only one layer for each feature class in the underlying database.

Load a utility network using a map with layers for all network sources

This technique gives users of your app access to all network sources through the map. The app uses the utility network constructor that references a map containing a layer for each service feature table in the utility network. Such a map is often available as a web map on the same service as the utility network, and provides a complete view of the utility network.

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

Each service feature table object representing a network source will have an associated feature layer. All the utility network sources are therefore available through the feature layers, allowing your app to easily access features needed to display a trace result or to perform further analysis.

Load a utility network using a map with layers for some network sources

You can load a utility network by referencing a map that contains layers for some (but not all) of the service feature tables in the utility network. This creates a feature table for each network source in the utility network. Where possible, the feature service tables are matched with a corresponding map layer. This is useful if you have a map containing layers for only a subset of the network sources, such as a simplified map designed for a specific audience. If needed, your app can create new feature layers for service feature tables that aren't displayed as layers in the map.

Diagram of objects loaded when loading a utility network using a map with layers for some (but not all) network sources.

Load a utility network without a map

You can load a utility network object without referencing a map. After loading, your app can access the network as sources service feature tables and create layers as needed. This provides the ability to create a completely new map on the fly.

Diagram of objects loaded when you load a utility network without a map.

Perform a connected trace

You can perform a connected trace on a utility network. One of several types of utility network traces, a connected trace analyzes a utility network to discover elements that are connected to specified locations.

A connected trace begins at one or more starting points and spans outward radially. The trace traverses connected utility elements until it cannot continue either because it encounters a barrier or reaches the end of a path. Upon completion, trace results are returned. You can use the list of utility elements in the results to get corresponding features in the utility network for display and further analysis.

The start of a trace is defined using one or more starting points along the network (coincident with network features). Any network junction or a point along an edge can be used as a starting point. Barriers are locations on the network that prevent tracing to continue.

  1. Create map view object and subscribe to its "geoview tapped" event.
  2. Create a map object that contains feature layer objects corresponding to part of the utility network that you want to visualize in your map.
  3. Create and load a utility network object.
  4. Add graphics overlay objects with symbology that distinguishes starting points from barriers.
  5. Identify features on the map and add a graphic object that represents its intended purpose (starting point or barrier) at the location of each identified feature.
  6. When a junction feature is identified, find available terminals using the utility network definition. If more than one terminal is found, select a terminal to use.
  7. Create a utility element object from the identified feature.
  8. When edge feature is identified, compute the fraction along the edge for the point used to identify the edge. The starting point or barrier will be placed at this location.
  9. Run the trace by calling the trace method on the utility network object using the specified parameters.

Get the corresponding features from trace results

Trace results are returned as utility elements. You can retrieve the corresponding features for these results for display or for further processing and analysis. This is done using a method on the utility network object used for the trace.

  1. Filter the results to find those that are part of the map, and group them by network source name. Then for every network source with utility elements, find the features corresponding to those utility elements using the get features for elements method on the utility network object.
  2. After finding the features corresponding to the trace results, you can do more with them such as selecting them in your map for additional processing.

Utility network components

The utility network provides a rich information model accessible through a set of read-only schema information classes. Utility networks are comprised of the following primary components:

  • Network definition - Each utility network contains a definition, which is metadata about a utility network feature service. Domain networks, utility network categories, network sources are among the components referred to in the network definition.
  • Domain networks - Domain networks organize features in a utility network based on what utility service they provide, such as natural gas, water, electricity, or structural elements such as poles or conduits. Each utility network will have a single domain network for the structure network and one or more domain networks corresponding to the various utility services they provide.
    Direct API access to the domain network class is planned for a future release.
  • Network sources - A network source is a feature table whose features comprise one of a utility network's datasets. A utility network has multiple network sources containing related information. Some network sources contain devices appropriate for each domain network. For example, one network source for an electric utility network is a feature table named "Electric Distribution Device" representing electric devices like switches and transformers. Also, all utility networks have network sources representing physical structures such as "Electric Support Pole" or "Electric Substation Boundary".
  • Asset groups and asset types - An asset group is the first-level categorization of a network source. Each asset group has a collection of asset types that provide the second-level categorization. An example for an electric utility is the asset group High Voltage Insulator which contains the asset types Single, Single String Running Angle, Double Suspension, and Triple String Running Angle.
  • Utility elements - A utility element is an entity in the utility network that corresponds to a feature in a network source. Network elements are used across the utility network API. They are used to specify starting points and barriers for tracing. They are also returned in trace results. A network elements may contain terminals when the network element corresponds to junction feature that has terminals.
  • Terminals - A terminal is used to model devices in the field have defined locations or ports from which resources, such as electricity and water, flow in and out. A utility network can model devices with terminals to a high degree of realism.
  • Network attributes - Network attributes are network source fields that have been copied into the utility network index for faster retrieval.