MirrorSync basic setup

From 360Works Product Documentation Wiki
Jump to navigation Jump to search

Upgrading from MirrorSync 2? Be sure to first read this important note on Updating from MirrorSync 2 to 3



Overview

MirrorSync is an elegant synchronization product that can sync between any combination of FileMaker Pro, FileMaker Go, FileMaker Server, SQL database (MySQL, Oracle, SQL Server, or any database that supports JDBC), Salesforce, and Amazon RedShift. For mobile devices, 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. For servers, MirrorSync allows a database to run in multiple locations, or to integrate different databases and make sure that changes to each server are reflected in the other server.

MirrorSync is only installed on the server computer. It is not a plug-in, and does not require any software installation on client devices.

MirrorSync is extremely easy to set up. The only required database changes are:

  1. Enabling the FMXML and FMXDBC extended privileges in your security configuration
  2. Making sure that every table you want to sync has a primary key, modification timestamp, and creation timestamp.
  3. Creating a layout for each table.
  4. Four copy and paste operations.

For FileMaker Server 17 Refer to this page for how to enable your XML Web Publishing Engine Enable_XML_FileMaker_17

@360Works on Twitter

Why use MirrorSync?

  1. For mobile users who access the database with FileMaker Go on their iOS device, MirrorSync allows these users to work efficiently with limited or no connectivity to the server network. Each user can take a local copy on their iPad or iPhone, input the information from the field, and then sync when they regain a network connection. Depending on their workflow, they could even specify a one-way sync where their information is pushed to the server, but no data is pulled down, or vice versa for users who need fast read-only information.
  2. For remote users who work on laptops, MirrorSync solves the problem of how to work productively on a hosted FileMaker database, regardless of network speed. 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 user's 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.
  3. For groups of users at multiple locations, MirrorSync should be used in server-to-server mode, where an identical copy of the database is installed on FileMaker Server in each location. Each workgroup works at full LAN speed on their own FileMaker Server, and MirrorSync takes care of keeping the servers in sync with each other, so that each workgroup can see and edit changes made by the other group. In this configuration, MirrorSync should be set to sync very often, such as every 30-60 seconds.
  4. To maximize performance and reliability, MirrorSync can be used in a clustering configuration, where two or more servers are running at the same data center and synchronized so that they all contain the same set of data. This means that each server only needs to work with 1/2 or less of the total users, and if one server goes down, the other server can take over the entire workload seamlessly. For a video demo of this, see https://www.youtube.com/watch?v=bQlGHrNtHCg
  5. For integration with non-FileMaker databases, MirrorSync is the simplest and most efficient way to accomplish this. For instance, if you have an online storefront running with MySQL or Oracle at a remote data center, but you need to have instant access to all of the orders in a database running on FileMaker Server, MirrorSync can selectively sync certain SQL tables to FileMaker, even if the table and field names do not match. In this configuration, MirrorSync should be set to sync fairly often, such as every 5-10 minutes.

Requirements

  • Server:
    • Windows 2003r2 or later / Mac OS X 10.6 or later / Linux running Tomcat 6 or 7.052 or later.
    • FileMaker Server 10.0v2, 11.0v3, 12 or later (tested with 13, 14, and 15), with XML Web Publishing enabled OR FileMaker Cloud (See special instructions for syncing with FileMaker Cloud)
    • 3 gigabytes or more of RAM. 8 gigabytes or more are recommended for large databases with hundreds of thousands of rows, or for more than 10 simultaneous sync operations.
  • Configuration utility (only run by developer / administrator):
  • Sync Client:
    • Mac or Windows with FileMaker Pro 10 or later OR
    • FileMaker Go (any version) running on iPad, iPhone, or iPod Touch

MirrorSync With Hosting Providers

MirrorSync supports hosting provider installations of MirrorSync.

If you would like for 360Works to host your FileMaker databases with MirrorSync, please contact us directly about this service.

