Claris FileMaker Custom App Upgrade Tool Guide

To create a patch file that adds a field to a table:

1. Close v1 of your app (MyApp-v1.fmp12) and run the upgrade tool with the ‑‑generateGUIDs subcommand and MyApp-v1.fmp12 as the source file.
2. Save a copy of MyApp-v1.fmp12 as XML and name it MyApp-v1.xml.
3. Make a copy of MyApp-v1.fmp12 and name it MyApp-v2.fmp12.
4. Add a field to a table in MyApp-v2.fmp12.
5. Close MyApp-v2.fmp12 and run the upgrade tool with the ‑‑generateGUIDs subcommand and MyApp-v2.fmp12 as the source file.
6. Save a copy of MyApp-v2.fmp12 as XML and name it MyApp-v2.xml.

7. Compare the relevant section of MyApp-v1.xml (left) and MyApp-v2.xml (right).

   

   The notable change between MyApp-v1.xml and MyApp-v2.xml is the addition of a Field element under the FieldsForTables/FieldCatalog/ObjectList element.

   Also note these important UUID elements or attributes:

   • Under the FieldCatalog element, the UUID element starts with A434D930 (line 47).
   • In the BaseTableReference element, the UUID attribute starts with 9B93EC91 (line 50).
   • Under the Field element, the UUID element starts with 9ADC7007 (line 111).

8. Create a plaintext patch file (v1-v2-patch.xml) that applies this change. Use the top-level structure shown in About the patch file. In the Structure element:

   • Add an AddAction element.
   • Under the AddAction element, re-create the structure down to the ObjectList element, using the UUID elements or attributes from the v2 FMSaveAsXML file.
   • Under ObjectList, add a Field element for the new field. You can include all the attribute and child elements from the v2 FMSaveAsXML file, but you must include the name and datatype attributes. Be sure to include the UUID element, so that in future upgrades, you can reference this field by this UUID, if needed.

   <?xml version="1.0"?>
<FMUpgradeToolPatch>
<Structure>
<AddAction>
<FieldsForTables membercount="1">
<FieldCatalog>
<UUID>A434D930-F3BE-4833-A8CF-D8BE9A5A8D31</UUID>
<TagList></TagList>
<BaseTableReference id="129" name="Table" UUID="9B93EC91-B53E-407B-AF5B-F1961A8CD109">
</BaseTableReference>
<ObjectList membercount="6">
<Field DefaultStyle="" id="6" name="Note" fieldtype="Normal" datatype="Text" comment="">
<UUID>9ADC7007-D176-4872-8982-B33CD51FAA61</UUID>
<TagList></TagList>
</Field>
</ObjectList>
</FieldCatalog>
</FieldsForTables>
</AddAction>
</Structure>
</FMUpgradeToolPatch>

To create a patch file that changes the height and other properties of a rectangle object on a layout:

1. In v1 of your app (MyApp-v1.fmp12), add a rectangle object to a layout.
2. Close MyApp‑v1.fmp12 and run the upgrade tool with the ‑‑generateGUIDs subcommand and MyApp-v1.fmp12 as the source file.
3. Save a copy of MyApp-v1.fmp12 as XML and name it MyApp-v1.xml.
4. Make a copy of MyApp-v1.fmp12 and name it MyApp-v2.fmp12.

5. In MyApp-v1.fmp12, change these properties of the rectangle:

   • layout object name
   • height
   • tooltip
6. Close MyApp-v2.fmp12 and run the upgrade tool with the ‑‑generateGUIDs subcommand and MyApp-v2.fmp12 as the source file.
7. Save a copy of MyApp-v2.fmp12 as XML and name it MyApp-v2.xml.

8. Compare the relevant section of MyApp-v1.xml (left) and MyApp-v2.xml (right).

   

   The notable changes between MyApp-v1.xml and MyApp-v2.xml are:

   • In the LayoutObject element, the layout object name has changed.
   • In the Bounds element, the location of the bottom edge of the rectangle has changed.
   • In the Tooltip element, the text of the tooltip has changed.

   Notice these important UUID elements:

   • Under the Layout element, the UUID element starts with B5470113 (line 2704).
   • Under the LayoutObject element, the UUID element starts with 5D660197 (line 2689).

