Back to Top

Add Trace Configuration (Utility Network)

In this topic

  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information

Available with Standard or Advanced license.

Summary

Creates a named trace configuration in the utility network.

Named trace configurations allow you to configure and store the properties of complex traces for reuse and sharing. Named trace configurations created in a utility network can be used in ArcGIS Pro with the Trace tool or by using the Named Configurations tab in the Trace pane. When working in an enterprise deployment, these can also be shared through a web map and used by web and field apps.

Learn more about how to create a named trace configuration

Usage

  • The Input Utility Network parameter value must be version 5 or later.

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

  • The connected portal account is set as the creator of the named trace configuration. Operating system authentication is used to store the creator of a named trace configuration when working with a utility network in a single-user deployment.

    • License:
    The active portal account must be assigned a license with the ArcGIS Advanced Editing user type extension to use this tool in an enterprise deployment.

Parameters

DialogPython

LabelExplanationData Type
Input Utility Network

The utility network that will contain the new named trace configuration.

Utility Network; Utility Network Layer
Trace Configuration Name

The name of the named trace configuration.

String
Trace Type

Specifies the type of trace that will be configured.

  • 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.
  • Subnetwork controllers—A subnetwork controllers trace that locates sources and sinks on subnetwork controllers associated with a subnetwork will be used.
  • Upstream—An upstream trace that discovers features upstream from a location in the network will be used.
  • Downstream—A downstream trace that discovers features downstream from a location in the network will be used.
  • 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.
  • Isolation—An isolation trace that discovers features that isolate an area of a network will be used.
String
Description
(Optional)

The description of the named trace configuration.

String
Tags
(Optional)

A set of tags used to identify the named trace configuration. The tags can be used in search and indexing.

String
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, and downstream trace types.

String
Tier
(Optional)

The name of the tier 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 to which the input tier will flow. 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 where the trace will be run. This parameter can be used when running a subnetwork trace type. If a subnetwork name is specified, starting points are not required. 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. When running a 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 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. The Include up to First Spatial Container parameter becomes active.
  • 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.

Condition barrier components are as follows:

  • Name—Filter by any network attribute defined in the system, or select Category to use a network category.
  • Operator—Choose from a number of operators.
  • Type—Select Specific value or Network attribute for the type of value from the Name parameter that will serve as a barrier. The Type parameter must be set to Specific value when the Name parameter is Category.
  • Value—Provide a specific value for the input attribute or category that would cause termination based on the operator value.
  • Combine using—Set this value if you have multiple conditions to add. You can combine them using an And or an Or condition.

The condition barriers Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • Does not include the values—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • Includes any—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

The condition barriers Type value options are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute.

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.

Function barrier components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value, for example, a function barrier that is calculating the sum of Shape length in which the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you have already reached a Shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, and the trace continues.
    • Checked—Local values will be used.
    • Unchecked—Global values will be used. This is the default.

The function barrier Function value options are as follows:

  • Minimum—The minimum of the input values.
  • Maximum—The maximum of the input values.
  • Add—The sum of the input values.
  • Average—The average of the input values.
  • Count—The number of features.
  • Subtract—The difference between the input values.

    Subnetwork controllers and loops trace types do not support the subtract function.

For example, the starting point feature has a value of 20. The next feature has a value of 30. If you use the minimum function, the result is 20, maximum is 30, add is 50, average is 25, count is 2, and subtract is -10.

The function barrier Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • Does not include the values—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • Includes any—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

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.

Filter barrier components are as follows:

  • Name—Filter by category or any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the Name parameter.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The filter barriers Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • Does not include the values—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • Includes any—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

The filter barriers Type value options are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute.

Value Table
Filter Function Barriers
(Optional)

Filters the results of the trace for a specific category.

Filter function barriers components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value. For example, a function barrier that is calculating the sum of shape length in which the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you will have reached a shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, or the trace continues.
    • Checked—Local values will be used.
    • Unchecked—Global values will be used. This is the default.

