Claris FileMaker Upgrade Tool Guide

The Claris FileMaker upgrade tool applies schema, layout, and script changes to a FileMaker Pro (.fmp12) file.

Where to find the tool

The FMUpgradeTool command-line tool is installed with FileMaker Server for Windows, macOS, and Linux.

During the installation of FileMaker Server, the FMUpgradeTool command is added to the accessible command paths, so you can run it from any location. The tool is installed in the following default locations:

  • Windows: C:\Program Files\FileMaker\FileMaker Server\Database Server\FMUpgradeTool

  • macOS: /Library/FileMaker Server/Database Server/bin/FMUpgradeTool

  • Linux: /opt/FileMaker/FileMaker Server/Database Server/bin/FMUpgradeTool

You also have the option to install only the FileMaker command-line tools. To choose this option:

  • Windows and macOS: Start installing FileMaker Server, then select FileMaker command-line tools in the Deployment Options dialog.

  • Linux: Run the FileMaker Server for Linux installer. When prompted to select the installation type, enter the command 3 for Claris FileMaker command-line tools.

Examples

Common use cases for the upgrade tool are:

  • A customer wants to upgrade to a newer version of your app but doesn't want to lose, or can't migrate, their data and their schema or layout customizations from their file to a new file.

  • A developer requests a customer to apply a temporary debug patch to an app to track down or mitigate an issue the customer is having.

  • A developer wants to provide a critical bug fix to all customers.

  • A developer wants to remove sensitive debug data or functionality that was not intended for distribution to customers.

  • A developer wants to generate a FileMaker Pro file directly from an XML file to:

    • Programmatically create a new file.

    • Regenerate a file after making edits to its XML representation.

    • Create a file as part of a version-controlled development workflow.

The best practice for using the upgrade tool is to provide quick, short-term fixes to problems between full releases of an app. This approach keeps the patch file relatively simple and primarily for adding objects to an app. For full releases of an app or to add or modify objects and properties not supported by the upgrade tool, use the FileMaker data migration tool instead. See FileMaker Data Migration Tool Guide.

Terms used in this document:

  • source file: An FMP12 file to be upgraded.

  • destination file: A copy of the source file that has been upgraded using a patch file.

  • patch file: An XML file that specifies the actions (add, delete, and replace) to perform on the source file. The root element is FMUpgradeToolPatch. A patch file may be plaintext or encrypted.

  • FMSaveAsXML file: An XML file created via the Save a Copy as XML command or script step in FileMaker Pro. This file is an XML representation of the FMP12 file it was saved from. The root element is FMSaveAsXML. You use this file to help create a patch file.

  • object: An element in an FMSaveAsXML file or patch file that describes an individual item in a FileMaker Pro file—for example, a field, table, script, script step, layout, or layout object.

  • catalog: A collection of objects in an FMSaveAsXML file or patch file.

  • *Name element: Any XML element name with the Name suffix. For example, *Action element refers to an AddAction, DeleteAction, or ReplaceAction element.

Before you begin

Windows: To display UTF-8 characters correctly in the upgrade tool output, set the code page for the command window to UTF-8. For example, use the chcp command:

Copy 
> chcp 65001
Active code page: 65001

Notes 

  • The upgrade tool does not support migrating, adding, modifying, or deleting record data, including externally stored container data.