Skip To Content

Traverse

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.

Note:

Associations are not traversed from spatial features to nonspatial objects and back to spatial features when the exit filter is placed on the first spatial feature.

Request parameters

ParameterDetails
f

Description: The response format. The default response format is html.

Values: html | json

gdbVersion

Description: Optional parameter specifying the name of the geodatabase version. The default is Default.

Syntax: gdbVersion=<version>

moment

Description: Optional parameter specifying 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>

type

Description: Optional parameter that specifies the type of traversal to perform. The default value is unspecified.

Values: "unspecified" | "dirtyAreaExpansion" | "firstContainers" | "spatialParents" | "topContainers" | "errorsNotModified" | "modifiedObjects"

direction

Description: Optional parameter specifying the direction of the association traversal. The default is descending.

Values: "ascending" | "descending"

dirtyStatusFilter

Description: Optional parameter specifying 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.

Values: "none" | "dirty" | "notDirty"

errorStatusFilter

Description: Optional parameter specifying whether to filter associations based on the error code. The default is none.

Values: "none" | "inError" | "notInError"

stopAtFirstSpatial

Description: 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.

Values: true | false

maxDepth

Description: Optional parameter to control 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

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

Syntax:

[ 
  {
    “networkSourceId” : <long>,
    “globalId” : <guid>,
    “terminalId” : <long>   // optional
  }
]

JSON Response syntax

{
   "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


direction=ascending
stopAtFirstSpatial=false
elements=[{"networkSourceId":19,"globalId":"{AE323515-8E6F-4CC2-B9A8-1DB963E769AB}"}]
{
	"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
}