Use attribute substitution

Attribute substitution allows the utility network to change the way values are propagated by allowing a feature to dynamically transpose values as the network is being traced. In practice, this allows you to alter the phasing of a portion of your network by using attribute substitution on a single device or junction that propagates to a section of your network instead of modifying the attribute of the propagating value on all features in that section of your network.

Attribute substitution values are used to recalculate network attributes when a subnetwork is traced or updated. They are set up for subnetworks in a tier using the Set Subnetwork Definition tool to represent the default or standard definition for all subnetworks in a tier. To modify this definition during an operation (update or trace), access the appropriate tool using ModelBuilder or programmatically through Python.

Attribute substitution is handled by configuring a network attribute for a database field. Substitution is a type of network attribute whose value is used to calculate the propagated value for features with the attribute substitution category assigned to its asset type. The resulting substitution value is then used to calculate the value for the next connected feature. To use attribute substitution, attribute propagation must be configured.

From a computing point of view, substitutions map each bit within a network attribute bitset to another bit. For example, consider phase in an electrical network. In this example, a bitset of three bits or more (depending on the configuration) is stored in the Phase field using a system-maintained in-line network attribute. Each bit represents a phase; A, B, and C, and bits are configured by using powers of 2. For example:

  • A, B, and C are 2^2, 2^1 and 2^0, or A = 4, B = 2, and C = 1, respectively.

You then configure the combinations, such as AB = 6, AC = 5, BC = 3, and ABC = 7 by adding the original values together. These are the same values you will find in the coded value domain configured for the Phase field. The following table displays the domain and bit values for each phase:

PhaseDomain valueBit value












2^1 + 2^0






2^2 + 2^0



2^2 + 2^1



2^2 + 2^1 + 2^0

This information allows you to configure information associated with your network that will tell a tracing operation to substitute one phase value for another. For example, substitute Phase B when Phase A is present or substitute de-energized for Phase B and C. As a result of a change such as this, features with Phase A are treated as Phase B, and features with Phase B or C are treated as de-energized. These calculated values are stored in another field on features that are configured for substitution.

Calculate substitution values

To properly calculate substitution values and configure attribute substitution, you need to think in terms of all 3 bits as each having 3 bits underneath them to describe the substitution for what bit A, B, and C are to become. With the 3-bit system, there are 9 bits to deal with. In a 4-bit system, adding a neutral to A, B, and C, there would be 16.

Illustration of 3 and 4-bit systems for substitution.

Focusing on a 3-bit system example from the Electric Utility Network Foundation solution in which A becomes B, B becomes de-energized, and C becomes de-energized (ABC->B00), we can better understand how this substitution is made. The A bit would switch to the B bit in that first position and the substitution bit would be 7. To substitute de-energized for Phase B or C does not require you to provide any value. To make this substitution, the value of 128 would be used, which is 2^7.

Example substitution where Phase A becomes Phase B.

From AFrom BFrom C

To A

256 (2^8)

32 (2^5)

4 (2^2)

To B

128 (2^7)

16 (2^4)

2 (2^1)

To C

64 (2^6)

8 (2^3)

1 (2^0)

Alternatively, if you wanted to substitute Phase B for Phase A; C for B; and A for C (ABC->BCA), the result would look like the following image where A becomes B, B becomes C, and C becomes A. To make this substitution, the value of 140 would be used, which is 2^7 + 2^3 + 2^2 (128 + 8 + 4 = 140).

Example substitution where Phase A becomes B, B becomes C, and C becomes A.

From AFrom BFrom C

To A

256 (2^8)

32 (2^5)

4 (2^2)

To B

128 (2^7)

16 (2^4)

2 (2^1)

To C

64 (2^6)

8 (2^3)

1 (2^0)

For more information on these examples of substitution for electric phases, review the phasessubstituted field for the Electric Device layer in the solution's data dictionary.

How substitution values work with propagation

To understand how the substitution values work with the propagated value, consider the image below displaying phase on an electrical circuit. The propagated value is ABC coming from the source controller feature on the left side. The triangle feature marked with a T represents a tap; that is, its asset type is tagged with the system-provided category of Subnetwork Tap. When an analytic operation encounters the tap, an attribute substitution takes place using the substitution value if one is set. For example, using the value of 128 for 3 bits indicates the following:

  • A becomes B.
  • B becomes de-energized.
  • C becomes de-energized.

