UtilityNetworkTraceViewModel

AMD: require(["esri/widgets/UtilityNetworkTrace/UtilityNetworkTraceViewModel"], (UtilityNetworkTraceViewModel) => { /* code goes here */ });
ESM: import UtilityNetworkTraceViewModel from "@arcgis/core/widgets/UtilityNetworkTrace/UtilityNetworkTraceViewModel.js";
Class: esri/widgets/UtilityNetworkTrace/UtilityNetworkTraceViewModel
Inheritance: UtilityNetworkTraceViewModel Accessor
Since: ArcGIS Maps SDK for JavaScript 4.22

Provides the logic for the UtilityNetworkTrace widget.

See also

Constructors

UtilityNetworkTraceViewModel

Constructor
new UtilityNetworkTraceViewModel(properties)
Parameter
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
String

The name of the class.

Accessor
GraphicColor

The default color to assign the aggregated geometry of a trace result.

UtilityNetworkTraceViewModel
Boolean

When true, provides the ability to show the convex hull or buffer.

UtilityNetworkTraceViewModel
FlagProperty[]

An array of map points to load into the widget to lookup flags.

UtilityNetworkTraceViewModel
String

The Geodatabase version to pass into the trace.

UtilityNetworkTraceViewModel
GoToOverride

This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.

UtilityNetworkTraceViewModel
ResultAreaPropertiesExtend

The properties to determine the size and color of the result area convex hull or buffer, and determines if it displays on the map when the trace completes.

UtilityNetworkTraceViewModel
String[]

An array of global Ids of traces to select on initial load.

UtilityNetworkTraceViewModel
Boolean

When true, the utility network elements are selected in the view when traces are completed.

UtilityNetworkTraceViewModel
Boolean

When true, a graphic layer is added to the view to highlight the utility network elements when traces are completed.

UtilityNetworkTraceViewModel
Boolean

Determines whether to show the list of selected features from completed traces.

UtilityNetworkTraceViewModel
String

The view model's state.

UtilityNetworkTraceViewModel
TraceResultExtend[]

Stores the result of completed traces.

UtilityNetworkTraceViewModel
UtilityNetwork

Determines the utility network to use.

UtilityNetworkTraceViewModel
MapView

The view from which the widget will operate.

UtilityNetworkTraceViewModel

Property Details

declaredClass

Inherited
Property
declaredClass Stringreadonly
Inherited from Accessor

The name of the class. The declared class name is formatted as esri.folder.className.

defaultGraphicColor

Property
defaultGraphicColor GraphicColor
Since: ArcGIS Maps SDK for JavaScript 4.23 UtilityNetworkTraceViewModel since 4.22, defaultGraphicColor added at 4.23.

The default color to assign the aggregated geometry of a trace result.

Default Value:{ color: [255, 255, 0, 0.6], haloOpacity: 0.9, fillOpacity: 0.2, hex: "#FFFF00" }

enableResultArea

Property
enableResultArea Boolean
Since: ArcGIS Maps SDK for JavaScript 4.27 UtilityNetworkTraceViewModel since 4.22, enableResultArea added at 4.27.

When true, provides the ability to show the convex hull or buffer.

Default Value:false

flags

Property
flags FlagProperty[]

An array of map points to load into the widget to lookup flags.

Default Value:[]
Example
const unt = new UtilityNetworkTrace({
 view: view,
 showSelectionAttributes: true,
 selectOnComplete: true,
 showGraphicsOnComplete: true,
 selectedTraces: ["{E8D545B8-596D-4656-BF5E-16C1D7CBEC9B}"],
 flags: [
   {
     type: "starting-point",
     mapPoint: {
       spatialReference: { latestWkid: 3857, wkid: 102100 },
       x: -9814829.166046409,
       y: 5127094.1017433
     }
   },
   {
     type: "barrier",
     mapPoint: {
     spatialReference: { latestWkid: 3857, wkid: 102100 },
       x: -9814828.449441982,
       y: 5127089.085566963
     }
   }
 ]
});

gdbVersion

Property
gdbVersion String

The Geodatabase version to pass into the trace.

Default Value:"sde.DEFAULT"

goToOverride

Property
goToOverride GoToOverride

This function provides the ability to override either the MapView goTo() or SceneView goTo() methods.

See also
Example
// The following snippet uses the Search widget but can be applied to any
// widgets that support the goToOverride property.
search.goToOverride = function(view, goToParams) {
  goToParams.options.duration = updatedDuration;
  return view.goTo(goToParams.target, goToParams.options);
};

