Training Handout: basic skills

When mSupply starts you will be presented with the log-in window:

This is the way the window appears when mSupply is started for the first time

  • You should select your user name from the list. If you're just opening mSupply for the first time after installing it, select user 1(pass=user1). If the list is long you can type the first few characters of your user name in the Search users field to shorten the list tio usernames that begin with what you have typed. On subsequent logins mSupply will default to the last logged in user.
  • Enter your password. The password for the user 1(pass=user1) user is “user1” (without the quotes - the hint is in the user name!).
  • From the drop down list, select the store which you want to login to. Most mSupply users will be operating with a single store, but for users operating with more than one store, the login screen allows you to select any of the stores to which you have access. If you have been working with one store and want to change to another one see Switching stores. After selecting the desired store, all transactions will relate to that store until you return to the login screen and select a different store from the drop down menu.
    • Supervisors and other Level 1 users will have an additional menu item, Supervisor - All stores. In this mode, all stores are accessible and you would use this mode, for instance, when placing an order for supplies which will be distributed to a number of stores or for reporting over more than one store. Further information is available here: Virtual stores.
    • If you have enabled the Hospital Info System (HIS) in the user login permission settings (see foreign_keys), and at least one license is allocated to HIS (see HIS preferences), then you will also see Hospital Info System in the list of stores. If you select this, the login mode automatically changes to HIS mode.
  • View any messages that might be displayed
  • Finally, click OK to login. If login is successful you will be taken to the navigator.

There are various options that can be set that cause a successfully logged-in user to be taken to other screens or shown other information. For example, Reminders or Invoices preferences.

If some of the terms used below are not clear, please see Conventions used in this user guide.

Only mSupply®'s basic features are covered in the Tutorial; its many enhanced features are covered in depth in appropriate chapters in the User Guide.

This chart shows the common steps in most pharmaceutical supply processes. (Of course, the manufacturing step only applies to manufacturers!)

mSupply work flow diagram

The two most common transaction types in mSupply® are the supplier invoice (si) and the customer invoice (ci) . These transactions record stock purchases from suppliers, and stock supplies to customers. mSupply® records a full audit trail by only allowing stock adjustments by way of a transaction. Therefore, given an opening balance of stock for the year, mSupply® can show a series of transactions that result in the recorded closing stock.

Of course, there is much more to it than that, but these two transactions are the core of the system.

Note that mSupply® has dozens of preference settings (File>Preferences) which change the behaviour of many aspects of the software. If you have customised Preferences from their default settings, some aspects of this tutorial may not be as stated below. To work through the tutorial, we recommend you start with a fresh copy of the example data to ensure the Preferences are set correctly.

Before starting the tutorial, you will need to have installed mSupply®, and opened the example database. If you haven't done so, see Installation

mSupply® runs best with a screen resolution of 1024 or 768 or greater. If you have your screen set to 950 x 850 or lower, some windows will not fit on the screen. To change screen resolution:

  • Windows: Right click anywhere on the desktop, select Properties > Settings , and make the necessary changes.
  • Macintosh: Choose Apple > System Preferences… then click on the Displays icon and set a new resolution

You will have two icons on your desktop - double-click the mSupply icon.

If you are opening mSupply® for the first time, the program should automatically open the example data file.

The full path to the data file is displayed, along with other useful information by choosing Menu >Help>About mSupply:

If you have already been using mSupply® and have another data file open, but would like to open the example data file for use with this tutorial, then you can use the mSupply® menu File > Open data file… to open the example data file. In Windows, by default the example data folder is stored inside c:/mSupply/database/; navigate to the location and open the data file.

If you have chosen a different location from the one suggested by the installer, the example folder will be in your chosen location.

A password entry window is presented as mSupply® opens up a data file. The message panel informs the user that the example data base is in use.

The “User 1” (pass= “user1”) entry should be highlighted, but if it is not, it should be selected. Enter “user1” (without the quotes) at 2.Enter your password.

The Choose store …. . drop-down list will display General, and the Choose login mode … drop-down list will display Store - these should not be changed. Click the OK button. After you have logged on, the Navigator screen appears:


