Skip to main content

Trace (Utility Network Tools)

Summary

Returns network features in a utility network based on connectivity or traversability from the specified starting points.

Utility network tracing capabilities allow you to analyze the paths in a network. Traversability refers to paths established by connected or associated features that also meet configuration requirements.

By default, trace results are returned as a selection and include the entire line feature. To return partial feature results that respect trace locations placed along an edge, such as starting points, stopping points, and barriers, set the Result Types parameter to Aggregated Geometry. Trace locations placed midspan along an edge object can be used to return partial geometries when edge objects are content of a line feature using the Synthesize Geometries parameter.

With the Aggregated Geometry option, starting points placed along an edge will return the edge element from the previous junction with midspan connectivity or endpoint. When a barrier is placed along an edge with the Include Barrier Features parameter checked, the trace will stop at the next junction encountered with midspan connectivity or the line end. If the Include Barrier Features parameter is unchecked, the trace will stop at the previous junction encountered with midspan connectivity or the previous line end.

You can then propagate the resulting selection set or output feature class generated by the trace to another map or to a diagram view of the network, or use it as input to another tool or trace.

Learn more about tracing utility networks

Usage

  • The network topology must be enabled. Since the Trace tool relies on the network topology, the results of a trace may not be accurate if dirty areas are traced. The network topology for the area to be traced must be validated to reflect the most recent edits or updates made to the network.

  • When working with an enterprise geodatabase, the input utility network must be a utility network service.

  • When a subnetwork-based trace is run on a traditional domain network using the Trace tool through Python, the subnetwork trace configuration for the input tier is not applied automatically and must be manually specified.

  • When working with network attributes assigned to a date field for filter barriers, filter function barriers, functions, and output conditions, format the date value as yyyy-mm-dd hh:mm:ss, for example, 2020-10-12 18:45:31.

Parameters

Label Explanation Data type

Input Utility Network

The utility network on which the trace will be run. When working with an enterprise geodatabase, an input utility network must be from a feature service; a utility network from a database connection is not supported.

Utility Network; Utility Network Layer

Trace Type

Specifies the type of trace that will be used.

  • Connected—A connected trace that begins at one or more starting points and spans outward along connected features will be used. This is the default.

  • Subnetwork—A subnetwork trace that begins at one or more starting points and spans outward to encompass the extent of the subnetwork will be used. This option is supported for traditional domain networks only.

  • Subnetwork controllers—A subnetwork controllers trace that locates sources and sinks on subnetwork controllers associated with a subnetwork will be used. This option is supported for traditional domain networks only.

  • Upstream—An upstream trace that discovers features upstream from a location in the network will be used. This option is supported for traditional domain networks only unless the Use Digitized Direction parameter is checked.

  • Downstream—A downstream trace that discovers features downstream from a location in the network will be used. This option is supported for traditional domain networks only unless the Use Digitized Direction parameter is checked.

  • Loops—A loops trace that spans outward from the starting point based on connectivity will be used. Loops are areas of the network where flow direction is ambiguous.

  • Shortest path—A shortest path trace that identifies the shortest path between two starting points will be used.

    Legacy:

    The shortest path trace type is deprecated with ArcGIS Pro 3.7 and ArcGIS Enterprise 12.1. While the shortest path trace will continue to function and be an option until the next major release, we recommend that you use the path trace to return the shortest path. The path trace provides the same functionality to return a shortest path result while offering additional capabilities to find paths in your network.

  • Isolation—An isolation trace that discovers features that isolate an area of a network will be used. This option is supported for traditional domain networks only.

  • Path—A path trace that identifies valid paths between one or more start and stop locations, or the shortest path between a specified starting point and stopping point will be used.

  • Circuit—A circuit trace that begins at a circuit's start location or a provided starting point to return the circuit definition and path information for both physical and virtual circuits will be used. This option is supported for telecom domain networks only.

String

Starting Points

(Optional)

