Add Network Attribute (Utility Network)

Summary

Adds a network attribute to a utility network.

A network attribute is a value derived from attributes on corresponding features in the network and is stored in the network topology. Network attributes are used by tracing analysis to control how the network can be traversed. While a network attribute can be associated with only one attribute on a feature class, there is no limit to the number of network attributes a single utility network can have. Network attributes are used as weights to control traversability and to model the cost of paths in the network.

Usage

• A network attribute can be associated with only one attribute on a feature class; however, it can be associated with multiple feature classes.

• When working with an enterprise geodatabase, the connected ArcGIS Enterprise portal account must be the portal utility network owner.

• The network topology must be disabled.

• When working with an enterprise geodatabase, this tool must be connected to the default version to run.

• When working with an enterprise geodatabase, the Input Utility Network parameter value must be from a database connection established as the database utility network owner.

License:

The active portal account must be assigned a license with the ArcGIS Advanced Editing user type extension to use this tool in an enterprise deployment.

• This tool can be used with the Set Network Attribute tool, which assigns the network attribute to a feature class field in the utility network.

• The following table lists the network attribute types and their applicable parameters:

  Attribute type	In line	Apportionable	Nullable	Substitution
  Short
  Long				(Out of line only)
  Double
  Date

Parameters

Dialog

Label	Explanation	Data Type
Input Utility Network	The input utility network where the network attribute will be added.	Utility Network; Utility Network Layer
Attribute Name	The name of the network attribute to add to the utility network.	String
Attribute Type	Specifies the data type of the network attribute. Short (16-bit integer)—The field type will be short. Long (32-bit integer)—The field type will be long. Double (64-bit floating point)—The field type will be double. Date—The field type will be date.	String
In Line (Optional)	Specifies whether the network attribute will be persisted in line. In-line network attributes are slightly more efficient, but the number of bits for user-defined in-line network attributes is limited to 25 per utility network. Store the most frequently used network attributes (for example, phase for electric networks, pressure for gas and water networks) in line if possible. The size of the bits is determined by the domain parameter. In-line attributes are only supported for integer network attributes (short, long). Checked—The attribute will be added internally to the topology, making retrieval more efficient. Unchecked—The attribute will be stored in an external table, and retrieval will require a call to the external weights table. This is the default.	Boolean
Apportionable (Optional)	Specifies whether the network attribute will be apportioned across multiple edges belonging to the same feature. Apportioned behavior is only supported with double network attributes. Network attributes with the apportionable property can be assigned to fields in line or junction feature classes, but only line features will have apportioned behavior. To illustrate, consider the shape_length network attribute and a line feature that consists of five edge elements of 20 feet each, where the total length of that line feature is 100 feet. This attribute will be apportioned across all edges. For example, using a function in a connected trace to count the shape length attribute for this line will return a count of 5 because it accounts for each individual edge element and not the entire line. The distribution of the value depends on the percentage along each edge element with respect to the from point of the original feature. Checked—The network attribute will be apportioned. Unchecked—The network attribute will not be apportioned. This is the default.	Boolean
Domain Name (Optional)	The domain with which the network attribute will be associated. This parameter is required when In Line is checked. This domain is used to determine the number of bits to allocate for the in-line attribute and must be a coded value type. For example, the LifeCycleStatusDomain (0, Unknown | 1, In-Service | 2, Proposed | 3, Abandoned) domain has four entries, which means 2 bits are required to store the in-line attribute. The coded value domain must have sequential codes starting from 0.	String
Is Overridable (Optional)	Note: This parameter is not used in the current release, and any value provided will be ignored. The functionality of this parameter is under development and will be applicable in a future release. Specifies whether the current value stored in the topology will be overridden using an external override table. This parameter can be used, for example, to input live data from external systems, such as present position in the case of electric or pressure value in the case of gas. An example is a SCADA system pushing the updated switching positions of Device A to the override table of the DeviceStatus network attribute, which the topology engine then uses to override its current value of device status for Device A with the override value. Checked—The current value stored in the topology will be overridden. Unchecked—The current value stored in the topology will not be overridden. This is the default.	Boolean
Nullable (Optional)	Specifies whether the network attribute will support null values. Checked—The network attribute will support null values. This is the default. Unchecked—The network attribute will not support null values.	Boolean
Substitution (Optional)	Specifies whether the network attribute will be used as a substitution. Substitution network attributes allow a substituted value to be used instead of bitset network attribute values during a propagation in a trace operation. Substitution is only supported with long integer network attributes. Checked—The network attribute will be used as a substitution. Unchecked—The network attribute will not be used as a substitution. This is the default.	Boolean
Network Attribute to Substitute (Optional)	The network attribute to be used as a substitution. Substitutions are encoded based on the number of bits in the network attribute being propagated. The network attribute must be in line and an integer field type less than or equal to 8 bits.	String

Derived Output

Label	Explanation	Data Type
Updated Utility Network	The updated utility network.	Utility Network

