Traverse (Associations) | ArcGIS REST APIs

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`. Values: `html` \| `json` \| `pjson`
`gdbVersion` (Optional)	Specifies the name of the geodatabase version. The default is `sde.Default`. Syntax: Use dark colors for code blocksCopy `1 2 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: Use dark colors for code blocksCopy `1 2 moment=<Epoch time in milliseconds>` Example: Use dark colors for code blocksCopy `1 2 moment=1651505446`
`type` (Optional)	Specifies the type of traversal to perform. The default value is "unspecified". Values: `unspecified` \| `dirtyAreaExpansion` \| `firstContainers` \| `spatialParents` \| `topContainers` \| `errorsNotModified` \| `modifiedObjects`
`direction` (Optional)	Specifies the direction of the association traversal. The default is `descending`. Values: `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. Values: `none` \| `dirty` \| `notDirty`
`errorStatusFilter` (Optional)	Specifies whether to filter associations based on the error code. The default is `none`. Values: `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`. Values: `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: Use dark colors for code blocksCopy `1 2 maxDepth=<short>`
`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.

Values: html | json | pjson

gdbVersion

(Optional)

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

Syntax:

Use dark colors for code blocksCopy

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:

Use dark colors for code blocksCopy

moment=<Epoch time in milliseconds>

Example:

Use dark colors for code blocksCopy

moment=1651505446

type

(Optional)

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

direction

(Optional)

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

Values: ascending | descending

dirtyStatusFilter

(Optional)

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

Values: none | dirty | notDirty

errorStatusFilter

(Optional)

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

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

Values: 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:

Use dark colors for code blocksCopy

maxDepth=<short>

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:

Use dark colors for code blocksCopy

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}"
  }
]

JSON response:

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
}