A feature layer created using the Start tab in the Trace pane, or a table or feature class containing one or more records that represent the starting points of the trace. This feature class or table must include the FEATUREGLOBALID field to store information from the associated network feature. The UN_Temp_Starting_Points feature class in the project's default geodatabase is used by default.

Feature Layer; Table View

Barriers

(Optional)

A feature layer created using the Barriers tab in the Trace pane, or a table or feature class containing one or more records representing barriers that prevent the trace from traversing beyond that point. This feature class or table must include the FEATUREGLOBALID field to store information from the associated network feature. The UN_Temp_Barriers feature class in the project's default geodatabase is used by default.

Feature Layer; Table View

Domain Network

(Optional)

The name of the domain network where the trace will be run. This parameter is required when running the subnetwork, subnetwork controllers, upstream, downstream, and circuit trace types.

String

Tier

(Optional)

The name of the tier in a traditional domain network where the trace will start. This parameter is required when running the subnetwork, subnetwork controllers, upstream, and downstream trace types.

String

Target Tier

(Optional)

The name of the target tier in a traditional domain network to which the input tier will flow in a directional trace. If this parameter is not specified for upstream and downstream traces, those traces will stop when they reach the boundary of the starting subnetwork. This parameter can be used to allow these traces to continue either farther up or farther down the hierarchy.

String

Subnetwork Name

(Optional)

The name of the subnetwork in a traditional domain network where the trace will be run. This parameter can be used when running a subnetwork trace type. This parameter is required when the Starting Points parameter is not used. When the subnetworks table contains 10,000 or more records for a tier, the parameter's choice list is not populated and an empty field is provided for the subnetwork name.

String

Shortest Path Network Attribute Name

(Optional)

The network attribute that will be used to calculate the shortest path using the path or shortest path trace type. The shortest path is calculated using a numeric network attribute such as shape length. Cost- and distance-based paths can both be achieved. This parameter is optional for a path trace but is required when running a shortest path trace.

String

Include Containers

(Optional)

Specifies whether the container features will be included in the trace results.

  • Checked—Container features will be included in the trace results.

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

Boolean

Include Content

(Optional)

Specifies whether the trace will return content in container features in the results.

  • Checked—Content in container features will be included in the trace results.

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

Boolean

Include Structures

(Optional)

Specifies whether structure features and objects will be included in the trace results.

  • 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.

Boolean

Include Barrier Features

(Optional)

Specifies whether the traversability barrier features will be included in the trace results. Traversability barriers are optional even if they have been preset in the subnetwork definition. This parameter does not apply to device features with terminals.

  • Checked—Traversability barrier features will be included in the trace results. This is the default.

  • Unchecked—Traversability barrier features will not be included in the trace results.

Boolean

Validate Consistency

(Optional)

Specifies whether an error will be returned if dirty areas are encountered in any of the traversed features. This is the only way to guarantee a trace is passing through features with consistent status in the network. To remove dirty areas, validate the network topology.

  • Checked—The trace will return an error if dirty areas are encountered in any of the traversed features. This is the default.

  • Unchecked—The trace will return results regardless of whether dirty areas are encountered in any of the traversed features.

Boolean

Condition Barriers

(Optional)

Sets a traversability barrier condition on features based on a comparison to a network attribute or check for a category string. A condition barrier uses a network attribute or network category, an operator and a type, and an attribute value. For example, stop a trace when a feature has the Device Status attribute equal to the specific value of Open. When a feature meets this condition, the trace stops. If you're using more than one attribute, you can use the Combine using parameter to define an And or an Or condition.

Learn more about using multiple conditional expressions

