Use geoprocessing models to manage diagram template rule and layout definitions

You can create diagram templates through manual execution of individual geoprocessing tools. This process is typically the following: In the Geoprocessing pane, run the Add Diagram Template tool, and run the Add <XXX> Rule or Add <XXX> Layout tool. Through this process, each rule is added in a systematic order because the sequence of rules for a template is arranged based on the order in which the rule was added; in other words, each newly added rule is appended to the end of the template rule sequence. Additionally, each newly added layout is appended to the end of the template layout sequence based on the order in which the layout is added.

However, for greater control over your template configuration and to document its structure, it is strongly recommended that you use ModelBuilder to create a geoprocessing model of your diagram template's rule and layout definitions. A geoprocessing model functions in a similar manner to the network diagrams building process. Both operations provide organization and structure for three main phases:

• Phase 1—Create a template and configure its elementary properties.
• Phase 2—Add rules that define the final diagram content.
• Phase 3—Add the set of diagram layouts that generate the presentation (spacing, visibility, and so on) of a diagram.

To control the creation process of your templates, the set of tools in a diagram template's rule and layout definitions geoprocessing model must be chained so that the output network and diagram template of the previous tool are the inputs to the next tool. This allows you to ensure the exact order of each rule in the template rule sequence as well as each layout in the template layout sequence. It results in better control over the content and its layout in the diagrams later based on this template.

Requirements and prerequisites

Adding diagram templates and editing their rule and layout definitions are administration and configuration tasks.

The requirements and prerequisites to configure a diagram template—for example, to create, alter, add rules or layouts to its definitions, export and import those definitions, and so on—are the same:

• This operation must be executed from either a utility network or trace network in a file or mobile geodatabase, or a database connection to the utility network or trace network in an enterprise geodatabase. When working with a utility network or trace network in an enterprise geodatabase, you can't work from a service.
• For the case of a database connection to a utility network or trace network in an enterprise geodatabase, you must connect using the credentials of the database network owner; that is, using the database utility network owner or database trace network owner credentials.
• When working with a database connection to a utility network or trace network in an enterprise geodatabase, you must sign in to your ArcGIS Enterprise portal using the credentials of the portal network owner; that is, using the portal utility network owner or portal trace network owner credentials.

Create a diagram template's rule and layout definitions geoprocessing model

The subsections below provide steps for each phase of the ModelBuilder workflow.

Phase 1—Create a template and configure its elementary properties

The first phase in configuring a geoprocessing model is to create a template and configure elementary properties for it. In most cases, this step requires two tools:

• Add Diagram Template—Create a template for a given network.
• Alter Diagram Template—Set up template elementary build settings, for example, the way GIS vertices must be managed along diagram edges or the size of margins on diagram containers.

1. Start ArcGIS Pro.
2. When working with a utility network or trace network in an enterprise geodatabase, sign in to your ArcGIS Enterprise portal using the credentials of the portal network owner—that is, using the portal utility network owner or portal trace network owner credentials.
3. Load your project or create one.
4. Depending on the geodatabase you want to work with, do one of the following:
   • When working with a utility network or trace network in a file or mobile geodatabase, add the file or mobile geodatabase to the project.
   • When working with a utility network or trace network in an enterprise geodatabase, add the database connection file to the project or create one.

     Caution:

     Make sure the utility network or trace network is registered as branch versioned and you are connecting using the credentials of the database network owner—that is, using the database utility network owner or database trace network owner credentials.

5. On the Analysis tab, click ModelBuilder.

   A new geoprocessing model view named Model opens.

6. Open the Geoprocessing pane, click Toolboxes, and expand the Network Diagram Tools toolbox.
7. Expand the Configuration toolset and drag the Add Diagram Template tool to the model view.
8. Double-click the Add Diagram Template box on the model view and do the following:
   1. Click the browse button next to the Input Network box, go to Project/Databases, select the database connection file, and browse to the network.
   2. Type a name for the new template in the Diagram Template Name box.
   3. Click OK.
