Skip To Content
ArcGIS Developers
Dashboard

Trace

Description

A trace refers to a preconfigured algorithm that systematically travels a network to return results. Generalized traces allow you to trace across multiple types of domain networks. For example, you can run a connected trace from your electric network through to your gas network. Multiple parameters and properties are provided with the trace operation that support various analytic work flows. All traces use the network topology to read cached information about network features. This can improve performance of complex traces on large networks. Trace results are not guaranteed to accurately represent a utility network when dirty areas are present. The network topology must be validated to ensure that it reflects the most recent edits or updates made to the network.

Learn more about utility network trace types

License:
The active portal account must be licensed with the ArcGIS Utility Network user type extension to use this operation.

Request parameters

ParameterDetails
f

Description: Optional parameter specifying the output format of the response. 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>

sessionId

Description: Optional parameter specifying the token (GUID) used to lock the version. If the calling client has previously started a service session (editing) and holds an exclusive lock on the specified version, the request will fail if the sessionId is not provided. If the specified version is currently locked by any other session, the request will fail if the sessionId is not provided or does not match the sessionId that holds the exclusive lock.

Syntax: sessionId=<guid>

moment

Description: Optional parameter specifying the session moment (the default is the version current moment). This should only be specified by the client when they do not want to use the current moment.

Syntax: moment=<Epoch time in milliseconds>

traceType

Description: The trace type. This required parameter specifies the core algorithm that will be executed to analyze the network. Trace types can be configured using the traceConfiguration parameter.

Values: <connected | subnetwork | subnetworkController | upstream | downstream | loops | shortestPath | isolation>

Syntax: traceType=<traceType>

Example: traceType=subnetwork

traceLocations

Description: The locations for starting points and barriers. An empty array must be used when performing a subnetwork trace if a subnetworkName is provided as part of the traceConfiguration—for example, traceLocations=[].

The trace location is ignored by the trace if the following required properties are not defined:

  • A percentAlong value is required for edge features and objects.
  • A terminalID value is required for junction features and objects.

Syntax:

[
 {
  "traceLocationType" : "startingPoint" | "barrier", 
  "globalId" : <guid>,
  "terminalId" : <long>,   // optional
  “percentAlong” : <double>, // optional
  "isFilterBarrier" : true | false // optional Introduced at 10.8.1
 }
]

traceConfiguration

Description: Optional parameter specifying the collection of trace configuration properties. Depending on the trace type, some of the trace configuration properties are required.

To reference the collection of trace configuration properties, see the traceConfiguration properties section below.

Syntax: traceConfiguration=<traceConfiguration>

Learn more about using multiple conditional expressions

traceConfigurationGlobalId

Description: Optional parameter. The global ID of a named trace configuration. When specified, this configuration is used instead of the traceConfiguration parameter. Additionally, named trace configurations are persisted with their own trace type so the trace type parameter is ignored.

This parameter was introduced at ArcGIS Enterprise 10.9.

Syntax: traceConfigurationglobalId=<guid>

resultType

This parameter was deprecated at 10.8.

resultTypes

Description: Optional parameter specifying the types of results to return.

Syntax :

[
  { 
    "type" : "elements" | "aggregatedGeometry",
    "includeGeometry" : true | false,
    "includePropagatedValues": true | false,
    "networkAttributeNames" :["attribute1Name","attribute2Name",...],
    "diagramTemplateName": <value>, 
    "resultTypeFields":[{"networkSourceId":<long>,"fieldname":<value>},...]
  },...
]

traceConfiguration properties

The traceConfiguration parameter is a collection of trace configuration properties that include basic properties for a trace and control trace settings for traversability, functions, filters, outputs, and propagators.

PropertyDetails
includeContainers

Description: Optional property specifying whether to include containers in the trace result. The default is false.

Values: <true | false>

includeContent

Description: Optional property specifying whether to include content in the trace result. The default is false.

Values: <true | false>

includeStructures

Description: Optional property specifying whether to include structures in the trace result. The default is false.

Values: <true | false>

includeBarriers

Description: Optional property specifying whether to include barrier features that stop a trace in the trace result. The default is true.

Values: <true | false>

validateConsistency

Description: Optional property specifying whether to validate the consistency of the trace results. The default is true.

Values: <true | false>

validateLocatability

Description: Optional property specifying whether to validate whether traversed junction or edge objects have the necessary containment, attachment, or connectivity association in their association hierarchy. The default is false.

Values: <true | false>

includeIsolated

Description: Optional property specifying whether to include isolated features for an isolation trace. The default is false.

Values: <true | false>

ignoreBarriersAtStartingPoints

Description: Optional property specifying whether dynamic barriers in the trace configuration are ignored for starting points. This can be useful when performing an upstream protective device trace using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices. The default is false.

Values: <true | false>

includeUpToFirstSpatialContainer

Description: Optional property specifying whether to limit the containers returned in the trace result. This property depends on the includeContainers property and no-ops if includeContainers is false. If includeContainers is true and this property is true, containment associations up to and including the first spatial container are returned; otherwise, all containment associations are returned. The default is false.

Values: <true | false>

allowIndeterminateFlow

