Traverse

URL:: https://<root>/<serviceName>/UtilityNetworkServer/associations/traverse
Methods:: POST
Required Capability:: Requires the ArcGIS Advanced Editing user type extension license
Version Introduced:: 10.9

Description

The traverse operation allows you to obtain and extract useful information from the associations table in a utility network.

The type parameter is used to provide the following predefined traversal types:

dirtyAreaExpansion—Returns associations and objects that have been modified and are marked as dirty. Completes a downward traversal, followed by an ascending traversal, with an exit filter on the first spatial feature in each direction.
firstContainers—Completes an ascending traversal on containment associations, with an exit filter on the first spatial feature.
spatialParents—Completes an ascending traversal on all association types, with an exit filter on the first spatial feature.
topContainers—Completes an ascending traversal to return associations and objects with no exit filter.
errorsNotModified—Completes a downward traversal to return associations in error, with an exit filter on the first spatial feature.
modifiedObjects—Completes a downward traversal to return associations that are dirty, with an exit filter on the first spatial feature.

To create a custom traversal the direction, dirtyStatusFilter, errorStatusFilter, stopAtFirstSpatial, and maxDepth parameters can be used. When a traversal type is specified using the type parameter other than the default unspecified, these parameters are ignored.

Request parameters

Parameter Details