The filter function barriers Function value options are as follows:

  • Minimum—The minimum of the input values will be identified.
  • Maximum—The maximum of the input values will be identified.
  • Add—The sum of the values will be calculated.
  • Average—The average of the input values will be calculated.
  • Count—The number of features will be identified.
  • Subtract—The difference between the values will be calculated. Subnetwork controllers and loops trace types do not support the subtract function.

For example, a starting point feature has a value of 20. The next feature has a value of 30. If you are using the Minimum function, the result is 20. Maximum is 30, Add is 50, Average is 25, Count is 2, and Subtract is -10.

The filter function barriers Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • Does not include the values—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • Includes any—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

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.

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 Count, Cost Network Attribute, Nearest Categories, or Nearest Asset Groups/Types 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 category or 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.

Functions components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Filter Name—Filter the function results by attribute name.
  • Filter Operator—Choose from a number of operators.
  • Filter Type—Choose from a number of filter types.
  • Filter Value—Provide a specific value for the input filter attribute.

The functions Function value options are as follows:

  • Average—The average of the input values will be calculated.
  • Count—The number of features will be identified.
  • Maximum—The maximum of the input values will be identified.
  • Minimum—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.

For example, a starting point feature has a value of 20. The next feature has a value of 30. If you're using the Minimum function, the result is 20, Maximum is 30, Add is 50, Average is 25, Count is 2, and Subtract is -10.

The functions Filter Operator value options are as follows:

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

The functions Filter Type value options are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute.

  • Average—The average of the input values will be calculated.
  • Count—The number of features will be identified.
  • Maximum—The maximum of the input values will be identified.
  • Minimum—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.
Value Table
Propagators
(Optional)
  • 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 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 will not be included in the results. Any traced features that do will be returned in the result selection set.

Output conditions components are as follows:

  • Name—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the Name parameter.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The output conditions Operator value options are as follows:

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

The output conditions Type value options are as follows:

  • Specific Value—Filter by a specific value.
  • Network Attribute—Filter by a network attribute.

Value Table
Include Isolated Features
(Optional)

Specifies whether isolated features will be included in the trace results. 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.

Note:

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

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 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 active when Include Containers is checked.

  • 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.
String
Allow Indeterminate Flow
(Optional)

Specifies whether features with indeterminate flow will be traced. This parameter is only applicable when running an upstream, downstream, or isolation trace.

  • 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 if nonspatial junction or edge objects are encountered without an associated container or structure in the association hierarchy for the traversed features. This parameter ensures that nonspatial objects returned by a trace are associated with spatial features.

  • Checked—The trace will return an error if nonspatial junction or edge objects are encountered without an associated container or structure in the association hierarchy for the traversed features.
  • 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 features. This is the default.

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

  • 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. When this parameter is checked, the Domain Network, Tier, and Target Tier parameters are hidden and ignored.
  • Unchecked—Trace operations will determine flow direction based on the location of subnetwork controllers. This is the default.

Note:

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

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

Note:

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

Boolean

Derived Output

LabelExplanationData Type
Output Utility Network

The updated utility network.

Utility Network

arcpy.un.AddTraceConfiguration(in_utility_network, trace_config_name, trace_type, {description}, {tags}, {domain_network}, {tier}, {target_tier}, {subnetwork_name}, {shortest_path_network_attribute_name}, {include_containers}, {include_content}, {include_structures}, {include_barriers}, {validate_consistency}, {condition_barriers}, {function_barriers}, {traversability_scope}, {filter_barriers}, {filter_function_barriers}, {filter_scope}, {filter_bitset_network_attribute_name}, {filter_nearest}, {nearest_count}, {nearest_cost_network_attribute}, {nearest_categories}, {nearest_assets}, {functions}, {propagators}, {output_assettypes}, {output_conditions}, {include_isolated_features}, {ignore_barriers_at_starting_points}, {include_up_to_first_spatial_container}, {result_types}, {allow_indeterminate_flow}, {validate_locatability}, {use_digitized_direction}, {synthesize_geometries})
NameExplanationData Type
in_utility_network

