The Trace rule is used to run a trace from utility network or trace network elements currently represented in a diagram.
Typically, the Trace rule is configured on diagram templates to run among the first rules during diagram building. The common workflow is to preset starting points among all the potential input utility network or trace network elements using a Set Starting Point rule beforehand, so the trace operates from these starting points only.
The starting points from which the trace executes depend on the trace type:
- 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.
Trace rule specifics
The rule can execute the following types of traces:
- Connected—Executed 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— 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 in the related subnetwork. All the subnetwork elements are appended to the diagram.
- Upstream—Executed 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—Executed 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—Executed from the 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 trace 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.
Trace and Set Starting Point rules
To avoid executing multiple traces from a large set of network elements and affecting performance, it is recommended that you configure Set Starting Point rules on any diagram template you set up 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 and run the trace only from these starting points. 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.
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, see Set Starting Point rule process
Configure Trace rules
You can add a Trace rule on a template with the Add Trace Rule tool.