9. From the Configuration toolset, drag the Alter Diagram Template tool to the model view.
10. Connect the output variables of the Add Diagram Template tool to the Alter Diagram Template tool as follows:
    1. Click the output network variable of the Add Diagram Template tool while you move the pointer to the Alter Diagram Template tool. Click Input Network.
    2. Click the output template variable of the Add Diagram Template tool while you move the pointer to the Alter Diagram Template tool. Click Input Diagram Template.
11. Double-click the Alter Diagram Template box and set up the container margin as follows:
    1. Check Default template if you want this new template to be the default diagram template.
    2. In the Description text box, type a description for your diagram template.
    3. Expand the Template General Definitions section.
    4. Depending on your network coordinate system, type an appropriate value for the container margin size.

       For example, type 0.2 for Container Margin and select Meters from the drop-down list.

    5. Uncheck Enable diagram storage if you want to prevent users from storing diagrams based on this template. Typically, this makes sense if your template is designed to generate a single diagram for data control purposes.
    6. Check Enable to extend diagram if you want users to be able to extend diagrams based on this template.
    7. Click OK.

Your diagram template geoprocessing model should look like the following:

Phase 2—Add rules that define the final diagram content

The second phase in the configuration of a diagram template's rule and layout definitions geoprocessing model is dedicated to rules. It uses tools such as Add <XXX> Rule or Add <XXX> By Attribute Rule to add a new rule to the template rule sequence. The sequence of rules created by these tools defines the order in which the diagram building process will execute the rules, defining the content of diagrams based on that template.

Rules are used to modify the diagram graph, but each rule operates a specific transformation of the graph that often justifies a common position in the rule sequence. For example, a Trace rule is generally set up at the beginning of the template rule sequence, Reduce Junction rules are often configured at the end of the rule sequence, and Remove Feature rules can be set up at any position in the sequence depending on their purpose.

As detailed in Diagram rules, the process of each rule in this chain is iterative, but the rule sequence is not. To adopt an iterative rule sequence, two additional tools are often used during this phase—Add Start Iteration Rule and Add Stop Iteration Rule. These tools must be used to iterate a sequence of multiple Reduce Junction rules that don't only process junctions connecting two other junctions; in other words, when among the Reduce Junction rules, there are junctions with one adjacent junction that are configured to be reduced. Reducing the junctions connecting one other junction causes the number of connections to the remaining junctions to change, so those remaining junctions potentially become new candidates for a reduction rule that was executed beforehand.

Keeping in mind that each rule is optional, most of the typical rule sequences you will configure should fit all or part of the sequence detailed below:

1. 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.

2. 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.
3. 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.
4. 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.
5. 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.

6. 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.
7. 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.
8. 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.
9. 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.

10. 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.
11. Reduce Edge rules—Set up using the Add Reduce Edge By Attribute Rule tool, Reduce Edge rules reduce edges.
12. 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:

Example of adding diagram rules to a diagram template

Prerequisite:

Create an elementary diagram template geoprocessing model as described in Phase 1—Create a template and configure its elementary properties.

The steps below are an example of Phase 2 diagram template configuration. The purpose is to chain the Add <XXX> Rule or Add <XXX> By Attribute Rule tool in a diagram template to allow the generation of diagrams from a subnetwork trace that starts from the circuit breakers among the input features. The resulting trace will then be simplified by collapsing most of the containers and reducing junctions and devices, except circuit breakers and switches. To ensure the diagrams based on this template will strictly reflect the expected subnetwork traces, some Remove Feature rules will be configured at the beginning of diagram generation to discard all unexpected input features.

