Arcgis Utility Networks

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

Utility Network Associations Component

Utility Network Validate Topology Component

Utility Network Trace Analysis Component

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

  
    
    
    
    
    
      html,
      body {
        height: 100%;
        margin: 0;
      }
    
  
  
    
      
      
    
  

Common Pitfalls

1. Authentication required: Utility network services typically require authentication — configure esriConfig.portalUrl and credentials.

1. WebMap required: Utility networks must be accessed through a WebMap — they cannot be created client-side.

1. High zoom for associations: Associations only display at very high zoom levels — use TileInfo.create({ numLODs: 32 }) and set snapToZoom: false.

1. Load order: Must load WebMap first, then load UtilityNetwork before creating widgets.

1. Enterprise portals: Often hosted on ArcGIS Enterprise — set esriConfig.portalUrl to the portal URL.

1. Topology validation: Network topology must be enabled and validated before accurate tracing results.

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: SaschaBrunnerCH
• Source: SaschaBrunnerCH/arcgis-maps-sdk-js-ai-context
• License: MIT

Install and usage instructions live in the source repository linked above.