The mSupply® Navigator provides access to most of the functions you will be using regularly in mSupply®. You will learn that many of these functions may also be opened with shortcut key sequences from the various Menu items, and once you have gained some experience, you may find it quicker to use the shortcuts.

The Navigator always opens at the Customers screen in Store mode, shown above, or the Patients screen in Dispensary mode, shown below:

Displayed along the top of the screen are four items of information:

  • the mode selected at logon (store or dispensary),
  • the store in which you are working - for most users, “General”,
  • the active data file,
  • the user currently logged on.

Immediately below this, there are six large icons, Customers or Patients, Suppliers ……. Admin .“ Click on the icon appropriate to the task you are performing, and you will be presented with a panel displaying annotated icons listing the available functions and procedures; these are in turn selected either by clicking on the icon of your choice with the mouse, or by advancing through the icons with the right or left arrow keys and pressing the Enter key. You will be using the Items panel of the Navigator in the next step in the tutorial, and as the same procedures are common to all panels, you will quickly become familiar with them.

The bottom right area of the Navigator screen is available for displaying your own logo - the logo of “Acme Medical Supplies” is displayed in our example. The placing of your logo is performed by choosing File > Preferences > Logo. You can also read how to do it here.

Creating a new item

For this section of the tutorial, we are going to add two new items to our mSupply® database. From the Navigator's opening screen, click on Item, the 3rd of the large icons near the top of the screen

and the following screen appears:

  • Click on the New item icon
  • You are presented with a window with a number of fields to enter:

Below is a list of fields and the text to be entered into each field. Use the Tab key to advance from field to field or, using the mouse, click on the field you want to edit.

Type: The default entry normal is shown in the drop-down list, and should not be changed.

Item code: Enter amo500c then press the Tab key to advance to the next field.

Item name: Enter Amoxycillin 500mg tab/cap then press the Tab key to advance to the next field

Continue to use the Tab key for the rest of the tutorial when you need to advance to the next field.

Units: “None” is displayed by default. The options are: unit, ea (for each), gm and ml.

Price list: Click in the box so a check appears in it. This means that when we export a price list, the price for this item will be included.

Shelf location: Enter a3. Amoxycillin is stored on shelf 3 in the “a” section of our imaginary store. Note that “A” is interpreted differently from “a”, so it is recommended to be consistent and use either all upper case or all lower case letters for entering shelf locations.

Preferred pack size: Enter 100. This means we want a 100 unit pack to be our standard for comparing prices of this item.

Category: If a list of categories has been defined, this field allows the item which is being added to be placed in its appropriate category.

Normal stock, Critical stock, Essential drug, ATC category, DDD value, DDD factor, Weight, Non stock item, Default customer: For this tutorial, ignore these fields and leave them blank.

Click the OK & Next button to add this item to mSupply®. The window's fields will clear allowing you to add a further item.

If you have no more items to add, click the OK button to add only the item just added and exit. If you accidentally click OK & Next and then want to exit, just click the Cancel button. The Amoxycillin 500mg tab/cap would still be entered, as it was saved when you pressed the OK & Next button.

Proceed to add a further item with the following details:

Note that if you make a mistake, you can click in a field and edit the value.

Field Enter….
Item code “amo125s”
Item name “Amoxycillin 125mg/5ml syrup”
Units “mL”
Price list check the check box.
Shelf location enter “a7”.
Preferred pack size enter “60”.

Click OK now that you have added the item, then click Cancel to exit the window.

Congratulations! You have now added 2 items to our example data file. Let's go and see how to find them.

Viewing item details

Click on Show items from the Navigator's Item screen.


You will be presented with a window to find items:


  • Type “a” into the text entry area, then click the Find button.
  • A list of all the items whose name or code starts with “a” is shown.

  • We will choose the Amoxycillin 250mg tabs/caps - an item that was already in the example data file. To choose the item, double-click anywhere on its line in the window.
  • You will now be presented with a window that displays a lot of information about “Amoxycillin 250mg tab/caps”. From this window you can see stock on hand, view and edit supplier quotations, view usage for this item for the last 24 months, view backorders, view, add and edit notes for this item. Phew!

  • At this stage, we only want to know how to view the information. For an explanation of all the information displayed see Item Edit - General Options
  • When you have finished viewing the information, click the OK button to return to the list of items.
  • If you want to view a different item, you can double-click its line. Otherwise click the X button in the top right corner (on Windows) or the top left corner (on a Mac) to exit to the Navigator.

