Export Subnetwork (Utility Network)

Summary

Exports subnetworks from a utility network into a .json file. This tool also allows you to delete a row in the Subnetworks table as long as the Is deleted attribute is set to true. This indicates that the subnetwork controller has been removed from the subnetwork.

Note:

Starting with ArcGIS Enterprise 10.9.1, the export subnetwork operation processes asynchronously using the UtilityNetworkTools geoprocessing service when working with a utility network in an enterprise geodatabase. The UtilityNetworkTools service is preconfigured in the System folder for feature services that include a utility network. It has a longer time-out setting and is reserved for utility network geoprocessing tasks.

Learn more about exporting subnetworks

Usage

  • The subnetworks must be clean before they can be exported; run the Update Subnetwork tool first.

  • The parameters in the Trace Parameters category can only be used in Python.

  • The following requirement must be met when working with an enterprise geodatabase:
    • The Input Utility Network parameter value must be from a utility network service.
  • When the Set export acknowledged parameter is checked, the following must be true:

    • The network topology must be enabled.

    • Enterprise geodatabases have the following additional requirements:
      • This tool must be connected to the default version to run.
        • All other sessions connected to the default version are blocked from running validate or enable operations during the enable operation.
      • The connected ArcGIS Enterprise portal account must be the portal utility network owner.

  • At ArcGIS Pro 2.3, the following parameters are added: Include Geometry, Result Types, Result Network Attributes, and Result Fields. When these parameters are used, the output JSON file format will vary. These parameters require ArcGIS Enterprise 10.7 or later when used with an enterprise geodatabase. Review the output JSON response syntax.

Parameters

LabelExplanationData Type
Input Utility Network

The utility network that contains the subnetwork to export.

Utility Network; Utility Network Layer
Domain Network

The domain network that contains the subnetwork.

String
Tier

The tier that contains the subnetwork.

String
Subnetwork Name

The name of the subnetwork that will be exported from the tier. Select a specific source to export the corresponding subnetwork information. When the subnetworks table contains 10,000 or more records for a tier, the parameter's choice list is not populated and an empty field is provided for the subnetwork name.

String
Set export acknowledged

Specifies whether the LASTACKEXPORTSUBNETWORK attribute for the corresponding controller in the Subnetworks table and feature in the SubnetLine feature class will be updated.

  • Checked—The LASTACKEXPORTSUBNETWORK attribute for the corresponding controller in the Subnetworks table will be updated. If the controller has been marked for deletion (Is deleted = True), it will be deleted from the Subnetworks table. This option requires that the input utility network reference the default version.
  • Unchecked—The LASTACKEXPORTSUBNETWORK attribute for the corresponding controller in the Subnetworks table will not be updated. This is the default.

Boolean
Output JSON

The name and location of the .json file that will be generated.

File
Condition Barriers
(Optional)
Note:

This parameter is only available for Python.

Value Table
Function Barriers
(Optional)
Note:

This parameter is only available for Python.

Value Table
Include Barrier Features
(Optional)
Note:

This parameter is only available for Python.

Boolean
Apply Traversability To
(Optional)

Specifies the type of traversability that will be applied. Traversability scope determines whether traversability is applied to junctions, edges, or both. For example, if a condition barrier is defined to stop the trace if DEVICESTATUS is set to Open and the traversability scope is set to edges only, the trace will not stop even if the trace encounters an open device, because DEVICESTATUS is only applicable to junctions. In other words, this parameter indicates to the trace whether to ignore junctions, edges, or both.

  • Both junctions and edgesTraversability will be applied to both junctions and edges.
  • Junctions onlyTraversability will be applied to junctions only.
  • Edges onlyTraversability will be applied to edges only.
Note:

This parameter is only available for Python.

String
Propagators
(Optional)
Note:

This parameter is only available for Python.

Value Table
Include geometry
(Optional)

Specifies whether geometry will be included in the results.

  • Checked—Geometry will be included in the results.
  • Unchecked—Geometry will not be included in the results. This is the default.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

Boolean
Result Types
(Optional)

Specifies the types of results that will be returned.

  • ConnectivityFeatures that are connected through geometric coincidence or connectivity associations will be returned. This is the default.
  • FeaturesFeature-level information will be returned.
  • Containment and attachment associationsFeatures that are associated through containment and structural attachment associations will be returned.
Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

The containment and attachment associations option requires ArcGIS Enterprise 10.8.1 or later.

String
Result Network Attributes
(Optional)

The network attributes that will be included in the results.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

String
Result Fields
(Optional)

Fields from a feature class that will be returned as results. The values of the field will be returned in the results for the features in the subnetwork.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

Value Table
Include domain descriptions
(Optional)

Specifies whether domain descriptions will be included in the output .json file to communicate domain mapping for controllers, featureElements, connectivity, and associations.

  • Checked—Domain descriptions will be included in the results.
  • Unchecked—Domain descriptions will not be included in the results. This is the default.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.9.1 or later.

Boolean

Derived Output

LabelExplanationData Type
Updated Utility Network

The updated utility network.

Utility Network