Here is a complete list of companies that 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 plugins@360works.com.

The following companies support MirrorSync, but only in dedicated (not shared) configurations:

If you are a hosting provider, read the Installation for hosting providers' section in the advanced documentation page.

Technical overview

MirrorSync is a web application, installed on a server (typically on FileMaker Server) and accessed on client machines using the Insert from URL script step. MirrorSync communicates with FileMaker Server using either JDBC or the XML Web Publishing Engine (selected during configuration).

For FileMaker Pro/Go sync, users run the sync by triggering a regular FileMaker Script in the solution. For server-to-server sync, the syncs are run using the MirrorSync admin utility, and can be scheduled to run in the background at regular intervals. In MirrorSync 3, server-to-server syncs can also be triggered from a client connected as a guest of FileMaker Server by running the MirrorSync script.

There are no plug-ins or other software to install on user's devices.

Three ways to get started with MirrorSync

We've setup three ways for you to try MirrorSync:

  1. Live demo (time to sync: Less than 1 minute): If you would like to see MirrorSync in action without even needing to install anything, you can download our live MirrorSync demo database by clicking the yellow button titled 'Try live demo now' from the main MirrorSync page. Just open the file in FileMaker Pro or Go, make some changes, and then hit the sync button. To see how MirrorSync works between multiple devices, use that same download URL on a different device and sync away! Be aware that the data in this file is shared with everybody who downloads it, and also that it resets every night at midnight EST, so don't put anything important in this file.
  2. Sync using the Tasks template (time to sync: Approximately 20 minutes): Using the tasks starter solution that comes with FileMaker Pro, we provide a step-by-step video walkthrough that you can follow along with. This 13 minute video starts with creating a new FileMaker database and goes through setup and sync. Just watch the video for each step, and pause while you do it on your own file. Watch the video on YouTube.
  3. Configure your own file for syncing (time to sync: 30-60 minutes for most solutions): Follow the instructions below to configure MirrorSync with your own FileMaker solution.

Installing / upgrading

MirrorSync has a standard OS X and Windows installer included with it. Just double-click the installer for your platform and follow the instructions. Be aware that if you re-install FileMaker Server at some point in the future, you may need to re-run the MirrorSync installer in order to set the web server settings correctly. If you are running into other issues during installation, please go over our troubleshooting steps here.

If you are upgrading from MirrorSync 1 or 2, be sure to first read this important note on Updating from MirrorSync 2 to 3

