ArcGIS REST API

Automating utility network functions using command line

We receive the question a lot at conferences, ‘Can the utility network run outside of ArcGIS Pro?’ The answer is yes!

ArcGIS Pro is used to initially create the utility network and it is the primary smart client for the utility network however, as the case with other clients, ArcGIS Pro is consuming the REST end points of the utility network server. In one of our previous blog post we had shown how to perform a subnetwork trace on the utility network from the web using JavaScript. In this post we will discuss how can we perform mission critical functions such as validate network topology, update subnetworks and update the Is connected attribute from the command line in Windows using a tool built with C#. This can be scheduled to run every day or every hour depending on the business needs to always ensure a consistent network.

Note: The code here has been authored from scratch in C# to hit the Utility Network REST API directly. The tool can run on any machine and doesn’t require ArcGIS Pro to be on the same machine.

Source code and tool download: https://github.com/hussein-nasser/uncmd

Validate Network Topology
The utility network uses dirty area management. This means any edit a user performs is followed by the creation of a dirty area that envelopes the edit. Dirty areas are then validated using the Validate Network Topology tool. This process stitches the connectivity and syncs the network index at the backend with recent edits to features. This ensures the index is up to date when used with analytics (tracing and network diagrams).
As users create more edits, validate topology needs to be run frequently. The command line utility can be used to automate validate as follows. By default, the option /v will validate the full extent of the utility network on the Default version.

Validate Network Topology

Update Subnetworks
The utility network offers subnetwork management (circuit management in electric utilities or pressure zones in water and gas) out of the box. A user can create subnetworks by assigning certain devices as “controllers” of that subnetwork. The Update subnetwork tool is executed to update the subnetwork name fields on all the devices, populate propagated attributes such as phases, manage the IsConnected attribute and generate SubnetLine features which identifies the linear extent of the subnetwork.

The command line utility can be used to update subnetworks for all tiers, for all domain networks in the input utility network service by using the /u parameter. This makes it very convenient for users to have clean subnetworks that are always up to date and ready to be exported as edits are made to the network. The result can be either printed on the screen or logged to a file. The call can be optionally configured to stack both validate full extent and update subnetwork in the same execution. This way the Validate Network Topology operation will remove any dirty areas from edits and mark necessary subnetworks as dirty, then the Update Subnetwork process will pick up and update the dirty subnetworks.

Update Subnetwork

Update is Connected
Certain classes in a utility network like devices, junctions and line have a field called IsConnected. In 2.1/10.6 the field is a Boolean of True and False. The field is used to identify isolated/island features that are not connected to any subnetwork. The value of True on the IsConnected field on a given feature means that this feature has some sort of physical network connectivity to a controller. That is if you run a connected trace from that feature you will discover a controller device. A value of false means that the feature is not connected to the subnetwork controller for the subnetwork and is isolated.

The Update Is Connected tool updates this field for the entire utility network. The command line utility can be used with the parameter /c to run this tool. It is recommended to stack this call with validate as well to clear any dirty areas.

Note: In 2.2 a new code domain has been assigned to this field the values are now Unknown, True and False. With Unknown being the default value of that field.

Update Is Connected

Command line configuration examples
The following table provides information and examples to aid in using the command line utility:

Parameter Description Example
/url:PORTAL_URL The portal web adaptor url, no space should be after the colon /url:utilitynetwork.esri.com/portal
/user:USER_NAME The portal username, must be the owner of the service. /user:unadmin
/pass:USER_PASS The password for the user. /pass:unadminp
/s:SERVICE_NAME The feature service name that has the utility network.
Replace SERVICE_NAME to apply the methods on all services that have UN in them.
/s:AllStar_Oracle

/s:all (all services)

/v

Validates the full extent of the utility network.
/v /e:EXTENT Validates the given EXTENT, where EXTENT is a json string (no spaces). /v /e: {“xmin”:-117608483.4351523,”ymin”:
-91881060.91924113,”xmax”: 130731816.76848565,”ymax”:
59380583.64835839,”spatialReference”: { “wkid”:
3498,”latestWkid”: 3498,”xyTolerance”: 0.00328083333333333,”zTolerance”:
0.001,”mTolerance”: 0.001,”falseX”:
-117608900,”falseY”: -91881400,”xyUnits”:
3048.0060960121905,”falseZ”: -100000,”zUnits”:
10000,”falseM”: -100000,”mUnits”: 10000}}
/u Updates all subnetworks in all domain networks, in all tiers in the given un service.
If /s:all were given then it is applied on all services
/c Runs update is connected on the given service. If /s:all were given then it is applied on all services.
/l Option to enable
logging to a file. The logs will go to a folder called logs in the same
directory as uncmd.exe. The name of the file will be a timestamp.

About

Software Engineer, Author of several GIS books and Software Engineering Content Creator on YouTube and Anchor podcast

About Utility Network Team

The utility network team blogs about utility industry topics and the functionality available with the ArcGIS Utility Network Management extension. #UtilityNetwork #EsriElectric #EsriGas #SmartGrid

Next Article

Rocking Gradients in Pro Layouts

Read this article