Diagram rules are specific tasks, executed during network diagram generation and update, that discard certain network elements, add extra features or objects, or simplify diagram content. Diagram rules are also used to configure specific flags in the resulting diagrams.
Overview
The rules can be used to do the following (depending on the rule):
- Modify diagram content; that is, refine the graph itself by doing any of the following:
- Discarding certain network elements (Remove Feature rule)
- Adding extra features or objects (Add Connectivity Associations, Add Structural Attachments, Trace, Spatial Query, and Expand Container rules)
- Simplifying diagram content by aggregating network elements (Reduce Junction, Reduce Edges, and Collapse Container rules)
- Set up specific flags, such as root flags or starting points, on features contained in the diagram (Set Root Junction and Set Starting Point rules).
- Control the execution of other rules, in particular, iterate on a particular sequence of rules (Start Iteration and Stop Iteration).
Diagram rules are executed during diagram generation and update when they have been configured on the template on which the diagram is based.
Starting from the network features or objects in input, the building process first builds the diagram features expected in the generated diagram—it builds one diagram feature for each network element in input. Then, when rules are configured on the template, they operate on those initial diagram features to automatically simplify diagram content (for example, reduction rules) or create new diagram features (for example, tracing rules) in the diagrams.
Several rules can be configured on a template; they are generally chained in their entry sequence order: rule 1 running on the diagram features built at the end of the elementary build phase and rule N on the features resulting from the execution of rule (N-1).
Note:
The only exception to this is the Add Structural Attachment rule. This rule is systematically executed last regardless of where you set it up in the rule sequence.
Diagram graph modification rules
The rules described in the following sections are all used to modify the diagram graph.
Remove Feature
The Remove Feature rule is used to remove specific network features or network objects represented in diagrams. This rule removes these network elements by source class or object table and, optionally, filters them based on connectivity constraints, or their attributes.
It is useful to automatically discard network features or network objects that may be present among the input network elements set during diagram building. For example, to generate diagrams representing the distribution part of a network that is selected in the network map, you can use a diagram template configured with the Remove Feature rule that automatically discards all network features or network objects from the input network elements except distribution lines.
Trace
The Trace rule is used to run a trace from utility network or trace network elements currently represented in a diagram.
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 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.
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.
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.
Expand Container
The Expand Container rule is used to expand diagrams by adding content features or objects that adhere to the following:
- They are contained in a container in the diagram input.
- They share the same container as content in the diagram input.
The Expand Container rule expands the containers by source class or object table and, optionally, filters them based on their attributes.
Add Connectivity Associations
The Add Connectivity Associations rule is used to add explicit edges to the diagram that represent connectivity associations for both the from and to junctions that are currently represented in the diagram.
Connectivity associations are not drawn by default in a network map. The Add Connectivity Associations rule allows you to generate diagrams in which connectivity associations are systematically drawn each time the related from and to junctions are present in the diagram at the time the rule executes. They display as straight diagram edges between the from and to diagram junctions they connect.
Add Structural Attachments
The Add Structural Attachments rule is used to add explicit edges to the diagram that represent structural attachment associations for both the attached network element and the structure element that are currently represented in the diagram.
Structural attachment associations are not drawn by default in a network map. The Add Structural Attachments rule allows you to generate diagrams in which structural attachment associations are systematically drawn each time the attached network element and structure element are present in the diagram at the time the rule executes. They appear as straight diagram edges between the related attached and structure diagram features.
Spatial Query
The Spatial Query rule is used to detect new network features based on their location relative to network features that currently exist in the diagram, and append the newly detected features to the network diagram.
The Spatial Query rule appends features that belong to a network class based on their location relative to network features that belong to another network class. Optionally, the existing features as well as the appended features can be filtered based on SQL expressions.
Collapse Container
The Collapse Container rule is used to simplify diagrams by collapsing all contents related to containers that may exist in diagrams.
The Collapse Container rule collapses the containers by source class or object table and, optionally, filters them based on their attributes.
Reduce Junction
The Reduce Junction rule is used to simplify the diagram graph while preserving the topology.
The Reduce Junction rule reduces junctions that belong to network junction classes or object tables based on the number of junctions to which they connect. Optionally, the junctions can be filtered based on specific attribute values or attributes from adjacent edges before being reduced.
Reduce Edge
The Reduce Edge rule is used to simplify the diagram graph while preserving the topology by merging each expected network line feature or edge object and all its connection points into a schematic diagram junction. This type of junction is called a reduction junction.
Any reduction junction in the resulting diagram aggregates one network line feature or edge object and all its connection points; that is, a reduction junction cannot aggregate several network line features or several edge objects.
Set up flags, capability, or starting points on diagram feature rules
The rules described in the following sections are used to set some diagram features so they are taken into account by other diagram rules or layouts afterward.
Set Root Junction
The Set Root Junction rule is used to specify junctions based on a network junction class or object table as diagram root junctions by filtering those junctions based on their attributes, if any.
Since the root junctions are specific junctions from which tree layouts operate when they execute on network diagrams, this rule is typically configured on templates that are set up to automatically execute tree layouts at diagram generation.
Set Starting Point
The Set Starting Point rule is used to preset network elements represented in the diagram as starting points.
When a Set Starting Point rule is preset before a Trace rule, it identifies the specified starting points as the only starting points instead of running all the network elements represented in the diagram at the time it executes.
Add Diagram Feature Capability
The Add Diagram Feature Capability rule is used to assign a particular capability on some diagram features currently represented at the time it executes.
This capability may be considered by some other rules that are configured to go into action later in the rule sequence.
Rule sequencing
Diagram rules are configured on a diagram template to be executed each time a diagram based on this template is generated or updated.
Their execution follows specific properties and principles you must keep in mind when configuring a rule sequence on a diagram template:
- Each rule process is iterative.
- The result of a rule sequence execution depends on each rule position in this sequence.
- A rule sequence is not iterative by default.
Each rule process is iterative
Each rule runs individually as an iterative in-memory process.
For example, when configuring a Reduce Junction rule to reduce particular network junctions when they connect a single junction, the Reduce Junction rule runs once to reduce all the expected junctions in the diagram graph. Then, it runs again to reduce any new junctions that became connected to a single junction after the first iteration of the rule, and so on, until such junctions no longer exist in the diagram graph.
 |
 |
 |
 |
