Tracing returns selected features based on connectivity or traversability from the one or more starting points. For a full overview of tracing see this article.
There are a number of Trace Widgets you can set up for a UNE application. These can be configured and added to any Custom Panel.
Trace Command – Allow a user to create start points, barriers and run pre-configured traces.
Trace Results – Display the results of a trace in a table format broken down by asset group.
The default UNE application has a custom panel called Trace, where the Trace Command widget has been added.
Trace Command
When added to a UNE application, the trace command widget appears as shown below and allows users to run traces against your Utility Network’s topology.
The types of traces available are configured within the application builder.
Trace Command – Configuring a new trace
Trace configurations can be added and removed in the Trace Types section of the Trace Command Panel.
Clicking to add a new trace provides options for setting the name of a trace as well as its associated configuration. These settings are broadly the same as documented for the trace geoprocessing task.
To use a named trace configuration saved to your utility network service, pick ‘Named’ from the list of trace types, and then pick the named trace you require.
Trace parameters
When adding trace configurations, it is possible to use parameters. These are extra properties that the user will be requested to enter, before they can execute a trace.
Trace parameters can be used for many of the values that need to be provided as part of a trace configuration. When parameters are added, new options will appear when configuring the different trace specific settings. In addition the trace parameters can be used when processing or displaying the results of a trace.
Some examples of using trace parameters are as follows:
Configuring a trace that stops when it reaches a certain user entered distance. This can be achieved by adding a distance parameter and then using it as the value part of a function barrier.
Tracing a pipe network up until a certain threshold pressure value – a function could be set which terminates when the sum of asset field values reaches a user input threshold.
Trace result tasks
In UNE, trace configurations have trace result tasks. These tasks determine what the application will do with the results of a particular trace operation.
By default, when a new trace configuration is added to UNE, the builder will add a select result task. This will cause the results of the trace to be selected.
There may be situations or workflows where this is not the desired behaviour of a trace. For example, a trace may be executed to get a report. Or a trace may be executed to create work items in another system. To cater for these scenarios, the application can use the execution task framework to perform any operation with the results of a trace.
Please refer to task execution for more detail on how the type of actions that can be taken with a trace result.
If the trace execution will result in a new set of selected features on the map, please set the ‘Result tasks change map selection’ option. When this is set, the application will reset the selection every time the trace is executed, to make it clearer that the selected features are in response to running the trace.
$traceresult global variable
Trace result tasks have access to the results of the trace. This is available as a global in any Arcade script execution as $traceresult.
This global variable is accessible in most script locations, and allows the results of last run trace to be worked with.
The properties available on the $traceresult are dependent on the chosen result types.
/**Example showing $traceresult Consoled out.
*
* Note:
* - $traceresult.mapelements is a Featuresetcollection containing
* the features from layers that are returned as elements in the
* trace results.
* - $traceresult.aggregatedGeometry contains the aggregated geometry
* information returned from the trace result in the coordinate
* system of the map.
*/
{
"type": "traceresult",
"trace": {
"id": "738ae65d-9f15-2c4f-55a0-06f2a9dae63b",
"name": "Connected assets",
"runid": 1,
"type": "custom",
"namedConfigurationId": "",
"traceConfiguration": {
"traceType": "connected",
"traceLocations": [
{
"traceLocationType": "startingpoint",
"globalId": "{D2252B86-8CE2-4C7E-B3CE-F58A8BC659BD}",
"percentAlong": 0.6115834092856117
},
{
"traceLocationType": "barrier",
"globalId": "{D2252B86-8CE2-4C7E-B3CE-F58A8BC659BD}",
"percentAlong": 0.5853789273082104
},
],
"traceConfiguration": {
}
},
"isrunning": false,
"success": true,
"error": null,
"traceResults": {
"elements": [
{
"networkSourceId": 9,
"globalId": "{1978545D-B43D-4FDF-9296-E574D063D2D7}",
"objectId": 5066,
"terminalId": 1,
"assetGroupCode": 22,
"assetTypeCode": 422
},
],
"diagramName": "<placeholder>",
"globalFunctionResults": [],
"kFeaturesForKNNFound": false,
"startingPointsIgnored": false,
"warnings": [],
"aggregatedGeometry": {
"point": {
"hasM": true,
"hasZ": true,
"points": [
[
-9814221.72976257,
5129148.92185136,
0,
null
],
[
-9814212.982625445,
5129150.10117076,
0,
null
]
],
"spatialReference": {
"latestWkid": 3857,
"wkid": 102100
}
},
"line": {
"hasM": true,
"hasZ": true,
"paths": [
[
[
-9814183.215080498,
5129146.418597,
1.582299999994575,
null
],
[
-9814186.635347126,
5129146.8414585255,
0,
null
]
],
[
[
-9814186.635347126,
5129146.8414585255,
0,
null
],
[
-9814212.982625451,
5129150.101170742,
0,
null
]
],
],
"spatialReference": {
"latestWkid": 3857,
"wkid": 102100
}
}
}
},
"mapelements": ... /* Featuresetcollection contaning the element.
Equivelent of $map and $selection */
}
Advanced: Customising trace configuation
This is an advanced option, that allows for the trace request to be intercepted and adjusted before being sent.
With this option is possible to completely alter what the trace request is.
This option is provided as an Arcade script. It provides the full detail about the trace that is about to be executed, as well as the current parameter values the user has set.
An example of using this capability is as follows:
A parameter called ‘Ignore consistency’ is added to the configuration.
When the trace is executed, the arcade script checks this parameter value and uses it to adust the ‘validateConsistency’ property value of the trace request.
When executing, the script will be provided with the trace configuration that is being sent. This will be in the global $traceconfig. The parameters the user has set will be available as $traceparameters. The trace parameters will already have been substituted into the configuration.
/**Example showing $traceconfig Consoled out.
*
* Note: The customisation script can alter the configuration object and
* then pass the result out to then be run by utility network trace
* service
*/
{
"traceType": "connected",
"traceLocations": [
{
"traceLocationType": "startingpoint",
"globalId": "{9A7E6204-F78F-4F7C-89D8-25F3B7B9CB82}",
"percentAlong": 0.7208687935518765
},
],
"traceConfiguration": {
...
},
"resultType": "elements"
}
Trace results widget
A trace results widget can be added to a custom panel to display the results of a trace in a table format.
With the trace result widget, actions can be set. These are offered to the user as optional commands they can run on individual result features.
The Action result can be used to initiate further workflows / business processes, for example:
The results of the trace are displayed in the results widget. An individual row in the results can be clicked on, and an operation to ‘Send inspection team’ seen and initiated.
Trace results in other widgets
When a trace has been executed, the results of the trace is made available to all Charts, Commands and Feedback components. This means it is possible add widgets to custom panels and the map showing different aspects of the trace result.
The trace is made available throughout the UNE application as $traceresult. Any component that uses $traceresult will automatically update when this global changes.
This capability can be used to show an Infographic or other chart with values calculated by a trace operation.