Python

arcpy.un.AddNetworkAttribute(in_utility_network, attribute_name, attribute_type, {is_inline}, {is_apportionable}, {domain}, {is_overridable}, {is_nullable}, {is_substitution}, {network_attribute_to_substitute})

Name	Explanation	Data Type
in_utility_network	The input utility network where the network attribute will be added.	Utility Network; Utility Network Layer
attribute_name	The name of the network attribute to add to the utility network.	String
attribute_type	Specifies the data type of the network attribute. SHORT—The field type will be short. LONG—The field type will be long. DOUBLE—The field type will be double. DATE—The field type will be date.	String
is_inline (Optional)	Specifies whether the network attribute will be persisted in line. In-line network attributes are slightly more efficient, but the number of bits for user-defined in-line network attributes is limited to 25 per utility network. Store the most frequently used network attributes (for example, phase for electric networks, pressure for gas and water networks) in line if possible. The size of the bits is determined by the domain parameter. In-line attributes are only supported for integer network attributes (short, long). INLINE—The attribute will be added internally to the topology, making retrieval more efficient. NOT_INLINE—The attribute will be stored in an external table, and retrieval will require a call to the external weights table. This is the default.	Boolean
is_apportionable (Optional)	Specifies whether the network attribute will be apportioned across multiple edges belonging to the same feature. Apportioned behavior is only supported with double network attributes. Network attributes with the apportionable property can be assigned to fields in line or junction feature classes, but only line features will have apportioned behavior. To illustrate, consider the shape_length network attribute and a line feature that consists of five edge elements of 20 feet each, where the total length of that line feature is 100 feet. This attribute will be apportioned across all edges. For example, using a function in a connected trace to count the shape_length attribute for this line will return a count of 5 because it accounts for each individual edge element and not the entire line. The distribution of the value depends on the percentage along each edge element with respect to the from point of the original feature. APPORTIONABLE—The network attribute will be apportioned. NOT_APPORTIONABLE—The network attribute will not be apportioned. This is the default.	Boolean
domain (Optional)	The domain with which the network attribute will be associated. This parameter is required when is_inline = "INLINE". This domain is used to determine the number of bits to allocate for the in-line attribute and must be a coded value type. For example, the LifeCycleStatusDomain (0, Unknown | 1, In-Service | 2, Proposed | 3, Abandoned) domain has four entries, which means 2 bits are required to store the in-line attribute. The coded value domain must have sequential codes starting from 0.	String
is_overridable (Optional)	Note: This parameter is not used in the current release, and any value provided will be ignored. The functionality of this parameter is under development and will be applicable in a future release. Specifies whether the current value stored in the topology will be overridden using an external override table. This parameter can be used, for example, to input live data from external systems, such as present position in the case of electric or pressure value in the case of gas. An example is a SCADA system pushing the updated switching positions of Device A to the override table of the DeviceStatus network attribute, which the topology engine then uses to override its current value of device status for Device A with the override value. OVERRIDE—The current value stored in the topology will be overridden. NOT_OVERRIDABLE—The current value stored in the topology will not be overridden. This is the default.	Boolean
is_nullable (Optional)	Specifies whether the network attribute will support null values. NULLABLE—The network attribute will support null values. This is the default. NOT_NULLABLE—The network attribute will not support null values.	Boolean
is_substitution (Optional)	Specifies whether the network attribute will be used as a substitution. Substitution network attributes allow a substituted value to be used instead of bitset network attribute values during a propagation in a trace operation. Substitution is only supported with long integer network attributes. SUBSTITUTION—The network attribute will be used as a substitution. NOT_SUBSTITUTION—The network attribute will not be used as a substitution. This is the default.	Boolean
network_attribute_to_substitute (Optional)	The network attribute to be used as a substitution. Substitutions are encoded based on the number of bits in the network attribute being propagated. The network attribute must be in line and an integer field type less than or equal to 8 bits.	String

Derived Output

Name	Explanation	Data Type
out_utility_network	The updated utility network.	Utility Network

Code sample

AddNetworkAttribute example 1 (Python window)

Add a network attribute named Device Status with a short attribute type.

import arcpy
arcpy.un.AddNetworkAttribute("Utility Network", "Device Status", "SHORT", 
                             "INLINE", "NOT_APPORTIONABLE", "", 
                             "ElectricDistributionDeviceStatus", 
                             "NOT_OVERRIDABLE")

AddNetworkAttribute example 2 (Python window)

Add a network attribute to be used for substitution.

import arcpy
arcpy.un.AddNetworkAttribute("Utility Network", 
                             "Phases", "LONG", "NOT_INLINE", 
                             "NOT_APPORTIONABLE", 
                             "ElectricDistributionDeviceStatus", "", 
                             "NOT_NULLABLE", "SUBSTITUTION", 
                             "Phases current")

Environments

Current Workspace

Licensing information

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