Configure a trace

Tracing a utility network is done to discover answers and solve problems with regard to the state of your network at any moment. To trace a utility network, use the Trace geoprocessing tool.

There are many types of traces provided with the Trace tool:

Along with these trace types, the Trace tool also includes a comprehensive set of advanced configurations used to refine each provided trace type. These configurations allow you to establish traversability, distinguish what features or objects should be returned, and set up calculations to be performed. ModelBuilder can be used to save complex configurations and reduce the number of parameters presented on the model tool interface. Named trace configurations can be used to create and store complex traces that can be shared across an organization. This helps you and others rerun advanced traces with just one click.

Setting subnetwork trace configurations in the subnetwork definition allows the Trace tool to be automatically populated when running a trace against a specific tier. This applies for subnetwork-based traces. For example, while you may always want your subnetwork traces to stop at protective devices to indicate the end of the feeder and to calculate the total load for each feeder, you probably do not want to set these parameters every time you run a subnetwork-based trace. This is the reason the ability to define a standard subnetwork definition for all subnetworks in a tier is provided. A subnetwork definition is set by the administrator when a tier is created. When the tier is specified in the Trace tool, the advanced parameters are automatically populated with the subnetwork trace definition set for the input tier. Any trace configuration parameters that are populated can be overwritten manually in the tool before running the trace.

During the setup of a trace, you can modify or add to the subnetwork trace configuration. You can do things such as control the types of features and objects traced (pipe diameter greater than 6 inches), choose what types of network features you want returned (all open valves), and perform calculations using network attributes (sum the length of the AB-phase lines).

Each configuration component is examined in the following sections. See the Trace tool for parameter options and usage information.

Run a trace asynchronously

Starting with ArcGIS Pro 2.9 and ArcGIS Enterprise 10.9.1, the Run in asynchronous mode on the server parameter provides the option to process trace operations asynchronously using the UtilityNetworkTools geoprocessing service. This option is only available when working with a utility network in an enterprise deployment. Trace operations process synchronously by default.

Configuration optionDescription

Run in asynchronous mode on the server

  • Checked—Trace operations will process asynchronously.
  • Unchecked—Trace operations will process synchronously. This is the default.

Define the trace region

In the Trace tool, you must specify where the trace is allowed to travel within your network. Defining a traceable area helps to ensure the intended part of the network is traced. It is also used to restrict traversal to other tiers for certain trace types. Three pieces of information are used to denote the extent of a traceable area: domain network, tier, and subnetwork. The type of trace determines the required pieces of information; therefore, not all traces will have these parameters.

Specifying a domain network restricts a trace to only that domain network. All subnetwork-based traces require a domain network to be set. Some traces require a tier and optional subnetwork to be specified. Other types of traces require a tier and a target tier to be set (upstream and downstream). A target tier allows you to trace across multiple tiers within a domain network.

The Tier parameter is used to restrict tracing to a particular tier when specified in the Trace tool. It is also used to automatically populate trace configuration parameters with values set for the subnetwork definition. When starting points are used in conjunction with the Tier parameter, the starting points must reside within the specified tier. The Target Tier parameter is used for Upstream and Downstream traces and indicates the boundary of the traceable network; a trace can traverse within, but not beyond, the target tier.

When tracing across multiple tiers, trace configuration settings are loaded for the initial tier. The following trace configuration settings are loaded for each new tier the trace encounters:

  • Traversability scope
  • Condition barriers
  • Function barriers
  • Propagators

For Subnetwork traces, providing a Subnetwork Name value allows you to specify what subnetwork to trace without the use of starting points. This approach uses the subnetwork controller or controllers for the specified subnetwork as the starting point for the trace.

Include containers, content, structures, and barriers in results

This set of configurable options in the Trace tool allows you to configure the network features that are included in the results based on their association role or barrier status. Association features can include containers, content, and structures. By default, everything except containers, their content, and structures is returned in the results of a trace.

Include Containers