Value table columns:

  • Name—Filter by network attribute name.

  • Operator—Filter by an operator.

    • Is equal to—The attribute is equal to the value.

    • Does not equal—The attribute is not equal to the value.

    • Is greater than—The attribute is greater than the value.

    • Is greater than or equal to—The attribute is greater than or equal to the value.

    • Is less than—The attribute is less than the value.

    • Is less than or equal to—The attribute is less than or equal to the value.

    • Includes the values (bitwise AND equals the value)—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).

    • Does not include the values (bitwise AND does not equal the value)—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).

    • Includes any (bitwise AND equals True)—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).

    • Does not include any (bitwise AND equals False)—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

  • Type—Filter by a specific type.

    • Specific value—Filter by a specific value or network category.

    • Network attribute—Filter by a network attribute.

  • Value—Filter by a specific value.

  • Combine Using—Use this parameter to combine multiple condition barriers.

    • And—Combine the condition barriers.

    • Or—Use if either condition barrier is met.

Value Table

Function Barriers

(Optional)

Sets a traversability barrier on features based on a function. Function barriers can be used to do such things as restrict how far the trace travels from the starting point, or set a maximum value to stop a trace. For example, the length of each line traveled is added to the total distance traveled so far. When the total length traveled reaches the value specified, the trace stops.

Value table columns:

  • Function—Filter by a function.

    • Minimum—The minimum of the input values will be identified.

    • Maximum—The maximum of the input values will be identified.

    • Average—The average of the input values will be calculated.

    • Count—The number of features will be identified.

    • Add—The sum of the input values will be calculated.

    • Subtract—The difference between the input values will be calculated. Subnetwork controllers and loops trace types do not support the subtract function.

  • Attribute—Filter by a network attribute.

  • Operator—Filter by an operator.

    • Is equal to—The function result is equal to the value.

    • Does not equal—The function result is not equal to the value.

    • Is greater than—The function result is greater than the value.

    • Is greater than or equal to—The function result is greater than or equal to the value.

    • Is less than—The function result is less than the value.

    • Is less than or equal to—The function result is less than or equal to the value.

    • Includes the values (bitwise AND equals the value)—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).

    • Does not include the values (bitwise AND does not equal the value)—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).

    • Includes any (bitwise AND equals True)—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).

    • Does not include any (bitwise AND equals False)—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

  • Value—Filter by a specific value.

  • Use Local Values—Boolean value that uses local variables instead of a global variable.

Value Table

Apply Traversability To

(Optional)

Specifies whether traversability will be applied to junctions, edges, or both. For example, if a condition barrier is defined to stop the trace if Device Status is equal to Open and traversability scope is set to edges only, the trace will not stop—even if it encounters an open device—because Device Status is only applicable to junctions. In other words, this parameter indicates to the trace whether to ignore junctions, edges, or both.

  • Both junctions and edges—Traversability will be applied to both junctions and edges. This is the default.

  • Junctions only—Traversability will be applied to junctions only.

  • Edges only—Traversability will be applied to edges only.

String

Filter Barriers

(Optional)

Specifies when a trace will stop for a specific category or network attribute. For example, stop a trace at features that have a life cycle status attribute that is equal to a certain value. This parameter is used to set a terminator based on a value of a network attribute that is defined in the system. If you're using more than one attribute, you can use the Combine Using option to define an And or an Or condition.

Learn more about using multiple conditional expressions

Value table columns:

  • Name—Filter by network attribute name.

  • Operator—Filter by an operator.

    • Is equal to—The attribute is equal to the value.

    • Does not equal—The attribute is not equal to the value.

    • Is greater than—The attribute is greater than the value.

    • Is greater than or equal to—The attribute is greater than or equal to the value.

    • Is less than—The attribute is less than the value.

    • Is less than or equal to—The attribute is less than or equal to the value.

    • Includes the values (bitwise AND equals the value)—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).

    • Does not include the values (bitwise AND does not equal the value)—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).

    • Includes any (bitwise AND equals True)—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).

    • Does not include any (bitwise AND equals False)—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

  • Type—Filter by a specific type.

    • Specific value—Filter by a specific value.

    • Network attribute—Filter by a network attribute.

  • Value—Filter by a specific value.

  • Combine Using—Use this parameter to combine multiple filter barriers.

    • And—Combine the condition barriers.

    • Or—Use if either condition barrier is met.

