ArcGIS Utility Networks Skill

ArcGIS Utility Networks

Use this skill for utility networks: tracing, associations, topology validation, and network analysis for connected infrastructure.

Import Patterns

ESM (npm)

// Core network class
import UtilityNetwork from "@arcgis/core/networks/UtilityNetwork.js";

// Widgets
import UtilityNetworkTrace from "@arcgis/core/widgets/UtilityNetworkTrace.js";
import UtilityNetworkAssociations from "@arcgis/core/widgets/UtilityNetworkAssociations.js";
import UtilityNetworkValidateTopology from "@arcgis/core/widgets/UtilityNetworkValidateTopology.js";

// Support
import TileInfo from "@arcgis/core/layers/support/TileInfo.js";
import WebMap from "@arcgis/core/WebMap.js";
import MapView from "@arcgis/core/views/MapView.js";
import esriConfig from "@arcgis/core/config.js";

CDN (dynamic import)

const UtilityNetwork = await $arcgis.import("@arcgis/core/networks/UtilityNetwork.js");
const UtilityNetworkTrace = await $arcgis.import("@arcgis/core/widgets/UtilityNetworkTrace.js");
const UtilityNetworkAssociations = await $arcgis.import("@arcgis/core/widgets/UtilityNetworkAssociations.js");

Key Concepts

Utility networks model connected infrastructure (electric, gas, water, telecom). Key concepts:

Network tracing — Follow connectivity through the network
Associations — Connectivity, containment, and structural attachment relationships
Subnetworks — Isolated portions of the network
Topology — Network connectivity validation

Map Components Approach

Utility Network Trace Component

<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
  <arcgis-utility-network-trace slot="top-right"></arcgis-utility-network-trace>
</arcgis-map>

Utility Network Associations Component

<arcgis-map item-id="e53b1054b29f4579baf878dcf2effe7a">
  <arcgis-utility-network-associations slot="top-right"></arcgis-utility-network-associations>
</arcgis-map>

Utility Network Validate Topology Component

<arcgis-map item-id="YOUR_WEBMAP_ID">
  <arcgis-utility-network-validate-topology slot="top-right"></arcgis-utility-network-validate-topology>
</arcgis-map>

Utility Network Trace Analysis Component

<arcgis-map item-id="YOUR_WEBMAP_ID">
  <arcgis-utility-network-trace-analysis slot="top-right"></arcgis-utility-network-trace-analysis>
</arcgis-map>

Components Summary

| Component | Purpose | |-----------|---------| | arcgis-utility-network-trace | Interactive trace UI | | arcgis-utility-network-associations | Association visualization | | arcgis-utility-network-trace-analysis | Detailed trace analysis | | arcgis-utility-network-validate-topology | Topology validation |

Core API Approach

UtilityNetworkTrace Widget

esriConfig.portalUrl = "https://www.arcgis.com";

const webmap = new WebMap({
  portalItem: { id: "YOUR_WEBMAP_ID" }
});

const view = new MapView({
  container: "viewDiv",
  map: webmap
});

const utilityNetworkTrace = new UtilityNetworkTrace({
  view: view,
  showSelectionAttributes: true,
  selectOnComplete: true
});

view.ui.add(utilityNetworkTrace, "top-right");

UtilityNetworkTrace Properties

| Property | Type | Description | |----------|------|-------------| | view | MapView | Map view (required) | | flags | MapPoint[] | Starting points and barriers | | selectedTraces | string[] | Global IDs of traces to select on load | | showSelectionAttributes | boolean | Show results as organized list | | selectOnComplete | boolean | Auto-select features on trace completion | | enableResultArea | boolean | Show result area graphics | | resultAreaColor | Color | Color for aggregated trace geometry |

UtilityNetworkTrace Events

| Event | Description | |-------|-------------| | trace-complete | Fires after a trace completes | | result-area-added | Fires when adding result area graphic | | result-area-removed | Fires when removing result area graphic |

UtilityNetworkAssociations Widget

view.when(async () => {
  await webMap.load();

  if (webMap.utilityNetworks.length > 0) {
    const utilityNetwork = webMap.utilityNetworks.getItemAt(0);
    await utilityNetwork.load();

    const unAssociations = new UtilityNetworkAssociations({
      view,
      utilityNetwork
    });

    view.ui.add(unAssociations, "top-right");
  }
});

Association Types

Connectivity — Electrical/flow connections between features
Containment — Features contained inside other features
Structural Attachment — Features attached to structures

Associations Visible Elements

