Trace parameters

TraceA trace is an action that analyzes the paths in a utility network and returns features based on connectivity or traversability from the specified starting points.Learn more parameters specify how the trace analysis proceeds across the utility networkA utility network is a feature service that represents a utility system, such as water, gas, or electricity. A utility network provides the capabilities to visualize, edit, and analyze utility assets and data.Learn more. Essential trace parameters, described in this section, include:

• Trace type
• Trace locations
• Trace configuration
• Trace results

Trace type

Use one of the supported traces (such as upstream, downstream, subnetwork, and so on) to create the parameters with starting locations. Refer to the Trace a utility network overview for a description of the supported trace types.

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
        let traceParameters = UtilityTraceParameters(traceType: .downstream, startingLocations: startingLocations)

Trace locations

A trace location can be one of the following:

• Starting point
• Barrier
• Filter barrierA filter barrier is a setting in a trace configuration that specifies when an isolation trace will stop for a specific category or network attribute.Learn more

All of the traces except shortest path require at least one starting point. Barriers are optional. A filter barrier is only required for an isolation traceAn isolation trace is a trace that is used to determine the minimum set of operable assets (point and line features) required to stop a utility network's resource from traveling / flowing, effectively isolating an area of the network.Learn more when no trace filter barrier condition was specified. The respective collections for these contain UtilityElement objects that can be created as explained in the Analyze your network topic.

Once you have a utility elementA utility element is an entity in a utility network that corresponds to a feature or a part of a feature (for example, a terminal inside a device).Learn more, you can add it to the collection that fits its purpose.

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
        traceParameters.addStartingLocation(startingElement)
        traceParameters.addBarrier(barrierElement)
        traceParameters.addFilterBarrier(filterBarrierElement)

Trace configuration

A trace configuration allows you to do things like:

• Stop the trace at protective devices if they are open. For example, the flow of electricity in a network will be stopped if a fuse is open.
• Control the types of features traced. For example, trace only pipes with a diameter greater than six inches.
• Filter the types of features returned as trace results. For example, only return elements identified by the trace that represent wooden poles.
• Define functions to run calculations on network attributesAttributes are fields and values for a single feature or non-spatial record. They are typically stored in a database or service such as a feature service.Learn more associated with traced features. For example, the sum of the length of all the wire traced. Several functions can be specified for a trace.

See the Trace configuration topic for more information.

Below is an example of trace configuration for isolation trace.

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
        let traceConfiguration = UtilityTraceConfiguration()
        traceConfiguration.domainNetwork = utilityNetwork.definition?.domainNetwork(named: ("Water"))
        traceConfiguration.sourceTier = traceConfiguration.domainNetwork?.tier(named: "Water Pressure")

        let filter = UtilityTraceFilter()
        let barriers = UtilityCategoryComparison(categoryName: "Isolating", operator: .exists)
        filter.barriers = barriers
        traceConfiguration.filter = filter
        traceParameters.traceConfiguration = traceConfiguration

Trace results

You can add a variety of trace result types (UtilityTraceParameters.ResultType) to the UtilityTraceParameters result types collection to define the results returned from a trace. At least one type of trace result is required, but you can request several.

• Element results—Provide information about the individual network features. This is the default result returned.
• Function results—Calculate values based on network attributesAttributes are fields and values for a single feature or non-spatial record. They are typically stored in a database or service such as a feature service.Learn more. Note that this type of result requires your trace configuration to include function inputs.
• Geometry results—Allow you to display the results on the map. This result type is supported by ArcGIS EnterpriseArcGIS Enterprise is a GIS mapping, analytics, data hosting, and content management product that can be hosted on-premise or in a cloud infrastructure. It includes software, applications, tools, APIs, and services for users and developers.Learn more 10.8.1 or later and for mobile geodatabaseA mobile geodatabase (.geodatabase) is a spatial data storage format in a single file on disk that can store, query, and manage spatial and nonspatial data. In applications built with the ArcGIS Maps SDKs for Native Apps, mobile geodatabases can be used in offline workflows when taking maps and features offline from services or in desktop-based scenarios as standalone mobile geodatabases from ArcGIS Pro.Learn more, you need ArcGIS Maps SDKs for Native Apps version 200.1 or later.

See the Work with trace results topic for more information about trace results.

The following example shows creating a trace function, including it with the trace configuration, and requesting its result in the output.

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
        guard let shapeLengthAttribute = utilityNetwork.definition?.networkAttribute(named: ("Shape length")) else { return }
        let addShapeLength = UtilityTraceFunction(functionType: .add, networkAttribute: shapeLengthAttribute)
        traceParameters.traceConfiguration?.addFunction(addShapeLength)
        traceParameters.addResultType(.functionOutputs)