A subnetwork represents a subset of your utility network's topology in a tier where all participating features have traversability to the same subnetwork controllers. The life cycle of a subnetwork begins when it is created and consists of many stages as it is managed and edited by users, only ending if it is deleted. It can be best understood through the various subnetwork management tasks typically run on subnetworks.
The following summarizes the various subnetwork management tasks that make up the subnetwork life cycle:
- Set a subnetwork controller—You can create a subnetwork by setting one or more network features as subnetwork controllers. The name of the subnetwork is defined when a terminal on a device or junction object is set to be a subnetwork controller. When adding a controller to an existing subnetwork, the status of the existing subnetwork is unchanged until the modified features are validated. If you're creating a subnetwork, there is no record in the Subnetworks table or SubnetLine feature class to represent the status of the subnetwork controller.
- Validate network topology—The modified network features are validated to update the network topology with the changes. This changes the status of the subnetwork to Dirty.
- Update a subnetwork—The update subnetwork operation performs a trace from all subnetwork controllers, updates the subnetwork name of modified features, creates or updates the record for the subnetwork in the SubnetLine feature class, updates subnetwork system diagrams, and changes the status of all its controllers to Clean (isDirty = false). If validate consistency issues or subnetwork errors are encountered during the update subnetwork operation, the status of all its controllers is changed to Invalid (isDirty = Invalid).
- Modify a subnetwork—Subnetworks are modified to change their name or to either add or remove subnetwork controllers from the subnetwork. These workflows modify the subnetwork in the same manner as setting a new subnetwork controller. Changes must be validated and the subnetwork updated to change the status to Clean.
- Remove a subnetwork controller—You can remove a subnetwork controller by deleting the subnetwork controller setting from the terminal using the Modify Subnetwork Controller pane. This sets the isDeleted attribute for the controller in the Subnetworks table to True. You can remove controllers from subnetworks as long as other controllers are still connected to the subnetwork. If they are not, an error is returned when the subnetwork is updated. These workflows modify the subnetwork in the same manner as setting a new subnetwork controller. Changes must be validated and the subnetwork updated to change the status to Clean.
- Export subnetwork information—The Export Subnetwork tool is used to export information about a subnetwork into a .json file. That information can then be consumed by external systems such as outage management and asset tracking programs. A subnetwork's status must be Clean to be eligible for export.
- Delete a subnetwork—A subnetwork can be deleted from a tier in the utility network by removing all the subnetwork controllers that define the subnetwork. Once removed, the records for the subnetwork controllers are marked as deleted, and the update subnetwork operation is run to update the network topology so that the network features are not treated as controllers by analytic operations. The Export Subnetworks tool is then used with the Set export acknowledged parameter checked to export information about the deleted subnetwork and remove the rows from the Subnetworks table, effectively deleting the subnetwork from the tier.
Subnetwork status
There are various tools used for subnetwork management that influence the state (or status) of a subnetwork. The status of a subnetwork determines what operations can be run on a subnetwork.
A subnetwork can be dirty, invalid, or clean. This is tracked by the Is dirty attribute in the Subnetworks table and applies to all subnetwork controllers for a subnetwork when updated. The subnetwork statuses are defined as follows:
- Dirty—A dirty subnetwork is a subnetwork that contains validated edits that have not yet been processed by the update subnetwork operation. Validating the network topology discovers and marks controllers of a subnetwork as dirty when the geometry or network attributes for a network feature in that subnetwork have been modified.
- Invalid—An invalid subnetwork is a subnetwork in which validate consistency failures or subnetwork errors are discovered during the update subnetwork operation. These issues and errors must be addressed by modifying the geometry or network attribute for the impacted network features and validating to update the subnetwork status, changing it to Dirty. Invalid subnetworks are ignored during the update subnetwork operation and must first be made dirty before they can be updated again and marked as clean. All controllers in the Subnetworks table for an invalid subnetwork have their isDirty attribute set to Invalid.
- Clean—A clean (or consistent) subnetwork is a subnetwork that has been successfully updated. All controllers in the Subnetworks table, the record in the SubnetLine feature class, subnetwork system diagrams, and various fields for modified network features have been updated and are in sync with changes made to the network topology. All controllers in the Subnetworks table for a clean subnetwork have their isDirty attribute set to False.
Subnetwork management tasks and their impact
The following tables list various edits that can be performed on a utility network that affect the state of subnetworks or subnetwork components:
- Action—Description of action or operation performed
- Results from action—List of changes in the subnetwork
Enable and disable network topology
A network topology is disabled to perform administrative tasks such as managing network rules, modifying terminal configurations, addressing subnetwork errors, or updating the subnetwork definition. When the disable operation completes, all subnetwork controllers in the Subnetworks table and all the features in the SubnetLine feature class are marked as dirty. The network topology is initially enabled once a utility network is configured and ready for consumption, to work with dirty areas, run traces, and generate network diagrams. Following the enable operation, dirty areas are generated to mark features with topological errors in your network, all subnetwork controllers in the Subnetworks table are marked as dirty, and any features in the SubnetLine feature class are marked as dirty.
The following table outlines the impact that enabling and disabling the network topology have on the status of the subnetworks:
| Action | Results from action |
|---|---|
Enable the network topology. |
|
Disable the network topology. |
|
Modify features and validate the network topology
When network features are created or modified through edits to their associations, terminal configuration information, network attributes, or geometry, dirty areas are created to flag the location of edits. These serve as an indicator that a change to the network has taken place that is not reflected in the network topology. Dirty areas are cleaned when the network topology is validated. When network features have successfully validated, this updates the network topology with the changes along with marking the corresponding subnetwork controllers in the Subnetworks table and SubnetLine features as dirty. This dirty state indicates that the subnetwork status and network topology are not in sync.
Note:
The response from the validateNetworkTopology operation in the REST API returns the name of any subnetwork that is marked as dirty during the operation along with the domain network and tier containing the subnetwork as discoveredSubnetworks.
The following table outlines the impact that modifying features and validating the network topology have on the status of the subnetworks:
| Action | Results from action |
|---|---|
Create or modify network features. |
|
Validate the network topology. |
|
Update a subnetwork
When a subnetwork is updated, information in the Subnetworks table, attributes on features, and objects are updated, and a subnetwork line in the SubnetLine feature class can be created or updated. If subnetwork errors or validate consistency failures are encountered during the update operation, the update operation fails and the subnetwork is marked as invalid. To learn more, see Update subnetworks.
The following table outlines the impact that updating a subnetwork has on the status of the subnetworks:
| Action | Results from action |
|---|---|
Update a subnetwork. |
When subnetwork errors or validate consistency failures are encountered during the update subnetwork operation, the update subnetwork operation fails, and the following occur:
|
Remove a subnetwork controller and export subnetworks
Removing a subnetwork from the system does not happen frequently, but when it is required, several steps must be performed in a specific order for it to be properly removed. You must first remove a subnetwork controller by deleting the subnetwork controller setting from the terminal using the Modify Subnetwork Controller pane. When this assignment is removed, the Is Deleted attribute is marked as true for the associated subnetwork controller in the Subnetworks table. Like other modifications to network features, this operation creates dirty areas that must be cleaned. Validating the network topology ensures that the topology is up to date so that the terminal is no longer treated as a subnetwork controller by analytic operations. Updating the subnetwork following validation marks the subnetwork as clean, and if the removed controller was the last controller for that subnetwork, the tool also removes the subnetwork name from any connected features in the subnetwork. The deleted subnetwork controller will remain in the system until an administrator acknowledges the delete when exporting the subnetwork.
Exporting a subnetwork is most commonly performed to export information from a clean subnetwork to a .json file for use by external systems. The export subnetwork operation can also be used to remove deleted subnetwork controllers from the Subnetworks table. To remove the deleted controller, run the Export Subnetwork tool with the Set export acknowledged parameter checked. This operation updates the Last ack export subnetwork field in the SubnetLine feature class and deletes the record for the controller from the Subnetworks table while updating the Last Exported field for all of the remaining controllers that participate in the subnetwork. When all subnetwork controllers for a subnetwork are removed, an export with the Set export acknowledged parameter checked will delete the subnetwork controller from the Subnetworks table and will also remove the SubnetLine feature for the subnetwork. From that point forward, the subnetwork will no longer be available for analysis in the tier.
The following table outlines the impact to subnetworks when removing a subnetwork controller and exporting subnetwork information:
| Action | Results from action |
|---|---|
Remove a subnetwork controller. |
|
Export a subnetwork. |
|