arcpy.un.ExportSubnetwork(in_utility_network, domain_network, tier, subnetwork_name, export_acknowledged, out_json_file, {condition_barriers}, {function_barriers}, {include_barriers}, {traversability_scope}, {propagators}, {include_geometry}, {result_types}, {result_network_attributes}, {result_fields}, {include_domain_descriptions})
NameExplanationData Type
in_utility_network

The utility network that contains the subnetwork to export.

Utility Network; Utility Network Layer
domain_network

The domain network that contains the subnetwork.

String
tier

The tier that contains the subnetwork.

String
subnetwork_name

The name of the subnetwork that will be exported from the tier. Select a specific source to export the corresponding subnetwork information.

String
export_acknowledged

Specifies whether the LASTACKEXPORTSUBNETWORK attribute for the corresponding controller in the Subnetworks table and feature in the SubnetLine feature class will be updated.

  • ACKNOWLEDGEThe LASTACKEXPORTSUBNETWORK attribute for the corresponding controller in the Subnetworks table will be updated. If the source has been marked for deletion (Is deleted = True), it will be deleted from the Subnetworks table. This option requires that the input utility network reference the default version.
  • NO_ACKNOWLEDGEThe LASTACKEXPORTSUBNETWORK attribute for the corresponding controller in the Subnetworks table will not be updated. This is the default.
Boolean
out_json_file

The name and location of the .json file that will be generated.

File
condition_barriers
[[Name, Operator, Type, Value, Combine Using],...]
(Optional)

Sets a traversability barrier condition on features based on a comparison to a network attribute or check for a category string. A condition barrier uses a network attribute, an operator and a type, and an attribute value. For example, stop a trace when a feature has the Device Status attribute equal to the specific value of Open. When a feature meets this condition, the trace stops. If you're using more than one attribute, you can use the Combine using parameter to define an And or an Or condition.

Condition barrier components are as follows:

  • Name—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of different operators.
  • Type—Choose a specific value or network attribute from the value that is specified in the name parameter.
  • Value—Set a specific value of the input attribute type that will cause termination based on the operator value.
  • Combine Using—Set this value if you have multiple attributes to add. You can combine them using an And or an Or condition.

The condition barrier operator values are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).

The condition barrier type options are as follows:

  • SPECIFIC_VALUEFilter by a specific value.
  • NETWORK_ATTRIBUTEFilter by a network attribute.

The Combine Using values are as follows:

  • ANDCombine the condition barriers.
  • ORUse if either condition barrier is met.

Learn more about using multiple conditional expressions

Value Table
function_barriers
[[Function, Attribute, Operator, Value, Use Local Values],...]
(Optional)

Sets a traversability barrier on features based on a function. Function barriers can be used to do such things as restrict how far the trace travels from the starting point, or set a maximum value to stop a trace. For example, the length of each line traveled is added to the total distance traveled so far. When the total length traveled reaches the value specified, the trace stops.

Function barrier components are as follows:

  • Function—Choose from a number of different calculation functions.
  • Attribute—Filter by any network attribute defined in the system.
  • Operator—Choose from a number of different operators.
  • Value—Set a specific value of the input attribute type that, if discovered, will cause the termination.
  • Use Local Values—Calculate values in each direction as opposed to an overall global value. For example, use for a function barrier that is calculating the sum of Shape length where the trace terminates if the value is greater than or equal to 4. In the global case, after you have traversed two edges with a value of 2, you have already reached a shape length sum of 4, so the trace stops. If local values are used, the local values along each path change, so the trace goes farther.

  • TRUEUse local values.
  • FALSEUse global values. This is the default.

Possible values for the function barrier function options are as follows:

  • AVERAGEThe average of the input values.
  • COUNTThe number of features.
  • MAXThe maximum of the input values.
  • MINThe minimum of the input values.
  • ADDAdd the values.
  • SUBTRACTSubtract the values. Subnetwork controllers and loops trace types do not support the subtract function.

For example, the starting point feature has a value of 20. The next feature has a value of 30. If you use the minimum function, the result is 20, maximum is 30, add is 50, average is 25, count is 2, and subtract is -10.

The function barrier operator value options are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES_NOT_INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INCLUDE_ANYA bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).
Value Table
include_barriers
(Optional)

Specifies whether the traversability barrier features will be included in the trace results. Traversability barriers are optional even if they have been preset in the subnetwork definition.

  • INCLUDE_BARRIERSTraversability barriers will be included in the trace results. This is the default.
  • EXCLUDE_BARRIERSTraversability barriers will not be included in the trace results.
Boolean
traversability_scope
(Optional)

Specifies the type of traversability that will be applied. Traversability scope determines whether traversability is applied to junctions, edges, or both. For example, if a condition barrier is defined to stop the trace if DEVICESTATUS is set to Open and the traversability scope is set to edges only, the trace will not stop even if the trace encounters an open device, because DEVICESTATUS is only applicable to junctions. In other words, this parameter indicates to the trace whether to ignore junctions, edges, or both.

  • BOTH_JUNCTIONS_AND_EDGESTraversability will be applied to both junctions and edges.
  • JUNCTIONS_ONLYTraversability will be applied to junctions only.
  • EDGES_ONLYTraversability will be applied to edges only.