1. Open the diagram template geoprocessing model you created in the previous section.
2. Configure diagram rules to remove any unexpected features that may have been selected as input. In this example, Remove Feature rules are set up to discard all input features, except structure boundaries and circuit breaker distribution devices:
   1. In the Configuration toolset, drag the Add Remove Feature Rule tool to the model view.
   2. Use steps 10a and 10b from the Phase 1 workflow above to connect output variables from Alter Diagram Template as input for Add Remove Feature Rule.
   3. Double-click the Add Remove Feature Rule tool in the model and set the rule parameters to remove all features except electric distribution devices and structure boundaries as follows:

      • Source Type—Select Both junctions and edges.
      • Rule Process—Select Exclude source classes.
      • Network Sources—Select ElectricDistributionDevice, and select Structure Boundary.

   4. Click OK.
   5. In the Configuration toolset, drag the Add Remove Feature By Attribute Rule tool to the model view.
   6. Connect the output variables from Add Remove Feature Rule as input for Add Remove Feature By Attribute Rule.
   7. Double-click the Add Remove Feature By Attribute Rule tool in the model and set the rule parameters to remove any electric distribution devices except circuit breakers:

      • Network Source To Remove—Select ElectricDistributionDevice.
      • Expression—Click New Expression. Then select Asset group for Field, and click Is not equal to as the expression operator. Check 4 - CircuitBreaker for Values, and click Update.

   8. Click OK.
3. Set the starting points among the features that will remain. In this example, a Set Starting Point rule is configured to set any circuit breaker with a terminal ID of 3/ Load as a starting point:
   1. From the Configuration toolset, drag the Add Set Starting Point By Attribute Rule tool to the Model tab.
   2. Connect the output variables from Add Remove Feature By Attribute Rule as input for Add Set Starting Point By Attribute Rule.
   3. Double-click the Add Set Starting Point By Attribute Rule tool in the model and set the rule parameters:

      • Network Source—Select ElectricDistributionDevice.
      • Expression—Click New Expression. Then select Asset group for Field, and click Is equal to as the expression operator. Check 4 - CircuitBreaker for Values, and click Update.
      • Junction Terminal(s)—Check 3/Load.

   4. Click OK.
4. Add a Trace rule to trace medium-voltage distribution subnetworks:
   1. Double-click the Add Trace Rule tool in the model and set up a Trace rule to trace subnetworks as follows:

      • Trace Type—Select SUBNETWORK.
      • Domain Network—Select ElectricDistribution.
      • Tier—Select Medium Voltage.

   2. Click OK.
5. Collapse containers. In this example, the Collapse Containers rule is configured to collapse all containers except structure boundaries:
   1. In the Configuration toolset, drag the Add Collapse Container Rule tool to the model view.
   2. Connect the output variables from Add Trace Rule as input for Add Collapse Container Rule.
   3. Double-click the Add Collapse Container Rule tool in the model and set the rule parameters:

      • Container Type—Select Both junctions and edges.
      • Rule Process—Select Exclude source classes.
      • Container Sources—Select StructureBoundary.
      • Aggregate reconnected edges—Leave the box checked.

   4. Click OK.
6. Loop on a sequence of reduction rules to reduce all junctions that have 0, 1, or 2 other junctions, except distribution devices and assemblies; reduce all distribution assemblies except the switch gears and switch banks; and reduce all distribution devices except the circuit breakers and switches:
   1. In the Configuration toolset, drag the Add Start Iteration Rule tool to the model view.
   2. Connect the output variables from Add Collapse Container Rule as input for Add Start Iteration Rule.
   3. In the Configuration toolset, drag the Add Reduce Junction Rule tool to the model view.
   4. Connect the output variables from Add Start Iteration Rule as input for Add Reduce Junction Rule.
   5. Double-click the Add Reduce Junction Rule tool in the model and set the rule parameters:

      • Rule Process—Select Exclude source classes.
      • Junction Sources—Select ElectricDistributionDevice and select ElectricDistributionAssembly.
      • Connectivity constraints—Expand this section:
        • Reduce Junctions With—Select Maximum two connected junctions.
        • Reduce if unconnected—Check the box.
        • Reduce if connected to a single junction—Check the box.
        • Reduce if connected to 2 different junctions—Leave the box checked.

   6. Click OK.
   7. In the Configuration toolset, drag the Add Reduce Junction By Attribute Rule tool to the model view.
   8. Connect the output variables from Add Reduce Junction Rule as input for Add Reduce Junction By Attribute Rule.
   9. Double-click the Add Reduce Junction By Attribute Rule tool in the model and set the rule parameters:

      • Junction Source To Reduce—Select ElectricDistributionAssembly.
      • Expression—Click New Expression. Then select Asset group for Field and click Does not include the value(s) as the expression operator. Check 8 - Switch bank and 9 - Switchgear for Values and click Update.
      • Connectivity constraints—Expand this section:
        • Reduce Junctions With—Select Maximum two connected junctions.
        • Reduce if unconnected—Check this box.
        • Reduce if connected to a single junction—Check this box.
        • Reduce if connected to 2 different junctions—Leave this box checked.

   10. Click OK.
   11. In the Configuration toolset, drag the Add Reduce Junction By Attribute Rule tool to the model view.
   12. Connect the output variables from the first Add Reduce Junction By Attribute Rule as input for the second Add Reduce Junction By Attribute Rule.
   13. Double-click the second Add Reduce Junction By Attribute Rule tool in the model and set the rule parameters:

       • Junction Source To Reduce—Select ElectricDistributionDevice.
       • Expression—Click New Expression, select Asset group for Field, and click Does not include the value(s) as the expression operator. Check 4 - Circuit Breaker and 15 - Switch for Values and click Update.
       • Connectivity constraints—Expand this section:
         • Reduce Junctions With—Select Maximum two connected junctions.
         • Reduce if unconnected—Check this box.
         • Reduce if connected to a single junction—Check this box.
         • Reduce if connected to 2 different junctions—Leave this box checked.

   14. Click OK.
   15. In the Configuration toolset, drag the Add Stop Iteration Rule tool to the model view.
   16. Connect the output variables from Add Reduce Junction By Attribute Rule as input for Add Stop Iteration Rule.

