Migrate relationship classes to a utility network

You're a GIS analyst in a small city tasked with migrating your data to an electric utility network so you can trace, manage, and analyze your network data. You decide to implement a standard model supported by multiple vendors, such as one of Esri's Utility Network Foundations. A Utility Network Foundation allows you to create associations between different types of features in the network. Associations represent the relationships between features in a way that facilitates tracing and analysis.

In this tutorial, you'll migrate data and relationships from an electric geodatabase to a utility network. The focus of this tutorial is on how to create associations for electrical features using existing relationship classes. You can find resources covering different industries and data migration at the end of this tutorial.

This tutorial was last tested on April 29, 2026, using ArcGIS Pro 3.6. If you're using a different version of ArcGIS Pro, you may encounter different functionality and results.

Requirements

• ArcGIS Pro (see options for software access)

Migrate relationship classes to a utility network

Create a data mapping workbook

The first step to migrating your data to a standard, preconfigured data model like a Utility Network Foundation is to create high-level data mappings that show how the data in your source database will be migrated to the target model. You'll create these mappings and turn them into a data migration workspace that can be used with data loading tools.

Note:

This tutorial focuses on migrating the relationship between transformers and poles, but the workflow can be used for any of the relationships or associations supported by the utility network.

1. Download the Data_Loading project package and extract it to a location on your computer, such as your C:\Temp folder.
2. Locate the downloaded file on your computer and double-click it to open it in ArcGIS Pro. If prompted, sign in with your ArcGIS account credentials.

   Note:

   If you don't have access to ArcGIS Pro or an ArcGIS organizational account, see options for software access.

   ArcGIS Pro opens in Catalog view. The Catalog pane also opens with your Data Loading project folder.

   

3. In the Catalog pane, expand Folders and expand the Data Loading folder.

   

   The Data Loading folder is also the project folder, indicated by the icon that appears on the folder. It contains folders with sample source and target data models for several industries, but for the purpose of this tutorial, you'll focus on electric.

   Each target data model is an asset package. You can learn more about asset packages and how they're used for migration on the Overview of the Utility Network Package toolbox page.

4. In the Catalog pane, expand UtilityDataManagementSupport.atbx.
5. Expand the Data Migration folder and double-click the Create Simple Data Mapping tool.

   

6. In the Create Simple Data Mapping tool, for Source Dataset, click the Browse folder button.
7. In the Source Dataset window, under Project, expand Folders and Data Loading. Click the Electric folder and choose ElectricUtilities.gdb.

   

   This is the current data that you want to migrate to a utility network package.

8. Click OK.
9. For Asset Package, click the Browse folder button.
10. In the Electric folder, click Electric_AssetPackage.gdb or use file path C:\Temp\Data_Loading\DataLoading\Electric\Electric_AssetPackage.gdb.

    This is the schema and configuration from the Utility Network Foundation that you want to migrate your data to.

11. For Output Location, click the Browse folder button and choose the Electric folder. For Output Folder Name, type Data mappings.

    This is where you want to output the simple data mappings that will be created by the tool.

12. Check the box next to Include All Target Classes.

    

    The Create Simple Data Mapping tool creates a data mappings workbook in a new folder in the project.

13. Click Run.

    Once the tool is finished, a Data Mapping folder with a spreadsheet is added to the output folder. The spreadsheet describes the contents of your source database and contains additional columns that you'll use to map your existing source features to new objects in the target data model.

Map feature classes

Next, you'll create data mappings to migrate the devices and structures in your source database to their corresponding classes in the target asset package. The spreadsheet has been prepopulated with the contents of your database. All the columns that include Source represent the source information from your source data. The Target columns are empty and you will walk through the process of populating them in the next steps.

Note:

Because the focus of this tutorial is on creating associations, the mappings used for the classes in this section have been simplified. You can find more detailed examples of data mappings at the end of this tutorial.

1. In File Explorer, browse to the Electric folder and open the DataMapping workbook in C:\Temp\Electric\DataMappings\DataMapping.xls.

   

   The DataMapping workbook opens.

   

2. Scroll down to row 10 where the Source Class is Transformer.

   For each of these rows, you'll use the drop-down menus on the Target Class, Target Subtype, and Target Asset Type columns to specify their destination in the target database.

   

   Note:

   Because most analysts migrating to Utility Network Foundations tend to think about their equipment first and then structures, you'll fill in your workbook in that order. If you fill in the workbook in a different order, you'll achieve the same results.

   First, you'll set up your devices.

3. On rows 10 through 13, click the Target Class cell and use the drop-down arrow to choose ElectricDevice.

   

   Transformers are electrical devices in a network, as seen in the source class. This is how you know the Target Class is ElectricDevice.

4. On rows 10 through 13, for Target Subtype (Asset Group), choose Transformer.

   

   When you choose the electric device target class, the Target Subtype (Asset Group) menu will automatically update to show all the relevant asset groups for that class. You chose Transformer because it most closely matches the source class, Transformer.