String
propagators
[[Attribute, Substitution Attribute, Function, Operator, Value],...]
(Optional)

Specifies the network attributes to propagate as well as how that propagation will occur during a trace. Propagated class attributes denote the key values on subnetwork controllers that are disseminated to the rest of the features in the subnetwork. For example, in an electric distribution model, you can propagate the phase value.

Propagators components are as follows:

  • Attribute—Filter by any network attribute defined in the system.
  • Substitution Attribute—Use a substituted value instead of bitset network attribute values. Substitutions are encoded based on the number of bits in the network attribute being propagated. A substitution is a mapping of each bit in phase to another bit. For example, for Phase AC, one substitution could map bit A to B, and bit C to null. In this example, the substitution for 1010 (Phase AC) is 0000-0010-0000-0000 (512). The substitution captures the mapping so you know that Phase A was mapped to B and Phase C was mapped to null, and not the other way around (that is, Phase A was not mapped to null and Phase C was not mapped to B).
  • Function—Choose from a number of calculation functions.
  • Operator—Choose from a number of operators.
  • Value—Provide a specific value for the input attribute type that would cause termination based on the operator value.

Possible values for the propagators function are as follows:

  • PROPAGATED_BITWISE_ANDCompare the values from one feature to the next.
  • PROPAGATED_MINGet the minimum value.
  • PROPAGATED_MAXGet the maximum value.

The propagator operator values are as follows:

  • IS_EQUAL_TOThe attribute is equal to the value.
  • DOES_NOT_EQUALThe attribute is not equal to the value.
  • IS_GREATER_THANThe attribute is greater than the value.
  • IS_GREATER_THAN_OR_EQUAL_TOThe attribute is greater than or equal to the value.
  • IS_LESS_THANThe attribute is less than the value.
  • IS_LESS_THAN_OR_EQUAL_TOThe attribute is less than or equal to the value.
  • INCLUDES_THE_VALUESA bitwise AND operation in which all bits in the value are present in the attribute (bitwise AND == value).
  • DOES NOT INCLUDE_THE_VALUESA bitwise AND operation in which not all of the bits in the value are present in the attribute (bitwise AND != value).
  • INCLUDES_ANYA bitwise AND operation in which at least one bit in the value is present in the attribute (bitwise AND == True).
  • DOES_NOT_INLCUDE_ANYA bitwise AND operation in which none of the bits in the value are present in the attribute (bitwise AND == False).
Value Table
include_geometry
(Optional)

Specifies whether geometry will be included in the results.

  • INCLUDE_GEOMETRYGeometry will be included in the results.
  • EXCLUDE_GEOMETRYGeometry will not be included in the results. This is the default.
Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

Boolean
result_types
[result_types,...]
(Optional)

Specifies the types of results that will be returned.

  • CONNECTIVITYFeatures that are connected through geometric coincidence or connectivity associations will be returned. This is the default.
  • FEATURESFeature-level information will be returned.
  • CONTAINMENT_AND_ATTACHMENT_ASSOCIATIONSFeatures that are associated through containment and structural attachment associations will be returned.
Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

The containment and attachment associations option requires ArcGIS Enterprise 10.8.1 or later.

String
result_network_attributes
[result_network_attributes,...]
(Optional)

The network attributes that will be included in the results.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

String
result_fields
[[Feature Class, Field Name],...]
(Optional)

Fields from a feature class that will be returned as results. The values of the field will be returned in the results for the features in the subnetwork.

Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.7 or later.

Value Table
include_domain_descriptions
(Optional)

Specifies whether domain descriptions will be included in the output .json to communicate domain mapping for controllers, featureElements, connectivity, and associations.

  • INCLUDE_DOMAIN_DESCRIPTIONSDomain descriptions will be included in the results.
  • EXCLUDE_DOMAIN_DESCRIPTIONSDomain descriptions will not be included in the results. This is the default.
Note:

For enterprise geodatabases, this parameter requires ArcGIS Enterprise 10.9.1 or later.

Boolean

Derived Output

NameExplanationData Type
out_utility_network

The updated utility network.

Utility Network

Code sample

ExportSubnetwork example (Python window)

Export the corresponding subnetwork information for a source named RMT002 to a .json file with domain descriptions included.

import arcpy
arcpy.un.ExportSubnetwork("Utility Network", "ElectricDistribution", 
                          "Medium Voltage", "RMT002", "ACKNOWLEDGE", 
                          "C:\\Temp\\RMT002clean.json", None, None, 
                          "INCLUDE_BARRIERS", "BOTH_JUNCTIONS_AND_EDGES", 
                          None, "EXCLUDE_GEOMETRY", None, None, None, 
                          "INCLUDE_DOMAIN_DESCRIPTIONS")

Environments

This tool does not use any geoprocessing environments.

Licensing information

  • Basic: No
  • Standard: Yes
  • Advanced: Yes

Related topics