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:
- Load a utility network from a service
- Perform a connected trace (one of several trace types) on the utility network
- Get the features identified in the trace
ArcGIS utility networks provide 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 serves as the system of record for the assets of a utility and provides information about the past, present, and planned future state of a utility network system. It allows you to model significant elements of your system and enables 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 the utility network
A 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.
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.
Note:Web maps used with a 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.
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.
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.
Load the Utility Network
Utility network 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.
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.
Setup the start locations and barriers. 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.
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.
Perform this trace as follows:
- Create the utility trace parameters with the trace type connected and an empty set of start locations.
- Get the network source for a feature that defines the start of the trace.
- Get the ArcGIS feature table for the feature.
- Derive the network source represented by the ArcGIS feature table.
- Create a utility element to represent the start feature. You must adopt different code patterns depending on whether the utility network source is a junction or an edge. If the utility network source is a junction find the available terminals for that feature using the utility network definition. If more than one terminal is found, select a terminal to use. Create the utility element from the feature and the terminal.
- When an edge feature is used create the utility element from the feature. Set the fractionAlongEdge value to represent the location of the starting point or barrier along that edge.
- Add the utility element to the utility trace parameters’ startingLocations or barriers collections.
- Repeat step 3 through 5 for barriers.
- Run the trace by calling the trace method on the utility network object using the utility trace parameters containing the start locations and the barriers. This will return the utility element trace result.
Get the corresponding features from trace results
Trace results are returned as utility elements. You can retrieve the corresponding features for display or for further processing and analysis. This is done using a method on the utility network object used for the trace.
- 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.
- 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, and 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.
Note: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.