Description: Optional property specifying whether network features with indeterminate flow stop traversability and are included in the trace results. This property is only honored when running an upstream or downstream trace.

Values: <true | false>

domainNetworkName

Description: Specifies the name of the domain network where the trace is starting. This is required for subnetwork-based traces.

Syntax: domainNetworkName=<string>

tierName

Description: Specifies the name of the tier where the trace is starting. This is required for subnetwork-based traces.

Syntax: tierName=<string>

targetTierName

Description: Optional property that specifies the name of the tier where an upstream or downstream trace ends.

Syntax: targetTierName=<string>

subnetworkName

Description: Optional property that specifies the name of the subnetwork that will be traced. The starting points of the trace are the controllers of this subnetwork.

Syntax: subnetworkName=<string>

shortestPathNetworkAttributeName

Description: Required property for a shortest path trace; otherwise, it's optional. It specifies the network attribute name used for determining cost when calculating the shortest path.

Syntax: shortestPathNetworkAttributeName=<string>

filterBitsetNetworkAttributeName

Description: Optional property used during a loops trace to only return loops with the same bit set all around the loop. This is used during upstream and downstream traces to ensure that trace results include any bit that is set in the starting points for the network attribute.

Syntax: filterBitsetNetworkAttributeName=<string>

traversabilityScope

Description: Optional property specifying the network element types to which the condition, category, or function barriers apply. The default is junctionsAndEdges.

values : "junctions" | "edges" | "junctionsAndEdges"

filterScope

Description: Optional property specifying the network element types to which the filter barriers or filter function barriers apply. The default is junctionsAndEdges.

values : "junctions" | "edges" | "junctionsAndEdges"

conditionBarriers

Description: Optional property containing an array of objects (representing network attribute or category conditions) that serve as barriers (the default is null). If isSpecificValue is true, the network attribute is compared to a specific value; otherwise, the network attribute is compared to another network attribute.

Syntax:

[
  {
    "name" : <string>,
    "operator" : "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny",
    "value" : <string>,
    "combineUsingOr" : <true | false>,
    "isSpecificValue" : <true | false>
  }
]

Learn more about using multiple conditional expressions

functionBarriers

Description: Optional property. This is an array of objects representing function barriers.

Syntax:

[
  {
    "functionType" : "add" | "subtract" |
                   "average" | "count" |
                   "min" | "max",
    "networkAttributeName" : <string>,
    "operator" : "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny",
    "value" : <string>
  }
]

filterBarriers

Description: Optional property containing an array of objects (representing network attribute or category conditions) that serve as barriers (the default is null). If isSpecificValue is true, the network attribute is compared to a specific value; otherwise, the network attribute is compared to another network attribute.

[
  {
    "name" : <string>,
    "operator" : "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny",
    "value" : string (numeric),
    "combineUsingOr" : <true | false>,
    "isSpecificValue" : <true | false>
  }
]

Learn more about using multiple conditional expressions

filterFunctionBarriers

Description: Optional property. This is an array of objects representing filter function barriers.

[
  {
    "functionType" : "add" | "subtract" |
                   "average" | "count" |
                   "min" | "max",
    "networkAttributeName" : <string>,
    "operator" : "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny",
    "value" : string (numeric)
  }
]

functions

Description: Optional property. This is an array of objects representing functions. Each function can have an optional array of network attribute conditions.

Syntax:

[
  {
    "functionType" : "add" | "subtract" 
                   | "average" | "count" 
                   | "min" | "max",
    "networkAttributeName" : <string>, 
    "conditions":
    [
      {
        "name" : <string>,
        "type" : "networkAttribute" | "category",
        "operator" : "equal" | "notEqual" 
               | "greaterThan"    
               | "greaterThanEqual |  
               | "lessThan" 
               | "lessThanEqual" 
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny", 
        "value" : <string>,
        "combineUsingOr" : <true | false>,
        "isSpecificValue" : <true | false>
     }
   ] 
 }
]

Learn more about using multiple conditional expressions

nearestNeighbor

Description: Optional property that specifies the parameters needed for calculating nearest neighbors. The default is null.

{
  "count" : int
  "costNetworkAttributeName" : string,
  "nearestCategories" : array of string,
  "nearestAssets"
  [ 
    {
      "networkSourceId" : long,
      "assetGroupCode" : long,
      "assetTypeCode" : long
    }
  ]
}

outputFilters

Description: Optional property specifying the output filter: an array of objects. The default is null.

[
 {
  "networkSourceId" : long,
  "assetGroupCode" : long,
  "assetTypeCode" : long
 }
]
outputConditions

Description: Optional property specifying the type of features returned based on a network attribute or category.

[
 {
  "name": "<string>",
  "type": "networkAttribute" | "category",
  "operator": "equal" | "notEqual"
               | "greaterThan"
               | "greaterThanEqual"
               | "lessThan"
               | "lessThanEqual"
               | "includesTheValues"
               | "doesNotIncludeTheValues"
               | "includesAny"
               | "doesNotIncludeAny",
 	"value": <string>,			
  "combineUsingOr": <true | false>,
  "isSpecificValue": <true | false>
 }	
]

