ESM
import "@arcgis/map-components/components/arcgis-utility-network-trace-analysis";
Inheritance
ArcgisUtilityNetworkTraceAnalysis→HTMLElement
Since
ArcGIS Maps SDK for JavaScript 5.0

Overview

The Utility Network Trace Analysis component allows users to run traces and view trace results in a utility network.

  • The component supports selecting a utility network and a named trace configuration in that utility network. Both the utility network and trace configuration must be stored in the map.
  • Trace locations (starting points, stopping points, and barriers) are set by selecting features on the view.
  • When a subnetwork-based trace is selected, the component displays the domain, tier, and target tier specified by the selected named trace configuration.
  • If the user selects a subnetwork trace with a specified subnetwork name, the component provides an option to choose a subnetwork name instead of starting location(s) to run the trace with.

Supported trace types are: connected, upstream, downstream, shortest-path (deprecated), path, subnetwork, subnetwork-controller, loops, and isolation.

The shortest path trace type is deprecated with ArcGIS Pro 3.7 and ArcGIS Enterprise 12.1.

While the shortest path trace will continue to function and be an option until the next major release, it is recommended to use the path trace to return the shortest path. The path trace provides the same functionality to return a shortest path result while offering additional capabilities to find paths in your network.

The component can display the following from a trace result: elements (as features), aggregated geometries, and function results.

The Utility Network Trace Analysis component does not support the following:

  1. Proxied feature services or feature services that utilize stored credentials.
  2. The circuit trace type or the paths and circuits result types.
  3. Setting grouping properties firstUnit and lastUnit for trace locations in a telecom domain network. If a grouped object is used as a trace location, its firstUnit and lastUnit attributes are not used in the trace.

Working with nonspatial objects

The Utility Network Trace Analysis component supports selecting nonspatial objects as trace locations by traversing associations.

When selecting a trace location or viewing a trace result feature, information about the feature is displayed according to the PopupTemplate of the layer that the feature belongs to. If the feature's layer has no PopupTemplate, a default template is used to display the feature's attributes.

To select a nonspatial object as a trace location, first select a spatial feature on the map that is associated with the target nonspatial object. The spatial feature's layer must have a PopupTemplate that includes a UtilityNetworkAssociationsContent. Navigate through the spatial feature's associations to the target nonspatial object, then add the object as a trace location.

Examples

This component can be used slotted into an arcgis-map:

<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
<arcgis-utility-network-trace-analysis slot="bottom-left"></arcgis-utility-network-trace-analysis>
</arcgis-map>

Alternatively, this component can be used outside of a map by providing a referenceElement:

<calcite-shell>
<calcite-shell-panel slot="panel-start" position="start" width="l">
<arcgis-utility-network-trace-analysis reference-element="#map-element"></arcgis-utility-network-trace-analysis>
</calcite-shell-panel>
<arcgis-map id="map-element" item-id="471eb0bf37074b1fbb972b1da70fb310"></arcgis-map>
</calcite-shell>

Note: Sign in to access the data in this demo, U/P: viewer01/I68VGU^nMurF

Demo

Properties

PropertyAttributeType
aggregated-geometry-graphics-color
aggregated-geometry-results-graphics-color
aggregated-geometry-results-size
auto-destroy-disabled
disable-highlight-feature-results
readonly
hide-action-bar
hide-clear-results-count
hide-feature-results
hide-graphics
hide-placeholder
include-default-actions-disabled
deprecated reflected
label
reference-element
readonly
readonly

actions

Property
Type
ArcgisFeaturesNext["actions"] | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

A collection of action button or action toggle objects. Each action may be executed by clicking the icon or image symbolizing them. There is a default Zoom To action styled with a magnifying glass icon to zoom in four LODs and center the map on the selected feature. This default action can be removed by setting includeDefaultActionsDisabled to true, or by setting the overwriteActions property to true in a PopupTemplate.

The order of each action is the order in which they appear in the actions Collection. The @arcgisTriggerAction event fires each time an action is clicked.

See also

aggregatedGeometryGraphicsColor

deprecated Property
Type
Color

The color used to render graphics for aggregated geometries in trace results.

Attribute
aggregated-geometry-graphics-color

aggregatedGeometryResultsGraphicsColor

Property
Type
Color
Since
ArcGIS Maps SDK for JavaScript 5.2

