Setting up mSupply Mobile - Server side

Book Creator
Add this page to your book

Book Creator
Remove this page from your book

This is an old revision of the document!

The following details the steps of setting up mSupply from your organisation's mSupply Server

Note - the mSupply Support Team will complete these steps for you.
The following instructions are for your information only.

As of 2019-10-24, this process is largely manual, with sync sites and stores needing to be created by an operator, one-by-one with a few small bits of code to make some of these processes quicker and more reliable. There is a plan to develop a tool by which virtually all of the process can be automated. Even with such a tool, at least the following information will need to provided manually:

Store name
Customer name from which the store is being created (normally the case)
Item master list controlling visibility for the store

A server running mSupply with a web server license registered
Sync server has a static IP and any network permissions required configured
A mobile tablet fitting the recommended specifications here

EACH mobile store needs to have these:

If the stores being created from existing customers in an existing mSupply system, then an additional step needs to be carried out: Merge the existing customer name with the new store. There is some footrunner code that can facilitate this for multiple sites - see 2. Create store from existing customer name using store_create_from_name, below.

However, Any unfinalised CIs from supplying stores to these existing customers need to be finalised first. On a system with supplying stores on multiple sync sites, this can take a long time. Start early, and if possible, ask the supplying stores to refrain from creating new CIs until the merging is done…

If you try to do the merge before finalising unfinalised customer invoices, you will get an error message, and as that message indicates, the merge will not proceed:

The first step is to create the sync site that the store will be 'Active' on.

As of 2019-10-24, this process is manual, with sync sites needing to be created by an operator, one-by-one.

Got to Admin > Preferences
On the Synchronise tab on the left-hand side and click on the unlock button and enter the password
Add new Sync Site
Enter Sync ID, User name and Password. Note that URL and Hardware ID are not required.
Click OK
- Keep track of the password! If it is lost you'll have to resynchronise from scratch!
- Sussol will typically have them securely stored if Sussol has done the sync setup.

After the sync sites have been set up, there are three approaches to creating and configuring the store that will operated on that site.

This can be done 'manually' as described in the first method below. This method is suitable if you are creating only a handful of stores.
If you are creating a larger number of stores, then it is more appropriate to use one or both of the two footrunner code methods. As of 2019-10-24 there are two pieces of footrunner code that can expedite this process - see Creating data files for multiple new remote sites. They can not be used together for the same store, but it may be appropriate to use store_create_from_name for creation of one store, and then use sync_clone_sync_site to create subsequent stores.

On mSupply desktop go to Special > Stores > New Store
Enter the Store Code and the Store Name
- The Store Code can not include spaces
- The Store Name needs to be something that users will recognise.
  Mobile Store 1 is not likely to be a good name to use.
Configure items visibility for the store
Configure synchronisation settings
Configure store visibility to other stores

Use the footrunner code store_create_from_name. This method is only useful if you already have a customer and you want to convert it to a store.

Run store_create_from_name to clone the original store. You will need to provide:
1. Name ID (not name Code ) to create the store for (must not be blank or already a store)
2. Store mode for new store (one of store, dispensary or report). Almost always, this should be store
3. Sync ID for site on which the new store will be Active (optional; if left blank, will default to the current site ID)
Configure items visibility for the store
Configure synchronisation settings
Configure store visibility to other stores

Use the footrunner code sync_clone_sync_site. Under this method:

Manually create and appropriately configure a single store.
Make sure the relevant sync sites have been created (above) and then, for EACH store:
Run sync_clone_sync_site to clone the original store. You will need to provide:
1. Sync ID for source sync site
2. Sync ID for clone sync site
3. sync version (v1 for desktop, v3 for mobile)
4. Decision on whether the cloned store will have 'group' store visibility (visible to all other stores with the same supplying store) or not
5. Decision on whether to also clone locations, transactions, stock, requisitions. (almost always NO!)
6. new store code and name for each cloned store
7. new user name and password for the each cloned store's default user
If there are actually existing customers for each of these stores, you will need to merge the existing customer name with the new store
The store will have the same item visibility configuration as the store that has been cloned. Review, and if necessary, Configure items visibility for the store
The store will have the correct 'basic' sync settings. Review, and if necessary, Configure synchronisation settings
The store will have the correct 'basic' store visiblity settings, including, if you have selected it, 'group' store visibility. Review, and if necessary, Configure store visibility to other stores

Click on the Master Lists tab and select at least one Master List.
Click OK
Click OK again

If you have used store_create_from_name for creation of the store, and you have specified the sync site that the store will be Active on, then all you need to do here is:

Change the Synchronisation type for this store on the Primary Server to Collector if so desired (normally the case)
Configure this new store's Sync type to be Transfer or Active/Collector for any other sync sites that need to deal with this store.

Edit store synchronisation settings (Special > Show Stores > Double-click on store > Synchronisation > Click to Unlock, enter code to edit):
In the table below, in row of the Sync site that was created for this store, tick the tickbox in the Local column. This will automatically change the Sync type for that site to Active/Collector.
Set Synchronisation type at the top to Collector
Click OK

Edit the 'name' associated with the store and configure visibility to other stores appropriately

Unlike mSupply Desktop, mSupply Mobile does not need or use individual user permissions for the various activities within the store. All that is required is for the user to have login rights to the store.

This step has already been carried out if you have used method 3. Create the store by cloning another sync store using sync_clone_sync_site. Don't do it again!

At least one store user needs to be set up to have have access to the new store on the Primary server. Even though the user will access the store from the device, their credentials need to be set up on the Primary server - refer managing users.

For convenience when using a tablet:

Only use lower-case letters for both username and password
Consider using short usernames and passwords

At least one admin user needs to be set up to have have access to the new store on the Primary server. This user will normally be the Sussol user that has set up the new store, but there could well be other local administrators that need access.