Include containers in the results of a trace. Any containers for the content features and objects that are traced will also be included in the trace results. This configuration can also be used to trace a structure network, for example, returning connected underground ducts.

Configuration optionDescription

Include Containers

  • Checked—Container network features will be included in the trace results.
  • Unchecked—Container network features will not be included in the trace results. This is the default.

Include up to First Spatial Container

Specifies whether to limit the containers returned to include only those encountered up to, and including, the first spatial container for each network element in the trace results. If no spatial containers are encountered but nonspatial containers are present for a given network element, all nonspatial containers will be included in results. This parameter is only available when Include Containers is enabled.

Configuration optionDescription

Include up to First Spatial Container

  • Checked—Return all containers in the trace result for a network element up to, and including, the first spatial container when nested containment associations are encountered along the trace path. If no spatial containers exist, all nonspatial containers will be included in the results for a given network element.
  • Unchecked—All containers will be returned in the results. This is the default.

Include Content

Include content features and objects in the results of a trace. This encompasses content from containers that are included in the trace results. To clarify between the different types of containers, use an Output filter to filter your results.

Configuration optionDescription

Include Content

  • Checked—Content of container network features will be included in the trace results.
  • Unchecked—Content of container network features will not be included in the trace results. This is the default.

Include Structures

Include structures in the results of a trace. This is helpful for such tasks as reporting structural assets.

Configuration optionDescription

Include Structures

  • Checked—Structure features and objects will be included in the trace results.
  • Unchecked—Structure features and objects will not be included in the trace results. This is the default.

Include Barrier Features

Include barriers in the results of a trace. This encompasses feature barriers set on the Barriers tab in the Trace pane as well as any dynamically configured barriers: condition barriers, function barriers, filter barriers, and filter function barriers. The subnetwork definition can be used to configure whether barriers are included in trace results as part of the subnetwork trace configuration.

Note:

The selection set returned by a trace may display unexpected results when barriers are placed on edge features with midspan connectivity and the Include Barrier Features option is unchecked. If any part of the feature is returned by the trace, the entire feature is selected and displayed in the trace result.

Configuration optionDescription

Include Barrier Features

  • Checked—Barrier features will be included in the trace results. This is the default.
  • Unchecked—Barrier features will not be included in the trace results.

Note:
This trace configuration option is also influenced by the subnetwork trace configuration for subnetwork-based trace types. This is loaded when the Tier parameter is specified.

Note:

The Include Barrier Features configuration option does not apply to features with terminals.

Ignore Barriers At Starting Points

Ignore barriers in the trace configuration if they are starting points. This may be useful when performing an upstream protective device trace and using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices.

Configuration optionDescription

Ignore Barriers At Starting Points

  • Checked—Barriers at starting points will be ignored in the trace.
  • Unchecked—Barriers at starting points will not be ignored in the trace. This is the default.

Configure flow of resources

Understanding how resources flow along a network edge is essential when performing directional traces in the utility network. When you create or upgrade a utility network to version 7 or later, the Use Digitized Direction parameter is provided to perform an upstream and downstream trace. If you use a model that relies on the digitized direction of lines to determine the direction that resources flow in the network, this option may be beneficial. Do not use this option if you are currently modeling flow using subnetwork controllers. By default, trace operations in the utility network determine flow based on the location of subnetwork controllers.

When this is checked, the Domain Network, Tier, and Target Tier parameters are hidden and ignored. This parameter is only available and active for Utility Network Version 7 and later when the Trace Type is Upstream or Downstream.

Configuration optionDescription

Use Digitized Direction

  • Checked—Trace operations will determine flow direction using the digitized direction of the line, the From and To global ID of the edge object in the association, and the flow direction attribute.
  • Unchecked—Trace operations will determine flow direction based on the location of subnetwork controllers. This is the default.

Ensure network consistency

A consistent area of a network is one that does not have any dirty areas. Validating the network topology is the only way to guarantee a trace is reading the latest information about your network from the network topology. Some trace types require the subnetworks you trace to be clean as well. To learn more, see Subnetwork life-cycle.

