arcgis-utility-networks
Skill1 starsChanged 6 months agoMITView on GitHub
Work with utility networks in the ArcGIS Maps SDK for JavaScript 5.1: load a UtilityNetwork (from a web map or a layer URL; secured services hang on a sign-in dialog), run traces with utilityNetwork.trace() and TraceParameters (the JS name is namedTraceConfigurationGlobalId; the REST name is dropped silently), and the arcgis-utility-network-trace-analysis component (the old arcgis-utility-network-trace is deprecated since 5.0, and the new one needs a web map that stores the network). Use this skill whenever the user analyzes utility networks (water, electric, gas), runs a trace, or works with terminals.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- GeoDaoyu/arcgis-maps-sdk-js-ai-contexttheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- GeoDaoyu/arcgis-maps-sdk-js-ai-context★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository73 other files it gives its agents.
- skills/arcgis-3d-layers/AGENTS.mdAGENTS.md
- skills/arcgis-advanced-layers/AGENTS.mdAGENTS.md
- skills/arcgis-ai-components/AGENTS.mdAGENTS.md
- skills/arcgis-arcade/AGENTS.mdAGENTS.md
- skills/arcgis-authentication/AGENTS.mdAGENTS.md
- skills/arcgis-charts/AGENTS.mdAGENTS.md
- skills/arcgis-cim-symbols/AGENTS.mdAGENTS.md
- skills/arcgis-coding-components/AGENTS.mdAGENTS.md
- skills/arcgis-coordinates-projection/AGENTS.mdAGENTS.md
- skills/arcgis-core-maps/AGENTS.mdAGENTS.md
- skills/arcgis-core-utilities/AGENTS.mdAGENTS.md
- skills/arcgis-custom-rendering/AGENTS.mdAGENTS.md
- skills/arcgis-editing/AGENTS.mdAGENTS.md
- skills/arcgis-embeddable-maps/AGENTS.mdAGENTS.md
- skills/arcgis-feature-effects/AGENTS.mdAGENTS.md
- skills/arcgis-geometry-operations/AGENTS.mdAGENTS.md
- skills/arcgis-imagery/AGENTS.mdAGENTS.md
- skills/arcgis-interaction/AGENTS.mdAGENTS.md
- skills/arcgis-knowledge-graphs/AGENTS.mdAGENTS.md
- skills/arcgis-layers/AGENTS.mdAGENTS.md
- skills/arcgis-map-tools/AGENTS.mdAGENTS.md
- skills/arcgis-parquet/AGENTS.mdAGENTS.md
- skills/arcgis-performance/AGENTS.mdAGENTS.md
- skills/arcgis-popup-templates/AGENTS.mdAGENTS.md
- skills/arcgis-portal-content/AGENTS.mdAGENTS.md
- skills/arcgis-rest-services/AGENTS.mdAGENTS.md
- skills/arcgis-scene-environment/AGENTS.mdAGENTS.md
- skills/arcgis-smart-mapping/AGENTS.mdAGENTS.md
- skills/arcgis-spatial-analysis/AGENTS.mdAGENTS.md
- skills/arcgis-starter-app/AGENTS.mdAGENTS.md
- skills/arcgis-tables-forms/AGENTS.mdAGENTS.md
- skills/arcgis-time-animation/AGENTS.mdAGENTS.md
- skills/arcgis-utility-networks/AGENTS.mdAGENTS.md
- skills/arcgis-visualization/AGENTS.mdAGENTS.md
- skills/arcgis-widgets-advanced/AGENTS.mdAGENTS.md
- skills/arcgis-widgets-ui/AGENTS.mdAGENTS.md
- skills/hello-world/AGENTS.mdAGENTS.md
- arcgis-3d-layersSkill
- arcgis-advanced-layersSkill
- arcgis-ai-componentsSkill
- arcgis-arcadeSkill
- arcgis-authenticationSkill
- arcgis-chartsSkill
- arcgis-cim-symbolsSkill
- arcgis-coding-componentsSkill
- arcgis-coordinates-projectionSkill
- arcgis-core-mapsSkill
- arcgis-core-utilitiesSkill
- arcgis-custom-renderingSkill
- arcgis-editingSkill
- arcgis-embeddable-mapsSkill
- arcgis-feature-effectsSkill
- arcgis-geometry-operationsSkill
- arcgis-imagerySkill
- arcgis-interactionSkill
- arcgis-knowledge-graphsSkill
- arcgis-layersSkill
- arcgis-map-toolsSkill
- arcgis-parquetSkill
- arcgis-performanceSkill
- The first 60 shown.
The file
Files
Utility Networks
When to use: Activate this skill whenever the user loads a utility network, runs a trace, or analyzes connectivity (water/electric/gas).
Overview
A UtilityNetwork models connected infrastructure; a trace follows connectivity from starting points.
- Problem it solves: connectivity analysis on utility infrastructure.
- Who it serves: developers building water, electric, and gas network apps.
- Pattern it teaches: get the network from a web map, sign in, pick a named trace configuration, trace.
- What it does NOT cover: generic layers (see
arcgis-layers), routing (seearcgis-rest-services), or sign-in itself (seearcgis-authentication).
Quick Start
import WebMap from "@arcgis/core/WebMap.js";
const webMap = new WebMap({ portalItem: { id: "YOUR_UN_WEBMAP_ID" } }); // a web map that stores the network
await webMap.load();
const un = webMap.utilityNetworks?.at(0);
if (un) {
await un.load();
const config = un.sharedNamedTraceConfigurations[0]; // configurations saved with the web map
const result = await un.trace({
namedTraceConfigurationGlobalId: config.globalId,
traceLocations: [{ type: "starting-point", globalId: "{FEATURE-GLOBALID}", terminalId: 1 }],
});
console.log(result.elements.length, result.startingPointsIgnored);
}Utility network services are secured: the app must sign in first (arcgis-authentication). Esri's public Naperville
sample answers "Token Required" without a session.
Decision Tree
- Need a ready trace UI?
- Yes →
arcgis-utility-network-trace-analysisin a map loaded from a web map that stores the network. - Not
arcgis-utility-network-trace: deprecated since 5.0.
- Yes →
- Custom trace logic?
- Yes →
un.trace({ namedTraceConfigurationGlobalId, traceLocations })(it fillsgdbVersionandmoment), or the RESTtrace(url, new TraceParameters(...))when you only have the service URL.
- Yes →
- Which trace type?
- Connectivity →
connected; flow →upstream/downstream; valves →isolation; a path →path(shortest-pathis deprecated in ArcGIS Pro 3.7 and Enterprise 12.1).
- Connectivity →
Default: the trace analysis component for standard UX; un.trace() with a named configuration for custom work.
Import Patterns
Direct ESM (recommended for npm/Vite/Webpack)
import UtilityNetwork from "@arcgis/core/networks/UtilityNetwork.js";
import TraceParameters from "@arcgis/core/rest/networks/support/TraceParameters.js";Dynamic Imports (CDN)
const UtilityNetwork = await $arcgis.import("@arcgis/core/networks/UtilityNetwork.js");Map Components (recommended for new projects)
import "@arcgis/map-components/components/arcgis-utility-network-trace-analysis";Key Concepts
Concept 1: Where the network comes from
A web map saved with a utility network exposes it as webMap.utilityNetworks, together with the trace
configurations shared with it (sharedNamedTraceConfigurations). new UtilityNetwork({ layerUrl }) also works, but
then there are no shared configurations; ask the service with un.queryNamedTraceConfigurations().
Concept 2: A trace is a configuration plus locations
A named trace configuration (its globalId) carries the trace type, tiers, and filters. Trace locations are
starting-point, stopping-point, or barrier, each a feature globalId with a terminalId on multi-terminal
devices or a percentAlong on lines.
Concept 3: Read what the trace ignored
TraceResult returns elements, aggregatedGeometry, globalFunctionResults, and also startingPointsIgnored and
warnings: a location the network could not use does not fail the trace, it is reported there.
Common Pitfalls (Top 3)
Pitfall 1: Using the REST parameter name in JavaScript
// ❌ Anti-pattern: the REST name; the JS class drops it
new TraceParameters({ traceConfigurationGlobalId: cfgId } as never);// ✅ Correct: the JS name, serialized as traceConfigurationGlobalId
new TraceParameters({ namedTraceConfigurationGlobalId: cfgId });Impact: measured on 5.1.27: with the REST name, namedTraceConfigurationGlobalId is null and toJSON() has no
configuration at all, with no error. The trace goes out without one.
Pitfall 2: Passing a plain object to the REST trace
// ❌ Anti-pattern
await trace.trace(url, { traceType: "connected", traceLocations }); // TypeError: n2.toJSON is not a function// ✅ Correct
await trace.trace(url, new TraceParameters({ namedTraceConfigurationGlobalId: cfgId, traceLocations }));
// or, with a loaded network: await un.trace({ namedTraceConfigurationGlobalId: cfgId, traceLocations })Impact: measured: the REST module calls toJSON() on its parameters and throws a TypeError before any request.
Strict TypeScript also rejects the plain object (TS2740).
Pitfall 3: Building on the deprecated trace component
<!-- ❌ Anti-pattern -->
<arcgis-utility-network-trace></arcgis-utility-network-trace><!-- ✅ Correct, inside a map loaded from a web map that stores the network -->
<arcgis-map item-id="YOUR_UN_WEBMAP_ID">
<arcgis-utility-network-trace-analysis slot="top-right"></arcgis-utility-network-trace-analysis>
</arcgis-map>Impact: arcgis-utility-network-trace is @deprecated since 5.0. Its replacement needs the network in the web
map: measured in a map with only a basemap, it reached state: "ready" and drew its tabs, and the console logged
"The property utilityNetworks is empty but must have at least one element".
When to Read references/
| If you need... | Read |
| UtilityNetwork / trace signatures | references/api-detail.md |
| Trace examples | references/examples.md |
| More pitfalls (5+ extended) | references/pitfalls.md |
Related Skills
arcgis-layers— the feature layers in the networkarcgis-editing— edit network featuresarcgis-interaction— pick starting points on the map
Reference Samples
Changelog
- 0.2.0 (2026-10-27): SDK 5.1. Runtime checks in
tests/runtime/casos/arcgis-utility-networks.ts, without credentials (the public Naperville sample needs a token, and the harness does not sign in), so no trace ran end to end. Fixed: the trace configuration parameter was the REST nametraceConfigurationGlobalId, which the JS class drops silently (measured); the REST trace example passed a plain object, which throwsTypeError: n2.toJSON is not a function(measured; it was also the block failing TS2740);dataElement.domainNetworksreplaced by the typed members. New:arcgis-utility-network-traceis deprecated since 5.0, its replacement needs a web map that stores the network (measured), a secured service leavesload()pending on a sign-in dialog (measured),un.trace(),startingPointsIgnored, andshortest-pathdeprecated. Replaced the five comment-only pitfalls. - 0.1.0 (2026-05-31): Initial release.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