Value Table

Filter Function Barriers

(Optional)

Filters the results of the trace for a specific category.

Value table columns:

  • Function—Filter by a function.

    • Minimum—The minimum of the input values will be identified.

    • Maximum—The maximum of the input values will be identified.

    • Average—The average of the input values will be calculated.

    • Count—The number of features will be identified.

    • Add—The sum of the values will be calculated.

    • Subtract—The difference between the values will be calculated. Subnetwork controllers and loops trace types do not support the subtract function.

  • Attribute—Filter by a network attribute.

  • Operator—Filter by an operator.

    • Is equal to—The attribute is equal to the value.

    • Does not equal—The attribute is not equal to the value.

    • Is greater than—The attribute is greater than the value.

    • Is greater than or equal to—The attribute is greater than or equal to the value.

    • Is less than—The attribute is less than the value.

    • Is less than or equal to—The attribute is less than or equal to the value.

    • Includes the values (bitwise AND equals the value)—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).

    • Does not include the values (bitwise AND does not equal the value)—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).

    • Includes any (bitwise AND equals True)—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).

    • Does not include any (bitwise AND equals False)—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

  • Value—Filter by a specific value.

  • Use Local Values—Boolean value that uses local variables instead of a global variable.

Value Table

Apply Filter To

(Optional)

Specifies whether the filter for a specific category will be applied to junctions, edges, or both. For example, if a filter barrier is defined to stop the trace if Device Status is equal to Open and traversability scope is set to edges only, the trace will not stop—even if the trace encounters an open device—because Device Status is only applicable to junctions. In other words, this parameter indicates to the trace whether to ignore junctions, edges, or both.

  • Both junctions and edges—The filter will be applied to both junctions and edges. This is the default.

  • Junctions only—The filter will be applied to junctions only.

  • Edges only—The filter will be applied to edges only.

  • Both junctions and edges—The filter will be applied to both junctions and edges. This is the default.

  • Junctions only—The filter will be applied to junctions only.

  • Edges only—The filter will be applied to edges only.

String

Filter by bitset network attribute

(Optional)

The name of the network attribute that will be used to filter by bitset. This parameter is only applicable to upstream, downstream, and loops trace types. This parameter can be used to add special logic during a trace so the trace more closely reflects real-world scenarios. For example, for a loops trace, the Phases current network attribute can determine if the loop is a true electrical loop (the same phase is energized all around the loop, that is, A) and return only real electrical loops for the trace results. An example for an upstream trace is when tracing an electric distribution network, specify a Phases current network attribute, and the trace results will only include valid paths that are specified in the network attribute, not all paths.

String

Filter by nearest

(Optional)

Specifies whether the k-nearest neighbors algorithm will be used to return a number of features of a certain type within a given distance. You can provide a count and a cost as well as a collection of categories, an asset type, or both.

  • Checked—The k-nearest neighbors algorithm will be used to return a number of features as specified in the nearest_count, nearest_cost_network_attribute, nearest_categories, or nearest_assets parameter.

  • Unchecked—The k-nearest neighbors algorithm will not be used to filter results. This is the default.

Boolean

Count

(Optional)

The number of features that will be returned when Filter by nearest is checked.

Long

Cost Network Attribute

(Optional)

The numeric network attribute that will be used to calculate nearness, cost, or distance when Filter by nearest is checked—for example, shape length.

String

Nearest Categories

(Optional)

The categories that will be returned when Filter by nearest is checked—for example, protective.

String

Nearest Asset Groups/Types

(Optional)

The asset groups and asset types that will be returned when Filter by nearest is checked—for example, ElectricDistributionDevice/Transformer/Step Down.

String

Functions

(Optional)

The calculation function or functions that will be applied to the trace results.