The Validate Consistency option in the Trace tool allows you to ensure the trace results are consistent with the network topology. When Validate Consistency is set to true, the trace operation fails if any dirty areas intersect the trace path. When this occurs, an error is returned that includes the class name and global ID of any features or objects in the trace path that are found to be dirty, as shown in the example below:

ERROR 002041: One or more dirty areas were discovered.
[[ElectricDistributionLine: {C0060506-AG17-4B64-B2E0-9162BE613C05}]]
Failed to execute (Trace).

The following scenarios do not cause an error to be raised about inconsistencies in the trace results:

  • Dirty areas from newly created features.
  • Dirty areas from associated containers or structures when the Include Containers or Include Structures options are not enabled.

To clean and remove dirty areas, validate the network topology.

Running a trace without the Validate Consistency check box checked can lead to unexpected trace results. For an example, consider the following scenario: a feature is deleted from a network that breaks the only path between location A and location B. A dirty area is created for the deleted feature, but before the network topology is validated, a trace is run to find connected features starting at location A with the Validate Consistency option unchecked. In this scenario, the trace reaches location B and the tool completes with no warnings. Location B was reached because the deletion of the feature connecting A to B has not been reflected in the network topology by running a validate operation.

If the Validate Consistency option is checked in the example above, when the trace reaches the dirty area marking the deleted feature, the trace fails and an error is returned to let you know a dirty area was encountered. After the topology is validated for the area being traced, the trace cannot reach location B, as the deleted feature is now reflected in the network topology. If the network topology is not validated for the entire extent of the area that will be traced, other dirty areas could be encountered.

Even though information in the network topology is up to date for the traceable area, the subnetworks may be dirty. Ensure the traceable subnetworks are updated as well. To learn more, see Update subnetworks.

Configuration optionDescription

Validate Consistency

When this option is checked, the trace fails, and the tool returns an error if any dirty areas intersect the trace path. If this option is not checked, dirty areas are ignored. This option is checked by default.

Ensure locatability of nonspatial objects

Associations are used to determine the location of, and visually represent nonspatial junction and edge objects on a map. If this association is deleted, this can create a scenario in which the junction or edge object is unlocatable. The Validate Locatability option in the Trace and Set Subnetwork Definition tools provides the ability to identify objects without the necessary containment, attachment, or connectivity association in their association hierarchy of the traversed objects.

When Validate Locatability is set to true, the trace operation fails and an error is displayed when unlocatable objects are discovered in the path of a trace. When this occurs, the tool returns an error that includes the class name and global ID of the unlocatable objects in the trace path, as shown in the example below:

ERROR 003326: Unlocatable objects discovered.
[[GasDistributionJunctionObject: {4F860903-PK17-5c15-Y2W0-3512BP436C00}]]
Failed to execute (Trace).

The Modify Associations pane can be used to create the necessary associations for the object to be considered locatable.

To learn more, see Locatability.

Configuration optionDescription

Validate Locatability

When this option is checked, the trace fails, and the tool returns an error if any unlocatable objects are discovered. If this option is not checked, a check is not performed for unlocatable objects. This option is unchecked by default.

Control what is traced

Barriers are used during a trace to denote a stopping location; network features beyond that location are not traced. The results of a trace do not include network features past a barrier but can optionally include the barrier itself. Other parameters, such as Allow Indeterminate Flow and those found within the Traversability section, help to define what controls the traversability of network paths.

Allow Indeterminate Flow

When performing an upstream, downstream, or isolation trace there are scenarios in which the specific direction of flow cannot be determined. When modeling the direction of flow using subnetwork controllers, scenarios with loops are defined as indeterminate. Similarly, when the Use Digitized Direction parameter is used to perform an upstream or downstream trace, lines or edge objects with a Flow direction attribute set as Indeterminate are also defined as indeterminate.

By default, features and objects with indeterminate flow are included in the trace results and the Allow Indeterminate Flow parameter is checked. If this option is unchecked, these network features with indeterminate flow stop traversability and are not included in the trace results. This parameter is only honored when running an upstream, downstream, or isolation trace.