In the same way, when configuring an Expand Container rule to systematically expand particular network junctions when they are containers, the Expand Container rule runs once to expand all the expected junctions in the diagram. Then, it runs again to expand any new containers that may have been added to the diagram after the first iteration of the rule, and so on, until such containers no longer exist in the diagram graph.
 |
 |
 |
The result of a rule sequence execution depends on each rule position in this sequence
Processing a rule sequence is not a commutative operation. That is, the entry sequence order of the rules being chained—rule#1 running on the diagram features initially built from the set of network elements used as input and rule#N on the diagram features resulting from the execution of rule#(N-1)—is decisive and determines the final content of the diagrams.
- This is true when there are different types of rules to be chained during the diagram building Rules phase—that is, when combining the Reduce Junction rule, Remove Feature rule, Expand Container rule, Collapse Container rule, Add Connectivity Associations rule, and Trace rule during the rule phase.
For example, running the Reduce Junction rule and then running the Expand Container rule (Rules configuration 1) doesn’t give the same result as running the Expand Container rule first and then running the Reduce Junction rule (Rules configuration 2).
Graphic A—Sample diagram content before the rules execution: This graphic shows the content of a sample diagram before the rule sequence execution. 
Graphic A1—Sample diagram content after executing Rules configuration#1: This graphic shows the content of the diagram after reducing junctions first and then expanding containers. 
Graphic A2—Sample diagram content after executing Rules configuration#2: This graphic shows the content of the diagram after expanding containers first and then reducing the junctions. - This is also true when chaining several rules of the same rule type during the diagram building Rules phase.
For example, running the Reduce Junction rule to reduce any blue junctions connected to a single junction and then running the Reduce Junction rule again to reduce any green junctions connected to a single junction (Rules configuration#3) is not the same as reducing the green junctions first and then reducing the blue junctions (Rules configuration 4).
Graphic B—Sample diagram content before the rules execution: This graphic shows the content of a sample diagram before the rules execution. 
Graphic B1—Sample diagram content after executing Rules configuration 3: This graphic shows the content of the diagram after reducing the blue junctions first, followed by the green junctions. 
Graphic B2—Sample diagram content after executing Rules configuration 4: This graphic shows the content of the diagram after reducing the green junctions first, followed by the blue junctions.
A rule sequence is not iterative by default
A rule sequence is not iterative by default. Each rule process is individually iterative, but a sequence of rules is never iterated by default.
For example, graphics B1 and B2 above show the sample diagrams after the configuration 3 and 4 rule sequence is executed once. For these particular samples, executing each rule sequence twice produces the same result, that is, a complete reduction of both all green and blue junctions connected to a single junction in the two diagrams.
 | |
Two specific rules are required to make your rule sequence iterative when you need to configure multiple reduce junction rules with junctions that connect one other junction and consequently change the number of junctions connecting the remaining target junctions during their execution: Start Iteration and Stop Iteration.
- The Start Iteration rule is used to notify the beginning of a rule sequence on which the diagram builder process will iterate or loop.
- The Stop Iteration rule is used to notify the end of a rule sequence on which the diagram builder process must iterate or loop.
These two specific rules are particularly useful when configuring rule sequences that chain several reduce junctions rules. Since reduce junction rules connecting one other junction change the number of connections of the remaining junctions, those remaining junctions potentially become new candidates for a reduction rule that was previously executed. Because of the Start and Stop rules, the build process iterates on the identified sequence until there are no longer any junctions to reduce.
To add a Start Iteration rule and a Stop Iteration rule on a template, use the Add Start Iteration Rule and Add Stop Iteration Rule tools.
Caution:
Reducing junctions that connect three or more other junctions is time consuming and must be processed after all other reduce junction rules complete. To optimize diagram generation and update performance, avoid mixing junction reduction rules that process junctions connecting a maximum of two other junctions and a minimum of three other junctions inside the same iterative sequence. The recommended workflow is as follows:
- Configure a first iterative sequence of reduction rules to process junctions that connect a maximum of two other junctions.
- Then, configure a second iterative sequence of reduction rules to process junctions that connect a minimum of three other junctions.
Recommendations and warnings for rule execution
Keep the following in mind when configuring diagram rules:
- Remove Features rules—Configured using the Add Remove Feature Rule or Add Remove Feature By Attribute Rule tools, Remove Features rules can be executed at the first position of the rule sequence to systematically discard particular network features or network objects from the diagram before refining the diagram graph.
For example, execute the Add Remove Feature Rule tool with the Exclude source classes rule process to discard any network features or network objects related to all network source classes and object tables except some specific network source classes or object tables. Also, since graph completeness is always maintained in network diagrams, excluding a particular line class (for example, a transmission line) while running Source Type = EDGES may be helpful to ensure your diagrams build on a given part of the network, in other words, the transmission network in this example.
- Spatial Query rules—Added using the Add Spatial Query Rule tool, Spatial Query rules can be set up in the rule sequence at any time but may be useful at the beginning of the rule sequence to include all features of interest.
- Trace rules—Added using the Add Trace Rule tool, Trace rules are generally one of the first rules you set up in the rule sequence when you want to configure a template to generate diagrams from traces. In this case, you can also configure Set Starting Point rules on the template to set specific features or junction terminals as starting points for the Trace rule execution. Starting Points rules must be set up before the Trace rule in the diagram template rule sequence using the Add Set Starting Point By Attribute Rule tool.
- Expand Containers rules—Configured using the Add Expand Container Rule or Add Expand Container By Attribute Rule tool, Expand Containers rules allow you to expand containers in diagrams. They are generally set up before any rules that simplify the diagram graph.
- Add Connectivity Associations rule—Configured using the Add Connectivity Associations Rule tool, Add Connectivity Associations rules can be set up to get the connectivity associations represented in the diagrams and ensure graph completeness before collapsing or reducing features.
Caution:
Avoid configuring this rule when it is not needed because it is time-consuming. For example, adding connectivity associations is not relevant to a template configured to run a Trace rule, since the connectivity associations will already be systematically returned by the trace.
- Add Diagram Feature Capability rules—Added using the Add Diagram Feature Capability By Attribute Rule tool, Add Diagram Feature Capability rules can be set up to manage collapsing of containers or reduction of junctions with precision. They can be used to prevent particular containers from collapse or particular junctions to be reduced during all or part of the diagram building.
- Collapse Containers rules—Set up when running the Add Collapse Container Rule or Add Collapse Container By Attribute Rule tool, Collapse Container rules are executed to collapse containers in diagrams. They must be executed after the Expand Container rules if you want to keep track of all contents related to the collapsed containers.
- Start Iteration rules—Configured using the Add Start Iteration Rule tool, the Start Iteration rule must be positioned at the beginning of a Reduce Junction rule iterative sequence. It forces the building diagram process to loop on the Reduce Junction rule sequence until there are junctions in the diagram, which is reduced by one of the rules in that sequence.
- Reduce Junction rules—Added when running the Add Reduce Junction Rule and Add Reduce Junction By Attribute Rule tools, Reduce Junction rules are used to simplify the diagram graph.
Caution:
During configuration, do not use Reduce Junction rules that process junctions connecting a maximum of two other junctions with Reduce Junction rules that process a minimum of three other junctions inside the same reduction rules' iterative sequence. Using these together decreases performance at diagram generation. To reduce junctions connecting a minimum of three other junctions, set up two iterative sequences—the first one to process the reduction of junctions connecting a maximum of two other junctions and the second for the reduction of junctions connecting a minimum of three other junctions.
Tip:
Because content junctions do not aggregate noncontent elements and noncontent junctions do not aggregate content elements, you can configure a Remove Feature rule before reducing junctions to remove any polygon containers and all content-container relations in the diagram and force reductions.
- Stop Iteration rules—Configured using the Add Stop Iteration Rule tool, Stop Iteration rules must be positioned at the end of a Reduce Junction rule iterative sequence, in other words, just after the last Reduce Junction rule in the sequence where you want the build process to iterate.
- Reduce Edge rules—Set up using the Add Reduce Edge By Attribute Rule tool, Reduce Edge rules reduce edges.
- Structural Attachment rules—Configured using the Add Structural Attachments Rule tool, Structural Attachment rules are systematically executed last wherever they are set up in the rule sequence.
Caution:
Avoid configuring this rule when it is not needed because it is time-consuming. For example, adding structural attachments is not relevant to a template configured to run the following:
- A Trace rule that does not include structures
- Remove Feature rules set up to process structure junctions that support attachments
Note:
You can also set up Remove Feature rules under these specific circumstances:
- After a Trace rule or after an Expand Containers rule to remove container relations in the diagram graph. This simplifies the diagram graph.
- At the end of your rule sequence to clean the diagram graph or simplify the diagram, for example, to systematically remove linear container edges, since having both the network linear containers and their related contents represented in the diagrams may be confusing or irrelevant.
The following diagram illustrates the recommended position for each rule in the rule sequence according to the recommendations outlined above:
Note:
Keep in mind that each rule is optional, and most of the usual rule sequences configured for a diagram template fit various parts of the sequence detailed above.