Example:

[
 {
  "name": "Line Asset Group",
  "type": "networkAttribute",
  "operator": "equal",
  "value": 1,			
  "combineUsingOr": false,
  "isSpecificValue": true
 }	
]

Learn more about using multiple conditional expressions

propagators

Description: Required property. This is an array of objects. The default is null.

[
 {
  "networkAttributeName" : "<string>",
  "substitutionAttributeName": "<string>",
  "propagatorfunctionType" : "bitwiseAnd" | "min", | "max"
  "operator : "equal" | "notEqual" 
               | "greaterThan" 
               | "greaterThanEqual" 
               | "lessThan"
               | "lessThanEqual" 
               | "includesTheValues” 
               | "doesNotIncludeTheValues" 
               | "includesAny" 
               | "doesNotIncludeAny",
  "value" : string (numeric),
  "propagatedAttributeName": "<string>"
 }
]

JSON Response syntax

{
  "traceResults" : {
    "elements" : [
      {
        "networkSourceId" : <long>,
        "globalId" : <guid>,
        "objectId" : <oid>
        "terminalId" : <long>,            // optional
        "networkAttributes" : [           // optional
          "<networkAttribute1>" : <long>, // optional
          "<networkAttribute2>" : <long>  // optional
        ],                                // optional
        "assetGroup" : <long>,            // optional
        "assetType" : <long>,              // optional
        "positionFrom" : <double>,         // optional 
        "positionTo" : <double>           // optional
      }
    ],
    "aggregatedGeometry" : { 
      "point" : <aggregated point geometry>, 
      "line" : <aggregated line geometry>,
      "polygon" : <aggregated polygon geometry> 
    }, 
    "globalFunctionResults" : [
      {
        "functionType" : "add" | "average" | "count" | "max" | "min" | 
                         "subtract",
        "Name" : <string>,
        "result" : <double>
      }
    ],
    "isConsistent" : <true | false>,
    "kFeaturesForKNNFound" : <true | false>,
    "startingPointsIgnored" : <true | false>,
    "warnings" : [ <string> ]
  }
  "success" : <true | false>,
  "error" : {                   // only if success is false
    "extendedCode" : <HRESULT>,
    "message" : <error message>,
    "details" : [ <detail> ]
  }
}

Example usage

Perform a subnetwork trace for the ElectricDistribution domain network Medium Voltage Radial tier. The trace operation request includes the traceConfiguration parameter.

Request URL and parameters:

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

f=json
gdbVersion=SDE.DEFAULT
sessionID={55DCF5E1-4DB9-478A-8B0C-65E5F37F5D16}
moment=1554214441244
traceType=subnetwork
traceLocations=
[
 {
  "traceLocationType": "startingPoint",
  "globalId": "{BBF88249-6BAD-438F-9DBB-0E48DD89EECA}",
  "percentAlong": 0.5805425412252266	
 }
]
traceConfiguration=
{
 "includeContainers": true,
 "includeContent": false,
 "includeStructures": true,
 "includeBarriers": true,
 "validateConsistency": true,
 "validateLocatability": false,
 "includeIsolated": false,
 "ignoreBarriersAtStartingPoints": false,
 "includeUpToFirstSpatialContainer":false,
 "allowIndeterminateFlow":true,
 "domainNetworkName": "ElectricDistribution",
 "tierName": "Medium Voltage Radial",
 "targetTierName": "",
 "subnetworkName": "",
 "diagramTemplateName": "",
 "shortestPathNetworkAttributeName": "",
 "filterBitsetNetworkAttributeName": "",
 "traversabilityScope": "junctionsAndEdges",
 "conditionBarriers": [
		{
			"name": "Operational Device Status",
			"type": "networkAttribute",
			"operator": "equal",
			"value": 1,
			"combineUsingOr": false,
			"isSpecificValue": true
		}
 ],
 "functionBarriers": [],
 "arcadeExpressionBarrier": "",
 "filterBarriers": [],
 "filterFunctionBarriers": [],
 "filterScope": "junctionsAndEdges",
 "functions": [],
 "nearestNeighbor": {
		"count": -1,
		"costNetworkAttributeName": "",
		"nearestCategories": [],
		"nearestAssets": []	
 },
 "outputFilters": [],
 "outputConditions": [],
 "propagators": []
}

JSON response:

{
  "traceResults": {
		"elements": [
			{
				"networkSourceId": 5,
				"globalId": "{54E80EBF-343E-4CAB-89F7-89712E653F05}",
				"objectId": 1,
				"terminalId": 1,
				"assetGroupCode": 102,
				"assetTypeCode": 83
			},
			{
				"networkSourceId": 3,
				"globalId": "{89ADD4A3-EB2B-451C-AA6F-0AE94C6A9198}",
				"objectId": 1245,
				"terminalId": 1,
				"assetGroupCode": 106,
				"assetTypeCode": 201
			},
			{<more network elements>}
		],
		"diagramName": "<placeholder>",
		"globalFunctionResults": [],
		"kFeaturesForKNNFound": false,
		"startingPointsIgnored": false,
		"warnings": []	
  },
  "success": true
}