Configuration optionDescription

Allow Indeterminate Flow

  • Checked—Features and objects with indeterminate flow are traced. This is the default.
  • Unchecked—Features and objects with indeterminate flow stop traversability and are not traced.

Traversability

The Traversability section of the Trace tool includes condition barriers and function barriers to control the traversability of a trace. Condition barriers are expressions based on network attributes or network categories to define where a trace should stop. Function barriers define when a trace should stop when a condition is satisfied.

Traversability scope is further controlled by the traversability scope parameter Apply Traversability To in the Trace tool. This parameter determines whether traversability is applied to both junctions and edges, junctions only, or edges only. For example, if traversability is applied to junctions only and an edge satisfies the condition specified in a condition barrier, the trace does not stop at the edge due to the traversability scope.

To learn more, see Barriers.

Set up functions

A function is a trace configuration property that allows you to run calculations on network attributes associated with traced network features, for example, the sum of the length of all the wire traced. More than one function can be specified for a trace.

In addition, an optional network attribute filter can be added to each function; when specified, the function will only be applied to the network features that satisfy the network attribute filter. Filters in functions are used to introduce a conditional requirement—for example, add up the length of all the lines where the Phases Current attribute includes the values A, B, and C.

Note:

Trace configurations that use apportioned network attributes with functions (Add, Average, Count, Max, Min, and Subtract) return apportionable results based on edge elements. For example, using a function within a connected trace to count the shape length attribute returns a count based on the individual edge features and not the entire line. See Apportionable network attributes for more details.

Control what is returned

To control what is returned in the results of a trace, output filters and result types are used.

Output filters

An output filter screens every network feature encountered during a trace to determine whether it meets the criteria specified in the filter. For example, a trace returns all upstream protective devices from a starting point in an electrical network.

There are two types of Output filters available in the Trace tool: Output Asset Types and Output Conditions.

An Output Asset Types filter is used to include only the asset types specified in the trace results. For example, a pole report for an electric network would include an output asset type filter and include only poles in the results.

The Output Conditions filter supports network categories and network attributes. For example, an output condition uses a specific network category name to return all isolating devices in a gas network. This operation returns all features and objects with the Isolating network category assigned. A trace on a gas network could return emergency valves, bypass valves, system valves, or short stops. Features and objects without this network category are still traced, but they are not included in the results.

Network attributes are stored in the network topology and are associated with a field in one or more network classes. In an output condition, the name of the network attribute, an operator, and a value that is valid for the network attribute are specified. In the case of a leak in a water network, a network attribute is input to return pinchable pipes. In this case, the Line class has a field named Pinchable. This field is associated with a network attribute named Pinchable. The Output Conditions parameter is configured to look for classes with the Pinchable network attribute where the value is equal to True. The results of the trace include features and objects from a class with this field and the value True, as well as network features from classes without the Pinchable field.

Given the behavior of network attributes in output conditions, to return pinchable pipes, it is necessary to use an Output Asset Type filter. For example, in the Esri-provided Gas utility network, from the PipelineLine class, in the Distribution Pipe asset group, the Plastic PE asset type would be specified. With the two filters, IsPinchable = True AND AssetType = Plastic PE, the trace results will only include pinchable plastic PE pipes.

Multiple Output Conditions values can be implemented using the Combine Using parameter. Both types of outputs can be used and more than one output type can be set up. Combining output types allows you to do such things as return all 12-inch pinchable Plastic PE pipes that exceed 80 PSI.

Learn more about using multiple conditional expressions

Result Types

The optional Result Types parameter allows you to control the type of results returned by the trace.

The Aggregated Geometry, Selection, Connectivity, Elements, Features, and Containment and attachment associations result types can be specified independently or concurrently to generate output geometries, create a selection set for a trace operation, return a connectivity graph of network features connected through either geometric coincidence or connectivity associations, return feature-based information, return feature-based information with geometry, network attribute, and field information, or return features that are associated through containment and structural attachment associations to a .json file, respectively.