The utility network that will contain the new named trace configuration.

Utility Network; Utility Network Layer
trace_config_name

The name of the named trace configuration.

String
trace_type

Specifies the type of trace that will be configured.

  • 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.
  • SUBNETWORK_CONTROLLERS—A subnetwork controllers trace that locates sources and sinks on subnetwork controllers associated with a subnetwork will be used.
  • UPSTREAM—An upstream trace that discovers features upstream from a location in the network will be used.
  • DOWNSTREAM—A downstream trace that discovers features downstream from a location in the network will be used.
  • 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.
  • ISOLATION—An isolation trace that discovers features that isolate an area of a network will be used.
String
description
(Optional)

The description of the named trace configuration.

String
tags
[tags,...]
(Optional)

A set of tags used to identify the named trace configuration. The tags can be used in search and indexing.

String
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, and downstream trace types.

String
tier
(Optional)

The name of the tier 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 to which the input tier will flow. 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 where the trace will be run. This parameter can be used when running a subnetwork trace type. If a subnetwork name is specified, the starting_points parameter is not required.

String
shortest_path_network_attribute_name
(Optional)

The network attribute that will be used to calculate the shortest path. When running a 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 required when running a shortest path trace.

String
include_containers
(Optional)

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

  • INCLUDE_CONTAINERS—Container features will be included in the trace results.
  • EXCLUDE_CONTAINERS—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.

  • INCLUDE_CONTENT—Content in container features will be included in the trace results.
  • EXCLUDE_CONTENT—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.

  • INCLUDE_STRUCTURES—Structure features and objects will be included in the trace results.
  • EXCLUDE_STRUCTURES—Structure features and objects will not be included in the trace results. This is the default.
