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

ParameterDetails

f

The response format. The default response format is html.

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

1
type=unspecified | dirtyAreaExpansion |  firstContainers | spatialParents |  topContainers | errorsNotModified |  modifiedObjects

direction

(Optional)

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

1
direction=ascending | descending

dirtyStatusFilter

(Optional)

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

1
dirtyStatusFilter=none | dirty | notDirty

errorStatusFilter

(Optional)

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

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.

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:

1
2
3
4
5
6
7
[
  {
    “networkSourceId” : <long>,
    “globalId” : <guid>,
    “terminalId” : <long>   // optional
  }
]

JSON Response syntax

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
   "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

1
2
3
direction=ascending
stopAtFirstSpatial=false
elements=[{"networkSourceId":19,"globalId":"{AE323515-8E6F-4CC2-B9A8-1DB963E769AB}"}]
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
{
	"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
}

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

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close