Add Trace Rule (Network Diagram Tools)

Summary

Adds a diagram rule to the rule sequence specified on a diagram template to automatically run a trace on a utility network or trace network during diagram building. The resulting traced network features and network objects are used to build the diagram content.

Learn more about using the Trace rule to build diagrams

Caution:

This tool is a configuration and administration tool.

Note:

This tool impacts the consistency of any existing diagrams based on the input diagram template. All of the existing diagrams become inconsistent and open with a consistency warning icon until they are updated.

Usage

This tool is not supported when working with a utility network or trace network service. You must use either a utility network or trace network in a file or mobile geodatabase, or a database connection to a utility network or trace network in an enterprise geodatabase. When working with an enterprise geodatabase, the following are requirements:
- The Input Network parameter value must be from a database connection established as the database utility network owner or database trace network owner.
- The connected ArcGIS Enterprise portal account must be the portal utility network owner or portal trace network owner.
- This tool must be connected to the default version, which is expected to be public and not protected.
The Trace rule is used to run a trace from network features or network objects currently represented in a diagram or from particular starting points specified either as input or using a Set Starting Point rule.

Depending on the specified trace type, starting points may or must be preset in the diagram to perform the Trace rule as follows:
- For the Connected, Subnetwork, Upstream, Downstream, and Circuit trace types, all the utility network or trace network elements represented in the diagram when the trace rule starts are considered the starting points for the trace, unless the diagram creation starts from particular trace locations provided as input or a Set Starting Point rule is configured on the diagram template to clearly identify specific starting points beforehand.
- The Path trace type must have one or more starting and stopping locations to properly work. The Path trace type has specific requirements when used as a diagram Trace rule compared to the other trace types because stopping points cannot be specified through diagram rules. To create diagrams based on a diagram template configured to apply a Path trace type rule, the Create Diagram tool must run with the Create diagram from trace locations parameter checked.
  
  Tip:
  
  Configuring the Shortest Path Network Attribute Name parameter allows to calculate the shortest path between the specified starting and stopping locations and display the detected shortest path as a diagram.
When you configure a template based on a Trace rule, the trace will systematically rerun on the utility network or trace network at each diagram update. This means that any diagram based on that template will always reflect the current network trace result when updated.
Starting at Utility Network version 7, you can configure Trace rules to run upstream or downstream trace operations that determine flow using the digitized direction of the lines and the Flow direction attribute rather than the location of the subnetwork controllers.
Starting at Utility Network version 7 and Trace Network version 4, you can also configure Trace rules using named trace configurations.
Starting at ArcGIS Pro 3.6, you can configure the Trace rule to filter the output asset types or the type of features based on network attributes or category to return.
Starting at Utility Network version 8, if your utility network exists with Telecom domains, you can configure a Trace rule to run circuit traces on a telecom domain.