Boolean
include_barriers
(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.

  • INCLUDE_BARRIERS—Traversability barrier features will be included in the trace results. This is the default.
  • EXCLUDE_BARRIERS—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.

  • VALIDATE_CONSISTENCY—The trace will return an error if dirty areas are encountered in any of the traversed features. This is the default.
  • DO_NOT_VALIDATE_CONSISTENCY—The trace will return results regardless of whether dirty areas are encountered in any of the traversed features.
Boolean
condition_barriers
[[Name, Operator, Type, Value, Combine Using],...]
(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.

Condition barrier components are as follows:

  • Name—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the name parameter.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The condition barriers operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The condition barriers Type value options are as follows:

  • SPECIFIC_VALUE—Filter by a specific value.
  • NETWORK_ATTRIBUTE—Filter by a network attribute.

The condition barriers Combine Using value options are as follows:

  • AND—Combine the condition barriers.
  • OR—Use if either condition barrier is met.

Learn more about using multiple conditional expressions

Value Table
function_barriers
[[Function, Attribute, Operator, Value, Use Local Values],...]
(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.

Function barrier components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value. For example, a function barrier that is calculating the sum of shape length in which the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you will have reached a shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, and the trace continues.

The function barrier Function value options are as follows:

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

The function barrier operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The function barrier Use Local Values options are as follows:

  • TRUE—Local values will be used.
  • FALSE—Global values will be used. This is the default.
Value Table
traversability_scope
(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
[[Name, Operator, Type, Value, Combine Using],...]
(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.

Filter barrier components are as follows:

  • Name—Filter by category or any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the name parameter.
  • Value—Provide a specific value of the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The filter barriers Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—A bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INLCUDE_ANY—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The filter barriers Type value options are as follows:

  • SPECIFIC_VALUE—Filter by a specific value.
  • NETWORK_ATTRIBUTE—Filter by a network attribute.

The filter barriers Combine Using value options are as follows:

  • AND—Combine the condition barriers.
  • OR—Use if either condition barrier is met.

Learn more about using multiple conditional expressions

Value Table
filter_function_barriers
[[Function, Attribute, Operator, Value, Use Local Values],...]
(Optional)

Filters the results of the trace for a specific category.

Filter function barriers components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value. For example, a function barrier that is calculating the sum of shape length in which the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you will have reached a shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, or the trace continues.

The filter function barriers Function value options are as follows:

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

The filter function barriers Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The filter function barriers Use Local Values options are as follows:

  • TRUE—Local values will be used.
  • FALSE—Global values will be used. This is the default.
Value Table
filter_scope
(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.
String
filter_bitset_network_attribute_name
(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_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.

  • FILTER_BY_NEAREST—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.
  • DO_NOT_FILTER—The k-nearest neighbors algorithm will not be used to filter results. This is the default.
Boolean
nearest_count
(Optional)

The number of features that will be returned when filter_nearest is set to FILTER_BY_NEAREST.

Long
nearest_cost_network_attribute
(Optional)

The numeric network attribute that will be used to calculate nearness, cost, or distance when filter_nearest is set to FILTER_BY_NEAREST—for example, shape length.

String
nearest_categories
[nearest_categories,...]
(Optional)

The category or categories that will be returned when filter_nearest is set to FILTER_BY_NEAREST—for example, protective.

String
nearest_assets
[nearest_assets,...]
(Optional)

The asset groups and asset types that will be returned when filter_nearest is set to FILTER_BY_NEAREST—for example, ElectricDistributionDevice/Transformer/Step Down.

String
functions
[[Function, Attribute, Filter Name, Filter Operator, Filter Type, Filter Value],...]
(Optional)

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

Functions components are as follows:

  • Function—Choose from a number of calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Filter Name—Filter the function results by attribute name.
  • Filter Operator—Choose from a number of operators.
  • Filter Type—Choose from a number of filter types.
  • Filter Value—Provide a specific value for the input filter attribute.

The functions Function value options are as follows:

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

For example, a starting point feature has a value of 20. The next feature has a value of 30. If you are using the MINIMUM function, the result is 20, MAXIMUM is 30, ADD is 50, AVERAGE is 25, COUNT is 2, and SUBTRACT is -10.

The Filter Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The functions Filter Type value options are as follows:

  • SPECIFIC_VALUE—Filter by a specific value.
  • NETWORK_ATTRIBUTE—Filter by a network attribute.
Value Table
propagators
[[Attribute, Substitution Attribute, Function, Operator, Value],...]
(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.

Propagators components are as follows:

  • Attribute—Filter by any network attribute defined in the system.
  • Substitution Attribute—Use a substituted value instead of bitset network attribute values. Substitutions are encoded based on the number of bits in the network attribute being propagated. A substitution is a mapping of each bit in phase to another bit. For example, for Phase AC, one substitution could map bit A to B, and bit C to null. In this example, the substitution for 1010 (Phase AC) is 0000-0010-0000-0000 (512). The substitution captures the mapping so you know that Phase A was mapped to B and Phase C was mapped to null, and not the other way around (that is, Phase A was not mapped to null and Phase C was not mapped to B).
  • Function—Choose from a number of calculation functions.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.

The propagators Function value options are as follows:

  • PROPAGATED_BITWISE_AND—The values from one feature to the next will be compared.
  • PROPAGATED_MIN—The minimum value will be identified.
  • PROPAGATED_MAX—The maximum value will be identified.

The propagators Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

Note:

This parameter is only available in Python.

Value Table
output_assettypes
[output_assettypes,...]
(Optional)

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

String
output_conditions
[[Name, Operator, Type, Value, Combine Using],...]
(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 will not be included in the results. Any traced features that do will be returned in the result selection set. If you're using more than one attribute, you can use the Combine Using option to define an And or an Or condition.

Output conditions components are as follows:

  • Name—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the name parameter.
  • Value—Provide a specific value of the input attribute type that would cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The output conditions Operator value options are as follows:

  • 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—A bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUES—A bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANY—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—A bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

Learn more about bitwise operators

The output conditions Type value options are as follows:

  • SPECIFIC_VALUE—Filter by a specific value.
  • NETWORK_ATTRIBUTE—Filter by a network attribute.

The output conditions Combine Using value options are as follows:

  • AND—Combine the conditions.
  • OR—Use if either condition is met.

Learn more about using multiple conditional expressions

Value Table
include_isolated_features
(Optional)

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

  • INCLUDE_ISOLATED_FEATURES—Isolated features will be included in the trace results.
  • EXCLUDE_ISOLATED_FEATURES—Isolated features will not be included in the trace results. This is the default.
Note:

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

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 using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices.

  • IGNORE_BARRIERS_AT_STARTING_POINTS—Barriers at starting points will be ignored in the trace.
  • DO_NOT_IGNORE_BARRIERS_AT_STARTING_POINTS—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.

  • INCLUDE_UP_TO_FIRST_SPATIAL_CONTAINER—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.
  • DO_NOT_INCLUDE_UP_TO_FIRST_SPATIAL_CONTAINER—All containers will be returned in the results. This is the default.
Boolean
result_types
[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.
String
allow_indeterminate_flow
(Optional)

Specifies whether features with indeterminate flow will be traced. This parameter is only applicable when running an upstream, downstream, or isolation trace.

  • TRACE_INDETERMINATE_FLOW—Features with indeterminate flow will be traced. This is the default.
  • IGNORE_INDETERMINATE_FLOW—Features with indeterminate flow will stop traversability and will not be traced.
Boolean
validate_locatability
(Optional)

Specifies whether an error will be returned if nonspatial junction or edge objects are encountered without an associated container or structure in the association hierarchy for the traversed features. This parameter ensures that nonspatial objects returned by a trace are associated with spatial features.

  • VALIDATE_LOCATABILITY—The trace will return an error if nonspatial junction or edge objects are encountered without an associated container or structure in the association hierarchy for the traversed features.
  • DO_NOT_VALIDATE_LOCATABILITY—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 features. This is the default.
Boolean
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.

  • USE_DIGITIZED_DIRECTION—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, the domain_network, tier, and target_tier parameters are ignored.
  • IGNORE_DIGITIZED_DIRECTION—Trace operations will determine flow direction based on the location of subnetwork controllers. This is the default.
Note:

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

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 result type.

  • DO_NOT_SYNTHESIZE_GEOMETRIES— Geometries will not be synthesized for the traversed associations and edge objects. This is the default.
  • SYNTHESIZE_GEOMETRIES—Geometries will be inferred and created for the traversed associations and edge objects in the output Trace_Results_Aggregated_Lines feature class.

Note:

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

Boolean

Derived Output

NameExplanationData Type
out_utility_network

The updated utility network.

Utility Network

Code sample

AddTraceConfiguration example (Python window)

The following Python window script demonstrates how to use the AddTraceConfiguration function.

import arcpy
arcpy.un.AddTraceConfiguration(
        r"SampleUNService\Elec Utility Network", "Upstream_RMT002", "UPSTREAM", 
        "Upstream trace on RMT002", "Upstream;RMT002", "ElectricDistribution", 
        "Medium Voltage", '', '', '', "EXCLUDE_CONTAINERS", "EXCLUDE_CONTENT", 
        "EXCLUDE_STRUCTURES", "INCLUDE_BARRIERS", "VALIDATE_CONSISTENCY", None, 
        None, "BOTH_JUNCTIONS_AND_EDGES", None, None, "BOTH_JUNCTIONS_AND_EDGES", 
        '', "DO_NOT_FILTER", None, '', None, None, None, None, None, None, 
        "EXCLUDE_ISOLATED_FEATURES", "DO_NOT_IGNORE_BARRIERS_AT_STARTING_POINTS", 
        "DO_NOT_INCLUDE_UP_TO_FIRST_SPATIAL_CONTAINER", None, 
        "TRACE_INDETERMINATE_FLOW", "DO_NOT_VALIDATE_LOCATABILITY")

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: No
  • Standard: Yes
  • Advanced: Yes

Related topics

  • An overview of the Trace Configuration toolset
  • Find a geoprocessing tool

Feedback on this topic?

In this topic
  1. Summary
  2. Usage
  3. Parameters
  4. Environments
  5. Licensing information