ParameterOptions

Result Types

  • Selection—The results from the trace operation are returned as a selection set on the appropriate network features. This is the default.
  • Aggregated Geometry—The results from the trace operation are aggregated by geometry type and stored in multipart feature classes displayed through layers in the active map.
  • Connectivity—The results from the trace are returned as a connectivity graph in a specified output .json file for traversed network features.
  • Elements—The results from the trace are returned as feature-based information in a specified output .json file for traversed network features.
  • Features—The results from the trace are returned as feature-based information in a specified output .json file with optional feature geometry, network attribute information, and field values for the traversed network features.
  • Containment and attachment associations—The results from the trace are returned as association information for traversed network features that are associated through containment and structural attachment associations in a specified output .json file.

Note:

When working with enterprise geodatabases, the following requirements must be met:

  • The Connectivity option requires ArcGIS Enterprise 10.9.1 or later.
  • The Features and Containment and attachment associations options require ArcGIS Enterprise 11.1 or later.

The Aggregated Geometry option enables trace results to be returned as multipart geometry in a feature class. This honors the location of starting points and barriers placed midspan on line features and edge objects to return partial feature results.

Review the images below to compare the differences between the selection and aggregated geometry result type options in a downstream trace. The network below contains five line features (represented as f1, f2, f3, f4, and f5) that are composed of nine edge elements (represented as e1, e2, e3, and so on).

In this example, which includes barrier features, the selection result returns seven point features and five line features consisting of nine edge elements (f1::e1,e2,e3, f2::e1,e2, and f5::e1,e2). The aggregated geometry result returns the same features but excludes edge elements f1::e1,e2 and f5::e2.

Downstream trace results using selection and aggregated geometry options

When a barrier is placed along an edge with the Include Barrier Features configuration option checked, the trace will stop at the barrier feature and return partial feature geometry for the edge in the trace results. If the Include Barrier Features option is unchecked, the trace will stop at the prior line end or junction encountered with midspan connectivity.

The examples below show the difference in trace results when using the Include Barrier Features option to include or exclude barrier features in the trace results. In this example, both the starting point and barrier are placed along an edge. With this option enabled, the selection result returns six point features and five line features consisting of nine edge elements (f1::e1,e2,e3, f2::e1,e2, f3::e1, f4::e1, and f5::e1,e2). The aggregated geometry result will return the same five line features but excludes edge elements f1::e1 and f5::e2. Partial geometry is returned for the edge element f1::e2. The selection result would not change if you were to exclude barrier features with Include Barrier Features unchecked; however, the aggregated geometry results would additionally exclude f1::e2.

Comparison of trace results with the Include Barrier Features configuration option enabled and disabled

When the Aggregated Geometry option is selected for the result type, six additional parameters are provided to define the trace output behavior:

  • Clear All Previous Trace Results
  • Synthesize Geometries
  • Trace Name
  • Aggregated Points
  • Aggregated Lines
  • Aggregated Polygons

The Clear All Previous Trace Results check box provides an option to truncate or append to the contents of the feature classes chosen to store aggregated geometry.

ParameterOptions

Clear All Previous Trace Results

  • Checked—The feature classes storing aggregated trace geometry are truncated. Only the output geometry from the current trace operation will be written. This is the default.
  • Unchecked—Output geometry from the current trace operation will be appended to the feature classes storing aggregated geometry.

The Synthesize Geometries parameter allows you to visualize the path of associations and edge objects that are traversed during a trace by synthesizing geometry in the aggregated geometry output.

The geometry for an edge object can be synthesized in two ways. When an edge object is content of a line, geometry is inferred from the spatial container. When an edge object has no spatial containment and this is not possible, geometry is synthesized between the endpoints of the edge object.

Learn more about how to synthesize geometry for edge objects in a trace

When working with associations, geometry is synthesized between the endpoints of the association. When an edge object or association's endpoint container is nonspatial, its location is derived from the first spatial feature in the containment hierarchy.