resultAreaProperties

Property
resultAreaProperties ResultAreaPropertiesExtend
Since: ArcGIS Maps SDK for JavaScript 4.27 UtilityNetworkTraceViewModel since 4.22, resultAreaProperties added at 4.27.

The properties to determine the size and color of the result area convex hull or buffer, and determines if it displays on the map when the trace completes.

Default Value:{ type: "convexhull", distance: 10, unit: "meters", areaUnit: "square-meters", color: { color: [255, 165, 0, 0.5], haloOpacity: 0.9, fillOpacity: 0.2, hex: "#ffa500" }, show: false }
Example
const unt = new UtilityNetworkTrace({
 un: un,
 view: view,
 enableResultArea: true,
 resultAreaProperties: {
   type: "buffer",
   distance: 10,
   unit: "feet",
   areaUnit: "square-feet",
   color: {
     color: [255, 165, 0, 0.5],
     haloOpacity: 0.9,
     fillOpacity: 0.2,
     hex: "#ffa500"
   },
   show: true
 }
});

selectedTraces

Property
selectedTraces String[]

An array of global Ids of traces to select on initial load.

Default Value:[]

selectOnComplete

Property
selectOnComplete Boolean

When true, the utility network elements are selected in the view when traces are completed.

Default Value:true

showGraphicsOnComplete

Property
showGraphicsOnComplete Boolean

When true, a graphic layer is added to the view to highlight the utility network elements when traces are completed.

Default Value:true

showSelectionAttributes

Property
showSelectionAttributes Boolean

Determines whether to show the list of selected features from completed traces.

Default Value:true

state

Property
state Stringreadonly

The view model's state.

Possible Values:"loading"|"ready"

Default Value:ready

traceResults

Property
traceResults TraceResultExtend[]
Since: ArcGIS Maps SDK for JavaScript 4.27 UtilityNetworkTraceViewModel since 4.22, traceResults added at 4.27.

Stores the result of completed traces.

utilityNetwork

Property
utilityNetwork UtilityNetwork
Since: ArcGIS Maps SDK for JavaScript 4.27 UtilityNetworkTraceViewModel since 4.22, utilityNetwork added at 4.27.

Determines the utility network to use.

view

Property
view MapView

The view from which the widget will operate.

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class
Promise<boolean>

Adds a flag point graphic for the click event on the view if there is a feature to query.

UtilityNetworkTraceViewModel

Adds one or more handles which are to be tied to the lifecycle of the object.

Accessor

Creates a graphic from the trace result and adds it to the map.

UtilityNetworkTraceViewModel
Promise

Create a graphic on the view’s graphics for the aggregated results of all the features returned by the trace.

UtilityNetworkTraceViewModel

Adds the selected terminal to a flag point.

UtilityNetworkTraceViewModel
Promise<boolean>

Get all parameters for the trace type selected to be run before executing the trace.

UtilityNetworkTraceViewModel

Change the graphic color for the aggregated results of a trace.

UtilityNetworkTraceViewModel
ValidSetup

May be used to verify if all requirements are met to execute a trace (at least 1 starting point and at least 1 trace type selected).

UtilityNetworkTraceViewModel
Boolean

Indicates if any selection exists on the view.

UtilityNetworkTraceViewModel

Removes a specific trace from the results.

UtilityNetworkTraceViewModel
Promise<Graphic>

Creates a buffer or convex hull graphic of the trace result.

UtilityNetworkTraceViewModel
Promise<TraceResultExtend>

Executes the trace and returns all trace results as graphics and/or feature selections and functions.

UtilityNetworkTraceViewModel
Array<(EdgeSourceJSON|JunctionSourceJSON)>

Gets the valid edge and junction layers within the view that are part of the Utility Network and can be used for placing flags in the view.

UtilityNetworkTraceViewModel
Boolean

Returns true if a named group of handles exist.

Accessor
Promise<UtilityNetwork>

Reads the web map and loads the UtilityNetwork if it exists.

UtilityNetworkTraceViewModel

Enables or disables the filter barrier setting on barrier flags.

UtilityNetworkTraceViewModel

Is used to merge the feature selections in the layer views when multiple traces are run.

UtilityNetworkTraceViewModel
Promise<FeatureSetInfo[]>

Query the layers by ObjectID for more attributes not present on the trace result elements.

UtilityNetworkTraceViewModel
Promise<boolean>

Takes the result of a hit test to lookup the asset to create a flag for the trace.

UtilityNetworkTraceViewModel

Removes all the graphics from the result area graphic layer

