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 in 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 typeIn lineApportionableNullableSubstitution

    Short

    Check markCheck mark

    Long

    Check markCheck markCheck mark

    (Out of line only)

    Double

    Check markCheck mark

    Date

    Check mark

    Big integer

    Note:
    Big integer network attributes are supported with Utility Network Version 7 and later.
    Check mark

Parameters

LabelExplanationData 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 that will be added 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.
  • DateThe field type will be date.
  • Big integer (64-bit integer)The field type will be big integer.
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 or 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.

For example, with the shape_length network attribute and a line feature that consists of five edge elements of 20 feet each in which the total length of that line feature is 100 feet, the 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.

Learn more about how to calculate the bit size for In Line network attributes

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 that will 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

LabelExplanationData Type
Updated Utility Network

The updated utility network.

Utility Network

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})
NameExplanationData 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 that will be added to the utility network.

String
attribute_type

Specifies the data type of the network attribute.

  • SHORTThe field type will be short.
  • LONGThe field type will be long.
  • DOUBLEThe field type will be double.
  • DATEThe field type will be date.
  • BIGINTEGERThe field type will be big integer.
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 or long).

  • INLINEThe attribute will be added internally to the topology, making retrieval more efficient.
  • NOT_INLINEThe 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.

For example, with the shape_length network attribute and a line feature that consists of five edge elements of 20 feet each in which the total length of that line feature is 100 feet, the 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.

  • APPORTIONABLEThe network attribute will be apportioned.
  • NOT_APPORTIONABLEThe 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.

  • OVERRIDEThe current value stored in the topology will be overridden.
  • NOT_OVERRIDABLEThe 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.

  • NULLABLEThe network attribute will support null values. This is the default.
  • NOT_NULLABLEThe 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.

  • SUBSTITUTIONThe network attribute will be used as a substitution.
  • NOT_SUBSTITUTIONThe network attribute will not be used as a substitution. This is the default.
Boolean
network_attribute_to_substitute
(Optional)

The network attribute that will 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

NameExplanationData 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

Licensing information

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

Related topics