The next connected feature's propagated value is the result of the calculated substitution value on the tap. In the example below, the tap has a network attribute value of AC, which is recalculated to B. Each subsequent feature with an A in its set of phases is replaced with a B while the analytic operation takes place.

Phase swap using taps in an electrical circuit.

In the image above, black label values represent network attributes (Phase), the purple label values represent the substitution network attribute, and the blue represents the propagated network attribute value. Notice the features connected to the right of the first tap do not display a propagated value of B. This is because the tap feature has the subnetwork tap network category assigned, which allows the tap's substitution value to only affect those features connected off the main line, the line on which the tap is midspan.


Network features marked with the subnetwork tap category must be midspan on a line, otherwise they will become errors when validating the network topology.

The features connected to the right of the second tap have the same value propagated down through the first tap (denoted by the blue B). The features connected below the second tap have underlined Bs to denote new propagated values calculated from the second tap.

Substitutions allow you to further refine the results of propagated values. Consider the example above with that below. In the example above, the second downstream tap is energized, where the substitution is: A becomes B, and B and C become de-energized. In the example below, where the substitution is: A becomes de-energized, C becomes B, and B becomes de-energized; the second downstream tap is de-energized, (substitution value of 2 on the right side instead of 128 in the example on the left) effectively de-energizing the tap and any features tapped off from it.

Phase swap using taps and slight variation of substitutions: AC to ØB.

Use substitution propagation

Propagated values, including attribute substitutions, are not used to override the values on your features or the associated network attribute values. When you export a subnetwork, propagated values are stored in the extracted information. When a subnetwork is updated, propagated values can be stored in the Propagated Attribute field, if defined. This field is set using the Set Subnetwork Definition tool when configuring a tier. This example shows a tier with Propagators configured that include a Substitution Attribute as well as Propagated Attribute, both of which are optional.

Example model displaying Propagators configured with a Substitution Attribute.

Using the Propagator configured in the image above, when a subnetwork in this tier is updated, the Phases Current network attribute, defined as the Attribute field in the image, will be propagated. If it traverses a feature with the subnetwork category of Attribute Substitution, it will check for a substitution value using the PhasesSubstituted network attribute defined in the Substitution Attribute field. The resulting propagated value, including substitution if applicable, will be written to the phaseenergized field, which is defined in the Propagated Attribute field.

Define what features use substitute attributes

The attribute substitution network category is a system-provided network category that allows you to specify which asset types are to be considered for attribute substitution. Any features with this category will be considered for attribute substitution.

This category is set on asset types by the utility network administrator at the time of configuration using the Set Network Category tool. Attribute substitution can be configured by running the Set Subnetwork Definition tool for an existing tier using ModelBuilder or through Python.

Attribute substitution setup overview

Attribute substitutions are configured by the administrator of a utility network. These are the necessary steps for establishing attribute substitution and build on the example outlined in the Attribute propagation topic:

  1. Assign the Attribute Substitution network category to classes for specific asset groups and asset types—for example, an electrical Tap from the Junction feature class.
  2. Create a field to store the value that will be used to determine how to substitute the values being propagated. This is only necessary on the classes in which an asset type was set with the Attribute Substitution network category.
  3. Create and assign a coded value domain to the field created in step 2. The value 128, for example, when decoded means A becomes B, B becomes de-energized, and C becomes de-energized in a 3-bit system. Add coded values to represent each substitution that a user may want to do. Examples discussed so far for 3 bit are as follows:
    • CodeDescription


      C to B, and AB de-energized


      A to B, and BC de-energized


      A to B, and B to C, and C to A

  4. Add a network attribute for the Substitution Attribute and specify that it substitutes for the network attribute being propagated. This is done by checking the Substitution parameter on the Add Network Attribute tool and selecting the network attribute from the Network Attribute to Substitute drop-down menu.
  5. Assign the substitution network attribute to the field created in step 2 using the Set Network Attribute tool.
  6. Use the Set Subnetwork Definition tool to define attribute substitutions used for propagation during analytic events. This can be done by adding the Set Subnetwork Definition tool to a model in ModelBuilder. In ModelBuilder, do the following:
    1. Right-click the Set Subnetwork Definition tool in the model and choose Create Variable, then click From Parameter, and click Propagators.
    2. Double-click the Propagators parameter added to the model and populate the attributes appropriately.