The color used to render graphics for aggregated geometries in trace results, specified as a Color object.

Aggregated geometry is only rendered if the trace configuration specifies aggregated geometry as a result type.

Default color is #FFFF00.

See also
Attribute
aggregated-geometry-results-graphics-color
Examples

Set the default aggregated geometry graphics color to lime green in JavaScript.

const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.aggregatedGeometryResultsGraphicsColor = new Color("lime");

Set the default aggregated geometry graphics color to red in HTML.

<arcgis-map item-id="967a4180aa6c46b68996ea9406e8a606">
<arcgis-utility-network-trace-analysis slot="bottom-left" aggregated-geometry-results-graphics-color="red">
</arcgis-utility-network-trace-analysis>
</arcgis-map>

aggregatedGeometryResultsSize

Property
Type
number
Since
ArcGIS Maps SDK for JavaScript 5.2

The size in points used to render graphics for aggregated geometries in trace results.

Aggregated geometry is only rendered if the trace configuration specifies aggregated geometry as a result type.

See also
Attribute
aggregated-geometry-results-size
Default value
12
Example

Set the default aggregated geometry graphics size to 8 points.

const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.aggregatedGeometryResultsSize = 8;

autoDestroyDisabled

Property
Type
boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute
auto-destroy-disabled
Default value
false
Example
<arcgis-utility-network-trace-analysis auto-destroy-disabled></arcgis-utility-network-trace-analysis>
utilityNetworkTraceAnalysisElement.autoDestroyDisabled = true;

disableHighlightFeatureResults

Property
Type
boolean

Whether to disable highlighting trace result features on the map.

If true, the features returned by a trace will not be highlighted on the map.

Attribute
disable-highlight-feature-results
Default value
false
Example

Disable highlighting trace result features.

<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
<arcgis-utility-network-trace-analysis disable-highlight-feature-results slot="top-right">
</arcgis-utility-network-trace-analysis>
</arcgis-map>

flowItems

readonly Property
Type
Collection
Since
ArcGIS Maps SDK for JavaScript 5.2

Additional Calcite Flow Items displayed in the Results tab. Add or remove native calcite-flow-item elements through this Collection.

hideActionBar

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether to hide the action bar that holds the feature's arcgis-features-next.actions when selecting trace locations and viewing trace result features.

See also
Attribute
hide-action-bar
Default value
false

hideClearResultsCount

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Whether to hide the count of features next to the "Clear results" button in the Results tab for trace results which include elements.

Attribute
hide-clear-results-count
Default value
false

hideFeatureResults

Property
Type
boolean

Whether to hide feature results in the results tab.

If true, when features are returned by a trace, they will not be visible in the results tab. A message will be displayed in its place indicating that features were returned by the trace, but are not visible in the results pane. This string can be overridden with the messageOverrides property.

Attribute
hide-feature-results
Default value
false
Examples

Do not show features in the results tab.

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

Override the message displayed in the results tab when features are hidden.

const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.messageOverrides = { resultFeaturesAreHidden: "Feature results were sent to the results window." };

hideGraphics

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Whether to hide the aggregated geometry graphics from the map when the trace result contains aggregated geometry results.

Attribute
hide-graphics
Default value
false

hidePlaceholder

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Whether to hide the placeholder string when feature results are hidden in the results tab.

When this property and hideFeatureResults are both set to true, nothing is rendered for trace result elements. However, features are still queried and are available through traceResultFeatures.

Attribute
hide-placeholder
Default value
false
Example

Hide the placeholder when feature results are hidden.

<arcgis-map item-id="471eb0bf37074b1fbb972b1da70fb310">
<arcgis-utility-network-trace-analysis
hide-feature-results
hide-placeholder
slot="top-right"
></arcgis-utility-network-trace-analysis>
</arcgis-map>

includeDefaultActionsDisabled

Property
Type
boolean
Since
ArcGIS Maps SDK for JavaScript 5.2

Indicates whether default actions are disabled (hidden) when selecting trace locations and viewing trace result features. This property must be set to true to disable default actions.

See also
Attribute
include-default-actions-disabled
Default value
false

label

deprecatedreflected Property
Type
string | undefined

The component's default label.

Attribute
label

messageOverrides

Property
Type
Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

referenceElement

Property
Type
ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also
Attribute
reference-element

state