Value table columns:

  • Function—Calculation function.

    • Average—The average of the input values will be calculated.

    • Count—The number of features will be identified.

    • Max—The maximum of the input values will be identified.

    • Min—The minimum of the input values will be identified.

    • Add—The sum of the input values will be calculated.

    • Subtract—The difference between the input values will be calculated. Subnetwork controllers and loops trace types do not support the subtract function.

  • Attribute—Filter by a network attribute

  • Filter Name—Filter by attribute name.

  • Filter Operator—Filter by an operator.

    • Is equal to—The attribute is equal to the value.

    • Does not equal—The attribute is not equal to the value.

    • Is greater than—The attribute is greater than the value.

    • Is greater than or equal to—The attribute is greater than or equal to the value.

    • Is less than—The attribute is less than the value.

    • Is less than or equal to—The attribute is less than or equal to the value.

    • Includes the values (bitwise AND equals the value)—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).

    • Does not include the values (bitwise AND does not equal the value)—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).

    • Includes any (bitwise AND equals True)—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).

    • Does not include any (bitwise AND equals False)—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

  • Filter Type—Filter by attribute type.

    • Specific value—Filter by a specific value.

    • Network attribute—Filter by a network attribute.

  • Filter Value—Filter by a specific value.

  • Function Name—The name for the alias to describe the function result.

Value Table

Propagators

(Optional)

Specifies the network attributes to propagate as well as how that propagation will occur during a trace. Propagated class attributes denote the key values on subnetwork controllers that are disseminated to the rest of the features in the subnetwork. For example, in an electric distribution model, you can propagate the phase value. In a telecom domain network, you can propagate wavelengths values from features defined as circuit locations.

Learn more about bitwise operators

Note:

This parameter is only available for Python.

Value table columns:

  • Attribute—Filter by a network attribute.

  • Substitution Attribute—The network attribute used for substitution.

  • Function—Filter by a function.

  • Operator—Filter by an operator.

  • Value—Filter by a specific value.

Value Table

Output Asset Types

(Optional)

Filters the output asset types to be included in the results—for example, only return overhead transformers.

String

Output Conditions

(Optional)

The types of features that will be returned based on a network attribute or category. For example, in a trace configured to filter out everything but Tap features, any traced features that do not have the Tap category assigned to them are not included in the results. Any traced features that do are returned in the result selection set.

Learn more about using multiple conditional expressions

Value table columns:

  • Name—Filter by network attribute name.

  • Operator—Filter by an operator.

    • Is equal to—The attribute is equal to the value.

    • Does not equal—The attribute is not equal to the value.

    • Is greater than—The attribute is greater than the value.

    • Is greater than or equal to—The attribute is greater than or equal to the value.

    • Is less than—The attribute is less than the value.

    • Is less than or equal to—The attribute is less than or equal to the value.

    • Includes the values (bitwise AND equals the value)—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).

    • Does not include the values (bitwise AND does not equal the value)—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).

    • Includes any (bitwise AND equals True)—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).

    • Does not include any (bitwise AND equals False)—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

  • Type—Filter by a specific type.

    • Specific value—Filter by a specific value.

    • Network attribute—Filter by a network attribute.

  • Value—Filter by a specific value.

  • Combine Using—Use this parameter to combine multiple conditions.

    • And—Combine the conditions.

    • Or—Use if either condition is met.

Value Table

Include Isolated Features

(Optional)

Specifies whether isolated features will be included in the trace results with a traditional domain network. This parameter is only used when running an isolation trace.

  • Checked—Isolated features will be included in the trace results.

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

Boolean

Ignore Barriers At Starting Points

(Optional)

Specifies whether dynamic barriers in the trace configuration will be ignored for 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.

  • 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.

Boolean

Include up to First Spatial Container

(Optional)

