- URL: https://<associations-url>/traverse(POST only)
- 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.
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
| Parameter | Details |
|---|---|
| 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: |
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
}