Preparing your database for use with MirrorSync

  • If you have a multi-file solution (ie. separation model or migrated from older FileMaker version), make sure that there is a single main file with external table occurrences referencing the other files. If you are using a separation model, this should be the data file. When you distribute offline files to your users, you will distribute the entire set of files, which will include the main sync file.
  • Be sure that the FMXML and FMXDBC extended privileges are enabled in FileMaker Pro for all accounts that will use MirrorSync. Choose this option under File > Manage > Security… Double click the FileMaker user, and choose Edit… from the Privilege Set.
  • Make sure that every table in your solution has a primary key. This is a unique identifier which cannot be empty, and should never be changed once the record is created. MirrorSync can work with traditional serial number primary keys, UUID primary keys, or custom primary key strategies. It will save steps during setup (but it's not required) for your primary keys to have the 'not empty' and 'unique' validation option enabled. We recommend, but do not require, that you set primary key validation to happen 'always' and do not allow user overrides. For a deeper discussion of how primary keys are handled when syncing, refer to 'Primary key considerations' in the advanced documentation. Do NOT create new primary keys for use with MirrorSync, unless you have tables that do not already have primary keys (read the 'primary key considerations' link for an explanation)
  • If you are using UUID primary keys, be sure to UNCHECK the field options checkboxes that say 'Do not replace existing value of field' and 'Prohibit modification of value during data entry'. Enable the 'Unique value' validation option.
  • If your solution uses serial numbers as user-visible data for things like job numbers, check numbers, P.O. numbers, or invoice numbers, refer to the section 'User-visible serial numbers' in the advanced documentation.
  • Every table (including join tables) must have a timestamp field which is set to auto-enter a modification timestamp, as well as a creation timestamp field which auto-enters the creation timestamp. If you will have users with direct, online access to FileMaker Server who are not in the same time zone as the FileMaker Server, you will need to set up special host modification timestamps as outlined in the 'Time zone considerations' section of the advanced documentation. This requirement does not apply to offline users in different time zones, who access the server via MirrorSync.
  • Please remove or rename fields that have parentheses ( ) or square brackets [ ] in the name. These fields are incompatible with MirrorSync.
  • Host the database on FileMaker Server. Open the file from the server with FileMaker Pro Advanced, using a full access account. If you do not have FileMaker Pro Advanced, refer to the 'Configuration without FileMaker Pro Advanced' section in the advanced documentation.

Integrating MirrorSync into your solution

Here are the steps to integrate MirrorSync into your solution:

  1. Install MirrorSync. You can install MirrorSync on any Mac, Windows, or Linux computer, whether or not it is running FileMaker Server. During installation, you will create a username and password that will be used to administer MirrorSync. If you choose to install MirrorSync on a computer other than your FileMaker Server, you will need to also install an extra copy of MirrorSync on your FileMaker Server if you want to use the 'download link' feature for easy distribute to offline users.
  2. After installation, you will be taken to the MirrorSync home page. This is located at http://yourServerAddress/MirrorSync, or in some cases, http://yourServerAddress:42424/MirrorSync. Keep in mind that you can open this page and proceed with the rest of the integration process from your own computer - you don't need to remote desktop to the computer where MirrorSync is installed. From the home page, click the blue 'Launch MirrorSync Client' button. If you are using Mac OS X, you will then need to double-click the downloaded JNLP file.
  3. Use the username and password you created during installation to log in to the config client, and then follow the setup instructions in the config client.
  4. After completing the setup, if you will be syncing with FileMaker Pro or Go, you will need to distribute offline copies of your solution to your users. Click the 'Download Database' button in the config client and choose either 'Download' for quick testing on your own computer, or 'Create Link' for deployment to end users.
  5. Once you have created an offline copy, run the 'MirrorSync' script to do the initial sync, and then run it again whenever you want to sync with the server. If you'd like to, you can add a button somewhere on the layout for users to run the sync easily.

Distributing new versions of your application

When you make development changes to the file hosted on FileMaker Server, as long as you do not delete or rename fields, it will not interfere with offline user's ability to sync. You can add new tables, layouts, fields, scripts, etc., and your existing offline files will continue to sync normally.

Once you are ready to deploy your changes to offline users, edit the configuration in the MirrorSync admin utility. When you get to the end of the process, re-copy and paste the script steps into your FileMaker solutions. Send an e-mail to your users with a download link (you can use one you've generated in the past or create a new one) and instructions to sync their old file, delete it, and then download a new one. Users who do not download the file will also continue to sync normally, they just won't have the latest and greatest version of the solution.

Advanced topics

This document should get you up and running with MirrorSync. However, there are many advanced features and customizations available, which are covered on the MirrorSync advanced topics page.

Getting help

If you encounter any problems while syncing, please go to the MirrorSync homepage and click the link titled 'report a bug'. This will send us the sync log file, which is required to solve almost all issues. Be sure to include your contact info in the bug report so that we can get in touch with you.

Mirrorsync report bug.png

There is an online discussion forum hosted by FMForums. Please look through the posts and see if your question has been posted before making a new topic.

If you have other questions, we have a dedicated support team that is ready to help. Send us an e-mail at support@360works.com or call us at 770-234-9293. If it's related to a sync problem, it's better to use the 'report a bug' link described above, since that will attach the sync log file.


360Works Plugins for FileMaker