Specifies whether the containers returned will be limited to 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 the results. This parameter is only enabled when include_containers is set to INCLUDE_CONTAINERS.

  • Checked—Only containers encountered up to, and including, the first spatial container will be returned in the results 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.

Boolean

Result Types

(Optional)

Specifies the type of results that will be returned by the trace.

  • Selection—The trace results will be returned as a selection set on the appropriate network features. This is the default.

  • Aggregated Geometry—The trace results will be aggregated by geometry type and stored in multipart feature classes displayed in layers in the active map.

  • Connectivity—The trace results will be returned as a connectivity graph in a specified output .json file for the traversed network features. This option enables the Include geometry, Include domain descriptions, and Output JSON parameters.

  • Elements—The trace results will be returned as feature-based information in a specified output .json file for the traversed network features. This option enables the Output JSON parameter.

  • Features—The trace results will be returned as feature-based information in a specified output .json file for the traversed network features. This option enables the Include geometry, Include domain descriptions, Result Network Attributes, Result Fields, and Output JSON parameters.

    Note:

    For enterprise geodatabases, this option requires ArcGIS Enterprise 11.1 or later.

  • Containment and attachment associations—The trace results will be returned as association information for traversed network features that are associated through containment and structural attachment associations in a specified output .json file. This option enables the Include domain descriptions and Output JSON parameters.

    Note:

    For enterprise geodatabases, this option requires ArcGIS Enterprise 11.1 or later.

  • Related records—Values from related objects will be returned for the traversed features in the output .json file using the specified relationship class and field. This option enables the Include geometry, Include domain descriptions, Related Record Fields, and Output JSON parameters.

    Note:

    For enterprise geodatabases, this option requires ArcGIS Enterprise 11.5 or later.

  • Circuits—The trace results will be returned as a circuit definition with the option to include path connectivity information and geometry for each section in a specified output .json file. This option is supported with circuit traces in a telecom domain network only and enables the Include geometry, Synthesize Geometries, and Output JSON parameters.

String

Selection Type

Specifies how the selection will be applied and what will occur if a current selection exists.

  • New selection—The resulting selection will replace the current selection. This is the default.

  • Add to the current selection—The resulting selection will be 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 will be removed from the current selection. If no selection exists, this option has no effect.

  • Select subset from the current selection—The resulting selection will be combined with the current selection. Only records that are common to both remain selected.

  • Switch the current selection—The resulting selection will be switched. Results that were selected are removed from the current selection, and results that were not selected are added to the current selection. If no selection exists, this is the same as the new selection option.

String

Clear All Previous Trace Results

(Optional)

Specifies whether content will be truncated from, or appended to, the feature classes chosen to store aggregated geometry. This parameter is only applicable to the Aggregated Geometry result type.

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

  • Unchecked—The output geometry from the current trace operation will be appended to the feature classes storing aggregated geometry.

Boolean

Trace Name

(Optional)

The name of the trace operation. This value is stored in the TRACENAME field of the output feature class to assist with identification of the trace results. This parameter is only applicable to the Aggregated Geometry result type.

String

Aggregated Points

(Optional)

An output multipoint feature class containing the aggregated result geometry. By default, the parameter is populated with a system-generated feature class named Trace_Results_Aggregated_Points that will be stored in the project's default geodatabase.

This feature class will be created automatically if it does not exist. An existing feature class can also be used to store aggregated geometry. If a feature class other than the default is used, it must be a multipoint feature class and contain a string field named TRACENAME. This parameter is only applicable to the Aggregated Geometry result type.

Feature Class

Aggregated Lines

(Optional)

An output polyline feature class containing the aggregated result geometry. By default, the parameter is populated with a system-generated feature class named Trace_Results_Aggregated_Lines that will be stored in the project's default geodatabase.

This feature class will be created automatically if it does not exist. An existing feature class can also be used to store aggregated geometry. If a feature class other than the default is used, it must be a polyline feature class and contain a string field named TRACENAME. This parameter is only applicable to the Aggregated Geometry result type.

