Add Trace Rule (Network Diagram)

Summary

Adds a diagram rule to automatically execute a trace on a utility network or trace network during the building of diagrams based on an existing template. 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 May be inconsistent 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 Trace rule is used to run a trace from utility network or trace network elements currently represented in a diagram.

    Depending on the specified trace type, starting points may or must be preset in the diagram to execute the Trace rule:

    • For the Connected, Subnetwork, Upstream, and Downstream 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 a Set Starting Point rule is configured on the diagram template to clearly identify specific starting points beforehand.
    • For the Shortest path trace type, Set Starting Point rules can be configured on the diagram template to identify the two starting points among all the trace network elements currently represented in the diagram between which the shortest path must be found.

  • When you configure a template based on a Trace rule, the trace will systematically reexecute 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.

Parameters

LabelExplanationData 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 active when generating and updating diagrams based on the specified template.

  • Checked—The added rule will become active during the generation and update of any diagrams based on the input template. This is the default.
  • Unchecked—The added rule will not become active during the generation or update of any diagrams based on the input template.

Boolean
Trace Type

Specifies the type of trace the rule will perform to build the diagram content.

  • Connected A connected trace will be executed from the utility network or trace network elements currently represented in the diagram when the rule starts and spans outward along connected elements. This is the default.
  • Subnetwork A subnetwork trace will be executed from the utility network elements currently represented in the diagram when the rule starts and spans outward along connected elements to find sources or sinks from which it spans outward along the related subnetwork.
  • UpstreamAn upstream trace will be executed from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements upstream.
  • DownstreamA downstream trace will be executed 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 executed 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.
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, and downstream 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, 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).

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)

The type of traversability to enforce. Traversability scope dictates whether traversability is 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 edgesTraversability will be applied to both junctions and edges. This is the default.
  • Junctions onlyTraversability will be applied to junctions only.
  • Edges onlyTraversability 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. If 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 different 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 different calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of different 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 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, 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 used.
  • Maximum—The maximum of the input values will be used.
  • Add—The sum of the values will be used.
  • Average—The average of the input values will be used.
  • Count—The number of features will be used.
  • Subtract—The difference between the values will be used. Subnetwork controllers and loops trace types do not support the subtract function.

For example, there is a starting point feature with 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.

  • Both junctions and edgesThe filter will be applied to both junctions and edges. This is the default.
  • Junctions onlyThe filter will be applied to junctions only.
  • Edges onlyThe 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. When this parameter is used, you can specify 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 to 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)
  • Is equal toThe attribute is equal to the value.
  • Does not equalThe attribute is not equal to the value.
  • Is greater thanThe attribute is greater than the value.
  • Is greater than or equal toThe attribute is greater than or equal to the value.
  • Is less thanThe attribute is less than the value.
  • Is less than or equal toThe 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
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 on a trace network.

  • 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 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 running a Shortest path trace type.

  • NO_DIRECTIONThe path will be between the two starting points regardless of the direction of flow. This is the default.
  • PATH_UPSTREAMThe direction of the path will be downstream between the two starting points.
  • PATH_DOWNSTREAMThe direction of the path will be upstream between the two starting points.
String
Shortest Path Network Attribute Name
(Optional)

The network attribute that will be used to calculate the path 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

Derived Output

LabelExplanationData 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})
NameExplanationData 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.

  • ACTIVEThe added rule will become enabled during the generation and update of any diagrams based on the input template. This is the default.
  • INACTIVEThe 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 the rule will perform to build the diagram content.

  • CONNECTED A connected trace will be executed from the utility network or trace network elements currently represented in the diagram when the rule starts and spans outward along connected elements. This is the default.
  • SUBNETWORK A subnetwork trace will be executed from the utility network elements currently represented in the diagram when the rule starts and spans outward along connected elements to find sources or sinks from which it spans outward along the related subnetwork.
  • UPSTREAMAn upstream trace will be executed from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements upstream.
  • DOWNSTREAMA downstream trace will be executed 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 executed 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.
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, and downstream 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_STRUCTURESStructure features and objects will be included in the trace results.
  • EXCLUDE_STRUCTURESStructure 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_BARRIERSTraversability barrier features will be included in the trace results. This is the default.
  • EXCLUDE_BARRIERSTraversability 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, 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 different 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_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA 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_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

The condition barriers Combine Using value options are as follows:

  • ANDCombine the condition barriers.
  • ORUse 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.

Function barrier components are as follows:

  • Function—Choose from a number of different calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of different 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 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.

The function barrier function value options are as follows:

  • AVERAGEThe average of the input values will be used.
  • COUNTThe number of features will be used.
  • MAXThe maximum of the input values will be used.
  • MINThe minimum of the input values will be used.
  • ADDThe sum of the values will be used.
  • SUBTRACTThe difference between the values will be used. Subnetwork controllers and loops trace types do not support the subtract function.

The function barrier operator value options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA 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:

  • TRUELocal values will be used.
  • FALSEGlobal values will be used. This is the default.
Value Table
traversability_scope
(Optional)

The type of traversability that will be enforced. Traversability scope dictates whether traversability is 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, even if the trace encounters an open device, the trace will not stop 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_EDGESTraversability will be applied to both junctions and edges. This is the default.
  • JUNCTIONS_ONLYTraversability will be applied to junctions only.
  • EDGES_ONLYTraversability 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 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 different 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_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES NOT INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INLCUDE_ANYA 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_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

The filter barriers Combine Using value options are as follows:

  • ANDCombine the condition barriers.
  • ORUse 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.

Filter function barriers components are as follows:

  • Function—Choose from a number of different calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of different 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 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, or the trace continues.

The filter function barriers function value options are as follows:

  • AVERAGEThe average of the input values will be used.
  • COUNTThe number of features will be used.
  • MAXThe maximum of the input values will be used.
  • MINThe minimum of the input values will be used.
  • ADDThe sum of the values will be used.
  • SUBTRACTThe difference between the values will be used. Subnetwork controllers and loops trace types do not support the subtract function.

The filter function barriers operator value options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA 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:

  • TRUELocal values will be used.
  • FALSEGlobal 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_EDGESThe filter will be applied to both junctions and edges. This is the default.
  • JUNCTIONS_ONLYThe filter will be applied to junctions only.
  • EDGES_ONLYThe 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. When this parameter is used, you can specify a count and a cost as well as a collection of categories, an asset type, or both.

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

The number of features to be returned when filter_nearest is 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 FILTER_BY_NEAREST—for example, shape length.

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

The categories that will be returned when filter_nearest is 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 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. 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_ANDValues will be compared from one feature to the next.
  • PROPAGATED_MINThe minimum value will be propagated.
  • PROPAGATED_MAXThe maximum value will be propagated.

The propagators operator value options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA 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 via Python.

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_FLOWTrace network features that have indeterminate or uninitialized flow direction in the trace will be included.
  • IGNORE_INDETERMINATE_FLOWTrace 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 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 running a SHORTEST_PATH trace type.

  • NO_DIRECTIONThe path will be between the two starting points regardless of the direction of flow. This is the default.
  • PATH_UPSTREAMThe direction of the path will be downstream between the two starting points.
  • PATH_DOWNSTREAMThe direction of the path will be upstream between the two starting points.
String
path_network_weight_name
(Optional)

The network attribute that will be used to calculate the path 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

Derived Output

NameExplanationData 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.AddTraceRule_nd(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

Related topics