When you find that a custom field has the wrong scope, data type, or prompt behavior, or is just in the wrong place, you can migrate the values from the old field to a new one. The process uses a query to export the existing values and Upload Dataset to import those values back to the correct destination.
This article describes the generic process for migrating values from one field to another. Some migrations require additional destination-specific mappings. For example, migrating from custom phone and email fields to the device table (a common example) must also map the device type for each imported value.
🔔 Important!
Data imports and merge processes cannot be undone. Test the migration in an up-to-date test environment before running it in production.
Before you begin
Identify the field to be migrated, the new destination, and the record type that stores the values. Confirm that the new destination already exists and is configured correctly before exporting or importing data.
Decide how the import should match existing records. Use the most stable identifier available for the record type:
Person records: Use a stable person identifier, such as Prospect ID, or another unique identifier that already exists on the record.
Application records: Use Application Slate ID when the value belongs to a specific application.
Dataset records: Use Row Slate GUID Matching Only, Row Identity Matching Only, Key, or a dataset-scoped field that is configured as unique for merging. See Matching Criteria for Dataset Records for the matching order for dataset imports.
If the new destination uses prompts, review the prompt list before importing. If the field stores multiple values, decide whether the import should append values to existing data or replace existing data.
Planning the migration
Create a short migration plan before changing data. The plan should answer the following questions:
Which records should receive the migrated value?
Which column will identify the existing record during import?
Which old field value should move to the new destination?
Should blank values be ignored, or should they clear values in the new destination?
Which forms, queries, reports, dashboards, rules, source formats, and Deliver recipient lists currently use the old field?
Who should review the exported file and import mappings before the import runs?
Exporting the old values
Build a query that exports one row for each record and includes both the matching identifier and the old field value.
Go to Queries / Reports.
Create a new query, or copy an existing query that already returns the correct records.
Select the query base that matches the records that store the old field values.
Add the identifier export (globally unique identifier, or GUID) that Upload Dataset will use to match the imported row to the existing record.
Add the old field export.
Add filters to limit the results to records that should be migrated. For example, filter for records where the old field exists if you do not need rows with blank values.
Run the query.
From the Output list, select Excel Spreadsheet and then select Export.
For more detail about adding and configuring query exports, see Adding and Configuring Exports. For output options, see Query Output Options.
Preparing the import file
Review the exported file before you import it. Keep only the columns that the migration requires, and use clear column names so each mapping is easy to verify.
Retain the matching identifier column, and keep the old value column to be imported to the new destination.
Remove records that should not be updated.
Resolve duplicate rows if the import should update each record only once.
📝 Note
Excel can change some values when a file is opened or saved, including leading zeros. If the old field value includes IDs, postal codes, or other formatted text, confirm that the file preserves those values before import.
Importing values to the new destination
Use Upload Dataset to update existing records with the exported values.
Go to Database → Sources / Upload Dataset.
Select Upload Dataset.
Configure the following settings:
File Format: Select New Spreadsheet/Data File.
File Type: Select the file type that matches the export file, such as Excel Spreadsheet.
Destination Scope: Select Person/Dataset Record.
Record Type: Select the record type that stores the new destination.
Update Only: Select this setting so the import updates matching records and does not create new records.
Select Add Files, select the prepared file, and then select Upload.
Select Build Import.
In Field Mappings, map the identifier column to the matching-only destination for the selected record type.
Map the old field value column to the new destination field or standard destination.
If the new destination uses prompt values, complete the prompt value mappings.
If each imported row should receive the same supporting value, add it in Static Mappings. For example, use a static mapping when every imported value needs the same type, category, or status.
Open Review & Run Import, review any pre-flight warnings, and then select Run Import.
For complete Upload Dataset guidance, see Upload Dataset.
Verifying the migration
After the import finishes, verify the migrated values before you update or inactivate the old field.
Review the import status and row counts.
Open several updated records and confirm that the new destination contains the expected value.
Run a follow-up query that exports the matching identifier, the old field value, and the new destination value.
Compare the query results with the import file to confirm that expected records were updated.
Investigate records that did not update before rerunning the import.
Updating references to the old field
After the data has moved, update the resources that still use the old field. Common places to check include:
Forms and form field mappings
Queries, exports, filters, joins, reports, and dashboards
Deliver mailing recipient lists and merge fields
Rules, populations, portals, and tabs
Source formats and recurring imports
Custom SQL, formulas, or snippets that reference the field
When you update a form, inactivate the old form field instead of deleting it if you need to preserve prior form response data. When you update a query, inactivate old exports and filters if you need to preserve the previous query configuration for reference.
Inactivating the old field
Inactivate the old field only after you confirm that the values migrated successfully and active resources use the new destination.
Go to Database → Fields.
Open the old field.
Set Status to Inactive.
Select Save.
Inactive fields do not appear as new mapping destinations on forms or source imports, and corresponding exports and filters are not available to add to new queries. Existing resources that already reference the field should still be reviewed and updated as part of the migration.
📖 Further reading: Troubleshooting Misconfigured Fields