5. For the Target Asset Type column, choose the following options:
   • On row 10, choose Overhead Single Phase – MV -> LV.
   • On row 11, choose Pad Mounted Single Phase – MV -> LV.
   • On row 12, choose Overhead Three Phase – MV -> LV.
   • On row 13, choose Pad Mounted Three Phase – MV -> LV.

   When you select the target subtype, the Target Asset Type menu is populated with all the corresponding asset types. You can use the Source Subtype Name field for each of the transformers to determine the correct target asset type.

   

   Now that you have set up your devices, the last mapping you need to create is for the relationship class between the device and the structure.

6. On rows 3 through 9, for Target Class, choose StructureJunction.

   Poles are locations in your network where structures are supporting electrical infrastructure. In the list of target classes, StructureJunction most closely matches the source class, SupportStructure.

   

7. Use the drop-down menus to fill in the rest of the workbook with the following options:

   Row	Target Subtype (Asset Group)	Target Asset Type
   3	Electric Medium Voltage Pole	Primary Pole
   4	Electric Low Voltage Pole	Pole LV
   5	Electric Low Voltage Pole	Ornamental LV
   6	Electric Medium Voltage Pole	Primary Pole
   7	Electric High Voltage Pole	Pole HV
   8	Electric Medium Voltage Pole	Primary Pole
   9	Electric Low Voltage Pole	Pole LV

   

Map associations

Now that you have created mapping for your devices and structures, you are ready to create mapping for the relationship between them. You decided to start by migrating this device and structure class because they are important to your organization's network. You know that the device feature class has a relationship to the structure feature class that is modeled by storing the global ID of the structure in a field on the device class.

Some of the relationships, like those between devices and structures, are designed to be migrated as associations. You'll create the mappings to turn a relationship into an association.

Note:

The data mapping spreadsheet includes an Associations tab that can also be used to map relationships to associations. That approach relies on a static CSV file that isn't appropriate for datasets with many relationships, or those that are being edited frequently.

1. Right-click the row header after the last row (row 14) and choose Insert.

   

   A new row is added to the sheet.

2. Copy the Source Feature Dataset (E_Distribution) from one of the rows and paste it in the new empty row.

   A new mapping is created for all the devices in the class.

3. Copy the Source Type and Source Class values from the row above and add them to the row.

   

   Note:

   If the relationship between classes is an attributed or many-to-many relationship, create a mapping using the attributed relationship class instead of the destination of the relationship.

4. Set the Target Class column of the new mapping to C_Associations.

   

   You'll use this mapping to create the association between the device and structure.

   If you do not see the C_Associations option, you'll need to rerun the Create Simple Data Mapping tool with the Include All Target Classes option checked.

5. Save your workbook.

   Note:

   You can also create mappings to the C_SubnetworkControllers table if you want to create subnetworks as part of your migration. This method allows you to enable subnetwork management on features like circuit breakers (electric), custody transfer meters (gas), treatment plants (water and wastewater), or outfalls (stormwater).

Create a data migration workspace

Now that you have created high-level data mappings for several classes, you need to create a way to define how all the values for each feature are migrated. One way of doing this is to use Data Loading tools. Esri Data Loading tools use a data migration workspace to define the detailed mappings and translation of data between two databases.

The Utility Data Management Support toolbox includes the Create Migration Workspace tool. This tool turns the simple data mapping workbook you populated into a data migration workspace usable by the Data Loading tools.

1. In the Catalog pane, expand the UtilityDataManagementSupport and Data Migration toolboxes. Double-click the Create Migration Workspace tool.

   

2. In the Create Migration Workspace tool, set the following parameters:
   • For Source Dataset, click Browse and choose ElectricUtilities.gdb.
   • For Asset Package, click Browse and choose Electric_AssetPackage.gdb.
   • For Data Mapping Spreadsheet, click Browse and choose DataMapping.xlsx from the Data mappings folder in the Electric folder.
   • For Service Territory Polygon, click Browse and choose the ServiceTerritory feature in the ElectricUtilities.gdb folder.
   • For Output Location, click Browse and choose the Electric folder.
   • For Output Folder Name, type Migration Workspace.

   

   Note:

   If you cannot find your Data mappings spreadsheet, refresh your Data mapping folder.

   Because this tutorial is focused on creating associations, you'll accept the rest of the default parameters.

3. Click Run.

   The Create Migration Workspace tool takes a few minutes to run as it creates the migration workspace and creates a copy of the asset package that is reprojected to work with your coordinate system. This migration workspace provides full control of how the data is translated from your source database to the utility network.

Map association fields

Next, you'll create a detailed mapping that will turn the relationship between the device and structure into an attachment association. The type of association you create depends on the association role of the structure. Associations to a container require creating a containment association while structures require creating an attachment association.

First, you'll open the data reference workbook created in the data migration workspace you created.

1. In the Data Loading folder, browse to the Electric\Migration Workspace\Data Loading Workspace folder and open the DataReference.xlsx workbook.

   This workbook contains links to additional workbooks that contain detailed instructions for each mapping.

2. On the C_Associations line (Row 9), open the MappingWorkbook link.

   

   The Transfrmr_C_Assctns spreadsheet opens.