Learn more about how to synthesize association geometry in a trace

ParameterOptions

Synthesize Geometries

  • Checked—Trace operations infer and create geometries for the traversed associations and edge objects in the Trace_Results_Aggregated_Lines feature class.
  • Unchecked—Trace operations do not infer and create geometries for the traversed associations and edge objects. This is the default.

Note:

Requires ArcGIS Enterprise 11.3 or later when working with an enterprise geodatabase.

The optional Trace Name parameter enables the creation of a string identifier for the trace operation to assist with identification of trace results. When used with the Clear All Previous Trace Results parameter check box unchecked, this parameter allows you to run multiple trace operations and compare the results in the output aggregated geometry feature classes.

The Aggregated Points, Aggregated Lines, and Aggregated Polygons parameters enable you to specify feature classes for storage of the aggregated result geometry. By default, each parameter is populated with a system-generated feature class stored in the project's default geodatabase:

  • Trace_Results_Aggregated_Lines—A line feature class
  • Trace_Results_Aggregated_Points—A multipoint feature class
  • Trace_Results_Aggregated_Polygons—A polygon feature class

These feature classes are created automatically if they do not exist. Existing feature classes can also be used to store aggregated geometry. If a feature class other than the default is used, it must contain a String field named TRACENAME and match the geometry type of the output.

The generation of output geometry with partial feature results provides a more accurate representation of the trace and enables comparison and reuse of trace results for other tasks.

Caution:

Disabling the geoprocessing option Allow geoprocessing tools to overwrite existing datasets can cause tool validation issues if the output feature classes for aggregated geometry result types exist in the default geodatabase for the project. This can be addressed by enabling the geoprocessing option or by renaming the aggregated point, line, and polygon feature classes in the default geodatabase of the project.

When the Selection option is selected for the result type, an additional Selection Type parameter is provided to define how the selection will be applied and what action to perform if a selection already exists.

ParameterOptions

Selection Type

  • New selection—The resulting selection replaces the current selection. This is the default.
  • Add to the current selection—The resulting selection is added to the current selection if one exists. If no selection exists, this is the same as the new selection option.
  • Remove from the current selection—The resulting selection is removed from the current selection. If no selection exists, this option has no effect.
  • Select subset from the current selection—The resulting selection is combined with the current selection. Only records that are common to both remain selected.
  • Switch the current selection—The resulting selection is switched. Results that were selected are removed from the current selection; results that were not selected are added to the current selection. If no selection exists, this is the same as the new selection option.

The Connectivity result types option returns trace results as a connectivity graph of network features connected through geometric coincidence or connectivity associations. When this option is selected, connectivity is output to a .json file in the specified location that can be parsed and imported into other systems to build your own graph representation of the data. Connectivity information is only returned for network features returned by the trace. The output .json file contains the following information for all traversed network features under connctivity:

  • fromNetworkSourceId
  • fromGlobalId
  • fromObjectId
  • fromTerminalId
  • fromGeometry
  • viaNetworkSourceId
  • viaGlobalId
  • viaObjectId
  • viaPositionFrom
  • viaPositionTo
  • viaGeometry
  • toNetworkSourceId
  • toGlobalId
  • toObjectId
  • toTerminalId
  • toGeometry

The Elements result types option returns trace results as feature-based information in a specified output .json file that can be used as an input to perform additional analysis. The output .json file contains the following information for all traversed network features under elements:

  • networkSourceId
  • globalId
  • objectId
  • assetGroupCode
  • assetTypeCode

Additional information is returned for point features and junction objects:

  • terminalId

Additional information is returned for line features and edge objects:

  • positionFrom
  • positionTo

The Features result types option returns trace results as feature-based information in a specified output .json file. Similar to the Elements option, this option allows you to include additional information in the output for use with other applications, such as feature geometry, information about network attributes, and values from attribute fields. The output .json file contains the same information returned by Elements above for all traversed network features under featureElements along with the following additional information:

Information returned with Include geometry (not present for junction and edge objects):

  • geometry

Information returned with Include domain descriptions:

  • networkSourceName
  • assetGroupName
  • assetTypeName
  • networkAttributeDescriptions(when Result Network Attributes are specified)
  • Additional information is returned for point features and junction objects:

    • terminalName

Information returned with Result Network Attributes:

  • networkAttributeValues

Information returned with Result Fields:

  • fieldValues

The Containment and attachment associations result types option returns association information for the traversed network features that are associated through containment and structural attachment associations in a specified output .json file. The output .json file contains the following information for all traversed network features under associations:

  • associationType
  • fromNetworkSourceId
  • fromGlobalId
  • fromTerminalId
  • toNetworkSourceId
  • toGlobalId
  • toTerminalId

Information returned with Include domain descriptions:

  • fromNetworkSourceName
  • fromTerminalName
  • toNetworkSourceName
  • toTerminalName

Additional parameters are enabled when certain Result Types options are selected:

  • When the Connectivity, Elements, Features, or Containment and attachment associations option is selected, an additional Output JSON parameter is provided to give the location of the output .json file.
  • When the Features or Containment and attachment associations options are selected, an additional Include domain descriptions parameter is provided to include domain descriptions for the traversed network features.
  • When the Features option is selected, the Include geometry, Result Network Attributes, and Result Fields parameters are additionally provided to output feature geometry, network attribute information, and field level information for the traversed network features.

When the Connectivity, Elements, Features, or Containment and attachment associations options are selected, the output .json file includes a sourceMapping element located at the bottom of the file. This element allows you to look up the layer name associated with each networkSourceId.

"sourceMapping": {
		"1": "UN_6_Associations",
		"2": "UN_6_SystemJunctions",
		"4": "Structure Junction",
		"5": "Structure Line",
		"6": "Structure Boundary",
		"7": "Structure Junction Object",
		"8": "Structure Edge Object",
		"9": "Electric Distribution Device",
		"10": "Electric Distribution Line",
		"11": "Electric Distribution Assembly",
		"12": "Electric Distribution Junction",
		"13": "Electric Distribution SubnetLine",
		"14": "Electric Distribution Junction Object",
		"15": "Electric Distribution Edge Object"
	},

Work with bitwise operators

The trace configuration uses a common set of operators that are used to define barriers, filters, functions, and outputs for the trace results. Standard operators are used to evaluate feature attributes to determine whether they are equal, less than, or greater than a value.

Bitwise operators work with bits to derive the binary value from a given integer value. These operators provide power and flexibility and are more commonly used in advanced applications of tracing. The tracing framework can work with these bits independent of the meaning that the user defines in the domain's coded value pair.

Bitwise operators used in the trace configuration include the following:

  • Includes the values—A bitwise AND operation in which all bits in the provided value are present in the attribute (bitwise AND == value).
    • When using this operator, all bits included in the configuration value must also be present in the network attribute value for it to evaluate as true.
  • Does not include the values—A bitwise AND operation in which not all of the bits in the provided value are present in the attribute (bitwise AND != value).
    • When using this operator, it will only evaluate as true when the network attribute does not include all bits in the configuration value.
  • Includes any—A bitwise AND operation in which at least one bit in the provided value is present in the attribute (bitwise AND == True).
    • When using this operator, any bit present in the configuration value that is also present in the network attribute evaluates as true.
  • Does not include any—A bitwise AND operation in which none of the bits in the provided value are present in the attribute (bitwise AND == False).
    • When using this operator, it will only evaluate as true when no bits in the configuration value are present in the network attribute value.

When modeling phase in an electric utility network, the dataset can be configured to use the binary value of the integer specified for the domain code. A set of values is configured for each permissible phase combination in a coded value domain and assigned to attributes that use phase. For use in the trace configuration, a network attribute is then configured and assigned to the phase field.

