This is an old revision of the document!


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:

When thinking about sites, it's useful to align the concept with real-world scenarios as well as the type of mSupply installation being used.

mSupply Desktop can be run as a single-user site. This is recommended for smaller facilities where there will only be one mSupply store being managed, and only one user needing to access the application at a time. A single user site can run offline while the internet is patchy, and communicate with other sites once internet connection is restored.

Facilities that require multiple concurrent users can use a client-server instance.

A mobile site will run mSupply Mobile, an open-source mobile app with a stripped-back version of mSupply. The mSupply mobile app has been specifically designed to be used in areas with intermittent internet connection.

We recommend mSupply mobile for small facilities which process up to [TO DO] transactions per day, and do not require label or receipt printing.

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.

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 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)

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.

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 js node http client

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.

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.

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.

Sync sites can be deleted if they:

  • Have no stores connected to them, and
  • Are not the active site on your current datafile.

If the sync site you want to delete has stores on it, you will have to remove those stores from the sync site before mSupply allows you to delete it. Removing a store from a remote site will add that store to the central server.

You can not delete the site that is active on your current datafile. That would break your datafile!

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

Coming soon!

Coming soon!

Coming soon!

  • Last modified: 2023/04/07 09:07
  • by Gary Willetts