Trace

  • URL:http://<utilitynetworkservice-url>/trace
  • Version Introduced:10.6

Description

A trace refers to a pre-configured algorithm that systematically travels a network to return results. Generalized traces allow you to trace across multiple types of domain networks. For example, running a Connected trace from your electric network through to your gas network. An assortment of options is provided with trace to 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 it reflects the most recent edits or updates made to the network.

License:
The ArcGIS Utility Network Management extension is required to use these resources.

Request Parameters

ParameterDetails
F

Description: Optional parameter representing the output format of the response (default is JSON).

gdbVersion

Description: The name of the geodatabase version.

Syntax: gdbVersion=<version>

sessionId

Description: Optional parameter representing 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 which holds the exclusive lock.

Syntax: sessionId=<guid>

moment

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

traceType

Description: The trace type.

Syntax:

"connected " | " subnetwork " | " subnetworkController " | " upstream " | " downstream " | " loops " | " shortestPath "
traceLocations

Description: The locations for starting and stopping points, as well as barriers. Optional parameter for subnetwork trace type, required parameter for all other trace types.

Syntax:

Syntax for traceLocations

[
  {
    "traceLocationType" : "startingPoint" | "barrier" 
                        | "stoppingPoint"
    "globalId" : <guid>,
    "terminalId" : <long>,    // optional
    "percentAlong" : <double> // optional
  }
]

traceConfiguration

Description: Optional parameter representing the collection of trace configuration parameters (see below).

Syntax: traceConfiguration=<traceConfiguration>

resultFields

Description : Optional parameter that specifies which fields on the elements to return (default is none).

Syntax:

[
  { 
    "layerId" : <layerId>,
    "resultFields" : [ <field1>, <field2>, . . . ]
  }
]
resultType

Description : Optional parameter representing the type of results to return.

Values: "elements" | "connectivity" | "networkAttributes" | "assetInfo" | "aggregateGeometry" | "diagram"

traceConfiguration Properties

PropertyDetails
includeContainers

Description: Optional parameter representing whether or not to include containers in the trace result (default is false).

Values: " true " | " false "

includeContent

Description: Optional parameter representing whether or not to include content in the trace result (default is false).

Values: " true " | " false "

includeStructures

Description: Optional parameter representing whether or not to include structures in the trace result (default is false).

Values: " true " | " false "

includeBarriers

Description: Optional parameter representing whether or not to include barrier features that stop a trace in the trace result (default is true).

Values: " true " | " false "

validateConsistency

Description: Optional parameter representing whether or not to validate the consistency of the trace results (default is false).

Values: " true " | " false "

domainNetworkName

Description: Optional parameter that specifies the name of the domain network where the trace is starting.

Syntax: domainNetworkName=<string>

tierName

Description: Optional parameter that specifies the name of the tier where the trace is starting.

Syntax: tierName=<string>

targetTierName

Description: Optional parameter representing the name of the tier where upstream or downstream trace ends.

Syntax: targetTierName=<string>

subnetworkName

Description: Optional parameter representing the name of the subnetwork that will be traced - the starting points of the trace will be the controllers of this subnetwork .

Syntax: subnetworkName=<string>

diagramTemplateName

Description: Optional parameter representing the name of the diagram template.

Syntax: designTemplateName=<string>

shortestPathNetworkAttributeName

Description: Required parameter for shortest path trace ; optional otherwise. It represents the network attribute name used for determining cost when calulating the shortest path.

Syntax: shortestPathNetworkAttributeName=<string>

filterBitsetNetworkAttributeName

Description: Optional parameter. Used during loops trace to only return loops with the same bit set all around the loop. Used during upstream/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 parameters representing which network element types the condition, category, or function barriers apply to (default is junctionsAndEdges).

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

conditionBarriers

Description: Optional parameter containing an array of objects (representing network attribute conditions) that serve as barriers - default is null. If isTypeSpecificValue is true, the network attribute is being compared with a specific value ; otherwise the network attribute is being compared with another network attribute.

Syntax:

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

categoryBarriers

array of string

The categories that serve as barriers (default is none) : optional parameter.

functionBarriers

array of objects; optional parameter.

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

filterCategories

array of string

A second pass is done over the trace results and all results after these categories are encountered are filtered (default is none) : optional parameter.

functions

Description: Optional parameter ; an array of objects representing functions. Each function may have an optional array of network attribute conditions.

Syntax:

Syntax:

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

nearestNeighbor

object

This object specifies the parameters need for calculating nearest neighbors (default is null) ; optional parameter.

syntax for nearestNeighbor

{
  "count" : int
  "costNetworkAttributeName" : string
  "nearestCategories" : array of string
  "nearestAssets"
  [ 
    {
      "sourceId" : int
      "assetGroup" : int
      "assetType" : int
    }
  ]
}

outputFilterCategories

array of string

The categories associated with the output filter (default is none) ; optional parameter.

outputFilters

array of object (default is null)

Syntax:

[
  {
  "sourceId" : int
  "assetGroup" : int
  "assetType" : int
  }
]
propagators

array of object (default is null) ; optional parameter.

Syntax:

[
  {
    "networkAttributeName" : string
    "functionType" : "bitwiseAnd" | "min" | "max"
    "operator : "equal" | "notEqual" 
              | "bitwiseAnd" | "greater" 
              | "greaterEqual" | "less" 
              | "lessEqual"
    "value" : string (numeric)
  }
]

JSON Response Syntax

JSON response syntax for trace

JSON Response:

{
  "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
      }
    ],
    "url" : "<url>",              // url of created connectivity file
    "diagramName" : <string>,
    "globalFunctionResults" : [
      {
        "functionType" : "add" | "average" | "count" | "max" | "min" | 
                         "subtract",
        "networkAttributeName" : <string>,
        "result" : <double>
      }
    ],
  "isConsistent" : <true | false>,
  "kFeaturesForKNNFount" : <true | false>,
  "startingPointsIgnored" : <true | false>,
  "warnings" : [ <string> ]
  }
  "success" : <true | false>,
  "error" : {                   // only if success is false
    "hresult" : <HRESULT>,
    "message" : <error message>,
    "details" : [ <detail> ]
  }
}

Connectivity file JSON format:

{ 
  "type" : "tabular",
  "sourceMapping" : { "<sourceId1>" : <sourceName1>, 
                      "<sourceId2>" : <sourceName2>, . . .
  }
  "rows" : [
    {
      "viaSourceId" : <long>, 
      "viaGlobalId" : <guid>, 
      "viaSubtypeName" : <name>, 
      "viaGeometry" : <geometry>,
      "fromSourceId" : <long>, 
      "fromGlobalId" : <guid>, 
      "fromSubtypeName" : <name>, 
      "fromTerminalId" : <long>, 
      "fromGeometry" : <geometry>
      "toSourceId" : <long>, 
      "toGlobalId" : <guid>, 
      "toSubtypeName" : <name>, 
      "toTerminalId" : <long>, 
      "toGeometry" : <geometry>
    }
  ]
  "controllers: [
    {
      "networkSourceId" : <long>, 
      "globalId" : <guid>, 
      "objectId" : <oid>,
      "terminalId" : <long>,
      "controllerName" : <name>,
      "subnetworkName" : <name>
    },
    {
      "networkSourceId" : <long>, 
      "globalId" : <guid>, 
      "objectId" : <oid>,
      "terminalId" : <long>,
      "controllerName" : <name>,
      "subnetworkName" : <name>
    },
  ]
}