Adding a Customer or Supplier

For this tutorial example, we will first add a new supplier, then add a new customer.

Adding a Supplier

From the Navigator's opening screen, click on the 2nd of the large icons, Suppliers tab, then on the New Supplier

You will be shown this window to enter the details:

You can now enter the details for your new Supplier.

Field What to do….
Code Enter “Acmep” to identify the Supplier (Acme Pharmaceuticals).
You need to choose a unique code for each name.
Try to choose a logical system, as the code is used to look up the Supplier (or Customer) when you are entering invoice data.
(for example, try to start the code with at least the first three letters of the Supplier name)
Charge to Enter “Acmep” again. This field is only used when exporting data to an
accounting program - this code must match the code
you use for the supplier in your accounting program.
Name Enter “Acme Pharmaceuticals” - the name of our supplier.
Master ID Ignore for now
Customer check box Leave this box unchecked, as we are entering a new Supplier.
Supplier check box As you chose “new supplier” this box is already checked.
Manufacturer Leave unchecked
Benchmark Leave unchecked
Email, Web site etc. Fill in with the appropriate details
Hold checkbox If this box is checked for supplier or customer, that particular supplier or customer can neither supply nor be supplied with items.
Preferred checkbox Leave unchecked
Price Category This applies to customers. It is possible to assign multiple sell prices to customers. Leave it set to “A”.
Supplier details
Currency The field is automatically filled in with “Nrs”
(=Nepali rupees - the default currency in our example data).
This is the currency that this supplier will use to bill us.
Margin Enter “10”. Items purchased from this supplier will have a 10%
margin added to calculate the selling price.
Freight factor Enter “1”. Acme Pharmaceuticals does not charge any freight to us.
Their prices are “CIF”(Cost, Insurance & Freight to named port). This field is only used for comparing quotations from suppliers
- it is not used for actual invoices.
Category 1-6 Ignore for now
Custom 1-3 Ignore for now
Flag Ignore for now
Comment You can enter a brief note here (Ignore it for now)
Print invoices Ignore for now
Address, Main & Postal address. You can complete these with appropriate values.

If you are satisfied with the details, click OK . You will be returned to the mSupply® startup screen.

Adding a Customer

From the Navigator's opening screen, click on the 1st of the large icons, Customers, near the top of the screen, and then click on “New Customer” from the Navigator screen that appears. You will be presented with a window similar to the New Supplier one above to enter the details:

Fill in the fields as follows:

Field What to do
Code Enter “bluec”
Charge to Enter “bluec”
Name Enter “Blue Cross Hospital” - the name of our customer.
Master ID Ignore for now
Customer check box As you chose “new customer” this box is already checked.
Supplier check box Leave this box unchecked, as we are not entering a new Supplier.
Manufacturer, Benchmark check boxes Leave these unchecked too
Hold checkbox If this box is checked for supplier or customer,
that particular supplier or customer can neither supply nor be supplied with items.
Price Category This applies to customers. It is possible to assign multiple sell prices to customers. Leave it set to “A”.
email, web site, etc. You can complete these with appropriate values.
Category 1-6 Ignore for now
Custom 1-3 Ignore for now
Flag Ignore for now
Comment You can enter a brief note here (Ignore it for now)
Print invoices Ignore for now
Address, Main, Postal and Shipping address. You can complete these with appropriate values.

Click the OK button to save the details and exit the window.

Editing a Customer or Supplier

Let's now look up “Acme Pharmaceuticals”

  • Choose Show suppliers … from the Navigator's Supplier screen. You are presented with a window to enter as much of the Supplier name or the code as you know.

For this tutorial, just click the Find button - you will get a full list of all suppliers.