9. Create a plaintext patch file (v1-v2-patch.xml) that applies these changes. Use the top-level structure shown in About the patch file. In the Structure element:

   • Add a ReplaceAction element with a single Replace child element.
   • In the Replace element, the type attribute is the same as the element name to be changed, which you can see in the FMSaveAsXML files (in this case, LayoutObject). The UUID attribute is the same value as the UUID child element of the LayoutObject element to be changed in the FMSaveAsXML files.
   • Under the Replace element, add a *Reference element to specify the parent of the object to be changed—in this example, LayoutReference. For the UUID attribute, specify the value of the Layout element's UUID child element from the FMSaveAsXML file. For the other attributes of the LayoutReference element, specify the same values as for the Layout element in the FMSaveAsXML file.
   • Also under the Replace element, add an element for the object to replace—in this example, LayoutObject. For the object, use the same XML from the FMSaveAsXML file and change the values of the properties as needed.

   <?xml version="1.0"?>
<FMUpgradeToolPatch>
<Structure>
<ReplaceAction>
<!-- Layout object's UUID -->
<Replace type="LayoutObject" UUID="5D660197-8995-4AE1-9C53-989AD6394604">
<!-- Layout's UUID -->
<LayoutReference id="1" name="Table" width="1024" UUID="B5470113-1D0F-4787-99B0-00BD19AF6600">
</LayoutReference>
<LayoutObject id="1" type="Rectangle" name="MyRectangleObjectName" kind="5">
<!-- Layout object's UUID -->
<UUID>5D660197-8995-4AE1-9C53-989AD6394604</UUID>
<Bounds top="88" left="29" bottom="140" right="86"></Bounds>
<Options>805322752</Options>
<Rectangle></Rectangle>
<Tooltip>
<Text><![CDATA["My rectangle tooltip."]]></Text>
</Tooltip>
</LayoutObject>
</Replace>
</ReplaceAction>
</Structure>
</FMUpgradeToolPatch>

The following commands assume the app is unencrypted and has a full access account named Admin with the password admin. They use the same filenames as in the above examples.

To generate GUIDs in your app:

./FMUpgradeTool ‑‑generateGUIDs ‑src_path ./MyApp-v1.fmp12 ‑src_account Admin ‑src_pwd admin

To validate the patch file:

./FMUpgradeTool ‑‑validatePatch ‑src_path ./MyApp-v1.fmp12 ‑patch_path ./v1-v2-patch.xml ‑src_account Admin ‑src_pwd admin

To test that the patch file updates MyApp‑v1.fmp12:

./FMUpgradeTool ‑‑update ‑src_path ./MyApp-v1.fmp12 ‑src_account Admin ‑src_pwd admin ‑patch_path ./v1-v2-patch.xml ‑dest_path ./MyApp-v1-patched.fmp12 ‑v

By default, a patch file is a plaintext XML file, usually with the filename extension .xml. You should use a plaintext patch file only when you are not concerned about anyone modifying the customer's instance of your app using their own plaintext patch file.

Even if a patch file is plaintext, you must specify a FileMaker file account name and password when you run the upgrade tool. The account in the app to be upgraded must have either of the following:

• the Full Access privilege set
• a privilege set with the fmupgrade extended privilege

An encrypted patch file, with the filename extension .fmpatch, makes the patch file unreadable to anyone without the passkey and causes the upgrade tool to return an error if the patch file has been altered after it was encrypted. You should use an encrypted patch file when you are concerned about others applying their own patches to the customer's instance of your app.

When the tool upgrades an app, the tool opens the source file with the specified account credentials, retrieves the passkey, uses the passkey to decrypt the patch file, and applies the patch.

To associate the passkey with the FileMaker file account:

1. Decide on a passkey to use to encrypt the patch file. The passkey must:

   • use only the characters A-Z, a-z, or 0-9
   • be 91 characters or fewer

   Note:The passkey is case sensitive.

2. Before you distribute a custom app, create an extended privilege named fmupgradepasskey, where passkey is the same passkey you use to encrypt the patch file.

   For example, if your passkey is k4EuhSEG, then the extended privilege name should be fmupgradek4EuhSEG.

3. Add your fmupgradepasskey extended privilege to the privilege set assigned to the FileMaker file account that you plan to use when the tool upgrades a source file.

   You can use any privilege set, Full Access or not. A common use case is to add fmupgradepasskey to the Full Access privilege set and optionally add it to another, very limited privilege set assigned to the account that has the permission to upgrade the app.

   If there's more than one fmupgradepasskey extended privilege, only the first one listed in FileMaker Pro will be used.

To encrypt the patch file, run the upgrade tool using the ‑‑encryptPatch subcommand and, for ‑patch_key, use the same passkey you decided on in step 1. For example:

FMUpgradeTool ‑‑encryptPatch
‑patch_path ./plaintext-patch.xml
‑patch_key k4EuhSEG
‑dest_path ./encrypted-patch.fmpatch