MirrorSync is a simple, elegant FileMaker synchronization product that connects FileMaker Server with FileMaker Pro and FileMaker Go. Users can sync the hosted file with their FMGo or Pro clients, go off network to make changes, and sync again when a connection is available.
Why use MirrorSync?
MirrorSync is designed to solve the problem of how to work productively on a hosted FileMaker database without being tied to FileMaker Server. If, for example, you have multiple users connecting to FileMaker Server over a wide area network (WAN) you could notice a substantial slowdown, as every change is immediately written back to FileMaker Server. MirrorSync allows each user to take a local copy of the database which would run on the users machine and not be affected by the WAN performance. The user could sync when they first came into the office, work on their local copy throughout the day, and sync at specified times (or on demand) to push and pull the latest data to the server.
Another use case would be users who work in the field and may have limited or no connectivity to the FileMaker server network. The user could take a local copy on their iPad or iPhone, input the information from the field, and then sync when they regain a network connection. If the connection is spotty, they could even specify a one-way sync where their information is pushed to the server, but no data is pulled down, thus speeding up the process.
|Please note that the latest Java 1.6 Update for Mac OS X Lion or higher breaks Java Web Start Functionality. For instructions on how to resolve this issue, click here.|
- Windows 2003r2 or later, or Mac OS X 10.5 or later
- FileMaker Server 11.0v3 or 12.
- Configuration utility:
- OS X 10.6 or later, or Windows 2007 with Java 1.6 or higher installed
- FileMaker Pro 11 or 12 (FileMaker Pro Advanced is recommended and reduces setup steps, but not required. If you do not have FileMaker Pro Advanced, read the FAQ on Is FileMaker Pro Advanced necessary for configuration?
- NOTE: This is only required for one machine on the network
- Sync Client:
- Mac or Windows with FileMaker Pro 11 or 12 OR
- FileMaker Go running on iPad, iPhone, or iPod Touch
MirrorSync With Hosting Providers
As of 1.25, MirrorSync supports hosting provider installations of MirrorSync.
The following companies have indicated that they are set up or willing to configure their servers to host MirrorSync. If you'd like to be added to this list, please contact us at email@example.com.
- ODI Technologies ( http://www.oditech.com/ )
- John May, Point in Space ( http://www.pointinspace.com/ )
- Andrew McCallum, Niche IT Pty Lty ( http://www.nicheit.com.au/ )
- Foxtail Technology ( http://www.foxtailtech.com/ )
- 360Works can also host your database with MirrorSync, so feel free to ask us about this service.
To install multiple instances of MirrorSync, choose either the Hosting provider option on Mac, or hold down ALT on a Windows computer. This will allow you to name a new instance of MirrorSync and install multiple copies. These copies can then be managed via the 360Admin utility, which is found either in your Program Files or Applications folder. When installing additional instances of the application, only a single Tomcat process will be installed which is shared by all of the MirrorSync instances.
We strongly recommend you use the installer, even for hosting providers. We at 360Works use the installer for our hosting clients as well, and find it easy to update and manage. If you are curious as to what the installer actually does, it modifies and adds the following:
- Creates a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows that is readable and writeable.
- Downloads and installs an instance of Tomcat 6 into that folder. (Only one copy of Tomcat is installed, regardless of how many copies of MirrorSync are running)
- Copies the installer's MirrorSync.war which deploys the web app, as well as the other supporting material into the folder.
- Adds a launch daemon in Library/LaunchDaemons in OS X, or creates a Windows Service to automatically start Tomcat.
- Modifies the http.conf file for Apache to allow for URL redirection. If using Windows with IIS, we create an ISAPI filter for the URL redirect.
- Copies a lightweight Admin Utility JAR file to manage Tomcat to either Program Files/360Works or Applications.
If upgrading from an older version of MirrorSync, we'll copy over the SyncData and remove the URL redirects for the old MirrorSync.
If you prefer MirrorSync to be deployed to your own instance of Tomcat that you've set up, please note and follow these instructions:
- Create a folder at '/Library/360Works' on Mac or 'C:\Program Files\360Works' on Windows. Make sure that it is readable and writeable to the process that Tomcat is running as.
- Rename the MirrorSync.war file to whatever name you'd like the instance to run as for your hosting customer, ie. 'CustomerXSync.war'
- Drop that file into the webapps directory in your Tomcat instance.
- Modify the the MirrorSync.xml context descriptor and set the administrative username and password for MirrorSync. In Tomcat 6, this file is automatically written to the Tomcat/conf/Catalina/localhost. If you are running Tomcat 7, the file is located in the webapps/MirrorSync/META-INF/context.xml file, or you can follow the instructions at http://tomcat.apache.org/tomcat-7.0-doc/config/host.html regarding copyXML to get the same behavior as Tomcat 6 (we recommend doing this, so that you don't lose the context.xml file every time the application is redeployed).
- If necessary for your configuration, set up URL forwarding from IIS / Apache to your Tomcat connectors. See tomcat documentation on how to do this.
Important MirrorSync Information
Before moving further in MirrorSync, there are a few important points you need to know about. MirrorSync is a web application, accessed on client machines through a FileMaker Web Viewer. MirrorSync communicates to FileMaker Web Publishing Engine using XML to push and pull data to FileMaker Server. To configure and run MirrorSync, follow the instructions in the configuration utility to modify the hosted copy of the database you wish to sync. User will then download local copies of the hosted database and run the MirrorSync script to sync the local copy to their devices and the server.
Distributing files is easy. You can either download a copy of the file from FileMaker Server, or MirrorSync, or create a download link. The download link is available to users of version 1.5 and above, and can create a revocable link to download a copy directly to a mobile device or computer. Click Download Database, and choose Create Link. Once you've downloaded the local database, you can make copies of this file, email the file, and use DropBox to distribute the offline copy to other users, iPads, and iPhones. When distributing copies, MAKE SURE to not run the sync script in the database! Once the sync script is run for the first time, the database is linked to your device's MAC address. Using a previously synced file on devices with different MAC addresses will result in errors. To get a copy of the file that is not linked to any device, simply navigate to your MirrorSync server address, login to the main screen, and choose "Download Database". You'll download a new copy that you can then email to other devices. You can also simply revisit the download link provided.
After distribution, it is very important that you run the MirrorSync script before making any changes. This links the local copy to your device and ensures that you have the most recent information from the hosted database. During the initial sync, information from the hosted database takes precedence, so any changes you've made will be reverted.
Devices cannot sync simultaneously. If a user gets a "Sync in Progress" message, they will need to try again in a few seconds to allow the first sync to finish.
Preparing your database for use with MirrorSync
MirrorSync only supports sync with a single-file database, so if you have multiple files, create a new table with external table references to the other files.
Be sure that XML extended privilege is enabled in FileMaker Pro. Choose this option under File > Manage > Security… Double click the FileMaker user, and choose Edit… from the Privilege Set.
Make sure the Access via XML Web Publishing option is enabled and has a checkmark. Please note that this screen is different in FileMaker 12.
Most tables that you would like to synchronize need to have a unique identifier, also known as a primary key. This can either be a sequential serial number, a universally unique identifier (UUID) generated with the new FileMaker 12 Get(UUID) function, or any other value that is guaranteed to be unique, non-empty, and unchanging for every record. If you are using UUID primary keys, it is important that you do NOT check the box prohibiting modification of these values -- for serial numbers this is irrelevant and syncs will work either way. The exception for this requirement is many-to-many join tables, which often do not have a primary key, and instead have two foreign keys linking them to primary keys in other tables. It is OK if these tables do not have primary keys.
Every table (including join tables) must have a timestamp field which is set to auto-enter a modification timestamp.
You should create a new layout for each table that you plan on synchronizing. Be sure to include the modification timestamp, primary key, and any fields that you want to synchronize. Be sure to NOT include summary fields, global fields, and unstored calculations. These will make synchronization slower. These are easy to spot, because if you enable the 'View->Show->Quick Find' menu in FileMaker, those field types will either have a yellow magnifying glass, or no magnifying glass. Remove those fields from the layout, and keep the ones with the green magnifying glass.
MirrorSync checks with the initial sync which fields are read or writeable. If you have options selected that may prohibit writing to a field, MirrorSync may not be able to sync those fields appropriately. These options include "Prohibit modification of value during data entry" and "Validated by Calculation" under the options section for a field.
Please remove or rename fields that have parentheses ( ) or square brackets [ ] . These fields are incompatible with MirrorSync.
Host the database on FileMaker Server. Open the file as a guest with FileMaker Pro Advanced, using a full access account.
Configuring MirrorSync without FileMaker Pro Advanced
Steps to manually import MirrorSync tables in FileMaker Pro
- Locate the XML schema that came with your MirrorSync download.
- Open FileMaker Pro and navigate to File -> Import Records -> XML Data Source.
- In the "Specify XML and XSL Options" window, choose the "File" radio button, then click "Specify...".
- Navigate to your MirrorSync download folder and choose the MirrorSync.xml file from the XML Schema subfolder.
- Click continue to bring up the Import Field Mapping window.
- Open the "Target" drop down menu, and select "New Table ("MirrorSync")"
- Verify that the source fields and target fields have been matched correctly.
- Click import.
Steps to configure your new MirrorSync table
- Navigate to File -> Manage -> Database...
- Navigate to the "Fields" tab, highlight the "id" field and click the "Options..." button.
- Check the box next to "Serial Number." Set it to generate on creation.
- Check the box next to "Prohibit modification of value during data entry."
- Navigate to the "Validation" tab and check the boxes next to "Not Empty" and "Unique Value" then press OK.
- Next, highlight the "modstamp" field and click the "Options..." button.
- Check the box next to "Modification" and ensure that the drop down menu says "Timestamp (Date and Time)."
- Check the box next to "Prohibit modification of value during data entry."
- Navigate to the "Validation" tab and check the box next to "Not Empty" then press OK
- Finally, highlight the "container" field, and select "Container" from the "Type" drop down menu, next to the "Options..." button.
You are now finished manually configuring your MirrorSync table. Click the OK button to close the database management window, and return to the MirrorSync configuration. (Be sure to save your changes!)
MirrorSync Quick Start Tutorial: Syncing the Demo File
MirrorSync comes with a fully featured demo. You may use the demo for your own files, or walk through a sample configuration below. The only demo limitation is that once you have created an offline copy of the database, that particular copy can only sync for 24 hours. You can renew this 24 hour window at any time by downloading a new offline copy from the server.
MirrorSync ships with two example files: "Contact Management.fp7" and "Contact Management.fp12", along with a MirrorConfig.txt file. These files are copies of the Contact Management Starter Solution from FileMaker Pro 11. The only changes that have been made are the addition of the table generated by the MirrorSync Configuration Utility.
To use the demo file:
- Host the file on FileMaker Server
- Run the appropriate Mac Installer.app or Windows Installer.jar
- On the client machine, navigate to the URL provided at the end of the installation to download the MirrorSync utility. Be sure to match the capitalization of the word 'MirrorSync' in the URL.
- Run the configuration utility using the username and password you created during installation. From the starting screen, click import and choose the configuration file (MirrorConfig.txt) from your download.
- With the new configuration selected, click "Edit" from the main screen and proceed through the configuration utility. If using a three-machine FileMaker Server deployment, be sure to enter the host name of the web server. Otherwise, use 'localhost'. Be sure the "Contact Management" database that you hosted on FileMaker Server is selected, then click "Next" through the next six configuration screens. On the final screen, copy the scripts, layouts, and steps as indicated.
- Download the file and run the MirrorSync script. This is a local copy of the FileMaker file and is linked with your current machine during the initial sync. To sync this file with multiple devices, follow the steps below for a custom configuration.
MirrorSync Setup Tutorial: Custom Configurations
In this tutorial, we'll walk through a MirrorSync configuration from start to finish, using the Contact Management.fp7 FileMaker Starter Solution. If you are using FileMaker 12 and would like to follow along, you can download a converted file at http://mirrorsync.360works.com/static/Contact%20Management.zip
1) Prepare the file. This involves: - enabling the Access via XML Web Publishing extended privilege set in File > Manage > Security - ensuring that the database is contained in a single file - ensuring that each table has a primary key field, either with an auto-entered, unique serial number or UUID - ensuring that each table has a modification timestamp field, also set to auto-enter - creating a new "sync" layout for each base table (not table occurrence). The layout should only contain those fields that should be synched. This means no global fields, summary fields, or unstored calculations. If your solution has repeating fields, make sure to show all of the repetitions on the layout.
2) Host the file on your FileMaker Server and run the MirrorSync installer. If you have a multiple machine deployment, run the installer on the machine where the web publishing engine is running. Make note of the URL at the end of the installation process.
3) On your client machine, navigate to the MirrorSync URL and launch the MirrorSync Client. Follow the instructions in the configuration utility. This involves setting the primary keys and relationships, choosing the layouts to sync, confirming the fields, and inserting the table, script, and layout that MirrorSync generates. If you get stuck, look for the blue question marks - they have helpful tooltips.
4) During the final screen of the configuration, MirrorSync will generate a table, script, layout, and script steps for synching. Copy and paste these into the hosted database (if you don't have FileMaker Pro Advanced, you'll need to import the XML for the table). Once these changes are made, click finished.
5) From the MirrorSync Dashboard, choose the correct configuration and click "Download Database". This will download a copy of the database to your local machine. Keep in mind that after the initial sync this copy is tied to your device. If you would like to have the database on multiple devices, you'll need to navigate to the server address on that device, launch the client, and download the database directly, or download a fresh copy of the database and email it to the device.
6) Before making any local changes, run the MirrorSync script.
To sync changes to the server copy, simply run the MirrorSync script. This script is attached to the button on the MirrorSync layout, but users may choose to attach it to whatever is required. Be sure to sync once before making changes to assure that both copies are identical.
Please note: if the database has multiple access accounts with different privilege sets, make a new copy for each user. Do not sync an offline copy of the database to the server using multiple accounts.
After configuration, users can view information about current sync configurations. The left window displays all the current sync configurations. Users may Add new sync configurations, edit existing ones, duplicate, or delete them. If a sync with MirrorSync has been set up on another server, that configuration may be imported using the Import button.
If a sync configuration needs to be changed, there are a couple of things to keep in mind. Choose Edit… from the Main Screen and walk through the configuration again. After making the changes required, be sure to delete everything in the MirrorSync script first and then paste in the new script steps. After walking through the configuration utility, make a fresh copy of the database and run the MirrorSync script again.
The right window displays information about the currently selected sync and the option to run the sync script.
The bottom window displays the log for MirrorSync.
|Please note that the updating process is different for hosting providers. Please see this page for details.|
To update MirrorSync to a new version:
- Download the new version from the website
- Run the installer included in the download on the server
After installing the new version, users with copies of offline files will be able to continue syncing. Occasionally, the script steps or the table may change in new builds. To check if there are new scripts to run, choose edit from the Main Screen. Keep pressing Next until you get to the final screen, where you copied the layouts, tables, and scripts into the hosted file. If there is an exclamation mark next to a step, hover over it and read the tooltip. You may need to replace the scripts in your solution to take advantage of a new feature, or to solve an issue in an older version.
Remember, users with older offline files will be able to continue syncing. But to take advantage of the update, simply recopy the elements as directed on the screen and redistribute the offline files. There is no need to delete the configuration.
If there are issues after upgrading, try restarting the Web Publishing Engine.
Frequently Asked Questions
Deployment and installation questions
Q: How should MirrorSync be installed?
A: Run either the Mac Installer.pkg or the WindowsInstaller.exe to install the MirrorSync application on the server. Your server can be separate from the Web Publishing Engine, beginning with version 1.5, but must have a Web Server such as IIS or Apache.
After installation is finished, a message will be displayed pointing to the address where MirrorSync can be configured. Typically the address will display as http://servername/MirrorSync, where servername is replaced with the address of the server. Please keep in mind that the address requires the correct capitalization. From a client computer, navigate to that address to launch the configuration utility.
Q: How do I upgrade MirrorSync to a new version?
To upgrade to a new version, run the new install file (Mac Installer.pkg or WindowsInstaller.exe) and select Upgrade.
Q: Are plug-ins required?
A: No, the only software to install anywhere is the MirrorSync server application, which is installed on the FileMaker Web Publishing Engine. You can send a copy of the FileMaker database to anybody with a copy of FileMaker Pro, and they will be able to run the sync script.
Q: Does MirrorSync work on SSL enabled FMS
A: Yes. For SSL support, choose the appropriate checkbox when selecting a database in the configuration utility. If you get an error saying that you have a self-signed certificate, then you will need to follow the Custom SSL Certificate setup instructions.
Q: What ports are required for MirrorSync? Can I change them?
MirrorSync transmits container data on port 5003, which is the regular port for communication betwen FileMaker Pro and FileMaker Server. All other field types (text, number, date, time, timestamp) are transmitted using regular HTTP communication, which typically runs on port 80, or port 443 if SSL encryption is being used. These port numbers are set in your web server configuration (IIS on Windows or Apache on OS X), and can be customized to any value you prefer. A good way to test this is to test the FileMaker Web Publishing Engine - if the URL http://yourServer:somePort/fmi/iwp works for you, then it should work for MirrorSync as well.
Q: Will MirrorSync work on a VPN?
Yes. MirrorSync runs over standard HTTP protocols (which are VPN compatible) for non-container data, and standard FileMaker protocols (which are also VPN compatible) for container data.
Q: My solution is behind a firewall. Will MirrorSync still work?
A: MirrorSync communicates with FileMaker Server using a web viewer, so as long as the firewall allows standard HTTP traffic on port 80 (most firewalls are configured to allow this), all of your sync devices should be able to access it through the firewall.
Q: Can MirrorSync sync between two FileMaker Servers?
A: No, MirrorSync depends on web viewers and scripts steps that are only available in regular FileMaker Pro. You can sync between FileMaker Pro and FileMaker Server, but not between FileMaker Server and FileMaker Server. If this feature is important for you, please e-mail us and let us know: firstname.lastname@example.org
Q: Does MirrorSync work with runtime versions of FileMaker Pro?
A: MirrorSync is untested and unsupported for use in this configuration. In addition, the legal licensing agreement for creating runtime versions of FileMaker specifically disallows any automated transfer of data between the runtime version and FileMaker Server. This restriction means that no sync process can legally be used to transfer data between the runtime edition and FileMaker Server, whether that is from a 3rd party or a home-grown automation process. Contact your FileMaker Business Account Manager for volume pricing on FileMaker Pro licenses.
Q: I have a three-machine FileMaker Server deployment. How do I install MirrorSync?
A: While MirrorSync can be installed on whatever machine is most convenient, we recommend that you install MirrorSync in the same location as FileMaker Server, as that will enable the Download Database functionality in MirrorSync. Please keep in mind you can always download the most recent version of the file via the FileMaker Server Admin Console. If that machine does not have a Web Server installed, such as Apache or IIS, your MirrorSync URL will be a direct URL such as http://360works.com:42424/MirrorSync.
Q: Does MirrorSync support ESS tables?
A: Yes! To use MirrorSync with ESS tables, there are additional steps. First, configure MirrorSync in its entirety. You should be able to select your ESS tables and files in the configuration utility. After you have pasted the last script step, download a copy of the file as usual.
At this point, you need to make some modifications for the file to work offline. Open the downloaded copy, and make the following modifications to the local copy ONLY! Do not run the sync yet.
- First, delete the data source. This is vital to preventing duplicate records and other artifacts of using ESS. Open File > Manage > External Data Sources and delete the OBDC data source.
- Next, open the File > Manage > Database and navigate to the Tables tab. Copy any ESS tables. Then delete them. Make sure NOT to delete the table occurrences. After all the italicized tables are gone, paste the tables back in. This ensures they are local FileMaker files, not references to external data.
- Make sure the primary keys and modification timestamps are correct. The primary key needs to be an auto-entered serial number or generated UUID.
- Open the relationships tab in the File > Manage > Database and relink any missing tables.
You can now distribute this file for synchronization to your users. Make a copy of this file and send it to each user who needs a copy. These copies are then ready for synchronization.
Q: How do I uninstall MirrorSync?
A: To uninstall, first stop the Web Publishing Engine. After that, run the original install file (Mac Installer.app or WindowsInstaller.exe) and select Uninstall.
Q: What if I move servers, change my hostname, or IP?
A: To move a MirrorSync installation:
- First, export your settings by opening MirrorSync and pressing Export for each configuration. This will save each configuration's settings in a simple text file.
- Next, you may uninstall MirrorSync off the server. This will clear the license information and prevent users from syncing to the old server.
- After moving the FileMaker file to the new server, install MirrorSync at the new location and enter your license information. You can them Import your configurations back in.
Please note! After moving servers, changing your server's hostname, or IP address, you will need to edit the data sources in the FileMaker file. To do this, open the file on the server and choose File> Manage > External Data Sources and clear out any MirrorSync data sources. Walk through the configurations in MirrorSync again, and repaste the script steps, which will create new data sources with the information provided during setup. Distribute new copies of this correct file to all users, as older versions will not sync.
You will only need to do this if you need to change the addresses you provided MirrorSync previously. For example, if you made a configuration that pointed to MacMini.local, and never provided an IP address, then there's no reason to walk through this process every time the IP address changed. However, if you specified the internal and external IP addresses in MirrorSync, and those change, this process would be required.
Q: I tried to follow the configuration utility, but don't quite understand the process. Do you have a walkthrough somewhere?
A: There is a MirrorSync configuration walkthrough page that explains this in more detail.
Q: How do I configure synchronization for solutions with multiple database files?
A: MirrorSync will work fine with multi-file solutions. Whether you're using the separation model, migrated from an older version of FileMaker, or just prefer to split our your tables into separate files, we've got you covered. You will need to select one file as your main file. Make sure that the main file contains table occurrences from the other database files that you want to sync, and when the configuration screen instructs you to create layouts for each table, be sure to create the layouts in the main file.
When you complete the setup process and get to the step where you click the button to download an offline copy of the database from your server, select the option for a multi-file solution. This will show a checkboxes of all of the database files available on the server. Be sure to select all the database files in your solution.
Q: What happens if I edit my configuration, or make changes to the sync layouts on my hosted database?
A: If you change your configuration or edit your hosted database in a way that affects the sync layouts, then your need to go back through and edit the configuration and re-generate the sync script steps. Delete the current contents of the MirrorSync script and replace with the steps you just downloaded. Then send a copy of this new file to each offline user to replace their database.
Q: I configured my file in FM11 and everything worked great. I just converted it to FM12 and now it doesn't sync at all. What's going on?
A: After converting your file, you'll need to edit the configuration and replace the MirrorSync script steps with ones generated for the FileMaker 12 file. This is due to the fact that the "Insert from URL" script step doesn't exist in FileMaker Pro 11.
You'll also need to re-run the MirrorSync installer.
Q: Is FileMaker Pro Advanced completely necessary for configuration?
A: If you do not have a license for FileMaker Pro Advanced, you'll need to import the table data from the XML schema that came with your MirrorSync download.
Please see Configuring MirrorSync without FMP Advanced for detailed instructions.
Q: I never saw the foreign key mapping screen! What do I do?
A: If you selected UUIDs as your primary keys at the beginning of the configuration, the foreign key screens will not appear. This is normal and expected behavior. When using serial numbers, primary keys can be (and usually are) re-numbered when they are transferred to another device. MirrorSync needs to know which foreign keys which point to the primary keys, in order to write the new primary key value to each foreign key. When using UUIDs, the primary keys stay the same on every device because there is no possibility of conflict. Therefore, there is never a need to re-write foreign keys.
A: Make sure XML publishing is enabled for the account you are using in MirrorSync. Also be sure the database is accessible from the machine you are installing MirrorSync on.
Try to navigate to your server's URL, and adding
/fmi/xml/FMPXMLRESULT.xml?-dbnames to the end. You should see an XML document listing the databases in FileMaker Server. If you do not, or find a 404 or 401 error, then FileMaker Server may not be configured correctly.
If there is an authentication required at that test URL, try disabling IIS authentication. FileMaker Server authenticates its password-protected databases; however, this method disables the IIS authentication layer. This will also disable authentication for other websites that are using IIS on that server.
- From the Control panel, navigate to Administrative Tools > Internet Information Services (IIS) Manager
- Select the website in IIS and choose Action > Properties
- Navigate to the Directory Security pane, and select Edit for authentications. This button may differ in various Windows versions.
- In the Authentications Methods pop up:
- Make sure Anonymous Access is enabled
- For Authenticated access, disable the authentication methods.
- Press OK
Q: I keep getting a 102 Field is missing error, but I know my Sync layouts have all the right fields, what's wrong with it?
Please make sure that the sync layouts are matching in both the offline and server copy. If you have repeating fields, make sure the fields show the maximum number of repetitions that are defined in the field definitions. In other words, if a field can repeat 5 times, make sure the repetitions in the inspector show 5.
Q: Why can't I transfer my database to another computer after I've synced it?
A: The MirrorSync server stores information about each device that syncs with it. This includes the primary key, as well as the count of modifications for that record on that particular device. If this file were to be synced from two different devices, this information would conflict and cause problems. If you do try to send a database to another device and sync it, an error message will appear and the sync will be prevented.
Q: Can I log into my local copy with different accounts/different privilege sets?
A: No, you'll need to download a new copy of the database for each of the user accounts you use to the server using multiple accounts with the same file may generate errors.
Q: Does MirrorSync sync container fields?
A:Yes, MirrorSync works with FileMaker container fields as of version 1.1. If container fields are slowing down your synchronization, consider moving containers to a separate table and create new layouts for them. MirrorSync scans for modification timestamps to find records that have been changed, so by moving containers to a separate table with a separate timestamp, they are only uploaded and downloaded when containers change.
Q: What about SuperContainer? Does MirrorSync work with that?
A: Yes, it does. However, with SuperContainer the approach is very different. Only the URLs are synchronized, not the actual files - they remain on the SuperContainer server. The advantage is syncing is very fast - there is no binary data being transferred. The disadvantage is that you'll only have access to the files stored in SuperContainer when you have working network access from your computer or iOS device.
Q: Does MirrorSync sync external container fields?
A: Yes, MirrorSync works with external container fields. If you are using external container fields in FileMaker 12, there are a few steps after configuration that are required.
- Download a copy of the database from MirrorSync or FileMaker Admin
- Open the copy on a computer, and navigate to File > Save a copy as...
- Under the type drop down, choose "self-contained copy (single file)
This ensures the copy of the file embeds the containers into the file for easy use with FileMaker Go and offline functionality.
PLEASE NOTE: there is an unexpected behavior in FIleMaker in this process: when saving the self-contained copy, FileMaker updates the modification timestamp for every record that has an external stored container field. That's not a problem normally, but when used with MirrorSync, it will make the initial sync very slow. The reason behind the slow initial is due to MirrorSync assuming that all of those records have been modified on the client, so it writes all of the server data to the client (including the container data).
The workaround for this is to uncheck the modification timestamp auto-entry before saving the self-contained copy, and then turn it back on after the copy has been saved. This modification timestamp behavior has been reported to FileMaker, Inc. and will hopefully be resolved soon.
Q: Does MirrorSync do conflict resolution?
A:MirrorSync 1.2 introduced a choice of manual conflict resolution or automatic conflict resolution. If a user syncs their changes and a conflict arises, the user has an option of selecting either. Selecting manual conflict resolution will bring up an interface that highlights differences in the server and client copies. For each conflict, users can select which version of the record will win and MirrorSync will use that record. MirrorSync does not 'merge' changes - it will always pick one entire record as the winner of the conflict.
Previous versions of MirrorSync, and automatic conflict resolution keep track of which change was made last, and selects that as the winner in a conflict. So if a record is changed at 2PM on one device, and 3PM on another device, the 3PM change will win the conflict. The exception is that changes always win over deletions, regardless of which one happened last. A common misconception is that conflict resolution is based on who syncs first or last - MirrorSync will pick the record that was EDITED last, not the one that was SYNCED last. Again, MirrorSync does not 'merge' changes - it will always pick one entire record as the winner of the conflict.
Q: Is MirrorSync transactional? What happens if the connection is lost while syncing?
A: MirrorSync is not 'transactional' in the strictest sense. If the connection is dropped during a sync, it is possible for records from one table to be written to the server, while records from another related table may not be written. However, MirrorSync keeps track of which records have been written and which ones have not, and it will resume from where it was on the next sync and complete everything as if the first sync had finished. If a record on the server cannot be written because it is being edited, the offline user will get a warning error message telling them this. MirrorSync will continue to retry that edit operation each time the sync script is run.
Q: Can I use external authentication with MirrorSync?
A: Yes, MirrorSync supports externally authenticated accounts with no modifications. So long as the username on the local copy matches the username on the server, you can set up one password for local access and another for external authentication with the server. The passwords do not need to match between the local file and the hosted file.
Q: How do I make changes to my hosted database if I have offline users who are syncing? Can I add fields and tables?
A: MirrorSync will match your fields by name whenever you sync. What this means is that as long as you don't rename or delete fields, you can freely add additional tables and fields to your hosted database without causing problems for your users working with the older databases running offline. Don't forget to add new fields to your sync layouts. To distribute your updated version of the database to users, re-run the configuration process and select any new fields and tables to add to the sync configuration. Be sure to re-copy your script steps for the MirrorSync script. Then download a copy of the database from the server and send it to your users to get them the newest version. Users running the old version will be able to sync until they are ready to download the newest version of the file.
Primary key / serial numbers
Q: I'm running FileMaker 12, and my primary keys are UUIDs. When I try to sync I get errors. What's going on?
A: Make sure that if you are using UUIDs as primary keys, the "Prohibit Modification of these Values" box is unchecked in the specify field window. MirrorSync must be able to write to these fields.
Q: Do I need to change how my primary keys are generated?
A: No. MirrorSync does not require primary keys to be unique across devices. It will take care of keeping track of primary and foreign keys that are re-numbered when they are transferred to other devices.
Q: After a couple of syncs I noticed that the serial numbers on my records don't match on my iPad and my laptop. Is this a problem?
A: No, serial numbers are expected to be different between devices, because when a record is written from a mobile device to the server, another record may already exist with that same serial number. MirrorSync keeps track of which serial numbers are assigned to which records. For example, if the contact record 'Jesse Barnum' is ID #5 on your laptop, and the same record is #12 on the server, and the same record is #15 on your iPad, Then when a change to record #5 is written from your laptop to the server, MirrorSync knows to make the change to record #12. When you download the change on your iPad, MirrorSync knows to change record #15 on the iPad. It also updates all foreign keys that link to the primary key (this is why the foreign key mapping step is important in the setup process).
Q: What if I need to assign a user-friendly serial number to my records that stays the same when it is synced? For example, an invoice number?
As the previous FAQ points out, if you are using serial numbers for your primary keys, MirrorSync will renumber these serial numbers when it writes to another device to prevent number conflicts. However, this can be a problem for things like invoice numbers, that need to always be the same for all devices. This isn't really MirrorSync's "fault", because obviously if the devices are off-line from each other, there is no way to know what the next available serial number is if it might have been used by another off-line device.
Before talking about solutions to this problem, it's important to emphasize that this user-friendly number should NOT be what you use as a primary key in your database. Primary keys are internal database identifiers, and should not do double-duty as a user-readable value, so even if you are not using MirrorSync, you should have two fields in your table: One hidden field used as a primary key that the user never sees, and then a second user-visible serial number that users can refer to. With that in mind, here are two potential solutions to the problem:
1) Have a separate database file that is hosted on the server (not off-line) with a table that contains serial numbers. When you want to generate the next serial number, go to that online table, create a new record, and use that next serial number for your invoice number (or whatever user-visible field this is). Since this database is online, everybody shares it and nobody gets the same serial number. The downside of this is that you won't be able to create new records unless you have a network connection to the server, but the upside is that you can still get all of the speed benefits of working on your own offline copy of the database (since only the serial number table is hosted on the server).
2) Either use a prefix for each device (so that records created on machine 'ABC' would be numbered ABC1, ABC2, ABC3, while records created on machine 'DEF' would be numbered DEF1, DEF2, DEF3), or assign a serial number range to each device (so records created on 'ABC' would be numbered 10,001, 10,002, 10,003, and records from DEF would be numbered 20,001, 20,002, 20,003). The downside to this approach is that your user-visible number will be longer, and also that you need to customize the database slightly for each device (either by changing the next serial number or by setting the prefix).
If you'd like our assistance doing the integration and development for this, we'd be happy to help - please contact us for an estimate.
Q: Does the sync run any faster if you use UUIDs rather than serial numbers?
A: The choice of primary keys do not substantially affect the speed.
Q: How do I configure and use two foreign keys as a primary key?
A: In the configuration screen, use the drop down menus to select the two foreign keys.
Please keep in mind primary keys need to be unique. If using two foreign keys, there may be an instance where an error occurs about a duplicate node ID, since FileMaker is not validating the fields together and making sure they are always unique in a table. To avoid this, make sure:
- Ensure that the combination of two foreign keys only ever occurs once in the database.
- If you need to be able to have multiple join table records with the same foreign keys, add a regular serial number field to the join table and use that as the primary key, instead of the compound foreign keys.
Q: How fast is MirrorSync?
A: From a speed standpoint, there are three types of operations that MirrorSync does: 1) Initial sync, 2) syncing inserts and edits, and 3) syncing deletions. #1 and #3 are affected by the number of records in your database, but #2 is not.
For each sync, there is an overhead associated with sync that is typically 1/4 - 1/2 of a second per table on a local network. Therefore, if you sync 20 tables, expect about 5 or 10 seconds in addition to the actual time to sync the records. For iOS devices, this is more like 2-3 seconds per table.
For syncing inserts and edits, we find that 20 records per second going from server to client is a fairly typical benchmark. Therefore, if 100 records have been edited on the server, it should take about 5 seconds to sync these records to the client. This number will be higher or lower depending on how much information is stored in your records, and is more like 4 or 5 records per second for iOS devices.
Syncing inserts and edits from the client to the server is about 5 records per second for FileMaker Server 11, and 40 records per second for FileMaker Server 12.
Detecting deletions takes about 1 second per 1,000 records in your table. This can be time consuming if you have a large number of records. See the performance tips section below for tips on improving this.
Initial sync takes about the twice as long as deletion - 2 seconds per 1,000 records in the table. This only happens the first time that a user syncs with an offline copy of the database.
Q: How well does MirrorSync perform on slow networks?
A: MirrorSync is very efficient over slow networks, because it sends very little data other than the actual record changes, and it transmits this information in large chunks, which is more efficient. There are 2 HTTP request at the beginning of the sync, and usually 2 HTTP requests per table that contains any modifications. For example, if you have a 20 table solution, and there are only changes in 5 of the tables, it will usually take 12 HTTP requests (2 + 2*5) to complete the sync. By comparison, the FileMaker home page takes 65 HTTP requests to load in a web browser.
Q: I don't want to sync my entire database to my offline users. Can I just sync certain tables, fields, or records?
A: That's a three-part question with a three-part answer. Just syncing certain tables is very easy: When you're configuring the sync using the MirrorSync configuration utility, only include layouts corresponding to the tables that you want to sync.
Syncing certain fields is also very easy: Just don't include any fields on your sync layouts except the ones that you want to sync. You can also simply uncheck unwanted fields in the MirrorSync configuration utility.
Syncing certain records is only slightly less easy: Utilize the record level access privileges in FileMaker's security management dialog to create custom restrictions. For example, you can easily restrict each user to only see their own records by creating a calculated restriction that checks to see if Get(AccountName) is equal to a field with an Account Name auto-entry option. With a little creativity, you can set up similar restrictions to only sync records with certain statuses, or which fall in certain date ranges.
If you decide to use this technique to limit records based on access level privileges, you may choose to distribute an empty clone to your users instead of a full copy of the database. That way, the initial sync will only pull the records into their offline file that they have access privileges to on the database. Keep in mind that if they have access to many thousands of records, that could make the initial sync slower than if you distributed a full copy of the database that already contains all of the record data.
Q: How does MirrorSync work with restricted accounts?
MirrorSync requires a full access account only once: to paste in the table, scripts, and layout. After configuration, feel free to distribute copies of your file to restricted users. When MirrorSync does a sync, it logs in to the server copy as the user doing a sync, and won't be able to sync changes they don't have access to. See the above question for distributing empty clones, but please note the question above is more a guide on how to create these restricted accounts, and this question deals more with currently existing accounts.
WARNING: If you use a start up script that sets global variables which then determine access privileges, these privileges will not get set. The Web Publishing Engine in FileMaker does not run start up scripts, and so these globals won't be set when MirrorSync tries to write changes. A way to set up custom access instead would be to use the Get(AccountName), Get (AccountPrivilegeSetName) functions to determine access levels. This could avoid the start up script entirely.
Q: I don't want users to have to click on the dialog that comes up at the end of the sync, can I hide that?
A: Yes, set the global variable $$SILENT_MODE to "1" in your startup script. This will prevent MirrorSync from showing a dialog unless an error occurs.
Q: Can MirrorSync run automatically when my users finishes a job/invoice/widget? Can it run at startup?
A: Yes, absolutely. Remember that the MirrorSync script is a regular FileMaker script that can be set to run at any time by the developer. For example, if there is a critical section of your application that you want to avoid conflicts, trigger the sync when the user navigates to that screen, and again when they are finished editing in that screen. You could make it so that checking a box, clicking a button, or any other condition that you choose can trigger the sync to happen. If you'd like to incorporate MirrorSync into your startup script, but you only want it to run the first time that user opens an offline file, you can switch to the MirrorSync table and do a search for any record that has a value in the 'lastClientToken' field. If there is at least one record matching the search, then this file has been synced before.
Q: Can MirrorSync run automatically every x seconds/minutes?
A: Yes, you can use an On Timer script to trigger this. However, keep in mind that when the script runs, it commits the current record and pops open a new window that could be open for a few seconds or longer. This could get annoying if it happens in the middle of something that the user is working on. For this reason, we recommend the approach in the previous FAQ entry of linking your script sync operations to some user-initiated action. The exception to this is unattended computers - if you want to have a computer that is running MirrorSync all the time for purposes of having an extra copy of the database replicated, without a user working on it, then by all means go ahead and use an On Timer script step (and be sure to see the FAQ above about disabling dialogs).
Q: I have users in different time zones. Does MirrorSync account for that?
A: Yes. When an offline client syncs with the server, one of the first pieces of information it sends to the client is the client's current time. The server compares this to its own clock to see how different the client is (whether from being in a different time zone or just the client's clock being wrong), and then it applies this offset amount to all the timestamps it receives from the client for writing modification timestamps and resolving conflicts.
For online users connecting directly to the server, this offset cannot be calculated. Therefore, it is possible that online users in a different time zone, or whose clock is incorrect by more than 10 minutes (MirrorSync automatically includes a 10 minute "overlap"), could have their modifications missed by the sync process. To solve this problem, we recommend adding a new field, called something like 'Host modification timestamp', in addition to a regular modification timestamp field. Set the field type to 'Timestamp', and configure this auto-entered calculation:
Evaluate ( "Get ( CurrentHostTimeStamp )"; Modification timestamp ) //Change modification timestamp to be whatever the name of your modification timestamp field is
Be SURE to uncheck the box titled 'Do not replace existing value of field (if any)'.
Repeat this step for every table. This Host modification timestamp should now be configured as the modification timestamp for MirrorSync.
Q: My file is very large, and I want to give MirrorSync more memory allocation. How do I give Tomcat more memory?
A: For some users, they may find that the default memory allocation is insufficient to transmit large amounts of data. To allocate more memory to Tomcat, modify the catalina.bat (for Win) or catalina.sh (for Mac) file in the Tomcat directory. To find that directory:
- For FileMaker 11:
- FileMaker Server/Web Publishing/publishing-engine/cwpe-tomcat/bin/
- For FileMaker 12:
- FileMaker Server/Web Publishing/publishing-engine/jwpc-tomcat/bin/
Open the catalina.bat (for Win) or catalina.sh (for Mac), and find the following lines:
# FileMaker Server CWPE Tomcat Settings CATALINA_HOME="../../../../Common/Tomcat" CATALINA_BASE=".." JAVA_OPTS="-server -d32 -Xmx512M -DFMS.COMPONENT=cwpe -Dcom.prosc.devmode=true"
You can then change the -Xmx512M parameter to -Xmx1024M, which will double the memory available.
Q: I want to sync very large containers and data. How can I increase the timeout limits?
A: As of MirrorSync 1.4301, you can configure MirrorSync to override the default timeout values. To do so, you must find and modify the MirrorSync configuration XML file:
Open this file with a text editor, and find the lines below. You can then modify these values to your own specifications.
<Parameter name="clientSecondsPerInsertion" value="1.5" /> <!--2 records every 3 seconds for non-container inserts--> <Parameter name="clientSecondsPerContainerInsertion" value="15" /> <!--1 record every 15 seconds if we're inserting containers--> <Parameter name="clientSecondsPerUpdate" value="5" /> <!--1 record every 5 seconds for normal updates--> <Parameter name="clientSecondsPerContainerUpdate" value="15" /> <!--1 record every 15 seconds for updating containers--> <Parameter name="clientSecondsPerDeletion" value="1" /> <!--1 record per second for deletions--> <Parameter name="clientSecondsPerFetchRecord" value=".1" /> <!--10 records per seconds for getting changes records from client--> <Parameter name="clientSecondsPerContainerFetchRecord" value="10" /> <!--1 record per 10 seconds for getting records from client that have one or more container fields--> <Parameter name="clientSecondsPerFetchHeader" value=".03" /> <!--33 headers per seconds for just fetching primary key and modification timestamp (no record data)-->
Is MirrorSync included in the 360Works Portfolio Bundle?
Q: Is MirrorSync included in the 360Works Portfolio Bundle?
A: Yes, the Portfolio Bundle (http://360works.com/portfolio) includes MirrorSync. This is the same license as if it were purchased separately - up to 10 devices and 2 FileMaker solutions.
Q: From a licensing standpoint, what is a 'solution'?
A: From a business standpoint, a solution is one or more FileMaker database files that are integrated together for the purpose of meeting a particular business need. From a technical standpoint, there must be a single FileMaker file that contains external table occurrences in its relationship graph pointing to tables stored in other FileMaker data files. To be considered a single solution for purposes of MirrorSync licensing, a file must satisfy both the business and technical requirement.
Q: Is there an unlimited device license for MirrorSync? What about for vertical market solutions?
A: No, we do not offer an unlimited device license for MirrorSync. The same applies for vertical market solutions. For vertical market applications, we recommend that you pre-integrate your solution with MirrorSync, using the demo version of MirrorSync. Then tell your customers that if they would like to enable the offline sync feature, they can purchase MirrorSync separately, with no development work required. All that is needed is to install the MirrorSync software on their server, enter the license key using the admin utility, and customize the FileMaker sync script with the IP address of their MirrorSync server (this can be stored in a settings table, so that it doesn't have to be customized for each client / device).
Q: Is MirrorSync localized into any non-English languages? Does it work in other languages?
A: At this time, MirrorSync is only localized to English. Our current focus is on adding features, but we anticipate translating this into other languages when the product is more mature. If you would like to offer help with translation, please contact email@example.com to let us know. You should still be able to add MirrorSync to your solution in other languages, although we have discovered that copying and pasting the script steps does not work with other languages active - you must switch to English for this step of the configuration, and then you can switch back. Do so by editing your preferences in FileMaker Pro and selecting English in Windows, or by opening System Preferences in Mac, choosing English, and restarting FMP.
Q: I only have an offline copy of my file left, and need to upload it back to the server. What do I do?
A: Please note that this is an unsupported use of the offline file. But if necessary, users can reupload an offline copy of the file to FileMaker Server and use it with MirrorSync. Users will need to remove the "Client" record in the MirrorSync table, and keep only the "Server" record. Navigate to the MirrorSync layout, open the Debugging tab, and perform a find for "Server" in the type field. Select the inverse of the records found by pressing the pie icon in the status bar. Then, delete those other records.
Performance / speed optimization tips
Limit fields on the sync layout
It's a good idea to remove unnecessary fields on your sync layouts. Unstored calculations, summary fields, and related fields can cause significant slowdowns and are not synced anyway, so they should definitely be removed from the layout. Global fields and stored calculations do not affect speed as much, but they are not used for sync either so it's best to remove them if speed is important.
Move container fields into their own separate table
When MirrorSync checks if a record has been modified, it looks at the modification timestamp. If a record has been changed, it downloads the entire record, including container fields, every time. By moving container fields off the regular sync layouts, MirrorSync will only download and upload containers when they have actually changed. To implement this optimization, create a new table that is used only to store the container fields. Put your containers fields in that table, and add a primary key and modification timestamp. Be sure to import all the actual container data from the old table to the new one. Then, take the containers off your current sync layouts (if you have already configured MirrorSync), and create a new layout for the container table. Be sure to re-run the MirrorSync configuration utility so that it knows about the new layout.
Create layouts with just the ID and the modification timestamp
FileMaker 11 transmits data differently than FileMaker 12 to MirrorSync. This technique doesn't have any effect with FileMaker 12, but it may make the initial synchronization as well as deletion scanning much faster for FileMaker 11 tables with more than 1,000 records. For each Sync layout, create a new layout with the suffix _small. For example, you may have a table called Contacts. When you set up MirrorSync, you'd make SyncContacts. Now create another layout called SyncContacts_small. On this layout, place the primary key and modification timestamp ONLY. MirrorSync will automatically detect this layout and quickly scan for modification timestamps and records to add and delete. There is no need to rerun the configuration utility or script steps with this option.
Flag records instead of deleting them
If you want to optimize performance here, it might make more sense to flag records as being deleted instead of actually deleting them. That makes it into an edit operation, which is not affected by the number of records in the table.
The maximum number of users are currently using this copy of FileMaker Pro
There is a small bug in FileMaker Pro and FileMaker Pro Advanced that may occur when pasting the MirrorSync script, or editing the MirrorSync script. This occurs due to the references found in the script, which will reference both the internal and external IP address. FileMaker then opens both those references, which triggers the licensing server as two copies of FileMaker Pro. This error would occur for any script that contains both references to a single hosted file.
There are three work arounds for this:
- Upgrade your single user license to a volume license. You can contact FileMaker directly to upgrade your license if you have 5 or more copies.
- Change your Data Sources to list the internal address first in both MirrorSync scripts. You should have either the data sources listing one IP each, or two data sources with two IP addresses. Either way, make sure that both have the internal address listed first, and then for the External source list the external IP in a second line. This will only call the internal IP references when opening the script, but will slow down syncs significantly. It will now try the internal IP address first, and if it unavailable, time out and then try the external address.
- Paste the script and let FileMaker crash. The script will save appropriately. You will not need to modify the script after the initial configuration, so it should work correctly. If an update is released that requires changes to the script, be aware that any sync buttons or references to the MirrorSync script will have to be corrected on updates.
If you require assistance on this issue, please let us know.
The operation couldn’t be completed. (OSStatus error -67049.)
Apple's new Mountain Lion feature, Gatekeeper, prevents software from being installed outside the Mac App Store. However, you should be able to override Gatekeeper settings with right or control click. This way of getting around Gatekeeper does not always work correctly, and may result in the error message, "The operation couldn't be completed. (OSStatus error -67049)" To continue with MirrorSync or any other non App Store application, disable Gatekeeper completely in your System Preferences, perform the installation, and reenable once finished.
As of MirrorSync 1.5, the installer has been completely rewritten and no longer encounters the issues with Gatekeeper's right or control click.
Error from server: java.lang.IllegalArgumentException: Invalid date value (XXXXXXXXX)
This error occurs when invalid timestamps are being used in timestamp fields. This could be due to legacy timestamps that were previously stored in text fields and then converted to timestamp fields. FileMaker will retain the preexisting data in the field, but will not allow new invalid data to be entered.
The solution to this problem is to convert the existing invalid timestamps to equivalent timestamps in the correct format (MM/DD/YYYY HH:MM:SS). For example, if the contents of your timestamp fields appear like this YYYY-MM-DD HH:MM:SS you would isolate the found set of all records with invalid timestamps, and perform a Replace Field Contents operation with this code as the calculated result:
- Let ( [
- var.ts = Table::TimestampField ;
- var.year = Left ( var.ts ; 4 ) ;
- var.month = Middle ( var.ts ; 6 ; 2 ) ;
- var.day = Middle ( var.ts ; 9 ; 2 ) ;
- var.date = Date ( var.month ; var.day ; var.year ) ;
- var.time = Trim ( Middle ( var.ts ; 11 ; 100 ) )
- Timestamp ( var.date ; GetAsTime ( var.time ) )
This code only works for invalid timestamps in one specific format (YYYY-MM-DD HH:MM:SS), but with only slight modification, it could be made to work with many different invalid timestamp formats.
More Help Sources
If you still need help, there are several resources available! FMForums hosts a support forum for MirrorSync. Please look through the posts and see if your question has been posted before making a new topic.
Support is also available via email at firstname.lastname@example.org. You can also call us at 770-234-9293.
We're confident you'll be able to configure MirrorSync quickly and easily. However, if you want to have us integrate MirrorSync your solution for you, it will take approximately an hour at our rate of $165. We'll take a look at your files first, and if the integration will take more than an hour we'll contact you. Contact us to learn more and get started!