const unAssociations = new UtilityNetworkAssociations({
  view,
  utilityNetwork,
  visibleElements: {
    maxAllowableAssociationsSlider: true,
    connectivityAssociationsSettings: {
      arrowsToggle: false,
      capSelect: false,
      colorPicker: true,
      stylePicker: true,
      widthInput: true
    },
    structuralAttachmentAssociationsSettings: {
      arrowsToggle: false,
      capSelect: false,
      colorPicker: true,
      stylePicker: true,
      widthInput: true
    }
  }
});

Accessing Utility Networks

Get Utility Network from WebMap

await webMap.load();

if (webMap.utilityNetworks && webMap.utilityNetworks.length > 0) {
  const utilityNetwork = webMap.utilityNetworks.getItemAt(0);
  await utilityNetwork.load();

  console.log("Title:", utilityNetwork.title);
  console.log("Dataset name:", utilityNetwork.datasetName);
  console.log("Domain networks:", utilityNetwork.domainNetworks);
  console.log("Network attributes:", utilityNetwork.networkAttributes);
  console.log("Terminal configs:", utilityNetwork.terminalConfigurations);
}

UtilityNetwork Properties

| Property | Type | Description | |----------|------|-------------| | title | string | Network title | | datasetName | string | Dataset name | | domainNetworks | object[] | Domain networks in the utility network | | networkAttributes | object[] | Network attributes | | terminalConfigurations | object[] | Terminal configurations | | sharedNamedTraceConfigurations | object[] | Shared trace configurations |

UtilityNetwork Methods

| Method | Description | |--------|-------------| | load() | Load utility network metadata | | trace(traceParams) | Execute trace synchronously | | submitTraceJob(traceParams) | Execute trace asynchronously | | queryAssociations(params) | Query associations | | synthesizeAssociationGeometries(extent) | Get association geometries | | loadAssociationsTable() | Load associations table (recommended before querying) |

Network Tracing

Trace Types

| Trace Type | Description | |-----------|-------------| | Connected | Find all connected features | | Upstream | Trace toward sources | | Downstream | Trace away from sources | | Subnetwork | Find features in same subnetwork | | Isolation | Find isolation points | | Loops | Find loops in network |

Execute Trace Programmatically

const utilityNetwork = webMap.utilityNetworks.getItemAt(0);
await utilityNetwork.load();

const traceResult = await utilityNetwork.trace(traceParams);

// For long-running traces
const jobInfo = await utilityNetwork.submitTraceJob(traceParams);

Query Associations

await utilityNetwork.loadAssociationsTable();

const result = await utilityNetwork.queryAssociations(queryParams);

High Zoom Level Support

Associations are only visible at very high zoom levels. Configure additional LODs:

const tileInfo = TileInfo.create({
  spatialReference: { wkid: 102100 },
  numLODs: 32
});

const view = new MapView({
  container: "viewDiv",
  map: webMap,
  zoom: 25,
  constraints: {
    lods: tileInfo.lods,
    snapToZoom: false
  }
});

Complete Example

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
  <script type="module" src="https://js.arcgis.com/5.0/"></script>
  <script type="module" src="https://js.arcgis.com/map-components/5.0/arcgis-map-components.esm.js"></script>
  <style>
    html, body { height: 100%; margin: 0; }
  </style>
</head>
<body>
  <arcgis-map item-id="YOUR_WEBMAP_ID">
    <arcgis-utility-network-trace slot="top-right"></arcgis-utility-network-trace>
    <arcgis-utility-network-associations slot="bottom-right"></arcgis-utility-network-associations>
  </arcgis-map>
</body>
</html>

Common Pitfalls

Authentication required: Utility network services typically require authentication — configure esriConfig.portalUrl and credentials.
WebMap required: Utility networks must be accessed through a WebMap — they cannot be created client-side.
High zoom for associations: Associations only display at very high zoom levels — use TileInfo.create({ numLODs: 32 }) and set snapToZoom: false.
Load order: Must load WebMap first, then load UtilityNetwork before creating widgets.
Enterprise portals: Often hosted on ArcGIS Enterprise — set esriConfig.portalUrl to the portal URL.
Topology validation: Network topology must be enabled and validated before accurate tracing results.
Named trace configurations: Trace widget requires shared named trace configurations (Enterprise 10.9+).

Reference Samples

utility-network-trace — Running utility network traces
utility-network-associations — Viewing associations
widgets-untrace — Utility network trace widget

Related Skills

arcgis-layers — Layer configuration and WebMap loading
arcgis-authentication — Portal authentication setup
arcgis-widgets-ui — Widget placement and UI customization

Agent Skills: ArcGIS Utility Networks

Install this agent skill to your local

Skill Files