FileMaker Data Migration Tool Guide

Use the FileMaker data migration command-line tool to migrate all record data and user accounts from a source file in the FileMaker Pro 12 format (FMP12) to a target file. This tool can be used in Windows or macOS.

For example, use the data migration tool to:

• copy test data or live data into a custom app between different stages of the DTAP (Development, Testing, Acceptance, and Production) cycle
• copy existing data into a new version of a custom app

Advantages of using the data migration tool, instead of importing data, include:

• you migrate all data at once, instead of importing data from each table separately
• the data migration tool maps fields between source and target tables automatically, instead of you mapping them manually for importing
• you can migrate user accounts, custom value lists, and serial numbers, which you can't do when you import data

Terms used in this document:

• source file: An FMP12 file that contains the data to migrate.
• clone: A copy of an FMP12 file that contains all the tables, layouts, scripts, and field definitions but none of the data. Use FileMaker Pro Advanced to make a clone, but don't open the clone. Opening a clone modifies it so that it won't work with the data migration tool.
• file to be cloned: A file that includes tables, layouts, scripts, and field definitions to use for the target file. This file can be the same as the source file, or it can be a different file. For example, if you migrate data between different stages of the DTAP cycle, the file to be cloned could be in the testing stage while the data to migrate could be in the production stage.
• target file: A copy of the clone created by the tool, into which data and user accounts from the source file are migrated.

• If the account for accessing the source file or the clone doesn't have the Full Access privilege set, create a new extended privilege, called fmmigration, for the account. See FileMaker Pro Advanced Help in the Product Documentation Center.

  The keyword for the extended privilege must start with the fmmigration prefix. The account with this extended privilege doesn't need to have access to any tables, scripts, or layouts. The source and clone extended privilege names must match (but are not case sensitive).

• The source file and the clone must be either both encrypted or both unencrypted. If they are encrypted, the encryption passwords can be different.
• Make sure you know the account name, password, and encryption password (if encrypted) for the source file and the clone.

1. In FileMaker Pro Advanced, open the file to be cloned.

2. Choose File menu > Save a Copy As, then choose clone (no records).

   Important:Do not open the clone with FileMaker Pro Advanced.

3. Make sure the source file is closed.
4. Download the file Win_FMDataMigration_x64.zip (Windows) or Mac_FMDataMigration.zip (macOS).
5. Unzip the downloaded file and move the contents to a location of your choice.

6. Use the following command at the command-line prompt:

   FMDataMigration -src_path <path> -clone_path <path>

   The parameters -src_path and -clone_path are required. All the other parameters are optional.

   Parameter	Description
   -src_path	Source filename and path.
   -src_account	Account name used for opening the source file. The default is Admin.
   -src_pwd	Password for accessing the source file.
   -src_key	Encryption password for decrypting the source file.
   -clone_path	Clone filename and path.
   -clone_account	Account name for accessing the clone. The default is Admin.
   -clone_pwd	Password for accessing the clone.
   -clone_key	Encryption password for decrypting the clone.
   -target_path	Target filename and path. The default target file, source filename migrated.fmp12, is located in the same folder as the source file.
   -force	Overwrites an existing target file. If you have an existing target file, you must use a different name for the new target file, or use -force to overwrite the existing file.
   -ignore_valuelists	Uses custom value lists from the clone instead of the source file.
   -ignore_accounts	Uses the account names, passwords, and the encryption password from the clone instead of the source file.
   -ignore_fonts	Doesn't check the font mapping for field contents.
   -version	Ignores any other parameters and only outputs the version number.
   -v (verbose mode)	For accounts with the Full Access privilege set, provides a detailed report about the data migration process. For accounts with the fmmigration extended privilege, in both normal and verbose modes, the tool provides only a brief report without displaying any information about the schema.
   -q (quiet mode)	Doesn't provide a report.

Notes

• The data migration tool returns zero (0) when it is successful, and returns a non-zero number when there is an error. For the meaning of an error, see the error message that the tool outputs.

External container data

The data migration tool doesn't migrate container data that is stored externally, so keep the following in mind:

• Before you open the target file after migration, make sure the target is in the same location as the source file relative to the external container data. This ensures that references to external container data will work.
• If the source file is hosted, use Admin Console to close the file and download it to a computer where the data migration tool is located, run the tool, and rename the target file to match the source file's name. Next, use Admin Console to remove the source file on the host. Then use FileMaker Pro Advanced to upload the newly migrated file to the host. If you prefer not to download and upload a large amount of external container data along with the file, you can manually transfer only the database file. For information on uploading database files manually to FileMaker Server, see FileMaker Server Help.
• If, during migration, container field storage options are changed (for example, from open storage to secure storage), the FileMaker data migration tool does not transfer the container data. To transfer the container data, open the target file with FileMaker Pro Advanced and click Transfer Data in the Manage Containers dialog box.

The command in this example migrates the data from the source file, SampleDB.fmp12, to the target file, SampleDB migrated.fmp12. This example uses the Admin account with no password. The source file and the clone aren't encrypted. The data migration tool uses custom value lists from the clone, doesn't check font mapping, and creates a detailed report.

FMDataMigration -src_path SampleDB.fmp12 -clone_path SampleDBClone.fmp12 -ignore_valuelists -ignore_fonts -v

The FileMaker data migration tool uses the following rules to match the data between the source file and the clone.

• Data is migrated only if the names or internal IDs of tables and fields match. The tool determines the best match in this order:

  • both the names and the IDs match
  • only the names match
  • only the IDs match

  If no matches are found, the data is not migrated.

• The privilege set for a migrated user account is set to the clone’s privilege set only if the privilege set names or IDs match. The tool determines the best match in this order:

  • both the names and the IDs match
  • only the names match
  • only the IDs match

  If no matches are found, a new privilege set, Unmapped Privilege Set, with no privileges assigned is created for the account.

• Custom value lists are migrated only if the names match.