UtilityNetworkTraceViewModel

Removes the selected flag from the view.

UtilityNetworkTraceViewModel

Removes a group of handles owned by the object.

Accessor

Removes the result area graphic from the Map.

UtilityNetworkTraceViewModel

Removes a specific trace result graphic from the view’s graphics.

UtilityNetworkTraceViewModel

Removes the selection from the layer view.

UtilityNetworkTraceViewModel

Removes the selected terminal from the flag.

UtilityNetworkTraceViewModel

Clears all inputs (flags, trace types) and all results (selections, graphics) in the view.

UtilityNetworkTraceViewModel

Performs a selection on a layer view based on a list of ObjectIDs.

UtilityNetworkTraceViewModel

Loops through the trace result elements to group them by network source id and selects them on the layer view.

UtilityNetworkTraceViewModel

Set the trace type to be run from the available trace configurations in the WebMap.

UtilityNetworkTraceViewModel

Preset a trace type to be run from the available trace configurations in the WebMap when the widget loads.

UtilityNetworkTraceViewModel

Zoom to a flag's feature or a result feature in the view.

UtilityNetworkTraceViewModel

Method Details

addFlagByHit

Method
addFlagByHit(type){Promise<boolean>}

Adds a flag point graphic for the click event on the view if there is a feature to query.

Parameter
type String

The type of flag can be a "starting point" or a "barrier".

Returns
Type Description
Promise<boolean> When resolved, response is true if there is a feature to query in the view.

addHandles

Inherited
Method
addHandles(handleOrHandles, groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, addHandles added at 4.25.

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

this.addHandles(handle);

// Destroy the object
this.destroy();
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

addResultAreaToMap

Method
addResultAreaToMap(trace)
Since: ArcGIS Maps SDK for JavaScript 4.27 UtilityNetworkTraceViewModel since 4.22, addResultAreaToMap added at 4.27.

Creates a graphic from the trace result and adds it to the map. If a trace has both aggregated geometries and elements as results, aggregated geometries will be used to generate this area.

Parameter

The aggregate of the trace configuration settings and the results for that trace.

addResultGraphicToView

Method
addResultGraphicToView(trace, color){Promise}

Create a graphic on the view’s graphics for the aggregated results of all the features returned by the trace.

Parameters

The aggregate of the trace configuration settings and the results for that trace.

color GraphicColor

The color for the graphic of the trace results in the view’s graphics.

Returns
Type Description
Promise Resolves when the graphics are added to the view.

addTerminal

Method
addTerminal(selectedTerminal, feature)

Adds the selected terminal to a flag point.

Parameters
selectedTerminal String

The terminal id of the selected terminal.

feature FlagProperty

The flag to assign the terminal.

callTrace

Method
callTrace(){Promise<boolean>}

Get all parameters for the trace type selected to be run before executing the trace.

Returns
Type Description
Promise<boolean> When resolved, response is true when the parameters from the trace type have loaded.

changeResultGraphicColor

Method
changeResultGraphicColor(color, trace)

Change the graphic color for the aggregated results of a trace.

Parameters
color GraphicColor

The color for the graphic of the trace results in the view’s graphics.

The aggregate of the trace configuration settings and the results for that trace.

checkCanTrace

Method
checkCanTrace(){ValidSetup}

May be used to verify if all requirements are met to execute a trace (at least 1 starting point and at least 1 trace type selected).

Returns
Type Description
ValidSetup Represents whether a trace is setup correctly.

checkSelectionExist

Method
checkSelectionExist(){Boolean}

Indicates if any selection exists on the view.

Returns
Type Description
Boolean Returns true if selection exists on the view.

clearResult

Method
clearResult(trace)

Removes a specific trace from the results. This will also clear any graphics or selection in the view for that trace.

Parameter
trace TraceItem

The trace that will be cleared.

createResultAreaGraphic

Method
createResultAreaGraphic(traceResults){Promise<Graphic>}

Creates a buffer or convex hull graphic of the trace result.

Parameter
traceResults TraceResultExtend

The aggregate of the trace configuration settings and the results for that trace.

Returns
Type Description
Promise<Graphic> Buffer or convex hull graphic of trace result.

executeTrace

Method
executeTrace(traceItem, url, params){Promise<TraceResultExtend>}

Executes the trace and returns all trace results as graphics and/or feature selections and functions.

Parameters
traceItem TraceItem

The trace item input for the trace.

url String

The URL of the service being traced.

The trace input parameters.

Returns
Type Description
Promise<TraceResultExtend> Represents the trace results and its properties.

getValidSources

Method
getValidSources(){Array<(EdgeSourceJSON|JunctionSourceJSON)>}

Gets the valid edge and junction layers within the view that are part of the Utility Network and can be used for placing flags in the view.

Returns
Type Description
Array<(EdgeSourceJSON|JunctionSourceJSON)> The edge or junction layer info.

hasHandles

Inherited
Method
hasHandles(groupKey){Boolean}
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, hasHandles added at 4.25.

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}