Label	Explanation	Data type
Input Network	The utility network or trace network containing the diagram template that will be modified.	Utility Network; Trace Network
Input Diagram Template	The name of the diagram template that will be modified.	String
Active	Specifies whether the rule will be enabled when generating and updating diagrams based on the specified template. Checked—The added rule will become enabled during the generation and update of any diagrams based on the input template. This is the default. Unchecked—The added rule will not become enabled during the generation or update of any diagrams based on the input template.	Boolean
Trace Type	Specifies the type of trace that will be run to build the diagram content. Connected—A connected trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts and span outward along connected elements. This is the default. Subnetwork—A subnetwork trace will be run from the utility network elements currently represented in the diagram when the rule starts and span outward along connected elements to find sources or sinks from which it spans outward along the related subnetwork. Upstream—An upstream trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements upstream. Downstream—A downstream trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements downstream. Shortest path—A shortest path trace will be run from the utility network or trace network features currently specified as starting points in the diagram when the rule starts to discover features along the shortest path between those starting points. The cost of traversing the path is determined based on the network attribute set for the Shortest Path Network Attribute Name parameter value regardless of flow direction. Legacy: The Shortest path trace type is deprecated with ArcGIS Pro 3.7 and ArcGIS Enterprise 12.1. While it will continue to function and be an option until the next major release, we recommend that you use the Path trace type to return a shortest path. The Path trace type provides the same functionality to return a shortest path result while offering additional capabilities to find paths in your network. Circuit—A circuit trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts. It will return circuit definition and path information for both physical and virtual circuits. This option is supported for telecom domain networks only. Path—A path trace will be run to identify valid paths between the starting and stopping points used as input trace locations for the diagram generation.	String
Domain Network (Optional)	The name of the domain network where the trace will be run for a utility network. This parameter is required when running the subnetwork, upstream, downstream, and circuit trace types.	String
Tier (Optional)	The name of the tier where the trace will start for a utility network. This parameter is optional when running the connected trace type; it is required when running the subnetwork, upstream, and downstream trace types.	String
Target Tier (Optional)	The name of the target tier to which the input tier will flow for a utility network. If this parameter is missing 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
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 Barriers 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
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. Value table columns: Name—Filter by any network attribute defined in the system. Operator—Choose from a number of different operators. 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—Choose a specific value or network attribute from the value that is specified with the name. Specific value—Filter by a specific value. Network attribute—Filter by a network attribute. 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. 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—Choose from a number of different calculation functions. Minimum—The minimum of the input values will be used. Maximum—The maximum of the input values will be used. Average—The average of the input values will be used. Count—The number of features will be used. Add—The sum of the values will be used. Subtract—The difference between the values will be used. Subnetwork controllers and loops trace types do not support the subtract function. Attribute—Filter by any network attribute defined in the system. Operator—Choose from a number of different operators. 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—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 traverse 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.	Value Table
Apply Traversability To (Optional)	Specifies the type of traversability that will be enforced. Traversability scope defines whether traversability will be enforced at 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. Junctions only—Traversability will be applied to junctions only. Edges only—Traversability will be applied to edges only. 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 the 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. Value table columns: Name—Filter by category or any network attribute defined in the system. Operator—Choose from a number of different operators. 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—Choose a specific value or network attribute from the value that is specified with the name. Specific value—Filter by a specific value. Network attribute—Filter by a network attribute. 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. 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 used. Maximum—The maximum of the input values will be used. Average—The average of the input values will be used. Count—The number of features will be used. Add—The sum of the values will be used. Subtract—The difference between the values will be used. 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 to use 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 Count, Cost Network Attribute, Nearest Categories, or Nearest Asset Groups/Types. 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
Propagators (Optional)	This parameter is only available through Python. Value table columns: 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. Propagated bitwise AND—Compare the values from one feature to the next. Propagated minimum—The minimum value will be used. Propagated maximum—The maximum value will be used. Operator—Choose from a number of operators. Is equal to—The attribute is equal to the value. Does not equal—The attribute is 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—Provide a specific value for the input attribute type that would cause termination based on the operator value.	Value Table
Description (Optional)	The description of the rule.	String
Allow Indeterminate Flow (Optional)	Specifies whether trace network features that have indeterminate or uninitialized flow will be traced. This parameter is only honored when running an upstream or downstream trace type. Checked—Trace network features that have indeterminate or uninitialized flow direction in the trace will be included. Unchecked—Trace network features that have indeterminate or uninitialized flow direction will not be included. This is the default.	Boolean
Path Direction (Optional)	Specifies the direction of the shortest path for a trace network. The cost of traversing the path is determined by the Shortest Path Network Attribute Name parameter value. This parameter is only honored when applying a Shortest path trace type to a trace network. No direction—The shortest path will be between the two starting points regardless of the direction of flow. This is the default. Upstream path—The direction of the shortest path will be upstream between the two starting points. Downstream path—The direction of the shortest path will be downstream between the two starting points.	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 for a utility network or trace network. 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
Use Trace Configuration (Optional)	Specifies whether an existing named trace configuration will be used to define the properties of the trace. This parameter is only enabled for Utility Network version 7 and later. Checked—An existing named trace configuration will be used to define the properties of the trace. 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.	String
Use Digitized Direction (Optional)	Specifies whether upstream and downstream trace operations will determine flow using the digitized direction of the line and the flow direction attribute. This parameter is only enabled for Utility Network version 7 and later when the Trace Type parameter is set to the Upstream or Downstream option. Note: This parameter requires ArcGIS Enterprise 11.3 or later when using an enterprise geodatabase. Checked—The trace operations will determine flow direction using the digitized direction of the line and the flow direction attribute. With this option, the Domain Network, Tier, and Target Tier parameters are disabled. Unchecked—Trace operations will determine flow direction based on the location of subnetwork controllers. This is the default.	Boolean
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. 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
Num Paths (Optional)	The maximum number of paths that will be returned in the path or circuit trace. The default is 1. This parameter is only active when the Trace Type parameter is set to Path or Circuit.	Long
Max Hops (Optional)	The maximum number of hops between edges allowed in the path or circuit, 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 or Circuit.	Long
Infer Connectivity (Optional)	Specifies whether the path trace will use connectivity inference to traverse containment associations and identify a path between the specified starting and stopping 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 starting and stopping location when incomplete connectivity prevents traversal. Unchecked—Connectivity inference will not be used to identify a path between the specified starting and stopping location. This is the default.	Boolean

Derived output

Label	Explanation	Data type
Output Network	The updated utility network or trace network.	Utility Network; Trace Network
Output Diagram Template	The name of the diagram template.	String

