Available with Standard or Advanced license.
Summary
Creates a trace configuration in the utility network.
Trace configurations allow you to configure and store the properties of complex traces for reuse and sharing. Trace configurations stored in a utility network can be loaded and executed from the Trace tool or shared for consumption by a web map or field app.
Usage
The Input Utility Network must be version 5 or later.
When working with an enterprise geodatabase, the input utility network must be from a utility network service.
The connected portal account is set as the creator of the trace configuration.
Operating system authentication is used to store the creator of a trace configuration when working with a utility network in a file geodatabase.
Syntax
arcpy.un.AddTraceConfiguration(in_utility_network, trace_config_name, trace_type, {description}, {tags}, {domain_network}, {tier}, {target_tier}, {subnetwork_name}, {shortest_path_network_attribute_name}, {include_containers}, {include_content}, {include_structures}, {include_barriers}, {validate_consistency}, {condition_barriers}, {function_barriers}, {traversability_scope}, {filter_barriers}, {filter_function_barriers}, {filter_scope}, {filter_bitset_network_attribute_name}, {filter_nearest}, {nearest_count}, {nearest_cost_network_attribute}, {nearest_categories}, {nearest_assets}, {functions}, {propagators}, {output_assettypes}, {output_conditions}, {include_isolated_features}, {ignore_barriers_at_starting_points}, {include_up_to_first_spatial_container}, {result_types}, {allow_indeterminate_flow}, {validate_locatability})
Parameter | Explanation | Data Type |
in_utility_network | The utility network that will contain the new trace configuration. | Utility Network; Utility Network Layer |
trace_config_name | The name for the trace configuration. | String |
trace_type | Specifies the type of trace that will be configured.
| String |
description (Optional) | The description of the trace configuration. | String |
tags [tags,...] (Optional) | A set of tags used to identify the trace configuration. The tags can be used in search and indexing. | String |
domain_network (Optional) | The name of the domain network where the trace will be run. This parameter is required when running the subnetwork, subnetwork controllers, upstream, and downstream trace types. | String |
tier (Optional) | The name of the tier to start the trace. This parameter is required when running the subnetwork, subnetwork controllers, upstream, and downstream trace types. | String |
target_tier (Optional) | The name of the target tier to which the input tier flows. 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 |
subnetwork_name (Optional) | The name of the subnetwork where the trace will be run. This parameter can be used when running a subnetwork trace type. If a subnetwork name is specified, the Starting Points parameter (the starting_points parameter in Python) is not required. | String |
shortest_path_network_attribute_name (Optional) | The network attribute used to calculate the shortest path. When running a shortest path trace type, the shortest path is calculated using a numeric network attribute such as shape length. Cost and distance based paths can both be achieved. This parameter is required when running a shortest path trace. | String |
include_containers (Optional) | Specifies whether the container features will be included in the trace results.
| Boolean |
include_content (Optional) | Specifies whether the trace will return content in containers in the results.
| Boolean |
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 |
validate_consistency (Optional) | Specifies whether an error will be returned if dirty areas are encountered in any of the traversed features. This is the only way to guarantee a trace is passing through features with consistent status in the network. To remove dirty areas, validate the network topology.
| 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:
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, 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.
| String |
filter_barriers [[Name, Operator, Type, Value, Combine Using],...] (Optional) | Specifies when a trace will stop for a specific category or network attribute. For example, stop a trace at features that have a life cycle status attribute that is equal to a certain value. This parameter is used to set a terminator based on a value of a network attribute that is defined in the system. If you're using more than one attribute, you can use the Combine Using option to define an And or an Or condition. Filter barrier components are as follows:
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, 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.
| 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 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 |
functions [[Function, Attribute, Filter Name, Filter Operator, Filter Type, Filter Value],...] (Optional) | Applies a calculation function to the trace results. Functions components are as follows:
The functions Function value options are as follows:
For example, a starting point feature has a value of 20. The next feature has a value of 30. If you are using the MINIMUM function, the result is 20. MAXIMUM is 30, ADD is 50, AVERAGE is 25, COUNT is 2, and SUBTRACT is -10. The Filter Operator value options are as follows:
Learn more about bitwise operators The functions Filter Type value options are as follows:
| Value Table |
propagators [[Attribute, Substitution Attribute, Function, Operator, Value],...] (Optional) |
Specifies the network attributes to propagate as well as how that propagation will occur during a trace. Propagated class attributes denote the key values on subnetwork controllers that are disseminated to the rest of the features in the subnetwork. For example, in an electric distribution model, you can propagate the phase value. Propagators components are as follows:
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 |
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) | Specifies 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. If you're using more than one attribute, you can use the Combine Using option to define an And or an Or condition. Output conditions components are as follows:
The output conditions operator value options are as follows:
Learn more about bitwise operators The output conditions Type value options are as follows:
The output conditions Combine Using value options are as follows:
| Value Table |
include_isolated_features (Optional) | Specifies whether the isolated features will be included in the trace results. This parameter is only used when running an isolation trace.
Note:The isolation trace type requires ArcGIS Enterprise 10.7 or later when using an enterprise geodatabase. | Boolean |
ignore_barriers_at_starting_points (Optional) | Specifies whether dynamic barriers in the trace configuration are ignored for starting points. This may be useful when performing an upstream protective device trace and using the discovered protective devices (barriers) as starting points to find subsequent upstream protective devices.
| Boolean |
include_up_to_first_spatial_container (Optional) | Specifies whether to limit the containers returned to only those encountered up to, and including, the first spatial container for each network element in the trace results. If no spatial containers are encountered but nonspatial containers are present for a given network element, all nonspatial containers will be included in the results. This parameter is only applicable when Include Containers is enabled.
| Boolean |
result_types [result_types,...] (Optional) | Specifies the type of results returned by the trace.
| String |
allow_indeterminate_flow (Optional) | Specifies whether features with indeterminate flow will be traced. This parameter is only honored when running an upstream or downstream trace.
| Boolean |
validate_locatability (Optional) | Specifies whether an error will be returned if nonspatial junction or edge objects are encountered without an associated container or structure in the association hierarchy for the traversed features. This option ensures that nonspatial objects returned by a trace are associated with spatial features.
| Boolean |
Derived Output
Name | Explanation | Data Type |
out_utility_network | The updated utility network. | Utility Network |
Code sample
The following Python window script demonstrates how to use the AddTraceConfiguration tool.
import arcpy
arcpy.AddTraceConfiguration_un(
r"SampleUNService\Elec Utility Network", "Upstream_RMT002", "UPSTREAM",
"Upstream trace on RMT002", "Upstream;RMT002", "ElectricDistribution",
"Medium Voltage", '', '', '', "EXCLUDE_CONTAINERS", "EXCLUDE_CONTENT",
"EXCLUDE_STRUCTURES", "INCLUDE_BARRIERS", "VALIDATE_CONSISTENCY", None,
None, "BOTH_JUNCTIONS_AND_EDGES", None, None, "BOTH_JUNCTIONS_AND_EDGES",
'', "DO_NOT_FILTER", None, '', None, None, None, None, None, None,
"EXCLUDE_ISOLATED_FEATURES", "DO_NOT_IGNORE_BARRIERS_AT_STARTING_POINTS",
"DO_NOT_INCLUDE_UP_TO_FIRST_SPATIAL_CONTAINER", None,
"TRACE_INDETERMINATE_FLOW", "DO_NOT_VALIDATE_LOCATABILITY")
Environments
Licensing information
- Basic: No
- Standard: Yes
- Advanced: Yes