Work with utility elements

An array of analysis and tracing options usually begin with or include a utility element in the result. This element corresponds to a network feature or object that contains additional information such as a terminal or fraction along value that affects the analysis. For example, the utility element's terminal may limit the number of connectivity associations or change the direction of a trace, while its fraction along value may return a partial geometry from a trace.

This utility element may be created from a feature or asset type with a global id. The feature may be a result of a query or identify operation on a layer or table that is part of the utility network.

Utility element from a feature

You may query for a specific feature using any of its fields or geometry or interactively identify a feature in a map view. When using identify, the feature may be found in the GeoElement list immediately under IdentifyLayerResult when part of a FeatureLayer or from sublayerResults when part of a SubtypeFeatureLayer.

Use dark colors for code blocksCopy
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
        let queryParameters = QueryParameters()
        queryParameters.whereClause = "GlobalId like '{D353C10C-E617-4618-BDD0-B48EDB822D07}'"
        let queryResult = try await table.queryFeatures(using: queryParameters)
        let feature = queryResult.features().first
Use dark colors for code blocksCopy
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
            let identifyLayerResult = try await mapViewProxy.identify(on: layer, screenPoint: screenPoint, tolerance: 5)
            // Identifies the first feature of the feature layer.
            guard let firstFeature = identifyLayerResult.geoElements.first else { return }
            let firstFeatureLayerFeature = firstFeature as? ArcGISFeature

            // Identifies the first feature from the sublayers' result.
            guard let firstSublayerResult = identifyLayerResult.sublayerResults.first else { return }
            let firstSublayerFeature = firstSublayerResult.geoElements.first as? ArcGISFeature
Use dark colors for code blocksCopy
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
            try await firstSublayerFeature?.load()
            guard let feature = firstSublayerFeature else { return }
            let element = utilityNetwork.makeElement(arcGISFeature: feature)

Utility element from an asset type

An asset type can come from another utility element or be derived from a feature in the utility network, except from a subnet line table that does not have an asset type. You can use the feature's table name to get its network source. Use the network source and the feature's subtype to get its asset group. From the asset group, you can select an asset type by name or code.

Use dark colors for code blocksCopy
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
        // Gets the asset type from an element.
        let assetType = otherElement.assetType
        // Makes a new utility element from the asset type and global ID.
        let element = utilityNetwork.makeElement(assetType: assetType, globalID: globalID)

        // Gets the network source with the specified name.
        guard let tableName = feature.table?.tableName else { return }
        var networkSource = utilityNetwork.definition?.networkSource(named: tableName)
        // Gets the asset group with the subtype name.
        guard let subtypeName = feature.subtype?.name else { return }
        var assetGroup = networkSource?.assetGroup(named: subtypeName)

        // Gets an asset type from a feature's asset type code.
        let assetTypeCode = feature.attributes["ASSETTYPE"] as? Int
        guard let featureAssetType = assetGroup?.assetTypes.first(where: { $0.code == assetTypeCode }) else { return }
        // Makes a new utility element with the feature's asset type.
        let element1 = utilityNetwork.makeElement(assetType: featureAssetType, globalID: globalID)

        // Gets the asset type by name.
        networkSource = utilityNetwork.definition?.networkSource(named: "Electric Distribution Device")
        assetGroup = networkSource?.assetGroup(named: "Service Point")
        guard let lowVoltageAssetType = assetGroup?.assetType(named: "Single Phase Low Voltage Meter") else { return }
        // Makes a new utility element with the low voltage asset type.
        let element2 = utilityNetwork.makeElement(assetType: lowVoltageAssetType, globalID: globalID)

Utility element properties

A terminal is required when a UtilityElement that supports more than one terminal is used in a trace and optional when used to get associations. Terminals impact traces and connectivity associations.

Use dark colors for code blocksCopy
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
        if let terminalsCount = element.assetType.terminalConfiguration?.terminals.count,
           terminalsCount > 1 {
            element.terminal = element.assetType.terminalConfiguration?.terminals.first

        }

If the feature represents a line, you can optionally specify a location along the line to use as a trace location. This value is a percentage of the length of the line, beginning from the line's 'from' point.

Use UtilityElement.fractionAlongEdge to define the location of the point along the line.

The following example uses the GeometryEngine to get the fraction of a tap location along the line.

Use dark colors for code blocksCopy
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
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
            if element.networkSource.kind == UtilityNetworkSource.Kind.edge {
                var line = feature.geometry as? Polyline
                if let polyline = line,
                   polyline.hasZ {
                    // If the polyline has a Z value, remove it.
                    let line2 = GeometryEngine.makeGeometry(from: polyline, z: nil)
                    line = line2
                }
                if mapPoint.spatialReference != nil,
                   let polyline = line,
                   polyline.spatialReference != mapPoint.spatialReference,
                   let projectedLine = GeometryEngine.project(polyline, into: mapPoint.spatialReference!) {
                    // Projects the line to the map point's spatial reference, if not already equivalent.
                    line = projectedLine
                }
                guard let polyline = line else { return }
                // Calculates and sets the fraction of a tap location along the line.
                let percentAlong = GeometryEngine.polyline(polyline, fractionalLengthClosestTo: mapPoint, tolerance: .nan)
                if !percentAlong.isNaN {
                    element.fractionAlongEdge = percentAlong
                }
            }

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.