Trace parameters specify how the trace analysis proceeds across the utility network. Essential trace parameters, described in this section, include:
Trace type
Use one of the supported traces (such as upstream, downstream, subnetwork, and so on) to create the parameters with starting locations. Refer to the Trace a utility network overview for a description of the supported trace types.
// Create a new utility trace parameters using the Utility trace type of 'Downstream'
// and a list of utility elements.
UtilityTraceParameters* traceParams = new UtilityTraceParameters(UtilityTraceType::Downstream,
startingLocations, this);
Trace locations
A trace location can be one of the following:
- Starting point
- Barrier
- Filter barrier
All of the traces except shortest path require at least one starting point. Barriers are optional. A filter barrier is only required for an isolation trace when no trace filter barrier condition was specified. The respective collections for these contain UtilityElement objects that can be created as explained in the Analyze your network topic.
Once you have a utility element, you can add it to the collection that fits its purpose.
// Get the QList of utility elements from the utility trace parameters
// for starting locations.
QList<UtilityElement*> startinglocationsUtilityElements = utilityTraceParameters->
startingLocations();
// Add the starting location utility element to the QList of utility elements.
startinglocationsUtilityElements.append(startinglocationUtilityElement);
// Get the QList of utility elements from the utility trace parameters for barriers.
QList<UtilityElement*> barrierUtilityElements = utilityTraceParameters->barriers();
// Add the barrier utility element to the QList of utility elements.
barrierUtilityElements.append(barrierUtilityElement);
// Get the QList of utility elements from the utility trace parameters for filter barriers.
QList<UtilityElement*> filterbarrierUtilityElements = utilityTraceParameters->filterBarriers();
// Add the filter barrier utility element to the QList of utility elements.
filterbarrierUtilityElements.append(filterbarrierUtilityElement);
Trace configuration
A trace configuration allows you to do things like:
- Stop the trace at protective devices if they are open. For example, the flow of electricity in a network will be stopped if a fuse is open.
- Control the types of features traced. For example, trace only pipes with a diameter greater than six inches.
- Filter the types of features returned as trace results. For example, only return elements identified by the trace that represent wooden poles.
- Define functions to run calculations on network attributes associated with traced features. For example, the sum of the length of all the wire traced. Several functions can be specified for a trace.
See the Trace configuration topic for more information.
Below is an example of trace configuration for isolation trace.
// Create a new utility trace configuration.
UtilityTraceConfiguration* utilityTraceConfiguration = new UtilityTraceConfiguration(this);
// Get the utility network definition from the utility network.
UtilityNetworkDefinition* utilityNetworkDefinition = utilityNetwork->definition();
// Get the utility domain network from the utility network definition for the "Water" type.
UtilityDomainNetwork* utilityDomainNetwork = utilityNetworkDefinition->domainNetwork("Water");
// Set the domain network on the utility trace configuration.
utilityTraceConfiguration->setDomainNetwork(utilityDomainNetwork);
// Get the utility tier from the utility domain network for the "Water Pressure" type.
UtilityTier* utilityTier = utilityDomainNetwork->tier("Water Pressure");
// Set the source tier on the utility trace configuration.
utilityTraceConfiguration->setSourceTier(utilityTier);
// Create a new utility trace filter.
UtilityTraceFilter* utilityTraceFilter = new UtilityTraceFilter(this);
// Create a utility category comparison with an "Isolating" type and a utility category
// comparision operator of 'Exists'.
UtilityCategoryComparison* utilityCategoryComparison = new UtilityCategoryComparison(
"Isolating", UtilityCategoryComparisonOperator::Exists, this);
// Set the utility category comparison on the utility trace filter.
utilityTraceFilter->setBarriers(utilityCategoryComparison);
// Set the utility trace configuration on the utility trace parameters.
utilityTraceParameters->setTraceConfiguration(utilityTraceConfiguration);
Trace results
You can add a variety of trace result types (UtilityTraceResultType) to the UtilityTraceParameters result types collection to define the results returned from a trace. At least one type of trace result is required, but you can request several.
- Element results—Provide information about the individual network features. This is the default result returned.
- Function results—Calculate values based on network attributes. Note that this type of result requires your trace configuration to include function inputs.
- Geometry results—Allow you to display the results on the map. This result type is supported by ArcGIS Enterprise 10.8.1 or later and for mobile geodatabase, you need ArcGIS Maps SDKs for Native Apps version 200.1 or later.
See the Work with trace results topic for more information about trace results.
The following example shows creating a trace function, including it with the trace configuration, and requesting its result in the output.
// Get the utility network definition from the utility network.
UtilityNetworkDefinition* utilityNetworkDefinition = utilityNetwork->definition();
// Get the utility network attribute from the utility network definition for the
// "Shape length" type.
UtilityNetworkAttribute* utilityNetworkAttribute = utilityNetworkDefinition->
networkAttribute("Shape length");
// Create a utility trace function with a utility trace function type of 'Add'
// and the utility network attribute.
UtilityTraceFunction* utilityTraceFunction = new UtilityTraceFunction(
UtilityTraceFunctionType::Add, utilityNetworkAttribute, this);
// Get the utility trace configuration from the utility trace parameters.
UtilityTraceConfiguration* utilityTraceConfiguration = utilityTraceParameters->traceConfiguration();
// Get the utility trace functional list model from the utility trace configuration.
UtilityTraceFunctionListModel* utilityTraceFunctionListModel = utilityTraceConfiguration->functions();
// Add the utility trace function to the utility trace function list model.
utilityTraceFunctionListModel->append(utilityTraceFunction);
// Get the QList of utility trace result types from the utility trace parameters.
QList<UtilityTraceResultType> utilityTraceResultTypes = utilityTraceParameters->resultTypes();
// Add the utility trace result type of 'FunctionOutputs' to the utility trace result types.
utilityTraceResultTypes.append(UtilityTraceResultType::FunctionOutputs);