Trace rule reference
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.
Typically, the Trace rule is configured on diagram templates to run among the first rules during diagram building. It operates from start locations set on network features or network objects in the network map or queried among all the potential input network features or network objects according to Set Starting Point rules configured beforehand on the template.
The starting points from which the trace runs depend on the trace type:
For the Connected, Subnetwork, Upstream, Downstream, Path 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.
For the Shortest Path trace type, instead of providing the two particular starting points to process as input, Set Starting Point rules can be configured on the diagram template to identify the two starting points among all the 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 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 with Utility Network Version 7, you can benefit from existing named trace configurations when configuring Trace rules on your diagram template. You can also 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 instead of being based on the location of the subnetwork controllers.
Starting with ArcGIS Pro 3.6, the Trace rule supports output filtering parameters. This allows you to filter the output asset types to be included in the trace results, or the only traced network elements to return based on network attributes or categories. Output filtering can be particularly useful for the first trace rule you configure in a sequence of trace rules for your diagram template.
Starting with ArcGIS Pro 3.7 and Enterprise 12.1, the Trace rule can be configured to apply two new trace types; Path and Circuit. The Circuit trace type applies to telecom network domain supported with Utility Network Version 8 and later.
When performing the Path or Circuit trace rule along a telecom network domain, the diagram builder accesses telecom network attributes and retrieves connectivity information such as that inferred by containment or connectivity. It also stores the unit identifiers through which the trace passes in the appropriate fields of the diagram junctions—ELEMENTUNIT field; and diagram edges—FROMELEMENTFIRSTUNIT, ELEMENTFIRSTUNIT, ELEMENTLASTUNIT, and TOELEMENTFIRSTUNIT.
Trace rule specifics
The rule can run the following types of traces:
Connected—Run from the utility network or trace network elements currently represented in the diagram when the rule starts and spans outward along connected elements. Those connected network elements are appended to the diagram.
Subnetwork—Run 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 in the related subnetwork. All the subnetwork elements are appended to the diagram.
Upstream—Run from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements upstream. All the discovered upstream elements are appended to the diagram.
Downstream—Run from the utility network or trace network elements currently represented in the diagram when the rule starts to discover elements downstream. All the discovered downstream elements are appended to the diagram.
Shortest path—Run from the utility network or trace network elements currently specified as starting points in the diagram when the rule starts to find the shortest path between those starting points in the network. The cost of traversing the path is based on the network weight set for the Path Network Weight Name value, regardless of flow direction. All the discovered elements along this shortest path are appended to the diagram.
Path—Run from the utility network elements currently specified as starting points in the diagram when the rule starts to find the paths starting from those starting points in the network. The maximum number of paths and hops specified allow to limit the traced paths. All the discovered elements along the traced paths are appended to the diagram.
Circuit—Run from the utility network elements currently specified as starting points in the diagram when the rule starts to find the network elements that composed the related circuits in the trace network. All the discovered elements along the traced circuits are appended to the diagram.
Trace and Set Starting Point rules
When generating diagrams from network features or network objects selected as input in the network map, it is recommended that you use diagram templates set up using Set Starting Point rules before a Trace rule. In this case, the Set Starting Point rules query the expected starting points from the network elements currently represented in the diagram. Then the Trace rule only operates from these starting points, and avoids running multiple traces from each network element and affecting performance. When none of the starting points specified by the Set Starting Point rules can be retrieved among these network elements, the Trace rule is skipped.
When generating diagrams from trace locations currently specified in the network map, such a Set Starting Point rule before a Trace rule is not always necessary among the template rules. In all cases, any Set Starting Point rule configured on the template before the first Trace rule in the template rule sequence is ignored when this first trace applies.
When generating circuit diagrams from the Find circuits pane, any diagram rules configured before the Trace rule along the sequence of rules set up on the associated telecom template is ignored. To learn more about circuit diagram building process, see Rule and layout definitions specifics for circuit diagram template.
Several Set Starting Point and Trace rules can be specified in the rule sequence configured for a diagram template. To learn more about how Set Starting Point rules and Trace rules are combined in the diagram build process depending on the type of input used for the diagram generation, see Set Starting Point rule process.
Configure Trace rules
You can add a Trace rule on a template with the Add Trace Rule tool.