3. For the field mappings, fill in the Expression field with the following information:
   • For association_type, type "Structural Attachment".
   • For from_global_id, choose !SupportStructure_GlobalID!.
   • For to_global_id, choose !GlobalID!.

   

   The type of association you create for each relationship depends on your needs, but the following are the most common types:

   • Containment—An association between a container and its content.
   • Structural Attachment—An association between a structure and its content.
   • Junction Junction Connectivity—A connection between two point features.
   • Junction Edge From Connectivity—A connection between a point and a line feature on the from end of the line.
   • Junction Edge To Connectivity—A connection between a point and a line feature on the to end of the line.
   • Junction Edge Midspan Connectivity—A midspan connection between a point and a line feature.

   When creating connectivity associations, you also need to specify the terminal ID for each network feature.

   Because you mapped the association to the destination in the relationship, the global ID of the feature will be used as the destination global ID of the association. This mapping will create an association between each device and structure. Associations allow devices and structures to see their associated features, like relationships. Associations also allow you to include structures in your trace results and subnetwork exports.

   Many of the fields on the association mapping are left blank. The domain, feature class, asset group, and asset type of the features for this association are not easily defined in the spreadsheet.

4. Save the workbook.

Migrate associations

Next, you'll use the Data Loading tools to run the migration workspace. These tools will migrate the devices, structures, and relationships you mapped from your source data into your asset package.

Once you've run the migration, you must populate the associations table in the asset package. Then, you'll run the Sync C Tables tool to populate all the required columns on the C_Associations table with the information from the rest of the tables in the target database.

1. On the ribbon, click the View tab. In the Windows group, click Geoprocessing.

   

   The Geoprocessing pane appears.

2. In the Geoprocessing pane, click the Toolboxes tab.
3. Under System, expand Data Management Tools. Expand Data Loading and double-click the Load Data Using Workspace tool.

   

   Tip:

   You can also use the search bar in the Geoprocessing pane to find a tool you need.

4. For Data Reference Workbook, click the Browse button and choose your DataReference.xlsx workbook or use the file path C:\Temp\Data_Loading\Data Loading\Electric\Migration Workspace\DataLoadingWorkspace.

   

   Note:

   If necessary, refresh your notebook.

5. Click Run.

   The tool will take a few minutes to run.

   Note:

   You may receive warnings because not all the devices have relationships with the structure you selected. The tool will run with the desired output. You can avoid these warnings by applying a definition query to the mapping that only includes features that have the origin feature's GlobalID field populated.

   A new table is added to the Catalog pane.

6. In the Catalog pane, expand the Electric folder and click your Migration Workspace folder.
7. In your Migration Workspace folder, open the Electric_AssetPackage.gdb folder, right-click the C_Associations table and choose Open Table.

   Note:

   The file path for this C_Associations table is C:\Temp\Data_Loading\Data Loading\Electric\Migration Workspace\Electric_AssetPackage.gdb.

   

   The C_Associations table opens.

   There are several empty columns. These are columns that you didn't provide mappings for. You'll use a tool from the UtilityDataManagementSupport toolbox to populate these columns.

   

8. Close the C_Associations table.
9. In the Catalog pane, expand UtilityDataManagementSupport and Asset Package. Open the Sync the C Tables Asset Group/Type tool.

   

10. For Asset Package, browse to C:\Temp\Data_Loading\Data Loading\Electric\Migration Workspace and choose Electric_AssetPackage.gdb.

    

11. Click Run.

    The tool runs and an updated table with all the columns filled out is now available.

    Note:

    If the tool fails because it cannot get an exclusive lock, ensure you have closed the C_Associations table and try again.

12. Open the C_Associations table.

    

    All the domain network, network class, asset group, and asset type columns are now populated.

    Note:

    This tutorial shows you how to migrate existing relationship classes to associations. If you want to use spatial analysis and proximity to create associations, you can use the Create Association Records tool and the B_Rules table to create associations.

In this tutorial, you learned how to create a data migration that can create devices, structures, and associations using the Data Loading tools. You learned how to use the Create Simple Data Mapping tool to create high-level mappings between your source and target database. You also learned how to use the Create Migration Workspace tool to create detailed mappings based on the workbook you populated.

You can find a complete collection of data migration resources on the ArcGIS Utility Network migration reading list.

While this tutorial doesn't include steps for performing the migration, you can find videos and instructions for the entire data mapping and migration process in the Deploying a Utility Network Foundation article. You can also find unique instructions and examples for each Utility Network Foundation included in their documentation.

If you want to learn more about populating detailed mappings on feature classes, including how to translate domain values between two models, check out the Load data into a utility network tutorial.

If you want a more detailed, industry-specific look at how to migrate data, several of the Utility Network Foundations now include instructions for data migration:

• Electric transmission data loading
• Electric unbalanced distribution data loading
• Sewer data loading
• Water distribution data loading

If you are looking for more examples of how other industries use associations in a utility network, refer to the Loading associations into a Utility Network Foundation article.

You can find more tutorials in the tutorial gallery.

Acknowledgements

• The Data_Loading zip file is artificial data that was created by Esri for this tutorial.