Editing code lists

After you check out a code list from Configuration Hub, you can edit it and then upload the modified code list. It is suggested that you keep these considerations in mind when you edit code lists.

Structure of code list file

Code lists are downloaded from Configuration Hub in comma-separated values (CSV) file format. Each CSV file is a delimited text file that uses a comma to separate each value.

Each CSV file contains CLH (Content List Header) rows, one CLIH (Content List Item Header) row, and one or more CLIV (Content List Item Value) rows.

CLH: The CLH (Code List Header) rows contain reference information about the code list.
Important: Do not edit or delete any CLH row or value.
CLIH: The CLIH (Code List Item Header) row contains the fixed headers (column names) that are used for every code list.
Important: Do not edit or delete the CLIH row or values.
CLIV: The CLIV (Code List Item Value) row or rows each contain one set of item values.
Tip: You can update values in the CLIV rows and add new CLIV rows as needed.

How to update a code list

Code lists are not modified directly in Configuration Hub. To modify a code list, you must check out the code list and edit it using a text editor or spreadsheet tool for comma-separated values (CSV) files. Checking out a code list gives you the ability to upload changes to it in Configuration Hub.

Important: When you edit a CSV code list file, keep in mind these considerations.

Spreadsheet tools provide a way to view and edit code lists with the values that are formatted in columns and rows. However, you need to use caution when you use spreadsheet tools if your code list values contain leading zeros.
- If you are sure that your code list does not contain values with leading zeros, you can open the CSV file with a spreadsheet tool with the default file open function.
- If you are not sure whether your code list contains any values with leading zeros, after you download the code list from Configuration Hub, open the CSV file in a text editor. Then, use the text editor find function to search for ,0. If that value is found in the search, your code list contains leading zeros.
- If your code list contains values with leading zeros, use the import function of your spreadsheet tool to preserve the leading zeros. For more information, see Preserving leading zeros in a code list. Alternatively, you can edit the CSV file by using a text editor, but be careful when you work with large code lists to be sure that the CSV format is maintained.
Leading and trailing spaces are trimmed.
Do not edit or delete any CLH row or value.
Do not edit or delete the CLIH row or values.
Do not add new columns to the file.
You can update values in the CLIV rows and add new CLIV rows as needed. However, be careful when you modify any existing code list data, especially when the code list is used by multiple maps or with multiple trading partners. Since code list changes might have unintentional effect, be sure to test any modified code list for each map or trading partner with which it is used.
Code list values can contain only extended ASCII characters, non-HTML characters, en dashes, or em dashes.
Do not change the file name of the code list CSV file.
Be sure to save the edited CSV file in the CSV format.

Special characters in code list values

If you use a spreadsheet tool to edit a CSV file, any special characters that you use in code list values might already be handled by your spreadsheet tool. For more information, see the documentation for your spreadsheet tool to determine how to special characters such as commas are handled.

If you are editing a CSV file with a text editor and a value contains a comma, you must enclose that value in double quotation marks. For example, the value blue, red needs to be encapsulated in double quotation marks in the CSV file as follows: "blue, red".

Maximum code list size

A code list can contain up to 25,000 items, but the overall code list CSV file size must be less than 3 megabytes.

Important: If a code list exceeds these size limits, the code list cannot be uploaded.

Leading and trailing spaces are not supported

Leading or trailing spaces are not supported in code list values. Any leading or trailing spaces are trimmed. Therefore, a value that consists solely of a space or spaces is treated as if no value is present. However, in a value that contains a space in between words (for example, blue red) the space is preserved.

Preserving leading zeros in a code list

If you open a CSV file in a spreadsheet tool and do not see expected leading zeros for a value, use a text editor to view the raw text values. If you edit a code list with a spreadsheet tool that formats text-type fields that contain numbers as numerical-type fields, leading zeros might be removed. The loss of leading zeros can cause incorrect code substitutions, missing values, data processing failures, and transformation failures.

You can import code list data into a spreadsheet tool to avoid the removal of leading zeros. For more information, see the documentation for your spreadsheet tool to determine how to display leading zeros in the tool by default.

Sample method to handle leading zeros by using Microsoft™ Excel (Windows™ operating system)

This procedure that is described is an example only, and might differ depending on your spreadsheet tool and operating system. For more information, see the documentation for your spreadsheet tool.

From Configuration Hub, download the code list CSV file.
In Microsoft Excel, be sure that the Import Wizard is enabled.
1. From the File menu, select Options.
2. In Excel Options, select Data.
3. In the Show legacy data import wizards section, select the From Text (Legacy) checkbox.
After the Import Wizard is enabled, select File > New and select Blank workbook.
From the Data menu, select Get Data > Legacy Wizards > From Text (Legacy).
In the Import Text File dialog box, select the appropriate code list and click Import.
In the Text Import Wizard - Step 1 of 3, be sure the Delimited option is selected and click Next.
In the Text Import Wizard - Step 2 of 3, clear the Tab checkbox and select the Comma checkbox. Then, click Next.
In the Text Import Wizard - Step 3 of 3, in the Data preview section hold SHIFT on your keyboard and click to select (highlight) all the columns. Then, in the Column data format section, select Text and click Finish.
In the Import Data File dialog box, select Existing Worksheet and click OK.
Tip: Verify that the code list data was imported with leading zeros preserved. If you add new values with leading zeros to the code list, those leading zeros are also preserved.
Make any necessary changes to the code list.
From the File menu, select Save As.
From the Save As dialog box, click Browse.
1. From Save as type, select CSV (Comma delimited) (*.CSV).
  Important: Do not save the code list as type CSV UTF-8.
2. In File Name, type the original code list CSV file name.
3. Click Save. Now you can upload the changed code list to Configuration Hub.

Sample method to handle leading zeros by using Microsoft Excel (macOS operating system)

This procedure that is described is an example only, and might differ depending on your spreadsheet tool and operating system. For more information, see the documentation for your spreadsheet tool.

From Configuration Hub, download the code list CSV file.
In Microsoft Excel, select File > New and select Blank workbook.
From the File menu, select Import.
In the Import dialog box, be sure that the CSV file option is selected. Then, select the appropriate code list and click Import.
Select the code list CSV file and click Get Data.
In the Text Import Wizard - Step 1 of 3, be sure the Delimited option is selected and click Next.
In the Text Import Wizard - Step 2 of 3, clear the Tab checkbox and select the Comma checkbox. Then, click Next.
In the Text Import Wizard - Step 3 of 3, in the Preview of selected data section hold SHIFT on your keyboard and click to select (highlight) all the columns. Then, in the Column data format section, select Text and click Finish.
In the Import Data dialog box, select Existing sheet and click OK.
Tip: Verify that the code list data was imported with leading zeros preserved. If you add new values with leading zeros to the code list, those leading zeros are also preserved.
Make any necessary changes to the code list.
From the File menu, select Save As.
From the Save As dialog box, click Browse.
1. From File Format, select Comma Separated Values (CSV).
  Important: Do not save the code list as type CSV UTF-8.
2. In Save As, select or type the original code list CSV file name.
3. Click Save. Now you can upload the changed code list to Configuration Hub.