For information on the Normal - Fuzzy slider, see Editing a Customer, Supplier or Manufacturer

  • Double-click the “Acme Pharmaceuticals” entry in the list. You will be shown a window the same as you used to enter “Acme Pharmaceuticals” as a new supplier.

  • Note the window has “Tabs” down the left side in the sidebar: “General”,”Invoices“, “Backorders”, “Quotes” and “Notes”, etc. Let's add a note for Acme pharmaceuticals:
  • Click on the “Notes” tab.

  • Click on the New Note button. Today's date is entered automatically and highlighted. Click inside the Note Entry field.
  • Enter “This is a test note” then click the OK button.

  • The first line of your note text will appear in the list of notes.
  • Click OK to exit viewing/editing the supplier, then click OK again to exit the list of suppliers.

If the precise geographical location of the supplier or customer is known, the Lat and Long fields can be completed in the Photo tab. Entries are made in these fields thus:

  • decimal degrees, and not degrees, minutes and seconds
  • in the Lat field, locations south of the Equator are entered as negative - i.e. the number is preceded by a '-' sign
  • in the Long field, locations west of the Prime meridian are entered as negative - i.e. the number is preceded by a '-' sign

Don't know a precise location? Using Google Maps find the desired location and place the cursor on it. Right click and select What's here from the drop down list. The geographical co-ordinates are displayed at the top of the screen. These should be noted and copied to the appropriate Lat and Long fields in mSupply®

In our example, the location of the imaginary Acme Pharmaceuticals is on Chetrapati in Kathmandu. Click on the Google Maps button to display a map of the vicinity, with the precise location pinpointed by a green arrow.

In some countries an invoice for incoming goods is referred to as a “bill”- we use “supplier invoice” to mean the same thing.

Let's suppose we have just received a shipment containing two items from Acme Pharmaceuticals, and we want to enter these goods into stock. The invoice looks like this:

From: Acme PharmaceuticalsBill no.:A939
Item Quan Pack Batch Expiry Price Extension
Amoxycillin Caps 250mg 1000 100 b93333 31/12/2015 344 344,000.00
Cotrimoxazole 240mg/5mL susp 65 60 bb23d 31/10/2015 21 1,365.00
Cotrimoxazole 240mg/5mL susp 100 60 bb22d 31/01/2016 21 2,100.00
Total: 347,465.00

Choose Supplier > New invoice from the menu or navigator.

The cursor will be positioned in the Name field. Type “a” and then press the tab key. If there is only one supplier whose name starts with “a”, the details will automatically be filled in.

In our case the supplier “Arbuckle distribution” was already present, so you are presented with a window listing the suppliers starting with “a”. Double-click the line containing “Acme Pharmaceuticals” to choose them for this invoice. The insertion point will jump to the Their ref. field.

Type “A939” into the Their ref. field. Press the Tab key to advance to the Comment field.

In the Comment field you can type a comment or information to identify the invoice.

Note that the margin is showing as 10 percent (the percentage that will be added to your cost price to obtain the selling price).