Feature Class

Aggregated Polygons

(Optional)

An output polygon feature class containing the aggregated result geometry. By default, the parameter is populated with a system-generated feature class named Trace_Results_Aggregated_Polygons that will be stored in the project's default geodatabase.

This feature class will be created automatically if it does not exist. An existing feature class can also be used to store aggregated geometry. If a feature class other than the default is used, it must be a polygon feature class and contain a string field named TRACENAME. This parameter is only applicable to the Aggregated Geometry result type.

Feature Class

Allow Indeterminate Flow

(Optional)

Specifies whether features with indeterminate flow will be traced. Indeterminate flow is defined as areas in a subnetwork where flow direction is ambiguous or cannot be determined. This parameter is only applicable when running an upstream, downstream, or isolation trace.

Note:

This parameter requires a Utility Network Version value of 5 or later.

  • Checked—Features with indeterminate flow will be traced. This is the default.

  • Unchecked—Features with indeterminate flow will stop traversability and will not be traced.

Boolean

Validate Locatability

(Optional)

Specifies whether an error will be returned during a trace if nonspatial junction or edge objects are encountered without the necessary connectivity, containment, or attachment association in their association hierarchy. This parameter ensures that nonspatial objects returned by a trace or update subnetwork operation can be located through an association with features or other locatable objects.

  • Checked—The trace will return an error if unlocatable nonspatial junction or edge objects are encountered without the necessary connectivity, containment, or attachment association in their association hierarchy.

  • Unchecked—The trace will not check for unlocatable objects and will return results regardless of whether unlocatable objects are present in the association hierarchy of the traversed objects. This is the default.

Boolean

Use Trace Configuration

(Optional)

Specifies whether an existing named trace configuration will be used to populate the parameters of this tool.

Note:

This parameter requires a Utility Network Version value of 5 or later.

  • Checked—An existing named trace configuration will be used to define the properties of the trace. All parameters except trace_config_name, starting_points, and barriers will be ignored.

  • Unchecked—An existing named trace configuration will not be used to define the properties of the trace. This is the default.

Boolean

Trace Configuration Name

(Optional)

The name of the existing named trace configuration that will be used to define the properties of the trace. This parameter is only active when the Use Trace Configuration parameter is checked.

Note:

This parameter requires a Utility Network Version value of 5 or later.

String

Output JSON

(Optional)

The name and location of the .json file that will be generated when returning trace results using the Connectivity, Elements, Features, Containment and attachment associations, or Related records result types.

File

Run in asynchronous mode on the server

(Optional)

Specifies whether trace operations will process asynchronously when working with a utility network in an enterprise geodatabase.

  • Checked—Trace operations will process asynchronously.

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

Boolean

Include geometry

(Optional)

Specifies whether geometry will be included in the results.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 11.1 or later.

  • Checked—Geometry will be included in the results.

  • Unchecked—Geometry will not be included in the results. This is the default.

Boolean

Include domain descriptions

(Optional)

Specifies whether domain descriptions will be included in the output .json file to communicate domain mapping for controllers, featureElements, connectivity, and associations.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 11.1 or later.

  • Checked—Domain descriptions will be included in the results.

  • Unchecked—Domain descriptions will not be included in the results. This is the default.

Boolean

Result Network Attributes

(Optional)

The network attributes that will be included in the results.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 11.1 or later.

String

Result Fields

(Optional)

Fields from a feature class that will be returned as results. The values of the fields will be returned in the results for the features in the trace.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 11.1 or later.

Value table columns:

  • Feature Class—A feature class that participates in the utility network.

  • Field Name—The name of a field from the feature class that will have its values returned in the results.

Value Table

Use Digitized Direction

(Optional)