Parameter	Details
`f`	The response format. The default response format is `html`. Use dark colors for code blocksCopy `1 f=html \| json \| pjson`
`gdbVersion` (Optional)	Specifies the name of the geodatabase version. The default is `sde.Default`. Syntax: `gdbVersion=<version>`
`moment` (Optional)	Specifies the session moment. The default is the version's current moment. This should only be specified when you do not want to use the current moment. Syntax: `moment=<Epoch time in milliseconds>` Example: `moment=1651505446`
`type` (Optional)	Specifies the type of traversal to perform. The default value is "unspecified". Use dark colors for code blocksCopy `1 type=unspecified \| dirtyAreaExpansion \| firstContainers \| spatialParents \| topContainers \| errorsNotModified \| modifiedObjects`
`direction` (Optional)	Specifies the direction of the association traversal. The default is `descending`. Use dark colors for code blocksCopy `1 direction=ascending \| descending`
`dirtyStatusFilter` (Optional)	Specifies whether to filter based on the dirty status of the association. The default is `none`. Note When `dirtyStatusFilter` and `errorStatusFilter` are specified together, the filters are combined using an AND expression. Use dark colors for code blocksCopy `1 dirtyStatusFilter=none \| dirty \| notDirty`
`errorStatusFilter` (Optional)	Specifies whether to filter associations based on the error code. The default is `none`. Use dark colors for code blocksCopy `1 errorStatusFilter=none \| inError \| notInError`
`stopAtFirstSpatial` (Optional)	Boolean parameter specifying whether to stop the traversal of associations from nonspatial object to feature when a spatial feature is encountered. The traversal will stop at the feature and will not traverse to the next nonspatial object. The default is `true`. Use dark colors for code blocksCopy `1 stopAtFirstSpatial=true \| false`
`maxDepth` (Optional)	Specifies how many hops through the association graph are allowed in either the ascending or descending direction. The default is `MAX_INT`. Syntax: `maxDepth=<integer>`
`elements` (Optional)	The feature or object elements for which the association traversal is initiated. Syntax: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 [ { “networkSourceId” : <long>, “globalId” : <guid>, “terminalId” : <long> // optional } ]`

f

The response format. The default response format is html.

Use dark colors for code blocksCopy
f=html | json | pjson

gdbVersion

(Optional)

Specifies the name of the geodatabase version. The default is sde.Default.

Syntax: gdbVersion=<version>

moment

(Optional)

Specifies the session moment. The default is the version's current moment. This should only be specified when you do not want to use the current moment.

Syntax: moment=<Epoch time in milliseconds>

Example: moment=1651505446

type

(Optional)

Specifies the type of traversal to perform. The default value is "unspecified".

Use dark colors for code blocksCopy
type=unspecified | dirtyAreaExpansion |  firstContainers | spatialParents |  topContainers | errorsNotModified |  modifiedObjects

direction

(Optional)

Specifies the direction of the association traversal. The default is descending.

Use dark colors for code blocksCopy
direction=ascending | descending

dirtyStatusFilter

(Optional)

Specifies whether to filter based on the dirty status of the association. The default is none.

Use dark colors for code blocksCopy
dirtyStatusFilter=none | dirty | notDirty

errorStatusFilter

(Optional)

Specifies whether to filter associations based on the error code. The default is none.

Use dark colors for code blocksCopy
errorStatusFilter=none | inError | notInError

stopAtFirstSpatial

(Optional)

Boolean parameter specifying whether to stop the traversal of associations from nonspatial object to feature when a spatial feature is encountered. The traversal will stop at the feature and will not traverse to the next nonspatial object. The default is true.

Use dark colors for code blocksCopy
stopAtFirstSpatial=true | false

maxDepth

(Optional)

Specifies how many hops through the association graph are allowed in either the ascending or descending direction. The default is MAX_INT.

Syntax: maxDepth=<integer>

elements

(Optional)

The feature or object elements for which the association traversal is initiated.

Syntax:

Use dark colors for code blocksCopy
[
  {
    “networkSourceId” : <long>,
    “globalId” : <guid>,
    “terminalId” : <long>   // optional
  }
]

JSON Response syntax

Use dark colors for code blocksCopy
{
   "associations":[
      {
         "globalId":<guid>,
         "fromNetworkSourceId":<long>,
         "fromGlobalId":<guid>,
         "fromTerminalId":<long>,
         "toNetworkSourceId":<long>,
         "toGlobalId":<guid>,
         "toTerminalId":<long>,
         "percentAlong": <double>,
         "associationType":"connectivity" | "attachment" | "containment" | "junctionEdgeFromConnectivity" | "junctionMidspanConnectivity" | "junctionEdgeToConnectivity",
         "status":<long>,
         "errorCode":<long>,
         "errorMessage"<string>,
         "isContentVisible":<boolean>
      }
   ],
   "objects":[
      {
         "sourceId":<long>,
         "globalId":<guid>
      }
   ],
  “success” : <boolean>,
  “error” : {                   // only if success is false
    “extendedCode” : <HRESULT>,
    “message” : <string>,
    “details” : [ <string> ]
}
}

Example usage

Request URL and parameters:

https://myserver.esri.com/server/rest/services/LandUse/UtilityNetworkServer/associations/traverse

Use dark colors for code blocksCopy
direction=ascending
stopAtFirstSpatial=false
elements=[{"networkSourceId":19,"globalId":"{AE323515-8E6F-4CC2-B9A8-1DB963E769AB}"}]

Use dark colors for code blocksCopy
{
	"associations": [
		{
			"globalId": "{FC70F615-60E2-4898-B65C-CF3BB0C6A933}",
			"fromNetworkSourceId": 4,
			"fromGlobalId": "{38429E9F-E585-4B20-BBD6-A7111E45C3AD}",
			"fromTerminalId": -1,
			"toNetworkSourceId": 16,
			"toGlobalId": "{0C75A4A0-7FCD-4078-90F3-9E1B124DD564}",
			"toTerminalId": -1,
			"associationType": "containment",
			"status": 0,
			"errorCode": 0,
			"errorMessage": "",
			"isContentVisible": true
},
		{
			"globalId": "{ABE73E74-B107-4527-967E-9283E5E12784}",
			"fromNetworkSourceId": 4,
			"fromGlobalId": "{B7E78E04-0E67-4287-88AE-08A4D135FA67}",
			"fromTerminalId": -1,
			"toNetworkSourceId": 19,
			"toGlobalId": "{AE323515-8E6F-4CC2-B9A8-1DB963E769AB}",
			"toTerminalId": -1,
			"associationType": "containment",
			"status": 0,
			"errorCode": 0,
			"errorMessage": "",
			"isContentVisible": true
		},
		{
			"globalId": "{EB0D71A6-7F4C-4521-A111-70B493141264}",
			"fromNetworkSourceId": 16,
			"fromGlobalId": "{0C75A4A0-7FCD-4078-90F3-9E1B124DD564}",
			"fromTerminalId": 1,
			"toNetworkSourceId": 19,
			"toGlobalId": "{AE323515-8E6F-4CC2-B9A8-1DB963E769AB}",
			"toTerminalId": 1,
			"associationType": "connectivity",
			"status": 0,
			"errorCode": 0,
			"errorMessage": "",
			"isContentVisible": true
		}
	],
	"objects": [
		{
			"sourceId": 16,
			"globalId": "{0C75A4A0-7FCD-4078-90F3-9E1B124DD564}"
		},
		{
			"sourceId": 4,
			"globalId": "{AE323515-8E6F-4CC2-B9A8-1DB963E769AB}"
		},
		{
			"sourceId": 4,
			"globalId": "{B7E78E04-0E67-4287-88AE-08A4D135FA67}"
		},
		{
			"sourceId": 4,
			"globalId": "{38429E9F-E585-4B20-BBD6-A7111E45C3AD}"
		}
	],
	"success": true
}