What's new in Utility Network JavaScript API 4.21

By Hussein Nasser

In the JavaScript API 4.20 release, the official utility network for JavaScript API was shipped with the ability to execute trace analytics using named trace configuration. In this release we extend this feature with the following capabilities:

Create your own Trace Configuration – Create or override existing utility network trace configuration
Retrieve more utility network Metadata – Access subnetwork management meta data

In this blog we will explain and demonstrate the new capabilities with example source code.

Edit 10-22-2021: You can download the demo source code for 4.21 from github here

Create your own Trace Configuration

While you could run a utility network tracing analytic in the 4.20 release, you were restricted by the named trace configurations persisted on the backend. For example, if you have a utility network trace called Downstream Trace that only returns elements, and you wanted to draw the aggregated geometries instead, you had to author and persist a new named trace configuration Downstream Trace - aggregated geometry which returns aggregated geometries of the result and re-share the webmap.

With 4.21, you can read the named trace configuration and override the result-type property to add aggregated geometries, create additional filters, and change various properties in trace. Do none of your shared named trace configuration do what you want in the client? No problem! You can also start from scratch and build your own trace configuration and execute a trace that way instead.

Let us show some examples.

Our Subnetwork is being edited!

When a feature is edited in the utility network, a dirty area is generated as a result. This is done so the validation process can pick up those dirty areas, which represent what has changed, and rebuild the network topology. The presence of dirty areas indicates inconsistencies in the network topology and could lead to incorrect trace analytic results. If a utility network trace detects a dirty area, an error is thrown by default when the validateConsistency option is enabled.

In our example below, trying to run a subnetwork trace on subnetwork RMT003 is returning an error : “One or more dirty areas were discovered”. This indicates that the subnetwork is being edited.

However, what if I still want to trace the subnetwork and am fine with getting inconsistent results as a side effect of the edits. I can overwrite the named trace configuration by setting the validateConsistency option to false and then re run the trace. As you can see the trace is now successful. Following is the source code to achieve this.



tc = utilityNetwork.sharedNamedTraceConfigurations.find(tc => tc.title === "Subnetwork_RMT003_NoStartingPoint_AllResultTypes")
//create a new UNTraceConfiguration and pass in the named one
mytc = new UNTraceConfiguration(tc.traceConfiguration.toJSON());
//disable validate consistency so we skip dirty area checking
mytc.validateConsistency = false;
//prepare the trace parameter, note that we are tracing in a version.
traceParameters = new TraceParameters ({ 
                                        "traceLocations": [],
                                         "gdbVersion": "unadmin.421-demo",
                                        "traceConfiguration": mytc,
                                        "resultTypes": mytc.resultTypes,
                                        "traceType": "subnetwork"
								}); 
results = await Tracer.trace(utilityNetwork.networkServiceUrl, traceParameters);
//the call will fail since we have dirty areas
console.log(results);

My Subnetwork Trace is not returning Containers

The named trace configuration for this particular trace has been configured with includeContainers set as false;however, I want to override that option and return all containers in my trace. We can easily do this by flipping the Boolean property includeContainers. Compare the results before and after making this change.


tc = utilityNetwork.sharedNamedTraceConfigurations.find(tc => tc.title === "Subnetwork_RMT003_NoStartingPoint_AllResultTypes")
//create a new UNTraceConfiguration and pass in the named one
mytc = new UNTraceConfiguration(tc.traceConfiguration.toJSON());
//disable validate consistency so we skip dirty area checking
mytc.includeContainers = true
mytc.validateConsistency = false
//prepare the trace parameter, note that we are tracing in a version.
traceParameters = new TraceParameters ({ 
                                        "traceLocations": [],
                                         "gdbVersion": "unadmin.421-demo",
                                        "traceConfiguration": mytc,
                                        "resultTypes": mytc.resultTypes,
                                        "traceType": "subnetwork"
								}); 
results = await Tracer.trace(utilityNetwork.networkServiceUrl, traceParameters);
//the call will fail since we have dirty areas
console.log(results);

But I only want the transformers back?

Most of the time, named trace configurations are configured to return everything they find which could be expensive for trace operations with large result-set. You can override the trace configuration to return only network features you are interested in. For example, if you want your subnetwork trace to only return overhead single phase transformers. This could be done by providing output filters, here is the code:



tc = utilityNetwork.sharedNamedTraceConfigurations.find(tc => tc.title === "Subnetwork_RMT003_NoStartingPoint_AllResultTypes")
//create a new UNTraceConfiguration and pass in the named one
mytc = new UNTraceConfiguration(tc.traceConfiguration.toJSON());
//disable validate consistency so we skip dirty area checking
mytc.includeContainers = true
mytc.validateConsistency = false
   // -- Return  Electric Device - Medium Voltage Transformer - Overhead Single Phase only

 mytc.outputFilters.push ({    
                                        "networkSourceId": 9,
                                        "assetGroupCode": 38,
                                        "assetTypeCode": 785
                                    });                
//prepare the trace parameter, note that we are tracing in a version.
traceParameters = new TraceParameters ({ 
                                        "traceLocations": [],
                                         "gdbVersion": "unadmin.421-demo",
                                        "traceConfiguration": mytc,
                                        "resultTypes": mytc.resultTypes,
                                        "traceType": "subnetwork"
								}); 
results = await Tracer.trace(utilityNetwork.networkServiceUrl, traceParameters);
//the call will fail since we have dirty areas
console.log(results);

Domain Networks and Tiers

Now that you can create your own name trace configuration, you might need more metadata to build out the named trace configuration. DoHere are few more things brewing in our incubator for the upcoming releases.main networks and tiers can now be retrieved from the utility network class to enable tracing on different domain networks, and tiers. Here is an example demonstrating how you can obtain the domain networks and tiers in a given domain network:


//get all domain networks
utilityNetwork.domainNetworkNames
//get all tiers in the "Electric" domain networks
utilityNetwork.getTierNames("Electric")

What’s Next?

Here are few more things brewing in our incubator for the upcoming releases.

Query Network Topology Moments

Additional functionality to read the state of the network topology, such as when it was last validated, when the last schema change was applied and more.

Rule-based Editing, Validate, Subnetwork Management

The ability to run utility network functions such as validate network topology and update subnetwork to maintain network consistency while also exposing network rules for use to derive editing snapping.