The second phase of your diagram template geoprocessing model should look similar to the following:

Phase 3—Add the set of diagram layouts

The third phase of your template configuration is dedicated to layouts. This consists of defining the set of active layouts with their parameter values and presetting default parameter values for those added as inactive layouts. It is configured using the Add <XXX> Layout tools, which allow a new layout to be added to a template layout sequence. The order of the active layouts in the sequence determines the order in which the layouts are executed at diagram generation.

Note that the Set Root Junction rule is tied to the execution of certain layouts that can be set up during this third phase. It is configured using the Add Set Root Junction Rule By Attribute Rule tool. This rule allows you to flag junctions in the generated diagrams as root junctions that can then be taken into account by the layouts you set up to apply to the diagrams.

As with the rules phase, the layouts phase must be carefully set up when configuring diagram templates. It is recommended that you proceed in the following order:

1. Configure the Set Root Junction rules using the Add Set Root Junction Rule By Attribute Rule tool.
2. Set up the sequence of active layout algorithms in the order you want them to execute during the diagram generation—when running the appropriate Add <XXX> Layout tool with the Active option enabled.
3. Set up the list of inactive layout algorithms—when running the appropriate Add <XXX> Layout tool with the Active option disabled.

Note:

To maintain your diagram template geoprocessing model in the future, do not mix active and inactive layouts.

Note:

When configuring the sequence of active layout algorithms, keep the following in mind:

• There is no benefit to configuring the execution of schematic layouts that preserve or try to preserve the current positions of the diagram features—for example, Linear Dispatch, Spatial Dispatch, and so on—before executing a tree layout, such as Radial Tree, Smart Tree, and Mainline Tree layouts.
• Partial Overlapping Edges and Reshape Diagram Edges layouts are often used as active refining algorithms executed at the last position in the template layout sequence.

As an example, the steps below describe the template configuration geoprocessing tools that must be chained together to lay out the generated diagram content as a smart tree, starting with circuit breakers as root junctions with tree branches arranged from the top to the bottom, and in which all the edges that may become overlapping after the Smart Tree layout execution are systematically separated.

Example of adding diagram layouts to a diagram template

Prerequisite:

Create a diagram template geoprocessing model as described in Phase 1—Create a template and configure its elementary properties and Phase 2—Add rules that define the final diagram content.