readonly Property
Type
UtilityNetworkTraceAnalysisState

The current state of the component.

traceError

readonly Property
Type
EsriError | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

The error from the most recent failed trace attempt. Read this property when @arcgisError fires. This property is reset to undefined before a new trace runs.

traceResult

Property
Type
TraceResult | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

The TraceResult returned by the most recent successful trace. This property is reset to undefined before a new trace runs.

traceResultFeatures

readonly Property
Type
Graphic[]

An array of features returned by the trace result.

This array is populated if the trace returned element results.

When @arcgisTraceResultFeaturesReady is raised, trace result features are available. When a new trace has been run, or the trace results are cleared, this array is cleared.

view

Property
Type
MapView | null | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-utility-network-trace-analysis component will be associated with a map or scene component rather than using the view property.

Methods

MethodSignature
inherited
componentOnReady(): Promise<this>
destroy(): Promise<void>

componentOnReady

inherited Method
Signature
componentOnReady (): Promise<this>

Creates a promise that resolves once the component is fully loaded.

Returns
Promise<this>
Example
const arcgisUtilityNetworkTraceAnalysis = document.createElement("arcgis-utility-network-trace-analysis");
document.body.append(arcgisUtilityNetworkTraceAnalysis);
await arcgisUtilityNetworkTraceAnalysis.componentOnReady();
console.log("arcgis-utility-network-trace-analysis is ready to go!");

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

Events

NameType
CustomEvent<{ name: "aggregatedGeometryGraphicsColor" | "aggregatedGeometryResultsGraphicsColor" | "hideGraphics" | "state" | "traceError" | "traceResult"; }>

arcgisError

Event
arcgisError: CustomEvent<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Fires when the selected named trace configuration's trace type or trace configuration is unavailable, or when an error occurs while executing a trace. The error is available through traceError before this event fires. This event does not include an error in its payload.

bubbles composed cancelable
Example
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.addEventListener("arcgisError", () => {
console.error("Trace failed:", traceElement.traceError);
});

arcgisHideGraphicsChange

deprecated Event
arcgisHideGraphicsChange: CustomEvent<boolean>

Fires when the user toggles displaying aggregated geometry results in the result pane. Event payload contains a boolean representing whether the aggregated geometry graphics are hidden. If true, the aggregated geometry graphics are hidden on the view.

bubbles composed cancelable
Example
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.addEventListener("arcgisHideGraphicsChange", (event) => {
const hideGraphics = event.detail;
console.log(hideGraphics);
});

arcgisPropertyChange

Event
arcgisPropertyChange: CustomEvent<{ name: "aggregatedGeometryGraphicsColor" | "aggregatedGeometryResultsGraphicsColor" | "hideGraphics" | "state" | "traceError" | "traceResult"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

bubbles composed cancelable

arcgisReady

Event
arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready for user interaction.

bubbles composed cancelable

arcgisTraceResultClear

Event
arcgisTraceResultClear: CustomEvent<void>

Fires when trace results and errors are cleared from the results tab.

bubbles composed cancelable
Example
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.addEventListener("arcgisTraceResultClear", (event) => {
console.log("Trace result was cleared.");
});

arcgisTraceResultFeaturesReady

Event
arcgisTraceResultFeaturesReady: CustomEvent<void>

Fires when the trace result features are ready. Check property traceResultFeatures for the trace result features.

bubbles composed cancelable
Example
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.addEventListener("arcgisTraceResultFeaturesReady", (event) => {
const resultFeatures = traceElement.traceResultFeatures;
console.log(resultFeatures);
});

arcgisTraceResultReady

Event
arcgisTraceResultReady: CustomEvent<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Fires when the trace result is ready.

bubbles composed cancelable
Example
const traceElement = document.querySelector("arcgis-utility-network-trace-analysis");
traceElement.addEventListener("arcgisTraceResultReady", (event) => {
console.log("Trace result is ready.");
});

arcgisTriggerAction

Event
arcgisTriggerAction: CustomEvent<ActionEvent>
Since
ArcGIS Maps SDK for JavaScript 5.2

Emitted when an action is triggered on the component.

bubbles composed cancelable

Slots

NameDescription

Slot for instances of arcgis-utility-network-trace-results, for displaying the results of one or more traces.

results

Slot

Slot for instances of arcgis-utility-network-trace-results, for displaying the results of one or more traces.