About the patch-file
The structure at the top level of the patch file is:
<?xml version="1.0"?>
<FMUpgradeToolPatch version="2.2.2.0">
<Structure>
<!-- One or more *Action elements -->
<AddAction> ... </AddAction>
<DeleteAction> ... </DeleteAction>
<ReplaceAction> ... </ReplaceAction>
</Structure>
<Metadata>
<AddAction> ... </AddAction>
</Metadata>
</FMUpgradeToolPatch>The FMUpgradeToolPatch root element indicates that this file is intended for the upgrade tool to use as a patch file. This distinguishes the file from the similar FMSaveAsXML file, which is not intended to be used unmodified with the upgrade tool.
Note For changes to some elements, the version attribute of FMUpgradeToolPatch requires a value greater than 2.0.0.0.
The child elements of FMUpgradeToolPatch are:
-
Structure: Contains actions to perform on the catalogs and other elements that describe the structure of the file.
-
Metadata: Contains actions to perform on anything that isn't a database catalog—for example, settings in the File Options dialog box.
Changing objects or catalogs using the Structure element
The *Action elements specify what objects or catalogs to add, delete, or replace and can be used under Structure.
|
*Action element |
Description |
Support |
|---|---|---|
|
AddAction |
Adds new objects. To add an object, use the element name for the object's catalog and specify the UUID for the catalog and object. For example: Copy
Under AddAction, use the catalog's element name. Under the catalog element, include the UUID element and reproduce the structure down to the specific object to be added. Some catalogs have ObjectList elements with a child element for each object, others don't. Under a single AddAction element, you can add multiple objects by including multiple objects under a list element like ObjectList. Refer to the FMSaveAsXML file for the structure to include. Also, see the example in Creating a patch file. |
In an FMSaveAsXML file, most children of the Structure element are catalogs. Generally, any of their children are supported objects that can be added with this action in a patch file. Adding sub-objects to existing container objects is not supported, except for FieldsForTables and StepsForTables. Saved finds are not supported. The following data formatting options are currently not supported:
|
|
DeleteAction |
Deletes objects or entire catalogs. To delete an object in a catalog, use the ItemReference element and specify the UUID and type attributes. For example: Copy
Note All references must have UUIDs; otherwise, the action isn't performed. To delete a catalog, use the CatalogReference element and specify the catalogName and uuid attributes. For example: Copy
Where supported, deleting a catalog will try to delete all user-created objects in the catalog; predefined objects—for example, the Full Access, Data Entry Only, and Read-Only Access privilege sets—won't be deleted. |
Only these high-level objects (and their containing objects) in the XML structure are supported:
All catalogs are supported, except AccountsCatalog. |
| ReplaceAction |
Modifies existing objects and their containing objects. In general, an object can have only its properties replaced, not its children. Therefore the XML that describes a containing object must not contain an ObjectList element—if it does, ReplaceAction will result in undefined behavior. One exception to this rule is replacing an entire layout; in this case, the XML describing the layout should be complete, as when using AddAction. To replace a sub-object, this action must refer to the sub-object specifically. For example, to replace a field layout object in a portal, don't attempt to replace the portal; replace only the field object. To replace an object, use the Replace element and specify the type and UUID attributes. For example: Copy
Within the Replace element, specify the object and its properties. See the example in Creating a patch file. Note All references must have UUIDs; otherwise, the action isn't performed. |
Only high-level objects (and their containing objects) in the XML structure are supported. For LayoutObject elements, only those with the following type attributes can have their basic properties modified with ReplaceAction:
Changing a layout object to a different type or changing the layout it's on is not supported. |
Changing settings using the Metadata element
The AddAction element specifies settings to change under the Metadata element. To change a setting, use the element name for the setting and specify the value of one or more attributes.
Starting with FileMaker 21.1.1, the upgrade tool supports changing the settings shown in the patch file below. This is a subset of the settings in the File Options dialog along with the Don't display in host's file list options for FileMaker Network clients and for FileMaker WebDirect clients.
To change any of the supported settings:
-
Create a patch file like the one shown below that includes one or more of the elements under AddAction with the attributes set as needed. You can omit any elements for settings you don't need to change.
-
Validate the patch file. For example:
Copy./FMUpgradeTool --validatePatch -src_path ./MyApp-v1.fmp12 -patch_path ./v1-v2-patch.xml -src_account Admin -src_pwd admin -
If the patch file is valid, test that the patch file updates your app as expected. For example:
Copy./FMUpgradeTool --update -src_path ./MyApp-v1.fmp12 -src_account Admin -src_pwd admin -patch_path ./v1-v2-patch.xml -dest_path ./MyApp-v1-patched-to-v2.fmp12 -v
<?xml version="1.0"?>
<FMUpgradeToolPatch version="2.2.2.0"> <!-- To change settings, a version value greater than 2.0.0.0 is required. -->
<Metadata> <!-- Required tag -->
<AddAction> <!-- Required tag -->
<HideClientSharing enable="True"></HideClientSharing> <!-- FileMaker Network clients, enable: Don't display in host's file list -->
<HideWebDirectSharing enable="True"></HideWebDirectSharing> <!-- FileMaker WebDirect clients, enable: Don't display in host's file list -->
<Login type="1"> <!-- type: Automatic log-in ON ("1"), OFF ("-1") -->
<UserName> <!-- You can omit UserName and INSECURE_PASSWORD if automatic log-in is OFF -->
<INSECURE_TEXT>Admin</INSECURE_TEXT>
</UserName>
<INSECURE_PASSWORD>
<INSECURE_TEXT></INSECURE_TEXT>
</INSECURE_PASSWORD>
</Login>
<SavePassword keychain="True" requireMobile="True"></SavePassword> <!-- keychain: Allow stored credentials for authentication; requireMobile: Require iOS and iPadOS passcode -->
<ShowSignInFields enable="True"></ShowSignInFields> <!-- enable: Show sign-in fields even when OAuth or AD FS is enabled -->
<HideToolbars enable="True"></HideToolbars> <!-- enable: Hide all toolbars -->
<Spelling whileTyping="Beep" underline="True"></Spelling> <!-- whileTyping: Check spelling as you type ("Beep"/"Off"); underline: Indicate questionable words with special underline -->
<Text>
<Handle smartQuotes="True" asian="True" roman="True"></Handle> <!-- smartQuotes: Use smart quotes; asian: Use Asian language line-breaking; roman: Use Roman language line-breaking -->
<DataEntry type="512"></DataEntry> <!-- type: Ask whenever settings are different ("512"); Always use current system settings ("1024"); Always use file's saved settings ("0") -->
</Text>
</AddAction>
</Metadata>
</FMUpgradeToolPatch>