Best Practices for working with Utility Network: Named Trace Configuration

[MichaelHirschheimer]

With the increasing number of parameters that the trace GP tool contains it is important to make the workflow easier to run any type of trace.   Once configured, these traces are not confined to GIS analysts in the office.  They can be shared with an audience who aren't GIS savvy.   This can be achieved with the use of Named Trace Configuration which was introduced with version 5 of the Utility Network. 

Named Trace Configuration stores complex trace settings in the geodatabase and shares them via Web Maps across the ArcGIS stack.  This includes ArcGIS Pro 2.9.x, Field Maps, Experience Builder, Instant Apps, and others.  Users can simply choose a Named Trace Configuration from a pick list and not have to worry about the details of the trace. 

In this blog, I’ll cover best practices regarding the setup of Named Trace Configurations and managing the Web Maps that use them.

Trace Configurations Naming Standards

In my team, multiple Solution Engineers were adding trace configurations without naming standards, and it got confusing rather quickly.  Based on the data available in the Network Options – Sharing dialog, I couldn’t infer much details about its configuration, such as purpose, tier, status, etc.   Coming up with a standard naming convention with meaningful details was necessary for Named Trace Configuration to be efficient, especially when working in groups.  At a minimum, I suggest having the naming standard along with a meaningful description to answer these questions:

• What Tier is this trace running against?
• Is this trace ready to be used in Fields Maps or a Web App?

The naming convention used in the screenshot is:   <Trace Type> - <Tier Name>.   

• Upstream – Distribution
• Upstream - Transmission

If your Utility Network has multiple industries (ex:  Electric and Communications), adding a industry prefix would be useful. 

• Elec: Upstream - Distribution
• Comm:  Upstream - Cable

In the description attribute, I used the keywords “Authoritative” and “Work in Progress” to signify the status of the configuration.  This gave confidence to my team members that they are using vetted Named Trace Configurations in their workflows and Web Maps.

Trace to Trace Configuration GP Tool

Using ArcGIS Pro 2.9.x, in the core Utility Network Tools GP toolbox, there is no GP tool to import the results of a trace into a Named Trace Configuration.  However, there is an Esri downloadable python toolbox called, Utility Data Management Support tools, that provides functionality to import the results of a trace into a Named Trace Configuration along with many other useful tools.

Details and download directions for the Utility Data Management Support toolbox  are located here.

Upon adding the Utility Data Management Support toolbox to your ArcGIS Pro Project, you can use the “Trace to Trace Configuration” GP tool to take python syntax for a successful trace execution and create a new Named Trace Configuration.

Here is the workflow to create the Named Trace Configuration from trace results

1. Manually configure the Trace GP tool with the parameters you need and run the trace
2. Open this History tab, right click on the Trace entry and select the “Copy Python Command"
3. Open the Trace to Trace configurations GP tool and paste the python command into the “Python” text box
4. Enter a Trace Configuration Name and Description and hit the run button
5. Note:  This screen shot was taken in March 2023.  You'll need to download the latest Utility Data Management Support toolbox if you are seeing an older version of this GP tool.

          

Sharing Named Trace Configuration to a Web Map

To execute a trace in Field Maps or a Web Application, you’ll need to assign a Named Trace Configuration to a Web Map and then share the Web Map to your portal.  At the time this blog was published, ArcGIS Pro 2.9.x is the only client where Named Trace Configuration can be assigned to a Web Map.

Follow these steps to

1.   Assign an existing Named Trace Configuration to a Web Map 
2.   Publish a Web Map to your Enterprise portal

In ArcGIS Pro, there are no capabilities to overwrite an existing Web Map in Portal.  However, you can make changes directly in portal’s Web Map and then save those changes.

1. In ArcGIS Pro, open the Web Map from Portal
2. Catalog Pane – Portal --> Right click on Web Map --> Add and Open
3. Once the map is loaded, notice the “links” in the icon.  This indicates it’s linked from your Portal
4.  Make your Named Trace Configuration assignments
5. To save the Web Map to portal: From Share Tab --> Save Web Map (in Manage group)
6. Note:  The Save Web Map button is only enabled when a "linked" Web Map is the active map

          

How can I update an existing Named Trace Configuration?

You may have noticed that the Trace Configuration toolbox doesn’t contain an Update tool. 

There are currently no means to update any of the settings of the Named Trace Configuration from ArcGIS Pro.  The only option is to use the Trace Configuration REST API’s Alter command.

• I strongly recommend reviewing the REST API documentation before making any changes.  There is no undo operation with the REST API.

The Alter documentation informs us that the globalID parameter is required and that all others are parameters are optional.  To get the Trace Configuration Globalids, follow the path in the screenshot.

Using the screenshot below, when the alter (Post) button is clicked, the only attribute that will be updated is the description. 

I’ve been using this REST API to update the descriptions and occasionally the name.

I avoided the traceConfiguration parameter as it is a complex JSON object.  Unless you are comfortable with JSON and Fiddler, I suggest creating a new Named Trace Configuration within ArcGIS Pro as opposed to updating the traceConfiguration from the REST API.

Note:  If you change the name of a trace, you will need to save your Web Map(s) again from within ArcGIS Pro for it to recognize the new name.

Configure Field Maps and Web Apps to use Named Trace Configuration

Now that we’ve setup our Web Maps and Named Trace Configurations, we can begin tracing in Field Maps and creating web applications  with the UN trace widget.

Conclusion

Named Trace Configuration is a key piece of Utility Network functionality.  It stores complex trace settings in the Geodatabase which enables users to execute a specific trace by picking from a drop down list.  It’s also the means for accessing those same traces in Desktop, Mobile and Web applications. 

By sharing my firsthand experiences with Named Trace Configuration, you will be in a better position to implement and support it. 

I look forward to sharing more findings in our upcoming blogs. Stay tuned!

About the Author

Mike Hirschheimer is a solution engineer on the Utilities Team with a focus on the Utility Network.   He is a big sports fan who enjoys watching NFL & NBA games and playing disc golf.