Data dictionaries. Lookup tables. Codebooks. While the name for a dataset’s documentation might vary across professions and data sources, the need for data documentation is universal! A common way to store this type of metadata is in a lookup table or data dictionary. At its simplest, a data dictionary is a two-column table in which one field is the field name, and another is the corresponding definition of what that field name represents.

This type of information can be stored on each field as the alias. An alias is an alternative name for a field providing a more user-friendly description of the content. Aliases are much more accommodating than field names, as they can contain up to 255 characters, including spaces and special characters, and even start with numbers. By applying aliases, you can give names to fields that are more descriptive than their actual field names.

Benefits of applying field aliases

The many ways that field aliases make your data easier to work with include:

• When selecting by attributes, your field aliases are visible in the dropdown menus when creating expressions.
• When creating charts, your field aliases are visible in the dropdown menus, and more importantly, in the titles and axes labels of your charts.
• When creating map layouts, your field aliases can be displayed in your legends.

In short, applying field aliases is good data management. It’s possible to set these field aliases using the handy dandy lookup table manually, which can take a whole afternoon. With this approach, there’s always the chance for human error, and the chance of getting a repetitive motion injury! Instead, we can use use this bulk-assign alias script tool to do this systematically.

What is a script tool?

Script tools are geoprocessing tools that execute a script or executable file. Script tools allow you to run these scripts from within ArcGIS, using a geoprocessing tool as the interface to the functionality in your script. When you create a script tool, you specify parameters that your script needs to execute. The most common parameters are input and output datasets, field names, and strings chosen from a choice list. When the script tool is run, the parameter values are passed to your script and used by your script during execution.

Almost all script tools execute a Python script (.py) that uses ArcPy, a Python site package installed with ArcGIS. ArcPy provides access to geoprocessing tools as well as additional functions, classes, and modules that allow you to create simple or complex workflows quickly. Through ArcPy, your script can access the geoprocessing environment of ArcGIS, providing benefits such as validation of inputs, error messages, and recording of history.

You can create your own script tool for your specific use-case by first writing a script with parameters. (While most script tools are written in Python, you can create a script tool for an .r, .bat, or .exe file that accepts arguments.) We created a script and accompanying script tool to bulk-assign aliases from a lookup table. We’re using a script tool in a Python toolbox rather than a custom toolbox, which is why it has the extension of .pyt. We are excited to share this tool with you!

A script tool that can bulk-assign aliases

The inspiration for this script tool comes from the geodatabase files containing American Community Survey data made available from the U.S. Census Bureau. These geodatabases contain a polygon file with boundaries, a metadata table which has two fields (Short_Name and Long_Name), and then 32 tables with a few hundred fields in each.

Here’s the metadata table:

Here’s an example of one of those 32 attribute tables:

The field names of these tables are the Short_Name in the metadata table. We wanted to apply the corresponding Long_Name as the alias. Taking advantage of the arcpy.management.AlterField tool, we wrote a script that bulk-assigns aliases to the table of your choice.

How can I use this tool?

First, decide if you want to run the stand-alone script in the Python window, or if you want to use the script tool. The stand-alone script will run much faster, but the script tool allows you to point-and-click your way to running the tool, since it’s essentially a custom geoprocessing tool.

Step 1. Download either the stand-alone script, or the Python toolbox containing the Bulk Assign Aliases script tool. Save and extract the files in your Pro Project’s folder.

Step 2. Within the Catalog Pane, navigate to the stand-alone script or the tool in your folder connections. (You can also see the stand-alone script by right-clicking the script tool and selecting Edit.)

Step 3. If running the script tool, set the parameters you want.

Step 4. Run the tool or the script, and be patient. It will most likely take some time.

Step 5. Open up your attribute table, and see your fields with aliases:

Aliases show up throughout ArcGIS Pro and ArcGIS Online

Aliases show up when working with the data, such as when selecting by attributes.

They also appear when displaying your data in charts, legends, and infographics.

Aliases are preserved when publishing your maps and layers to ArcGIS Online. Applying field aliases to your fields early on makes downstream work easier. Use use this bulk-assign alias script tool to assign aliases from a lookup table in a systematic way.

Update on 3 August, 2022: This script tool requires that the long names (aliases) be 255 characters or fewer. Many of the official long name values will need to be modified. The “find and replace” option in the table view can help to remove strings such as ” — (Estimate)” and ” — (Margin of Error)” which can help. There are no plans to update this script tool at this time.

Update on 5 March, 2023: For best results, make sure your feature layer is in a geodatabase (gdb).