The Migration toolset in the Utility Network toolbox contains three tools that provide a simplified process for the migration of existing data into a utility network to support basic editing and tracing workflows.
The Analyze Network Data tool evaluates an input utility network to find common types of topological inconsistencies, including self-intersecting lines, stacked points, and invalid connectivity. The tool generates a mobile geodatabase as an output that contains various feature classes and tables, which describe the error types found in the data. You can use these output feature classes and tables to understand the error scenarios and define the actions that you must take for each error type. The output Error Resolutions table can be edited and used to address error scenarios as the input for the Apply Error Resolutions tool.
Learn more about migrating to the utility network
Requirements
The following requirements must be met to analyze network data and find common error types:
- The network topology can be enabled or disabled.
- The following requirements must be met when working with an
enterprise geodatabase:
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.
Analyze network data to find errors
To analyze network data for common error types, complete the following steps:
- On the Analysis tab, in the Geoprocessing group, click Tools
to open the Geoprocessing pane. - In the Geoprocessing pane, search for and select Analyze Network Data.
- For the Input Utility Network parameter, specify a utility network.
Utility networks from a feature service are not supported.
- For the Output Location parameter, provide the path to a folder that will contain the output mobile geodatabase.
- For the Output Name parameter, specify the name for the output mobile geodatabase.
The default is AnalysisResults.
A folder is created that contains a mobile geodatabase with the name specified for the Output Location parameter.
- For the Set default resolution actions parameter, specify whether the default Action attribute values will be populated in the Error Resolutions table for the specified error types.
Any error action values populated by the tool can be modified. Not all errors have a default error action.
- Checked—The following error types will be populated with the default resolution action in the Action field of the output Error Resolutions table:
- Empty geometry—Delete all.
- Empty Shape length—Delete the row from the feature class.
- Self-intersecting line—Delete all but first vertex.
- Duplicate vertices—Delete all but first vertex.
- Stacked points—Delete all but first vertex.
- Multipart—Cut.
- Vertex within tolerance—One Anchor is assigned based on priority (junction > endpoint > midpoint) and Snap is assigned for all others.
- Unchecked—No error types will be populated with default error actions in the output Error Resolutions table. This is the default.
- Checked—The following error types will be populated with the default resolution action in the Action field of the output Error Resolutions table:
- Click Run.
The Analyze Network Data tool completes and creates a mobile geodatabase in the output location specified. The Error Summary and Error Locations feature class and Error Resolutions table are added to the active map using a group layer.
Feature class and table outputs
The mobile geodatabase created by the Analyze Network Data tool contains the following feature classes and tables:
- ErrorLocations—Point feature class describing distinct locations in the network where errors were discovered.
- ErrorSummary—Multipoint feature class summarizing all unique combinations of errors in the network using a multipart feature.
- ErrorRecords—Table containing information about all the features present at each error location and the type of associated error.
- ErrorResolution—Table describing the resolution for each group of errors. This is used as the input for the Apply Error Resolutions tool.
The folder containing the mobile geodatabase also contains a layer file (.lyrx) and a .csv file that can be used to understand and resolve errors:
- A group layer symbolizing errors found within the input utility network. The name of this group layer will match the name provided for the Output Name parameter when running the Analyze Network Data tool. This layer uses other tables and feature classes in the mobile geodatabase to aid the visualization of errors in the map.
- RuleCandidates—A .csv file communicating potential utility network rules that could be added to resolve errors.
The feature classes and tables in the output can be overlaid with a utility network using the group layer to provide context and aid visualization of the various errors encountered. The sections below outline the various output classes and their schema.
Error Summary and Error Locations feature classes
The Error Locations and Error Summary point feature classes provide information about the errors discovered in the input utility network. The Error Summary feature class contains multipoint geometries that aggregate all like features in the Error Locations feature class with a shared Analysis types and Error code value to provide an overview of the different error types in the utility network by class, asset group, and asset type.
The Error Locations feature class contains a point feature for every location in error. This allows you to review the individual locations represented by the Error Summary multipoint feature. When you select a location feature, related records are also selected in the Error Records table.
Note:
Selecting a record in the Error Locations feature class adds the source feature class to the map if it's not already present and selects related features. This relationship uses an absolute path to the source data. The relationship must be updated if the source data is moved.
The Error Summary feature class contains the following attribute fields:
| Field name | Field alias | Description |
|---|---|---|
OBJECTID | Object ID | The object ID for the multipoint error summary feature. |
ErrorCode | Error code | The error code for the summarized error type. |
AnalysisTypes | Analysis types | The feature class, asset groups, and asset types that are present at this location. This includes the feature in error and coincident features. Tip:In Options, adjust the Row Height setting to Triple on the Table tab to improve the readability of this field. |
TypesInError | Types in error | The feature class, asset group, and asset type of the features in error. |
SourceName | Source layers | The feature class of the features in error. |
AssetGroupName | Asset groups | The asset group of the features in error. |
AssetTypeName | Asset types | The asset type of the features in error. |
Occurrences | Occurrences | The number of Error Locations features that make up the multipoint geometry for each unique combination of AnalysisTypes and ErrorCode field values. |
ResolutionKey | Resolution key | The relational key used to link the Error Summary feature class to the Error Resolution table. Selecting a multipoint feature in the Error Summary feature class selects the related records in the Error Resolution table. |
Shape | Shape | The location of the features. |
The Error Locations feature class contains the following attribute fields:
| Field name | Field alias | Description |
|---|---|---|
OBJECTID | Object ID | The object ID for the individual error in the utility network. |
ErrorCode | Error code | The error code associated with the feature in error. |
AnalysisTypes | Analysis types | The feature class, asset groups, and asset types that are present at this location. This includes the feature in error and coincident features. |
ResolutionKey | ResolutionKey | The relational key used to link the Error Locations feature class to the Error Resolution table. |
SHAPE | Shape | The location of the feature. |
Error Records table
The Error Records table contains detailed information about features related to each error present in the Error Locations table. The group layer added to the map contains a subset of records from this table for every feature class containing errors filtered using a definition query. This table can be helpful when evaluating which other features may have contributed to the error condition reported.
The Error Records table contains the following attribute fields:
| Field name | Field alias | Description |
|---|---|---|
OBJECTID | Object ID | The object ID for the error record. |
LocationKey | Location key | The location key value for the error records. This corresponds to the object ID for the feature in the Error Locations feature class. |
ErrorCode | Error Code | The error code associated with the feature in error. |
AnalysisTypes | Analysis types | The feature class, asset groups, and asset types that are present at this location. This includes the feature in error and coincident features. |
ClassGroupType | Feature type | The feature class, asset group, and asset type of the associated feature. |
SourceID | Source layer | The feature class that is associated with the error record. |
SourceOID | Feature ID | The object ID of the feature associated with the error. |
Error Resolutions table
The Error Resolutions table is an editable table used to define the corrective actions that you must take to resolve the errors found by the Analyze Network Data tool. The modified table is then used as the input for the Apply Error Resolutions tool to edit features and correct error scenarios.
The Error Resolutions table contains the following columns:
| Field name | Field alias | Description |
|---|---|---|
OBJECTID | Object ID | The object ID of the resolution record. |
ErrorCode | Error code | The error code associated with the feature in error. |
AnalysisTypes | Analysis types | The feature class, asset groups, and asset types that are present at this location. This includes the feature in error and coincident features. Tip:In Options, adjust the Row Height setting to Triple on the Table tab to improve the readability of this field. |
ResolutionKey | Resolution key | The relational key that relates to the Error Summary feature class. |
GroupPosition | Group position | The sequence of the row in the Analysis types group. |
ClassGroupType | Feature type | The features class, asset group, and asset type of the features in error. |
SourceNames | Source layer | The feature class that is associated with the error record. |
AssetGroupNames | Asset group | The asset group of the feature associated with the error record. |
AssetTypeNames | Asset type | The asset type of the feature associated with the error record. |
ErrorContext | Context | Specifies whether the record references a feature in error or a coincident feature provided for context. |
ErrorAction | Action | The corrective action to be performed to resolve the error type. The options are as follows:
|
DeltaX | Delta X | The offset value applied to the x-coordinate of the geometry of a point or the vertex of a line. This is only valid for an update or create action. |
DeltaY | Delta Y | The offset value applied to the y-coordinate of the geometry of a point or the vertex of a line. This is only valid for an update or create action. |
DeltaZ | Delta Z | The offset value applied to the z-coordinate of the geometry of a point or the vertex of a line. This is only valid for an update or create action. |
DeltaStep | Delta step | When there are multiple features present in the same location, this defines the offset value applied to the DeltaX, DeltaY, and DeltaZ fields for each subsequent feature. This is only valid for an update or create action. |
ActionClassGroupType | Create/Update type | The asset group and asset type to use when creating a new feature or updating an existing feature. |
Error types found using the tool
While the Analyze Network Data tool is not intended to identify all errors, the following common utility network error types are found and returned in the Error codes attribute field in the Error Summary and Error Locations feature classes and Error Resolutions table. The table below outlines the error codes that may be found by the tool, the associated error ID, a description of the error, and the action (when applicable) that can be applied to resolve the error in the Error Resolutions table.
Note:
Not all error types have an automated solution available.Learn more about the best practices for fixing connectivity errors in a utility network
| Error code | Associated error ID | Description | Available error action |
|---|---|---|---|
Empty geometry | 1 | The geometry for the network feature is empty. This error can occur when a line feature has a zero or near-zero length. | Delete all/Delete all but first (vertex) |
Unknown asset group | 2 | The subtype used for the asset group attribute is unknown. This error occurs when a feature is migrated into the Unknown asset group. | Update all |
Shape length | 5 | The line feature has length within the tolerance. This error can occur when a line feature has a zero or near-zero length. | Delete all/Delete all but first (vertex) |
Rule missing | 8 | Connectivity exists between two features without a rule that permits the connectivity | N/A |
Ambiguous connectivity | 9 | There is more than one rule available for a potential connection. It is also possible to receive this error if more than one device exists at the endpoint of a line. | N/A |
Missing junction | 10 | Invalid connectivity exists due to line features that are connected between different asset groups and asset types without an intermediate device or junction feature. | Create |
Edge connectivity policy | 13 | A line has a connectivity that violates its edge-connectivity policy. For example, a line feature that only allows endpoint connectivity has a point or another line feature placed midspan. | N/A |
Multipart | 19 | A linear network feature has multipart geometry. | Cut |
Self-intersecting line | 20 | A line feature loops back and overlaps itself at the intersection of two vertices. | Cut Delete all/Delete all but first (vertex) |
Duplicate vertices | 21 | A linear network feature has multiple vertices existing in the same x, y, z location or within the network tolerance. | Delete all/Delete all but first (vertex) |
Invalid asset type | 23 | A network feature has an asset type other than the defined asset types for the asset group it belongs to. This error occurs when the asset type value of a feature is not a valid value in the asset type domain for the asset group. | Update all |
Invalid asset group | 23 | A network feature has an asset group with a value outside of the range for the subtype, or the subtype is invalid. This error occurs when the asset group value of a feature is not a valid subtype for its class. | Update all |
Stacked points | 25 | Two or more points are geometrically coincident or within the network tolerance. For example, a service point and a voltage regulator have the same x, y, z coordinates. | Delete all/Delete all but first (vertex) |
Invalid terminal | 36 | The line feature has an invalid terminal. This occurs when the from terminal ID or to terminal ID attribute for a line is not valid for one of the connected devices. | N/A |
Subnetwork tap | 37 | A feature with the subnetwork tap category is drawn at the end point of two lines. | N/A |
Midspan terminal device | 38 | A device with multiple terminals cannot be midspan along a line. This occurs when a terminal device is drawn midspan on a line. | N/A |
Vertex within tolerance | N/A | Two or more vertices from separate features are within the spatial tolerance of the dataset but are not topologically coincident. | Anchor Snap |
Available error actions
The following table describes the actions available to address errors using the tool
| Action | Description |
|---|---|
Create | Create a new feature. When this action is selected, you must specify the type of feature using the Create/Update type field. |
Update all Update all but first | Updates the corresponding vertex or features. If there are multiple features associated with the fix, you can choose to update all features or update all but the first feature. This action can also be used to update the location of a feature using the DeltaX, DeltaY, DeltaZ, and DeltaStep fields. When there are multiple coincident features, specify a value for the DeltaStep attribute to ensure each feature is offset from the previous feature. The asset group or asset type of a feature can also be changed using the Create/Update type field. |
Delete all Delete all but first | Deletes the corresponding vertex or features. If there are multiple features associated with the fix, you can choose to delete all features or vertices or to delete all but the first feature or vertex. |
Anchor Snap | The Anchor and Snap actions are used to resolve the Vertex within tolerance error. The Anchor action defines one vertex or feature as the anchor location while Snap communicates the other vertices or features to be snapped to the anchor location. |
Cut | Cuts the line at the vertex where the error occurs. When used to address self-intersecting lines this shorten the existing line feature and create a new line feature for the remaining geometry. When used to address multipart geometries, this action creates single-part features with attribute values matching the original feature. |
Define error resolution actions
The Error Resolutions table is used to define the corrective actions that you must take for the various errors found by the Analyze Network Data tool.
For an example, to define the actions needed to resolve a self-intersecting line error, complete the following steps:
- Add the utility network and all associated classes to an active map.
- Add the group layer (.lyrx file) containing the Error Summary feature class, Error Locations feature class, Error Records table, and Error Resolutions table.
By default, this file is in the folder specified in the Output Name parameter when the Analyze Network Data tool was run.
- Right-click the Error Summary feature class in the Contents pane, and click Attributes.
The attributes table for the Error Summary feature class opens.
- Identify a record with the Self-intersecting line error code, and select the row.
The Error Summary multipoint feature and related rows in the Error Resolutions table are selected.
- Right-click the selected row in the Error Summary attribute table and click Zoom To.
The map zooms to display all summary records associated with the error.
- Right-click the Error Resolutions table in the Contents pane, and click Open.
The attributes table for the Error Resolutions table opens.
- In the Error Resolutions table, use Show Selected Records to filter the table.
- For the selected records, identify the record with a Context value of Error, and review the Action attribute value.
If you checked the Set default resolution actions parameter when running the Analyze Network Data tool, a default resolution action of Delete all but first is specified for the field. If not, choose this value from the drop-down list in the field. This action causes the Apply Error Resolutions tool to delete all but the first vertex for the line at the intersecting location.
- On the ribbon, in the Manage Edits group, click Save to save your edits.
Resolution actions have been defined for errors found by the Analyze Network Data tool. You can use the Error Resolutions table as input for the Apply Error Resolutions tool to edit the utility network data and resolve the errors.