loadUtilityNetwork

Method
loadUtilityNetwork(){Promise<UtilityNetwork>}

Reads the web map and loads the UtilityNetwork if it exists.

Returns
Type Description
Promise<UtilityNetwork> Resolves when the UtilityNetwork has been loaded.

manageFilterBarrier

Method
manageFilterBarrier(status, feature)

Enables or disables the filter barrier setting on barrier flags.

Parameters
status Boolean

Whether the filter barrier is enabled or disabled.

feature FlagProperty

The barrier flag for which the filter barrier is enabled or disabled.

mergeSelection

Method
mergeSelection(status, trace)

Is used to merge the feature selections in the layer views when multiple traces are run.

Parameters
status Boolean

If true, the trace selection results are part of the merged selection set.

trace TraceItem

The trace for which the status is defined.

queryFeaturesById

Method
queryFeaturesById(dataItems){Promise<FeatureSetInfo[]>}

Query the layers by ObjectID for more attributes not present on the trace result elements.

Parameter
dataItems NetworkElement[]

An array of NetworkElements.

Returns
Type Description
Promise<FeatureSetInfo[]> When resolved, an array of FeatureSetInfo is returned.

queryFlagByHitTest

Method
queryFlagByHitTest(e, flagType){Promise<boolean>}

Takes the result of a hit test to lookup the asset to create a flag for the trace.

Parameters
e ClickEvent

The click event.

flagType String

The type of flag. It must be either "starting point" or "barrier".

Returns
Type Description
Promise<boolean> When resolved, returns true for a successful hitTest.

removeAllResultAreaGraphics

Method
removeAllResultAreaGraphics()

Removes all the graphics from the result area graphic layer

removeFlag

Method
removeFlag(flag)

Removes the selected flag from the view.

Parameter

The FlagProperty to identify the flag to be removed.

removeHandles

Inherited
Method
removeHandles(groupKey)
Inherited from Accessor
Since: ArcGIS Maps SDK for JavaScript 4.25 Accessor since 4.0, removeHandles added at 4.25.

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");

removeResultAreaFromMap

Method
removeResultAreaFromMap(trace)
Since: ArcGIS Maps SDK for JavaScript 4.27 UtilityNetworkTraceViewModel since 4.22, removeResultAreaFromMap added at 4.27.

Removes the result area graphic from the Map.

Parameter

The aggregate of the trace configuration settings and the results for that trace.

removeResultGraphicFromView

Method
removeResultGraphicFromView(trace)

Removes a specific trace result graphic from the view’s graphics.

Parameter

The trace for which the graphic will be removed.

removeSelection

Method
removeSelection()

Removes the selection from the layer view.

removeTerminal

Method
removeTerminal(selectedTerminal, feature)

Removes the selected terminal from the flag.

Parameters
selectedTerminal String

The terminal id of the selected terminal.

feature FlagProperty

The flag to remove the terminal.

reset

Method
reset()

Clears all inputs (flags, trace types) and all results (selections, graphics) in the view.

selectFeaturesById

Method
selectFeaturesById(resultSet)

Performs a selection on a layer view based on a list of ObjectIDs.

Parameter
resultSet NetworkElement[]

An array of NetworkElements.

selectResults

Method
selectResults(resultSet)

Loops through the trace result elements to group them by network source id and selects them on the layer view.

Parameter
resultSet NetworkElement[]

An array of NetworkElements.

selectTraces

Method
selectTraces(state, traceId)

Set the trace type to be run from the available trace configurations in the WebMap.

Parameters
state Boolean

This is true if the trace is selected.

traceId String

The globalid of the trace configuration.

selectTracesOnLoad

Method
selectTracesOnLoad()

Preset a trace type to be run from the available trace configurations in the WebMap when the widget loads.

zoomToAsset

Method
zoomToAsset(geometry)

Zoom to a flag's feature or a result feature in the view.

Parameter

The geometry to zoom to.

Type Definitions

AssetGroupJSON

Type Definition
AssetGroupJSON Object