The table below outlines how phase can be modeled using these binary values. The decimal value is stored as the code, and the phase value is used for the description in the coded value domain. Each decimal value has a corresponding binary value that is evaluated. The binary value column in the table shows the binary representation of each decimal value. Bitwise operators deconstruct an attribute to assess each piece and determine whether it satisfies the operational logic.

Binary valueCode (Decimal value)Description (Phase value)

001

1

C

010

2

B

100

4

A

011

3

BC

101

5

AC

110

6

AB

111

7

ABC

Example Phase coded value domain

For example, to find all network features in the subnetwork with a Phases Current value that includes A, a subnetwork trace on an electric distribution domain network is performed. The starting point is set on a service point with a Phases Current value of A (100), and the trace configuration below is specified as a filter barrier.

The filter barrier is configured to exclude features and objects that do not include phase A from the trace result. To ensure that the barrier features are not included in the trace results, the Include Barrier Features trace configuration option is set to false. The trace results include subnetwork features that have a Phases Current value of A or a Phases Current value that includes A. Any subnetwork features encountered that do not have a Phases Current value that includes A are seen as barriers and not included in the result.

Filter Barriers
Name: Phases Current
Operator: Does not include any (Bitwise AND equals False)
Type: Specific value
Value: 4 //code for A (100)

The table below provides a guide to help illustrate scenarios where a bitwise operator would evaluate as true and serve as a barrier in a trace. For example, consider a scenario where the Phase field on a device contains the network attribute value of AB (110) and the value being compared from the trace configuration is ABC (111):

  • If using the Includes the values operator, this would evaluate as false and would not act as a barrier because all bits are not present in the network attribute value. Bit C (001) is not present in AB (110).
  • If you use the Includes any operator for the same configuration, this would evaluate to true because some of the configuration value bits are present in the network attribute. Bit A (100) and Bit B (010) are present in ABC (111).
  • Using the Does not include the values operator would also evaluate as true because the network attribute value AB (110) does not include the bit C (001), even if A (100) and B (010) are present.
  • Finally, using the Does not include any operator with this configuration example would evaluate as false when it encounters the network attribute value of AB (110) because the configuration value contains matching bits A (100) and B (010). For this to evaluate as true, A (100), B (010), and C (001) would need to be absent.

Network attribute valueConfiguration valueIncludes the valuesIncludes anyDoes not include the valuesDoes not include any

ABC (111)

A (100)

True

True

False

False

AC(101)

BC (011)

False

True

True

False

C (001)

B (010)

False

False

True

True

AB (110)

ABC (111)

False

True

True

False

Perform calculations on traced network features

Utility networks provide an advanced functionality known as attribute propagation that is used when a subnetwork is updated or traced.

Attribute substitution is handled by configuring a network attribute for a database field. Substitution is a type of network attribute whose value is used to calculate the propagated value for features with the attribute substitution category assigned to its asset type. The resulting substitution value is then used to calculate the value for the next connected feature. To use attribute substitution, attribute propagation must be configured.

For more information, see Attribute propagation and Attribute substitution.

Load named trace configurations

Named trace configurations allow complex traces to be created for sharing and reuse. The Trace tool allows you to load an existing named trace configuration to define the properties for a trace. This simplifies the user experience associated with tracing and provides consistency through the reuse of common traces in an organization.

ParameterOptions

Use Trace Configuration

  • Checked—The tool will use an existing named trace configuration to define the properties of the trace. When checked, only the Trace Configuration Name, Starting Points, and Barriers parameters are displayed. When a named trace configuration is loaded that uses the aggregated geometry result types option, the Aggregated Points, Aggregated Lines, and Aggregated Polygons parameters are also displayed.
  • Unchecked—The tool will not use a named trace configuration to define the properties of the trace. This is the default.

A Trace Configuration Name parameter is provided to specify the name of the trace configuration that will be used to define the properties of the trace. This parameter is only available when Use Trace Configuration is enabled.

Note:

You can also use the Named Configurations tab in the Trace pane to run a trace using a previously configured named trace configuration.

Learn more about named trace configurations