Tracing in the ESRI Utility Network for Water

We are transiting our GIS water network data from ESRI’s geometric network to the Utility Network. This has been a long, involved process for the whole team, and we’ve been learning as we go. I took on the task of rewriting our Trace widget with no idea how challenging it would be. These are a few of the trickier things I figured out.

Performing traces in a web map

Our trace widget lets you click on the map to create a starting point and then places the results on the map. If you need to make something like this, I recommend using the trace widget that ESRI has built as a foundation to get you started. They have it for the ArcGIS API for JavaScript 4.x and the Web AppBuilder.

Network Trace widget-ArcGIS Web AppBuilder | Documentation

I used their 3.x version, which is no longer available on GitHub. The parts that query the REST endpoint to create starting points, run the trace, and place the results on the web map were very valuable to me. While the source code of this widget was pretty easy for me understand, the configuration was not.

Configuring barriers in the isolation trace

Ultimately, the widget makes a request to the /trace endpoint of your utility network web service using the ArcGIS REST API. When we run an isolation trace on our water network, we want there to be barriers at all of the controllable valves.

In ArcGIS Pro, you’d set it up it like this

How do you do that with the REST API? Well, I found out that if you turn on Verbose logging on your ArcGIS Server, you can look at the server log to see the request that ArcGIS Pro made to the server when it ran the trace. That will show you the proper way to structure the traceConfiguration parameters.

traceConfiguration=
{
     "filterBarriers":
          [{ "name": "Device Asset Group",
             "type": "networkAttribute",
             "operator": "equal",
             "value": 2,
             "combineUsingOr": false,
             "isSpecificValue": true
          }]
}

Configuring terminals and associations in the upstream/downstream trace

While our water traces are simple, because they are just looking at connectivity, the wastewater traces have to consider the direction of flow. In the geometric network, this can be determined by the digitization direction. There’s an ArcMap tool that you can use to turn it on:

After that, upstream and downstream traces “just work”

In the Utility Network, you have to designate features as sources that the flow is originating from. So my first step was to make all of my Wastewater Treatment Plants a Subnetwork Controller.

I did this using the Utility Network ribbon in ArcGIS Pro

That was only the beginning of the journey. I then discovered that my network had loops all over the place, which resulted in indeterminate flow.

Nothing was telling it whether it should go clockwise or counterclockwise around the circle

The only solution was to create input and output terminals at every manhole. The manholes needed to be changed to have an Asset Type of “Controller Point” before this was even possible.

Then, since we have thousands of manholes, it wouldn’t have been feasible to do the work manually. Luckily, we were able to use SSP Sync to auto-generate the input and output terminals based on the digitization direction.

Finally, we have a few areas where the pipes do not connect to the treatment plants on the map (the connecting features were too detailed to be drawn there). In these cases, we needed to create an association to tell the trace where to go.

Total traced distance in widget

My last tip came to me through serendipity. We had begun researching methods to create a batch trace solution on the wastewater network. We wanted to calculate the total upstream distance away from the treatment plant on every pipe. ESRI told us we should be able to use Functions to do this, so I started experimenting. I discovered it was easy to calculate the total distance traced, just like this:

traceConfiguration=
{
     "functions":
          [{ "functionType": "add",
             "networkAttributeName": "shape Length",
             "conditions": []
          }]
}

So, I added that to our Trace Widget as a finishing touch:

Then ESRI told us they were working on a new batch trace tool for their Utility Data Management Support toolbox. We coordinated with them on the development of this tool and got our requirements rolled in to the next update. They wrote their own blog post about it. You can go there to continue the story.

Utility Data Management Support tools - February 2022 Update

Here’s the result after running the tool in a small subnetwork:

In conclusion, it is complicated to switch to the Utility Network, and I hope this will make it a little easier for you. The effort is well worth it, as our tracing is faster, more flexible and more accurate now.