arcpy.nd.AddTraceRule(in_utility_network, template_name, is_active, trace_type, {domain_network}, {tier}, {target_tier}, {include_structures}, {include_barriers}, {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}, {propagators}, {description}, {allow_indeterminate_flow}, {path_direction}, {path_network_weight_name}, {use_trace_config}, {trace_config_name}, {use_digitized_direction}, {output_assettypes}, {output_conditions}, {num_paths}, {max_hops}, {infer_connectivity})

Name	Explanation	Data type
in_utility_network	The utility network or trace network containing the diagram template that will be modified.	Utility Network; Trace Network
template_name	The name of the diagram template that will be modified.	String
is_active	Specifies whether the rule will be enabled when generating and updating diagrams based on the specified template. `ACTIVE`—The added rule will become enabled during the generation and update of any diagrams based on the input template. This is the default. `INACTIVE`—The added rule will not become enabled during the generation or update of any diagrams based on the input template.	Boolean
trace_type	Specifies the type of trace that will be run to build the diagram content. `CONNECTED`—A connected trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts and span outward along connected elements. This is the default. `SUBNETWORK`—A subnetwork trace will be run from the utility network elements currently represented in the diagram when the rule starts and span outward along connected elements to find sources or sinks from which it spans outward along the related subnetwork. `UPSTREAM`—An upstream trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements upstream. `DOWNSTREAM`—A downstream trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements downstream. `SHORTEST_PATH`—A shortest path trace will be run from the utility network or trace network features currently specified as starting points in the diagram when the rule starts to discover features along the shortest path between those starting points. The cost of traversing the path is determined based on the network attribute set for the `path_network_weight_name` parameter value regardless of flow direction. Legacy: The `SHORTEST_PATH` trace type is deprecated with ArcGIS Pro 3.7 and ArcGIS Enterprise 12.1. While it will continue to function and be an option until the next major release, we recommend that you use the `PATH` trace type to return the shortest path. The `PATH` trace type provides the same functionality to return a shortest path result while offering additional capabilities to find paths in your network. `CIRCUIT`—A circuit trace will be run from the utility network or trace network elements currently represented in the diagram when the rule starts. It will return circuit definition and path information for both physical and virtual circuits. This option is supported for telecom domain networks only. `PATH`—A path trace will be run to identify valid paths between the starting and stopping points used as input trace locations for the diagram generation.	String
domain_network (Optional)	The name of the domain network where the trace will be run for a utility network. This parameter is required when running the subnetwork, upstream, downstream, and circuit trace types.	String
tier (Optional)	The name of the tier where the trace will start for a utility network. This parameter is optional when running the connected trace type; it is required when running the subnetwork, upstream, and downstream trace types.	String
target_tier (Optional)	The name of the target tier to which the input tier will flow for a utility network. If this parameter is missing 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
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
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. Value table columns: `Name`—Filter by any network attribute defined in the system. `Operator`—Choose from a number of different operators. `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). `Type`—Choose a specific value or network attribute from the value that is specified with the name. `SPECIFIC_VALUE`—Filter by a specific value. `NETWORK_ATTRIBUTE`—Filter by a network attribute. `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. `AND`—Combine the condition barriers. `OR`—Use if either condition barrier is met.	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. Value table columns: `Function`—Choose from a number of different calculation functions. `MIN`—The minimum of the input values will be used. `MAX`—The maximum of the input values will be used. `AVERAGE`—The average of the input values will be used. `COUNT`—The number of features will be used. `ADD`—The sum of the values will be used. `SUBTRACT`—The difference between the values will be used. Subnetwork controllers and loops trace types do not support the subtract function. `Attribute`—Filter by any network attribute defined in the system. `Operator`—Choose from a number of different operators. `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`—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 traverse 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.	Value Table
traversability_scope (Optional)	Specifies the type of traversability that will be applied. Traversability scope defines whether traversability will be applied at 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 the 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. Value table columns: `Name`—Filter by category or any network attribute defined in the system. `Operator`—Choose from a number of different operators. `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). `Type`—Choose a specific value or network attribute from the value that is specified with the name. `SPECIFIC_VALUE`—Filter by a specific value. `NETWORK_ATTRIBUTE`—Filter by a network attribute. `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. `AND`—Combine the condition barriers. `OR`—Use if either condition barrier is met.	Value Table
filter_function_barriers [[Function, Attribute, Operator, Value, Use Local Values],...] (Optional)	Filters the results of the trace for a specific category. Value table columns: `Function`—Filter by a function. `MIN`—The minimum of the input values will be used. `MAX`—The maximum of the input values will be used. `AVERAGE`—The average of the input values will be used. `COUNT`—The number of features will be used. `ADD`—The sum of the values will be used. `SUBTRACT`—The difference between the values will be used. 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`—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`—Filter by a specific value. `Use Local Values`—Boolean value to use local variables instead of a global variable.	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 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
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 in a traditional domain network. 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. Value table columns: `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. `PROPAGATED_BITWISE_AND`—Compare the values from one feature to the next. `PROPAGATED_MIN`—The minimum value will be used. `PROPAGATED_MAX`—The maximum value will be used. `Operator`—Choose from a number of operators. `IS_EQUAL_TO`—The attribute is equal to the value. `DOES_NOT_EQUAL`—The attribute is 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`—Provide a specific value for the input attribute type that would cause termination based on the operator value.	Value Table
description (Optional)	The description of the rule.	String
allow_indeterminate_flow (Optional)	Specifies whether trace network features that have indeterminate or uninitialized flow will be traced. This parameter is only honored when running an upstream or downstream trace type. `TRACE_INDETERMINATE_FLOW`—Trace network features that have indeterminate or uninitialized flow direction in the trace will be included. `IGNORE_INDETERMINATE_FLOW`—Trace network features that have indeterminate or uninitialized flow direction will not be included. This is the default.	Boolean
path_direction (Optional)	Specifies the direction of the shortest path for a trace network. The cost of traversing the path is determined by the `path_network_weight_name` parameter value. This parameter is only honored when applying a `SHORTEST_PATH` trace type to a trace network. `NO_DIRECTION`—The shortest path will be between the two starting points regardless of the direction of flow. This is the default. `PATH_UPSTREAM`—The direction of the shortest path will be upstream between the two starting points. `PATH_DOWNSTREAM`—The direction of the shortest path will be downstream between the two starting points.	String
path_network_weight_name (Optional)	The network attribute that will be used to calculate the shortest path using the path or shortest path trace type for a utility network or trace network. 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
use_trace_config (Optional)	Specifies whether an existing named trace configuration will be used to define the properties of the trace. This parameter is only enabled for Utility Network version 7 and later. `USE_TRACE_CONFIGURATION`—An existing named trace configuration will be used to define the properties of the trace. `DO_NOT_USE_TRACE_CONFIGURATION`—An existing named trace configuration will not be used to define the properties of the trace. This is the default.	Boolean
trace_config_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 enabled when the `use_trace_config` parameter is set to `USE_TRACE_CONFIGURATION`.	String
use_digitized_direction (Optional)	Specifies whether upstream and downstream trace operations will determine flow using the digitized direction of the line and the `Flow direction` attribute. This parameter is only enabled for Utility Network version 7 and later when the `trace_type` parameter is set to the `UPSTREAM` or `DOWNSTREAM` option. Note: This parameter requires ArcGIS Enterprise 11.3 or later when using an enterprise geodatabase. `USE_DIGITIZED_DIRECTION`—The trace operations will determine flow direction using the digitized direction of the line 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.	Boolean
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. 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`—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). `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
num_paths (Optional)	The maximum number of paths that will be returned in the Path or Circuit trace. The default is 1. This parameter is only active when the trace_type parameter is set to `PATH` or `CIRCUIT`.	Long
max_hops (Optional)	The maximum number of hops between edges allowed in the path or circuit, 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 valid when the `trace_type` parameter is set to `PATH` or `CIRCUIT`.	Long
infer_connectivity (Optional)	Specifies whether the path trace will use connectivity inference to traverse containment associations and identify a path between the specified starting and stopping 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. `INFER_CONNECTIVITY`—The path trace will use connectivity inference to traverse containment associations and identify a path between the specified starting and stopping location when incomplete connectivity prevents traversal. `DO_NOT_INFER_CONNECTIVITY`—Connectivity inference will not be used to identify a path between the specified starting and stopping location. This is the default.	Boolean

Derived output

Name	Explanation	Data type
out_utility_network	The updated utility network or trace network.	Utility Network; Trace Network
out_template_name	The name of the diagram template.	String

Code sample

AddTraceRule example (Python window)

Add a Trace rule to MyTemplate1 existing for a given network to generate diagrams from trace on subnetworks within the Medium Voltage tier in the ElectricDistribution domain.

import arcpy
input_Network = "D:/MyProjectLocation/MyDatabaseConnection.sde/MyDatabase.MAP.Electric/MyDatabase.MAP.Electric"
input_DiagramTemplate = "MyTemplate1"

arcpy.nd.AddTraceRule(input_Network, input_DiagramTemplate, "ACTIVE",
                      "SUBNETWORK", "ElectricDistribution", "Medium Voltage",
                      "Low Voltage Mesh")

Environments

This tool does not use any geoprocessing environments.

Licensing information

Basic: No
Standard: Yes
Advanced: Yes

Add Trace Rule (Network Diagram Tools)

Summary

Caution:

Note:

Usage

Tip:

Parameters

Legacy:

Note:

Derived output

Environments

Licensing information

Related topics