29.02. Synchronisation Sites

Synchronisation Sites, often simply called Sync sites or Sites, are configured for each device that is running mSupply that is using the synchronisation system. The synchronisation system ensures that all data on remote sites are synced to the central server.

How mSupply handles sync sites was 'refactored' and released in mSupply v5.07 (2022-03-22). This refactoring was significant. The main changes that the user will notice / experience are: The new Synchronisation button on the Special page of the Navigator which provides a much more user-friendly way of managing sync sites Sync Site ID is no longer user controllable. A new field called Site Code has been introduced to allow users to assign a meaningful code to a sync site, much like stores have names and codes.

Type of sites

When thinking about sites, it's helpful to understand which mSupply products are being used - refer Comparison of the mSupply products.

Permissions

As Synchronisation is sensitive to misconfiguration, only system administrators should have permission to edit sites. The user permission to edit Sync settings is found under Edit user > Permissions tab > Admin.

Without the permission, a user may still view sites but may not edit them.

Viewing Sync Sites

From drop down menu Special and click Show Sites… or from the navigator as below:

From here you'll see the list of all sites:

You can see the unique site ID, site name and application type of the remote site here.

Note: The active central server site will always be at the top of the list when sites are viewed on the central synchronisation server.

Note: The X/Y number in the bottom left corner shows the number of sites showing in the table (X) and the total number of sites (Y)

New button: When clicked, this will open a new site window for you to enter the details. See the Creating New Sync Sites section below for details of all the fields and what they mean.

Delete button: Select a site in the list and click on the Delete button to delete it. Sync sites can be deleted if they:

have no stores connected to them (delete the stores in the site first. Note: removing a store from a remote site will add that store to the central server), and

are not the active site on your current datafile.

Double-click on a site in the list to open its details window:

The various fields are all described below in the Creating New Sync Sites section. Click on the Log tab to see a list of the logs that have been recorded for that site:

The filters are set to show all logs for the current day by default.

Creating New Sync Sites

Click the New button in the Site List window above to create a new Site. This will open the Site details window:

The details to be entered are explained in the section below.

While editing a site, no changes that you make are saved in mSupply until you press OK. This allows you to press Cancel to discard all the changes to the site you had entered, including additions or removals of stores.

Editing Sync Sites

To view details and edit any existing sync site, double click any site in the list of sync sites to view the and edit its details.

If the site is blocked because there have been too many failed login attempts then an Unblock site button will be shown next to the Check connection button. Click it and the site will be unblocked so that isers can attempt to login to it again.

Site ID

The Site ID is a unique ID number for the site used throughout the mSupply system. It will be automatically allocated with each new site that you create and is read-only (you can't edit it).

Site Code

The Site Code is a free text field allowing you to set a short human readable code to identify the site. You can edit this at any time and it will not affect any workings of the sync system.

Site Name

The Site Name should succinctly describe the site. The value here will be used in authentication by the remote site communicating with the central server.

Note: due to this being used for authentication, beware editing it. If you change the site name on an actively used site, the remote site will stop syncing. To resume syncing, the site name must be restored to the old value on the central server, or updated to the new value on the remote site.

Password

The password is a password! It is used by remote sites to authenticate with the central server. You cannot view the password that is set, so you should record it securely.

Note: due to this being used for authentication, beware editing it. If you change the password on an actively used site, the remote site will stop syncing. To resume syncing, the password must be restored to the old value on the central server, or updated to the new value on the remote site.

Hardware ID

The Hardware ID is automatically set by remote sites when they authenticate with the central server for the first time. It identifies the particular device that is syncing, be it a tablet or a desktop computer. Once set, any sync requests for this site coming from a different device will be rejected, as they'll have a different hardware ID.

This is to protect against having multiple devices syncing to the central server using the same remote site details. If this were to happen, it'd cause both devices to have out of sync data. One would need to be disabled, and the other resynchronised.

If a device is lost or destroyed, you will need to setup mSupply on new hardware. In this case, for the site to start syncing on a new device you'll need to reset the Hardware ID by pressing the reset button to the right of field on the central server.

Type

The site type simply indicates the intent to synchronise the sync site with mSupply Desktop or mSupply Mobile. When a remote site synchronises it will update the value of this. As of v4.12, this setting has no functionality. Functionality around this is planned for the future.

standalone: mSupply Desktop or mSupply Server

mobile: mSupply mobile

Site is active on this datafile

If this is checked the site is active on this datafile, which means transactions can be entered in it but master data (like item and customer details etc.) cannot. If unchecked then the site is not active in this datafile and transactions cannot be entered in it.

Use of JS Node HTTP Client

This preference is not recommended and will be disabled in future versions of mSupply (v7.11 and above). Node JS was used in special circumstances where 4D HTTP handlers were not working well on cellular connections for certain regions. This has been improved and Node JS is no longer needed.

If checked then a js node http client will be used to transmit and receive synchronisation data instead of the built-in mSupply webserver. Useful in some special circumstances.

Sync interval

Only visible if you are on a remote site. The number of minutes to leave between sending and receiving synchronisation records. Minimum is 1 minute.

Sync request size

Only visible if you are on a remote site. The number of synchronisation records to send and request at a time. Make it smaller if you have a bad internet connection. mSupply will automatically adjust this to optimise the efficiency of communication with the server as synchronisation occurs.

Server URL

Only visible if you are on a remote site. The URL of the server to synchronise with, including the port number if necessary.

Adding stores

Note: You can only add a single store to a mobile type site. If you try to add another mSupply will show you an alert telling you that you can't add another.

To add a store press the Add store button, which will bring up a list of stores that you may add to the site:

Double click a store, or highlight one and click on the OK button.

The store you select will be removed from the site it is currently active on. The behaviour here will differ based on whether the store was on the central server, or an a remote site:

If the store was on an existing remote site

If the store is currently on another actively used remote site, please use caution. It is important to ensure the old remote site fully stops any usage of the store and synchronises before starting usage on the new site the store was moved to.

If the store was on the Central Server

It is OK to move stores from the Central Server to a remote site, as the Central Server will be guaranteed to have the most up-to-date data.

Store Data

When editing an existing site, all store data of any added stores will automatically be queued to sync to the remote site after pressing OK to save the changes.

Removing stores to the Central Server site

To remove a store, highlight the store you wish to remove in the list of stores in the Site window, then press the Remote store button.

Stores removed from a remote site will automatically be moved to the Central Server site.

Viewing/Editing Site Details on the Remote Site

All explanation of what the site editing is on the remote site.

Coming soon!

Check connection

Coming soon!

Enabling Sync

Coming soon!

Sync Mirror Setup

Coming soon!

Previous: 29.01. Introduction to Synchronisation | | Next: 29.03. Sync Site Wizard (Superseded)