FMComparison Help

You should absolutely read all of the following before using FMComparison.

CAVEAT: This is beta software. I can make no guarantees about the accuracy or completeness of the results until it has been fully validated by myself and by user experience. Exercise caution when using the results to guide development decisions.

Software Requirements

• FileMaker Pro 19 or higher.
• macOS 10.13 or higher.
• Windows 10 or higher. I’ve only tested in Windows 10, but it should work back to Windows 7. I would love to get confirmation of that from users.
• Up-to-date FMPerception support.

Requirements/Limitations

• FMComparison is currently not licensed independently from FMPerception. You must be a licensed user of FMPerception with up-to-date support in order to install FMComparison. Like FMPerception, you can install and use any version released before your support expires, even after your support expires.
• During the beta period, FMComparison will not be available to FMPerception users under a Trial license.
• FMComparison currently requires FileMaker 19 or greater. We may or may not add support for FileMaker 18 at some point in the future.
• FMComparison does not use the Database Design Report (DDR) XML. It uses the XML produced by the Tools —> Save a Copy as XML… menu item introduced in FileMaker 18.
• FMComparison compares single database files at a time. Claris has not yet implemented a multi-file XML export for the new XML format, and we have not introduced our own. If you need to compare multiple files, they can be run concurrently, but each will need to be run independently in its own window.
• I fully anticipate releasing many updates in the coming weeks, so if you regularly have restricted internet access or no internet access, you may want to wait a while before getting involved in the beta. If you can’t regularly access the update server and the registration server, your experience may suffer.
• FMComparison likes screen real-estate. Blow that window up!

Using FMComparison

1. Export/gather XML from 2 versions of one of your FileMaker database files using the Tools —> Save a Copy as XML… menu item.
2. After FMComparison launches, you will be presented with an interface allowing you to select the original version and the modified version. Click the appropriate Select button for each.
   • FMComparison will warn you if you select the same file twice, or if you select 2 copies of the same file.
   • FMComparison will warn you if you select a more recent file as the Original file, but it will not stop the process. There are situations where you might want to do this, either because you exported the original xml after the modified xml, or if you are looking for a guide to rolling back a series of changes.
3. After both files have loaded, click Begin Comparison.
4. Once the comparison has completed, you can click View Comparison to review the results.
5. [MORE TO COME]

Philosophy of FMComparison

The diff tool in FMPerception looked at each edited property as a “change”. Unfortunately, this produced an excessively detailed report that was difficult to understand without dumping the data into something like FileMaker in order to isolate the kinds of changes you were most concerned about. Too many trees, not enough forest.

FMComparison looks at a FileMaker element (field, table, script, layout, etc) as the core unit of change. Any changed properties in an element will cause the element to be flagged as edited. Once you click on it, it itemizes the changes to just that element. Additionally, the ordering of elements relative to each other is isolated into special Organization categories, allowing us to isolate element changes specific to those made to that element itself. If changes to the order of scripts or layouts are not relevant to your process, you never have to look at them.

Whenever possible, FMComparison will use the UUID that Claris has added to the XML to associate elements across versions. However, when that leaves elements unlinked, FMComparison will fall back to element names and FileMaker IDs. In certain cases, depending upon your process, this might result in two completely independent elements being associated, appearing as a single edited element rather than one deleted element and one created element. Nine times out of ten, this will occur when the items have matching FileMaker IDs. Note that when this occurs, all the properties of both elements will still be available in the details display.

FMComparison is intended as companion tool to FMPerception. There are currently no plans to sell it independently of FMPerception.

Welcome to the birth of the FMPerception Suite!

Still On the Agenda

• Keyboard navigation – We’d like to add further key commands with the intention of allowing mouseless navigation of the comparison results.
• Full-Screen details – We hope to better support users with smaller displays by allowing users to view the Details column full-screen once an element has been selected.
• Suppressing unedited properties – We’d like the user to be able to show only the changed properties in the details, rather than all properties with the changed ones highlighted.
• Running only a portion of the diff – We hope to allow the user to indicate when they only care about changes to scripts, or layouts, or custom functions. This should hopefully result in faster comparison.
• Suppressing irrelevant changes – When you change the name of a field, FileMaker updates the definition of every element that references that field, and this causes the item to appear as “changed”. Our future intention is to make FMComparison be able to isolate these changes such that items changed only because another item was renamed will not appear as changes.
• Dark Mode – ‘Nuff said.
• …and lots of other cool stuff.

Still Having Problems?

If you’re having difficulty working with FMComparison, we’d very much like to hear from you. Bug reports, issues, and feature requests are all most welcome. The best way to get that information to us is via email at support@geistinteractive.com.

Filing Bugs:

• During beta, FMComparison creates a text file on the desktop called “FMComparison_Developer_Logging.txt”. Including this file will be extremely helpful, especially in cases of crashes.
• As we all know, detailed descriptions are helpful.
• Larger screenshots are best. Very often the context of exactly how you got there is more important than the thing that’s not showing properly.
• Whenever possible/appropriate, include a zipped copy of both XML files. Very often it takes longer to reproduce an issue than to fix the code.
• Thank you in advance to those of you who include video. 🙂