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 until they are updated.
Usage
This tool is not supported when working with a utility network service. You must work with either a utility network or trace network in a file geodatabase or a database connection to a utility network in an enterprise geodatabase. When working with an enterprise geodatabase, the connection must be established as the database utility network owner.
When performing this operation on a utility network in an enterprise geodatabase, the connected ArcGIS Enterprise portal account must be the portal utility network owner.
The network data element specified for the input network parameter must be from either a utility network or trace network in a file geodatabase or a database connection to a utility network in an enterprise geodatabase.
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 must 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.
Syntax
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})
Parameter | Explanation | Data Type |
in_utility_network | The utility network or trace network containing the diagram template to modify. | Utility Network; Trace Network |
template_name | The name of the diagram template to modify. | String |
is_active | Specifies whether the rule will be enabled when generating and updating diagrams based on the specified template.
| Boolean |
trace_type | Specifies the type of trace the rule will perform to build the diagram content.
| String |
domain_network (Optional) | The name of the domain network where the trace is 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 starts 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 flows 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.
| 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.
| 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 attribute Device Status 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:
The condition barriers operator value options are as follows:
Learn more about bitwise operators The condition barriers Type value options are as follows:
The condition barriers Combine Using value options are as follows:
| 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:
The function barrier function value options are as follows:
The function barrier operator value options are as follows:
Learn more about bitwise operators The function barrier Use Local Values options are as follows:
| Value Table |
traversability_scope (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, then even if the trace encounters an open device, the trace would 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.
| 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:
The filter barriers operator value options are as follows:
Learn more about bitwise operators The filter barriers Type value options are as follows:
The filter barriers Combine Using value options are as follows:
| 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:
The filter function barriers function value options are as follows:
The filter function barriers operator value options are as follows:
Learn more about bitwise operators The filter function barriers Use Local Values options are as follows:
| Value Table |
filter_scope (Optional) | Specifies whether the filter for a specific category will be enforced at 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, then 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.
| 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.
| Boolean |
nearest_count (Optional) | The number of features to be returned when filter_nearest is True. | Long |
nearest_cost_network_attribute (Optional) | The numeric network attribute that will be used to calculate nearness, cost, or distance when filter_nearest is True—for example, Shape length. | String |
nearest_categories [nearest_categories,...] (Optional) | The categories that will be returned when filter_nearest is True—for example, Protective. | String |
nearest_assets [nearest_assets,...] (Optional) | The asset groups and asset types that will be returned when filter_nearest is True—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 should 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:
The propagators function value options are as follows:
The propagators operator value options are as follows:
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.
| Boolean |
path_direction (Optional) | Specifies the direction of the path for a trace network. The cost of traversing the path is determined based on the value set for the path_network_attribute_name. This parameter is only honored when running a PATH trace type.
| String |
path_network_weight_name (Optional) | The network attribute used to calculate the path for a 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
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
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
Licensing information
- Basic: No
- Standard: Yes
- Advanced: Yes