AssetGroupJSON represents the asset group. The asset group is the subtype field and represents the major classification of utility network classes.

Properties
assetGroupCode Number

The asset group code.

assetGroupName String

The asset group name.

assetTypes AssetTypeJSON[]

The asset type.

AssetTypeJSON

Type Definition
AssetTypeJSON Object

AssetTypeJSON represents asset type. Attribute domains are assigned on the asset type field at the subtype level for each network class. It represents the minor classification of the utility network classes.

Properties
assetTypeCode Number

The asset type code.

assetTypeName String

The asset type name.

terminalConfigurationId Number

The id of the terminal configuration.

DisplayField

Type Definition
DisplayField Object

DisplayField represents the attribute field used as a display label for flags and selected features.

Properties
field String

The feature's display field.

value String

The value of the field.

EdgeSourceJSON

Type Definition
EdgeSourceJSON Object

EdgeSourceJSON represents the line layers that participate in the utility network service.

Properties
layerId Number

The layer id of the line layer.

assetGroups AssetGroupJSON[]

The asset group attribute values for the line layer.

sourceId Number

The network source id of the line layer.

FeatureSetInfo

Type Definition
FeatureSetInfo Object

FeatureSetInfo represents the information for the results in the featureset.

Properties
layer FeatureLayer

The FeatureLayer of the dataset.

featureSet FeatureSet

The FeatureSet.

FlagProperty

Type Definition
FlagProperty Object

FlagProperty represents the properties to define each flag point (starting points and barriers).

Properties
allTerminals TerminalConfiguration

The available terminals to define the permissible paths based on the terminal configurations. The default terminal is always set.

details any

All the information returned by the hitTest.

displayField DisplayField

The display field of the flag.

id Number

The id of the flag.

mapGraphic Graphic

The flag graphic.

mapPoint Point

The geometry point of the flag.

selectedTerminals Number[]

The terminals that are selected for the flag (this can be the default terminal or terminals selected by the end-user).

type String

The flag type being set. Must be either "starting point" or "barrier".

Possible Values

Value Description
starting-point The flag set will be the starting location of the trace.
barrier The flag set will mark the location to stop the trace.

GraphicColor

Type Definition
GraphicColor Object

GraphicColor represents the color for the trace result graphic in the graphics layer.

Properties
color Number[]

The color of the trace result graphic in the view.

haloOpacity Number

The opacity of the graphic symbol's halo.

hex String

The color of the trace result graphic in the color picker.

JunctionSourceJSON

Type Definition
JunctionSourceJSON Object

JunctionSourceJSON represents the point layers that participate in the utility network service.

Properties
layerId Number

The layer id of the point layer.

assetGroups AssetGroupJSON[]

The asset group attribute values for the point layer.

sourceId Number

The network source id of the point layer.

ResultAreaPropertiesExtend

Type Definition
ResultAreaPropertiesExtend Object

ResultAreaPropertiesExtend represents the properties to determine the size and color of the result area convex hull or buffer, and whether it displays on the map when the trace completes.

Properties
type String

The geometry of the result area. The convex hull is the smallest convex polygon enclosing all the result elements. If a distance is defined, it will be applied as a buffer to the convex hull. The buffer is the polygon generated from an offset at each feature's vertices. The distance value will be used to buffer the features.

Possible Values:"buffer"|"convexhull"

distance Number

The buffer or padding added to the result area.

Units for linear measurements.

areaUnit AreaUnits

Units for area measurements.

color GraphicColor

The color for the result area graphic.

show Boolean

Determines if the area is shown on the map.

TraceItem

Type Definition
TraceItem Object

TraceItem extends the named trace configuration and adds a property to manage the selection on the view.

Property
selected Boolean

Returns true if there is a selection on the view for a trace.

TraceResultExtend

Type Definition
TraceResultExtend Object

TraceResultExtend organizes the results based on the trace configuration and the trace results.

Properties
TraceItem TraceItem

TraceItem extends the named trace configuration and adds a property to manage the selection on the view.

TraceResult TraceResult

The collection of results returned from the trace.

selectionEnabled Boolean

Returns true if selection is enabled.

graphicEnabled Boolean

Returns true if graphic is enabled.

graphicColor GraphicColor

The color for the graphic of the trace results in the graphics layer.

status String

The current status of the trace to return errors from the server.

ValidSetup

Type Definition
ValidSetup Object

ValidSetup verifies whether a trace meets all the requirements before it can execute.

Properties
status Boolean

Is true if the requirements are met.

issues String[]

An array of error messages for the missing requirements.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.