1. Open the diagram template geoprocessing model you created in the previous section.
2. In the Configuration toolset, drag the Add Set Root Junction By Attribute Rule tool to the model view.
3. Use steps 10a and 10b from the Phase 1 workflow to connect output variables from Add Stop Iteration Rule as input for Add Set Root Junction By Attribute Rule.
4. Double-click the Add Set Root Junction By Attribute Rule tool in the model and set up the Set Root Junction rule so it flags each circuit breaker as a junction root:
   1. Select DistributionDevice from the first drop-down list under Junction Source To Select.
   2. Click New Expression.
   3. Select Asset group for Field, click is Equal to as the expression operator, and check 4 - CircuitBreaker for Values. Click Update.
   4. Click OK.
5. In the Configuration toolset, drag the Add Smart Tree Layout tool to the model view.
6. Connect output variables from Add Set Root Junction By Attribute Rule as input for Add Smart Tree Layout.
7. Double-click the Add Smart Tree Layout tool in the model and set up the layout algorithm so it arranges the tree branches from the top to the bottom:
   1. Leave the Active box checked so the algorithm activates during diagram generation.
   2. Select From top to bottom from the Tree Direction drop-down list.
   3. Click OK.
8. In the Configuration toolset, drag the Add Reshape Diagram Edges Layout tool to the Model tab.
9. Connect output variables from Add Smart Tree Layout as input for Add Reshape Diagram Edges Layout.
10. Double-click the Add Reshape Diagram Edges Layout tool in the model and set up the layout algorithm so it separates edges that may be overlapping in the diagram:
    1. Leave the Active box checked so the algorithm activates during diagram generation.
    2. Select Separate overlapping edges from the Reshape Operation drop-down list.
    3. Click OK.

The third phase of your diagram template geoprocessing model should look similar to the following:

Run a diagram template's rule and layout definitions geoprocessing model

To create a diagram template and generate diagrams based on it, complete the following steps:

Prerequisite:

Create a diagram template's rule and layout definitions geoprocessing model as described in the section above and open it for editing.

1. Click the ModelBuilder tab and click Validate.
2. Click Run.
3. Click Save to save the diagram template geoprocessing model in your project toolbox.
4. Open the map that references the network from which you want to generate diagrams.
5. Select some network features on the map.
6. Select the network layer in the Contents pane.
7. Click the Utility Network or Trace Network tabs and click the arrow under the New button in the Diagram group.

Verify that a new item corresponding to the name of the newly created template appears in this template list.

To make the template you just created fully operational for working with the related service, sign in to your ArcGIS Server Manager portal using the administrator credentials, and stop and restart this service.

Maintain a diagram template's rule and layout definitions geoprocessing model

The Add Diagram Template tool cannot be executed on an existing diagram template. To edit your diagram template geoprocessing model in the future, modify the model so it uses the Alter Diagram Template tool as described in the following steps:

Prerequisite:

Open your diagram template geoprocessing model for editing.

1. Remove the connection between the input network parameter of the Add Diagram Template tool and the tool itself.
2. Select the Add Diagram Template tool in the model and press Delete.
3. Connect the remaining input network parameter to the Alter Diagram Template tool—in other words, click the input network variable while you move the pointer to the Alter Diagram Template tool, and click Input Network.
4. Modify the Alter Diagram Template tool settings so it overwrites the template rule and layout definitions each time it executes:
   1. Double-click the Alter Diagram Template tool in the model.
   2. Check the Remove the diagram template rule and layout definitions check box.
   3. Click OK.
5. Save the diagram template geoprocessing model.

Caution:

Removing the rule and layout definitions for an existing template as explained above is essential to correctly maintain its settings.

Since all the tools chained in a diagram template geoprocessing model are executed to put all the settings in place, running the model with the Remove the diagram template rule and layout definitions check box checked for the Alter Diagram Template tool allows you to remove both the template rule and layout sequences before reinitializing all the template settings.

When rerunning the diagram template geoprocessing model without checking this box, each rule and layout processed is added to the end of the template rule and layout sequences, causing the same set of rules and algorithms to be configured several times. This makes the content of diagrams based on the template unsuitable.

Tip:

All the geoprocessing models you build are saved in your ArcGIS Pro project toolbox by default. To avoid losing your diagram template geoprocessing model when this project is deleted, create your own toolbox in a safe location on your local disk, and keep a backup of all your diagram template geoprocessing models in this toolbox.