Click the New line button to add the first invoice line. You will be presented with the window for adding invoice lines.

  • The cursor will be positioned in the Item field. Type “a”, then press the Tab key. You will be presented with a window listing all items whose name starts with “a”. Double-click the “Amoxycillin 250mg tab/cap” entry to choose it. The cursor will now be positioned in the “Quantity” field.
  • Enter the number of packs received in the Quantity field: “1000” (Note that this is the number of packs, not the total quantity of capsules). Press Tab to advance to the next field.
  • Enter the pack size: “100.” Press Tab to advance to the next field.
  • The cursor will now be in the location field. Ignore this for now and press Tab again.
  • You can also ignore the Volume per pack field and press Tab to keep going.
  • Enter the batch number: “b93333.” Press Tab to advance to the next field.
  • Enter the expiry date: “31/12/2014” (Presuming you have dates set up to enter as dd/mm/yy. If your dates are set to the USA's mm/dd/yy format, enter “12/31/14”). You only have to enter 2 digits for the year, as long as the year is in the range 1961 to 2060. Dates outside this range must have the year entered as four digits. Press Tab to advance to the next field.
  • In the “Invoice line cost” field enter the pack cost price: “344”
  • The table shown in the picture at the bottom appears if you have Show previous purchases checked in your preferences. It will show purchases you have made of this item in the past.
  • Donor is the donor who provided funds for the goods on this invoice. You can create donors by activating donor tracking in File/Preferences/Suppliers/New Supplier and then check the donor check box.

As we have another line to add, click the OK and Next button. The entry is recorded, and the window is now blank to accept your second invoice line.

  • Enter “c” into the item name field and press tab. In the list of items showing, you will find “Cotrimoxazole 240mg/5mL susp”. Double-click the entry.
  • Enter the remaining invoice details for “Cotrimoxazole 240mg/5mL susp”:
  • num units: “65”
  • pack size: “60” (Note that it is better to record the actual volume of most packs, unless the volume is not important- for example with an eye-drop, where you could record the pack as “1”)
  • batch: “bb23d”
  • expiry: “31/12/2013”
  • price: “21.00” (You can just enter “21”)

Click the OK & Next button to save the details and start to enter another item.

Now enter the third item on the supplier invoice from the example invoice from Acme Pharmaceuticals example invoice above.

When you have finished, click the OK button to take you back to the main list of invoices.

Our invoice will now have 3 items added to it. The invoice total should read “347,465”, and should appear like this:

If you have made a mistake, click on the relevant line , which will now be highlighted; double-clicking on it allows you to edit it. You will be shown the line details again, and you can then make corrections and click the OK button to save your changes. There are 3 icons in the lower left corner of the invoice window.

  1. This allows you to rearrange the order in which the lines are shown on the invoice
  2. Here you can make a note of anything relevant to this invoice
  3. This will copy the details of the invoice to the clipboard

Now click the OK button. As long as you have left the “print” check box (bottom right corner) checked, you will be asked if you want to print the invoice (you may do so). Note that when you print, you are shown two windows. The first window is the page setup for your printer, the second window allows you to specify how many copies to print, etc. (The second window also has “preview” check box, where you can preview the print job).

As this invoice is a “supplier invoice” it has been “confirmed” when you clicked the OK button in the invoice entry window. You can view and edit the invoice details until the invoice is finalised. Note that if you issue some of the stock you have just entered to a customer, some fields relating to that stock will no longer be edit-able.

NOTE - As of mSupply® v190, a more precise alternative for entering received goods has been implemented. See Viewing and editing supplier invoices created via Goods Receipts

Now let's suppose we have just received an order as follows:

From: Blue Cross Hospital
Order number: PO882
Delivery: Express courier please
Item Quan
Amoxycillin 250mg tab/caps 10,000
Cotrimoxazole 240mg/5mL susp 120

Choose New Invoice from the Customer menu, and the following window appears:

Type “b” into the Name field, and press the Tab key. You will be presented with a list of customers whose name starts with “b”. Double-click the “Blue Cross Hospital” entry to select it.

  • In the Their ref field enter “PO882”.
  • In the Comment field enter “This afternoon by courier”
  • Click the New line button to add a line to the invoice. You are presented with the “Add item” window.

Enter the following details:

  • Type “a” into the Name field then press the Tab key. In the list you are presented with, double-click the “Amoxycillin 250mg tab/cap” entry.

  • You will see that a list of available stock has appeared in the window, and the cursor has moved to the Line number field. Enter “2” to choose line 2. (The list is sorted so batches with the shortest expiry date are at the top - usually you would choose the shortest expiry batch, but today we're being different!).

  • Quantity field - the line we have chosen has a pack size of “100”, so we need to enter a quantity of “100” to make a total of 10,000

Click the OK & next button to add the second line of the order.

This time enter “c” and press the tab key. Double-click the “Cotrimoxazole 240mg/5mL susp” entry. The window will close and the list of available batches and quantities will be completed.

Note that in the list of available stock, the second line we entered from “Acme pharmaceuticals” is now at the top of the list - this is because the list is sorted so that the item with the shortest expiry date comes to the top of the list.

Line 1 is selected, despite the fact that there is insufficient stock of line 1 to meet the order of 120. Nevertheless, you should enter “120” in the Quantity field, press Tab, and the following message will appear:

For this tutorial, choose Distribute (which is likely to be your normal choice), and the necessary stock to complete the order will be drawn from another batch/other batches, starting with the batch which will be the first to expire. There will be occasions, however, when you wish to override this automatic means of distribution, and in this event you would select Try Again and manually select the batches from which you wish to meet the order.

Click the OK & Next button

Because the invoice has not been confirmed, the “available” amount for the line has been reduced, but the “total stc” (total stock) is still showing as “100”. mSupply® includes these lines in the list so you can see stock that has been allocated to an invoice but has not yet left your store. You can then edit the other invoice if stock is urgently needed on the current invoice.

Click OK as we are finished entering lines. You will be returned to the main Customer invoice window.

At the bottom right of the invoice you will see the invoice total.

  • As the customer has requested an express courier, we will charge them Rs200 for the service (Rs = “rupees” the currency in our tutorial). At the bottom of the window you will see the Other charges field:
  • There, enter “Courier charge” and press the Tab key
  • In the “amount” field enter “200” and press the Tab key. The new total should be “37,020.00”

Now we are ready to print a packing slip. Make sure that Print is checked in the bottom right corner, and click OK; a window appears displaying your print options:

We want to print a packing slip, so the default settings suit our purpose. You will notice the packing slip printed has a column where you can write down the actual quantity packed.

Confirming the invoice:

Let's suppose the order was successfully packed according to the packing slip, and you now want to confirm the order and print an invoice to pack with the goods. (We're in a hurry - the express courier is on her way!)

First, we need to look up the invoice. Here's an easy way to look up the last invoice you have entered:

  • Choose Show invoices.. from the Customer menu.
  • If you know the invoice number (printed on the packing slip) you can enter it. To bring a list of the most recent invoices, you enter the number of invoices to view. As we know the invoice we want is the last one to be entered, we just type “1” and click OK - you will be taken straight to the invoice.

Click the Confirm truck icon,

and today's date will appear in the Confirm date field. Click OK to confirm you want to proceed.

The invoice is confirmed, and you are given the opportunity to print an invoice.

mSupply® allows you to keep a record of prices that suppliers have quoted to you. Let's assume that you have just received 2 quotations for Amoxycillin 250mg capsules; one of the companies has used US dollars for their quotation, and the other has used British pounds, so before entering the details of the quotations, it is necessary that both of these currencies are recognised. To achieve this, choose the menu item Special > Currencies, and this window appears:

Click on the New button, and a window appears which allows you to enter another currency:

Enter “USD” in the Currency field; in the Rate field you should enter the number of units of the default currency - in this case Nepali Rupees - equivalent to 1 US dollar; at the time of compiling this tutorial, the rate was 71.74 N.Rs. to US $1, so “71.74” is entered in the Rate field. Click on the OK button, and repeat the exercise for British pounds, the rate presently being 116.36.

Once you have performed this, the Currencies window should look like this:

We're now ready to proceed.

To enter a quotation:

  1. Choose Items > Show items
  2. Type “Amox” then press Enter.
  3. Double-click the “Amoxycillin 250mg caps” entry from the list.
  4. The item view window, on the left, has vertical content list (General, Usage, Quotes). Click the Quotes line.
  5. Click the “New Quote” button.
  6. Note that the item is entered for us. We need to choose a supplier and enter their price details.
  7. Enter “Arb” in the supplier field and press tab. Arbuckle distribution is automatically chosen. They have quoted in US dollars, so choose “USD” from the currency menu.
  8. Their price is US $3.50 per 100 capsules, so enter “3.5” in the price field and “100” in the pack size field.
  9. Click OK to save the entry
  10. Now click “new quote” again and enter the following details:
Supplier Gold Medical Supplies
Currency Sterling [GBP]
Price 20.00
Pack size 1000

Click OK when you are done.

Now we can see the list of quotes, which should look like this:

Notice how the adjusted price takes into account differences in pack size and currency, so you can easily compare suppliers.

Thanks for working through the tutorial. We hope you learnt something useful, and now feel confident to start using mSupply®!

  • Use the example database to experiment with different commands as you read about them in the user guide.
  • Have a “dummy run” at starting a new data file and using it.
  • Return to our main documentation page at www.docs.msupply.org.nz

  • Last modified: 2018/03/18 23:15
  • by rozanna