Specifies whether upstream and downstream 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. This parameter is only available and active for utility network version 7 and later when the trace_type parameter is set to UPSTREAM or DOWNSTREAM.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 11.3 or later.

  • 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. With this option, propagators configured on a tier will be ignored and the domain_network, tier, and target_tier parameters will also be ignored.

  • Unchecked—Trace operations will determine flow direction based on the location of subnetwork controllers. This is the default.

Boolean

Synthesize Geometries

(Optional)

Specifies whether geometries will be inferred and created (synthesized) for associations and edge objects traversed as part of a trace operation. This parameter is only applicable to the Aggregated Geometry and Circuits result types.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 11.3 or later for use with the Aggregated Geometry result type and ArcGIS Enterprise 12.1 or later for use with the Circuits result type.

  • Checked—Geometries will be inferred and created for the traversed associations and edge objects in the output Trace_Results_Aggregated_Lines feature class.

  • Unchecked—Geometries will not be synthesized for the traversed associations and edge objects. This is the default.

Boolean

Stopping Points

(Optional)

A feature layer created using the Stop tab in the Trace pane, or a table or feature class containing one or more records that represent the stopping points for a Path trace. This feature class or table must include the FEATUREGLOBALID field to store information from the associated network feature. The UN_Temp_Stopping_Points feature class in the project's default geodatabase is used by default.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 12.1 or later.

Feature Layer; Table View

Num Paths

(Optional)

The maximum number of paths that will be returned between a given set of start and stop locations in a Path trace. The default is 1. This parameter is only active when the Trace Type parameter is set to Path.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 12.1 or later.

Long

Max Hops

(Optional)

The maximum number of hops between edges allowed in the path, excluding the starting point. All edges and junction-junction connectivity associations are evaluated as having a fixed unit length of 1 on traversal. Terminal devices are evaluated as having a fixed unit length of 2. The default is 100. This parameter is only active when the Trace Type parameter is set to Path.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 12.1 or later.

Long

Related Record Fields

(Optional)

The fields from related object classes that will be returned as results. The values of the fields will be returned in the results for the traversed features in the output .json file.

Value table columns:

  • Relationship Class—A relationship class that relates to a feature or object class that participates in the utility network.

  • Field Name—The name of a field from the related object class that will have its values returned in the results.

Value Table

Circuit Name

(Optional)

The name of the circuit in a telecom domain network where the circuit trace will be run. This is required for a circuit trace when the Starting Points parameter is not used.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 12.1 or later.

String

Infer Connectivity

(Optional)

Specifies whether the path trace will use connectivity inference to traverse containment associations and identify a path between the specified start and stop location. This parameter is only supported with the path trace in telecom domain networks and enables paths to be discovered between sections when connectivity information is not explicitly available. For more information, see Infer Connectivity.

  • Checked—The path trace will use connectivity inference to traverse containment associations and identify a path between the specified start and stop location when incomplete connectivity prevents traversal.

  • Unchecked—Connectivity inference is not used to identify a path between the specified start and stop location. This is the default.

Boolean

Include flow directions

(Optional)

Specifies whether flow directions will be included in the output .json file. If included, the file will contain flow direction information derived from the subnetwork controllers for traversed lines, edge objects, the internal edges of devices with terminals, and connectivity associations.

This parameter applies only to the Connectivity, Elements, and Features result types options when used with the subnetwork, upstream, and downstream trace types.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 12.1 or later.

  • Checked—Flow directions will be included in the results.

  • Unchecked—Flow directions will not be included in the results. This is the default.

Boolean

Include propagated values

(Optional)

Specifies whether propagated values will be included in the output .json file when running a subnetwork-based trace. This parameter is only applicable to the Features result type.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 12.1 or later.

  • Checked—Propagated values will be included in the results.

  • Unchecked—Propagated values will not be included in the results. This is the default.

Boolean

Derived output

Label Explanation Data type

Output Utility Network

The updated utility network.

Utility Network

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: Limited
    Supported in an enterprise deployment when using ArcGIS Enterprise named user licensing.
  • Standard: Yes
  • Advanced: Yes