misc:test:start

This is an old revision of the document!

test - all namespaces

1.01. Introduction

Thank you for choosing mSupply. mSupply is now a family of software products, a team of trainers and consultants. Before you launch in (if you haven't already!), we suggest you plan to take the following steps.

  • Get a feel for Open mSupply. If you're running a vertically integrated supply chain, Open mSupply will likely work well for you. It is open source (free of charge) and is the product that The mSupply Foundation is prioritising for development. As of February 2025, a proprietary Legacy mSupply Central server is still required at the core of an mSupply installation, but most stores in the supply chain below the 'central' store(s) can be Open mSupply. The plan is to develop all of the central server functionality in Open mSupply.
  • Read the rest of this introduction.
  • Read the setup, tutorial and licence chapters in this manual.

Please note that installation requires basic computer skills:

  • You need to be able to locate a file using the “open” and “save” windows.
  • If you are not sure, why not try, and email us if you get stuck.

mSupply is designed to handle the following tasks:

  • Recording quotations received from various suppliers in a way that makes for easy comparison of true cost prices.
  • Create tenders for suppliers to respond to.
  • Ordering (Purchasing) of items from a particular supplier, using actual usage figures to calculate the required quantities.
  • Entering of incoming goods into inventory.
  • Manufacturing items. That is, building new items from raw materials in your stock.
  • Tracking Accounts Payable and Accounts Receivable
  • Issuing of invoices for customers, and recording the transaction against inventory.
  • Customers are able to order on-line via the internet, and can view stock status and the status of their orders.
  • Exporting purchase and invoice data for import into an accounting program.
  • Reporting on transactions and other data in almost any manner you want!
  • If you need help with installing mSupply please feel free to email us at support@msupply.org.nz
About this user guide

The latest and most authoritative version of this User Guide is located on-line at http://docs.msupply.org.nz/. You can export the chapter you're viewing in PDF format by clicking the export:pdf tab to the right. It may then be viewed off-line within Acrobat Reader or other PDF viewer. To obtain the whole user guide in PDF format, visit mSupply site

If you are reading a PDF version, it is likely that a more up-to-date version is available on-line.

The software is under constant development as new features and facilities are added. We strive to ensure that the user guide and the graphics that it contains reflect these developments, but occasionally you may find that there are differences between the program itself and the guide or its graphics, where the updating of the guide has not quite kept pace with the development of the software. These are usually of a minor nature, but should you have any difficulties, do please send us an e-mail with details of your problem.
It should also be noted that with the considerable range of preferences and user permissions, a particular user's window may have features included or omitted (according to their preferences and their permissions) when compared with the screenshots appearing in the guide.

As mSupply is compatible with both Windows OS and Apple Mac OS, there is a mix of screenshots in the manual taken from each operating system.

About us

Sustainable Solutions was established in 2001 with the primary aim of supplying and supporting mSupply software in developing countries. We are committed to producing software that enables excellence in health care delivery. We take pride in looking after people who choose to use our services.

We have offices in:

  • Kathmandu, Nepal
  • Auckland, New Zealand
  • Dundee, United Kingdom
  • Belfast, United Kingdom
  • Melbourne, Australia

We can be contacted at:

Please feel free to request more information.

Thanks
  • This software grew out of necessity at the Medical Supply Department, Kathmandu, Nepal. We learnt a lot from Jaap Zijp's software “Bhandari”, and from the staff at MSD where mSupply was originally developed and tested.
  • Ujwal Khatry has stuck with Sustainable Solutions for twenty years, including the startup period where our company name could well have been a misnomer.
  • Jim Staples of 4D inc. http://www.4D.com kindly arranged an initial donation of the 4D development environment we use.
  • Thanks to those people in the 4D tech mailing list who have helped for no benefit to themselves.
  • John Ross, Pharmacist of Patan Hospital, Kathmandu, believed in the quality of mSupply enough to use it long before it was fully ready
  • David Adams kindly donated his superb texts on 4D.
  • The moderators of the E-Drug mailing list have been gracious in letting us use that list for occasional announcements.
  • Juliet has always been supporting and more through the ups and downs of starting a new organisation.

mSupply software is copyright Sustainable Solutions, 2006, UMN/INF/Interserve 1996 to 1999. You may only use the software in accordance with the accompanying licence agreement.

Licence Agreement and Costs

Commercial users or any user wanting multi-user functionality enabled must obtain a licence from Sustainable Solutions.

Please view our web site http://www.msupply.org.nz for up-to-date pricing.

A free version of mSupply is available for Non-commercial use

  • You may use mSupply software in single user mode for free as long as it is used:
    • in an approved not-for-profit organisation
    • in a developing country.
  • Sustainable Solutions shall be the sole arbiter of those qualifying for free use.
  • All users (free and paid) must register with Sustainable Solutions to obtain a registration code. Information supplied will not be used for any purpose other than generation of registration code.
  • Users who have obtained a free licence number are not eligible for free support.

Please contact us for quotes regarding customised versions and installation and training packages.

Changes in recent versions

The mSupply version history is available here: http://msupply.org.nz/history



Previous: 1. About mSupply | | Next: 1.02. Why mSupply?

1.05. Terms, definitions and conventions used in this user guide

If you aren't familiar with using a computer, you should read this chapter. We also recommend you work through the 3. Tutorial section of this user guide.

General terms

Menus: choose New item from the Item menu (sometimes also written as choose Item>New item) means click on the word Item in the menu bar, then choose New item from the menu that drops down.

Keyboard keys: a handful of keys on the keyboard are used extensively and are indicated in italics. The most common are: Tab, Shift, Ctrl, Alt, Enter and Backspace.

Field: an area on the screen (usually a white box) where you can make an entry, either text or numbers. In many places, you can use your mouse to hover over a field for a description of what is required.

Typed data: anything that must be typed into a field is shown in monospace font. For example: Type 100 and press Enter.

Checkbox: a box that changes from having an “X” in it to being blank each time you click in it. To “check” a checkbox means to click it so that an “X” appears (if there is not one already present). Checkboxes have text beside them explaining what the box is for.

Tab & Shift: you can generally move from field to field in a window using the Tab key. Holding down the Shift key while pressing the Tab key will move from field to field in the reverse order to normal. Note that on Windows, some buttons are “tab-able”. That is, pressing the Tab key moves the “focus” to a button. Pressing the Return or Enter key will then activate that button.

Highlight button: pressing the Enter key will operate the highlighted button in a window. This is is usually the OK button.

Double-click: in lists (e.g. of suppliers, customers or items), double-click using the left button of the mouse on a line to edit or view more details.

Insertion point: the blinking line in a field that indicates which field is currently accepting typed input.

OK button: can be operated by pressing the Enter key.

Cancel button: can be operated by holding down Ctrl key (cmd on Macs), and pressing the period key (full stop).

Path to a file (or document): a way of describing where a document is stored on your hard disk. It is written as hard disk:folder 1:folder 2:document, which is the same as C:\folder 1\folder 2\document.

Modifier keys: are different for Windows and Macs. We've tried to list both in the manual, but sometimes one might slip through.

  • The Windows Ctrl (control) key does the same as the cmd (command) key on Macs
  • The Windows Alt (alternate) key does the same as the opt (option) key on Macs.

Column headings: can be clicked to sort the list by that column.

Negative values: are generally not required in mSupply. Even when you are entering returned goods from customers, or returned goods to suppliers, you enter positive values. mSupply automatically converts the invoice total to a negative amount when it is a credit to a supplier or from a customer.

mSupply terms
Basics

Items: Items are the products we manage in mSupply, including medicines, consumables, equipment, laboratory and radiology items or even larger assets such as vehicles and furniture. An item may or may not have stock lines at any given time. For example: In the example data file provided with mSupply, “Amoxycillin 250mg tab/cap” is an item. When you first start to use the example data file it has 2 stock lines. (You can view them under the “stock” tab of the Item details window (more on that later!).

Item Lines (or “Stock Lines”): Represent different batches of the same item.

Stock: Represents the physical stock (inventory) in your store.

Stores: Stores are facilities using mSupply (desktop or mobile). Some facilities can run multiple stores. For example, there may be a pharmacy in the emergency department that manages stock completely separately to the main pharmacy – this can be a separate store (if they are using mSupply).

Locations: Locations are places within stores where items are kept. Locations can only exist within a store. A large store like a central warehouse may have several thousand highly specific locations (e.g. A.02.04, B.01.03), while a small store may only have a few locations (e.g. Room 1, Room 2). Items may also be stored without assigning a location: this is common in very small facilities, where items are just stored alphabetically.

People

Suppliers: Suppliers are facilities that a store orders or receives stock from. Suppliers may be external (e.g. private drug companies or wholesalers) or internal (e.g. central medical store, provincial warehouses).

Donors: Donors are external entities who pay for donated stock (e.g. UNICEF, USAID). No donor is entered when the government or medical store is paying in a normal financial transaction. When the donor is recorded, you can track donated items through the supply chain and run donor transaction reports and stocktakes.

Customers: Customers are recipients of items, excluding patients (usually). This includes health centres, hospitals, wards, private clinics and pharmacies, touring medical teams, outreach services and any other entity that an mSupply store issues stock to.

Patients: Patients are individual people who receive items from a prescription. When a store uses mSupply in dispensary mode, patients receive unique ID numbers and we can track their prescription history, allergies, payment history, insurers and notes.

Prescribers: Prescribers are authorised medical professionals who provide prescriptions to patients, which we can dispense in mSupply. Prescribers may include doctors, nurses and other authorised individuals.

Users: Users are the people using mSupply (you!). Each user has their own password and set of permissions (which can vary from store to store). System logs track everything that users do in mSupply.

Transactions and Features

Builds: Builds are transactions that record the manufacturing of an item by turning raw materials into a finished product.

Stocktakes: Stocktakes are physical counts of the stock in your store including all item details, such as the item name, quantity, batch and expiry date.

Purchase Orders: Purchase Orders are used to order stock from an external supplier i.e. a supplier who does not use mSupply (e.g. private drug companies, wholesalers, private pharmacies).

Goods Receiving: Goods Receiving is used to receive stock from an external supplier who we previously ordered stock from via a purchase order. We can then create a Supplier Invoice directly from the goods receipt to add received stock to our inventory.

Supplier Invoices: Supplier Invoices are used to add received stock to our inventory. They are also known as “bills”.

Internal Orders: Internal Orders are used to order stock from an internal supplier i.e. a supplier who does use mSupply (e.g. central medical store, provincial warehouses).

Requisitions: Requisitions show internal orders placed to our store from customers using mSupply. Examples of customers using mSupply include provincial warehouses, public hospitals and health centres. We can create a Customer Invoice directly from the requisition to issue stock to a customer.

Customer Invoices: Customer Invoices are used to issue stock to a customer from our inventory.

Prescriptions: Prescriptions are instructions written by a prescriber authorising a patient to be provided a medicine or medical device. mSupply can record dispensed prescriptions and maintain patient dispensing histories.

Patient Credits: Patient Credits are used to return items from patients and record credits in their favour. mSupply tracks patient credits and applies them to outstanding prescription payments.

Payments: Payments are used to record payments made to suppliers. mSupply tracks outstanding payments from supplier invoices.

Cash Receipts: Cash Receipts are used to record payments received from customers for customer invoices. They can also be used to record patient payments for dispensed items. mSupply tracks outstanding payments owed by customers and patients.

Supplier Credits: Supplier Credits are used to return items to suppliers and record credits in your favour. mSupply tracks supplier credits and applies them to outstanding supplier payments.

Customer Credits: Customer Credits are used to return items from customers and record credits in their favour. mSupply tracks customer credits and applies them to outstanding customer payments.

Cash Register: The Cash Register records incoming and outgoing cash transactions and displays a current balance. mSupply tracks all cash movements and records them here.

Configuration

Visibility: Visibility allows us to control what stores, customers, suppliers and items a user can see when logged into a specific store.

Preferences: Preferences are system-wide settings that apply to all stores and users.

Store Preferences: Store Preferences are settings that apply to specific stores.

Permissions: Permissions are settings that apply to specific users as either individuals or groups.



Previous: 1.04. Which mSupply package best suits your organisation? | | Next: 2. Setting Up mSupply: Technical Guide

1.04. Which combination of mSupply products best suits your organisation?

Since its creation in 1998, mSupply has grown and multiplied as it has been applied to different challenges. The original Free-user (Windows or Mac based) application continues to be downloaded and used regularly. In fact, it comes packed with (almost) all the bells and whistles of some of our most sophisticated installations, but is only suitable for a small, 'single concurrent user' facility.

Comparison of the mSupply products

So which are the right mSupply products for your organisation?

Free-user
  • PC or Mac application - Download here. The database resides on the computer that the application has been installed on. It can be used by only one user at any one time.
  • Free! You still need to register mSupply with Sustainable Solutions, but we don't charge you for it - and we don't sell your contact details either!
Single-user
  • Same as Free-user, but for users who wish to make use of Support1) and Up-to-Date (UTD)2)
  • A software license needs to be procured, generally for about 1/3 of the price of a multi-user client, and then Support and UTD on top of that.
Multi-user (Server / client)
  • For situations where more than one user needs to access the database at one time. The database is hosted on a file server and mSupply server software is installed on that hardware. Users have access to this data through mSupply client software installed on client PCs that communicate to the server through a Local Access Network (LAN). Remote users can access the server through Remote Desktop Protocol (RDP) or similar.
  • A software license needs to be procured for each concurrent client. Support and UTD is optional, but highly recommended. Most of our customers are very happy to pay for these services.
Synchronised Multi-user
  • If the internet connection to remote users in a Multi-user configuration is inadequate, then synchronisation allows a Primary - Satellite configuration to be deployed. 'Satellite' multi-user servers are installed at remote sites where users operate mSupply on their local store without worrying about the internet connection. In the background, these 'satellite' servers will synchronise their local store data with a 'Primary' server when the internet connection becomes adequate.
  • A software license needs to be procured for each concurrent client for each server. The Synchronisation server Module and Web Server Module are required on the central server.
Synchronised Single-user (Single-user sync)
  • There are situations where the remote sites (with poor internet access) are just single-operator stores needing to manage and report their stock using the fully featured mSupply client. Procuring the minimum multi-user satellite server configuration for each of these sites would be expensive. A solution has been developed that entails installing single-user client machines (normally laptops) at these remote locations and then synchronising them to the primary server much like the Synchronised Multi-user configuration.
  • Lower cost than conventional synchronised multi-user as the single-user client license is less costly than multi-user client licenses. The Synchronisation server Module and Web Server Module are required on the central server.
mSupply Mobile (Android)
Open mSupply
Comparison table

The key differences between the configurations basically comes down to how the user(s) interact with the database. We hope this table helps in making that decision.

Product / configuration Description Software price implications
- refer Pricing
Free-user PC or Mac application - Download here. The database resides on the computer that the application has been installed on. It can be used by only one user at any one time. Free! You still need to register mSupply with Sustainable Solutions, but we don't charge you for it - and we don't sell your contact details either!
Single-user Same as Free-user, but for users who wish to make use of Support3) and Up-to-Date (UTD)4) A software license needs to be procured, generally for about 1/3 of the price of a multi-user client, and then Support and UTD on top of that.
Multi-user (Server / client) For situations where more than one user needs to access the database at one time. The database is hosted on a file server and mSupply server software is installed on that hardware. Users have access to this data through mSupply client software installed on client PCs that communicate to the server through a Local Access Network (LAN). Remote users can access the server through Remote Desktop Protocol (RDP) or similar. A software license needs to be procured for each concurrent client. Support and UTD is optional, but highly recommended. Most of our customers are very happy to pay for these services.
Synchronised Multi-user If the internet connection to remote users in a Multi-user configuration is inadequate, then synchronisation allows a Primary - Satellite configuration to be deployed. 'Satellite' multi-user servers are installed at remote sites where users operate mSupply on their local store without worrying about the internet connection. In the background, these 'satellite' servers will synchronise their local store data with a 'Primary' server when the internet connection becomes adequate. A software license needs to be procured for each concurrent client for each server. The Synchronisation server Module and Web Server Module are required on the central server.
Synchronised Single-user\\ (Single-user sync) There are situations where the remote sites (with poor internet access) are just single-operator stores needing to manage and report their stock using the fully featured mSupply client. Procuring the minimum multi-user satellite server configuration for each of these sites would be expensive. A solution has been developed that entails installing single-user clients machines (normally laptops) at these remote locations and then synchronising them to the primary server much like the Synchronised Multi-user configuration. Lower cost than conventional synchronised multi-user as the single-user client license is less costly than multi-user client licenses. The Synchronisation server Module and Web Server Module are required on the central server.
mSupply Mobile mSupply Mobile is Open Source software that is similar to the synchronised Single-user configuration, but the users operates the software app on an Android tablets. This app has a reduced feature set, but is more than adequate for most Last-Mile needs. Local stock details are synchronised back to the Central server, and can be monitored and reported on there. Pricing is even lower than for Synchronised Single-User. This was the way forward for the medical supply chain in small and remote facilities - until Open mSupply (see below) took that honour! The Synchronisation server Module and Web Server Module are required on the central server.
Open mSupply Open mSupply is the Open Source software multi-platform mSupply software that has been under development by the mSupply Foundation since 2020. Open mSupply has all of the flexibility of all of the other versions of mSupply with the benefit of being Open source. Local stock details are synchronised back to the Central server, and can be monitored and reported on there. Pricing for smaller facilities (single-user stores) is the same as mSupply Mobile. We see this as the way forward for the medical supply chain in both small and remote facilities and in large multi-user facilities. The Synchronisation server Module and Web Server Module are required on the central server.
mSupply Customer Web Interface Allows staff of Customers in your mSupply system order stock on-line. It runs on a browser on any device: tablet, smartphone, net-book, desktop computer etc. It's a little hard to see why this should be chosen over Open mSupply, as the costs are very similar, without the benefit of being able to operate a store… Depends on your situation - contact us. The Web Server Module is required on the central server.
FrontlineSMS integration mSupply has the ability to integrate with a FrontlineSMS installation. This allows a customer to send their current stock levels to mSupply using an SMS (text) message from any mobile phone. This is particularly useful if, for example, you are a mobile or remote health post or dispensary which doesn't have internet access and only needs to send in information about a few items at a time. SMS module is required on the central server.

Other modules

Other modules are available for addition to the basic mSupply application:

Module Comments Software price implications - refer Pricing
FrontlineSMS Allows users to send their current stock levels to mSupply using an SMS (text) message from any mobile phone - even with only 2G reception!. This can then be used by mSupply to determine how much stock to send to the facility. Equal to the price of 1 client license.
Product (drug) Registration Allows integration of product registration (control of what products can be supplied by authorising particular suppliers and products) by recording and tracking the status of supplier's registrations and storing the documentation for easy retrieval. Equal to the price of 2 client licenses.
Web Server Module Allows you to access mSupply data on the server from any networked computer that has internet access.
This module is a prerequisite for several other modules. 		Equal to the price of 2 client licenses.
Synchronisation server Module Maintains data integrity between a central mSupply server and 'satellite' mSupply servers. It therefore only applies to situations where there is a multi-mSupply server setup.
Requires the Web Server. 		Equal to the price of 2 client licenses.
Tender Management Allows execution of a full tender process including publishing of the tender through a web site, and so allowing tenderers to submit tenders on-line.
Requires the Web Server. 		Equal to the price of 1 client license.



A note about costs...

Software costs

When procuring software, an obvious question is what does it cost. We try to be as up-front as possible about what mSupply software costs. Even so, it's complicated. As you can see above, the mSupply ecosystem is complex and each component has different costs. For a start, we've tried to document the software costs on our pricing page. The amounts that you might pay for mSupply software can be divided into three components:

  • License costs Thanks to the generous support of many donor agencies over the decades of mSupply's existence, only the mSupply products built on the (very good!) 4D database engine incur a license fee, up-front, lasting forever - refer Pricing. Not all of the 4D based mSupply products have a license fee; Free-user is … free ;-).
    mSupply Mobile and Open mSupply are both Open Source software, and so are FREE of licence fees.
  • Installation costs mSupply systems need to be configured to the needs of the supply chain system. In principle, software and hardware configuration can be done by system administrators in the host organisation. However, in most cases, the mSupply Foundation is engaged to assist with software and hardware configuration. This is often done initially by one or more consultants travelling to the country for a number of weeks. The costs of this will normally be in the tens of thousands of dollars. Once a country has an mSupply system up and running, additional stores and sites can normally be added at much lower costs, with indicative prices below. For large implementations, local configuration capacity needs to be developed, and the mSupply Foundation is very keen to train local system administrative configuration capacity.
    • Configure a store, not including storage locations and complex user profiles: USD 100
    • Configure hardware:
      • Tablet: USD 25
      • Single-user PC: USD 100
      • Server: USD 200
  • Maintenance costs As with any technology systems, there are ongoing maintenance costs including keeping software up-to-date5) and providing support. This support could be provided by system administrators in the host organisation. However, in most cases, it has been found to be more effective to engage the mSupply Foundation to provide support, at least in part. For large implementations, local support capacity needs to be developed, and the mSupply Foundation is very keen to train local system administrative support capacity.
    • For mSupply products that have a license fee, Up-to-date and support is charged as detailed here.
    • For Open source products, support is charged as detailed here.
And all the other costs

Software is never the largest component of deployment and operational costs. Local circumstances can vary dramatically, but in one a typical developing country with in excess of 500 mSuppy stores, the experience has been that after the expensive initial deployment, deployment and operational costs have been:

Cost type Deployment Annual operation
License 0% (Open source) 0% (Open source)
Configuration / Support 5.6% 7.6%
Hardware 37.3% 9.1%
Internet 0% 36.6%
Training 57.1% 46.6%

Note that in this particular country, the annual costs of a the cheapest commercially available cellular internet connection exceeded the capital cost of the 10“ Android tablets.

Key conclusions:

  • Training is the highest cost (rightly so!)
  • Provision should be made for hardware depreciation (devices do break, get stolen, etc.)
  • Software costs are normally < 10% of the costs (capital and operational)

Referring to the server machine vs. server software

We need two servers!!!???

The ICT industry is plagued by the practice of using the same term to refer to software, hardware or both combined! As it relates to mSupply in multi-user environments, there is often confusion over two of these:

  • The term 'Server' can refer to:
    • The mSupply server computer software which runs the mSupply database,
    • The hardware which the mSupply server software is installed on, and;
    • Both the hardware and the software acting together. This is possibly the most common usage. When we say something like “send to the server” we mean send data to the server software operating on the server hardware.

The server hardware can actually be a cloud hosted 'service' rather than physical hardware that you own and try to manage. Sometimes the server hardware is referred to as a 'file server', and this can help to avoid confusion. In any case, for any multi-user mSupply installation, including mSupply mobile, both server software and server hardware are needed, and both of them cost money.

  • Similarly, the term 'Client' can refer to:
    • The mSupply client computer software which accesses the mSupply server (software) database on the server (hardware),
    • The hardware which this client software operates on, and;
    • Both the hardware and the software acting together.

Sometimes the client hardware is referred to as a 'client PC' (Mac or Windows) and this can help to avoid confusion. Again, for any multi-user mSupply installation, including mSupply mobile, both client software and client hardware are needed. For mSupply mobile, the client hardware is an Android Tablet - refer Mobile (Android) user guide v2.0 - featuring offline operation.

We are a software company, so when we use these terms, we will almost certainly be referring to our software, but sometimes not. The context normally helps, but please forgive us if we fail to distinguish between these meanings!



Previous: 1.03. Who uses mSupply? | | Next: 1.05. Terms, definitions and conventions used in this user guide

1.03. Who uses mSupply?

This list isn't exhaustive.

All sites are multi-user with the number of sites x number of concurrent users at each site in brackets unless denoted by SU (=“Single User”) after the name.

Our 3 largest users are:

Country Total Sites Desktop Sites Mobile Sites
Myanmar 900 900 0
Côte d'Ivoire 1996 1200 796
Papua New Guinea 447 42 405

Open mSupply installations are in:

  • Djibouti
  • Timor-Leste
  • Mali
  • Sao Tome
  • with Côte d'Ivoire, Niger, Chad, Republic of Congo all planned for 2025
Africa (16 countries)
Angola
  • Went live at CECOMA (their CMS) in September 2023)
Côte d'Ivoire
  • Designated national system
  • Type of system: WMS & ELMIS
  • As of December 2021: over 700 sites- mixture of desktop and mobile
  • 30 sites with World Bank funding from 2021
Djibouti
  • Went live at 14 sites May 2023
Democratic Republic of Congo
  • Cordaid (3)
Gambia
  • Gambia Central Medical Stores (14)
Ghana
  • Central Medical Stores (5)
  • Status 2015: CMS was destroyed in a fire in 2014, and the project has been on hold since then.
Niger
  • 2 regional warehouses managed by Chemonics (SU) - 2020
Nigeria
  • Six Government state stores (6 x 3)
  • Ten Government stores managed by Axios (10 x 2)
    • Axios HQ, Abuja (4)
    • Axios uses mSupply synchronisation to connect sites that don't have full time internet access. This system has been in use since 2010, and continues to function well.
  • FCMS Store, Lagos (5)
  • Jigawa CMS
  • From March 2016: 20 new users spread over 6 states (Kaduna, Katsina, Zamfara, Kano, Jigawa, Yobe)
  • Private non-pharmaceutical supplier, Lagos (STIL)(SU)
  • UNFPA warehouse, Lagos (5 users) - 2021
Liberia
  • Axios: 1 site synchronising to a central server
  • Liberia MoH: 11 sites being consolidated to a single mSupply installation Dec 2016
  • using EPI module: yes
Malawi
  • Orant Charities (SU). From 2017.
  • Nkhoma Hospital Pharmacy Department. From 2015
Mali
  • UNFPA Open mSupply pilot, December 2024 onwards
Sāo Tomé and Principe
  • Designated national system
  • Type of system: WMS & ELMIS
  • National supply chain system (10 users 2021, expanding to 40 users in 2022)
Sierra Leone
  • Designated national system
  • Type of system: WMS & ELMIS
  • MRC (SU)
  • Crown Agents Ebola Response and Free Health care distribution (20) - several stores around Freetown running from a single cloud server.
  • National Pharmaceutical procurement unit (2017). Central server with 18 users, 13 regional sites, et al.
  • LSHTM Ebovac (2017). Server with 5 users.
South Sudan
  • Designated national system
  • Type of system: WMS & ELMIS (expanding to ELMIS H2 2022)
  • MoH Central Medical Stores (5 users)
    • Expanding to whole country in 2022
  • UNDP Juba (5 users)
Zambia
  • Churches Health Association (4 users)
Zanzibar
  • ZILS (5 users)
    • this system employs an EDI interface to pick up orders sent to a dropbox folder from the Zanzibar LMIS system and incorporates it into mSupply
    • expanding to Pemba in 2022
Pacific (15 countries)
Cook Islands
  • Desktop Sites (5) - 2018
  • Mobile Sites (10) - 2018
  • using EPI module: yes
Federated States of Micronesia (FSM)
  • 7 users at CMS/main hospital - 2012
Kingdom of Tonga
  • Central Pharmacy Medical Stores (3)
  • Vaiola Hospital (4)
  • Haapai Hospital (SU)
  • Vava'u Hosptial (SU)
  • 'Eua Hospital (SU)
  • Mobile (11)
  • National Covid 19 vaccination program run using mSupply mobile - 2021
  • using EPI module: yes
Kiribati
  • Designated national system
  • Type of system: WMS & ELMIS & Covid Vaccination Record
  • Tungaru Hospital (9)
  • 3 34 sites using mSupply mobile
  • National Covid 19 vaccination program run using mSupply mobile
  • using EPI module: yes
Marshall Islands
  • Ministry of Health/Majuro Hospital (2)
Nauru
  • Central Hospital and Stores (6 users)
Palau
  • 3 sites including CMS- went live in 2022.
Papua New Guinea
National Department of Health
  • Designated national system
  • Type of system: WMS & ELMIS
  • Central server (cloud hosted) with 12 client users
  • 28 Sync server sites (Area medical stores (AMS), provincial hospitals) with 118 client users
  • 13 Single-User desktop sync sites (district hospitals)
  • 105 Mobile sites (Health centres)
  • 300 Mobile sites (UNICEF) 2022
  • using EPI module: yes
Burnett Institute
  • 8 mobile sites (Strive project)
Solomon Islands
  • Designated national system
  • Type of system: WMS & ELMIS
  • National Medical Stores (14 users + Web server + Tender module)
  • National Referral Hospital (4)
  • mSupply mobile- 50 Second Level Medical Stores (phased installation from October 2016)
Tokelau
  • 3 sites covering country - 2018
Tuvalu
  • Princess Margaret Hospital (2)
Vanuatu
  • Designated national system
  • Type of system: WMS & ELMIS
  • Central Medical Stores (2)
  • Vila Central Hospital Pharmacy and Store (3)
  • Lenekel Hospital (2)
  • Norsup Hospital (2)
  • Luganville Hospital (2)
  • using EPI module: yes
Fiji
  • Designated national system
  • Type of system: WMS & ELMIS
  • National deployment to 230 sites started October 2020.
  • Aspen Hospitals x 2
Samoa
  • Nationwide deployment (approx 18 sites) started July 2020 - completed 2022
  • Using mSupply Coldchain for monitoring fridges, including receiving Telegram alerts for breaches.
Niue
  • Using mSupply for pharmacy store and all dispensing.
  • Using mSupply Coldchain for monitoring fridges
Asia (3 countries)
India
  • Meyer Free Clinic
Nepal
  • INF (3 sites- SU)
  • MSMT (SU)
  • Patan Hospital (SU)
  • Lal Gadh Hospital
  • Gurkha Welfare scheme (26 sites, SU) Funders: DFID, GWT
Afghanistan
  • Six NGOs responsible for medicine distribution in provinces synchronise data back to a management server in Kabul (July 2016). Includes automated generation of a multi-workbook Excel spreadsheet that includes macros that submit data to a Ministry of Health database.
  • UNDP warehouse (2019- 5 users)
  • CMS warehouse (2019- 5 users)
  • AFIAT project: 70 sites
  • UNCEF : starting to roll out as national system from May 2025
South-East Asia (4 countries)
Cambodia
  • World Mate Emergency Hospital
  • WMEH Warehouse
Laos
  • Designated national system
  • Type of system: WMS & ELMIS
  • 186 sites (complete Nation implementation) using mSupply synchronisation
Myanmar
  • Designated national system
  • Type of system: WMS & ELMIS
  • 31, no 42 150 362 639 sites using synchronisation to connect to a cloud server, with plans to extend to 3000 sites over the next few years.
  • Medical Action Myanmar (Dec 2017) - 25 mobile sites connecting to a cloud server running mSupply.
  • UNICEF funded EPI program - approx 350 sites starting 2021
  • using EPI module: yes
  • Zenith TRI (2022 onwards): another ~40 sites on a separate system serving NGOs
Timor-Leste
Ministry of Health
  • Designated national system
  • Type of system: WMS & ELMIS
  • Sites
    • SAMES (10)
    • Hospital Nacionale Guido Valedares (5)
    • Dili Central Medical Services (Mobile)
    • 100 mSupply mobile sites (expanding to over 300 in 2022)
    • National Laboratory, Dili & 5 regional laboaratory sites
Menzies Health
  • Central laboratory
  • 8 remote laboratory sites
Americas (3 countries)
Colombia
  • Bogota warehouse supported by Chemonics (2022)
  • Valle del Cauca regional warehouse
  • Cundinamarca regional warehouse
Haiti
  • National warehouse run by Chemonics (2021)
  • National Logistics System (2023/24)
USA
  • SafeNetRx (was Iowa Prescription drug corporation)
    • users: 2
    • Web server: clients from all over Iowa place orders using the mSupply web interface
    • SafeNetRx are the largest non-governmental supplier of free medicines in the USA.
Europe and the United Kingdom (1 country)
United Kingdom
  • UK Microbiological Products supplier (Private company). Since 2012
  • UK Med, suppliers of the UK-EMT (Emergency Medical team), responsible for the UK's international emergency medical response.



Previous: 1.02. Why mSupply? | | Next: 1.04. Which combination of mSupply products best suits your organisation?

1.02. Why mSupply?

This section outlines the approach and ethos of Sustainable Solutions as well as the main areas of functionality that mSupply covers.

People
  • Our aim is to serve developing countries with solutions that provide real benefit.
  • We are driven by a desire to serve, rather than by profit.
  • That said, we are a profitable company with no debt and a commitment to stay in business for as long as we are needed.
  • We have a balanced mix of expatriate and Nepali staff who work on mSupply.
Experience
  • We've been working on mSupply since 1998, and full-time as Sustainable Solutions since 2001. In that time we've done hundreds of days of training, converted hundreds of thousands of records from other systems to mSupply, and installed mSupply in hundreds of locations.
  • Our experience in Nepal, and in many other developing countries, gives us a unique perspective and understanding of the challenges and opportunities involved in working in similar environments.
  • We know that a decision to install mSupply is a big one. We're committed for the long term. We're planning to be here decades from now.
Ease-of-use
  • mSupply is very easy to install- 10 minutes and a whole department is up and running.
  • mSupply uses an easy-to-use graphical interface that makes it a breeze to add purchase orders, patient prescriptions, tenders, etc.
  • The system is also made with high-usage warehouses and busy pharmacy departments in mind. he system automates item purchases, receipts and sales for the warehouse administrator, and also provides features such as abbreviated directions entry for quick prescribing of medicines.
  • There is always a balance between features and usability. While we know we don’t always get it right, we try to make sure we don’t add features that aren’t really needed. Also, we make sure that features only needed by one client don’t clutter up the interface for everyone.
Stability and reliability
  • The initial mSupply server installations in 2002 have run since then without ever crashing.
  • We have more than ten years of experience in keeping mSupply installations running in developing countries, so we know what it takes to make a reliable system. All multi-user mSupply systems we have installed are still running.
  • mSupply includes an automated internet backup system, so backups are automatically transferred to a remote secure site.
  • Server backups are automatic with configurable frequency.
  • mSupply keeps a log of every action you make, and if there is a power failure then the log can be used to restore all unsaved data on the server.
Security
  • We do not know of any instances of a security breach of an mSupply server
  • There is a full password protected login and permissions system, allowing each user’s access to functions to be controlled and recorded.
  • A user log records all significant user interactions, allowing an audit of which user performed which actions.
Local or Cloud or both!
  • mSupply can run in many different ways, depending on whether you want to run a local or cloud-based service:
    • Local server with client connecting over your local network
    • Cloud based server with clients connecting via a special application or a web browser (e.g. Citrix)
    • If you have several sites and want to manage them centrally, but the internet does not support a cloud-based service, then mSupply also supports running individual servers at mulitple locations that then synchronise their data back to a central server when communications are available.
mSupply mobile
  • On Sept 2nd 2013 we officially released mSupply mobile. It allows you to run a small medical store using a tablet computer (iPad or Android or Windows). An internet connection is required, but users in developing countries are successfully using mSupply mobile over an EDGE (2g) mobile network.

As of mid 2016, the internet connection does not need to be there all the time! See Mobile (Android) user guide

  • mSupply mobile can give stock visibility and automated replenishment for hundreds or thousands of stores connected to a single server, which may be hosted on your premises or be cloud-based.
Scalable
  • The same data file can grow from being used in a single-user system to having hundreds of concurrent users with millions of transactions.
Customisation
  • Many mSupply users have unique needs requiring some customisation of the standard mSupply software. mSupply allows customised versions that can still be easily upgraded as new releases are made. Often customisation is done at no extra cost if the client has a current up-to-date contract.
Specially designed for pharmaceuticals
  • mSupply is built from the ground up to handle batches and expiry dates.
  • There are multiple ways of classifying medicines, and mSupply supports ATC coding, WHO’s EDL6) categories and the user’s own custom categories.
  • Many of the reports are specific to the needs of pharmaceutical distribution
Reporting
  • The in-built reports have been developed since the beginning in response to user requests.
  • Users can easily create their own custom reports and save them for use again. Saved reports are available from a menu in the custom report window.
  • Items, Names, and transactions all have lots of spare fields that users can use to store custom data, and then use those fields in reports.
  • mSupply dashboard allows managers in remote locations to log on with a web browser and view reports.
Mistake tolerance
  • mSupply provides easy merging of duplicate items.
  • Easy adjustment of inventory errors (but with a full audit trail!)
  • Most fields allow entry by name or code, and allow partial entry of as much of the name or code as the user knows.
  • Easily find transactions you've entered, by number, by customer/supplier name, by a list of recent transactions or by a custom search.
  • If the user’s hardware is powerful enough, fuzzy find searches allow finding data even if the search terms are incorrectly entered.
Backorders
  • Items that you are unable to supply to customers are put onto backorder. A report of all backordered items is easily generated. When the stock for the backorder becomes available a customer invoice is automatically created awaiting your confirmation.
Web interface for customers
  • mSupply allows customers to remotely log in via a web browser and place orders, view order status, stock status and transaction history. This system is in daily use.
Customer stock history / indent ordering
  • mSupply supports a unique system of centralised supply where the distribution point submits current stock on hand figures, and mSupply calculate a rational quantity to supply, knowing the historic stock on hand, the ordering cycle, and the amount supplied during the previous cycle.
  • mSupply also supports the simpler imprest system where the amount given to customers is based on a fixed level of stock, as is commonly done when supplying wards in hospitals.
Quantification
  • mSupply uses a powerful ordering system that allows accurate real-time analysis of how much stock should be ordered, based on historic consumption, order lead time, the ordering frequency, desired “buffer” stock levels and current stock levels. Unmet demand from customers, backorders, and stock on order are also taken into account.
  • This system has proven reliable, and requires little user intervention, unlike systems that require you to set minimum and maximum stock levels. mSupply still allows minimum stock to be set if really needed.
Procurement
  • mSupply handles purchase orders in multiple currencies, and allows split deliveries.
  • The goods receipt module allows full or partial receipt of each purchase order plus addition of stock not ordered.
  • Ad hoc quotes from suppliers can also be handled.
  • The quantification, tender management and purchase order systems all tie together so data flows from one to the other without requiring re-entry.
Tender management
  • The Tender Management module provides detailed production and management of tenders including using mSupply data to determine quantification, printing invitation letters, comparing tender submissions and automatically producing Purchase Orders for the winning tender supplier.
  • The Remote Tender Management Module provides posting of tenders by suppliers to https://tenders.msupply.org.nz secure web site. You download and automatically import completed tenders to mSupply for easy comparison of supplier responses, choosing the winning supplier and creation of purchase orders.
  • Supplier Registration functionality is planned to be developed as part of the Tender management module.
Dispensing
  • mSupply integrates well into hospital pharmacies, providing easy breakdown of bulk packs for dispensing.
  • Prescribers are recorded, and prescriber reports allow analysis of prescribing trends and costs.
  • Drug interactions are handled, as is repeat dispensing.
  • Patient history is recorded and easily accessible.
  • Customisable abbreviations allow rapid entry of patient instructions on to printed labels.
  • Medicine labels are produced using specialist label printers. Busy sites using mSupply produce hundreds of thousands of labels per year.
Multiple sites from one server
  • mSupply is able to handle multiple virtual stores within a single data file. A common use for this is a hospital, where several stores may be present, but each needs to run independently.
  • Stores can run in either dispensary or store mode, so one server can handle both a hospital pharmacy and a warehouse store simultaneously.
  • Using Citrix and a DSL internet connection you can run a whole country's medical distribution system from a single server, greatly reducing infrastructure requirements while dramatically improving availability and reliability.
Stock control
  • Because mSupply tracks each batch separately, full FEFO 7) can be maintained for every item.
  • There is a full audit trail for each stock line.
  • Each stock line has a record of warehouse location, enabling easy warehouse management
  • If stock lines have the same batch number, expiry and pack size, they can be split and combined.
  • Stock lines can be re-packed to different pack sizes for convenience. Warehouses will find it easier to handle cartons with a pack size of, say, 12,000 tablets while dispensaries will be dispensing individual tablets, and so will want a pack size of 1.
Warehouse management
  • Full Location management
    • mSupply allows volume based calculations of available storage, that is especially critical for cold chain items.
    • Volume information is used to provide either reports or a graphical depiction of how full each section of the warehouse is.
    • Alerts are given when placing purchase orders if there will not be enough space to hold the incoming goods.
  • Basic bar-coding functionality is planned to be developed soon.
Vaccines monitoring
  • mSupply allows recording of VVM8) status for batches, and allows sorting available stock by VVM status rather than by expiry.
Mobile communications
  • mSupply integrates with Frontline SMS to provide an interface for using SMS messaging to submit information such as stock levels and goods receipt confirmations to mSupply.
Hospital information system
  • A simple hospital information system has been developed as part of mSupply. It is designed to provide a basic service to record critical data:
    • Recording a hospital's wards and beds.
    • Recording inpatient admissions (admitting a patient, assigning them to a ward and bed).
    • Recording ICD9) 10 disease codes for each patient admission. You can assign multiple disease codes, and prioritise them (primary, secondary, etc..).
    • Moving patients to different wards/beds.
    • Recording discharge data (patient status at time of discharge)
    • Reporting on bed occupancy rates as a whole and by ward, and other useful statistics e.g. average length of stay, ICD10 statistics.
  • The mSupply HIS is a cost effective alternative to large commercial installations.
Product / medicine registration
  • mSupply's Registration module allows mSupply to manage registration of suppliers and their products on a per brand, dose, and form basis.
  • mSupply will record and track the status of supplier's registrations and stores the documentation for easy retrieval.
No data lock-in
  • All data in mSupply can be exported as industry-standard XML or as an SQL dump, allowing use by other systems as needed.
  • A public API has been developed, allowing any system to retrieve and submit information from/to mSupply.
Cross-platform
  • mSupply is available for Windows and Macintosh.
  • We recommend Windows servers, but client computers can be either Windows or Macintosh.
Interaction with other systems
  • mSupply can either query other systems or provide data in real time via XML web services and other industry standard connectors.
  • mSupply provides automated seamless integration with Moneyworks accounting software and general export files which can be easily customisable for import to other systems.

All of these features combine to make a very powerful medical inventory supply chain management system which has been tried and tested in dozens of locations around the world. We believe it has a unique set of features that no other product offers for managing medical supplies in developing countries

For full information, visit http://www.msupply.org.nz A demo version is available here

The home page for the documentation wiki is here

Previous: 1.01. Introduction | | Next: 1.03. Who uses mSupply?

2.04. Client/Server FAQ

mSupply Server Requirements

OPERATING SYSTEM:

  • Windows Server 2019 or above
  • Windows 10 Pro can be used on laptop servers at smaller remote sites

MEMORY:

  • New mSupply installation: 16GB minimum
  • Migration of existing mSupply Server: multiply mSupply datafile size + index-file by 1.5 (e.g. datafile 20GB + index-file 2GB x 1.5 = 33GB RAM min)

PROCESSOR:

  • 4 cores minimum

DRIVES:

  • Root drive: 100GB min
  • Data Backup: 100GB minimum allocated for mSupply backups (preferably on an additional volume rather than on the root drive)

NETWORK:

  • Assign a local static IP address to server

BACKUPS:

  • We can provide remote daily datafile backups to Backblaze cloud storage. We utilise an application on the server to encrypt all data before sending to the cloud storage so your is safe. This service will require urls to be whitelisted if your server restricts outbound traffic

Port & Firewall Configuration

Central Sync Server

Our standard port configuration for an mSupply sync server (where remote sites need to connect to a central server over internet). Alternative ports can be used if required, for example if TSPlus remote kiosk access is not required then the mSupply web server can be configured to run over port 443

Service Allow Port Protocol Network Requirement
mSupply Web Server TCP 2048 HTTPS Public mSupply web server traffic from remote mSupply sync sites
mSupply Dashboards TCP 3000 HTTPS Public mSupply Dashboard server traffic (if dashboards are to be accessible from the internet)
TSPlus Remote Web Kiosk TCP 443 HTTPS Public if running TSPlus for remote kiosk access to mSupply Client on the server
SSL renewal TCP 80 HTTPS Public Required for automatic SSL renewal via ACME http challenge (no other web traffic will use this port)
mSupply ColdChain API TCP 8090 HTTPS Public For mSupply ColdChain API (if used)
mSupply Application Server TCP 19812, 19813, 19814 Local mSupply Client connections to mSupply application server over LAN
mSupply broadcast UDP 49157 to 65535 Local mSupply will automatically broadcast on the local network over this UDP port range to find the mSupply server
mSupply Server (Central or Remote) with no syncing remote sites

All mSupply Client applications connect to the server over the LAN. There are no remote sites that need to sync to the central server.

Service Allow Port Protocol Network Requirement
mSupply Application Server TCP 19812, 19813, 19814 Local mSupply Client connections to mSupply Server over LAN
mSupply Client broadcast UDP 49157 to 65535 Local mSupply Clients will automatically broadcast on the local network over this UDP port range to find the mSupply server

UDP Ports: If a local static IP address is assigned to the mSupply Server then mSupply Clients can be configured to find the server without needing to open the UDP broadcast ports. This Client configuration is covered in a section below

Separate Dashboard Server Instance

The mSupply Dashboard application uses a PostgreSQL database. It may be advisable to run the Dashboard and Postgres servers together on a separate server instance from the mSupply server so that each instance can be configured specifically for the application that it is running, and so server resources required by Postgres do not interfere with the smooth functioning of mSupply Server.

If mSupply Dashboards and PostgreSQL are running on a separate server instance to the mSupply Server the following configuration will be required for the dashboard server:

Service Allow Port Protocol Network Requirement
PostgreSQL TCP 5432 Local export of data from the mSupply db to the Postgres dashboard db
mSupply Dashboards TCP 3000 HTTPS Public mSupply Dashboard server traffic (if dashboards are to be accessible from the internet)

mSupply Client Requirements & Configuration

OPERATING SYSTEM:

  • Windows 10 64 Bit

MEMORY:

  • 4GB minimum, 8GB recommended


If the UPD ports on the server are not open, or the mSupply Clients are on a separate subnet to the mSupply Server, then the Clients will not automatically find the Server. In this case the Server will require a static local IP address (which is good practice either way).

There are two methods to direct mSupply Clients to the IP address of the mSupply server:

1) Client configuration file

After mSupply Client has been installed edit the EnginedServer.4Dlink found at this path C:\mSupply client\Database using notepad. Replace <SERVER IP ADDRESS> in the code below with the Server IP. This same edited file can then be deployed to the client database folder of all the mSupply Client installations on this LAN. 

<?xml version="1.0" encoding="UTF-8"?><database_shortcut is_remote="true" server_database_name="mSupply" server_path="<SERVER IP ADDRESS>:19813" cache_folder_name="mSupplyClient"/>


2) Client Server Connection Window
  1. Double click on the mSupply client icon but hold down the alt key just after double clicking (This will open Connection to 4D Server window)
  2. Go to the 'Custom' tab as per the screenshot attached
  3. In project name field enter mSupply
  4. In the Network address field enter the server ip address
  5. Click OK (if Client successfully connects the connection config will be saved and this process will not need to be repeated)

Standard Sync or Mirror Sync?

For more information on both our standard sync and mirror sync setups please see this page of our docs

2.02. Installation

Synced system

If you are installing mSupply within a synced system, then it is quite likely that you should not be installing the single-user version as described in the section below. The instructions to follow depend on which sort of site you are installing:

Contact mSupply Foundation support for clarification: support@msupply.foundation

Single-User system

We are assuming you have obtained mSupply from the mSupply Downloads web page.

  • If you are using a Windows machine, you have downloaded the file you need, and you have saved it to your desktop, it is important that you saved the file with an .exe extension or it will not run. You can rename a file by right-clicking on it. The name of the file should be something like mSupply_Single_User_V4-07-09.
  • It is possible to allow mSupply to be run from multiple Windows accounts (e.g. admin and non-admin accounts). However there are a few precautions / tweeks:
    • If you are switching between admin and non-admin accounts, you will need to close mSupply before switching. Single user is intended to be used on one account at a time, and will throw an error if already open on another account.
    • Data file location needs to be in a commonly accessible location, e.g. C:\mSupply_Datafile.
    • Any backup location needs to be in a commonly accessible location, e.g. C:\mSupply_Backup.

It is strongly recommended that users who are not familiar with program installation adhere to these directions.

  • Double-click the installer and it will automatically run the mSupply installer.
  • The installer will do the following:
    • Create a folder on your chosen drive called “mSupply”
    • On Windows the example data file is installed in the My Documents/mSupply/Example sub folder.
      • NOTE: You can use this data file for practice. (Or use the tutorial at the start of the manual to learn the basics quickly)
    • Install the “mSupply.exe” application and associated files. Double-clicking this file will do the same as double-clicking the “start mSupply” icon on your desktop.
    • Install readme.txt - information on licensing and using mSupply.
    • Create a shortcut on your desktop: start mSupply
    • Create a mSupply folder entry in the Programs section of your Start menu.

Now you are ready to begin! Proceed to the section below on starting the example database.

Example data file

The mSupply installer treats Example data files in a special way. Re-installing mSupply on a previous installation will replace all the files except the Example data file. This is to prevent valuable data from being deleted as users may have started entering actual stock into the Example data file.

To install a fresh copy of the Example data file on Windows you can carry out one of the options described below:

  • Un-install mSupply using the Windows menu Start > Program Files > mSupply > Uninstall mSupply . This will remove all installed files of mSupply which includes the Example data files. Re-installing mSupply now will install a fresh copy of the Example data file.
  • You can manually delete the Example data file and re-install mSupply. The mSupply installer will install a fresh copy of the example database as the previously installed file has been deleted.

On Macintosh machines, simply replace the Example folder from the mSupply installer image.

Notes for Windows users
Date format
  • In the regional settings in Control Panel, we recommend that the short date format is set to display only 2 digits for the year (YY, not YYYY).mSupply lists are set up to allow only enough space for 4 digits with most font sizes, but occasionally 4 digit years may be truncated. Having the wrong setting here will only affect display, not the actual data. It does not matter if you use DD/MM/YY or MM/DD/YY or YY/MM/DD
  • If the display of lists in mSupply overlaps the separator lines, turn off large font in the display control panel.



Previous: 2.01. Requirements | | Next: 2.03. Starting mSupply for the first time

2.01. Requirements

For mSuppy Mobile, refer Requirements

For more detailed configuration information on mSupply Client/Server setups please see this FAQ page

Hardware requirements
General hardware recommendations

We have clients running mSupply on a wide range of hardware in a wide range of operating environments. We are happy to discuss hardware options further - please contact support@msupply.foundation, but here are our general recommendations:

  • In environments with regular power outages, which is most institutions using mSupply :-?, it is highly recommended to procure Laptop machines rather than desktop machines - refer to why we now recommend that you use laptops below.
  • A connected printer is not absolutely necessary in every situation, but for most situations it is a requirement. A laser printer or an ink 'tank' printer is preferable.
  • Buy hardware for which good after sales support is available.
  • Buy brands with a reputation for quality (even if it means buying a slower/older machine).
Hardware Requirements

As of version 7.17 and above, Mac OS is no longer supported for mSupply Client.

Hardware requirements vary widely depending on what you want to use mSupply for. Here's a rough guide:

Machine Minimum Recommended
Windows Client Machine
(For use with server) 		64 bit, Intel i5 or AMD Ryzen 5 Processor, 16GB RAM, 120GB of disk space, Windows 11 (or higher) Intel i7+ AMD Ryzen 5+ Processor, 16GB+ RAM, 256GB+ of disk space
Windows Central Server
(Central server on a synced system) 		64 bit, Intel i9 or AMD Ryzen 9 Processor, 32+ GB RAM, 4 x SSD/HDD volumes, 3 configured as RAID1 or RAID5 with hot spare plus daily backups to the fourth volume plus daily off-site backups, Windows Server 2016+ Cloud hosted on a reputable service, Windows Server 2022 or above
Windows Remote Server
(Remote server) 		64 bit, Intel i7 or Ryzen 7 Processor (or better), 16 GB RAM, 500 GB NVMe/SDD volume with daily backups to an external volume plus daily off-site backups, Windows 11 (or higher), Attached to a Smart UPS (see below) 64 bit, Intel i9 or Ryzen 9 Processor (or better), 32+ GB RAM, plus regular off-site backups, Windows 11 (or higher)
Windows Single-User Machine 64 bit, Intel i7 or Ryzen 7 Processor, 8 GB RAM, 256GB HDD/SDD volume plus daily backups to an external volume plus daily off-site backups
Windows 11 (or higher) 		64 bit, Intel i9 or AMD Ryzen 9 Processor (or better), 16+ GB RAM, 500GB HDD/SDD plus daily backups to an external volume plus daily off-site backups

For a Terminal server, the general specification changes in that

  • More RAM is needed.
  • Hard disks are less important, as no data is stored on the server (unless you are using the same server for both hosting the mSupply server and hosting the terminal sessions).
  • An additional Gigabit Ethernet port could be useful

If you are running a server that is not in a datacentre with proper power protection: Beware of Solid State Drives (SSDs) without Power Loss Protection!

At least one country using mSupply on servers in health facilities with SSDs installed has had the bitter experience of the SSDs failing after ungraceful shutdowns due to failing UPSes.

The vast majority of ICT documentation on the internet is written from and for locations enjoying relatively stable power supplies. When the above-mentioned experience happened, there was precious little information available for facilities suffering from the sort of chronic power supply issues which the majority of mSupply users experience. Now there is more literature - refer here : Surviving SSD sudden power loss

We now recommend that you use laptops

Laptop machines, preferably with long battery life, will almost always be the best solution in terms of both cost and effectiveness. See below for the reasons why.

The problem with power cuts and UPSes

In our experience, the primary cause of mSupply database corruption is ungraceful shutdowns of the computer hosting the mSupply database. Ungraceful shutdowns occur when power to the computer is cut instantly, without any notification to the computer to shut down gracefully.

Ungraceful shutdowns on client computers will not result in mSupply database corruption. They may result in incomplete data record entry, but that can be rectified once power is restored.

A common mitigation to prevent ungraceful shutdowns is to use an Uninterruptible Power Supply (UPS). If the computer is protected by a normal UPS, then we can still have ungraceful shutdowns when the battery power runs out. A 'smart' UPS detects when the battery power is about to run out and sends a notification to software on the server which triggers a graceful shut down of the computer. To enable this, there needs to be a cable connection (normally USB) between the UPS and the computer combined with software running on the computer. Even if the machine is protected by a smart UPS, there are a number of circumstances where this UPS protection fails:

  • Cable becomes disconnected
  • Software isn't configured correctly or doesn't start up
  • UPS batteries degrade (normally within 2 years of installation in environments with regular power cuts) and there is too little capacity to run long enough for the computer to shut down gracefully after receiving the notification from the UPS
The merits of laptops

Laptop computers tend to be much more resilient to power failure:

  • A laptop's built-in 'smart' UPS is very reliable
  • The internal batteries last much longer than UPS batteries
  • Even if the laptop internal battery degrades, the 'smart' function appears to work much more reliably than a standalone UPS communicating with a 'tower' computer.

Here are some additional advantages of laptops vs. desktop computers:

  • Can be more resilient to hot and humid working environments if you buy the right model.
  • Lower cost of freight:
    • To send the machine to site
    • To send spare parts for repair on-site
    • To retrieve the machine from site for any repairs that can not be undertaken on site

      There are countries using mSupply where the cost of sending a 40kg traditional server computer to the site is comparable to the purchase price of the server.

  • Wi-Fi capability normally included without extra cost
  • Bluetooth capability normally included without extra cost
  • 'Sound card', speaker, earphones and video camera normally included without extra cost
Battery life

While the consequences of running out of battery power on a laptop is not as catastrophic as on a desktop machine, it is still good to be able to keep your mSupply system running through long power cuts. Unfortunately most laptop manufacturers don't advertise how long their batteries last, even if they do last a long time! Fortunately, there are websites with reviews on laptops where the battery life has been tested and reported.

Security

A concern with laptop computers is security. It is easier to steal a laptop computer from an office than it is to steal a desktop computer. For this reason, laptops are normally configured with a physical locking feature such as Kensington lock slot or Noble wedge lock slot. Don't buy a laptop without one of these security lock features.

Keyboard

Because mSupply is dealing with lots of numbers (quantities of stock), it is highly recommended to have a keyboard with a numeric keypad. Smaller laptop computers (14“ screen or less) will not have this. Smaller laptop computers normally have an impractically small screen. It is therefore recommended to procure either:

  • A laptop computer with a keyboard that includes a numeric keypad - which will necessarily entail a larger screen or
  • A smaller laptop computer with an external keyboard, mouse and maybe even external screen. We don't recommend wireless external keyboard or mouse. Battery replacement is expensive and environmentally irresponsible.
Backup system

Once you start using mSupply, it is of crucial importance that you have a method of backing up your data. mSupply stores all its data in a file that rapidly becomes large. You need, therefore, to have a high capacity removable storage device. We strongly recommend the use of an external hard disk using either firewire (IEEE 1394) or USB2 to facilitate off-site storage of backups.

  • See the section in Preferences that covers mSupply's built-in backup features that allow backup to another disk, and to an internet backup site… you'll find it here: Backup
  • If not using our internet backup service, you need to be able to store backed up data off-site to prevent the risk of loss by fire, theft, etc.

Sustainable Solutions will not be able to help you recover lost data in the event of hardware failure if no backup is available.

Antivirus

Windows based operating systems are particularly prone to malware if precautions are not taken. We recommend the following precautions:

  • Install a reputable anti-virus program, including web protection if the computer has access to the internet.
  • Disable USB ports - refer to this site for suggested methods.

Ensure that access to passwords to allow exceptions to the above two measures are kept secure.

Upgrading mSupply from previous versions

If you open a data file that was created with a previous version, it will automatically be updated to the new format. Please note that this process may take some time.

Note that if you are using a version earlier than v1.96 you must first upgrade to v1.96 and then to version 2 or 3.

IMPORTANT! Always make a backup of your data file before upgrading, and preferably keep a copy off-site. We will not be able to help you in the event of some unexpected disaster if you haven't followed this advice!



Previous: 2. Setting Up mSupply: Technical Guide | | Next: 2.02. Installation

2.03. Starting mSupply for the first time

To start mSupply, either

  • double-click the start mSupply icon on your desktop, or
  • choose the start mSupply item from the mSupply menu in the programs section of the Start menu (on Windows). If this is the first time mSupply has been started after installation, then an example data file will be opened allowing you to follow the mSupply tutorial. mSupply will present you with a log in window.

Note that mSupply will “remember” the last data file used, and automatically present the log-in window for that file unless you move or rename your data file. If you do this, mSupply will show you a standard open/save window for you to choose the new name/location of your data.

Creating a new data file

Create a new data file while opening mSupply:

  1. Quit mSupply if it is running.
  2. Start mSupply and then immediately hold down the Alt key. You will now be shown the following dialogue box with a number of radio buttons with the different options available:new_file_option.jpg
  3. Choose the 3rd radio button Create a new data file.
  4. Another window will open where you can choose the location and name of your new data.
  5. You will be prompted for where to create the log file. Generally, it is OK to put the log file in the same location as the data file.
Default file location
  • Once mSupply has opened a particular data file, that data file becomes the default data file, and will be opened on restarting mSupply.
  • To open a different file, it must be chosen as described later.
  • If the default data file is renamed or moved to a different location, it must be opened using its new name or location.
Log-in to mSupply

The first time you use mSupply, you will be presented with the log-in window like this:

mSupply® ships with three users. “user 1” and “user 2” are the designer and administrator - these two users cannot be deleted, but they can be edited, allowing the use of appropriate names and making changes to their passwords and permissions.

  1. You should select user 1(pass=user1) from the list
  2. Enter the password “user1” (without the quotes). When different users with their own level of access have been set up, you will then log-in by selecting your user name and typing your own password.
  3. From the drop down list, select the store with which you are working. 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. 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. Further information is available here: Show stores

Finally, click OK to login

Preparing mSupply for actual use

The following 2 steps are necessary to start mSupply for the first time.

  • Create a new data file
  • Prepare the new data file for use
Create a new data file

In order to create a new data file, see creating a new data file above.

Save the data file in a location that you can easily find for doing backups. We suggest you create a folder called “mSupply data” inside the My Documents on Windows PC or the documents folder on a MAC to store your data file.

Prepare the new data file for use
  1. Choose your home currency. Currencies are used when you are calculating cost prices for orders, and when you are comparing quotations from suppliers. Choose Special > Currencies. If your currency is not already shown, click the New button at the top of the window and choose from the pick-list the three letter code abbreviation of the currency you will use to operate your database (e.g. “INR” for Indian Rupees, or “SAR” for South African Rands, or “USD” for US dollars). Set the “Rate” to “1”.
  2. Enter your Preferences. Choose File>Preferences to do this. Read section 16. Preferences of this User Guide to learn what the different Preference settings do.
  3. Enter your Suppliers and Customers.
  4. If you have a computer file holding your customer and/or supplier details, it can be imported directly into mSupply. See 17.03. Importing names.
  5. You can also do this as you go along simply by entering a customer or supplier the first time you create an invoice or order from them.
  6. Enter the items you keep in stock. There are a number of ways you can do this:
    • If you have a computer file holding details of the items you stock, it can be imported directly into mSupply. See: 17.01. Importing items.
    • A file containing the WHO essential drug list is available from the download page of the mSupply web site. You are encouraged to use this file should you have no computer file of your own.
    • You can enter each item using the New item Command from the item menu.
    • Enter your stock figures.
    • If you have a computer file holding both details of the items you stock and your current stock figures, it can be imported directly into mSupply. See: 17.02. Importing stock.
    • Your opening stock may be entered manually; choose Item>Inventory adjust - add stock , and enter the required details.
    • If you intend to record the location of each item, you should define the locations that your store contains. See: 4.06. Stock locations and location types.
About Stores

At the log in window you have the option to log into a specific store or to log in as 'Supervisor' by choosing option 3 shown in the below window.

Unless you intend to use multiple virtual stores in mSupply you can ignore this option. More information will be found here: Virtual stores

About Dispensary Mode

mSupply allows you to log in in two different modes, Store mode or Dispensary mode . Each user can have his/her permissions set to allow or disallow each mode.

Each mode presents the user with a different menu bar and different windows, depending on whether you are issuing stock to an organisation or an individual

See section 10.01. Dispensary mode

Previous: 2.02. Installation | | Next: 3. Tutorial

3.05. Creating and viewing items

Creating a new item

In 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 large icon on the top of the screen.

The following screen appears:

Click on the New item icon (the large “+”). 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. You can use Tab to move 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.
  • Item name: Enter Amoxycillin 500mg tab/cap.

If you make a mistake, you can click in a field and edit the value.

  • Units: The default entry is None. 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, section a of our imaginary store. Note that “A” is interpreted differently from “a”, so it is important to be consistent and use all upper case or all lower case letters for 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. 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:

Field Enter….
Item code amo125s
Item name Amoxycillin 125mg/5ml syrup
Units mL
Price list check the checkbox
Shelf location a7
Preferred pack size 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 panel.

nav_show_items.jpg

You will be presented with a window to find items:

find_item.jpg

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 see a window that displays a lot of information about “Amoxycillin 250mg tab/caps”. You can see stock on hand, view and edit supplier quotations, view usage for the last 24 months, view backorders, and read and edit notes.

At this stage, we only want to know how to view the information. For an explanation of all the information displayed see 4.01.01. Items - General tab. 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 and return to the navigator screen.



Previous: 3.04. Navigator | | Next: 3.06. Customers and suppliers

3.06. Customers and suppliers

Adding a customer or supplier

In this section of the tutorial, we will add a new supplier and a new customer.

Adding a supplier

From the top of the mSupply navigator screen, click on the 2nd of the large icons, Suppliers, and then click on New Supplier from the navigator panel. You will see this window:

You can enter the details for your new supplier in this window.

Field What to do….
Name
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
Contact
Email, Web site etc. Fill in with the appropriate details
Status
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
Price Category This applies to customers. It is possible to assign multiple sell prices to customers. Leave it set to “A”.
Currency
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.
Supplier details
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.
Printing
Print invoices Ignore for now
Category
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
Other
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)
Addresses
Address, Main, Postal and Shipping address. You can complete these with appropriate values.

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

Adding a customer

From the top of the mSupply navigator screen, click on the 1st of the large icons, Customers, and then click on New Customer from the navigator panel. You will be presented with a window similar to the New Supplier one above to enter the customer's details.

Fill in the fields as follows:

Field What to do
Name
Code Enter “bluec”
Charge to Enter “bluec”
Name Enter “Blue Cross Hospital” - the name of our customer.
Master ID Ignore for now
Contact
email, web site, etc. You can complete these with appropriate values.
Status
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
Price Category This applies to customers. It is possible to assign multiple sell prices to customers. Leave it set to “A”.
Category
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
Other
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
Addresses
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 panel. You are presented with a window to enter as much of the supplier's name or code as you know.


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

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



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

  • Note the window has Tabs down the left side in the sidebar: General, Invoices, Backorders, Quotes, 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 Acme Pharmaceutical supplier, then click OK again to exit the list of suppliers.



Previous: 3.05. Creating and viewing items | | Next: 3.07. Viewing Names in Google Maps

3.01. The tutorial like no other


For a glossary of terms please refer to section 1.05. Terms, definitions and conventions used in this user guide

Only mSupply®'s basic features are covered in this tutorial. The enhanced features are covered in-depth in later sections of the user guide.

mSupply explained

This chart shows the common steps in most pharmaceutical supply processes. 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 respectively. mSupply records stock adjustments through these two transactions. So, given an opening balance of stock, mSupply will 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 changed the preferences from their default settings, some parts 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 section 2.02. Installation.

mSupply runs best with a screen resolution of 1024 x 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



Previous: 3. Tutorial | | Next: 3.02. Logging in

3.08. Enter incoming goods (supplier invoices)

In some countries, an invoice for incoming goods is referred to as a “bill” - in mSupply 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 Pharmaceuticals Bill: 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 mSupply navigator screen.

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

In our case, there are two suppliers whose names starts with “a”, so you will see a window listing both of these suppliers. 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 Tab 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 Tab. You will see a window listing all items whose name starts with “a”. Double-click the Amoxycillin 250mg tab/cap entry to choose it.
    • In the Quantity field, enter the number of packs received 1000. Note that this is the number of packs, not the total quantity of capsules.
    • Enter the pack size 100.
    • You can ignore the Location and Volume per pack fields for this tutorial.
    • Enter the batch number b93333.
    • Enter the expiry date 31/12/14 (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 between 1961 and 2060. Dates outside this range must have the year entered as four digits (yyyy).
    • 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 checkbox.

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”:
    • quantity 65.
    • pack size 60. Note that it is better to record the actual volume of most packs, unless the volume is not important - e.g. with eye-drops where you could record the pack as “1”.
    • batch bb23d.
    • expiry 31/12/13.
    • 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 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 bottom 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” checkbox (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 a “preview” checkbox, 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 will no longer be editable.

NOTE: as of mSupply v190, a more precise alternative for entering received goods has been implemented. See section 7.02. Goods receipts for information on viewing and editing supplier invoices created via Goods Receipts.

Previous: 3.07. Viewing Names in Google Maps | | Next: 3.09. Enter outgoing goods (customer invoices)

3.07. Viewing Names in Google Maps

If you know the exact geographical location of the supplier or customer, the Lat (latitude) and Long (longitude) fields can be completed in their Photo tab.

You should use the following conventions when entering the exact geographic location for a supplier or customer:

  • Use decimal degrees (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

You can use Google Maps to find the exact geographical location. Find the desired location on Google Maps and place the cursor on it. Right-click and select What's here from the drop-down list. Google Maps will display the geographical coordinates (the first number is latitude and the second number is longitude). These should be noted and copied to the 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. The precise location is pinpointed by a green arrow.



Previous: 3.06. Customers and suppliers | | Next: 3.08. Enter incoming goods (supplier invoices)

3.02. Logging in

When mSupply starts you will be presented with the login window:

This is the login window for when mSupply is started for the first time.

Username

Select your username from the list.

  • Only users from your facility will be displayed. If the list is long, you can type the first few characters of your username in the Search users field to shorten the list to usernames that begin with what you have typed, sorted alphabetically.
  • If you're just opening mSupply for the first time after installing it, select user 1(pass= user1).
  • Each time it opens, mSupply will default to the user who last logged in.

Password

Enter your password. When this window opens, the focus is on the password field. This allows the user who last logged in to be able to quickly log in again.

If using the user 1(pass= user1) name, type user1 as the password.

Store

Select the store you want to log in to from the drop-down list.

  • Most mSupply users will only be able to access a single store. For users who have access to more than one store, the login screen allows you to select any of the stores to which you have access. Once you have logged in you can switch the store without logging out - see Switching stores.
  • After selecting the desired store, all transactions you process will relate to that store.
  • Supervisors and other Level 1 users will have an additional menu item, Supervisor - All stores. In this mode, all stores are accessible. You would use this mode, for example, when placing an order for supplies that will be distributed to a number of stores or for reporting on more than one store - see 26.07. Virtual stores.
  • HIS - if you have enabled the Hospital Info System (HIS) in the user login permission settings, and at least one licence 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.

In a synchronisation system (29.01. Introduction to Synchronisation) the user will see a list of all the active stores they have permission to log into in this datafile.

Messages

View any messages that might be displayed.

Click OK

Finally, click OK to login. If login is successful you will be taken to the navigator screen.

As with all windows in mSupply, pressing the Enter key at any point produces the same result as clicking on the highlighted button, which, for this window, is the OK button. This facilitates fast keyboard control.

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

Journal file

If one has not already been set up and if you are using a single user copy of mSupply, after logging in you will be asked to select the location for the journal file. A good place is to put it in the same folder as the datafile. You will only be asked to do this once.

The journal file is a place that mSupply records every database transaction that occurs after the last backup. It is used for repairing a damaged datafile and for investigating some types of errors.

Previous: 3.01. The tutorial like no other | | Next: 3.03. Opening the example data file
Overview

The mSupply navigator provides access to most of the functions you will be using regularly in mSupply. Many of these functions can also be opened using shortcut keys. 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 login (Store or Dispensary)
  • the store in which you are working - for most users, this will be General
  • the active data file
  • the user currently logged in

Immediately below this, there are six large icons, Customers or Patients, Suppliers, Item, Reports, Special and Admin. When you click on one of these large icons, the panel below will display more icons for each of the available functions and procedures. You can select the smaller panel icons by clicking on the icon, or by advancing through the icons with the right and left arrow keys and pressing Enter.

In the next part of the tutorial, you will be using the Items panel of the navigator. 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 logo. In our example, the logo of “Acme Medical Supplies” is displayed. You can add your logo by through the menu File>Preferences>Logo - see 16.06. Entering a new logo.



Previous: 3.03. Opening the example data file | | Next: 3.05. Creating and viewing items

3.03. Opening the example data file

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 training, then you can use Menu>File>Open data file… to open the example data file. In Windows, by default the example data folder is stored at 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 login window is presented as mSupply opens the data file.

The user 1 (pass= “user1”) entry should be highlighted, but if it is not, select this name.

Type user1 at 2. Enter your password.

The Choose store if available drop-down list will display General. The Choose login mode if available drop-down list will display Store. These should not be changed.

The message panel states that the example database will be used.

Click the OK button and the mSupply navigator screen appears.



Previous: 3.02. Logging in | | Next: 3.04. Navigator

3.09. Enter outgoing goods (customer invoices)

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

</HTML>

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

<HTML>

</HTML>

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

Type b into the Name field, and press Tab. You will be presented with a list of customers whose name starts with “b”. Double-click the Blue Cross Hospital row 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 Tab. In the list you are presented with, double-click on the Amoxycillin 250mg tab/cap row.

  • 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 you will 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 Tab. Double-click on the Cotrimoxazole 240mg/5mL susp row. The window will close and the list of available batches and quantities will be completed.

Note that in the list of available stock, the stock we entered from “Acme Pharmaceuticals” earlier in this tutorial is at the top of the list. This is because the list is sorted so items with the shortest expiry date are at the top of the list.

Line 1 is selected, despite the 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. Distribute is likely to be your normal choice. Distribute will mean that the stock needed to complete the order will be drawn from another batch/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. If this is the case, 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 is decreased, but the “total stc” (total stock) will remain the same. 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. Enter Courier charge and press Tab.
    • In the amount field enter 200 and press Tab. The new total should be 37,020.00.

Now we are ready to print a packing slip. Make sure that the Print checkbox 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 are correct. You will notice the packing slip printed has a column where you can record 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.

  • Choose Show invoices from the Customer invoices menu.
  • If you know the invoice number (printed on the packing slip) you can enter it. Or, 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, you can type 1 and click OK - you will be taken straight to the invoice.

Click the Confirm truck icon.

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.



Previous: 3.08. Enter incoming goods (supplier invoices) | | Next: 3.10. Entering quotations

3.10. Entering quotations

mSupply allows you to keep a record of prices that suppliers have quoted to you for each item. 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. Before entering the details of the quotations, it is necessary that both of these currencies are recognised in mSupply. To achieve this, choose the menu item Special>Currencies. 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 this tutorial was created, the rate was 71.74 N.Rs. to US $1. Enter 71.74 in the Rate field.
  • Click on the OK button.

Repeat the above for British pounds - assume that the rate is 116.36.

Once you have completed 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 on 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:

<HTML>

</HTML>

Supplier Gold Medical Supplies
Currency Sterling [GBP]
Price 20.00
Pack size 1000

<HTML>

</HTML>

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.



Previous: 3.09. Enter outgoing goods (customer invoices) | | Next: 3.11. Working with lists

3.12. Where to now?

  • 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



Previous: 3.11. Working with lists | | Next: 4. Items

3.11. Working with lists

Whenever you perform a search in mSupply resulting in more than one item being found, you will be presented with a list of records (e.g. items, names, contacts or another list) that match the criteria you entered.

mSupply uses two types of list display.

  1. Shorter lists, such as an invoice or stock lists, are displayed with a striped background. These lists have resizable and moveable columns. They also and have an indicator to show the sorted column. Their use is discussed in the next chapter.
  2. Longer lists, such as item and transaction lists, which can have thousands or millions of records.

In this tutorial section, look at the tools for handling of the longer lists.

When longer lists are displayed, a series of buttons are available along the top of the window, as shown in the below screenshot (note only a small list is shown for the purposes of the tutorial):

General

Viewing or editing a particular record: To view or edit a record, double-click the row in the list you wish to view. A new window will open showing the details of the record you clicked.

Column widths: The easiest way to change column widths is to drag the dividers (the dividing line) between the columns in the list view. Note that if the total column width is too wide for the window, a horizontal scroll bar is added to the list allowing you to view columns to the right of those displayed.

Choosing the column order: To change the sequence of the columns in a list, drag a column header to a new location.

Customising

Clicking the Customise button in the toolbar will display this window:

The list on the left-hand side gives all of the available fields (displayed in columns). The list on the right-hand side is a list of fields (columns) you are currently using.

To add a field to your view, click on the field in the left-hand list. You can control-click to add multiple columns at the same time. Then click > >, the right-pointing button, in-between the lists.

To remove a field from your view, select the field(s) to remove from the right-hand list,. Then click < <, the left-pointing button, to move the fields back to the available list.

You can not remove the first column for any list as it is the key column to identify each row uniquely.

Renaming columns: By double-clicking on a field name in the right-hand list you can change the column title.

Ordering

Ordering a list is the same as sorting it. Frequently a column may be ordered by clicking on the column heading. The column will be sorted in ascending order. Ascending means:

  • A > Z (upper and lowercase are not considered different)
  • 1 > 2 > 3 for numbers
  • earlier dates to later dates

Descending means the opposite of Ascending.

Note that ordering a list does not add or remove any records from the list. It simply changes the order in which the records are displayed.

Should you require two (or more) sort parameters, clicking the Order by button opens the following window:

lists-4.jpeg

The Available Fields list will reflect the type of records you are viewing. In our example, the list shown is for Items.

To order by a particular field, double-click it in the left-hand list. You can also drag fields to the right-hand list, or highlight the field in the left-hand list and click the right-pointing arrow. You can order by multiple fields by adding further fields to the right-hand list. Double-clicking on the flags and item name fields in our example results in this window:

lists-5.jpeg

To remove a field: Highlight the field in the Ordered by Fields list, then click the single left-pointing arrow between the two lists. The double left-pointing arrow will clear all fields from the Ordered by Fields list

To change field ordering: Each item in the Ordered by Fields list has a small triangle to the right. If pointing up, the ordering will be ascending. If pointing down, descending. To change the direction, click on the triangle for each field.

Using formulae: If you want to order by a formula, click the Add Formula button. Here the formula window is shown, and the formula Length([items]code) has been entered.

lists-6.jpeg

Using this formula would allow you to identify items whose item code is shorter/longer than your organisation's specifications.

Click the OK button to close the window.

Once the details are entered, click the Order by button to order the list.

Printing lists

You can press the print icon to send the list to Excel. The list will display in Excel with the column headings you have selected.

Find

This button opens a simple find window where you can enter the start of the item name or code.

Complex finds: The window shown above has a Complex Find button. This allows you to perform a search using multiple criteria. Clicking this button shows the query editor

Within this window there are four areas from which you have to choose or set a value for each line of a query.

  1. Available fields, select the field that you are looking for
  2. Operands, select the operand that is appropriate for your search
  3. Value, enter your specific criterion
  4. For queries with more than one criterion, click Add line, then complete as above but also with the appropriate conjunction

For example, if you want to find all items whose default pack size is greater than ten and whose code starts with A these are the required steps:

  1. Click on default_pack_size in the available fields list
  2. Click on is strictly greater than in the Comparisons list
  3. Enter 10 in the value field
  4. Click the Add line button
  5. Scroll down the available fields lists then click on code in the available fields list.
  6. Click on is in the Comparisons list
  7. Enter a@ in the value field (note the wildcard character @ has been used to find all items whose code has a as the first character)
  8. Click the Query button to perform the query

Before step 8, the window would look like this:

The upper area of the query editor shows a summary of the query that is about to be performed.

This example will return a list of items where both the search criteria are met because the conjunction And was used. If you wanted to find items that matched only one of the criteria entered, you would click on the second line in the large upper panel to select it, and then click on the Or button where the conjunctions are displayed.

Saving and Using saved queries: If you have spent time on developing a particular query, and you are likely to use the same query in the future, click the Save… button. You will be asked to choose a name and location to save the query. The saved file is very small.

Then when a blank query window is first shown, you can click the Load… button and locating the saved query.

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



Previous: 3.10. Entering quotations | | Next: 3.12. Where to now?

4.02. Adding a new item

There are different types of item in mSupply but this is the function you use to add them all. The different types are:

  • Normal: This is the one you will nearly always use and is something which you can receive, distribute and hold stock of.
  • Cross reference: This type of item is a pointer to a normal item. Whenever you select a cross reference it will be replaced with the normal item that it points to. In this way, you can use cross reference items to represent brand names (e.g. Panadol) or familiar names (e.g. “Cetamol” is used to refer to “Paracetamol” in Nepal) that actually refer to generic items.
  • Service: These are items which do not have physical stock such as consultancy fees or other charges.

To add any type of item choose Item > New item from the menus (Note: this is not for adding actual stock, just details of the items themselves - to add stock see 7.01. Supplier invoices or 7.02. Goods receipts.

Don't be put off by the number of fields appearing on these windows! mSupply will operate satisfactorily after entries have been made in just the Item code and Item name fields for any item type. All the other fields can be regarded as optional extras, some or all of which you may use at some later date, or never. mSupply is very versatile!

Normal items

Type: Select the type of item you want to add here. The field always defaults to normal.

Item code: This field is mandatory and is a short way of referring to and finding the item throughout mSupply. Any non-printable characters entered before or after the code (including spaces) will be removed. Any entered in the code (except spaces - spaces are allowed in item codes) will be replaced with an underscore (_). Item codes should be unique; mSupply will warn you if you try to enter an item code already in use by another item.

Item name: This field is also mandatory and is the name that the item will be known by throughout mSupply. It will appear in reports and displays, wherever the item is referred to. Any non-printable characters entered before or after the name will be removed. Any entered in the name will be replaced with an underscore (_).

These 3 fields are available to be filled in for every type of item.

Universal code: This read-only field shows the item's universal code as supplied by The mSupply Foundation's unversal code server at https://universalcodes.msupply.org.nz/. Use the button next to the field to search for this item's universal code. See the 4.01.01. Items - General tab page for more details. The universal code is useful for identifying the item across multiple systems.

You should decide on a clear scheme for item names and codes. This can be a tricky process but is worth persevering with. You can change your mind later but changing the codes of all the items and names in your datafile could be a time-consuming business - but note you can speed this up hugely by exporting all the items then reimporting them with their new codes. See the 17.01. Importing items page for details.

We would recommend that the item code is systematic and can be worked out from the item's details e.g. first 3 letters of the item's name, 3 figures for the strength, a letter for the formulation then a letter or number for disambiguation if necessary. e.g. the code for Amoxycillin 500mg capsules could be amo500c.

For item names we would recommend again that you use generic names (no brands or familiar names - use cross reference items for those), be systematic and start with the broadest part of the name. For example, “Brody forceps” would be entered as “Forceps, brody”, “Aqueous iodine” would be entered as “Iodine, aqueous”. For pharmaceuticals we would recommend the name followed by the strength then the formulation e.g. Amoxycillin 500mg capsules.

You are, of course, free to choose your own schemes, these are just our recommendations and one way of doing it. There are many reasons for adopting other schemes and it is not necessary to know or remember item codes while using mSupply!

General tab

Units: The drop down list allows you to choose the appropriate units for the new item ; mSupply comes with a limited list of pre-defined units, but it is recommended that users define their own list. You will find more information in section 4.20. Units.

Category 1: Click on the magnifying glass to select the category 1 this item belongs to. Category 1 is hierarchical and needs to be setup before you can select them here. See Item categories for details on setting them up.

Category 2 and 3: Select the category 2 and 3 that this item belongs to. You must setup these categories before you can select them here - see Item categories for details on doing that.

Department: Select the department the item belongs to. Departments are not a way of categorising items (use the other categories for that) but are for restricting access to items for different customers and are described in detail in section 4.12. Managing item access with Departments.

Default shelf location: This is the location in the store that the item is normally stored. It will be offered by default when the item is received into stock. Type as much of the location code or description (e.g. the first few characters) as you know, then press the Tab key. If only one location code matches your entry it will be filled in automatically, otherwise you will be shown a standard choice list like this:

Select the location you want by double-clicking its line or by clicking once on the line and then clicking OK.

Default pack size: This is the standard pack size that you use for comparing quotes from suppliers.

Default weight: The weight of the preferred pack size in kg.

Price list: If this box is checked, this item will be included when you produce price lists. If checked the item will also be included in the online catalogue. Refer Price list.

Non stock item: If the item is something you do not normally keep in stock, but is passed straight to a customer, this box should be checked.

Default customer: This is the customer the item is sent to by default - used for non-stock items only. Type the first few characters of the customer's name and press the Tab key on the keyboard to select the customer you want.

VEN category: Select which WHO VEN category the item belongs to (one only) - used for reporting.

Stock category: Check each one of these that apply to your item (used for reporting):

  • Normal stock: For practically all new entries this box should be checked; at a later date, should the item be removed from your formulary for instance, you would remove the check from this box.
  • Critical stock: Should it be a requirement that you must never be out of stock of this item, this box should be checked.
  • Essential drug: Check this box if the item is on your Essential Drugs List.

Doses: Enter the number of doses a single unit of this item provides. Used for vaccines and is only enterable if the Is a vaccine checkbox is checked.

Is a vaccine: Check this if this item is a vaccine and you want mSupply to include it in the vaccine functionality (see the mobile vaccine dispensing page for details). When checked, a default value of 1 is entered in the Doses field.

Restricted to: The location type that this item must be restricted to. You can pick from a list of all active Location types. When something is selected here, all stock of this item that is received must be put in a location which is of the same location type. For example, all cool store locations could have been given a type of “cool” and then if the item you are editing should be kept in a cool store, choose that type here, and you will only be able to receive that item into a cool store location.

When you have added all the details for your new item, click on the OK button or, if you want to add another new item, the OK & Next button.

If you have clicked OK & Next but don't want to add more items, press Cancel. Items previously added are still saved - just the details showing on the screen are not saved.

Stores tab

On this tab, you select which stores the item will be visible in:

Simply check the Visible in store checkbox against each store in the list you wish the item to be visible in (if an item is visible in a store then it can be used in that store). You can use the All/None checkbox to toggle selection of all stores or no stores.

If the preference Automatically update item visibility to match the master lists used by each store preference (see General preferences) is turned on then the table in this tab will be replaced with some text telling you that visibility is controlled by master lists and not selecting store visibility directly. Use the Master lists tab (details below) in that case.

Master lists tab

On this tab, you select which master lists the item should be added to:

Master lists can be used for many things in mSupply (e.g. controlling visibility of items in stores or determining which items appear on requisitions). See Item master lists for details of how to set them up and use them.

To add the new item to a master list simply check the Add to list checkbox against the particular master list in the table. Note that any master lists that have the Automatically add new items to this master list option checked will have their Add to list checkbox checked and you will not be able to uncheck it.

Barcodes tab

On this tab, you can add barcodes of the item that contain manufacturer and pack size information:

This information is used when using barcode scanners to help manage your pharmaceuticals. See Adding barcodes for details on setting them up.

Cross reference items

Cross reference items point to another item, they do not have stock themselves. Whenever the cross reference item is entered, it will be immediately replaced with the normal item it points to. This is useful for handling branded items or items with a common name that is more recognisable than its generic name. An example would be Aspirin for Acetysalycilic acid or Panadol for Paracetamol.

To create a cross reference item select cross reference in the Type drop down list. The window changes slightly:

The Item code and Item name fields are the same as for a normal item (described above) but remember you're entering the details of the brand or familiar name in here!

Cross reference item tab

When this item is chosen in a list, use: Type the first few characters of the normal item you always want to replace the brand/familiar name with in this field. Then press the Tab key on the keyboard and select the item you want. When you've selected the matching item then it's code will be appear in the read only Item code field.

That's it, all done. After clicking the OK or OK & Next buttons, every time a user chooses the item you entered in the Item name / Item code fields it will be replaced with the item you entered in the When this item is chosen in a list, use field.

Note: Item custom field 5 is also settable, as shown in the screenshot. It is a number field. This is the user_field_5 for the cross reference item (brand/familiar name), not the normal item. The user_field_5 label shown in the screenshot will be replaced with the name assigned to the field in the preferences (see the 16.01. General preferences page for details) if it has been set. Making this field settable here might seem strange but it is used in some customisations!

The visibility of cross reference items in different stores matches the visibility of the normal item it is linked to. So there is no functionality for manually setting the visibility of cross reference items.

Service items

Service items are those which have a price but no stock. You can use them to represent service or other charges that need to be handled.

To create a service item select service in the Type drop down list. PLEASE NOTE: the service option will not be available in this drop down list if the preference to allow service items has not been set. Please see General preferences for details.

The window changes slightly:

The Item code and Item name fields are the same as for a normal item (described above).

Service item tab

Cost price: Enter the cost you buy this service (e.g. getting an oxygen cylinder refilled) for.

Sell price: Enter the price you charge when selling the service.

Neither of these fields is compulsory.

Stores tab

You select the stores the service item will be visible in on this tab. It operates exactly the same as the Stores tab described above for normal items.

Note: service items cannot be added to master lists so there is no Master lists tab. Their visibility cannot therefore be controlled by master lists but only by directly selecting the stores they are visible in on this stores tab.

Previous: 4.01. About items | | Next: 4.03. Item categories

4.09. Ad hoc items

From the Item menu, choose Ad Hoc items…

This feature requires activation in Preferences > Invoices 1

mSupply® defines Ad Hoc items as items that you don't keep in stock, and that you never will keep in stock. An example of an Ad Hoc item is a specialised item of diagnostic equipment which you would purchase on one occasion only. When a customer orders an item that you decide will be a “one-off” purchase, you can enter it as an Ad Hoc item.

Ad Hoc items differ from non-stock items in only one respect; they are purchased once. Non-stock items are items which, although they do not feature in your stock list, may be purchased with some degree of regularity.

The following diagram outlines the work flow for Ad Hoc items:

When you choose Items > Ad Hoc items, the following window is displayed:

From this window you can view Ad Hoc items, add new items, delete items and edit existing items.

Show drop-down list

This drop-down list allows you to view Ad Hoc items by their status. Ad Hoc items can have the following status codes:

Status code Meaning
un The item has not yet been assigned to a supplier- think of this as your “to-do” list
as The item has been assigned to a supplier, but has not been placed on a Purchase Order. These items also need action.
po The item has been added to a Purchase Order, but the goods have not arrived.
fn The item has arrived from a supplier and been invoiced to the customer
Name field

Enter part of a customer or supplier name in this field and press Tab to show a list of matching names. Choosing a supplier will show items assigned to that supplier. Choosing a customer will show items supplied or to be supplied to that customer.

Once you have chosen a name you can fine-tune the list displayed for that name.

New button

Clicking the “new” button displays this window:

From this window you can add an item name, the name of the customer, then name of the supplier, the quantity to order, and add a comment.

When the customer orders an item, you may not know who the supplier is. You can just leave the supplier name blank.

Editing an ad hoc item

To edit an item, double-click it in the list to display the item details, and a window Edit Ad hoc item, almost identical to the Add Ad hoc item :, appears where you can edit the required details.

Adding ad hoc items to a purchase order

When you are making a Purchase Order for a particular supplier, you can click on the Ad Hoc items Tab to view a list of Ad Hoc items you have assigned to that supplier, allowing you to add them to the Purchase Order. More information is available here - ad hoc items tab.

Previous: 4.08. Merging two items | | Next: 4.10. Non-stock items

4.12. Managing item access with Departments

Introduction

Item departments are a mechanism by which you can restrict item availability to certain customers only.

Item departments are a bit complicated. Here's what you need to remember:

  • Each customer can be a member of only one group.
  • Each item can be a 'direct' member of only one department. However, a department can be a member of another department, so an item can, in effect, be a member of more than one department
  • Each group can have access to items from multiple departments.

The Activate restricted item access by customer group option must be turned on in Preferences>Invoices2 before this option to work.

  • Here is a summary of how department groups affect whether or not an item can be issued.

  • When you attempt to issue stock to a customer whose group does not have access to the department of the item you are issuing, either a warning will be displayed or mSupply® will not allow you to issue the stock - depending on how your preferences are set.
  • Items that are not in any department can be issued to any customer
  • Items that are members of a department can not be issued to any Customers that are not members of a group.
Creating and editing item departments

Choose Show departments from the Item menu displays the Edit departments… window. This is where you are able to create and edit item departments. Once you have created departments the window might appear something like this, and you are now ready to assign items to a department:

View item departments

Taking as an example the department Anti anaemic tablets, the items in the department are shown by clicking Show item departments on the Item menu, and then double clicking on the Anti anaemic tablets department:

  • Each department can have any number and combination of items and departments in it.
Setting up access from customer groups to item departments
  • From the Item menu, choose Manage item access…, and this window is displayed:

  • The left hand list shows the available departments
  • The right hand list shows the customer groups that presently have access to the department which is highlighted on the left hand side.
  • The example shown identifies the four customer groups which are linked to the Anti-anaemic item department:

  • The icons on the right side allow you to add and/or remove groups that have access to the highlighted department.
  • Clicking the Add a new relationship button shows a list of groups you can add:

  • Double-click (or click and then click OK) to add a group to the current department. You will be given a warning if you try to add the same group twice.

Show groups

Customer groups can be used to group customers (or suppliers) together for reporting purposes, and also to set up an item restrictions scheme, allowing some items to be issued only to certain customers.

An explanation of how to set up a restriction scheme is in Managing Item access.

The groups window allows you to set up group names:

  • Click the New group button to add a new group.
  • Double-click an entry to edit its name:

  • You can enter or edit the group name in the top field.
  • The list displays all names which are members of this group.
  • Click the Delete button to delete a group. You can only delete groups that have no names as members. You can remove group members from the Groups tab of the name viewing window (From the Customer menu, choose Show Customers and find the required customer in the usual way.)

  • The drop down list displays the group to which this customer belongs, and to remove the customer, make sure none is selected from the drop down list; to assign the customer to a different group, highlight the new group in the drop down list.
  • Click OK to leave the window.

Departments

Overview: A manufacturer might create departments for raw materials, packing materials, and quality control reagents. A drug store or hospital might create departments according to dose form or according to pharmacological classification, etc.

From the Item menu, choose Show departments …; you are shown a list of departments:

By default the list displays in alphabetic order; clicking on Departments toggles between alphabetic order and reverse alphabetic order; you may also drag and drop individual departments to any position in the list to suit your own requirements, and on clicking OK you will be asked whether or not you wish to save the list in the order you have specified.

To add a new department, click the New dept button.

To edit a department, double-click the department you want to edit. You are shown a window allowing you to edit the department name:

The radio buttons allow you to choose what will happen when you attempt to issue an item to a customer who is not a member of a linked group. Either the user can be warned or the issue can be disallowed. This only applies if you have Activate restricted item access by customer group turned on in the Preferences - otherwise you can ignore this setting.

The Items tab displays a list of items that are members of the group you are viewing:

To delete a department

Double-click it to display the entry window, then click the Delete button. Note that you can not delete a department that has item members. You will be warned if you try to do this. To delete a department with Items, click the items tab and note the items that are members, then edit those items (using the Items > Show items … menu command) and set their departments to either none or a different department. You will then be able to delete the department.

Previous: 4.11. Managing drug interaction groups | | Next: 4.13. Prices in mSupply

4.11. Managing drug interaction groups

This feature is chosen from the Item menu

The examples given in this section are included only for the purpose of familiarising the user with the interactions feature of mSupply and how to use it. Use of this feature is the responsibility of the user, and Sustainable Solutions bears no liability whatsoever for any consequence of inappropriate or incorrect use.

Drug interaction groups allow you to specify groups of items that interact with each other, and then prepare a warning message to be displayed if these items from interacting groups are issued to the same patient.

You can set up interactions in store mode, but warnings will only appear in dispensary mode.

To use this feature, it must be set up, and these are the steps:

  1. Choose a way of defining interaction groups. A number of systems are in use or are under development, and the internet is a useful resource for further investigation.
  2. Define which items are in which groups.
  3. Add interactions between groups.

Let's look at each of those steps in turn

Defining interaction groups

Choose Items> Drug interaction groups … Until you have set up some groups, the list will be blank; a number of groups have been set up for the purposes of this guide, shown below right:

Click the New Group button to add a new group, or double-click an entry to edit it.

Double clicking on NSAID displays this window:

The window has two tabs.

The Items tab shows a list of items that have been assigned to the group.

Define which items are in which groups

You assign an item to a group by viewing the item details (Choose Items > Show items ), and setting interaction group from a drop-down list.

Add interactions between groups

The Interactions tab shows a list of groups that the current group interacts with.

This tab has two buttons allowing you to add or delete a drug interaction. (To delete an interaction click on the line you wish to delete before clicking the Delete interaction button).

To edit an interaction double-click on the one to be edited. This window appears::

You choose the group that affects the current group, and then enter details about the interaction by choosing from the drop-down lists.

The choices available are:

  • Type of interaction
    • Inhibits (I)
    • Augments (A)
    • No effect (N)
    • Conflicting evidence (C)
  • Clinical Significance
    • Minor (1)
    • Moderate (2)
    • Major (3)
    • Unknown (?)
  • Quality of evidence
    • Poor (P)
    • Fair (F)
    • Good (G)
    • Unknown (?)

You can enter a message to be displayed when an interaction occurs, and any notes you may want to record. These fields are optional.

When you are issuing items in dispensary mode, in order to display a warning:

  • the Alert when there are drug interactions checkbox must be checked in File > Preferences > Drug Interactions. The warning as shown will be displayed if the patient is being issued with interacting items:
  • Number of days of patient history.. must be set. We recommend setting it to 180, so that any items dispensed in the last six months that interact with the item you are currently dispensing are found.



Previous: 4.10. Non-stock items | | Next: 4.12. Managing item access with Departments

4.21. Forecasting

In mSupply, 'consumption' is defined as stock that is issued. Stock lost due to damage, expiry, etc. is managed through Inventory Adjustments and is not included in 'consumption'. During the later quantification calculation, there are options to include or exclude Stock Transfers and Builds in the consumption calculation.

Forecasting is the art of determining how much stock to order to minimise stockouts (no stock available) and stock expiring before it is used. It requires you to use the information you have on past stock consumption and availability patterns to estimate what will happen in the future.

mSupply has a few tools to help you with this. For a full description of them, please see the details of the various places where forecasting is used in mSupply:

  • 6.01. Ordering stock from suppliers - when creating a new auto-generated purchase order. This page contains a discussion of the various calculation stages that go into working out the amount to order.
  • 13.04. Purchasing reports - when creating a Suggested order report. This page discusses the details of the options for calculating an item's AMC (Average Monthly Consumption).
  • 18.01. Introduction to tender management - when creating a new auto-generated tender. This page refers to the two pages above for detail.

Normally, mSupply is set to use the assumption that future consumption will continue at the same level as consumption over a given historic period. Our experience is that in almost all situations, this method, combined with a conservative provision for buffer stock, yields very good to excellent results. However, in certain situations you will want to provide your own forecasts. Reasons for this could include factors such as:

  • Excessive, sudden population increase
  • An epidemic causing increased demand
  • Historical usage being inaccurate due to operator error or stock-outs
  • A change to Standard Treatment Guidelines meaning a new treatment is being introduced, and there is no historical data
  • Morbidity and mortality data has been obtained and used to calculate requirements.

When these situations arise then you can fine-tune how mSupply calculates the AMC for each item individually. For details on this functionality, see the 4.01.04. Items - Usage tab page.



Previous: 4.20. Units | | Next: 4.22. Pickfaces and Replenishments setup

4.19. Inventory adjustments

Inventory adjustments allow you to increase or decrease the stock of an item that is recorded in mSupply®. You will need to adjust the inventory if:

  • Stock is discarded (due to damage or expiry)
  • Stock has been stolen.
  • You find some stock on the shelf that is not in mSupply and you don't know where it came from.

DO NOT use inventory adjustments for distributing stock to customers or patients or receiving stock from suppliers. Use customer invoices or prescriptions and supplier invoices for that. Otherwise, you will lose your audit trail and reporting on transactions will be difficult.

Inventory adjustments are used to deal with a problem or fix a mistake, not in the general process of entering stock transactions into mSupply. Ideally, you'll never have to use them but we know we don't live in an ideal world!

If you are doing a stocktake, it's better to use the stocktake module described here as it will create the needed inventory adjustments automatically.

Viewing inventory adjustments

Choose Items > Show inventory adjustments or click on the Show inventory adjustment icon on the Item tab of the Navigator:

This will open the usual transaction filter window for you to choose which inventory adjustments you want to see. Make your filter selections (or leave them alone to see the 15 most recent inventory adjustments by default) and click on the OK button to see the list of matching inventory adjustments:

You can double-click on any inventory adjustment in the list to view or edit it.

Note that si type inventory adjustments add stock and sc types reduce stock (si means “supplier invoice” and sc means “supplier credit”).

Add stock

Choose Item > Inventory adjust- add stock to create an inventory adjustment to add some stock into mSupply or click on the Inventory adjustment (add stock) icon on the Item tab of the Navigator:

The Inventory adjustment (add stock) window will open:

This transaction is almost exactly the same as a supplier invoice and you enter data in exactly the same way (see 7.01. Supplier invoices for details), except:

  • The name (Inventory adjust- add stock) is filled in automatically for you and cannot be changed.
  • There is an additional Adjustment reason column (see below for details).

Because an inventory adjustment represents a correction for some problem or other incident, we strongly recommend that you enter a comment in the Comment field of each inventory adjustment you create, whether to add or reduce stock, so that the reason for the correction is not forgotten.

Use the New line button to add a line to the transaction (and the Delete line button to remove them), just as you would on a supplier invoice.

When you have finished adding lines to the inventory adjustment, click on the OK button. You will be asked to confirm what you want to do:

If you've finished with the inventory adjustment and want to enter the lines into stock now, click on the Confirm button. If you don't want to enter it into stock now (because you want to add more lines later, for example) then click on the Later button.

Adjustment reasons

If you have added any active Positive inventory adjustment reasons on the Options tab of File > Preferences (see 16.10. Options (standard reasons)) then, when adding a line to the inventory adjustment (by clicking on the New line button), an Adjustment reason drop down list is displayed and you must select one of the reasons in the list before you can save the line:

Note that existing lines that do not have a reason selected can be left with no reason seleted if you click the Cancel button on this window.

Vaccines

If the Able to specify VVM status when receiving items store preference is turned on (see the 26.07. Virtual stores page for details) then an additional VVM status field will be displayed on the supplier invoice line entry/edit window as shown here:

The VVM status field is populated with the statuses set up in the system. See the 20.01. Vaccine Vial Monitoring (VVM) page for details on how to do that.

If you are editing an existing line on the inventory adjustment then the VVM status field will display the status selected for the invoice line or Please select… if it doesn't have one set already.

Reduce stock

Choose Item > Inventory adjust- reduce stock to create an inventory adjustment to remove some stock into mSupply or click on the Inventory adjustment (reduce stock) icon on the Item tab of the Navigator:

The Inventory adjustment (reduce stock) window will open:

This transaction is almost exactly the same as a customer invoice and you enter data in exactly the same way (see 8.01. Issuing goods to a customer (customer invoices) for details), except:

  • The name (Inventory adjust- reduce stock) is filled in automatically for you and cannot be changed.
  • There is an additional Adjustment reason column (see below for details).

Use the New line button to add a line to the transaction (and the Delete line button to remove them), just as you would on a customer invoice.

When you have finished adding lines to the inventory adjustment, click on the OK button. You will not be asked to confirm what you want to do, the inventory adjustment will be confirmed and the lines will immediately be removed from stock.

Adjustment reasons

If you have added any active Negative inventory adjustment reasons on the Options tab of File > Preferences (see 16.10. Options (standard reasons)) then, when adding a line to the inventory adjustment (by clicking on the New line button), an Adjustment reason drop down list is displayed and you must select one of the reasons in the list before you can save the line:

Note that existing lines that do not have a reason selected can be left with no reason seleted if you click the Cancel button on this window.



Previous: 4.17. Stocktakes | | Next: 4.20. Units

4.01. About items

An item in mSupply is usually a product that you purchase from a supplier, hold in stock and supply to a customer. However, there are also other types of items:

  • A service item has no stock, but can still be added to customer invoices and charged for. Service item examples are a freight charge, a consultation fee, an express delivery fee, etc.
  • A cross reference item points to another item, so that when it is chosen in a list, it is substituted with the item to which it refers. This allows you to have items in your system that are referred to by trade name, but are only issued according to their generic name.

Managing items is mostly done from the Item menu or Item tab on the Navigator. The item menu also contains commands for managing lists related to items such as accounts, drug interactions and units.

For how to add a new item, see 4.02. Adding a new item.

Item menu

Show items

Use this command for viewing or editing just about any information about an item.

First you are presented with a window asking you to enter search criteria to find the items you are interested in:

If you click on the Find button (or press the Enter key on the keyboard) without changing anything you will be shown a list of all the visible items in your store. But you can refine the search by entering and selecting different values in the different filter lines shown in the window. If you enter no value for a filter then that filter is ignored.

is on Master list drop down list: the drop down list will contain a selection of master lists defined in the system for you to choose:

  • If you are in supervisor mode (25.01. Miscellaneous topics) all master lists will be in the drop down list.
  • If the Automatically update item visibility in all stores to match master lists used by each store preference (15.01. General preferences) is turned on, you will only see master lists that are set to be used by the store you are logged into (25.08. Virtual stores).
  • If the Automatically update item visibility in all stores to match master lists used by each store preference is turned off then all master lists will be in the drop down list.

Randomly select x items from returned list text box: If you enter a number in here mSupply will randomly select that number of items from the items which match the search criteria you have entered in the filters above. Beware: if there are less items returned from the search than the number you enter in here mSupply will return all the items it found with no random selection.

Exclude hidden items checkbox: This is checked by default and means that only items that are visible in the store you are logged into are included in the search. If you uncheck this box then all items in all stores in your datafile will be included in the search.

If only one item is found by your search then its details are displayed, otherwise you will be shown a list of matching items.

The Complex find button gives you access to a more powerful query editor where you can find a very specific set of items. A tutorial on using the query editor is to be found in section 13.14. Custom reports.

To do a “contains” search, use the wildcard character '@'; e.g. entering “@250” will find all items with “250” anywhere in their name.

Here's an example of a list of items displayed after clicking the Find button:

Double-click the item in the list to view its details.

Buttons on the Items list view
New item

Click the New item button to enter the details of a new item you are adding to your inventory. You can find out how to do this here

Set values

Click the Set values button to do either (or both) of the following for all the highlighted items:

  • Set the flag
  • Set forecasting options

You can highlight multiple items at the same time by holding down the control key (command key on Mac) and click on the lines you wish to flag. They will become highlighted.

The flag field is limited to 16 characters in length. Particularly when mSupply allows multiple strings of text in a single flag, We recommend you use just a single character (or two) as the flag.

If you choose Append to existing flags, any items with existing flags will have the new flag added to the end of the flag. If you choose Replace existing flags, then the selected items will have their flags cleared.

You can clear all flags for all items by selecting all items (control - A) then leaving the Set flag to field blank, clicking “Replace existing flags”, and then clicking the OK button.

Find

Clicking the Find button displays the Find window, the same as if you had chosen Items > Show items.

Order by

Clicking the Order by button will bring up the standard Order by window, where you can choose fields by which to sort the displayed items

Print

Click the Print button to print the items currently displayed in a list.

Modify

Click the Modify button to show details for the first record that is highlighted. Clicking the OK and Next button in the item details window will jump to the next highlighted record. To select multiple records, hold down the control key (command on Mac) while you click on the records you wish to select.

Duplicate

Click the Duplicate button to create a new item with the same details as the selected item. A message box like the one below will appear. Click on button Duplicate to confirm creating the duplicate. Note that the only difference you will see between the existing item and the newly created item is the name of the new item ends with the text '(copy)'. The new item will be added to the end of the currently displayed list of items.

Note that for recording and audit purposes a Log event is created when an item is duplicated. For more information on log events see section 25.19. The system log.

Customise

Clicking the Customise button will show a window where you can choose which fields from the items table are shown in the list view. See Working with lists.

Merge

Click on the Merge button to merge two highlighted items.

Item details window

Buttons in the item details window

Delete: Provided that an item has no transactions, quotes, order lines or backorder lines, it can be deleted, and this button performs that action.

Once you have received stock for an item, it cannot be deleted. You can delete an item immediately after you have created it or imported it. Note that if you have imported an item and stock, you can delete it, and it's associated stock will be deleted too (but not once it has been used in a transaction such as an invoice or build).

OK & Next: Saves changes, exits the window, then brings up the next item in the item list. If you did not have an item list open, or if you have reached the last item in the list, you will be returned to the list or the initial menus, depending on your starting point.

Cancel: Exits the window without saving changes.

Changes you have made to quotes, notes and backorders will be saved, even if you click Cancel .

OK: Saves changes then exits the window.

Tabs on the item details window

The item details window displays a vertical list of 'tabs' down the left side. Click on the appropriate item to view a 'tab' displaying particular information about an item. The Item Details Window normally opens at the General tab.



Previous: 4. Items | | Next: 4.01.01. Items - General tab

4.03. Item categories

Item categories are a great way of grouping your items. This enables you, for example, to report on specific groups of products by filtering by item category. This can be extremely helpful.

mSupply provides 4 different categories (called category 1, category 2, category 3 and VEN) for you to use. Category 2 and 3 are normal categories but 1 is a bit special - it's hierarchical and has 3 levels (level 1, 2 and 3. Level 1 is the top level, level 3 is the bottom). VEN refers to the WHO categories of Vital, Essential and Nonessential.

Be careful not to get mixed up between the levels of category 1 (1, 2, and 3) and the different categories (1, 2, 3 and VEN) themselves here!

Category 1 categories

Selecting Show Item Categories from the Item menu opens the window appearing below, showing all the category 1 categories in their 3 levels by default (Note that the 3 “None” categories are default categories and cannot be renamed or removed): In the screenshot you can see that “6.Antiinfectives” is a top level (level 1) category 3 category. It has 3 level 2 child categories: “6.1 Antiinfectives, anthelmintics”, “6.2 Antiinfectives, antiamoebic/antigiardics” and “6.3 Antiinfectives, antibacterials”. And level 2 category “6.2 Antiinfectives, antiamoebic/antigiardics” has a single level 3 category “Antileprosy medicines”.

Clicking on any of the categories will show you which items are assigned to that category in the panel on the right hand side of the screenshot.

Adding category 1 categories

To add a category at level 1, 2 or 3, click on another category at the same level you want the new one to be, click on the Add button (or the Add child button if you want the new category to be a child of the category you selected) shown in the screenshot and the new level will appear at the bottom of the categories pane called “Click to edit” and already selected. Click on it once and type the category's name. When you're done click outside the category and that's it!

Editing category 1 categories

Renaming a category is simple. Click once on the category you want to rename to select it then click on it again to edit the name: the category will become a text box and you can type the new name. When you've finished editing the name, simply click outside the textbox (but inside the category pane) and the new name will be saved.

Changing the parent of a category is almost as simple. You simply click on the category once to select it then click on it again, drag it onto its new parent (or a sibling of the new parent) and let go of the mouse button. Two things to note here:

  1. You can only move a category to a position at the same level. If it's a level 3 category then you can only drop it onto a level 2 category or another level 3 category. If you drag a level 3 category onto a level 1 category nothing will happen. For example: in the screenshot you could drag category “6.1 Antiinfectives, anthelmintics” onto category “1. Anaesthetics” or onto category “4.2 Antidotes, specific” and it would move (to become a child of category “1. Anaesthetics” or “4. Antidotes”). But if you dragged it onto category “6.2.3 Antileprosy medicines” it would not move (this is a level 3 category, 1 level below “6.1 Antiinfectives, anthelmintics” so the move is not allowed).
  2. If you move a category which has any child categories, all the child categories will be moved too. For example: in the screenshot you could drag category “6.1 Antiinfectives, anthelmintics” onto category “4.2 Antidotes, specific” and it would move to become a child of category “4. Antidotes”. It's child (“6.1.3 Antischistosomals…”) would remain its child and become a grandchild of “4.2 Antidotes, specific”.
Deleting category 1 categories

This is the simplest of all. Select the category you want to delete by clicking on it and then click on the Delete button. After confirming you want to delete the category it will be deleted. mSupply will not allow you to delete categories that have items assigned to them - it will warn you that you have to remove the items from the category first. See the Assigning items to categories section below for details on how to do this.

Category 2 and 3 categories

Category 2 and 3 categories are simpler - they are not hierarchical. To view the category 2 or 3 item categories select Show Item Categories from the Item menu and change the Show drop down list at the top of the window to “Category 2” or “Category 3” and the window will change to look like the screenshot below:

The window shows a list of the existing categories of this type.

Save sort order button: The sort order of the categories is the order they will appear in the list when you are assigning items to the categories (see the Assigning items to categories section below) or when you're selecting them in a filter e.g. for a report. You can drag the categories up and down the list to give them the order you want them to appear in. When you are happy with the order, click on the Save sort order button and the order will be saved.

New button: Clicking on this will take you to the edit category window shown below:

Simply type the name of the category shown in the Item category textbox and click on the OK button to create the new category

If you double click on a category in the list you will also be taken to the edit category window where you can edit the category's name, see which items have been assigned to the category, delete the category (click on the Delete button).

VEN category

Refer VEN category

Assigning items to categories

Once you have set up the categories, all items can be assigned to their appropriate category. This is performed on the Item details window under the General tab (get here from File > Show items, click on the Find button and double click on the item you want to add to a category):

To assign the item to a category 2 or category 3 category, select the correct category from the Category2 or Category 3 drop down lists.

To assign the item to a category 1 category click on the magnifying glass next to the Category box. The following window will open:

  • If the item is already assigned to a category then that category is highlighted in the list
  • If you want to change the item's category, simply select the level 3 (bottom level) category you want to assign the item to, and click on the OK button. (You will be alerted if you attempt to select a higher-level category.)
  • If you want to remove the item from all category 1 categories, select the level 3 “None” category in the list.

You can assign an item to a category 1, 2 and 3 category at the same time.



Previous: 4.02. Adding a new item | | Next: 4.04. Item master lists

4.06. Stock locations and location types

Keeping track of where stock is in your store is an important part of good warehouse practice. You don't want to have to go hunting through your whole store for stock, wasting time and energy when mSupply can tell you exactly where it is!

Locations in mSupply are the places you store stock. Locations can have types (e.g. normal, cold, bulk…) to help you categorise them or to make sure that items are put away in the right type of location (e.g. cold or secure storage, or a particular section of the warehouse).

If you use location types it will help you if they are defined before the locations that belong to them otherwise they won't be available to select when defining a location - and you'll have to go back later and edit the locations. What a waste of time! So this section explains location types first and then goes on to explain about locations.

Location types

Location types give you the ability to categorise your locations.

They can be used for reporting on a group of locations, but also to restrict the locations that can be used for a particular item.

If you want to restrict items to being put away in locations with a certain type, you need to assign items the matching location type. For details on doing that see the 4.01.02. Items - Storage tab page.

Choose Item > Show location types to define or show a list of available location types.

show_loc_typ.jpg

The window that appears allows you to define the criteria for the various types of location in your store - e.g. the permitted temperature range, whether location must be dark, etc.

Adding a location type

Click on New , and the window that appears allows you to enter a name for the storage type, and the permitted conditions pertaining to that storage type.:

add_new_loc_typ.jpg

In the above example, a storage type “Refrigerator” has been defined, the permitted range of temperature being 2o C - 8o C.

Having defined your storage types, the Show location types window might look like this:

show_loc_typ2.jpg

It is worth emphasising that the list does not show the actual store locations, but the types of locations.

Editing a location type

Should you wish to edit the details of any location type, double click on it in the list and change the details in the window which appears.

Locations

Viewing locations

To view the locations you have defined choose Item > Show locations and you will see a list of location codes and descriptions:

From this window you can view, edit and remove locations and their details - this is the 'location management' window. Here are the various functions of the window:

New location button: Click this to add a location (see 'Adding a location' below).

Print button: Click this to print the list of locations displayed in the window (see 'Printing the locations list' below).

Search location: Enter some text in the text field and the list is updated as you type to show only the locations whose code or description starts with the text you have entered.

view and edit a location's details: Double click on a location in the list - see 'Viewing and editing a location' below. All the details are editable. See the 'Adding a location' section below for the meaning of the individual details.

Adding a location

Before you can associate an item with a specific location (e.g. Shelf D4, Refrigerator 2, etc.) you must define the locations in mSupply. To add a new location, click on the New location icon in the View locations window shown above. You will be shown the following window, where you can enter the details of the new location:

Code: This is how you refer to the location in mSupply and, for example, what you will select when you set an item's location. Any non-printable characters entered before or after the code will be removed. Any entered in the code (including spaces) will be replaced with an underscore (_).

Description: This is a description of the location e.g. “Top shelf of refrigerator 3” or “3rd shelf up in rack E” to help you identify it or remember something important about it. You will only see this in the list of locations shown above. Any non-printable characters entered before or after the description will be removed. Any entered in the description will be replaced with an underscore (_).

General tab

Under this tab, you enter the location's main details:

Location Type

Select one from the location types you have already entered (see the Location types section above).

  • Each item can have a Restricted to Location type set, and then you will only be able to store that item in a location with that type.
  • See the details about allocating items to particular location types on the 4.01.02. Items - Storage tab page. When you do this is done, the item will only be allowed to be placed in locations that have the matching location type when they are received or moved in the warehouse.

In a synchronised system, this must be done on the Primary server and will restrict items to the same location type in all stores in the system. Introduction of this in an already established system therefore needs to be carefully managed.

Replenishment location type

If you are using the pickface replenishment functionality, this is where you tell mSupply if this shelf location is a Pickface or a Bulk location (or neither, if you neave it set at None).

For details about what these settings mean and how to use the replenishment functionality, please see the 4.22. Pickfaces and Replenishments setup and 4.23. Pickfaces and Replenishments pages.

Parent

Select one from the locations already entered in mSupply form the drop down list. This is the location to which the location you are adding belongs. You cannot set the current location's child location to be the parent (i.e. circular relationships cannot be created).

This is for descriptive purposes and does not have any functional effect in mSupply at the moment (it was used when viewing the warehouse layout but this is currently disabled awaiting upgraded functionality).

Summary

Checking this means that the location is a summary location only and cannot be used for storing items. This is normally checked for all locations that are parents of others.

Comment

You can note anything you need to remember or indicate to others in here. It is only visible if you view the location's details (Item > Show locations, double click on the item in the list) later.

Total volume

The total volume of goods that you can store at the location. Volumes are stored in cubic metres [m3] but other volumes e.g. litres (l) may also be entered, provided the appropriate unit is entered following the number e.g. 5l for 5 litres. See the entry Volume per pack in Item edit - General options. Note that whatever you enter will be converted to and displayed in m3.

Knowing the volume of a location is important if, for example, you are replenishing your stock of vaccines, and you need to know if there is enough space available in the refrigerator in which you store vaccines to accommodate a new order (obviously, you would also need to know the volume of the vaccines that you are ordering).

Priority

The Location priorities are used for two different purposes:

  • When printing a picking slip:
    • By default a picking slip is printed with the lines ordered according to the alphabetical order of shelf locations. This helps the pickers to progress systematically through the store rather than walking a random marathon! However, it is sometimes useful to get mSupply to put certain items, e.g. bulk fluids or fridge items first or last on the picking slip. This is achieved by setting a priority for a location. The priority will override the default alphabetical ordering.
    • A location with a lower priority number will be printed before a location with a higher priority number.
    • All locations with 0 priority are counted as having no priority and will be printed, in alphabetical order, after all locations with a priority.
  • When suggesting stock lines for selection - when the expiry dates are the same:
    • For an item with several stock lines having the same expiry date, mSupply will use location priority to decide which stock line should be suggested first (at the top of the stock line selection list).
    • Locations with a lower priority number will be selected before a location with a higher priority number.
    • If multiple locations have the same priority number, then mSupply will suggest them in alphabetical order of location name.

When locations are first set up, if you do not specify the priority, they have their priorities set to the default of 0

An example of using location priorities to direct selection of stock lines

Let's say we have 7 stock lines of the first expiring batch in the following locations:

Line Location Location Priority
1 M02.04.3B 1
2 M04.02.2A 1
3 M02.06.1A 2
4 M02.04.4A 3
5 B01 4
  • mSupply will suggest the stock lines in this order, sorted firstly by location priority number, and then by alphabetical order of location name.
  • Line 1 is before Line 2 because, alphabetically, M02.04.3B sorts before M04.02.2A.
Hold

If this is checked then goods in this location cannot be selected for issue to customers. Goods can be moved in to, and out of, the location but they cannot be issued from that location.

Putting a location on hold can be useful if:

  • The stock needs to be kept from being issued until some inspection / approval (e.g. quarantine or under bond).
  • The stock is a bulk quantity with the same expiry date as another stock line in another location from which you want stock issued. You can use this feature to force mSupply to always suggest issuing stock of this item from the 'issue' location rather than this 'bulk' location. When you have finished issuing stock from the 'issue' location, and you want to issue the stock that is in the 'bulk' location, you will need to either take the 'bulk' location off hold, or, move all, or some of it (split), the stock from the 'bulk' location. Location priorities (above) is a more elegant way of managing issue of stock of an item with the same expiry date from multiple locations.
Asset this location is part of

If this location is part of an asset that is recorded in mSupply you can connect the location to that asset here. Type the first few characters of the asset's description in the field and press the Tab key on the keyboard to select the asset from a list of those that belong to the current store and have a description starting with what you typed.

When you have selected the asset by double-clicking on it, its description will appear in the field and its code (if it has one) will appear just underneath (Note: if only one asset matches what you typed, it will be selected for you and the fields appropriately populated):

This would be a very useful thing to do for cold chain equipment, for example, so that you can link temperature variations to maintenance schedules and repair requirements etc.

Layout tab

This tab is only of interest for those of you with older versions of mSupply! This tab has been removed in more recent versions because its functionality wasn't particularly helpful. Look out for Open mSupply coming soon, which is planned to have expanded functionality in this area.

Under this tab you can create a graphical plan view of the location in your store. This is useful for helping people to quickly locate any given location and presenting a graphical layout of your whole store. Locations are drawn as either rectangles (for which you enter the top left coordinate and the lengths of the 2 sides) or polygons (for which you enter a number of sequential coordinates which are connected with straight lines). Here's what the various input items mean for a rectangle, the rest we'll show you by the way of an example:

So, as an example, the coordinates are entered as above in the appropriate boxes, then the Draw button is clicked to produce the following display under the layout tab:

This has created a picture of location main1. This is the whole store or warehouse. You can't see the settings but this location will have no parent and will have its Summary checkbox checked (no items can be located here - it's just a summary location for descriptive purposes).

In our imaginary warehouse we have a set of open racking which is 'L'-shaped. We want to draw it in the warehouse so we create the location, call it 'sub1' and set its parent as Main1. If this set of shelves also has other locations in it we would also check its Summary checkbox.

To draw this location we click on the Layout tab and select Polygon as the object type. Click on the Add button to add a coordinate and then overwrite the zeros in the X and Y columns to give the correct coordinates. If you make a mistake, click on the set of coordinates in the list that is wrong and click on the Delete button to delete it. When all six co-ordinates have been entered, click on the Draw button to produce the layout displayed below:

You can do this same thing for all locations so that anyone can easily locate them in your store.

Viewing and editing a location

As you already know from above, to view all the locations you have defined select Item > Show locations. To view and edit the details of a particular location, double click on that location in this list. You will be shown the following window:

General tab

This is the same as the General tab for adding a location (see the 'Adding a location' section above) except that its details are filled in with the details of the location you selected. To edit the details simply overwrite the current value with a new value or select another option as appropriate.

Layout tab

This is the same as the Layout tab for adding a location (see the 'Adding a location' section above) except that the current graphical representation of the location is displayed (if you've already created one). You can edit the plan view of the location if required by changing, adding or deleting co-ordinates.

Stock tab

The Stock tab shows a list of existing stock lines stored in that particular location. A lot of information regarding the stock is displayed in the list and, as with most mSupply lists, it can be sorted on any column by clicking on the column heading:

If you want to know more information about any particular batch in the list, simply double click it and you'll be shown another window with lots of information about the batch, arranged in four tabs:

Deleting a location

To delete location you select Item > Show locations to view the list of locations, double click on the location you want to delete (as if you wanted to view all its details) and then click on the Delete button at the bottom of the window. If you confirm the deletion, the location is removed.

You can not delete a location that has had stock in it. You can achieve the desired result by merging the location that you want to delete with any other location - refer Merging two locations.

Merging two locations

If you want to remove a location from further use in mSupply (for example, you might have accidentally double-entered a location) this command can be used.

When you Choose Item > Merge two locations , this window is shown:

Use extreme caution! This operation will affect all historical records of the location you delete. They will be moved to the location you are keeping. The operation can only be undone by reverting to a backup copy of your data file.

In the window displayed enter the location to keep, and then the location to merge. When you have checked that the information is correct, click the OK button.

Managing stock in locations

mSupply allows stock in locations to be managed according to the volume of stock in those locations provided that:

Whenever stock is being allocated to a location, mSupply allows the user to identify those locations that are either completely empty, or where there is volume available for the selected stock line:

The Show empty radio button is selected here. This is appropriate when trying to find a location for a whole pallet of stock, as pallets can only go in empty locations.

The Show available radio button shows locations that have enough spare capacity to take the volume of the line we are allocating.



Previous: 4.05. Programs | | Next: 4.07. Building (manufacturing) items

4.20. Units

Choose Show units from the Items menu. When you have defined your units, a list is displayed:

Click the New button to add a new unit.

Note that you will need to have sufficient user permissions to use this function.

Do not change the record for one unit into a different unit, as all items using that unit will be updated.

Click the Merge button to merge two units. Note that duplicated units can occur on import of units or a user may duplicate a unit being unaware of one existing already. The below window appears to merge the units. The green boxed unit is the one that will be kept, the red boxed unit will be deleted.

Accounts

Choose Show accounts from the Items menu. This window allows you to manage the range of accounts that can be assigned to items.

Account codes are used when exporting transaction data from mSupply® to external accounting software. Double-click a line to edit its details. Changing an account code or description will affect all items that are assigned to that account.

Click the New button to add a new account.

Fill in the code, description field and select the account type. The field Items that use this account code will display such items for each account code. Account types are Expense, Income and Asset .Click on OK button to add a new account, and Delete button to delete an account.

Previous: 4.19. Inventory adjustments | | Next: 4.21. Forecasting

4.07. Building (manufacturing) items

mSupply provides for a mechanism to manufacture (build) a new item from two or more existing items. A build is a way of recording items you have manufactured. That is, raw materials that are in your stock are used (taken out of stock), and a new stock item is created.

Show builds

From the Items page of the Navigator, click on the Show Builds button:

show_build.jpg

You will be shown the standard find window to enter either the number of recent builds to display, or a particular build number.

You will then be shown a list as shown below:

From this list you should select the required build by double-clicking on it.

New build

From the Items page of the Navigator, click on the New Builds button:

new_build_0.jpg

On choosing this menu item you are shown the build entry window:

If you have restricted access to builds, you will not be able to see cost prices or the profit summary window at the bottom.

The build window has two parts:

  • The top part of the window records the details of the item to be built
  • The lower part lists ingredients that are used in the manufacture of the product.

click the Item to build or to edit icon

and in the next window enter the name of the product you're manufacturing (Syrup in our example)

and this window is displayed where you should complete the appropriate fields:

Adding ingredients manually

Note that ingredients can be added automatically from the Bill of materials tab. If you regularly build the same item, we recommend that you enter a Bill of Materials for the item being built, and use the method outlined under the Using a Bill of Materials heading below.

First, if you are entering a projected build (one that you expect to perform in the future), check the This is a projected build check box. If checked, all items added will be placeholder lines rather than actual stock. Doing this allows you to enter your manufacturing schedule in advance of ordering raw materials. The schedule will be taken into account when ordering to ensure that you will have enough materials in stock when the time comes to manufacture.

  • To add a new ingredient, click the New ingredient button. You will be shown the standard window for issuing goods from stock:

  • Enter ingredients just as you would for entering a customer invoice.
  • Once you have finished entering ingredient lines, click OK to return to the main window.
  • If you wish to edit a line, double-click it, and change the details.
  • To delete a line, double-click it, set it's quantity to zero, then click the OK button.
Adding the item to be built
  • To add the item to build, click Item to build or edit button. You will be shown the Add/edit supplier invoice line window below for receiving goods.

  • The cost price for the item is automatically calculated for you. You may enter the margin or the selling price as you prefer.
  • Once you have entered the item to build, click OK to return to the main window.
  • If you wish to edit the item, simply double-click inside the “item to build” rectangle.
  • At the bottom right of the window in Summary section is a summary of the cost, margin and selling prices for the build.
  • Once you are satisfied with the details, click OK to enter the build into the system. You will be asked if you want to enter the details into stock. If you say yes , the newly created item will immediately be available for issuing to customers. If you click later then the stock will not be available until you open the build window at a later date and enter it into stock.
  • Note that the ingredients used in a build are considered to have been “sold” for re-ordering purposes, and will be counted in your usage.
Finishing build entry
  • Understanding build status codes enables you to know what stage each build is at. The codes are the same as for other transactions.
Each build transaction has a status code:
Code Meaning
nw A new build is being entered, but has not been saved.
sg “Suggested”. A build has been entered, but has not yet been confirmed.
If stock lines have been entered, raw material stock is reduced so
that it is no longer available for other invoices, but the new item is not yet entered into stock.
You should leave builds with this status while manufactured items are “in process” ,
or if it is a projected build for a future date.
cn “Confirmed.” The item to build has been entered into stock.
fn “finalised.” The build can no longer be edited
  • When you click the OK button you may be asked if you want to enter the build into stock. You should only do so once the manufacturing and Quality Assurance (QA) process is complete. You will not be asked this question if there are any placeholder lines (those with a batch of “none”) entered as an ingredient. Such builds are presumed to be for projected manufacturing, and are kept with status sg automatically.
  • To finalize builds, choose File > Finalize builds when the splash screen is showing.
Converting projected builds into an actual build
  • Once your manufacturing of a projected build is about to take place, choose Item > Show builds … to locate the build you want to edit.
  • For each line whose batch is equal to “none” (a placeholder line) you will have to double-click it and choose an actual stock line from the item issue window (either by entering the line number or double-clicking the line you wish to use). Once you have done this, the stock you have chosen will be reserved, and manufacturing can take place.
  • mSupply® calculates the number of items that will result from your build, and clicking on the Print labels icon prints the correct number of labels.
Using a bill of materials

A bill of materials can be thought of as a “recipe” or “formula” for building an item. It records the ingredients, and the quantity of each required to make the finished product. You should create a bill of materials for an item before you come to this screen. This is done in an item's Item details window: see here for details. Screenshots in this section are using Simple Syrup as an example, and for this product a Bill of Materials has already been created.

When you click the “Bill of materials” tab in the build window, this window appears:

First you need to choose the item to be manufactured:

in the next window you need to specify the quantity to be manufactured and other details:

When you click OK, you are returned to the New Build window, and when you click the Add Bill of Materials Button, a window appears where you can confirm or cancel the quantity to be manufactured:

Assuming the quantity is correct, click OK, and you are returned to the New Build window, where the open tab is the Bill of materials tab. Click the Add Bill of Materials button, and the details on the Bill of Materials according to the formula previously entered for Simple Syrup is displayed:

Now click the Ingredients tab, where the ingredients are listed, but no stock is attached to any item - they are placeholder items (displayed in red). This is done as mSupply® cannot take into account all the factors that go into choosing an appropriate batch to use for each manufacturing run (The expiry, amount on hand, etc). click each line in turn to select the quantity and batch number of available stock lines for each ingredient. Note that there is a button displayed Re-distribute all. Clicking this button will take the “total quantity issued” figure and re-distribute it over the available batches, making it easy to move from using a placeholder line to issuing actual stock. The ingredient is repeated in black with appropriate details displayed. At this time (or later) you can also adjust the amount issued to reflect actual issued quantities and the actual batches of raw materials used, as opposed to the theoretical quantities that are initially entered.

If you are manufacturing the product immediately, the status of the build transaction should be changed to Confirmed on completion of the manufacturing process.

It's possible to print either a Pick list, detailing the ingredients and quantities, or a summary of the manufactured product. To achieve this, check the print icon in the bottom right hand corner of the window and click the OK button. The printing options window will appear and you can choose which document to print:

Calculate Yields button: This button (on the Bill of materials tab) compares the actual quantities issued and the actual final quantity manufactured with the theoretical amounts that should have been used and made. This allows you to monitor production efficiency. Use the Print yield report button to print the yield information if required.

Previous: 4.06. Stock locations and location types | | Next: 4.08. Merging two items

4.04. Item master lists

Updated: Version 3.1

Master lists are standard lists of items you would supply to wards, clinics, etc. on a regular basis. Once set up, a master lists can be assigned to customers or Virtual stores, and then used to support Stock Control including imprest orders. Master Lists are useful to stores which have a number of customers or virtual stores that they supply whose lists of stock items are either identical or very similar.

Choosing the Item > Show item master lists… menu item or clicking on the Master lists button masterlisticon.jpg on the Item tab of the navigator displays a list of the current master lists in your datafile in this window:

If the list oif master lists is long, you can tyoe something in the Search master lists field and the list will only show master lists that contain what you have typed.

Master lists can only be managed (created, deleted, edited, applied to stores or customers) on the Central Server in a synchronisation system.

Buttons on the Show master lists window

Add master list

Click on the Add Master List button and you are presented with this window:

Description

Enter the name of the master list here - this is the list name that everyone will see e.g. All items: General warehouse. Any non-printable characters entered before or after the description will be removed. Any entered in the description will be replaced with an underscore (_).

Note

Add any note or information here that will help you and others understand what the list is for.

Discount %

The % discount to apply to sell prices for the items on the masterlist when they are issued on a customer invoice. Will not affect prices on prescriptions. The discount is applied after other sell price calculations or substitutions are made.

Automatically add new items to this master list

If you check this, any new items created, whether manually or during import, will be added to the master list. This is a particularly helpful setting when you are using master lists to control the visibility of items in stores.

This master list is a patient list

If checked, this tells mSupply to use the prices on this master list for any of the items on this list on prescriptions (not customer invoices).

Is default price list

If checked then tells mSupply to use the unit prices set on this master list as the unit sell price for those items instead of other prices. This price will be applied ot prescriptions as well as customer invoices.

Buttons on the Master list window
Add item

You then populate the list with the required items by clicking the Add Item button:

  • On entering the first few characters of the item to be ordered and pressing the Tab key, the (by now!) familiar list will appear from which the desired item is selected by double-clicking.
  • If the imprest system is used in your organisation, the quantity is entered in the Imprest Quantity field. If the imprest system is not being used, you don't have to enter anything in this field.
  • If you want this list to determine the price of this item for customers using it, the price is entered in the Price per unit field. If not, no entry is required in this field.
Remove item(s)

To remove one or more items from the master list, select (click) the row(s) and then click on the Remove item(s) button.

When master lists are controlling visibility of items (see the 26.07. Virtual stores page for details) then removing an item from a master list will make it invisible in all stores where that master list is used. However, if there is stock of that item in the store, the stock remains visible and can no longer be distributed to a recipient, it can only be removed with an inventory adjustment or sent back to the supplier on a supplier credit.

Save sort order
  • The order in which the items are ordered dictates the order in which they populate various transaction forms in mSupply.
  • Clicking on any of the column headings allows you to sort the list according to that heading.
  • You also have the ability to click on an item in the list, and drag it to a new position.
  • Once you are happy with the sort order, click this button to save the order.
Copy to clipboard

The master list is copied to the clipboard when this button is clicked so that you can paste it into other applications on your computer e.g. a word processor or spreadsheet application.

Update prices to 12 month average

Also only visible if the Use program pricing preference is turned on (see the 15.03. Invoice preferences page for details). When you click this button, mSupply calculates a weighted average price for each item from all the cost prices on all supplier invoice lines that were confirmed in the 12 months previous to the current day for each item. That calculated price is then shown for each item in the Price column. When you click on the OK or OK & Next buttons these prices will be saved on the master list, if you click on the Cancel button the prices will revert to what they were before. mSupply will create logs when the function is run so that you have a record of the old and new prices - see the 25.19. The system log page for details on viewing the logs.

Import item list

You can import a list of items created elsewhere e.g. an accounting application or a spreadsheet. This can save you a lot of time when creating a master list!

The file to be imported must be tab delimited text file, which is most easily created in a spreadsheet. The file must contain columns in this order:

  • Item code Must match an existing item code.

    If you are not importing imprest quantity or price, then this is the only column needed. The following columns are not required.

  • Item name For information purposes only and is not actually imported. You can leave this column blank if you like, however, if you are importing imprest and / or price data, then you must include the column, it's just that the entries can be blank.
  • Imprest quantity Optional and can be left blank. You would leave the entries blank if the master list is not going to be used for an imprest.
  • Price Optional and can be left blank. You would leave the entries blank if the master list is not going to be used for pricing

Records in the file are, of course, separated by the end of line character, which will be created by the spreadsheet when you save the file as a Text (Tab delimited) format.

For example:

Item code Item name Imprest quantity Price
amo250t amoxycillin 250mg tab 800 4.50
amo500t amoxycillin 500mg tab 300 5.50

Clicking on the Import item list button takes you to a prompt:

add_itm_mstr_import_alert.jpg

after which you can select the file:

add_itm_mstr_import_file_select.jpg

And then the import preview dialogue box is displayed:

On this screen you use the Next and Previous buttons to move through the records and see what details will be imported for each. The First line contains column headers tells mSupply whether to ignore the first record in the import file (checked = ignore first line of file). The first record in the import file often contains headers describing the fields in each record, not actual data.

The Remove quote characters on import checkbox, if checked, tells mSupply® to strip all “ characters from the data. This is recommended. In fact, this option can be selected anyway without detriment to the import.

  • Any new items on in the import will be added to the end of the master list.
  • If you import items that are already on the master list, they will not be added to the end of the list. The existing entries will have their Imprest Quantity and Price details updated with the imported values.

Clicking the Import now button executes the import with the settings you made and takes you back to the master list screen with the imported items now showing in your master list.

The Cancel button also takes you back to the master list screen but, obviously, does not execute the import.

Search field

If you need to find a specific item in the master list you can type something in the Search items field just below the buttons. Only the items in the list with a name or code that contains what you typed will be shown, all others will be hidden.

Tabs on the Master list window
Items

Shows the list of items on the master list.

In use by

Shows which customers and stores the master list has been assigned to:

The table contains a list of all the stores and facilities (non-store names) that are visible in the current store. The stores or facilities that are already using this master list have the checkbox in the Uses this master list column checked. The xxx/yyy figures just below the table on the right hand side show how many names are currently displayed in the list (xxx) and how many names in total are visible in this store (yyy).

  • To assign a master list to a store or facility (non-store name) in the list, simply check its checkbox in the Uses this master list column.
  • To remove a master list from a store or facility uncheck its checkbox in the Uses this master list column.

If the list of names is long there are a few things you can do to find the ones you want and quickly set or unset master lists for them:

  • Check or uncheck the Store or Facility checkboxes to turn on and off the display of Stores and non-store names in the list.
  • Type something in the Search Names field. The list will only show stores and facilities that contain what you type in this field.
  • Click the All on button to check all the checkboxes visible in the Uses this master list column.
  • Click the All off button to uncheck all the checkboxes visible in the Uses this master list column.
Tags

Master lists can have tags applied to them to identify them for certain configurations. The tags applied to the master list will be shown in the Tags section.

To add another tag, simply click into the box inside the Tags area and type then name of the tag to attach. Click off the tag and the tag will be added. To remove any tag, simply click on the small 'X' in its top left hand corner.

Program settings

Master lists can be used to define programs. This is the tab where program settings are made, to see all the details please see to the 4.05. Programs page.

Delete master list

From the Item Master lists window, selecting the Delete Master List button allows you to delete a list which is no longer required.

  • This action has significant consequences for any customers who are users of the list. So to prevent accidental deletion, this action cannot be completed until any customers who are users of it have their assignment with it removed.
  • To find out which customers and stores the list is assigned to, open the master list and click on the In use by tab. If the list on this tab is empty, you will be able to remove the master list. Refer to the Assigning a list to a customer section below and the 25.08. Virtual stores page to remove the master lists from customers and stores respectively.
Duplicate master list

Should you wish to create a Master list which is very similar to an existing one, click on this icon, and a new Master list with the same name (description) but with ` (Copy)' appended to it is created; this can then be edited and renamed to suit your requirements.

Report

To create a custom master list report, click on the Report button on the Master list window. This will open the custom report editor and you can create your custom report there.

Print

To generate a built-in report based on all the master lists in the list, click on the Print button on the Master list window. You will be given the following options:

  • General: This report shows some of the simple settings for all the master lists (whether it is a program, whether it is a patient list, whether it will have new items automatically added to it etc.)
  • Cross tab: Item vs Master list: Opens directly in Excel. The rows are all the items on master lists, the columns are all the master lists and the cells contain Yes if the item is on that master list.
  • Items without master list: This shows all the items in your datafile that are not included on any master list.

Assigning a list to a customer

To assign a list to a customer, the customer's details need to be on screen; Choose Customer > Show customers , or using the Navigator, select Show customers , fill in the appropriate details, and press Find, or just press Find, then double click the entry required on the Names list. You will see the name's detail window:

Once the desired customer's Edit Customer/Supplier window appears click on the Item Lists tab to see this window:

Buttons in the Item Lists section:
  • Add Master list: Click this to select a master list to add to the customer from a list of all master lists which have been created. You will see this window:

Double-click on the list you want to add to the customer; the window will close and the selected list will be added.

If the list of master lists is long, you can type something in the Search master lists field, then only lists that contain what you typed will be displayed.

  • Delete list: Select a master list and click on this button to un-assign it from this customer. The master list remains in mSupply, it is not deleted.

When operating multiple stores in mSupply, you can sometimes have difficulty with item visibility: an item might be on a master list for a particular customer but if the item is not visible in the store you are logged into when using the list, then the item will not appear.

A temporary fix can be achieved by setting the item visibility in a particular store to match an item list - refer the Visibility tab. This is only a temporary fix. If you add a new item to a master list, the visibility of that item in the stores using that list will not be updated.

To avoid this problem, you can set a preference (see here for details) to have the visibility of items on lists altered to match the visibility of the name for which the lists are made.

  • Printing:
    • Before printing, choose either Sort by Group or Sort by department
    • Choose whether to send to Excel® or your printer.
    • Click Generate
Information button
Edit list properties

The attributes of a list are set by double clicking on the name of the list. This window is displayed:

The options should be checked as appropriate:

  • Imprest: If checked, this list will populate an imprest customer stock history created for the customer.
  • Customer stock history: If checked, this list will populate a customer stock history created for the customer.
  • Ordering list for web: Means that the list represents all items that the customer can order using the mSupply Customer interface. If a customer who uses the customer interface for ordering stock does not have a list with this option checked, they will not be able to order any items.
  • Price list: Means that the prices on this list will be used for these items when they are being distributed to this customer on a customer invoice. The price on this list will override any sell prices that individual stock lines have. Only one list can have this option checked for each customer.

Using master lists to control item visibility in stores

You can use master lists to control item visibility in each store. This will make the items visible in each individual store match exactly the items included in the master list(s) selected for that store.

Control of item visibility by master list can have drastic unintended consequences!
It affects ALL stores in the system.

  • Do not turn it on unless you know what you are doing!

One unintended consequence: An mSupply store can only order from another mSupply store those items that are on master lists which have been assigned to both stores.

For example:

Central store has the following master lists assigned:

  • All items (includes all items in the system)
  • HIV items

Kathmandu store has the following master lists assigned:

  • HIV items
  • TB items

Kathmandu store tries to place order from the Central store for:

  • Items on the HIV items master list. This succeeds, because both stores have been assigned the HIV items master list.
  • Items on the TB items master list. This fails because the TB items master list has not been assigned to the Central store, even though the TB items are all included in the All items master list .
Procedure - item visibility

For example, let's say there are 100 stores, and you want all of them to have the same item visibility:

  1. Create a master list and add some items
  2. Go to each store and make sure that the master list is selected
  3. Turn on the preference:
    Automatically update item visibility in all stores to match master lists used by each store

    A temporary list is created for each store containing items that cannot be removed from visibility when the master list preference is activated, normally because there is stock of the item in the store.

  4. Now whenever an item is added or removed from this master list, the preference will automatically update the visibility for all of the 100 stores, so that the items visible for each individual store matches the items included in the master list.
  5. Adding an item to a master list will automatically add that item to visibility for all stores using that master list
  6. Deleting an item from a master list will automatically remove that item from visibility for each store using that master list, provided that it is not included in another master list in use by each store respectively.

When deleting items from a master list, mSupply will first check all stores using the master list to make sure it is safe to remove that item. It is unsafe if the item has stock on hand and isn't included in another master list for any stores using master list you are editing.

If you've been running your mSupply for some time without controlling item visibility by master list and you now want to move to it, you will likely want to start by creating a master list containing ALL items and applying visibility to all existing stores according to that ALL items master list. Then, over time, different master lists can be created and applied to those existing stores.

To create a ALL items master list, you can export all items, and then import them to the master list, refer above.

Master list Tips

Creating a re-ordered master list

You may need to create a new master list which is similar to an existing one, but with significant changes, including, particularly, changing the sort order.

Small master list:

If this is a small list, this is relatively easily achievable by:

  1. Select 'source' master list
  2. Duplicate it to the new master list
  3. Add any new items to the temporary master list
  4. Re-organise the list to the desired sort order
Large master list:

However, if the list is a long one, then the re-organising can be extremely tedious, especially over a dodgy internet connection to the Central server (editing master lists must happen on the Central Server)! This is best achieved by:

  1. Select 'source' master list
  2. Duplicate it to a temporary master list
  3. Add any new items to the temporary master list
  4. Copy to clipboard (using button)
  5. Open a blank Excel sheet and Paste the clipboard in to cell A1
  6. Delete the first four lines in the spreadsheet
  7. Filter the table of data
  8. Do the necessary edits including any re-ordering
  9. Save as a tab separated values text file
  10. Back in mSupply, create your new master list from scratch (Add master list button).
  11. Import master list (using button)
  12. Once you've verified that it worked the way you wanted it to, Delete the temporary master list
Re-order existing master list

This method can even be used to effectively re-order an existing master list, but be careful; stop any syncing if in a synced system, and take a backup of your datafile before embarking on this:

Method 1:

  1. Stop syncing (if in a synced system) and make a backup.
  2. Create your new, correctly ordered master list as described above.
  3. Assign this list to all the same names as the original master list was assigned to.
  4. Unassign the original master list to all names
  5. Delete the original master list
  6. Rename new list

Method 2:

  1. Stop syncing (if in a synced system) and make a backup.
  2. Create the tab delimited text file for your new, correctly ordered master list as described above.
  3. Delete all but one of the items on the original master list. This one item is ideally the item that will be at the 'top' of the reordered list.
  4. Import the tab delimited text file to the original master list.

This is scarier (deleting items of master lists is a big deal), but avoids the need for steps 3 - 6 of Method 1.

Removing an item from a master list when it is currently in stock

There are a number of circumstances under which you will need to remove an item from a master list when it is currently in stock including:

  • The item is being phased out and you don't want facilities to be able to order it
  • The item should never have been on the master list and users have accidentally recorded stock of the item

In these cases, it is relatively straightforward to remove an item from a master list - except that if your system is using master lists to control item visibility in stores, then:

mSupply will not allow you to remove an item from a master list IF any store that is assigned to that master list has:

  • The item currently in stock AND
  • The item is not on any other master list assigned to that store.

There are two options open to you:

Wait for all stock to be removed

Wait for all stock to be removed from all the affected stores before you remove the item(s) from the master list. This is a particularly painful process if there are many affected stores. While you are waiting for the last store to remove the item, other stores can continue to receive and stock the item!

Use a temporary master list to assist with the process
  1. Create a temporary master list with the item(s) to be removed.
  2. Assign the temporary master list to all the affected stores that still hold stock of the item(s).
  3. Remove the item from the original master list. This should now be possible as the condition above should be met.
  4. As each store removes the stock of the item(s), un-assign the temporary master list from the store.
  5. Once all stores have removed stock of the item(s), the temporary master list can be deleted.



Previous: 4.03. Item categories | | Next: 4.05. Programs

4.08. Merging two items

If an item has inadvertently been added twice, with slightly different descriptions, here is your safety line! Choose Merge two items… from the Item menu. This window is displayed:

In the Item to keep box type the first few characters of the item you want to keep and press the Tab key. Then select the correct item from the list displayed (if only 1 item matches what you have typed it will be put in the box for you without the need for selection).

Now do the same in the Item to merge - will be deleted box. The item you select here will be completely replaced with the one in the Item to keep box.

Note that when selecting these items you are selecting from all of the items in your datafile, not just those visible in the store you are logged-in to.

When you are ready, click on the OK button. BUT BEWARE:

Merging items transfers the transaction history from the merged item to the item you keep. If you merge “Something innocuous” with “Something deadly”, then, for example, the patient history will show that you issued “Something deadly” to everyone who actually received “Something innocuous”.

Merging items is IRREVERSIBLE. If you merge two items when you didn't mean to, we are willing to help, but could take many hours and we charge a special penalty rate for people who do things after having been warned ;-)

Notes:

  1. Merging replaces all the instances of the item selected to delete with the item selected to keep throughout everywhere your datafile.
  2. Merging items affects all historical records except for item names on finalised transactions, which will retain the original name for safety reasons.
  3. Items that either have a bill of materials or are used in a bill of materials cannot be used for the item to delete/merge. If you try to do so, you will be warned.
  4. If the item you are merging/deleting has stocktake lines associated with it, these stocktake lines will be deleted, as you can't stocktake a non-existent item (except if you're Harry Potter).



Previous: 4.07. Building (manufacturing) items | | Next: 4.09. Ad hoc items

4.10. Non-stock items

There are occasions when you need to order an item that you wish to add to your stock list, but which you currently do not wish to keep in stock. mSupply® treats such an item as a Non-stock item. Although you do not hold any stock of a non-stock item, it is quite likely that you may place regular orders for it.

Note that ad hoc items are different to non-stock items in that:

  • ad-hoc items do not display in your list of items
  • it is likely that an ad hoc item will be ordered once and once only

The procedure for dealing with non-stock items is:

Step 1

The example used here to demonstrate this is for non-stock item Penicillamine 250mg tablets.

From the Item menu, select New item, and enter the particulars as you normally do, only this time check the Non-stock item box. In the box immediately below, select the customer from the list of customers held in mSupply®.

  • To place an order for a non-stock item, a customer must be identified, and this customer becomes the default customer for the item.
  • Should you need to order the same item for a different customer at a later date, the new customer is entered at the time the Purchase Order is being created.
Step 2

Create the Purchase Order which will include the non-stock item. (from the navigator - Suppliers/+Purchase Order/+new line)

Step 3

On receiving the order, proceed as usual to the New Goods receipt form.

In our example, we have ordered 2 items from IDA, one of which is our non-stock item, Penicillamine 250mg tablets, and it appears in blue.

The Goods Received must be finalised in order to create the Supplier invoice:

Uncheck the Hold box ( bottom left corner) then click on OK, and this Alert message is displayed:

advising you that 'Customer invoices have been created for non stock items……': From the main menu, choosing Customer > Show invoices allows us to select and process the invoice which has been created automatically for the non stock item for our customer, the Dispensary.



Previous: 4.09. Ad hoc items | | Next: 4.11. Managing drug interaction groups

4.18. Phased stocktakes

General

Phased stocktakes are commonly carried out in larger warehouses. In this type of stocktake, stocktakes are created for each aisle and level combination in the warehouse. When a stocktake is finalised then a new stocktake is created from it containing only the lines with discrepancies. When the third count is finalised then adjustments are made to make the stock in mSupply match any discrepancies. Thus, there is a maximum of 3 phases for each stocktake.

Setup

Store preferences

Before using phased stocktakes you must tell mSupply which parts of your shelf location codes (see the 4.06. Stock locations and location types page for details) represent the aisle, level and position of the location (aisle = rack, level = horizontal level within the rack, position = vertical 'column' within the rack).

See the 26.07. Virtual stores page for details on how this is set.

Confirm Customer Invoices

mSupply will not allow stock that is on a Customer Invoice with status of new (nw) or suggested (sg) to be taken out of stock by any other transaction process, including an inventory adjustment flowing from a stocktake - refer Creating inventory adjustments.

It is HIGHLY RECOMMENDED to process (take the stock off the shelves) and confirm any customer invoices with a status of new (nw) or suggested (sg) before doing a stocktake - please see Issuing Goods to a Customer (Customer Invoices), Confirming an invoice for details on how to do that.

This is so important that mSupply will show you a warning message when you try to create a new stocktake if it detects any customer invoices with suggested status. Please read the warning and take suitable action.

Creating a phased stocktake

Choose Items > Show Stocktakes… from the menus or click on the Stocktakes button on the Item tab of the Navigator. This window will open, showing a list of the current stocktakes:

Note that only phased stocktakes will have a value in the Reference column.

The Show: filter allows you to choose which stocktakes are displayed in the list. Options are:

  • All: shows all stocktakes in the current store with any status for all time. Could be many of them!
  • Current: selected by default when the window is displayed and shows all 'suggested' stocktakes (status = sg). These are stocktakes which have not yet been processed into inventory adjustments (finalised; status = fn)
  • This year: shows all stocktakes of any status that have been created in the current year.
  • Last year: shows all stocktakes of any status that were created in the year before the current one.

To create a phased stocktake click on the New phased stocktake button. The options window opens:

  • Count reference: This is mandatory and is the unique reference for this phased stocktake (that is, the collection of all the individual stocktakes that makeup this one). It must be unique so you will be shown an alert if it isn't.
  • Item filter: Make settings here to select the stock that is included in the stocktake. The filters work the same as for standard stocktakes as described on the 4.17. Stocktakes page.
  • Stock location: Here you can select a particular aisle or level of the warehouse to include in the stocktake. Enter the identifier of an aisle in the Aisle textbox or the identifer of a level in the Level textbox:
    • If you enter an Aisle value only, then a stocktake will be created for each level in that aisle.
    • If you enter a Level value only, then a stocktake will be created for that level in each aisle in the warehouse.
    • If you enter an Aisle and Level value then a single stocktake will be created for the level in the aisle specified.
    • If you enter neither value then a stocktake will be created for every level in every aisle in the warehouse.

When you click on the OK button mSupply will create a stocktake for each level in each aisle you have selected to be included in the phased stocktake. Each stocktake will contain one line for each line of stock found in a location that beloings to the aisle/level combination that the stocktake is for.

When the stocktake creation is complete you will be told how many stocktakes were created in an alert message. When you close the message, the stocktakes will be displayed in the table like this:

The reference in the Reference column is constructed as Count reference-Number-Aisle-Level/Phase where:

  • Count reference is the Count reference value entered in the stocktake options
  • Number is an incrementing number starting at 1 and padded to 5 digits with leading zeroes
  • Aisle is the aisle this stocktake is for
  • Level is the level this stocktake is for
  • Phase is the phase of this stocktake, a number from 1 to 3

Carrying out a phased stocktake

To open a phased stocktake, double click on it in the list. The stocktake detail window is opened:

  • Description: An editable description of the stocktake. Set to the date the stocktake was created followed by “Stocktake” by default
  • Reference: The count reference, read only
  • Comment: Enter anything you need to remember about this stocktake
  • Stocktake date: the date the stocktake count was started, set to the creation date by default

The table in the above screenshot shows the default columns. If any of the custom stock fields in File>Preferences>Stock tab or Adjustment reasons are enabled then columns will also be included for them.

The next thing to do is to print out the count sheets so that the warehouse operatives can take them into the warehouse to carry out the count. At this stage, when the stocktake is at sg (suggested) status, this is the only thing you can print and it looks like this:

NOTE: When the Reference value ends in /1 the count sheets contain a line for every location in the aisle/level combination this stocktake is for. These are the blank lines with a value only in the Location (Emplace) column. When the Reference value ends in /2 or /3 then only lines in the stocktake are printed.

Using the count sheets, the warehouse operatives count the stock in the warehouse.

After counting the stock

After counting the stock, the count sheets are brought back to mSupply and the information is entered into the stocktake.

The stocktake is completely blind so the batch, expiry date and number of packs of each line entered on the count sheets should be entered in the Counted batch, Counted Expiry date and Counted number of packs columns. Optionally, you can enter a value in the Comment column if there is something you need to remember about this line.

To enter something in one of the columns, simply click into it and type what you want to enter. If you need to enter more than the batch, expiry date, number of packs or comment then double-click on the line to make more fields available for entry:

  • Counted number of packs: The number of packs counted on the shelf
  • Pack size: The number of units that are in a pack
  • Batch: The batch of the stock
  • Expiry date: The expiry date of the stock. Enter is manually or select it by clicking on the calendar button
  • Location: The location the stock was found in. Type the first few characters of the location and press the Tab key to select the location from a list of locations that begin with what you typed (if there is only one that matches then it will be selected and filled in for you)
  • Donor: The donor of this stock (only shown if the option to track donor is turned on - see the 16.03. Invoice preferences page for details). Type the first few characters of the donor's name and press the Tab key to select the location from a list of locations that begin with what you typed (if there is only one that matches then it will be selected and filled in for you)
  • Adjustment reason: Only displayed if adjustment reasons are turned on (see the 16.10. Options (standard reasons) page for details). Required if it is turned on. Click on the drop down list to select the reason for the difference between the snapshot and counted number of packs.
  • Cost price: The cost price of one pack
  • 12 month average checkbox: Check this to replace the cost price with an average of the cost prices for stock of the same item received in the last 12 months
  • Sell price: The sell price of one pack
  • Hold: do not issue: If checked then the stock line is on hold and cannot be issued. WARNING: if you turn this checkbox on and save the line then it is put on hold immediately, it does not wait until the stocktake is finalised.
  • Custom stock fields 1-4: Fields for these will be displayed at the bottom if they are turned on in File>Preferences>Stock tab. Enter text values as required.

If a new line of stock was found which isn't in mSupply then add it using the New line button (see the Add a new line to a stocktake section below for details).

When all the count sheet details have been entered into the stocktake and checked, it is time to finalise the stocktake. To do this, click on the Finalise button. After confirming that you want to finalise the stocktake, this will do two things:

  1. The stocktake will be made read-only and no further changes can be made to it.
  2. If there are any differencies between the the batch, expiry date or number of packs that were entered for a line and the actual batch, expiry date or number of packs of the stock line in mSupply then:
    1. if the Reference value of the stocktake ends in /1 or /2, a new stocktake containing only the lines that showed a discrepancy is created. This sticktake will have the same reference value as this stocktake except that its phase number will be incremented by 1. So, if the Reference ended in /1, the new stocktake's reference will end in /2, if it ended in /2 then the new stocktake's reference will end in /3.
    2. if the Reference value of the stocktake ends in /3 then inventory adjustments are created to make the stock of the lines with discrepancies match what was counted in the stocktake. Note: any lines that only have a discrepancy in the batch or expiry date will not appear in an inventory adjustment but the changes will be made and logged.

If there are no differences between the batch, expiry date or number of packs that were entered for all lines and the actual batch, expiry date or number of packs of the matching stock lines in mSupply then nothing further is done and the user is shown an alert message to say that the count for this aisle/level combination is complete.

Note that a line that has had nothing entered for it in the stocktake is counted as having a discrepancy and will appear in a further stocktake or an inventory adjustment after a stocktake has been finalised.

Add a new line to the stocktake

To add a new line to the stocktake (for stock that you find during the stocktake that is not in mSupply already), click on the New line button. This window will open:

Enter the first few characters of the item the stock is for in the Item text box and press the Tab key on the keyboard to select the right item from a list of items beginning with what you typed (if there is only one item that matched it will be selected for you and entered in the Item text box).

Now enter the details of the stock in the New stock line section:

  • Counted number of packs: The number of packs counted on the shelf
  • Pack size: The number of units that are in a pack
  • Batch: The batch of the stock
  • Expiry date: The expiry date of the stock. Enter is manually or select it by clicking on the calendar button
  • Location: The location the stock was found in. Type the first few characters of the location and press the Tab key to select the location from a list of locations that begin with what you typed (if there is only one that matches then it will be selected and filled in for you)
  • Donor: The donor of this stock (only shown if the option to track donor is turned on - see the 16.03. Invoice preferences page for details). Type the first few characters of the donor's name and press the Tab key to select the location from a list of locations that begin with what you typed (if there is only one that matches then it will be selected and filled in for you).
  • Adjustment reason: Only displayed if adjustment reasons are turned on (see the 16.10. Options (standard reasons) page for details). Required if it is turned on. Click on the drop down list to select the reason for the difference between the snapshot and counted number of packs.
  • Cost price: The cost price of one pack
  • 12 month average checkbox: Check this to replace the cost price with an average of the cost prices for stock of the same item received in the last 12 months
  • Sell price: The sell price of one pack
  • Hold: do not issue: If checked then the stock line is on hold and cannot be issued. WARNING: if you turn this checkbox on and save the line then it is put on hold immediately, it does not wait until the stocktake is finalised.
  • Custom stock fields 1-4: Fields for these will be displayed at the bottom if they are turned on in File>Preferences>Stock tab. Enter text values as required.

When you've added all the details click on the Add new button to add the line to the stocktake. It will appear at the bottom of the table of stocktake lines.

Delete a line from the stocktake

To delete one or more lines from the stocktake, select them in the table and click on the Delete line(s) button. After confirmation the selected lines will be deleted.

Please note, you can only delete lines from the stocktake that you manually added to it uysing the New line button.

After finalising a stocktake

After finalising a stocktake the stocktake becomes read-only but you can now print out an In progress stock count sheet from the Print button. This is what it looks like:

When you finalise the last stocktake with the same Count reference (as entered in the options window when creating the phased stocktake) then you will be asked if you want to print out the Stock comparison report, which will show you all the discrepancies recorded in all the stocktakes with the same count reference.



Previous: 4.17. Stocktakes | | Next: 4.19. Inventory adjustments

4.13. Prices in mSupply

mSupply has many different mechanisms for altering the sell price of items in invoices depending on many things. Below in this article:

  • Item Margins
  • Per customer price lists

Elsewhere:

Customisations for certain clients (give us details of your situation, and we may be able to extend the functionality to your needs). Ask about:

  • Unified selling price (built off Catalogue Price)
  • Weighted Average Price (Built off Catalogue Price and similar to below two)
  • Price averaging derived across supplied cost prices at each store
  • Price averaging derived by the central warehouse applied to master list

Pricing With Default Settings

There are two key values associated with all stock and invoice lines:

  • Cost price: this is simply the price that the store paid the supplier for the goods.
  • Sell price: this is recorded price that is expected for the goods to be sold to customers at. There are many pricing strategies that modify or override this value throughout mSupply which we'll detail below.
1. Purchase Order (PO)

At the first instance, stock is often introduced into the supply chain via a purchase order. Each item ordered will have a price per pack which is carried through the next steps.

Note in this instance, the supplier uses the currency AUD. Our system is using USD. This Forex (Foreign exchange) rate will be used later.

2. Goods Receipt (GR)

Next a user would create a Goods Receipt linked to this Purchase Order in order to accept the physical stock arriving. They'd add the lines from the original PO and enter the verified count of items into the GR. Finalising this GR will create a Supplier Invoice.

3. Supplier Invoice (SI)

A Supplier Invoice is automatically created by the GR of the previous step. This invoice, also known as a transaction, is used to record the ledger of the stock entering the mSupply stock system.

At this point the user has an opportunity to adjust cost and sell price.

Note:

  • The currency exchange rate has been applied (and can be further edited).
  • There is an opportunity to apply a margin. It has been set to 10%. (there are multiple places in mSupply to configure default margins)
  • A sell price per pack is first recorded here. It is 10% higher than the cost price. It can be further edited manually.

Once finalised this will be available as stock in mSupply

4. Checking introduced stock

Under the Items menu, you can search for and view our item's stock. Note the other lines of stock which have different cost and sell price. This is because this stock was received or added at another time, with different prices applied at the time. All stock has it's own cost and sell price associated. Keep in mind that there are settings for centrally controlled sell prices for items, so that all customers pay the same amount regardless of the specific stock line they're receiving.

Editing our line of introduced stock, we can modify cost and sell price again.

5. Customer Invoice (CI)

If we create a new customer invoice to a facility, when adding an item we'll see our stock line is available with the prices carried through from the supplier invoice that introduced the stock.

Now added, we can see in our Customer Invoice the stock we added and see that it's Price Extension (the total sell price for the line) is 5x the sell price, as we are providing 5 packs.

6. Prescriptions

For a Prescription to a patient, it is much the same as a customer invoice.

The key difference here is that there are several patient specific pricing modifiers that can be configured in mSupply which we'll see later.

Sell Price Settings

At either introducing stock or at the point of distributing/selling/dispensing stock, there are settings that can modify the sell prices saved in the system or simply override the sell price when distributing. Hold on you your hats 😉.

Default Price List

A Default Price list is one of mSupply's approaches to standardising pricing across the whole system. This is useful when you want all customers/patients to pay the same amount per unit of an item regardless of what any particular line's sell price has been set to (usually related to cost price). This is useful when receiving stock from multiple suppliers, via various shipment methods (Air vs sea freight) where prices of different lots of an item received can vary greatly. Some donor stock might be free!

This setting is managed through 4.04. Item master lists. A Master List can be configured as a “Default Price List” by checking the checkbox shown below.

Items in this list will override the sell price of all outgoing stock in all stores across the entire mSupply system, including those that are active on remote sites. To set the price for the item, edit the “Price per unit” column.

Make sure you enter the Price per unit of the item, not the Price per pack. As an item can have many stock lines with differing pack sizes (e.g. blister pack of 10 vs 20), the system will adapt the sell price according to the stock line's pack size multiplied by the Price per unit.

When making a customer invoice we can see that all prices have been adapted when selecting our item from earlier in this guide. The default price is 1 per unit, and the pack sizes have been multiplied by that to determine the sell price.

Any item not in the Default Price List will use the sell price of the stock being used.

The Default Price List applies to prescriptions as well, but note that the similar Patient List setting for setting a global price for patients will override the Default Price List value if an item is in both lists.

Patient Price List

The Patient Price List setting is very similar to the Default Price List setting, but only applies to prescriptions. This is useful if not interested in changing prices for stock being distributed to other sellers/stores/pharmacies, but do want to set a standardised price for patients to level out cost fluctuations of stock.

To make a Master List a Patient Price List, check the setting “This master list is a patient list”.

If an item is in both the Patient Price List and the Default Price List, in a prescription the Patient Price List price will take priority over the default price list.

A Master list may be both a Patient Price List and Default Price List, but it is redundant 😉.

Discount Lists

Discount lists are a simple mechanism for setting a discount percentage rate for a set of items. They can be configured by simply adding a value to the Discount % field of a Master List. This discount rate will be applied on included items in all stores in mSupply.

This will be applied when adding items to a Customer Invoice. Below we can see the the Default Sell Price (per unit) applied to our stock lines has had a 50% discount rate applied. If item selected is not in the Default Price List, it's normal sell price of the stock line selected will be used.

Discount rates do not apply in Prescriptions. We may add settings for facilitating this in the future!

Item Margins

The price you charge customers for your goods is, of course, very important. mSupply provides you with several different ways to set the selling price of your goods. Here they are:

  • Each supplier has a margin field that determines how much to add on to the cost price when buying from that supplier
  • Each item has a margin field that determines how much to add on to the cost price when buying that item
  • There is a preference ( File > Preferences > Invoices 1 ) which controls how these 2 margins relate:
    • If this preference is ticked then the item margin will be used instead of the supplier margin. If it is unchecked then the supplier margin will be used instead of the item margin.
  • You can set custom margins for each customer group ( File > Preferences > Invoices 2 )
  • You can fix the item price under the General tab in the Item details window.
    • Note that setting an item price here will set the price of new stock as you receive. It will not affect the price of existing stock- you can change existing prices if you have permission to do so by viewing an item and going to the “Stock” tab.
  • You can set item prices when setting up a data file by importing an item list. (see below)
Per customer pricing

Updated: version 3.12

Alternatively, individual prices can be set for each customer. This can be done in the Edit Customer/Supplier window which you can find by:

  • going to the Customer tab of the Navigator
  • click on the Show Customers button
  • find the customer you wish to customise prices for
  • double click the customer line
  • choose the Item Lists tab (see below)

To customise the pricing, add a list to the Favourite Lists column (either by clicking Add master list, Add local list or Copy from master list) or edit an existing list by double-clicking on it. Check the Price list checkbox from the window that comes up and any other checkboxes that you require.

  • You only need the Price list check box marked to customise prices
  • Only one list per customer can be price customised

Make sure the list is selected and then go to the Items section of the window. Enter the corresponding prices that you would like to assign to each item for that customer by clicking on the item and then clicking on the price (“0” by default). You can also add items to the list by clicking Add item and entering the item name and the price in the window that appears. The customer will now be charged the prices set in the list instead of any other price set.

Previous: 4.12. Managing item access with Departments | | Next: 4.14. Repacking items

4.05. Programs

There are a number of ways of modelling programs in mSupply:

You can also manage requisitions by program. This involves using some special settings for master lists. In this method, a program is an extension to a master list. A program includes a standard list of items as well as:

  • Order Types: defined categories setting the maximum number of orders and quantity of stock to be ordered per period.
  • Period Schedules: defined time intervals when orders can be placed; schedules and periods must be set up before creating programs.
  • Regimen Data: a defined list of additional information that may need to be provided by a customer when making a program requisition.

Examples of items commonly managed by programs include Malaria, HIV and TB medicines and medical supplies.

4.05.01. Creating a program

A program is defined by additional settings made to a master list:

1. Navigate to the Item tab and click the Master List icon:

2. Double-click on a master list to open it (or create a new master list):

3. The Master list details window opens. Click on the Program Settings tab:

4. This shows all the settings available for a program:

5. Tick the This master list is a program checkbox to enable the program based features for this master list.

  • The HIV program and Immunization program checkboxes now appear. Check the HIV program checkbox if this is to be an HIV program (means extra indicators will be enterable when the program is being used). Check the Immunization checkbox if this is to be used as an immunization program to drive the immunization card functionality in Open mSupply (see the Open mSupply Immunizations page for details).
  • Create a Store tag for the program by clicking on the button just above the Store tag section.
  • The Tag field will be automatically populated with a new tag. Edit this new tag name and click on the button.
  • The field then becomes a drop down list which will contain any existing name tags for you to select. The tick button also becomes a modify button . If you click it you will be able to edit the tag name you just entered.
  • When you click on the OK button any new tags you have created will be saved and will appear in the name tags list (see the 5.05. Name tags page for details).

    You can edit the tags entered here until you close this window. After that, you cannot edit existing ones, you can only delete them and add new ones.

Any customers or stores that have a name tag matching the tag you set here will be able to use this program and the schedule you have set for that tag.

You can define multiple tags for each program.
For each tag, you set up both a schedule and order types- so for one program, you can have different facilities on different schedules

6. Select the Period Schedule from the dropdown list (you must have set up the schedules and periods first):

7. For each period schedule, one or more Order Types can be created - these set the parameters for program requisitions. Add order types by clicking the plus icon.

8. Give each order type a unique name and set its parameters:

  • Emergency: check this box if the order type is for emergencies.
  • Max orders per period: maximum number of orders that can be placed in a given period.
  • Max MOS: maximum number of months' stock to be kept for each item. Used in the calculation of the suggested amount to order.
  • Threshold MOS: items with a number of months' stock less than this value will appear in the order by default.
  • Max lines: maximum number of items allowed to be ordered for an emergency order (default = 5); an alert will appear if the user tries to exceed the maximum number of items allowed.

4.05.02. Adding indicators to a program

Indicators are used for reporting on the performance of programs, e.g. the number of patients treated. Each indicator value provides data on a metric for a particular store and regimen over a given period. Indicator values are recorded while creating a program requisition.

Indicators can record any relevant programme data, including that data that may be used to select a regimen (defined as a treatment plan that specifies the dosage, the schedule, and the duration of treatment.) The country that funded this feature uses the term Regimen data for all these indicators, and so that term has been used in this window.

Indicators allow an organisation to analyse regimen performance and determine what further data should be collected, stored and processed.

To add indicators to a program:

  • Open the program via the Master List (Click on the Master list icon on the Item tab of the Navigator).
  • Click on the Program Settings tab.
  • In the Regimen Data table add fields for the data that should be provided to the supplier with each program requisition
  • Check the HIV program checkbox if you want a fixed set of HIV-related indicators to be entered for this program.
  • If the customer must provide this information for supply to occur, tick the Is required? box to make this a mandatory requirement.

4.05.03 Connecting a program to a store

To allow a store to place program requisitions:

1. Navigate to the Special tab and click on the Stores icon:

2. Double click on the store.

3. In the Tags field, type in the Store Tag you set for the program and schedule above then press Tab.

4. Click on the Master Lists tab, check the Use master list box next to the program master list to be used:

5. All done - the store is now connected to the program you have created so click on the OK button to save all the settings.

4.05.04. Creating a program requisition

Once a store has been connected to a program, it can then place program requisitions:

1. In the customer store, navigate to the Suppliers tab and click on the Internal Orders icon:

2. Click New Internal Order. When a store uses programs, they will have the option to create a Program order or General (regular) order:

Check the Program button to create a program requisition.

3. In the Order Details section, select the Program, Requisition Type and Period from the dropdown lists. Enter the Supplier by typing the first few letters, pressing Tab and selecting the supplier from the list of those starting with what you typed. These details need to be entered sequentially as the program uses them to determine the requisition type, which in turn determines the period.

The maximum number of program orders that can be requested within a given period is set when the program is created (Max. orders per period).

If you try to create another order for the same period which exceeds the maximum number, an error message will appear and you will not be able to proceed.

4. Click OK to generate an internal order with all the items listed in the program master list. The details relating to the program order are in the top left. Review the data in the table, then enter the quantity of stock to be ordered in the User requested quantity column:

5. Click the Indicators tab to enter the additional data defined for the program:

This data will be sent to the supplier with the requisition when the requisition is finalised.

6. To send the program requisition to the supplier, return to the Data Entry tab, check the Finalise box and click OK.

4.05.05. Creating a program stocktake

Creating a stocktake with items from a particular program is just the same as creating a normal stocktake. The only difference is that you select the program in the Master list (or Program) filter:

1. Navigate to the Item tab and click the Stocktakes icon:

2. The list of stocktakes window opens. Click the New Stocktake icon:

3. Select the program from the Program is (or Master list is) dropdown menu and click the OK button to pre-populate your stocktake with items from the program:

Note: To further refine the selection of stock appearing in the stocktake you can also select other filter items at the same time.

For detailed information on how to complete the stocktake, refer to the 4.17. Stocktakes section.

Tip: In your stocktakes list, you can easily identify program stocktakes by referring to the Program column:



Previous: 4.04. Item master lists | | Next: 4.06. Stock locations and location types

4.14. Repacking items

Creating a new repack

The command Items > New repack will display a window where you can repack a particular item into smaller or larger packs and/or move all or part of a batch to another location. It is a more complex version of the split functionality and will allow you to handle several batches at a time.

There are 4 steps for creating a repack. The window is numbered from top to bottom to help you follow the correct steps:

  1. Choose item to be repacked: At [1.] type the first characters or code of the item to be repacked, then press the Tab key. If only one item text or code matches your entry, it will be filled in automatically, otherwise you will be shown a standard choice list from where you can select the item.
  2. Choose a batch: At [2.] double click a line to choose the batch; for repacking, batches cannot be mixed, and a single batch must be used.
  3. Quantity to be repacked: At [3.] enter the quantity which is to be repacked; the pack size field is automatically completed.
  4. Details of new line(s) - i.e. the repacks: At [4.] click the New line icon to bring up this window calling for the details of the repacks, and enter the details as appropriate.

Note that repacks of different sizes may be created at this stage - e.g. 5,000 Paracetamol tablets may be repacked into 40×50 and 30×100. The Sell price, the Batch number and the New Location are automatically completed, but all these fields may be edited as required.

Not infrequently, because some tablets may be broken, for example, the total quantity of the item re-packed will be less than the quantity selected for re-packing at [2.]. To maintain the accuracy of your stock record, an inventory stock adjustment should be performed - see section 4.19. Inventory adjustments for this.

Printing a repack

While the status of the repacking transaction is suggested (sg), checking the box beside the print icon will produce a picking slip of the number and size of packs of the original item; once the status is finalised, the same operation will give you the choice to produce a detailed record of the re-packs or a stock movement report (for when you're moving stock - perfect for giving to the people physically moving the stock in the warehouse because it shows what is to be moved to which location).

On clicking the OK button, a transaction is created showing the original line taken out of stock, and the new line(s) put into stock. The total value of the transaction is always zero.

You cannot edit a repack transaction after you have clicked the OK button, so get it right the first time! Tip: You can always “re-repack” an item to adjust a mistake however! ;-)

Deleting a repack

If you click on the Delete button, then the repack will be deleted. Only repacks whose status is “sg” (suggested) or “nw” (new) can be deleted.

Viewing repacks

Repacked items can be viewed in the normal transaction list window - (Item > Show repacks) and select Repacks from the drop down list

Note that repacks created with versions of mSupply® prior to v1.4 will not show up using the “recent transactions” section of the window- you will have to enter the number directly.



Previous: 4.13. Prices in mSupply | | Next: 4.15. Show items with stock

4.23. Pickfaces and Replenishments

Before using pickfaces and replenishments there is some setup you need to carry out. To find out about that, see the previous 4.22. Pickfaces and Replenishments setup page. When you've gone through that, you're ready to start here.

Replenishment statuses

Replenishments have two statuses: suggested and finalised. We sometimes refer to suggested as “pending” or “waiting to be actioned” and finalised as “actioned” in the description below.

Like other transactions in mSupply, a suggested status replenishment is only a description of a change that will take place, it has not changed anything in the system yet. The changes (stock movement and repacking) all occur when a replenishment is finalised.

Viewing replenishments and accessing the rest of the functionality

To see replenishments that have been actioned or are waiting to be actioned, click on the Items tab of the Navigator and click on the Replenishments icon:

That will open this window:

By default the window will show all the replenishments that are waiting to be actioned (the Show drop down list is set to All to action). These are all the suggested status (sg) replenishments. You can change this to show all the replenishments (pending and finalised) or to show all the pending replenishments for a particular worker; just select the appropriate option in the Show drop down list and the list will update accordingly.

Automatically generating replenishments for all pickfaces

This is probably the most common way you will create replenishments. To do this, simply click on the Generate all replenishments button and mSupply will work out which locations need replenishing and how much stock should be moved into each one and create a line in the table for each replenishment. You are shown a warning message before the process begins:

This is telling you that if a new replenishment is generated by this function and there is an existing suggested status, unassigned replenishment for the same item in the same pickface location then the existing replenishment will be deleted. If you don't want any replenishments like this to be deleted then click the Cancel button and assign them to a worker (see the Assigning users to replenishments section below) temporarily before running this function.

If you click the Proceed button the replenishments are generated.

This is how mSupply generates the replenishments:

  1. Find all the pickface type locations that have less than the trigger level of stock in them.
  2. For each one of these locations work out how much stock needs to be moved into them to bring them up to their Replenish up to level.
  3. Find out what stock is available for this item in bulk type locations and move as much as is needed using these rules, in this order:
    1. If the item has a preferred bulk location then stock is taken from that location first (ignored if there is no preferred bulk location).
    2. After the preferred bulk location, stock is chosen from other Bulk type locations in FEFO order, smallest batch first.
    3. Full cartons (outer packs) only are moved if possible.
  4. When this process has been done for the pickface locations, the whole thing is repeated for the preferred bulk locations. If you haven't set preferred bulk locations then this part of the process is skipped.
  5. The final step in the process is to delete all suggested status replenishments that are not assigned to a worker, that are for the same pickface location and item as a replenishment just created and were created before this process was started.

After finishing creating all the replenishments, mSupply will tell you how many replenishments it has created and whether there were any errors. The errors you can get are:

  • No bulk stock available: An item's pickface is depleted below the trigger level but there is no bulk stock available to replenish it. This could be because there is no stock of the item available or because none of it is in a location of Bulk replenishment type.
  • Partial replenishment only: A pickface is depleted below the trigger level and there was some stock available to replenish it but not enough to fill it up. This could be because there is not enough bulk stock of the item or because there is not enough of it in locations with a Bulk replenishment type.
  • Deletion failed: This is more a warning rather than an error. It means that a replenishment was created but an already existing, pending (suggested status) and unassigned replenishment for the same item could not be deleted. This will be because the replenishment is in use by being viewed or edited by another user.

Note about preferred bulk stock location replenishment (only applies if you're using them!): the pickfaces are replenished first from the preferred bulk locations as stated above. When the process moves onto replenishing the preferred bulk locations, the pickface replenishments haven't been finalised yet so the stock is still in the preferred bulk locations. This means that mSupply may well not generate many or any replenishments for the preferred bulk locations. So, when some or all of the pickface replenishments have been finalised simply click on the Generate all replenishments button again. mSupply will now see that the preferred bulk locations have less stock in them and replenishments will be generated as needed.

Also note that any stock that is on hold or in a locaiton that it on hold will be ignored and will not considered as being available for being used in a replenishment.

Manually creating a replenishment

If you need to add an extra replenishment manually for any reason you can do it by clicking on the Add replenishment button. This will open this window:

Start typing the name of the item you want to create the replenishment for in the Item field. A list of items with names starting with what you typed will appear below the field. You can keep typing or scroll the list to find the item you want; click on it to select it. Several things will happen:

  • The item name will then be entered in the Item field
  • The item code will be shown just below the Item field
  • The table will be show all the batches available for that item
  • The down arrow icon to the right of the Item field will be enabled. You can now click on it to go straight to the item's details window.

If you chose the wrong one, you can change the item by deleting the name in the Item field, typing again and re-selecting another item.

In the table the blue background columns are editable, the grey background columns are not.

When creating a replenishment you are describing what stock should be moved and where it should be moved to. So, the 'From' columns describe the bulk stock (where it is now), the 'To' describe what it will become in the pickface:

  • From available packs: the total number of packs that are available to move to the pickface.
  • From pack size: the pack size of the stock in its current location.
  • From location: the current location of the stock.
  • On hold: contains a checkbox for each row. If the stock is on hold or the location the stock is in is on hold then the checkbox will be ticked and the line will be disabled; it cannot take part in a replenishment.
  • From number of packs: the number of packs (of From pack size) that you want to move from the From location to the pickface.
  • Worker: the worker assigned to carry out the moving of the stock. Click the appropriate cell to select a user from all those who have the Can action replenishments permission for this store. This is the only column that can be left blank and a replenishment can still be created from the row.
  • To location: the pickface location. Type and select one from all locations in the current store.
  • To pack size: the pack size the stock will have in the pickface location.
  • To number of packs: the number of packs of To pack size that will be present in the pickface after the move.

If the item has a pickface location set then the To location column is filled in with that location and the To pack size column is filled with the pickface pack size as soon as the item has been selected.

If you have entered two of the From number of packs, To pack size and To number of packs values, the third will be calculated and entered for you. If all three have been entered and you edit one of them, one of the others will be edited to maintain the relationship From pack size x From number of packs = To number of packs x To pack size.

When you have finished entering values, click on the OK button (or OK & Next) to save the replenishment. If there is a row of the table that has some values entered but not enough to create a replenishment then you are asked to confirm you wish to proceed because those partialy completed rows will be ignored.

When you have finished creating all the replsnishments, click on the OK button. This window will close and you will return to the main replenishment list window.

Editing a replenishment

Simply double-click on a replenishment in the list to open it for editing. It will be opened in a window like that for creating a new replenishment but only a single line will be shown in the table and the Item field will not be editable:

If you want to edit the item of a replenishment, you must delete the replenishment and re-create it with the correct item.

Edit any of the values in the blue-background columns and click the OK button to save your changes.

Deleting replenishments

To Delete replenishments shown in the main replenishment list window, simply highlight the ones you want to delete in the list (click to select, Ctrl(Cmd)+A, Shift+click and Ctrl(Cmd)+click all work to help you select the right ones) and click on the Delete button.

Finalised replenishments cannot be deleted and will be simply ignored if they are selected for deletion.

After deletion has been carried out you will be told how many replenishments were deleted and how many were ignored.

Selecting all the pending replenishments in the current list

Click on the Highlight pending button and all the suggested status replenishments in the current list will be highlighted (selected).

This is particularly useful if you want to print all the replenishments waiting to be actioned in the current list.

Assigning users to replenishments

Users are assigned to a replenishment to indicate that they are responsible for carrying out or verifying the replenishment. You might wish to select the appropriate forklift driver for example.

To do this, highlight one or more replenishments in the list and click on the Assign user to highlighted button. A list of users with the Can action replenishments permission in the current store will be displayd and you can select which one to assign by clicking on it. The name will then appear in the Worker column of the list for those replenishments that were selected. If you select the None option in the list of users, any worker assigned to the replenishment is removed.

Printing replenishments

To print replenishments, highlight the ones you want to print in the list and click on the Print highlighted button. The usual print options window will appear. After you have selected the appropriate options, click on the OK button and your printout will appear. The default printout looks like this:

The Worker field will show the name of the user assigned to all the replenishments or the word “Multiple” if more than one different user is assigned to the replenishments shown in the list.

The Done column will show the word “Yes” for finalised (actioned) replenishments or will be blank for those that have not been actioned yet. The user responsible for actioning or verifying the movement of the stock can sign or tick in this column when the move has been physically completed if desired.

If there were any problems or differences between what was done and what was shown on the printout, the worker should mark them on the sheet and give that to the responsible mSupply user. The replenishments can then be edited to match what was actually done before they are finalised.

Finalising (actioning) replenishments

Until they are finalised, replenishments do not affect the stock in mSupply.

They should be finalised at a point which suits your physical restocking process in the warehouse; this could be before the stock is physically moved to the pickface location.

to finalise replenishments, simply select (highlight in the table) the replenishments to finalise and click on the Finalise highlighted button. mSupply will then move and repack the stock as required to match the details given in the replenishments.

Please note: any stock that is in on hold or that is in a location that is on hold will be ignored and will not take part in a replenishment.

Authorising pickface replenishments

When authorisation of pickface replenishments is turned on (see the 4.21. Pickfaces and Replenishments setup page for details) the replenishments list has a new Authorised column:

The column contains a checkbox for each replenishment. Only users with the Authorise replenishments permission can edit those checkboxes. When the Finalise highlighted button is clicked, only replenishments that have a checked Authorised checkbox will be finalised, all unauthorised replenishments will be ignored and left unactioned.

Previous: 4.22. Pickfaces and Replenishments setup | | Next: 5.01. Names: using, adding and editing

4.22. Pickfaces and Replenishments setup

In a large, busy warehouse it is sometimes useful to designate some shelf locations as pickfaces. These locations are easily accessible for pickers, usually at floor level or the next level up in the racking. These pickfaces are then replenished from other, harder to reach locations somewhere in the warehouse.

Typically, these replenishments take place at a time when the activity does not get in the way of the busy pickers; at the beginning of the day or lunch time. A forklift driver will fetch the stock from the bulk location and place it in or near the pickface so that others can place it or open the cartons ready for picking.

Deciding which locations to replenish when can be hard to keep track of so mSupply has functionality to help and this is what is described here. There is quite a lot of setup involved so that's detailed on this page. The next page (4.23. Pickfaces and Replenishments) describes the actual functionality and how you use it.

Create pickface and bulk locations

The first thing you need to do is tell mSupply which locations can be used as pickfaces and which are used to store the bulk stock to replenish them with.

If the location doesn't exist in your system create it, if it does then open it for editing (see 4.06. Stock locations and location types for details). You will see this window:

Click on the Replenishment location type drop down list and select the type this location will be:

  • None: The default for all locations and means that the location won't be selectable as a pickface and won't take part in replenishments.
  • Pickface: means that this location can be selected as a pickface for an item and will be replenished.
  • Bulk: means this location stores bulk stock that can be used to replenish pickfaces. Note that mSupply will only use stock in locations with a replenishment type of Bulk to replenish other locations. Any other stock in locations not set as Bulk type will be ignored in the automatic replenishment process. This means it is possible to protect stock that should not take part in the replenishment process by making sure its location has a replenishment type of None.

When you have finished assigning the replenishment type click on the OK or OK & Next button to save the changes. Repeat this process for all the locations that will be used as pickfaces or that will hold bulk stock that can be used to replenish the pickfaces.

Assign pickfaces to items

The next step is to assign pickfaces to items. To do this, find the item you want to set a pickface for and open its details window (see 4.01. About items for details). Then click on the storage tab:

On this tab, enter details in the Pickface and Bulk sections. See the 4.01.02. Items - Storage tab page for details on what the various values mean (Note: these settings are all store specific so have to be set for each store separately).

Define the users who can action replenishments

The final setup step is to tell mSupply which users can action replenishments. These are the users you can assign replenishments to.

Open a user for editing (see 25.15. Managing users for details) and go to the Permissions (3) tab on the user's details window:

Check the Can action replenishments checkbox and click on the OK button to save the changes.

Repeat this for every user who can be assigned to action replenishments.

This now completes the setup and you're ready to use the functionality. See the 4.23. Pickfaces and Replenishments page for details on that.

Authorisation of replenishments

If you want replenishments to be authorised before they can be finalised then follow these steps:

  1. Turn on Pickface replenishment authorisation: This is a store preference. See the 26.07. Virtual stores page for details on turning this preference on.
  2. Give the users who can authorise replenishments the permission to do so: See the 25.15. Managing users page for details on setting user permissions, including the Authorise replenishments permission.



Previous: 4.21. Forecasting | | Next: 4.23. Pickfaces and Replenishments

4.15. Show items with stock

Updated: version 3.12

This can be accessed by choosing Show items with stock from the Item menu or by clicking on the Stock icon on the Item tab of the Navigator. Either of these options will display this window:

By default all stock is listed, and where the stock of an item is present in different batch numbers, each one is displayed.

Just like nearly all the other tables of information in mSupply, you can order the information by any column by simply clicking on the column header. Reverse the sort order by clicking on the same column again.

Customising the list

You can choose the columns displayed by clicking on the Customise button to display this window:

Listed under Available are the columns not presently displayed, and under Chosen are the columns presently displayed. Changes are made by highlighting your chosen column on this window, and moving it using the buttons in the centre to add or remove it from the display.

You can drag the items in the Chosen column into the order of your choice to change the order they are displayed in the list (top of the list is displayed on the furthest left, bottom of the list is displayed the furthest right).

If any of the custom stock fields described on the 16.01. General preferences page are enabled then they will also be included in the Available column for you to display as required.

Printing / exporting the contents of the table

You can export the stock information on the items displayed in the table by clicking on the Export to Excel button. Only the items displayed in the table will be exported and a fixed set of columns will be exported - this set is not affected by any changes you make to the displayed columns using the Customise button described above.

In your spreadsheet application you can manipulate or print the data as you please.

Filtering the list

Entering the item name or code in the box will filter the list; entering the first few characters of an item name will display only those items which begin with those letters (or numbers).

To display a specific item, either the item code or the full name should be entered.

To find all items containing ran enter @ran which will display all items which include the characters entered, not only those items where the characters entered are at the start of the item name - e.g. this will not only display any Ranitidine in stock, but will also display `Pyrantel', `Nitrofurantoin', Propranolol', etc..

Filtering by location

Alternatively you can filter by location. Leave the first search box blank and enter a location into the second search box. This will show only the items with that location.

Even more specific

To view an even more specific selection of stock you can filter by both item name and location. By entering your criteria into both boxes, only the stock which matches your specified name and location will appear.

Editing stock lines

If you have the permissions, you can double-click on one of the stock lines shown in the list and a window will open to allow you to edit some details of the stock line:

See the 4.01.05 Items - Stock tab page for details on what the various fields mean.



Previous: 4.14. Repacking items | | Next: 4.16. Splitting a stock line

4.16. Splitting a stock line

The Split feature of mSupply provides us with the ability to break down stock into smaller pack sizes, consolidate it into larger pack sizes or move part or all of a stock line to a new location. Here's how to use it:

  • From the Item menu choose Show items to find the item to be split
  • Enter the start of the item name and click Find
  • Once the Item details window is displayed, choose Stock from the side bar list and you will see this window:

  • Click on the line you want to split, then click Split:

  • In the Quantity to split field enter the number of packs you want to move/split (if you're repacking the whole lot, then enter the total quantity - the number to the right of the word 'of'!)
  • In New location enter the new location for the packs that are being split (leave it alone if you're not changing the location)
  • In the New pack size field enter the The new pack size for the split items (leave this as it is if you're not changing the pack size!).
  • Click OK and you're done - the changes will be immediately visible in the item stock details window.

Here's an example:

In this example, 2 packs of 1,000 Erythromycin tablets (of which there are 37 available) are being transferred to a new location, and the 'outer' of 1,000 (actually 10×100 shrink wrapped together) is being opened to become 10 individual packs of 100.

When the OK button is clicked, the original line will show 35 packs of 1,000 tablets and there will be a new stock line with the same batch and expiry information but with 20 packs of 100.

So, to summarise, you can use the split command to perform these actions:

  • Change the location of some or all of a stock line
  • Repack some of a stock line into a different pack size
  • Both of the above at the same time!

When the new stock line is created, all the details of the existing stock line (such as manufacturer, donor, batch, expiry date, pallet pack size (number of inners in an outer) etc.) are copied over to it unchanged. Some other details, like volume per pack, weight per pack and outer (carton) pack size are changed according to the ratio of the new pack size to the original pack size.

Also, to make sure the audit trail is kept intact, a link is made between the transaction line that produced the original stock line and the new stock line.

Produce a movement report

mSupply provides a feature to produce a 'Movement report' for stock that you have moved to a different location using the split function. It's useful for printing off and giving to the person who is going to physically move the stock in the store.

Here's how to create one:

  • Once you have entered the details of your split/new stock location, click on the checkbox labelled Print Location Movement report and click OK:

  • The following report is displayed:

  • Note that the original and new locations are clearly identified so a printed version of this report can be easily referred to when physically carrying out the move in the warehouse.



Previous: 4.15. Show items with stock | | Next: 4.17. Stocktakes

4.17. Stocktakes

Updated: Version 4.10

General

There are three main types of stocktakes:

  • Partial stocktake: A partial stocktake means counting only a part of your stock. This may be a good way of splitting up counting all your stock, part of a system for counting all your stock in sections over a longer period of time or carrying out smaller periodic checks. You may select the stock to go in a stocktake by different locations, stock groups, types of items etc.
  • Full stocktake: All items are counted at one time.
  • Phased stocktakes: Items are counted in phases. See the full details on the 4.18. Phased stocktakes page.

A user can only create a stocktake or edit the lines on a stocktake if they have the appropriate permissions. See the 25.15. Managing users section for details.

Closing the store

Traditionally, during a full stocktake, the store is closed, and no transactions may take place until the exercise is completed.

The inconvenience caused by closure of the store varies from minor to significant. The benefit of using mSupply's stocktake module, while requiring that the store is closed while the physical stock check is in progress, is that the store may be opened immediately after the physical count is completed. Entry of the adjusted figures into mSupply® may be made at any convenient time over the next few days. Having said that normal operation can occur immediately after the stocktake, issuance will be affected by any discrepancies discovered during the stocktake.

It is recommended to Create inventory adjustments from the stocktake as soon as possible after the physical count.

Confirm Customer Invoices

mSupply will not allow stock that is on a Customer Invoice with status of new (nw) or suggested (sg) to be taken out of stock by any other transaction process, including an inventory adjustment flowing from a stocktake - refer Creating inventory adjustments.

Before starting a stocktake, it is HIGHLY RECOMMENDED to process (take the stock off the shelves) and confirm any customer invoices with a status of new (nw) or suggested (sg) - please see Issuing Goods to a Customer (Customer Invoices), Confirming an invoice for details on how to do that.

This is so important that mSupply will show you a warning message when you try to create a new stocktake if it detects any customer invoices with suggested (sg) status. Please read and heed the warning and take suitable action.

Displaying stocktakes already performed

Select Show Stocktakes… from the Items menu to display any stocktakes already created or performed. This displays the following screen:

The Show: filter allows you to choose which stocktakes are displayed in the list. Options are:

  • All: shows all stocktakes in the current store with any status for all time. Could be many of them!
  • Current: selected by default when the window is displayed and shows all 'suggested' stocktakes (status = sg). These are stocktakes which have not yet been processed into inventory adjustments (finalised; status = fn)
  • This year: shows all stocktakes of any status that have been created in the current year.
  • Last year: shows all stocktakes of any status that were created in the year before the current one.

Note: there will be an additional Program column in the table if you have program based master lists created (see 4.05. Programs) so that you can easily see if any of your stocktakes are program based.

Buttons on the Stocktake list window
New stock take

A New stock take is the normal way that you would create a stocktake, described in more detail on the rest of this page.

New blank stock take

A New blank stock take This would be used only if you are going to use the stocktake process to add new stock, that is stock that you are sure is not already recorded as in your store.

Delete stock take

Delete stock take allows you to delete stocktakes that have not been processed (finalised) into inventory adjustments.

There is little point in keeping old stocktakes with status = “sg”, especially if you are about to create a new stocktake containing the same items. Indeed, it can be quite dangerous to leave old stocktakes with status = “sg” in your system. If time has passed since the stocktake was created, then the snapshot and actual quantities are almost certainly incorrect. For good housekeeping reasons, it is good practice to delete old “suggested” stocktakes (status = “sg”).

Creating a new stocktake

After viewing the current stocktakes, click on the New stock take button, and the following window will appear:

You can produce a stocktake for all items in your store by clicking OK without entering any filtering criteria. However, it will often be helpful to filter the stock that will be included in a number of ways as discussed below.

Filtering the stock to be included

You can filter by:

  • Item properties Item name, code etc. as shown in this screenshot: Item properties filter
  • Item categories
  • VEN categories
  • Department
  • Master list If you organise your items using master lists this can be a very powerful way of including items on particular master lists only in a stocktake e.g. for programmes
  • Donor This filter is only displayed if the donor tracking preference is turned on (see Using the donor module)
  • Locations. This is recommended when you are doing a full stocktake of a large warehouse where you can have several stocktake teams working simultaneously - see the Filtering by location section below.
  • Expiry date. Search for items whose expiry is before a particular date. This allows you to easily remove all expired items from stock.
  • Randomly selected. Select a number of items randomly chosen by mSupply. This is handy for the purposes of doing an audit.

Whatever filters you use, ad-hoc or non-stock items will never be included in a stocktake

Filtering the stock by expiry

You can carry out a stock take based on expiry dates for your stock. This is useful to review and remove expired stock from your inventory.

Filtering by location

Filtering by location is an especially useful way of breaking up a large stocktake in to a series of smaller stocktakes. This also allows different teams to undertake different smaller stocktakes simultaneously.

Of course, it is not possible to filter by stock locations if locations have not been defined! Also, a stock location based stocktake will only include stock lines that have actually been placed in to locations ;-)

  • The “Shelf location” in the top left Item properties drop-down list is the default shelf location of the item, which is where stock of a particular item might usually stored. This is not a recommended way of organising a warehouse, and is included here only due to customer request ;-).
  • To filter the stock take by shelf location to include what stock is actually stored there (according to mSupply records!), use the Stock location filter.

In this example, the location filter has been set to equals (the default), and the entry in the box has been typed in as A. Only stock in shelf locations called A will be included in the stocktake.

Preparing the stocktake

The stocktake list is produced:

  • Sorted alphabetically, by name
  • Omitting items whose stock level is zero

At this point the status of the stocktake is sg (suggested i.e. it is still being worked on and has not affected stock in any way yet):

Now fill in the information at the top of the stocktake:

  • Description: A default description is filled in for you. We recommend that edit this to make it more meaningful while processing and for when you look back at your records later. This description is what is visible when you see a list of stocktakes. For example, you could add Annual stocktake or Monthly check. And / or, if you are filtering by anything such as stock location, it is worth including that here, e.g. M02.12.2A.
  • Comment: Put any other information you need to record about the stocktake in here.
  • Stock take date: This is the date you performed the stocktake and is set to the date the stocktake was created by default. Users will only be able to edit this if they have the Can edit stocktake dates permission set (see Managing users for more information). They will also be able to set the confirmation date of the inventory adjustments created from the stocktake when it has been finalised (but you can never change the date to before the Stock take date set in this field).

New line button: You can add new lines to the stocktake by clicking on this button (see the Adding items not in the stocktake section below)

Delete lines(s) button: Click on this to remove lines you have already selected in the list from the stocktake (you can use the usual Shift and Ctrl/Cmd clicking to select lines as usual).

Just a quick word about the read-only (non-editable) information displayed at the top of the stocktake:

  • Stock take key: The stock take number. This is an automatically generated number which increments by 1 for each new stocktake. It is unique within a store only so it is possible for stocktakes from different stores to have the same number.
  • Stock take entered date: The date the stocktake was created in mSupply.
  • Stock take status: The current status is the stocktake:
    • sg = suggested, the stocktake is still being worked on and is editable - new lines can be added or deleted and values can be edited etc.
    • fn = finalised, the stocktake is complete and cannot be edited (inventory adjustments have been created form it)

And a quick word about the columns in the table: if adjustment reasons are being used or any of the custom stock fields in File>Preferences>Stock tab then columns for those will also be displayed in this table.

The stocktake is a list of your stock, providing you with a 'snapshot' of your stock at a point in time. From this, mSupply enables you to create printed lists of your stock items from which you and your staff can do the physical stocktake.

Example for a large warehouse

A large warehouse can have thousands of locations. A full stocktake would run to tens or even hundreds of pages. This is a challenge to manage. In cases like this, it is recommended to create stocktakes broken down according to locations.

Remember to confirm any outstanding CIs with status = sg before you start, and don't let any of your staff create any new customer invoices until the stocktake is over, and preferably, all inventory adjustments have been processed.!

In large warehouses, stock locations are often labeled in a systematic pattern something like this:

A##.$$.%%, where,

  • A = 'Room', for example, M → Main store room
  • ## = aisle numbers, 01, 02, 03, etc.
  • $$ = bay number, 01, 02, 03, etc. noting that a common convention is for even numbered aisles to have only even numbered bays, and similarly, odd numbered aisles to have only odd numbered bays.
  • %% = shelf number, 1A, 1B, 1C, etc.

For example, M20.02.4E would be the location name for the location in the Main store room, Aisle 20, Bay 02, Shelf 4E

To create stocktakes for each Filter Stock location by
Aisle Starts with M01, Starts with M02, Starts with M03, etc.
Bay Starts with M01.01, Starts with M01.03, Starts with M01.05, etc.
Shelf Starts with M01.01.1A, Starts with M01.01.1B, Starts with M01.01.2A, Starts with M01.01.2B, etc.

To speed things up and ensure that you have described your stocktakes correctly according to the stock locations filter, you can copy the text of your filter (before clicking OK) and then paste it at the end of the stocktake description. After clicking on the Stocktakes button on the Items navigator this can be done entirely with the keyboard! 8-) For example, if you want to create a stocktake for all location in Bay M01.01:

Firstly, click on the Stocktakes button on the Items navigator
The Stocktake list… window appears. Then:

  1. Type Ctrl+N to start a New stock take
  2. Type Tab Tab Tab Tab Tab Tab Tab Tab (Tab x 8) to get to the Stock location equals pull-down button
  3. Type Down-arrow to get to the starts with option
  4. Type Tab to move the focus to the text entry field
  5. Type M01.01
  6. Type Ctrl+A to select all text
  7. Type Ctrl+C to copy the selection to the clipboard
  8. Type Enter (same as clicking OK button).
    The Stock take sheet… window appears.
  9. Type Tab to highlight all text in the Description field
  10. Type End to move the cursor to the end of the existing text (If you are on a laptop where the End key is hard to find, the Right arrow (→) key will also work here)
  11. Type (spacebar)
  12. Type Ctrl+V (Pastes the clipboard)
  13. Type Enter (same as clicking OK & Next button).
    The Stocktake list… window appears.

Repeat the above steps for each stocktake.

Example for fast moving items using a master list

It is often useful to regularly do a stocktake of fast moving items. A convenient way to do this is to create a master list of fast moving items called, say, Fast movers.

To create a stocktake containing just the items on this Fast movers master list:

  1. Confirm any outstanding CIs with status = sg
  2. Item > Stocktakes > New stock take
  3. Select the Fast movers option from the is on Master List pull-down
  4. Click OK

Before printing you need to ensure that the order in which items are displayed is appropriate. By default the list is alphabetical, but for stocktaking purposes, it may be more appropriate to sort the list by location and then by item name; this is achieved by clicking on the Order by button and choosing Sort by location then item name

If you want another sort order, click a column heading for a simple sort, or choose the Custom sort option from the Order by button.

You can filter a stock list by entering the item name - or the first few characters of the name - or the item code in the box Item name/code in the top right area of the window, then clicking the Find button

Clicking on the Print icon displays the available options:

  • General: contains several options. Click on it and you are presented with a further window: The Form to use drop down list contains these options:
    • Stock take line - prints out all the lines on the stocktake, including their quantity, with a space to write the actual counted quantity. It looks like this:
    • Stock take line discovered items - prints out a sheet with all the headers but containing only blank rows. Perfect for writing down the details of new batches you discover during the stocktake. Looks like this:
    • Stock take line with space - is the same as the Stock take line printout but with no quantity and 5 lines of space under each line. Useful if you know there's a lot of stock in the warehouse that isn't in mSupply.
    • Stock take line wt quantity - is the same as Stock take line but with no quantity. This is the one we recommend you normally use to give to the people carrying out the physical count. This helps to ensure that the quantity of stock on the shelves is actually counted and not just guessed!
    • Stock take line wt quantity big font - is the same as the one above but printed in landscape with a bigger font. This is particularly helpful in warehouses with poor lighting (powercuts, etc. :-( )
    • Stock take lines by location - prints the lines for each location on a separate page.
    • Stock take lines with signature - same as Stock take line wt quantity but the stocktake signature entered in the printing preferences is printed at the end.
    • Stock variance - this shows the items that were adjusted after the stocktake was finalised. Similar to the Inventory adjustments option below but a slightly different format.
  • Inventory adjustments: prints information about all the items that had their quantities adjusted because of the stocktake after the stocktake has been finalised (see finalise section below).
  • Inventory adjustments-all items: prints information about inventory adjustments made after finalisation but includes all items, not just those which have had their quantities adjusted.

There is, of course, a further option - you may provide the staff performing the stocktake with blank sheets, requiring them to list the items, batches, expiry dates, locations, pack sizes and quantities manually. We don't recommend you use this option unless your printer is broken ;-)

Perform the stocktake

Allocate staff to perform the stocktake, instruct them in the process you wish to follow, and issue the sheets to them.

For a stocktake involving several staff, it is recommended to require the staff members to write their name and date on each stocktake sheet. This is especially helpful when trying to interpret difficult handwriting :-)

Enter quantities into the system

Once the physical stocktake has been completed, you are ready to make entries to record any differences in stock levels into the system. Remember that any item which mSupply calculates as having zero stock will not appear on the stocktake sheet.

Filtering the list by item name or code

To help quickly find any item you want to make any adjustments to, you can enter the first few characters of its name or its code in the Search by item name and code field. The displayed list of items will be changed each time you enter a character to show only the items whose name or code matches what you have entered so far. To return to the full list just delete everything in this field.

Making adjustments

If there are no differences between what was physically seen in the warehouse and what is shown in the stocktake for a particular line then you can leave it alone - no changes are necessary.

If the only difference between what is in mSupply and what was physically seen in the warehouse is the number of packs (the figure in Enter Quantity column) then click on the figure in the Enter Quantity column and edit it to match what was physically counted in the warehouse.

You can press the Tab key on the keyboard to quickly move through the editable fields on one row and then then to the next row to edit (Shift+Tab to go to the previous editable field).

If there is more of a discrepancy between what mSupply says you have in stock and what was physically seen in the warehouse then double-click on the line. The line edit window will open:

You can now edit more details:

  • Stock take qty: the number of packs you counted in the warehouse
  • Batch: the batch or lot number of the stock
  • Expiry date: the date the stock will expire
  • Location: where the stock is located in the warehouse (type the first few letters of the location's code and press the Tab key on the keyboard to select the right location from a matching list)
  • Volume per pack: the volume of one pack (of the Pack size field) of the stock in m3. You can enter in litres or ml by typing l or ml after the figure you enter.
  • Weight per pack: the weight of one pack of the item (of the Pack size field) in kg.
  • Cost price: the price one pack of this line of stock cost you. Check the 12 month average checkbox if you want mSupply to calculate a weighted average pack price based on the supplies of this item you have received in the last 12 months.
  • Sell price: the price you sell a pack of this line of stock for.
  • Hold: do not issue: if checked then this will put the stock line on hold so that it cannot be issued in customer invoices. WARNING: this stockline will be put on hold immediately after the OK or OK & Next buttons are clicked if this checkbox is checked, the change will not wait until the stocktake is finalised.
  • Comment: anything you want to remember that was notable about this line during the stocktake.
  • Donor: the donor of this line of stock (type the first few letters of the donor's code and press the Tab key on the keyboard to select the right location from a matching list). Will only be available if the Allow tracking of received stock by donor preference is turned on (see the Invoice preferences page for details).
  • Manufacturer: If the Able to enter manufacturer when receiving, ordering or quoting for items store preference is turned on then this field will show and you can edit the manufacturer of the stock. Type the first few characters of the manufacturer's name and press the Tab key on the keyboard to select the right manufacturer from a list.
  • Custom stock fields 1-8: If any of these fields are turned on in the File>Preferences>Stock tab then they will show on this window and you can edit their values as appropriate.

Notice that you cannot change the Pack size value. If you want to do that then you must set the Stock take qty for this line to 0 and add a new line with the correct pack size (see the Adding items not in the stocktake list section below for details).

Adding items not in the stocktake list

In the event of an item being physically present in the warehouse, but not on the list then it needs to be added to the stocktake in mSupply:

  1. Click the New line button and this window will appear:
  2. If you want to add a line of stock that already exists in mSupply then, in the Existing stock lines table at the top, check the checkbox for the line you want to add and then click on the Add selected button. You can add more than one line if you wish - just check all the lines you want to add. If you check the checkbox in the header of the checkbox column this will check all the boxes for you (and uncheck them again if you uncheck it).
  3. If you want to add a new line of stock that doesn't exist in mSupply then enter its details in the New stock line section at the bottom and click on the Add new button to add it.
    • Stock take qty: the number of packs you found in the warehouse.
    • Pack size: the number of items in each pack that you found in the warehouse.
    • Batch: the batch number of the item you found.
    • Expiry date: the expiry date of the item you found (click on the calendar icon to select it or enter it manually).
    • Location: the shelf location in the warehouse where you found the item (if you don't know the exact location then type the first few characters of the location label, press the Tab key on the keyboard and select the location from the list that appears).
    • Donor: the donor of this line of stock (type the first few letters of the donor's code and press the Tab key on the keyboard to select the right location from a matching list). Will only be available if the Allow tracking of received stock by donor preference is turned on (see the Invoice preferences page for details).
    • Manufacturer: If the Able to enter manufacturer when receiving, ordering or quoting for items store preference is turned on then this field will show and you can edit the manufacturer of the stock. Type the first few characters of the manufacturer's name and press the Tab key on the keyboard to select the right manufacturer from a list.
    • Custom stock fields 1-8: If any of these fields are turned on in the File>Preferences>Stock tab then they will show on this window and you can edit their values as appropriate.
    • Volume per pack: the volume of one pack (of the Pack size field) of the stock in m3. You can enter in litres or ml by typing l or ml after the figure you enter.
    • Weight per pack: the weight of one pack of the item (of the Pack size field) in kg.
    • Cost price: if you know it, enter it in the currency you are using in your datafile. If you don't know it, you could check the 12 month average checkbox and mSupply will enter a weighted average price of all the stock of this item you received over the last 12 months.
    • Sell price: if you know it, enter it in the currency you are using in your datafile.
    • Hold: do not issue: if checked then this will put the stock line on hold so that it cannot be issued in customer invoices. WARNING: this stockline will be put on hold immediately if this checkbox is checked when the OK or OK & Next buttons are clicked, the change will not wait until the stocktake is finalised.
    • Use details of line selected above button: this is a shortcut to save typing values in all the fields in this section. If the details are similar to a stock line that is shown in the Existing stock lines table above then click on the line in the table to select it then click on this button. mSupply will copy the details of thew line into the fields in this section and you can then edit the ones that aren't quite right.
  4. You can also select a colour for the line in the stock take using the colour picker in the top right hand corner (set to black by default, as shown in the screenshot).

After clicking on the Add new button you are returned to the Stocktake sheet window, where the new line entered will now appear in the colour selected; note that the new line(s) appear at the bottom of the stocktake and they have a value of zero in the Snapshot column.

  • If you add a new line to the stocktake that has the same details (pack size, batch, expiry, location, cost and sell price) as one already on the stocktake, you will be asked to confirm if you really want to add the line.
  • All details of a new line added may be edited, but only the quantity or the location of existing lines on the sheet may be edited; this is performed by double clicking on the row you wish to edit.
  • The Delete item button will only work to delete lines which you have added yourself (i.e. lines with a snapshot quantity of zero).
Adjustment reasons

If you have created at least one Positive inventory adjustment reason and one Negative inventory adjustment reason in the system (see the 16.10. Options (standard reasons) section for details) and at least one of each type is active, then an additional Adjustment reason column will be displayed in the stocktake window:

The column is read only but, if you edit the number in the Enter Quantity column then the line edit window will be opened and you must select an Adjustment reason (one of those you set up in the preferences - a Positive adjustment reason if you have increased the quantity compared to the snapshot value, a Negative adjustment reason if you have reduced the value):

When you finalise the stocktake and create the inventory adjustments (see below), the individual lines of the inventory adjustments will be given the same adjustment reasons you set for them in the stocktake.

Create inventory adjustments

When all necessary adjustments have been entered, you are ready to create the inventory adjustments.

Creating inventory adjustments (finalising the stocktake) is not reversible, so you have to be quite certain you've finished making all the changes you want to the stocktake before you do it.

Inventory adjustment categories

After you click on the Create inventory adjustments button, the following window will appear to ask you to confirm this is what you want to do:

Before you click on the OK button to confirm, you can select a transaction category to give to the inventory adjustments when they are created by clicking on the drop down list (these can be useful when it comes to reporting later). This drop down list is populated with all the transaction categories in your datafile that have a type of inventory adjustment (see section 22.07. Transaction categories for information on creating transaction categories).

What if there is insufficient stock to adjust?

If an item has limited stock and that stock is allocated to an invoice during stocktake, when you try to adjust the stock the following window will display giving you two options to choose from:

For the excel option a spreadsheet will open allowing you to analyse the invoices to which the stock is allocated. The highest invoice number is likely to be the one entered during stocktake.

stocktakeerrorexcel.jpg

Of course, closing off transactions until a stocktake is complete and avoiding these kinds of issues is by far the best practice.

If you have the Can edit stocktake dates permission (see Managing users) then you will be able to edit the confirmation dates of the inventory adjustments to match the stock take date.

Any changes to lines in a stocktake that don't include a change in quantity (e.g. a change in batch, expiry date or sell price only) will also result in stock in the system being updated when you click on the Create inventory adjustments button but it will not result in any lines being added to an inventory adjustment. You can see the changes in the system by viewing the details of the individual stock lines and all such changes are logged, on the stocktake (see the log tab when viewing the stocktake or 25.19. The system log) and the stock line's log itself (see Stock line details window).

Viewing inventory adjustments

Once inventory adjustments have been created, the status of the stocktake changes from suggested (sg), to finalised (fn). You will now observe a change in the buttons appearing on the Stocktake sheet:

  • in the upper area, only the Print button is present
  • while at the bottom two new buttons are present; Show added adjustments and Show reduced adjustments.

  • Click on either button to display the related inventory adjustment transaction.
If the inventory adjustment quantities look wrong

It is possible for the stock reduction inventory adjustments created by your stocktake to have smaller quantities on them that you expect. They may even be zero like the example in this screenshot (and you know there should definitely be a reduction in stock because the counted quantity was less than the snapshot value in the stocktake):

The quantity might not be zero but still less than the snapshot minus the counted quantity specified in the stocktake.

This scenario is because stock was found on new or suggested status customer invoices. This stock is reserved for customers by mSupply but not removed form your total stock (see 8.01. Issuing goods to a customer (customer invoices)) and must be included in your count - if you don't include it in your count, then mSupply will try to remove it from your stock again when you finalise the stocktake. And if there's not enough stock, mSupply has to reduce the quantity on the reduction inventory adjustment. Which is the discrepancy you see when you look at the stock reduction inventory adjustment created by mSupply when you finalise the stocktake.

To avoid this scenario follow the golden stocktake rule:

Review and CONFIRM all Suggested (sg) or New (nw) status invoices before creating your stocktake.

If you must leave some customer invoices unconfirmed before finalising the stocktake then include the stock on them in your stocktake count. If you confirm the invoices after creating the stocktake but before finalising it you must reduce the count on your stocktake by the total amount of that stock line on the invoices you confirmed. As you can see, it can be complicated so it's much better to follow the golden rule. Trust us!

To understand further see the 28.04. How to remove stock lines that have ‘0’ available page.

Clicking on the Print button and clicking on Inventory adjustments will print this information:

In this example, three adjustments have been made:

  • Magnesium carbonate: present at the physical check but not on the sheet, has been added
  • Peppermint oil has had its stock increased
  • Sodium bicarbonate has been reduced in stock

Items that weren't changed don't show in the report - if you want to see all items, including those that weren't changed then click on the Print button and select the Inventory adjustments - all item option.

Some points to note:
  • When you have created the stocktake sheet, it's like `taking a snapshot'; the physical stock at that location should not be removed until the stocktake has been performed; nor should stock be added.
  • New transactions can however, be entered into the system.
  • the Log tab on the Stocktake sheet will list any anomalies. An anomaly may occur if a transaction has been entered after the stocktake that issued more stock than you physically counted. Obviously someone has made a mistake in such a situation.
  • There is on the stocktake window (lower left corner) a checkbox Locked , which, if checked, will allow neither deletion of the stocktake nor any changes to be made to it.

  • Ok and Next - if you have no more stocktakes to add, click the 'OK' button, to add only the stocktake just completed. To add a further stocktake, click the 'OK & Next' button and proceed to add your next stocktake.



Previous: 4.16. Splitting a stock line | | Next: 4.18. Phased stocktakes

5.01. Names: using, adding and editing

About names

In mSupply a “name” is one of these:

  • customer: a recipient of your goods
  • supplier: someone who sends your store goods
  • manufacturer: someone who makes the goods that you receive, store and distribute
  • donor: an entity that donates goods to you (you can track donated stock)
  • patient: someone you dispense goods to
  • others: you'll find other types e.g. benchmarks mentioned through out the documentation

A name can also be more than one (or all!) of these at the same time.

Adding a customer, supplier, manufacturer, donor or benchmark

Adding a new customer

In a multi-store system, you will quite likely not want the new customer to be visible to every store. By default, mSupply will make a new customer visible only to the store that you are logged in to when you create the customer. This store will be made the Supplying store. Make sure that you are logged in to the supply store before proceeding.

To add a new customer:

  • Log in to the supplying store
  • Choose Customer > new customer from the menu.
  • The form shown below will come up.
  • The customer checkbox will be checked and disabled (from editing).

Adding a new supplier
  • To add a new supplier, choose Supplier > New supplier from the menu (makes sense really!)
  • The window will look the same as for adding a customer, except the supplier checkbox will be checked and disabled (from editing).
Adding a new manufacturer
  • To add a new manufacturer, choose Supplier > New manufacturer from the menu.
  • The window will look the same as for adding a customer, except the manufacturer checkbox will be checked and disabled (from editing).
Adding a new donor or benchmark
  • Select Customer > New customer or Supplier > New supplier from the menu.
  • The same window for adding a new customer or supplier will open and you should check the Donor or Benchmark checkbox in the Category section.
Fields in the names entry window
Name Code

The unique code to identify this customer, supplier or manufacturer.

Charge to

mSupply is made to work in tandem with an accounting program (although it will also function just fine by itself). The “Charge to” code is what is exported with each invoice. Generally you should make the charge code and name code the same (If you want, there is an option in the Preferences > Misc tab to make sure this is the case). For example:

  • If you have 3 hospitals you supply, but you send the bills to one centre for payment, you may want to enter each hospital with its own name code, and all of them with the same charge code. In your accounting program you would just enter one debtor (customer) with a code the same as the charge code. eg.
Customer Name code Charge code
Fred H Hosp fhhosp bluehos
Mary P Hosp mphosp bluehos
Sam Q Hosp sqhosp bluehos
  • In your accounting program you would enter “Blue Hospitals Assoc” with the code “bluehos”
  • For a supplier, if you have entered a default currency and margin these will be entered, but you can override them. Every supplier should have its currency entered (The currency it uses for your invoices). If the currency isn't yet in your system, close the name entry window and choose Currencies from the Special menu to add it.
  • if you do not wish to use different name codes and charge codes, check the “supplier name code and charge must match” and “customer name code and charge must match” check boxes in the mSupply Preferences. If you do this, the charge code will automatically be identified with the name code.
  • spaces are not allowed in name codes and charge codes

Either the “customer” or “supplier” check box will be checked as appropriate, depending on whether you have chosen “new supplier” or “new customer” from the menus to produce this window. However, you can still alter things here without upsetting mSupply.

Name

The customer/supplier name. (Remember you can use the Tab key to move from field to field)

If there are non-printable characters before or after the name, code or charge code they will be removed. Any non-printable characters in the name, code or charge code will be replaced with an underscore (_).

HSH code & HSH name

These are used when using the Health Supply Hub (replacement for the Remote tender module - see the Health Supply Hub page for details) to link suppliers or manmufacturers with their record on the Health Supply Hub server and maintained by The mSupply Foundation. If your system does not use the Health Supply Hub, then you can ignore these fields.

To link a supplier or manufacturer to one already entered in the Health Supply Hub:

  1. set your Health Supply Hub preferences (16.01. General preferences)
  2. click on the padlock icon next to the HSH code field to unlock it and enable the button.
  3. click on the button.

mSupply will then search for a supplier or manufacturer (depending on whether the name is a supplier or manufacturer in mSupply) in the Health Supply Hub with a name having the same first letter. A window like this opens:

If the correct supplier or manufacturer is not shown in the list then clear the contents of the Quick search field. All suppliers or manufacturers registered on the Health Supply Hub are then displayed. You can refine the search by typing something in the Quick search field and only suppliers/manufacturers with names that begin with what you typed will be displayed.

When you see the supplier/manufacturer name that you wish to connect to the supplier in mSupply, double-click on it to select it; the Health Supply Hub code of the supplier/manufacturer will be put in the HSH code field and the supplier/manufacturer's Health Supply Hub name will be shown in the HSH name field.

It the search is unsuccessful or there is a problem connecting to the Health Supply Hub, you will be shown an appropriate message.

Note: if the name you are trying to link to the HSH is a customer then you shown a message telling you that linking it to a supplier or manufacturer in the Health Supply Hub is not possible.

Type

In the main entry screen, there are 4 check boxes to mark each entry as a customer, a supplier, a manufacturer and an additional Benchmark category. This last category is a feature of the Tender Management module, and is fully explained in that section, under Using Benchmark prices

Status - Hold checkbox

If this is checked this name can not be used for receiving or issuing goods.

Donor checkbox

This is applicable to suppliers only. There are a few situations in which this box should be checked:

  1. If this supplier/organisation provides goods free of charge (either in whole or in part).
  2. If this supplier/organisation provides funding (either in whole or in part) for purchasing.
Price Category

Selection of any of the categories will fix a certain price margin for that Supplier or Customer.The price category value is entered in File >Preferences > Prices . When goods are being issued to this customer, the selling price is increased/decreased by the percentage specified in the Preferences for this price category.

  • Eg: Consider customer XYZ, who is in category B, and in the preferences category B is assigned a value of 50. If an item is issued to customer XYZ with a normal selling price of $10, the selling price on this invoice will be $15.
Address and contact details

These should be completed with relevant details

  • For customers, you can enter separate delivery and billing addresses as necessary.
Other section
Categories

These category fields are used for reporting and are available for you to make whatever entries are appropriate in your situation. For example, you might wish to subdivide your Hospital category by number of beds, or your Clinics by the number of patients seen daily, etc. Or you may wish to identify your customers by their geographical location (region, district, state etc.) or by location type - urban, city centre, rural, remote, etc. The choice is yours - the main point to remember is that these fields are searchable, enabling you to produce reports relating to very specific criteria.

  • There are 6 category fields available for selecting as required.
  • Each category has its own drop down list containing the categories which have been defined using the menu item Supplier > Show categories… or Customer > Show categories… (see Name Categories for more details).
  • The labels of these 6 categories can also be changed in the preferences (see General preferences, Names tab for details).
Custom fields

Custom fields are similar to Category fields, the main difference being that these fields are not validated using a drop-down list, and so can't be reliably used for categorisation.

Analysis

You can use this field to group together certain types of customers or suppliers. You can filter the report by selecting the group in the Analysis field.

Postal address

Here you can enter a postal address if it is different to the physical address of the supplier.

Supplying store

As of mSupply versions (Mobile and Desktop) released since 2019, the concept of a Supplying store is less relevant than it was. The feature is still active, can be utilised with custom code, and is the default store for internal orders are if this customer becomes a stoer in its own right.

Extra information for customers only

Shipping address: If the name is a customer, shipping address fields will be shown.

Extra information for suppliers only

Currency: Enter the currency code of the currency this supplier uses for invoicing you.

Margin: Enter the percentage margin to apply to items received from this supplier.

Freight factor: Enter the amount to add to quotations from this supplier to adjust quoted prices for freight. For example: a physical check on invoices from IDA reveals that freight to Nepal generally amounts to about 15% of the net value of the invoice. Therefore we would enter “1.15” in this field for IDA. Note that if suppliers quote you “CIF” prices, then you should enter “0” here.

About manufacturers

When you are receiving goods, you can optionally specify the manufacturer of each item. Manufacturers can be chosen from a list that is made up of names which have the Manufacturer checkbox checked.

For the manufacturer field to be shown, the option must be turned on:

  • Special > Show stores > [choose your store and double-click] > Preferences tab
  • Check the Able to specify manufacturer when receiving, ordering or quoting for items checkbox

Editing a customer, supplier or manufacturer

Finding a name

Before you can edit a name, you have to find it and display its details! For this example we will edit a customer. Editing a supplier is just the same, except that you start by choosing Show supplier from the Supplier menu.

Choose Customer > Show Customer. You are presented with a window to enter as much of the Customer name or code as you know:

remote_desktop_connection.jpg

  • The slide bar at the top of the window may be set to Normal, at the left, or at intermediate points towards the Fuzzy end (right); this determines the accuracy of matching your entry; when set to Normal, the search will only match exactly what has been entered; when set at Fuzzy the search will list entries which are approximate matches to what has been entered. The accuracy with which the list matches the entry is determined by the position of the slider.
  • If you leave the Name/Code text field empty, clicking the Find button will produce a full list of all customers.
  • You can enter values for the other filters too (or them only!) if you want to refine your search.
  • Note that the window has a series of radio buttons to select the target of your search - All names, Customers, Suppliers, Manufacturers, etc. So even if you start this search from, say, Customer > Show Customers…, by selecting the Suppliers radio button, you can search in suppliers rather than customers.
  • The Exclude patients checkbox is checked by default and means that any patients you have in your datafile will not be included in the search. If you uncheck it, any patients in the current store will be included in the search.
  • The Exclude hidden names checkbox is checked by default and means that any names hidden in your store (but probably visible in other stores) will not be included in the search. If you uncheck this box then the search will include all names in all stores, and their visibility will be ignored.

If the search finds only one name that matches the filter criteria you entered, its details window will be displayed. If more than one name matches then you are shown a list of them all

Buttons in the names list window
New

This button allows you to enter the details of a new customer

Modify

This button opens a window displaying the details of the highlighted customer, allowing their details to be modified.

Set Flags

This button allows you to mark certain names with a flag.

  • First, highlight the names you wish to flag by holding down the control key (command on Mac) and clicking the names in the list you wish to use. Then click the Flags button to show a window where you can enter the flag you wish to add, and decide whether to replace any existing flags or append the new flag to the old one.
Print

Clicking this button will print a list similar to the one displayed on screen.

Find

This button shows the same find window as choosing the menu item did so you can find a different group of names.

Order by

This button allows you to sort the displayed list by the criteria you choose. The Labels and Print buttons will use the order that is displayed. By default, names are displayed alphabetically based on the name column.

Merge

This button allows two customers to be merged into one; highlight the two entries click on the Merge button to display this window:

Choose the record you wish to keep and click on OK ; the data from the deleted record is then merged with the data of the record being kept. If you change your mind, click on the Cancel button, and the merger will be cancelled.

Labels

Clicking this button allows you to print address labels for the names in the list. The label editor is displayed.

Report

Click on this icon to open the Quick Report editor window. Use of the Quick Report is discussed elsewhere in the guide. See Custom Reporting Tutorial

Custom data

This allows you to bulk edit the Custom data fields associated with the displayed names. An editor window like this will be displayed:

Only fields with their checkbox selected in the “Update” column will be modified. Note that you have the option to apply the changes to all names currently displayed in the list or only ones that you have selected before opening the editor.

Click “Save changes” to apply. After confirmation and processing, you will see your changes reflected immediately in the Custom Data column of the names list. It is recommended that you have the Custom Data column displayed (see Customise below) before bulk editing custom data so you can clearly see which names have been changed.

If you want to remove certain fields entirely from the names, select the field(s)' “Update” checkbox, then switch the selector at the bottom so it says “Fields with default (unchanged) values with be removed” (instead of “updated”). Any fields you haven't changed from their default values (i.e. blank for text, 0 for numbers, etc.) will be removed upon saving. You can completely remove all custom data for selected/displayed names by selecting all “Update” checkboxes, leaving all values default, and choosing the “removed” option.

Make sure you know what you're doing when bulk editing as you can easily over-write a lot of data if you're not careful.

Customise

Allows you to choose which columns to display using this window (Note: this only affects the columns you see in this list, it won't affect what other users see):

Columns on the left are available. Columns on the right are the ones in use in your names list. Click a row in either column then click the move left or right button to transfer it to the other column. Click OK when you're done, or Cancel if you want to stick with what you've got. Your choice of columns to display will be remembered for the next time you display a list of names (customers, suppliers etc.).

OK Button

Closes the window

Editing or viewing a name

To edit/view a particular name, if you are looking at a list of names double-click the name you want to edit on the list (no need to do this if you are already looking at the name's details page because only 1 name was returned from your search).

You will be shown the name's detail window which has a sidebar showing several tabs, General, Invoices, Backorders, Quotes etc. and opens at the General tab:

Edit any of the fields to the values you want. Note that fields with a padlock need to have the padlock unlocked (by clicking on it) first before you can edit the values. These actions are, of course, only possible if you have the appropriate permissions.

The Main/Billing Address fields will be disabled and not editable if the name beloings to a store. To edit these fields, do that on the store record. See the 26.07. Virtual stores page for details about this.

Deleting names

Click on the Delete button in the bottom left hand corner to delete the name.

If a name has transactions entered against it, you will not be able to uncheck the relevant check box in the Category section, and you will not be able to delete it. For example, if a supplier has invoices entered against it, you will not be able to uncheck the Supplier check box, and you will not be able to delete the supplier.

Putting a name on Hold

If you wish to prevent future transactions with a name, change it's status to on 'Hold'.

Invoices tab

Here you can view the invoices for a customer or supplier.

Note that the Total outstanding field shows a customer's payment balance and is only shown if the customer receipts module is turned on (see 11.02. Receiving payments from customers).

You are able to edit an invoice directly from this window by double-clicking the one you wish to edit. A new window will open with the invoice details displayed.

Buttons on the Invoices tab

Click this button to print a range of invoices for a customer. You will be asked to enter the first and last invoice numbers to be printed.

Aging

Click this button to display a list of aging categories and the outstanding unpaid balance for each invoice in each category.

Dates

Choose a date range from this menu to show quickly recent invoices, or to revert to showing all invoices

Backorders tab

back_ord.jpg

  • Here you can view, add and edit the backorders for a customer. mSupply allows entry of backorders against suppliers as well, but we are not sure why you would want to do this!
Buttons on the Backorders tab
New backorder

Clicking this button presents you with a window where you can add a backorder line for this customer.

  • Type at least a portion of the item code or item name, then press the Tab key.
  • Today's date is automatically entered. You can change the date if you like
  • Enter the total quantity owing.
  • Enter a comment (e.g. an expected arrival date)
  • Click OK to save changes and exit the window.
Delete backorder

Click a backorder line to highlight it, then click this button to delete the line. You can also select several at once (using ctrl/cmd+click and shift+click) or all the backorders in the list using ctrl/cmd+a and delete them at once as well.

Copy

This command copies the backorder to the clipboard, allowing you to paste the report into an email message, word processor or spreadsheet document.

Print

The list of backordered items for the customer is printed.

Viewing backorders

Double-click a backorder line to edit the line. You will be shown the backorder entry window, where you can change any details you wish.

Show

This drop-down list allows you to choose which backorders to display.

  • Backorders are normal items that have not been supplied to customers.
  • Ad Hoc items are items that customers have ordered but which you do not want to add to your stock list, rather making a special order just for that customer.
Quotes tab

You can view the quotations you have entered in mSupply for this supplier.

Notes tab

To add, edit or delete a note, click on the Notes tab, and this window displays:

notes.jpg

Click on New note to create a note, or select an existing note and double click on it to view, edit or delete it.

  • The date on which you are entering a new note is already completed, and in the main panel you should type in the wording of the note itself.
  • In the lower left of the window is a drop-down list offering various choices concerning the displaying of the note on screen; it may appear as an alert when a Supplier invoice is created, when a Purchase Order is created, etc..

If never is chosen, the note will never be displayed on screen, and if all is chosen, it will display for all events for this customer/supplier. You may also set the background colour of the note , but as the text is always black, dark colours should be avoided. A further option allows you to have one or more audible `beeps' sound when the note is displayed. Each note will display according to the attributes set for it, independently of other notes defined for the same customer/supplier.

Subsequently, when this customer/supplier is selected and depending on the display settings made, the note will appear on screen. Be aware that the note does not disappear automatically - you must close it manually.

The text of a note can be up to 32,000 characters.

Click OK when you are finished.

Contacts tab

contacts.jpg

Adding a contact

To add a contact for this customer or supplier, click the Add contact button, then enter the details in the window that appears:

  • Info if related to a customer or supplier textbox: read only. Shows the name of the customer or supplier this contact belongs to. Will be empty if this contact does not belong to a name.
  • Web login: in this section you enter the authorisation details that this contact will have if it is used for accessing the REST API or one of mSupply's web interfaces. See the 19.03. mSupply customer web interface and 19.09. mSupply REST API pages, for example, for more details.
Deleting a contact

To delete a contact, click on the contact you wish to delete, then click the Delete contact button.

Group tab

group.jpg

Groups are only relevant to customers, not suppliers.

If this customer has been added to a group, this tab displays the name of that group. An explanation of groups and how to work with them is here: Show groups...

Here you can select the group of which a customer is a member. When you choose a group, you will be shown a list of item departments which are linked to the chosen group. Once the group system is activated in the Preferences, only items belonging to one of the listed departments (or items with no department) may be supplied to that customer.

Purchase orders tab

This tab shows a view of Purchase Orders for the current name, and applies to suppliers only.

Web log-in tab

If you are allowing customers to access their order information using the mSupply web server, this is the window where you assign a logon name and password to a customer.

Also displayed on this tab is the internet connection speed. It should be noted that this value is derived from your network settings, and may not be edited manually.

Item lists tab

This tab is used to assign master lists to customers for use in requisitions and mSupply mobile. For more information, see Item master lists.

Note: Before version 5.3 customers could also have local lists assigned to them (they applied to that customer only) but these have been removed from version 5.3 onwards.

Stock history tab

A list of stock histories, showing dates of both the stock take and the date of entry into the computer, the ID reference, the status and the type, is displayed.

Store Visibility tab

Updated version 4.12

The tab shows which stores the customer/supplier is visible in. Only when the visibility checkbox is checked will the customer/supplier be visible to ‘this’ store, which is needed if the store will receive and/or issue goods from ‘this’ store.

There can be a huge number of stores in this list. If you want to find a particular store or group of stores you can type in the Search stores field just above the list. This will restrict the list to only stores with a name that contains what you have typed.

  • All on button: When clicked, this will check all the checkboxes in the Visible in store column and the button label will change to All off. Clicking it then will uncheck all the checkboxes.
  • Copy button: Will copy the current state of the Visible in store checkboxes.
  • Paste button: Will make the current state of all the Visible in store checkboxes the same as it was when the Copy button was clicked.
  • You can only edit the visibility of any name in another store if you have permission to login to the store and to edit name visibility in that store:
    • if you're just editing visibility in a single store, then an error dialog will popup and the state of its Visible in store checkbox will revert to its previous value.
    • however, when using the bulk All on, Copy and Paste buttons to update visibility in multiple stores, there is no error dialog and only the stores that you have permission for will be affected.
  • If you edit the visibility of store name A in store B, then the visibility of store name B in store A will be updated to match i.e. inter-store visibility is always symmetrical.
  • If you are using a syncing system, and editing visibility for a store name, that can affect the sync settings for the store on other sites i.e. if you make it invisible to all stores which are Active on a site, then the sync status will become None on that site; and if you make it visible to at least one store which is Active on a site, then the sync status will become Transfer on that site - see Store sync-with options.
  • In a syncing system, facility names (customers, suppliers, etc.) can only be created and edited on the primary server. Patients can be created in any dispensary, including on a sync site. After that, their visibility is controlled on the central server (after they sync there) in the same way as other names, so everything on this tab (including the All on, Copy and Paste buttons) will be read only on a sync satellite.

When a customer / supplier is created, it will only be made visible in:

  • its home store (the store that you are logged into when the name is created; see Home store for details), and
  • any other stores if their store preference Names created in other stores not visible in this store is switched OFF (there's an equivalent store preference for patients, which can be switched OFF to make new patients visible in other dispensary stores) - see Store preferences for more details.
Photo tab

On this tab you can assign a photo of the customer or supplier and set their world map coordinates. Both of these can be used in reports.

Adding or deleting a Photo

To add a photo, either copy the contents of a file to the clipboard and paste them into the image area or click on the Add photo button and select the picture file (png, jpg, bmp or gif files supported).

To delete a photo either click on it in the image area and press the delete key on your keyboard or click on the Delete photo button.

Map coordinates
  • You can use Google Maps to find the latitude and longitude coordinates of a customer. The format of the numbers copied from Google maps is “latitude, longitude”.
  • Copy these numbers into the Map coordinates field and press the Tab key on the keyboard. mSupply will copy the Latitude and Longitude numbers to their appropriate Lat and Long fields below.
  • You can also enter the numbers manually into the Lat and Long fields shown in the screenshot.
  • You can then view the customer's location by clicking the View on Map button.
Custom data tab

This tab shows all the custom fields that have been set up in the preferences. See the 16.11. Custom fields page for details.

You can edit or enter values in the fields as required. When you click on the OK or OK & Next buttons the values will be saved.

Log tab

This tab shows a list of all the log entries that belong to this name. These entries will also appear with all the other logs for other events throughout mSupply in the log. See the 25.19. The system log page for details.

If you want to see more details about one of the logs, double-click on it in the list and a detail window, populated with the log's details, will open.

Supplier hub tab

This tab allows you to register suppliers in the mSupply supplier hub. Enter the site name you wish to register the supplier with in the Site name field and click on the Register button.

Tags tab

This tab allows you to assign any name tags that you have setup to this name. The table shows a list of all the name tags currently setup in your system. To assign one to this name, simply check the corresponding checkbox in the Use column.

If the list of tags is long, you can type something in the Search tags field to make the list display tags which contain what you typed only.

Please note: if you assign a tag to a name that is also a store, the tag will be copied to that store's store tags. See the 25.08. Virtual stores page for details on store tags.

See the 5.05. Name tags page for details on how to create and edit name tags.

Import new name codes

If you need to change the name codes for a selection of names, it is a technically challenging process that is easy to get wrong if done manually, especially if you intend to re-use existing codes (not recommended!). Custom code has been developed to do this in bulk. Please contact Sustainable Solutions on support@msupply.foundation to discuss this. Include a link to this heading Code to update Name codes :-).

The relevant details are:



Previous: 5. Customers and Suppliers | | Next: 5.02. Contacts

5.06. Suppliers: adding and viewing

New supplier

To add a supplier, choose this item.

Note- if this supplier will have invoices entered against it and you are exporting invoice data to an accounting program, a new “creditor” must be made in your accounting software with the same code, or you will get an error when you import! (You can usually make the code when you get the error in your accounting software when you try to import!)

The window for viewing/editing a supplier contains basic information. Fields that especially relate to suppliers include:

Currency: If you are using currencies, enter the currency used by this supplier. This value will be filled in with the value set in the “default currency” option of the Preferences.

Margin: The amount (as a percentage) that will be added to the cost price to calculate the sell price when you enter an invoice. For example, if you enter “10”, items from this supplier that are bought for 30 dollars will have their value increased by 10% (i.e. 3 dollars) and will be sold for 33 dollars.

Category: You will note that the Supplier box is already checked. The special Benchmark category is discussed fully in the section on Tender management, which you can access here.

Freight factor: The amount to multiply supplier quotations by to account for freight charges. (If their quotations are “CIF” you should set this to zero).

Show suppliers

This item allows… you guessed it - you to view suppliers. This window is displayed.

In the field, type as much of the supplier name or code as you want to. If there is only one matching item, the details will be displayed, otherwise a list will be displayed from which you can choose the name you want by doubling clicking it.

Previous: 5.04. Name categories | | Next: 6. Purchasing

5.02. Contacts

This command from the Special menu displays a window where you can edit contacts.

Contacts are usually associated with a name (a customer or supplier), and it is easier to edit such contacts using the “show suppliers…” or “show customers…” command.

If a contact is not associated with a name, you can edit details for that contact using this command.

Buttons in the contact list window

New: Use to add a new contact.

Report: Presents the Quick report editor window. See Using the Query Search editor

Find: Use to find an individual contact

Order by: sort the contacts

Print: clicking this button will present you with a dialog with two choices:

  • If you click list a list will be printed of the records in the window.
  • If you choose labels, you will be shown the label editor, allowing you to print a set of address labels for the current list of contacts. Note that you can save a particular label layout and then use the load command in the label editor to restore your layout.

New: To edit a contact, double-click on the line you want to edit. You will be shown the contact details:



Previous: 5.01. Names: using, adding and editing | | Next: 5.03. Merging two names

5.03. Merging two names

If you accidentally enter two names into mSupply that identify the same organisation, you can use this command to combine them.

Use extreme caution: This operation will move all historical records from the name you delete to the name you are keeping. The operation can only be undone by reverting to a backup copy of your data file (so it is a very good idea to take a backup just before you begin any merging).

Access the function by selecting Customer > Merge two names… or Supplier > Merge two names… from the menus.

After selecting one of the options, the following window is displayed:

Enter the name to keep (type the first few characters of the name and press the Tab key to select it from a list of names that begin with what you typed), and then the name to merge (same way). When you have checked then checked again that the information is correct, click the OK button. You will be given one last chance to confirm and then the merge is carried out.

The merge takes all instances of the name to merge in the mSupply datafile, wherever it may appear, and replaces it with the name to keep and then deletes the name to merge.

You can also access this functionality by selecting two names from a list of customers or suppliers and clicking on the Merge button at the top:

If you do this you are presented with a different window, where you select which of the two names is the one to keep (in green) and which is the one to merge (in red):

Use the pairs of Keep and Merge radio buttons to select which name is to be kept and which one is to be merged. Make sure you select the right way round then click on the OK button and, after a final confirmaiton from you, the merge will be carried out.

You can also merge a name into a virtual store (the store must be the name to keep). This is particularly useful if, for example, you have a customer which you now want to turn into a store to manage their stock more fully. This has the benefit of moving all the transactions connected with the customer into the store so that you don't lose any historical transaction information.

When you merge a (customer) name with a virtual store you must finalise all transactions belonging to the customer first (mSupply will tell you to do this if you have not already).

In a synchronising system, The merging needs to take place on the primary server, even if the virtual store is 'Active' on a satellite server (see Remote Synchronisation)



Previous: 5.02. Contacts | | Next: 5.04. Name categories

5.04. Name categories

You can categorise names in mSupply with 6 different categories. This is very helpful for producing detailed reports. You can apply one or all or some of these categories to a name. Categories 2-6 are standard categories but category 1 is special - it's hierarchical and has 3 levels, level 1 is the top and level 3 is the bottom (similar to item categories).

Suppliers and customers have their own sets of categories. To view and edit them you choose Show categories from the Customer or Supplier menu and that brings up this window:

Here you can add and edit categories for your suppliers or, in this case, your customers.

Show drop down list: This determines which category type is shown in the list and which type of category will be created if you click on the New button. Note that the Category 1-6 labels in the drop down list will be replaced with any custom labels you have defined in the category label preferences in the General preferences, Names tab.

Delete button: Deletes the category you have selected in the list. You'll be asked to confirm the deletion first of course!

New button: Opens up the new category window which looks like this (Note that double clicking on a category in the list opens up this window too but it will be populated with the current settings for the category you double clicked so that you can edit them all):

Description: This is the category name and will be seen everywhere when assigning names to categories or filtering on name categories in reports.

Category_user_field_1: This is a user-defined field. If a label has not been entered in the preferences then the default Category_user_field_1 shown here is used. The information you enter here is used in some reports.

Category_user_field_2: A second user-defined field, same rules as for Category_user_field_1 apply.

Parent category drop down list: This only appears if you're editing a category 1 level 2 or 3 category because they are the only ones that can have parent categories. A parent category is the category to which this category belongs. If the category you are creating or editing is level 3 then you will be able to choose one of the level 2 categories as a parent. If you are editing a level 2 category then you'll be able to select one of the level 1 categories.

Previous: 5.03. Merging two names | | Next: 5.05. Name tags

5.05. Name tags

Name tags are tags that can be attached to customers, suppliers and other names to identify them in a flexible way. They can be used in a number of ways including:

  • With programs to identify which customers can use which programs.
  • To control which facilities are included or excluded in reports.
  • To control some aspects of customisations.

View name tags

To see a list of all the name tags currently set up choose Customer > Show tags… or Supplier > Show tags… from the menus. This window will open:

Add a new tag

To add a new tag, click on the New button and enter the tag's name in the Description field in the window that opens:

Click on the OK button to save it.

Delete a tag

To delete a tag, click on it in the list to select it then click on the Delete button. You will be asked to confirm the deletion.

You can only delete name tags that have just been created. After they have been saved by clicking on the OK button of the name tag list window then they can no longer be deleted.

Please note: You cannot edit a name tag so type the descriptions carefully! You can delete a newly created name tag, so if you spot a typing mistake before clicking on the OK button of the name tag list window, simply delete the tag and add another with the correct description.

Assigning tags to names

See the 5.01. Names: using, adding and editing page for details on how to assign tags to names.



Previous: 5.04. Name categories | | Next: 5.06. Suppliers: adding and viewing

6.02. Managing purchase orders

Managing purchase orders you have placed is an important part of running a medical supply facility. There are two main windows you will use to do this, along with a variety of reports.

Show outstanding purchase order lines....

Choosing this Suppliers > Show outstanding purchase orders from the menus or the Navigator displays a list of all lines outstanding on all confirmed Purchase Orders.

Using the find box

In the toolbar there is a field to enter searches. To the left of the field you can choose from the drop down list what to search for.

You can restrict the list displayed to a single supplier, to a single item, or to items whose delivery is expected within a specific number of days.

This search excludes finalised orders.

Printing and opening in Excel

Click the Print button to print the list as displayed. If you want to send the list to Excel, choose Open in Excel from the print options window that is shown after you click Print Double click on a line to display the Purchase Order containing that line

Show purchase orders

Choose Suppliers > Show Purchase Orders.

  • In the find window you can choose what will be displayed. By default mSupply displays the last 15 purchase orders.

  • You will be shown a list of matching Purchase Orders. Double-click a purchase order to open it.

For a more detailed description of this window see Ordering Items From Suppliers

Previous: 6.01. Ordering items from suppliers | | Next: 6.03. Purchase order categories

Updated: Version 4.02

6.04. Ordering from one store to another

If you run mSupply using virtual stores then you can place an order for goods with another store within mSupply.

There are two ways you can do this:

  • Create Purchase Orders. This method was the 'original' method, and is not recommended. In fact, from mSupply v7.0 this method has been removed.
  • The recommended (since mSupply v4.01) method is Internal Orders.

    Internal orders are the desktop equivalent of supplier requisitions in mSupply mobile.

Internal Orders are a simpler and easier way to place orders to another store if you've already been using purchase orders and goods received records in your workflow:

  1. In the requesting store:
    1. Create an Internal Order to the supplying store.
    2. When the internal order is finalised, a response requisition is automatically created in the supplying store
  2. In the supplying store:
    1. One or more customer invoices can be created from a single response requisition
    2. When each customer invoice is finalised, a supplier invoice is automatically created in the requesting store

Internal Orders

Internal Orders are also known as supplier requisitions or request requisitions.

Entering an internal order

To begin the process, choose Supplier > Show internal orders or click on the Internal orders icon on the Suppliers tab of the Navigator:

The following window will open, showing you a list of all existing internal orders:

  • Show drop down list: Set top Past 30 days by default, which will display all internal orders created in the last 30 days. You can select other options ot display All of them or those created in certain time periods or with certain statuses.
  • Type here to search field: If the list of requisitions is long you can type something in this field to display only requisitions in the list with a supplier name, comment, program or requisition number which contain what you have typed.

Either double-click on an existing order to edit it, or click the New internal order button to create a new one.

If you have activated programs in mSupply see the Programs heading below

The example below has a few lines already entered:

internal_order_edit.jpg

  • The Name will default to the supplying store for the current store, but any other visible store in the data file can be selected in the usual way (i.e. enter the first few characters and hit the Tab key to find matches).
  • The Order date defaults to the current date. You can change it.
  • Use either the New line button to manually add a single item, or Add from master list to add any items in the current store's master list which are not there already.
    • If adding from a master list, the cursor will go into the first new item's User requested quantity cell.
    • If adding a single item, the cursor will go into the User requested quantity cell for that item when it has been added. When you click on the New line button, this window opens:
      • Item: Type the first few characters of the item's name and press the Tab key on the keyboard to select the item from a list of items whose name or code begins with what you typed.
      • User requested: The quantity of units of the item the customer is requesting.
      • Comment: Any comment you want the supplier to see for this item.
      • Click on the OK button to add the line to the requisition, click the OK & Next button to add this line and empty the window so you can add another item right away or click the Cancel button to close the window without adding the current item to the requisition.
  • For each item,
    • mSupply already knows Our stock on hand
    • mSupply calculates the Average monthly consumption based on what the store has issued over the last 12 months (or less if the store hasn't been operating that long).
    • mSupply calculates the Months of stock from Our current stock on hand and the Average monthly consumption (this is therefore the months of stock at the current rate of consumption).
    • The Calculated quantity is then worked out by multiplying the Average monthly consumption by the Max MOS (maximum months of stock), and then subtracting Our stock on hand. If the resulting value is negative, a value of 0 will be displayed.
  • If the Use consumption and stock from customers for internal orders store preference is turned on (see 25.08. Virtual stores, preferences for details) then the Our current stock on hand figure comes from the sum of all stock currently held by all the customers of this store and the stock consumed is taken as the stock issued to all customers. Note that customer stores are those that have this store set as their supplying store.
  • The Max MOS is critical to this calculation, and you can change it.
    • There is an industry rule of thumb that the Max MOS should be set to 3 times the ordering cycle.
    • The default Max MOS is 3.0, which is based on an a monthly ordering cycle.
    • If, for example the ordering cycle was every two months, then Max MOS should be set to 3 x 2 = 6.0.
  • Hitting the Tab key will move the cursor into the Comment cell and, if there's another line below, hitting Tab again will move the cursor into the next User requested quantity cell.
  • If necessary, use the Delete line(s) button to remove selected item lines.

internal_order_edit_mos.jpg

If the order has a lot of item lines, you can filter them by typing into the Filter items field, which will change to display the number of visible items out of the total number in the order:

internal_order_edit_filter.jpg

Note that, while a filter is active, some of the other buttons are disabled e.g. you can't save the sort order unless all lines are visible.

You can also filter item lines which have a lot of stock (and therefore don't need to be ordered) by entering a value in the Threshold MOS field. This will automatically tick the Hide stock over threshold checkbox, and hide any lines which have their Months of stock greater than or equal to Threshold MOS.

internal_order_edit_threshold.jpg

Once you are satisfied, tick the Finalise checkbox. This will prevent further editing, and automatically delete any lines which have a requested quantity of zero.

internal_order_edit_finalised.jpg

When the order is then saved, it will automatically generate a corresponding response requisition in the supplying store. From there, one or more customer invoices can be raised in the supplying store which, when finalised, appear as supplier invoices back in the requesting store in the same way as regular stock transfers.

Programs

See the 4.05. Programs page for information on setting up programs.

Using programs activates a comprehensive system for managing orders and supplies by program. When you click on the New internal order button, before the order window opens, another window appears to allow you to select the program and period etc. that the order belongs to:

  • Order type: Selecting General will create a standard, non-program based requisition and none of the Order details section fields will apply. Selecting Program will create a program based requisition and you must fill in the details in the Order details section.
  • Order details section
    • Program: The program this requisition belongs to. Select one of the programs you have defined and assigned to this store.
    • Requisition type: Select one of the types of order you have defined for this program. Normal orders will follow the quantification rules and be limited in the number of orders per period. Emergency orders will not follow quantification rules and will not be limited in the numbers of orders per period but will typically be limited in the numbers of lines that can be entered on them.
    • Supplier: The supplying store for this store will be selected by default. Other stores can be seleted if required.
    • Period: The period this requisition is for. Will contain a list of all the periods which are still available for you to enter a requisition for i.e. those for which you have not already entered the maximum number of requisitions. The Start date and End date fields show the dates of the start and end of the selected period.

When you click on the OK button on this window, the requisition is created for you. The items defined for the program are automatically added to it and the suggested order quantity is calculated for you following the quantification rules.

Note that items belonging to the program will only be added to the order if they are also visible in the supplying store. This is to avoid the situation where you request an item that they don't have visible to them and therefore can never have any stock to supply!

Purchase orders

  • This method of ordering stock from another mSupply store is deprecated: Internal Orders (above) is the way to do it.
  • Purchase orders are used for Ordering stock from suppliers outside of mSupply
Using a purchase order to order from another store

For the most part, the process is the same as for creating a normal purchase order. There are, however, a few significant differences:

  • In the Name field of the purchase order, enter the name of the store which will supply your goods.

The names of suppliers which are stores will appear in RED in the choice list of suppliers. If the name of the store you select as a supplier is BLACK, then you have not chosen another store as a supplier (you will be creating a standard purchase order not an internal requisition), and the instructions in the remainder of this section do not apply.

Note: From mSupply v7.0 this method of ordering from another store has been removed. Store names have been filtered out of the name selection so it is not possible to send an internal requisition to another store this way.

  • The Internal requisition label will appear after the name to indicate that this is going to be an internal requisition.

Enter the purchase order lines as normal and when you're finished, confirm the purchase order (at this point you may be prompted to enter budget and/or category information, depending on your preferences):

Once confirmed, it will no longer be possible to:

  • modify the purchase order lines, except for updating the expected data of delivery (EDD).
  • delete the purchase order or any of its lines (mSupply will give you a warning if you try).
Processing the order (supplying store)

For versions of mSupply newer than v4.01, confirming the purchase order will create a response requisition in the supplying store (with your store's name in the Name field). This allows the supplying store to create multiple customer invoices to supply the order (and hence to better handle partially fulfilled orders). Once each customer invoice has been finalised, a goods received note for the purchase order will be created back in the store where you created the purchase order which started this whole process off (called the customer or receiving store).

Handling partially fulfilled orders

If you have unfilled lines on the customer invoice (i.e. red placeholder lines), when you finalise the customer invoice you will be asked if you want to create a new invoice with the unfilled lines. This new invoice retains the link to the purchase order that created the original customer invoice, and can be used to issue further goods to the customer.

Note that you can also create another invoice that is linked to the original purchase order at any time by using the "Duplicate" button on the toolbar of the customer invoice list.

Receiving the goods (requesting store)

Now, back in your store, where you created the purchase order which started this whole process off, you can view the goods received record via the Suppliers tab on the Navigator or via the File > Supplier > Show goods received menu item (or via the File > Supplier > Show purchase orders > Goods received tab)

Notice that on the goods received note the lines from the customer invoice will have been filled in automatically. Process the goods received note in the normal way and note that, as with all other goods received, the goods are not added to your store's stock and available for issue until the goods received note has been finalised and the resulting supplier invoice confirmed. Note that, from mSupply v3.85, the original purchase order lines will only be updated with the stock received when the goods received note has been finalised.

Previous: 6.03. Purchase order categories | | Next: 6.05. Multi-store Purchase Orders

6.01. Ordering stock from suppliers

The discussion here is focused on ordering stock from suppliers outside of your mSupply system, though the same principles apply when Ordering from one store to another.

Introduction to ordering

mSupply provides ways for you to generate a Purchase Order with manually or automatically calculated quantities. Each organisation tends to have different requirements for their ordering process, so we have tried to strike a balance between providing different methods and making the ordering module so complex that it is of little use to anyone. mSupply has two general methods for generating a purchase order:

  • Creating a new calculated purchase order. We recommend that you use this method since it will save you time and avoid mistakes.
  • Creating a blank Purchase Order. This method allows you to create a purchase order manually, which is useful if you think the information entered in mSupply is not complete or accurate or you want to base it on calculations of quantities you have made yourself or using other tools.

Whichever way you create a purchase order, the purchase order window looks like this:

New Blank Purchase Order

There is some read-only information at the top of the window which cannot be edited:

  • Order num: This is the purchase order's number. It is automatically generated and increments by 1 for each new purchase order. It is unique within a store only so it is possible for purchase orders in different stores to have the same number.

    The PO counter may get re-set to 1 under certain extreme circumstances like restoring the database from a backup on a new version of the mSupply software. This can result in the PO number not being unique in the same store. If you experience this, and want the PO numbers to continue in sequence from the last number, please contact support@msupply.foundation for assistance.

  • Confirm date: The date the purchase order was confirmed. If it has not been confirmed yet, this will be “00/00/00”.
  • Status: The current status of the purchase order - refer Purchase order status explained below.
  • Store: The name of the store the purchase order belongs to.

Creating a new (calculated) purchase order

Before launching into creating a new (calculated) Purchase Order, it is important to understand the logic that mSupply uses.

Logic used for calculating purchase order quantities

There are three distinct steps required to arrive at Purchase Order quantities for each line of stock:

mSupply uses this methodology to produce a suggested order quantities in a number of other places including:

To assist in understanding these calculations, an example will be developed through the following sections. Amoxycillin 250mg tabs/caps is being ordered at the end of December 2015. Historical consumption data is as follows:

Month 2013 2014 2015
Jan 200 1,000 1,000
Feb 250 1,050 1,100
Mar 300 950 900
Apr 350 1,000 1,000
May 400 1,200 1,400
Jun 450 800 600
Jul 500 1,000 1,000
Aug 550 1,150 1,300
Sep 600 850 700
Oct 650 1,000 1,000
Nov 700 1,100 1,200
Dec 750 900 800

From this data, the following historic AMC (Average Monthly Consumption) calculations can be made.

Period AMC
Last 36 months (Jan 2013 - Dec 2015) 825
Last 24 months (Jan 2014 - Dec 2015) 1,000
Last 12 months (Jan 2015 - Dec 2015) 1,000
Last 6 months (Jul 2015 - Dec 2015) 1,000

A more detailed analysis of this historic consumption shows a steady increase through 2013, and then the AMC sits at 1,000 per month in 2014 and 2015. In this case, we have an historic AMC of 1,000 per month regardless of whether we look at 6, 12 or 24 months of historic consumption data.

Forecast future consumption

See Quantification for a more detailed discussion of the various possible methods of quantification available in mSupply. For this discussion, the default 'Don't Adjust AMC' method is used, where the historic consumption is summed up for the number of months specified (defaulting to 12), and divided by the number of months. The assumption here is that future consumption will continue at the same level as historic consumption. mSupply has a number of other options for making a forecast of future consumption match what you think will happen or for accommodating features of your consumption data. The 4.21. Forecasting page contains a general descripotion and links to further detail.

Calculate required stock quantity

mSupply does not use set 'minimum' & 'maximum' stock levels as its primary means of determining order quantities. Conventional minimum and maximum stock levels are calculated using the methods described here, but it is problematic to try and fix these values, because:

  • The parameters will keep on changing and therefore so will the values,
  • It takes a lot of manual work to calculate,
  • The assumptions made in calculating them are often lost.

The ‘good’ reason to use ‘minimum’ & ‘maximum’ stock levels is if you don’t have a calculator like mSupply that can quickly and easily calculate the right amount of stock to order. Be assured that the system that mSupply uses will give you much better inventory control!

Having said that, mSupply does allow for minimum stock levels so as to allow you to ensure a minimum quantity of rarely used items. e.g. essential emergency supplies - see the Other information on the stock details page section on the 4.01.05. Items - Stock tab page for more information. These minimum stock levels should not be used for most items.

The amount of stock you require to have is based on the forecast of future consumption (previous section), modified by a range of factors including:

  • The Lead time: The time delay between carrying out the quantification analysis and when the stock is delivered to the store.
  • The Ordering cycle: How often you plan to order this item
  • The Buffer stock: How much of this item you plan to have on hand just before your next order arrives.

All of these are measured in months.

Some agencies recommend that Buffer stock (months) = 2 x Ordering cycle. If you have a central store with an annual order cycle, this means keeping two years worth of stock as a buffer. Expiry dates should not generally be problem, as a central store should definitely not be ordering stock with less than 3 years expiry. However, central stores may have limited storage capacity…

Stock required = Lead time + Ordering cycle + (months of) buffer stock

For example:

  • Lead time = 3 months
  • Ordering cycle = 6 months
  • Buffer stock = 12 months

From the equation above, Stock required is calculated as:

  • = Lead time + Ordering cycle + buffer stock
  • = 3 + 6 + 12
  • = 21 months.

So, 21 months worth of stock is required.

The amount of stock required is almost certainly NOT the amount of stock to be purchased! See the next section: Calculate purchase order quantity for an explanation.

Calculate purchase order quantity

Purchase Order quantities are based on the amount of stock required, normally expressed as a number of months of AMC, modified by factors including:

  • The current stock level (note: stock with no expiry date is counted as current stock for this calculation!).
  • The amount of stock on backorder to customers (if you are running the backorder feature).
  • The amount of stock already on order from Suppliers, but that has not yet arrived in your store.

Purchase order quantity = stock required - current stock level + stock on backorder to customers - stock on order from suppliers.

If the current stock levels and / or stock on backorder from suppliers is high enough, the above equation produces a negative number. This means that this item does not need to be procured during this ordering cycle. So, for the purposes of this mSupply calculation, the Purchase order quantity = zero or the value of the above expression, whichever is the greater. This is expressed mathematically as:

Purchase order quantity = MAX(0,stock required - current stock level + stock on backorder to customers - stock on backorder from suppliers)

It could be important to consider the months of anticipated stock-out (MOASO) - that is, the situation of running out of stock before the order arrives. There are (at least) two ways of dealing with MOASO:

  • Consider it: Reduce your order quantity by the MOASO because:
    • You will either obtain the shortfall through another purchase order (an emergency order, or from another supplier), or you will simply run out of stock.
    • Your customers will not increase their demand in the time immediately after you receive the stock from this purchase order to compensate for the stock being unavailable prior to the new order arriving.
  • Ignore it because:
    • Your customers will be using up their buffer stocks while you were out of stock, and so they will increase their demand in the time immediately after you receive the stock from this purchase order to re-build their buffers.
    • MOASO is too complicated to consider and explain!

It can be seen that

  • MOASO = the Lead time - Current stock level + stock on backorder to customers - stock on order from suppliers

If the above equation produces a negative number, this means that there will be no stock-out, and the anticipated stock-out will have no impact on the Purchase order quantity. So, for the purposes of this mSupply calculation, MOASO = maximum of zero and the above expression. This is expressed mathematically as:

MOASO = MAX(0,Lead time - Current stock level + stock on backorder to customers - stock on order from suppliers)

The automatic calculation of stock to order in mSupply does not include MOASO: it is only described here so that you can manually compensate for it in your choice of months of stock to order if you choose to do so.

Continuing our worked example, suppose:

  • Current stock levels = 5 months
  • Stock on backorder to customers = 3 months
  • Stock already on order from Suppliers = 2 months

Then, MOASO is calculated as:

  • = MAX(0,Lead time - Current stock levels + stock on backorder to customers - stock on backorder from suppliers)
  • = MAX(0,3-5+3-2)
  • = MAX(0,-1)
  • = 0

and Purchase order quantity is calculated as:

  • = MAX(0,stock required - current stock level + stock on backorder to customers - stock on backorder from suppliers - MOASO)
  • = MAX(0,21-5+3-2-0)
  • = MAX(0,17)
  • = 17

So 17 months worth of stock to be ordered. Compare this with the 21 months worth of stock required calculated in the previous section!

To demonstrate the impact of a stock-out, let us suppose that we have only 1 month's worth of stock on hand:

  • Current stock levels = 1 month
  • Stock on backorder to customers = 3 months
  • Stock already on order from Suppliers = 2 months

Then, MOASO is calculated as:

  • = MAX(0,Lead time - Current stock levels + stock on backorder to customers - stock on backorder from suppliers)
  • = MAX(0,3-1+3-2)
  • = MAX(0,3)
  • = 3

and Purchase order quantity is calculated as:

  • = MAX(0,stock required - current stock level + stock on backorder to customers - stock on backorder from suppliers - MOASO)
  • = MAX(0,21-5+3-2-3)
  • = MAX(0,14)
  • = 14

So, due to the 3 month anticipated stock-out, only 14 months worth of stock are to be ordered.

Create a purchase order

Choose Supplier > New Purchase Order from the menus. The following window will be displayed:

This window allows for a number of factors to be entered.

Types of order available from the popup menu

Firstly, you have the opportunity to select the order types:

Order for all suppliers
  • All items in the database will be evaluated to see if they need ordering. This is the default option
  • If you have a large number of items, this may take a few minutes.
  • By default, a single order will be generated. You have the option to generate a separate order for each supplier by checking the Separate order for each supplier box. In this case, mSupply will
    • For each item, look to see whether a supplier has been identified as preferred on a current quote
    • Create a separate order for each supplier.
    • Items without a preferred quotation will all be placed together in a single order.
Order for some items only

  • Either click on the Query items box, to bring up the Query Editor window, and enter the required parameters, or select one or more criteria by placing check marks as appropriate in the three boxes; use of the Query Editor is described in detail in the Reports chapter. See Using the Query Search editor. Please note that all items with the Never order this item checkbox checked will not be included in automatically generated purchase orders.
Order for one supplier
  • This method is the best method to use for ordering from a particular supplier (you might have guessed that!)
  • Enter the supplier code, and press the tab key. The supplier name will be filled in, or you will be given a list to choose from.
  • Any items that have a quotation from that supplier that is marked as “preferred” will be evaluated to see if they need reordering.
Calculate forecast

Secondly, the forecast of future consumption will be calculated in accordance with each item's settings as documented on the 4.21. Forecasting page. The only forecasting factor that can be adjusted here is the number of months of historical consumption data that will be used to calculated historical AMC.

  • The bigger the number you enter here, the more accurate mSupply is likely to be, provided that consumption has been reasonably stable over that period. Entering a large number will slow down the calculation.
  • Also, beware of extending this time period to a time in the past when data is inaccurate or non-existent. This will be detrimental to the quality of the forecast.

From our worked example above, consumption has been stable at 1,000 per month for the last two years (2014 and 2015), but was significantly lower in 2013. Putting 36 months would result in a lower AMC than has been the case for 2014 and 2015.

The number of months of historical consumption data to be used to calculated historical AMC will be ignored for those items that are configured not to use AMC in the forecast - see the 4.21. Forecasting page for details.

Calculate months of stock required

The months of stock required can be entered directly into the Months of stock required field. However, as demonstrated in the Calculate Purchase Order quantities section above, a more reliable way of getting to this figure is to use the Lead time, order cycle and buffer stock parameters. Clicking on the Calculate button brings up a window allowing you to enter these values, from which mSupply will calculate the quantity required and the Expected delivery date.

Using the same figures as in our worked example above:

  • Orders take three months to arrive from your supplier (Lead time = 3 months).
  • You order every six months (Ordering cycle = 6 months).
  • We want a buffer stock of at least 12 months when a Purchase Order arrives (Buffer stock = 12 months).

When you click on the OK button, mSupply will automatically calculate the Expected delivery date as the current date + the lead time (so, if the current date is 12th April and the lead time is 3 months, the Requested delivery date will be set to 12th July). This is important because mSupply assumes that your current stock will last until the end of the lead time and will not order stock for that period. So, even if the Months stock required is 9 months, if the lead time is 3 months (and so the Requested delivery date is set to 3 months in the future), then only 6 months of stock will be ordered. Of course, you can manually edit the Requested delivery date to alter the months of stock that are ordered.

The Requested delivery date field is set to the current day by default. If you manually enter a figure in the Months stock required field without using the Calculate button the Requested delivery date will not be automatically updated. So the order will be for the full number of months you enter in the Months stock required field.

  • The Requested delivery date affects the amount of stock that is ordered because mSupply assumes that your current stock covers that period and therefore does not order for the period up to the Requested delivery date.
Other settings in the create order window
AMC adjustment for out of stock

This field gives options for adjusting the consumption calculation if items are not fully in stock over the period of interest. See the 13.04. Purchasing reports page for a full description of what the various options are and what they do.

Comment

Add a comment (note) to the order should you so wish.

Exclude transfers from usage calculations

This option is only applicable if you are running multiple (virtual) stores. If you have more than one store, this option controls whether inter-store transfers are taken into account when calculating historic consumption. The default setting is not to exclude transfers. That is, stock transfers will be included in the calculation.

Include usage for build ingredients

Selecting this option ensures that any items that were used in builds (i.e. manufactured items) will be taken into account when calculating historic consumption.

Builds can be entered with placeholder lines to reflect a projected manufacturing schedule. If the Include usage for build ingredients check box in the “new order” window is checked, the proposed order quantity for each item will be adjusted by the amount of the item that is required for all projected builds, multiplied by the “times covered” value you have entered.

Using our worked example:

  • Let us say that we wish to 'build' a kit which includes 100 x Amoxycillin 250mg tabs/caps.
  • We have a projected build for 200 of these kits.
  • This will consume 20,000 Amoxycillin 250mg tabs/caps.
  • We enter 1.5 in the times covered box
  • Then the additional quantity of Amoxycillin 250mg tabs/caps that will be added to the order will be:
    • = 100x200x1.5
    • = 30,000 tabs/caps
  • In our worked example, ignoring projected builds, 14 months usage was to be ordered.
  • The AMC is 1,000 per month.
  • Without taking into account projected builds, this would result in an order of 14,000 tabs/caps.
  • When we add the usage of the projected builds, the amount to be ordered will be:
    • =14,000+30,000
    • =44,000 tabs/caps
Include items with suggested zero order quantity

If mSupply calculates that any of the lines from the supplier are not required, when this box is checked such lines will appear on the Purchase Order, the order quantity being 0.

Expiry consideration

The checkbox to Exclude stock that will expire within 3 months of projected consumption date is a new updated feature to accurately predict amount of stock that is likely to be wasted due to expiry and current consumption rate. In this current example, mSupply will only aim to distribute stock if the expiry is more than 3 months away. This updated feature is only available in mSupply v7.12 or later.

This topic is huge so it may be worth reading this topic Stock wastage prediction for ordering

Create order button

Once you have entered the details, click the Create order button. Order generation may take a couple of minutes, depending on how many items need to be evaluated. You will then be presented with the following Alert box:

Clicking on OK will close the Alert box and return you to the Navigator.

Creating a blank purchase order

Choose Supplier > New blank Purchase Order . You are presented with a blank order form, to which you can add items. This form only allows the choice of one supplier.

New Blank Purchase Order

Name

The name field is where you choose the supplier you are ordering from (type in the first few characters of the supplier's name and press the Tab key on the keyboard, then select the right supplier from a list of those beginning with what you typed - if there's only one that matches, it will be automatically chosen for you).

Donor

If it has been set in Preferences, the Donor field will appear, and the donor details may be entered here (in the same way as entering the supplier name - type the first few characters of the donor's name and press the Tab key to select from a list of donors starting with what you typed). Setting this preference is described in Supplier Invoices.

Reference

The Reference field allows you to enter any relevant information. Anything you type in here will be carried through to the Their ref field on the Goods Received note and Supplier Invoices created from the Purchase order (but can be overridden if required). This is true whether the purchase order is created manually or calculated for you by mSupply (as described above).

Requested delivery date

The Requested delivery date (RDD = contract delivery date ;-) ) field is for the date you have requested the supplier to deliver the items. Anything entered in this field becomes a default for all lines added to the purchase order. Such a requested delivery date can still be manually edited for each line if required.

By default the Requested delivery date will be today's date but you may edit this to request deliveries at the times you require.

This is optional unless you have turned on the preference to make it mandatory (see Purchase order preferences for details).

Colour

In the top right hand corner, there is a box where you may select a particular colour from a range of colours - in the window shown below, blue has been selected.

The purpose of this is to distinguish this particular Purchase Order in the Purchase Order list - see the example below where PO number 5 is shown in the selected colour (blue):

Adding Items to the PO

Once a supplier(Name) has been chosen you may add the item(s) you are ordering by clicking the New Line button.

Item

In the Item field type the beginning letter of the item you want and hit the Tab button. You may then choose the item from the displayed list. If you want to see the entire list of items available type @ and then Tab.

For more information on the other tabs in this window see Editing Purchase Order lines.

Please note that items that have the Never order this item checkbox checked cannot be added to a manually created purchase order.

Saving a suggested Purchase Order

Once you have chosen Items and entered the appropriate details clicking OK will return you to the Edit Purchase Order screen where you will see the line you have created. Below we have ordered 300 Packs of Chlopromazine.

The Original and Adjusted Quantities columns show the number of packs you ordered multiplied by the number of units in the pack.

Clicking OK here will save the PO with a status of 'suggested' (sg). It can be edited later and then confirmed for issue to the supplier.

Finding a purchase order

To find a recently created order choose Show Purchase Order… from the Supplier menu.

Choosing this menu item shows a window where you can enter either the number of recent orders to display or the order number (this is printed on an order if you have printed it out). If you click OK without changing any information you will be shown a list of the 15 most recent orders.

You will then be shown a window with a list of Purchase Orders. (If you entered a Purchase Order number you will be taken straight to the Purchase Order details window, bypassing the Purchase Order list, as shown above).

Buttons in the purchase order list window

New PO (purchase order)

When you click the New PO button, a Purchase Order details window is displayed . See “New Purchase Order” below.

Delete

Clicking the Delete button will delete any highlighted POs, with some exceptions - see below.

You can delete multiple Purchase Orders by highlighting more than one line. To do so, control-click (command-click on Mac) the lines you wish to highlight, and then click this button.

  • Confirmed POs need to have each line deleted on the PO before the PO itself can be deleted. If you try to delete a confirmed PO and it is not empty, you will get an alert message like this:
  • Finalised POs can not be deleted. If you try to delete a finalised PO, you will get an alert message like this:
Report

Clicking on the Report button presents you with the quick report modifier window, from which a simple report can be constructed. This report can be viewed, saved to disk or printed.

Find

This button is very useful for quickly finding a group of Purchase Orders. when you click on the Find button, you will be presented with a window with the same functionality as if you chose the Menu item Supplier > Show Purchase Orders (above).

Order by

The Order by button allows you to sort the orders by multiple fields. Otherwise simply clicking on an individual column will also sort the order list by that column.

Print

This allows you to print the displayed list of purchase orders. When you click on the Print button, it shows two windows. The first is the page setup for your printer, the second allows you to specify how many copies to print. The column sizes set in the list window are reflected in the printed output.

Customise

This button allows you to change the columns that are displayed in the list and what order they are displayed in:

See Working with lists for more details.

Duplicate

If you wish to duplicate any orders, highlight desired orders from list and click the “Duplicate” button.

Split

This button allows you to split the selected order between two or more suppliers, and may be used only on orders with a status of sg.

Finalise

This button allows you to finalise multiple purchase orders at once. Simply highlight a selection of purchase orders in the list and click on the button.

Only Confirmed status purchase orders will be finalised; purchase orders of any other status will be ignored. After finalisation has been carried out you will be told how many were successfully finalised and how many couldn't be updated because they weren't confirmed or because they were in use by someone else.

Editing a purchase order

After searching for a Purchase Order, double-click the order in the list you want to modify.

You will be presented with the General tab of the Edit Purchase Order window:

You can resize the order modifying window to show more lines, or to show more of the item name. To do so, drag the handle in the lower right corner to a new position.

If the entire order qualifies for a discount, either the discount percentage OR the cash value of the discount should be entered.

Split deliveries

There may be occasions when you want to arrange for split deliveries - for instance if you are placing a single order for a year's supply, but you want certain items to be delivered in, say, four consignments, at three monthly intervals. The order as generated lists the total quantity to be ordered, and you need to modify this; what you are actually doing is modifying a Purchase Order line. The procedure is described in Split deliveries in the order menu

Editing purchase order lines

To modify an order line, double click on the line you wish to modify.

When you double-click an order line (or when you click on the New line button) you will be presented with a window allowing you to modify the item, quantity and pack size:

Information in the Edit order line window
Item

Here you can modify the item that is being supplied. To change the item, type as much of the item name as you know, then press the tab key. If only one item matches your entry, it will be filled in automatically, otherwise you will be presented with a list where you can double-click the item you wish to enter.

Number of packs

The original quantity ordered from the supplier. This information is not modifiable once you have confirmed an order.

Pack size

This is the pack size you are requesting the supplier to provide, or the pack size the supplier has said they can provide. Normally you will want the supplier to supply the item in your preferred pack size, which is what will appear here by default.

Units

The units that the pack is measured in.

Supplier item code

The Supplier's item code for this item can be entered here. This field is optional.

Price before discount

The price quoted by the supplier for one pack (of the pack size shown in the Pack size field) of this item. If you enter it here, it will be carried through onto the goods received note and then the supplier invoice. Of course it can be edited on the supplier invoice if the delivered price turns out to be different to what is entered here). Entry of this field can be made mandatory if the preference is turned on (see Purchase order preferences - unit cost (price before discount) for details).

Discount

Enter any percentage discount that applies to this order.

Extension

The price multiplied by the quantity ordered.

Volume per pack

In this field, you can define the volume per pack for the pack size chosen. If you are entering a new line the volume and pack size you have entered for the item will be used.

Note the mSupply always stores volumes as m3 (cubic metres), but you can enter a volume as millilitres (ml), litres (L) or cubic metres (m3)

Shelf location

Type the first few characters of location name or code as you know, then press the Tab key. If only one location code matches your entry, it will be filled in automatically, otherwise you will be shown a standard choice list with the option to create a new location.

Adjusted quantity

The total quantity you now expect to receive from the supplier in all consignments. You can adjust this figure so that the amount received is reduced or increased due to changes agreed with the supplier.

Refresh buttons

The refresh button (to the right of Volume per pack), on clicking, displays the default volume of the selected item if it has been set previously. Similarly the refresh button next to Shelf location displays the default location.

The refresh button in the “Pricing for this item” frame reloads the price data from a preferred quotation. The price from the most recent quote is used if there are no preferred quotations. If you have received an updated quotation after generating the original price, use this button to apply the updated details to this line.

Requested delivery date

The Requested delivery date for each PO line is inherited from the PO. It can be manually overwritten for each PO line. For example, you may have a PO with a Requested delivery date of 30 June, but you have agreed with the supplier to deliver one of the lines a month earlier, on the 31 May.

Expected delivery date

The Expected delivery date can be entered manually at the time of originally populating the PO line, but it would normally be entered once a response from the supplier has been received.

Comment

Put anything you need to have recorded for this purchase order line in here. It will print against the line when the purchase order is printed out.

Notes

Any important notes you need to make about this purchase order line should go in here. These notes will not print out when the purchase order is printed but, if you check the Show notes on Goods Received checkbox, the note will be displayed on the goods received note line and the line will be coloured red when the goods are received into mSupply - see Goods receipts for details.

Other information in the Order line details window:

On hand: This is the quantity of stock on hand of the item

On order: This is the quantity of stock in other confirmed orders awaiting delivery.

On backorder: The quantity of stock you owe to customers on backorders

Quantity received: The total quantity of this line that has already been received on this order.

Tabs in the Order line details window
Usage tab

This tab shows the usage for the last 24 months of the item being viewed. This is useful for deciding if reported usage is consistent from month to month, or is due to one or two very large supplies to clients.

Quotes tab

This tab shows quotes from suppliers for the item being viewed.

You can double-click a quote to view and/or modify details.

View quotations for the item in question. You can double-click a quotation to modify its information.

Note that the supplier of the quotation that is marked as “preferred” will be the supplier selected when using the “split” command to break a general order into orders for each supplier.

The New button allows you to add a new quotation.

Receipt history tab

This tab shows all goods receipts for the item being viewed.

If you double-click a line the associated goods receipt transaction will open in a new window.

Ledger tab
  • This tab shows supplier and customer invoices for the item being viewed.

  • You can display a sub-set of the transaction lines by choosing options from the drop-down lists.
  • The option Received ledger for this Purchase Order line shows all supplier invoice transactions for the current Purchase Order line item. This is particularly useful if you want to see the history of prices paid for this item.
  • Goods receipts are shown on the Receipt history tab.

  • Unordered List ItemThe Dates drop-down list allows you to show only recent transactions….

  • If you double-click a ledger line, the associated invoice will be opened in a new window
Buttons in the Edit purchase order line window
OK & Next

This button will take you to the next order line, unless you have reached the last line in the order, in which case you will be taken back to the order modifying window.

OK

Will exit the window saving changes to the current window.

Delete

If you click the Delete button, the order will be deleted and the order number will be reused for the next order.

Purchase order status explained

Purchase orders generated from a tender will start with the status “tn” (for “tender”). For more information on purchase orders from tenders see the 18.07. Analysing supplier responses and creating purchase orders page for details

  • When a purchase order (PO) is first created it has status “sg” (for “suggested”)
    • POs with status sg can be modified in almost every way, including changing the supplier.
  • Once there are no more lines to add to a PO, it can be confirmed and sent to the supplier. A PO is confirmed by clicking on the Confirm button.
    • Once a PO is confirmed, it has status “cn” (for “confirmed”) and an appropriate log entry is created.
    • Confirmed POs have the order amount added to the “on order” field for each item, so that if another PO is created for the same item, this quantity already on order will be taken into account.
    • Confirmed POs can have new lines added to them but only with an adjusted quantity, not an original quantity. This is to allow for amendments made by the supplier after they have received the order.
    • Details of existing confirmed PO lines can be amended. Their adjusted quantity can be amended (to reflect changes made by the supplier) original quantity cannot be amended.
    • Lines can be deleted from a confirmed purchase order as long as nothing has been received against them on a goods received note. If any part of a line has been received on a goods received note then mSupply will show an alert and will not allow you to delete the line.
  • Once no more stock is to be received against a PO, it can be finalised. An order becomes finalised by clicking on the Finalise order tick-box at the bottom left of the PO window.
    • POs that have been finalised have status “fn” (for “finalised”) and an appropriate log entry is created.
    • Finalised POs can no longer be modified in any way.
    • No more goods can be received against a finalised PO. The `unsupplied' lines will not appear when you look for outstanding PO lines (Supplier>Show outstanding PO lines) and the `unsupplied' quantities are ignored in any of mSupply's subsequent Stock on order calculations.
Estimated order costs explained

From version 1.7 onwards, mSupply displays a new column (Price Ext) in the order modifying window that shows the cost of the order line.

Tabs on the Edit Purchase Order window

The General tab

Refer Editing a purchase order above for details on adding lines to this.

Buttons on the General tab
New line

Click this button to add a new line to the Purchase Order. You will be shown this window:

You may enter the quantity of the item either by number of packs or by total quantity. mSupply will automatically fill in the other fields for you.

Delete lines

Select one or more lines in the Purchase Order and then click this button to delete the lines from the Purchase Order.

Update EDD

Select one or more lines in the Purchase Order and then click on the Update EDD (Estimated Date of Delivery) button to enter a new date when delivery is expected.

Info

Click the Info button to display information about the Purchase Order including the name of the initials of the Purchase Order creator and modifier - refer figure below.

Notes:

  • If the Purchase Order has not been modified, then a modify date of 00/00/00 will be displayed.
  • If there is no name against the Created by and Modified by entries, then this Purchase Order was created / modified on the Primary Server in a synchronised mSupply system.
Print

Clicking the Print button will print the complete Purchase Order form for sending to a supplier. Note that you should fill in relevant details on the Details tab before printing the order.

Confirm

See the section above on “order status” for an explanation. Orders should be confirmed once the order has been placed with the supplier.

Check boxes on the General tab
Locked

When the locked check box is checked, the Purchase Order cannot be processed to the next status (confirmed or finalized) - refer Order Status explained.

Auto calc usage

When the Auto calc usage check box is checked, each time you modify an item line, the usage for that line will be calculated. This is slower, but gives useful information upon which to base your ordering . Note that this option can also be turned on within the order line modifying window.

When the Print my signature check-box is checked, the user's signature will be printed on the Purchase Order if it has been loaded - refer Managing users.

Details tab

This tab allows you to record a range of information that will be entered on the Purchase Order when it is sent to the supplier.

PO sent date

Enter the date the Purchase Order was sent to the supplier. When you print a Purchase Order mSupply will offer to fill in this date for you, but you should modify it if necessary to reflect the exact date.

Contract signed date, Advance paid and Received at port fields

Enter dates in these fields as appropriate. They are all optional unless any of them are made compulsory by turning on the appropriate preferences on the Purchase orders 2 tab of the File > Preferences… menu item. See Purchase order preferences for more details.

Minimum expiry date field

This field is only turned on if the Items received from a purchase order must be within a minimum expiry date store preference is turned on (see the 26.07. Virtual stores page for details on how to turn it on).

If a valid date is entered in this field, stock received on a goods received note must have an expiry date that is later than this date. Otherwise, you will not be able to finalise the goods received note. Please note, this setting does not affect supplier invoices.

Heading message

Any text you enter here (e.g. Urgent or Supplementary order for PO 183) will be printed in a large font across the top of the Purchase Order so your supplier will (or at least should) notice the message.

Expected delivery

Enter the date you expect the order to arrive

Goods received date

Fill in the actual delivery date. Leave the date blank for Purchase Orders that have not been delivered

Invoice received

Enter the date when you received the invoice from the supplier

Hint: you can find all orders that have not had an invoice supplied by querying on this field.

Comment

You can enter any appropriate comments here.

Supplier's agent

Enter the name of the intermediary party here - if there is one.

Delivery method

Enter a delivery method (eg “Air”, “Courier” …)

Authorizing officers

Enter the names of the people who are required to sign off the Purchase Order. These names are printed on the Purchase Order.

Freight conditions

Enter the delivery address, shipping marks, etc. here.

Additional instructions

Enter any further information you wish to appear on the Purchase Order.

Commissions and charges fields

Fill in any relevant charges agreed between you and the supplier. Note that any charges that are zero will be skipped when printing the Purchase Order.

Ad hoc items tab

Here you can display a list of items that have been assigned to the supplier, but not yet added to a Purchase Order.

Click on a line, then click the “Add selected line to order” button to add a line to the current Purchase Order.

Warning: if you delete a line from a Purchase Order it will not have its status updated automatically- it is your job to do so using the Items > Manage Ad Hoc items menu.

New ad hoc line button

Here you can add an ad hoc item “on-the-fly”. This is useful if you want to process a Purchase Order for a single Ad Hoc item that has not yet been entered into mSupply.

Note that the Items > Manage Ad Hoc items menu is the normal route to add, modify and delete Ad Hoc items.

Goods received tab

This is a record of the receipt of the order, and, where multiple deliveries have been made, records each instance.

Supplier invoices tab

This tab displays a list of invoices related to this Purchase Order.

There are two types of invoice that are created directly from Purchase Orders:

Log tab

This tab records a log of actions that have been performed on this purchase order. The below image shows that the Purchase Order has been confirmed for sending to the supplier and printed by the user Margaret at the date and times shown:

Location tab

This tab displays the locations of the items received, if this feature is used. Where details of the volume of available space in any location has been entered, and where details of the area/volume of item pack has also been entered, the remaining available space will be displayed.

Lines will also be coloured red/orange/green to indicate greater than 100%, 90 to 100% or less than 90% of space used. showing which lines are likely to cause space problems on receipt.

Custom data tab

This tab contains all the custom fields created for the purchase order table in the preferences. See the 16.11. Custom fields page for details on how they are set up.

You can enter any data in the fields as appropriate. When you click on the OK or OK & Next button the information in the fields is saved.

Documents tab

This tab allows you to upload any documents you wish to the purchase order. The table shows you the documents already uploaded.

To add a document, click on the Add button. A new window will open for you to select the file from your computer. Double-click on the file or click on it and click on the Open button to add it to the purchase order.

To delete a document from the purchase order, click on the file in the table to select it and click on the Remove button.

To view a file or download it, double-click on it in the list.

Order menu

When the order modifying window is being shown, an extra menu is added to the menu bar:

Copy order to clipboard

Copies the order details to the clipboard, so you can paste it into an email or text document.

Export html...

If you want to produce an order which can be saved as a file in html format, use this option. . If you have Excel installed, the report will open in Excel. Note that if you want to keep the Excel file, you should choose File > Save as.. in Excel and choose a location.

Print

Prints the order. You will be shown the standard printing dialog boxes.

Note that if Show all lines is selected, the entire order is printed; if Show incomplete lines is selected, the printout lists only lines which have either not been supplied at all or require a balance to complete the order.

Split

Splits the order into a number of smaller orders based on the preferred supplier for each line. The preferred supplier is the quotation that is marked as “preferred” for that item. To view and modify quotations you can double-click the order line then chose “quotes” from the “show” menu. All items that do not have a quotation marked as “preferred” will be put into a separate order.

Email in body

The order will be turned into an e-mail and placed in the queue so that it is sent next time you send e-mails. You will be warned if you have not entered an e-mail address for the supplier.

The e-mail will be formatted as follows:

To check the email before sending it, choose Special > show l_formatemails , then double-click the email to modify it. Note that to make the columns line up properly, you will have to click the <|-|> button to view the text in a fixed-width font.

Email HTML attachment...

The order will be turned into an HTML attachment, and attached to a new email that is then placed in the queue so that it is sent next time you send e-mails. You will be warned if you have not entered an e-mail address for the supplier. The attachment will be stored in the export folder you have nominated in the Preferences. (For multi-user mSupply, the export folder is set as the folder “C:\mSupply\mSupply client\Export” (on the assumption that you have selected the default install location for mSupply).

Email PDF

Choosing this item will cause mSupply to generate a PDF file, create an email and attach the PDF file to the email.

Note that you must use the PDF xChange PDF driver installed on the computer generating the email for this to work. The driver currently costs US$50, and is available from Sustainable Solutions info@ss.org.np

The PDF that is created is stored in the mSupply data file, so you can create a PDF attachment on one computer and send it from a different computer without problems.

Update quotes using this order

This command allows you to check that quotation data is up to date based on actual supplied prices.

Each order line will be evaluated, and if a quotation does not exist, one will be created. If a quotation does exist and the price you have paid in the order and the price stored for your quotation are different, you will be shown a window to compare prices, and you can decide whether to keep the existing quotation or update it.

Note that you need to have your user permissions “Can add quotations” and/or “Can modify quotations” set before this command is available.

Split deliveries

Creating split or multiple deliveries will now be described using the following example.

It is important to note that the Purchase Order should not be finalised before this procedure is performed, as a finalised order may not be modified or altered in any way.

A store is placing an order for Normal Saline and, having followed the normal procedures, mSupply has created the Purchase Order displayed: below.

The store does not have the storage capacity to hold 1250 packs of Normal Saline, so the supply of this item needs to be made in multiple deliveries; it is decided that 500 be requested for delivery at the beginning of January, followed by 250 at the beginning of each of the months of April, July and October - i.e. at three monthly intervals.

The Purchase Order is modified as follows:

  • Click on New line, and add the item Normal Saline
  • In the Number of packs field, enter 500
  • In the Requested Delivery date enter 1/1/17
  • Click OK & Next
  • In the Number of packs field, enter 250
  • In the Requested Delivery date enter 1/4/17
  • Click OK & Next
  • In the Number of packs field, enter 250
  • In the Requested Delivery date enter 1/7/17
  • Click OK & Next

Repeat the last two steps, but enter 1/10/17 in the Requested Delivery date field for the final delivery in October.

To complete the process, delete the line calling for 1250 units on 1/1/17.

The Purchase Order should now look like this:

You won't see the different requested dates on this screen. Expected dates are generated upon feedback from the supplier or can be entered manually.

This feature enables mSupply to take future deliveries into its reckoning if, for example, an additional order for Normal Saline was placed in mid June, and a delivery of 2,500 had already been arranged for 1 July.'

Authorising purchase orders

If required, it is possible to turn on authorisation of purchase orders. See Authorisation for details.

Purchase order categories

Purchase order categories are useful for separating up your purchase orders when reporting. For details about setting them up and assigning them to purchase orders, see Purchase order categories.

Previous: 6. Purchasing | | Next: 6.02. Managing purchase orders

6.05. Multi-store Purchase Orders

The multi-store purchase order will enable you to create a purchase order that includes lines for many stores at once.

Limitations

  • You can only create a multi-store purchase order when logged in to the Supervisor - All stores store.
  • You can only create a multi-store purchase order as a blank purchase order. You cannot create a calculated multi-store purchase order (yet;-)).
  • You cannot use multi-store purchase orders to order from another store in the mSupply system.
  • For a specific item, you cannot order different pack sizes for different stores. For any item, all stores must have receive the stock in the same pack size.

Set up

To make a store available for multi-store purchasing, you will need to go into the store preferences and add a custom field labelled canBeIncludedInMultiStorePOs with its value set to true:

  1. Log into any store
  2. Special > Show stores…
  3. Double click on the store name in the list
  4. Go to the Custom fields tab
  5. Add a new line that looks like this (be VERY careful to get the spelling of canBeIncludedInMultiStorePOs correct. It is case sensitive):

How it works
Permissions

To be able to create a multi-store purchase order the user must have permissions to:

Creating a new purchase order

To create a new multi-store purchase order

  1. login to the Supervisor - All stores 'store'.
  2. Choose Supplier > New blank Purchase Order.
  3. Enter in PO general details as usual. As with a normal purchase order, only one supplier can be chosen, but for multi-store purchase orders this supplier cannot be an mSupply store in your system.

When entering a new line, you will be presented with this window.

  • Select an item in the normal way.
  • After choosing an item, a line will appear in the table for each of the stores that you have setup to be included in multi-store purchase orders, along with the default pack size for that item and the currently set requested delivery date.

  • If you put a price per pack and a discount, the discounted price per pack will be calculated and applied to each line.
  • For each store, you can specify the number of packs to order.
  • The total quantity will be automatically calculated.
  • You can change the requested delivery date and add an expected delivery date either manually or through the calendar icon on the column to the right.
  • When you click OK, only the lines for which the number of packs is not 0 will be included in the purchase order.
  • The other tabs are the same as normal purchase orders with two exceptions:
    • Usage tab When adding a line for a normal purchase order, the usage is calculated for the currently logged in store only. For multi-store purchasing there is now a dropdown list that lets you choose for which store you want the usage to be calculated.
    • Ledger tab There is also a dropdown list in the ledger tabs, where you can select the store for which you want the ledger to be displayed.
Editing a new purchase order

To edit a multi-store purchase order line

  1. login to the Supervisor - All stores 'store'.
  2. Open the purchase order
  3. Double-click on the line you want to edit. All the lines pertaining to that item will be loaded.

Here’s an example of a multi-store purchase order opened in supervisor mode:

If you double-click on the first line of the “Acryliser, Electric” item, all five stores’ order lines for that item will be loaded.

  • You can change the pack size, the price, the discount and the requested and expected delivery dates.
  • If you put 0 as the number of packs for a line that had previously contained a quantity, this line will be deleted when the user clicks the OK or OK & Next button.

As with normal purchase orders, when a purchase order has been confirmed it is no longer possible to go back and edit the order lines.

Viewing multi-store POs when logged in to the receiving stores

When logged in to the receiving stores, multi-store purchase orders can be identified by an asterisk (*) after the supplier name in the purchase order display list.

  • A multi-store purchase order appears in the purchase order list of each store for which goods have been ordered.
  • When viewed in a particular store, only the lines that belong to that store will be displayed - see example:

Furthermore, the displayed lines will not be editable. To edit the lines, you will need to accessing it in supervisor mode.

Goods receipt

Good receipting will function as normal (refer Goods receipts) but only the lines pertaining to the store you are currently logged in to will be available.

Previous: 6.04. Ordering from one store to another | | Next: 7. Receiving Goods

6.03. Purchase order categories

Sometimes it's really helpful to categorise your purchase orders for reporting purposes. To allow you to do this, mSupply allows you to create purchase order categories and then apply them to purchase orders as needed.

Viewing purchase order categories

Choose Supplier > Show purchase order categories… from the menus. You will be shown this window:

This shows a fill list of all the purchase order categories that you have at the moment. The user_field_1-3 columns show the values of the custom values given to each category, which can be used to further refine your reporting later.

Adding, deleting and editing purchase order categories are all done through this window.

Adding purchase order categories

Click on the New button in the window shown above to add a new category. This window will open:

  1. Enter the following:
    • Category name: Description of the category. This is name by which the category will be known and selected throughout mSupply
    • user_field_1: Any alphanumeric value
    • user_field_2: Any alphanumeric value
    • user_field_3: Any numeric value
  2. Click on the OK button to save the new category

You will see the new category immediately added to the list of available purchase order categories.

Deleting a purchase order category

Select the category to delete in the list of purchase order categories and click on the Delete button. You will be asked to confirm the deletion.

Note: you will only be able to delete a purchase order category if no purchase orders belong to it.

Editing an existing purchase order category

To edit a purchase order category simply double-click on it in the list. The same window as for adding a new purchase order category will open populated with the selected category's details. Simply edit the details as required and click on the OK button to save your changes.

Assigning categories to purchase orders

Assigning categories to purchase orders is really simple, as you'd expect! When editing or creating a purchase order, simply select the category the purchase order belongs to using the Category drop down list on the General tab:

The drop down list will contain the descriptions of all the categories you have added.

Previous: 6.02. Managing purchase orders | | Next: 6.04. Ordering from one store to another

7.05. Custom stock fields

Custom stock fields are a useful way of tracking your stock. You can think of them as providing stock tags or categories which can be seen wherever stock is viewed throughout the system and can be used for filtering reports.

There are 8 custom stock fields available. The first 4 are free text (the user can enter any text they like) and the final 4 allow the user to select values from preset lists defined by you.

Setting them up

You turn them on in the stock tab of File > Preferences. See here for details.

To define the lists the user can select from for custom stock fields 5 to 8, click on the Item > Show custom stock field value lists… menu item. This window is displayed:

In the Show drop down list, select the custom stock field you want to add/edit/delete values for. Note that the items in the list will be “Custom stock field 5” to “Custom stock field 8” but those fields which have been given a Display name in the preferences will be replaced by it. In our example, Custom stock field 5 has been given the display name “Programme”:

The custom stock field values table below the drop down list shows all the values currently in the list for the selected field.

New button Click on this to enter a new item for list for the custom stock field currently selected in the show drop down list. Note that the list of items will always be displayed in ascending alphabetical order for a user to choose from.

Delete button select an item in the list and click on this button to delete an item from the list

Double click on an item in the list to edit its name

Using them

Now that they have been set up, when you receive goods in on a supplier invoice the enabled custom fields will appear on the supplier invoice line detail window. Enter the values in there as you receive stock into mSupply. The values will then appear wherever you see stock in the system e.g. on the stock tab of an item's details window.

The fields will also be available for filtering on when you are running any of the stock based reports.



Previous: 7.04. Managing outstanding purchase order lines (pipeline stock) | | Next: 7.06. Managing donors

7.06. Managing donors

What / who is a donor?

In mSupply, we have the idea of a 'name'. A name can be a customer, a supplier, a patient, … or a donor.

A donor is normally the name of the organisation that has paid for, or somehow managed, the supply of certain stocklines.

A donor can also be a supplier and / or a manufacturer or they can be just a donor. mSupply allows for any combination of that.

mSupply allows you to specify the donor for each incoming stock line independently of the supplier.

For example, GlobalFund might agree to supply certain malaria medicines, and then contract a supplier to deliver them to you. mSupply allows you to record this accurately, and to track and report on all the stock and transactions relating to those medicines donated by GlobalFund.

The Donor feature was designed for the purposes of tracking and reporting on stock that has been funded by a donor. However, the feature can be used for more than just tracking donors. For example, In many countries that use mSupply, most medical supplies are supplied free-of-charge to the health facility by a government agency. But if the government agency has not supplied stock, the facility might decide to procure the stock 'privately'. The facility management will often want to keep track and report on this privately procured stock. The donor feature can be used for this purpose. The 'donor' name for this purpose might be called Privately procured.

Using the donor module

To use the donor module, you must first turn it on:

  • Click drop down menu File>Preferences…
  • Click the Invoice 1 tab in the left-hand list
  • Check the box Allow tracking of received stock by donor

Once you have done this you can add donors and track stock by donor.

Adding or editing donors

To add or edit a donor you should first bring up the list of donors. Do this from the Navigator:

  • Go to the Suppliers tab > Show Suppliers and check the box beside Donors so that the list shows donors rather than suppliers.
  • Click Find. This will bring up a new window showing any donors that have been added to mSupply in your system
  • You can edit a donor by double-clicking on it.
  • You can add donors using the New tool bar at the top of the window. This will bring up a window like this:

  • Now add your donor details and click OK.

Track a donor in mSupply

Donors and the purchase order
  • Create a Purchase Order in one of the usual ways - refer Ordering Items From Suppliers.
  • With donor tracking turned on, the Donor field will appear in the window - see below. The value you enter here will be tracked from this point on through to receipt, stock transfers and dispatch.

  • In the Donor field type the first few characters of the donor name or code (or enter the wildcard character '@' in field) and press the Tab key on the keyboard. This opens the window below, showing the donor that match what you typed:

  • If your donor does not exist, you can add it at this point by clicking on the New button - see Adding or Editing Donors above.
  • Once you have selected your donor, click on the OK button and the donor's name will appear in the Donor field:

  • Add your Item line(s), check your order is correct and click the Confirm button to make the order available for Goods Receipt in the normal way - see Ordering Items From Suppliers for more details.
Donors and the goods receipt function

Receive goods in the usual way - see Receiving goods (Goods Receipt function). The only difference is that the Donor's name is now present in the Donor field:

Donors and the supplier invoice
  • Clicking Finalise on the Goods Receipt generates the Supplier Invoice in the usual way (see Receiving Goods - a Supplier Invoice). Note that you can see the donor identified in the Purchase Order in the Default donor field:

Default donor for each stock line
  • Each stock line on a Supplier Invoice will inherit the Default donor from the Supplier Invoice.
  • The Default donor can be edited.

Changing the donor for a particular supplier invoice line
  • There may be circumstances when delivered stock may be from a mix of donated and non-donated, or from different donors. You can change the donor for any stock line on a supplier invoice when editing the details of the stock line (double-click on the stock line).

If you change the Default donor, you will be presented with the following options:

  • “Do nothing”: The change will have no effect on existing invoice line(s).
  • “Update existing donor lines with this donor”: existing donor lines will be updated to match the newly selected donor.
  • “Assign this donor to the lines with no donor”: lines with no donor selected will be updated with the newly selected donor.
  • “Assign this donor to all lines”: all lines will be updated with the newly selected donor.
Donors and the customer invoice

Customer invoices, including stock transfers for donated goods are created in the usual way - refer Issuing Goods to a Customer (Customer Invoices).

  • They key thing to note is that when selecting from the stock lines to add to the Customer Invoice, the donated stock lines can be distinguished from the other stock lines by the donor name in the Donor column - see below:

mSupply will always suggest stock lines according to selection criteria (primarily, FEFO). If you want to overide this:

  • If a donated stock line is not the first expiring and you do want to issue it, you will need to manually select it.
  • If a donated stock line is the first expiring and you don't want to issue it, you will need to manually de-select it.

Reporting

Obviously, one of the points of entering all this donor information is to be able to report on it. When the donor tracking preference has been turned on, many of the stock based report filters in mSupply will have an additional donor filter added to them. Simply enter the donor filter settings you need, as appropriate, to filter the reports accordingly.

Previous: 7.05. Custom stock fields | | Next: 8. Issuing Goods

7.03. Editing pack sizes

New: mSupply version 3.03

Changing pack sizes for items already received

If you have received goods and the supplier invoice is taken off hold, these goods will go into stock and be available for issue.

You can still edit the pack size if.

  1. No stock has been issued, or:
  2. You have the user preference set that allows editing pack sizes even after issue. 10)

Allowing editing of pack sizes

Changing a received pack size after items have been issued

Take as an example chloramphenicol eye ointment; a delivery has been received, comprising 500 tubes, packed in packs of 100 - i.e. 5 boxes, each containing 100 tubes. When the entry is made into mSupply the operator in error enters a quantity of 5 and a pack size of 1, instead of a quantity of 5 and a pack size of 100.

Provided the user permission described above has been set, the error can be rectified, and the invoice altered to show the correct pack size of 100. From the Supplier menu, choose Show invoices to access the required invoice. Select the line Chloramphenicol 1% eye oint,and double click on it. If stock has already been issued, a window will appear to alert you, and allowing you immediate access to the customer invoices detailing the issues.

It should be noted that adjustments may be necessary on these invoices.

Click OK to display the Add/edit supplier invoice line where the correction can be made by changing the Pack size entry from 1 to 100.

How is this different to splitting a stock line?

Splitting a stock line is required when a store receives and manages an item whose pack size contains a number of units in the pack, but typically issues the item to the store's customers in smaller quantities. Taking the example above, the store receives and manages chloramphenicol eye ointment in a pack size of 100, but issues in single tubes.

  • Editing the pack size in a supplier invoice, changes the total stock on hand (and / or issued)
  • Splitting a stock line does not change the total stock on hand (and / or issued)

The Item details screen is displayed from the Item > Show items menu, by entering the first few characters of the item in the Find item window. From the list on the side bar, click Stock, and on the window which appears click on the appropriate line to select it; the window should now have this appearance:

Click the Split button, and fill in the appropriate details on the form - in this example the 3 packs of 100 are to be changed to 300 packs of 1.

Looking again at the Item details window, the stock is now displayed as 300 single units, and the store is now able to issue as little as a single tube, or any quantity up to the total available.



Previous: 7.02 Goods receipt | | Next: 7.04. Managing outstanding purchase order lines (pipeline stock)

7.02. Goods receipts

Entering goods received

If the receiving store is receiving goods from another virtual store in your mSupply system, in response to an Internal Requisition (Purchase Order) from that store, the Goods Receipt will be created automatically - refer Receiving the goods (requesting store). Open this automatically created Goods Receipt. Do not create a new Goods Receipt!

Choose Supplier > New goods received and this window appears:

There is some read-only information at the top of the goods received note that cannot be edited:

  • Store: The name of the store the goods received note belongs to.
  • Goods received ID: This goods received note's number. The number is automatically incremented and assigned when the goods received note is first created and is unique within a store. Note that goods received notes in different stores could have the same number.
  • Created by: The name of the user who created the goods received note.
  • Modified by: The name of the user who last modified the goods received note.
  • Entry date: The date the goods received note was created.
  • Purchase order: The number of the purchase order the goods on this goods received note were ordered on. It is a link and clicking on it will open the purchase order.
  • Supplier invoice: The number of the supplier invoice produced from this goods received note. The number is filled in after the goods received note is finalised. Again, it is a link and clicking on it will open the supplier invoice.
  • Status: The status of the goods received note:
    • nw = new, the goods received note is not complete yet and is still editable
    • fn = finalised, the goods received note is complete and is no longer editable

If you have goods receipt authorisation set up in Store Preferences there will be an extra Authorised column - see the Authorising items on goods received notes section below for more details.

Selecting the Purchase Order

In the Supplier field (which displays Search Purchase Order when it first opens), enter the first few characters of the name of the supplier from whom the order has been received. To display all Purchase Orders awaited, enter @ in the Supplier field. (This has been done in the example shown below):

  • Supplier column: The name of the supplier the purchase order was sent to.
  • PO reference column: The value entered in the Reference field on the purchase order.
  • Tender reference column: The reference to the tender this purchase order came from. Will only have a value if this purchase order came from a tender.
  • Our PO ID column: The number of the purchase order in mSupply.
  • Comment column: The value entered in the Comment field on the purchase order.

If there are a lot of purchase orders in the list you can shorten it by typing something in the Type here to search field. The list will then only show purchase orders for suppliers that have a name which contains what you typed.

From this screen select the entry which matches the purchase order for which you have received stock, either by double clicking on the entry, or by highlighting the entry and clicking on the Ok button.

The New Goods Receipt window reappears with the supplier field and some other details completed.

Filling in general details

At this point you should fill in the:

  • Supplier reference field with, for example, the delivery note number
  • Comment field with any extra information you need to record about the delivery
Adding items from the purchase order

Next, you should click on the Add from Purchase Order button to add the items which have arrived to the goods received note. Clicking the button brings up the Choose order lines… window:

This window displays the goods on the Purchase Order, and you may either select each item separately (click on a single item), the entire order (click on an item then press Ctrl+A on the keyboard, or Cmd+A on a Mac) or something in between (use Ctrl+click to select individual items and add/remove them to/from the selection and/or Shift+click to select a range of items) to enter the details of the items received!

If you're trying to find a particular item in a long list you can also type the start of the item's name or code into the search box at the top and the list will be filtered to show items which have a name or code starting with what you have typed.

mSupply does allow you to create a Goods Receipt for stock for which you have already received all of the ordered stock, that is, Remaining (outstanding) quantity = 0).

In any case, when you have selected the items to receive, click on the Use button.

Adding un-ordered items

Occasionally goods may be received which were not ordered; when this occurs, click on the Add an un-ordered item button and select the item before proceeding. There is a user permission that can be set to prevent users being able to use this button (see the 25.25. Managing users page for details)

Goods receipt line entry

The lines you have selected are added to the goods received note and you will see them in the table but with no batch, expiry date, location or quantities:

No information about the batches or number of packs that have been delivered has yet been entered. You can set the Quan column (number of packs) to the number remaining to be delivered by selecting the appropriate lines (Click with Shift and Control and Ctrl+a all work as usual) and clicking on the Apply suggested remaining quantity button.

To enter the batch and quantity information for each line, double-click on the first line in the table and the Edit goods received line window will open, populated with the first item:

Let's have a look around the window and see what information is being displayed:

  • Item: the name of the item we're entering the information about. At the end of the field is the item's code.
  • Remaining quantity to receive: the number of packs we're still waiting to receive from the supplier on the purchase order this goods receipt note is for. This is 0 on the screenshot because, by default, mSupply creates a line in the table which contains all the outstanding stock.
  • packs of: the pack size (number of items in the packs) we're waiting to receive. So, the total number of individual pieces of this item we're waiting to receive is Remaining quantity to receive x packs of.
  • table: contains all the lines of the item that we're receiving from the supplier. Click on any of the cells to edit them (they are all editable except the Total quan column because this is a calculated column and equal to Quantity x Pack Size). There will be a separate line in this table for each batch or location (and manufacturer if the preference to record manufacturer is turned on - entering a manufacturer is the same as entering a location i.e. enter the first few characters of the manufacturer's name and press the Tab key on the keyboard and select the manufacturer you want from the list displayed or click on the New button to create a new manufacturer). If there are any of the first 4 custom fields described on the 16.01. General preferences page turned on then columns for them will be displayed after the expiry date picker column and you can enter values for each one there.
  • Expiry date picker: this is in the column just to the right of the Expiry column. Click on it to select the expiry date from a date picker: Click on a month and year in either order and mSupply enters the last day of that month in the expiry date column. You can manually edit the date (or manually enter it without using the picker) if you don't want the last day of the month.
  • Volume per pack: the volume per pack for the line currently selected in the table. Will be set to the item's default volume per pack if it has one, otherwise 0.
  • Weight per pack: the weight per pack for the line currently selected in the table. Will be set to the item's default weight per pack if it has one, otherwise 0.
  • Total line weight: the total weight of this line in the table (= Weight per pack x Quantity column figure for the line)
  • Total capacity: the total volume the location for the selected line in the table has. 0 if the location is not set for the line or has no volume set.
  • Available space: the available space in the location before putting this line in it.
  • Space required: the volume this line requires (= Volume per pack x Quantity column figure for the line). So compare this with the Available space figure to see whether the line will fit in the location selected.
  • Comment: Anything you want recorded for this line. Anything typed in here will appear in the Comment column in the table.

If you have set a note for this item on the purchase order (see Notes section in Editing Purchase Order Lines) then an extra Note section will appear at the bottom of the window:

Until the Note has been actioned checkbox is checked, lines for this item will appear in red on the overall goods receipt window (see below).

To add lines for new batches or locations, click on the Add line or Duplicate line line button - they both add a line, Add line adds a blank one, Duplicate copies the line currently selected in the table. No surprises but, to delete a selected line, you click on the Delete line button!

You can edit a row in the table by clicking on the various cells. It is best to click on the left-hand Quantity cell and adjust that one first. Then you can use the tab key to advance to the next cell in the row.

Let's take the following example for amoxycillin 500mg caps.

quantity pack batch expiry
648 1000 b1234 30/06/18
324 1000 b1235 30/11/18

Let's say there are 12 packs in a box, and 27 boxes on a pallet, so you have 2 pallets of the first batch and one pallet of the second batch. You can only put one pallet in each location, so the first row will be split into two.

Enter the details into the first row as above.

1. If you are entering details for an item which has its “Expiry date required on receive” preference set (see here for details) and you do not enter an expiry date for any of the item's batches then, when you click on the OK or OK & Next buttons, you will be shown a warning message and you will not be able to close the window without entering an expiry date for each batch or deleting all the item's batches.

2. If you receive more than was ordered on the purchase order, when you click on the OK or OK & Next buttons an alert message will appear asking you to confirm the receipt.

Location management when receiving goods

If the items you are receiving have had a location and volume entered when the Purchase Order was created, these will be transferred to the goods receipt. If you want to edit these details you can do so by double-clicking a line and either changing the volume or the location.

You can then choose a different location by entering it in the location field, or enter the start of a location code and press tab to get a list of matching locations.

When you get to the location column, we type m then press tab. you are shown the location choosing window with locations that match “m”

Note we have then clicked the Show empty radio button, as we are putting away a whole pallet, and pallets only go in empty locations. The Show available radio button shows locations that have enough spare capacity to take the volume of the line we are receiving. We then double-click on the location to choose.

If the item you are receiving has a default location set for it, this will have already been filled in when the line was added to the purchase order. Default locations should be set if the same item is always put in the same place, otherwise leave it blank. In the current example we've assumed it has not been set for each item.

Now we have entered all details for the line, we can click on the row to highlight it, then click the Duplicate line button to create another row the same without entering all the details again - you then only need to click on the location column on the newly duplicated row, and you can edit the location to find another empty location for the second pallet.

Once done, you can duplicate the row again, and this time you have to change the batch (to b1235), expiry (to 30/11/18) and location.

Then your window should look like this:

Note that the bottom row of the table shows you the total number of packs and total quantity being received.

If all the details are correct click OK (or OK & Next if you selected more items to be added from the purchase order) or click Cancel if you want to abandon this entry. You will be taken back to the window showing the overall goods receipt, this time including the lines you've just entered:

Review overall goods receipt

All the items you've selected have been added to the goods receipt. The quantity is set to the total remaining to be received for that item.

Double click on each item in turn and the window allowing you to enter quantities, pack, batch numbers, expiry dates.

Red line in the Goods Receipt?

If you see lines show up in red on the Goods Receipt that means that you have set a note that must be actioned for that line on the Purchase Order (see Notes section of Editing Purchase Order lines for details).

Once you have actioned the note, the lines will return to their 'normal' black colour.

The right hand side of the window shows you the shelf location, total capacity and available space for a particular item in a particular shelf location. You are also shown the volume or space required for a particular item. The small “refresh” icon the right inserts the default location for the items. The volume of the shelf location is now reduced to reflect the space consumed by our newly added stock item.

After entering the details for each item, you can click on OK & next to proceed to editing the next item.

Finalising goods received

The next step in receiving your goods into mSupply is to create a supplier invoice (that is where you will enter pricing information if you need to). This is done automatically for you when you finalise the goods receipt.

When you have entered all the goods you have received onto the Goods Receipt note, you finalise it by checking the Finalise box in the bottom left hand corner of the window and clicking on the OK button. Only do this when you are sure the Goods receipt note is an accurate record of what you have received and contains all the information you want in it because finalised means finalised and you won't be able to change it afterwards (just like everywhere else in mSupply!).

Finalising a Goods Receipt will update the received (and outstanding) quantities in the Purchase Order for any goods receipt lines which came from a Purchase Order.

Your goods are not yet entered into stock in mSupply - that only happens when the supplier invoice is confirmed. The initial status of this automatically created supplier invoice is controlled by the “When finalising a Goods Receipt” store preference - see here for details.

If you have the store preferences set to force supplier invoice authorisation, you will not be able to confirm supplier invoices (and therefore bring items into stock) until they have been authorised. See here for details.

If the Items received on a purchase order must be within a minimum expiry date preference is turned on (see the 6.01. Ordering stock from suppliers page for details) then, when finalising a goods received note, a check is made to see whether any of the lines have an expiry date that is before the date set on the purchase order. If they do then you will be shown a message telling you which lines have too short an expiry date and you will not be able to finalise the goods received note until the expiry date is changed or the line is removed from the goods received note.

Authorising items on goods received notes

When you have goods received note authorisation turned on in Store Preferences you will see an extra “Authorised” column on your goods received note:

The column will contain a checkbox for each batch you add to the goods received note. If a batch is authorised then check its box in the Authorised column (only users with the Can authorise goods received permission can check these boxes). You can enter any notes on batches which fail authorisation in the Authorisation comment box at the bottom. When you finalise your goods received note only the batches which have been authorised will be put on the automatically created supplier invoice. In this way you have a complete record of what was received, what was satisfactory and what was sub-standard.

Viewing existing goods receipts

Choose Supplier > Show goods received…

A standard mSupply find window is shown:

Click the OK button to view the last 15 goods receipts, or enter a value to find in the lower field, and choose the field you are searching for in the left-hand drop-down list (if you enter something in the lower text box this filter only will be used and the top one - number of recent goods received notes - will be ignored). This window then opens to show the goods received notes that match your filter selections:

New button: Creates a new goods received note

Find button: Opens the search filter window again, allowing you to make a new search for goods received notes.

Accessing the related Purchase Order when the Edit goods received window is open is achieved by clicking on the blue “Purchase Order” on the right side.

Similarly, if you want to see the linked Supplier Invoice then click on the blue “Supplier Invoice”.

If you have turned on any of the custom stock fields in store preferences they will be displayed as columns (between the Batch and Expiry columns) in the list of items and the information you entered for these fields when the stock was received will be shown in the appropriate cells. If you double-click on one of the supplier invoice lines to edit it (assuming they are editable!), you will see the custom fields and be able to enter information into them.

Outstanding purchase order lines

Outstanding PO lines are those which you are still waiting to be delivered from the supplier (also known as your pipeline stock). These will only be updated when a Goods Receipt is finalised. You can view them by either:

  • Clicking on Show outstanding PO lines on the Navigator's Supplier tab or
  • From the Supplier > Show outstanding PO lines menu item
Other tabs on a goods received note

All the functionality described above has been on the General tab. There are others!

Documents tab

The Documents tab on a requisition enables you to save documents and other files relating to the goods received note. The tab looks like this:

The table shows you all the files currently uploaded to this goods received note.

  • Upload document button: Click this to upload a document to the goods received note. This will open a window enabling you to search for and select the file on your computer. After you've selected it, click on the Open button to upload it. If you upload a file with the same name as one already uploaded, mSupply will upload it as a new version of the already uploaded file.
  • Delete document button: Select a file in the table by clicking on it and click this button to remove it from the goods received note.
  • Download document button: When you click on this button you are presented with two options:
    • Download: this will download the file to a location you select on your computer.
    • Download and open: this will download the file to a location you select on your computer and then attempt to open it using the default application on your computer for that file type. If there is no application associated with the file type on your computer then mSupply will tell you that the file could not be opened.
Log tab

The log tab displays all the log entries that have been made regarding this goods received note. All log entries are stored in the mSupply log (see the 25.19. The system log page for details) and this tab will display all the log entries in there which were made for this goods received note.

Viewing and editing supplier invoices created via goods receipts

A supplier invoice will be created automatically once the Goods Received note is finalised.

Supplier invoices created via goods receipts differ slightly from standard supplier invoices.

Price tab

Here, you can add in any extra currency related charges

  1. in the supplier's currency in the Extra Foreign Currency charge field , and
  2. in your local currency in the Local charges field and mSupply will automatically calculate the updated invoice price.

Here's an example of how mSupply will do this with a currency “YXB” whose rate is YXB 7 = USD 1

Item Foreign Price Quantity Foreign Currency
Price Extension 		Local Price Local price Extension
Amoxycillin 250mg tabs 50 10 500 350 3,500
Paracetamol 500mg tabs 300 5 1,500 2,100 10,500

Now we add USD300 of freight charges and YXB1400 of import duties:

  • The total USD value of the order is USD2000, so 15% must be added to each line to account for this
  • The YXB1400 is equivalent to USD200 in local charges, so 10% must be added.
  • Therefore a total of 25% is added.
Item Foreign Price Quantity Foreign Currency
Price Extension 		Local Price Local price Extension
Amoxycillin 250mg tabs 50 10 500 437.5 4,375
Paracetamol 500mg tabs 300 5 1500 2,625 13,125
Currency and currency rate

Select the supplier currency from this drop-down box, and enter the current exchange rate in the Currency rate field . Note that currencies must first be entered using the menu item Special>Currencies. See Currencies...

Extra foreign currency charges

In the supplier's currency, enter any extra charges from the supplier.

Local charges

Enter any local charges, in your local currency.

Application of charges

mSupply distributes any extra charges proportionally according to the invoice value of each item on the invoice; this is done automatically

MoneyWorks tab

If you are using the MoneyWorks accounting software (which is highly recommended), clicking on this tab allows you to export the invoice details to MoneyWorks. Elsewhere in this guide instructions on setting up mSupply to work with Moneyworks are to be found. See Moneyworks.



Previous: 7.01. Receiving goods (supplier invoices) | | Next: 7.03. Editing pack sizes

7.04. Managing outstanding purchase order lines (pipeline stock)

Stock that you have ordered and waiting to be delivered is called your pipeline stock. Sometimes it's helpful and important to monitor this stock so mSupply has functions to help you do that.

Pipeline stock is represented by all the outstanding purchase order lines i.e. purchase order lines on confirmed purchase orders which haven't been fully received into mSupply yet.

To see all your pipeline stock simply choose Supplier > Show outstanding PO lines… from the menus or click on the Outstanding icon in the Purchase orders section of the Suppliers tab on the navigator. This window will open:

All lines in black are those where the expected delivery date (EDD) is after the current date i.e. where the Days to EDD column (which contains the difference between the EDD for a line and the current date) has a number greater than 0. These are items which are not yet overdue but, if the Days to EDD column contains a small number, you might want to call the supplier to check on the delivery.

All lines in red are those where the expected delivery date is on or before the current date i.e. where the Days to EDD column contains 0. These items are overdue and it probably means that the supplier could do with a call to find out what's happening with your delivery.

The Adjusted quantity column shows the actual number of items you ordered (number of packs x the packsize).

The Qty received column shows the number of items (number of packs x the packsize) yo have already received into mSupply.

The Qty Outstanding column shows the remaining number of items on the order waiting to be received (Adjusted quantity - Qty received).

Double clicking on any line will open the Purchase Order with that line highlighted.

You can print the list of purchase order lines currently displayed in this window at any time by clicking on the Print button - as usual, you will be given the option of printing or exporting to Excel.

Update EDD button

If you speak with the supplier about a delivery or receive information from elsewhere about when goods are going to be delivered you can update the expected delivery date for those lines.

To do this, simply select the lines in the table that are affected then click on the Update EDD button. In the window that opens, enter the new EDD for the lines and click on the Update button. The EDD is immediately updated for the chosen lines and, if the lines were red, they will turn black.

You can select multiple lines to update using the usual Shift+click to select/deselect a range of lines and Ctrl+click (Cmd+click on Mac) to add/remove a line to/from what is currently selected.

Filtering the list

Sometimes the list of outstanding purchase order lines can be very long (just after running your annual tender for example, or when you have placed several large orders) and it can be hard to find a specific item or items expected from a particular supplier. To help in this situation, mSupply allows you to filter the displayed list.

To do this, select the type of filter you would like to apply by clicking on the filter icon () just to the left of the textbox and select one of:

  • Search by supplier or code - will show only those outstanding purchase order lines on purchase orders whose supplier name or code begins with what you type in the textbox
  • Item name or code - will show only those outstanding purchase order lines whose item name or code begins with what you type in the textbox
  • Days to expected delivery is less than… - will show only those outstanding purchase order lines with an expected delivery date less than the number of days you enter in the text box from the current date.

Then enter the value you wish to filter by in the textbox and click on the Find button. The list will then be changed to show only those purchase order lines matching the filter you have selected.

Finalising purchase orders

Any outstanding goods on finalised purchase orders will NOT be included in this window. So, if there are goods that you have ordered but will never receive from a supplier (maybe a substitute item has been shipped or you cancelled part of an order because a supplier said they couldn't deliver it), when everything else on the purchase order has been received you should finalise it. The goods on the purchase order that you have not received will then no longer be shown as outstanding in this window.

It is good practice to finalise purchase orders for which you have received everything because it also removes the purchase order from the list you can create a goods received note from (see Receiving goods (goods receipt function)), making it easier to find a purchase order you're wanting to create a goods received note for, and means that no changes can be made to the purchase order in the future.

But beware: don't finalise a purchase order before you have received everything the supplier is going to send because you won't be able to make any changes to it or receive goods against it using the Receiving goods (goods receipt function).

Why can't we just un-finalise this PO ourselves?

Purchase orders are a legal contract between you and your supplier, and are often the subject of particular attention by auditors. As such they must be protected from misuse.

When a PO is finalised, somebody with authority is saying “we are not receiving anything more on this PO”. This will be because either:

  • all ordered stock has been delivered
  • the supplier has failed to supply in accordance with the PO contract and so is in breach of the contract. The decision to finalise the PO is then a decision to terminate the supply contract. It is most irregular for an organisation to turn around and say, “wait, we'll continue to deal with the supplier on this order even though the contract is in breach”. Auditors will likely want to see good documented evidence to support why this was done. A new purchase order, needing new approval by management is normally the more appropriate way to proceed.

For this reason, mSupply does not have the facility for users to unfinalise a PO. However, mistakes can happen…

If you do accidentally finalise a purchase order and you need to receive more stock against it, then POs can be unfinalised. The following will be needed:

  • Sustainable Solutions will need remote access to your database,
  • An officer with authority must provide approval for the unfinalisation.

Sustainable Solutions keeps records of all communications and will be able to provide a copy of this approval to your auditor on request.



Previous: 7.03. Editing pack sizes | | Next: 7.05. Custom stock fields

7.01. Supplier invoices

Introduction

All received goods should be recorded in mSupply either by:

In some countries a supplier invoice is called a “bill”, a “creditor invoice” or a “purchase invoice”

Goods are only entered into stock once a supplier invoice is confirmed

Confirming the supplier invoice also calculates the selling price based on the margin you have chosen for that supplier or for that item, depending on how you have set your mSupply preferences.

You will notice there is a Prices tab in the supplier invoice window - this is for use with invoices received in foreign currencies, which will usually be done via the goods receipt system.

Each line received on a supplier invoice will be treated as a separate line in your stock. You can manually consolidate these later, or set a preference to automatically consolidate items with the same batch, expiry date, pack size, location, donor, cost and sell price.

Creating a new supplier invoice

STOP! Don't proceed with creation of a new supplier invoice if the stock came as a result of:

In these cases, you should NOT create a new Supplier invoice, and can skip most of the following section.

Search for these automatically created invoice using Suppliers>Show invoices…

Depending on the store preferences, the supplier invoice may be finalised. If not, you will be able to add, edit or delete lines on the supplier invoice if what you actually received is different to what the supplier invoice states…

To create a new supplier invoice, navigate to the Suppliers tab and click the New Supplier Invoice button.

The supplier invoice entry window will open:

If you have turned on any of the custom stock fields in store preferences they will be displayed as columns (between the Batch and Expiry columns) in the list of invoice lines and the information you entered for these fields will be shown in the appropriate cells.

Information to enter in the main window

Name: The first thing to do is enter the Supplier's name in the Name field. Type the first few characters of the supplier's name or code, and then press the Tab key. If only one supplier name matches the entry, the supplier's name will be filled in. Otherwise, a list will be displayed:

Double-click the appropriate entry, or click Cancel to try again. You can also use the up and down arrow keys or the “u” and “d” keys on the keyboard to move the highlighted item up or down, then click the Use button or use the Enter key to choose the highlighted item.

At this point the supplier's name will normally just appear in the Name field (and their code will appear at the end of the Their ref field) and you can continue as below. However, if the Can manually link requisition to supplier invoice preference is turned on for this store (see Store preferences), a list of requisitions the store previously made to that supplier will appear. Select a requisition to associate with this supplier invoice, then click OK:

The supplier invoice window will appear with the name of the supplier you have chosen in the Name field:

The arrow next to the Name field takes you directly to the Edit Customer/Supplier window, giving access to all the information relating to the supplier entered.

Their ref: Enter the serial number or delivery note number on the bill the supplier gave you.

Comment: Enter anything that needs to be remembered about this invoice. If you need more room, click on the arrow next to the Comment field to give a large area for entering the comment.

Category: Categories created for supplier invoices in File > Preferences > Invoices 1 are listed here.

Colour: Clicking the colour box presents you with a selection of eight colours. When the list of supplier invoices is displayed, the text of this particular supplier invoice will appear in your chosen colour. The colour does not appear on the supplier invoice itself.

Confirm date: This is normally read only but will be editable if the Allow entry of dates on invoices preference is turned on (see the Invoice preferences page for details).

Read-only information at the top of the invoice

There is some information at the top of the invoice that is read-only and cannot be edited:

Invoice number: This is the invoice number. The number is automatically incremented and assigned when the invoice is first saved (which actually occurs when the first line is added to it) and is unique within a store. Note that supplier invoices in different stores could have the same invoice number.

Entry date: The date the invoice was created.

Confirm date: The date the invoice was confirmed. Will be “00/00/00” if the invoice has not been confirmed.

Status: The current status of the supplier invoice:

  • nw = new (just created, can still be edited, stock not yet added to mSupply)
  • cn = confirmed (stock has been added to mSupply but invoice is still editable)
  • fn = finalised (stock has been added to mSupply and the invoice is no longer editable)

Goods received ID: If the supplier invoice was created automatically when a goods received note was finalised then the goods received note's ID will appear here in blue, indicating that it is a link and, if clicked, will open the goods received note. A 0 here indicates there is no linked goods received note.

Purchase order ID: Again, if the supplier invoice was created automatically when a goods received note was finalised then the ID of the purchase order which the goods were ordered on will appear here in blue, indicating that it is a link and, if clicked, will open the purchase order. A 0 here indicates there is no linked purchase order.

Requisition ID: If the supplier invoice was linked to a requisition, the requisition number appears here. You can click on it to be taken directly to the requisition. A 0 here indicates there is no linked requisition.

Entered by: The user name of the user who created the invoice.

Store: The name of the store the invoice belongs to.

Buttons in the supplier invoice window

New line: Add an item to the invoice. See Adding lines to an invoice below for more details. To edit a line, double-click on it.

Add items from requisition: Only visible if the supplier invoice is linked to a requisition. Displays a list of items from the linked requisition, which you can add to the supplier invoice. You can add one or more items by highlighting them and clicking OK. To edit a line, double-click on it.

Delete line: Delete item(s) from an invoice. Highlight the line(s), then click this button. Multiple lines can be deleted simultaneously.

Duplicate lines: Select one or more lines on the invoice and click this button to add duplicates of those lines. Great time saver when receiving large quantities of the same item with similar batches into different shelf locations, for example.

Hold checkbox: If checked, the invoice status cannot be changed.

Items on a supplier invoice with new (nw) status have not been entered into the system yet. Putting a new invoice on hold allows you to enter the supplier invoice, but not allow the stock to be available for issuing until all the details have been checked.

Finalise check box: If checked, clicking the OK button will finalise the supplier invoice. Once finalised, the invoice can no longer be edited so be sure first that all the details are correct. Only users with the Can finalise individual invoices permission can check this box. Other users will be warned if they try to turn it on, and the check box will automatically uncheck.

When the OK button is clicked, you will be asked to Confirm invoice and enter into stock now?

  • If you click Later the invoice will still have a new (nw) status
  • If you click Confirm and the Finalise box was not checked, the invoice will be confirmed (cn)
  • If you click Confirm and the Finalise box was checked, the invoice will be confirmed (cn) and finalised (fn)

A finalised invoice cannot be edited.

Should a finalised invoice need to be changed, the entire invoice may be cancelled, and the correct data may be entered as a replacement.

In order to maintain the accuracy of any subsequent audit trail, mSupply creates a transaction which reverses all the stock movements on the invoice being cancelled, having due regard to all appropriate details, such as batch numbers, etc. See Cancelling finalised invoices

If Confirm supplier invoices without asking is checked in the “Invoices 1” tab of the Preferences window, then all invoices will be finalised automatically.

If you have the store preferences set to force supplier invoice authorisation, you will not be able to confirm supplier invoices until they have been authorised. See here for details.

Copy: Copies the invoice details to the clipboard, allowing you to paste them into a spreadsheet or email message.

Delete: Deletes the entire invoice. When deleted, there will be no trace of your entry and the invoice number assigned will be reused.

Unless the invoice has a new (nw) status, if you have added lines to an invoice, you must manually delete each line using the Delete line button before deleting the invoice. This is intentional, to save the “Oops, I just deleted my invoice with 100 lines on it” feeling.

Invoice status Description
nw The invoice has just been created - clicking Delete will automatically delete each line and the entire invoice
sg The Delete button will only delete the invoice if you have first deleted all lines using the Delete line button
cn Same as for suggested (sg) status
fn No changes or deletions can be made and the Delete button will be disabled

Print checkbox: If checked, the supplier invoice or packing slip will be printed when the OK button is clicked. If the supplier invoice has a suggested (sg) status, a packing slip will be printed; otherwise an invoice will be printed.

OK: Saves the changes you have made and exits the window.

OK and Next: Saves the changes you have made and opens a new supplier invoice.

Tabs in the supplier invoice window
General tab

This shows a detailed view of each line on the invoice. This is the tab you see when you first open or create a supplier invoice.

Summary by item tab

Displays a summary of each item's requested quantity, sent quantity and received quantity. Different batch numbers of the same item are consolidated into a single line.

Summary by batch tab

This tab shows each batch but grouped by item and showing summary price information for each batch.

Price tab

There can be a lot of information on this tab! It is all detailed in the Price tab section below.

Unsupplied items tab

This tab is only shown if this supplier invoice is the result of a stock transfer from another mSupply store and the supplying store has the Use EDD placeholder lines in supplier invoices from this store store preference turned on (see the 26.08. Virtual stores page for details).

The table on this tab shows all placeholder lines that were present on the customer invoice in the supplying store (they represent the quantities of items that could not be supplied). If the item is also present on a purchase order in the supplying store then the Notes column contains the Expected Delivery Date of the item and the purchase order this date is taken from. Note: this is the expected date the item will be delivered to the supplying store, not your store.

Documents tab

The Documents tab on a supplier invoice enables you to save documents and other files relating to the invoice. The tab looks like this:

The table shows you all the files currently uploaded to this invoice.

  • Upload document button: Click this to upload a document to the invoice. This will open a window enabling you to search for and select the file on your computer. After you've selected it, click on the Open button to upload it. If you upload a file with the same name as one already uploaded, mSupply will upload it as a new version of the already uploaded file.
  • Delete document button: Select a file in the table by clicking on it and click this button to remove it from the invoice.
  • Download document button: When you click on this button you are presented with two options:
    • Download: this will download the file to a location you select on your computer.
    • Download and open: this will download the file to a location you select on your computer and then attempt to open it using the default application on your computer for that file type. If there is no application associated with the file type on your computer then mSupply will tell you that the file could not be opened.
Log tab

The log tab displays all the log entries that have been made regarding this invoice. All log entries are stored in the mSupply log and this tab will display all the log entries in there which were made for this invoice.

Custom data tab

This tab shows the custom fields that have been set up for supplier invoices.

All custom data will be saved with the invoice (i.e. when you click the OK or OK & Next button).

Adding new lines to a supplier invoice

Click the New line button to add a line to the invoice. This window appears: The cursor will be in the field ready for you to enter the item name.

Item: Enter as much of the item name (or code) as you know, then press the Tab key. As usual, if only one entry matches, it will be filled in. More than one matching entry will present you with a list from you should double-clicking on the required item. The text you type will be matched against both the item name and the code. A match for either will display the item.

To query for an item name or code that contains, rather than starts with, a string of text, use the asperand (@) wild character. So, for example, to search for “250mg” within an item, enter @250mg in the search field.

Hint: you can use the “up” and “down” arrow keys to change the highlighted item (You can also press u to move up and d to move down!) . Pressing the enter key will choose the highlighted item.

If you did wish to apply a different margin to the whole invoice, click the cancel button, and edit the margin for that supplier by choosing Supplier >Edit supplier and change the margin. If you wish to apply a different margin to just some lines, you can do this as you enter the lines, as long as Editing margins is enabled in the Preferences.

If the the item you are entering is not listed, you can click New item to add it.

Note: it is a good idea to agree upon a standard form for entering items. For example, will you enter an “infant feeding tube” as:

  • “infant feeding tube”
  • “feeding tube, infant”
  • “tube, infant feeding”

Duplicated items can later be merged, but it is better to get it right first time!

If you need to see the full details of the item itself after selecting it, click on the down arrow icon () to the right of the item name field and you will be taken to the item's details window.

Now there are a series of fields to enter to fill in the basic information for the line

Received quantity: How many packs did you receive?

Pack size: How many units are in each pack? Once the item has been selected the item's unit will be displayed after this field. If you also want to enter the number of packs in a carton (the “inner” pack size) and the number of cartons on a pallet (the “outer” pack size) then you can turn on a preference, as described on the 16.03. Invoice preferences page.

Total quantity: mSupply will automatically calculate the total quantity of individual units (received quantity x pack size).

Say you receive 50 boxes of amoxycillin caps, each box containing 10 strips of 10 caps. You would normally enter 50 in the received quantity field and 100 in the pack size field. However, if you normally issue the capsules in strips of 10 to customers (e.g. you allow them to order 20 or 30 capsules), then it will be more convenient to enter a quantity of 500 and a pack size 10.

Pack to one: Clicking this button will automatically change the pack size to 1 and update the Received quantity to match. If the Convert pack to one when receiving option is turned on for this item (see the 4.01.01. Items - General tab page for details) then this button will not be present but will be replaced with a warning that the pack size will automatically be changed to 1 (and the Received quantity updated accordingly) when the OK button is clicked or a cost price is entered. If you are using barcoding then the barcode for this batch will automatically be updated to a barcode matching the pack size (1) and manufacturer (if selected). If there is no matching barcode then the barcode selection will be changed to Remove barcode and, when the OK button is clicked, the barcode will be removed from the batch (you can of course use the Add one option to add an appropriate barcode before clicking on the OK button).

Invoice quantity: How many packs did the supplier claim to have sent? (Sometimes this is different to the quantity received!)

Invoice pack size: What is the pack size stated on the supplier invoice? It should match the received pack size, but if Pack-to-one has been applied to the received quantity (see above), this value will show the original pack size on the supplier invoice.

Invoice total quantity: mSupply will automatically calculate the total quantity of individual units stated on the supplier invoice (Invoice quantity x Invoice pack size).

Batch: The batch number or other identifying information. The batch appears on the invoice, so you can use this field to differentiate between brands if you need to (eg you operate using generic names, but occasionally want to give a specific brand- you can put an abbreviation for the brand name here as well as the batch).

Expiry: You can use “/” or “.” to separate the day/month/year.

Use whichever date format you have set in your computer (dd/mm/yy or mm/dd/yy or yy/mm/dd). You can enter the year as 2 digits, which will be understood as a date between 1961 and 2060. This should cover the expiry date on most things you receive in the next 52 years!

Location: The location of the item should be entered in this field. Type the first few characters of the location's code and press the Tab key on the keyboard to select the correct location. If there is only one location that matches what you typed mSupply will select it for you, otherwise this window will open to allow you to select the right location:

Double-click on the location in the table to select it. You can refine the list by selecting the Show available or Show empty radio buttons:

  • Show available: If this is selected the list will only show those locations that have enough volume left in them to accepot the volume in this line. For this to be useful, the locations must have a volume entered and the stock you are receiving must have a volume per pack value.
  • Show empty: If this is selected the list will only show those locations that have nothing in them at all (this does not use volume, it uses the presence of stock in that location).

Volume per pack: How much space the pack occupies in metres cubed (m3).

Weight per pack: The weight of the pack in kilograms (kg).

Invoice line unit cost: Enter your cost price for one pack of the pack size you entered above. If your supplier's currency is different to that of mSupply the cost price will appears in the supplier's currency.

If you have set a default selling price for this item, if you set the Invoice line unit cost to zero after setting it to some value, you will be asked to confirm whether you want to zero the cost price. If you confirm the change, the Sell price and Price extension will be set to zero.

Adjusted local cost: Displays the cost of a single unit of the item in local currency.

% Margin and sell price: If you have allowed editing of these fields in Preferences, you can adjust the margin (and the sell price will adjust automatically), or you can adjust the sell price (and the margin will adjust automatically).

If you do not set it to something else, the sell price will be set to the item's default sell price.

Manufacturer: This field displays the name of the manufacturer of the item. It will only be shown if you have turned the Able to specify manufacturer when receiving, ordering or quoting for items preference on in the store preferences.

Entering a manufacturer follows the same pattern as entering an item or supplier - type the first few letters of the manufacturer's name or code, and press the Tab key. Choose the required manufacturer from the list if more than one is displayed.

You can add a new manufacturer by clicking on the New button.

Donor: The donor of the item can be entered to this field. A valid donor should be entered, type the wildcard character '@' and press the TAB button to view your list of donors.

Price extension: This information field provides the cost price in local currency for the total quantity of the item you have entered.

Custom fields 1-8: The appearance of these fields is controlled by the Custom stock field preferences. Any information you enter in these fields will be displayed wherever stock information is displayed (e.g. when issuing stock on a customer invoice or when viewing the stock of an item on the stock tab of the item details window). The fields can also be reported on so they are an important and powerful way of tracking different categories of stock. For full details please see Custom stock fields.

Click OK if you are finished, or OK & next to add another line. (The invoice lines added will be displayed in Items Display Field.)Click Cancel to exit to the main screen without saving any of the details.

mSupply provides the feature of receiving service items into stock. Service items are items that are not normally held in stock and are called non-stock items in mSupply. See here for more information on those. You might be tempted to use service items to manage assets - if you are you might find the mSupply asset management functionality better. See the 21.02. Asset management page for details.

If the Convert pack to 1 when receiving preference is turned on for the item (see the 4.01.01. Items - General tab page for details), the Pack size field will be changed to 1 and the Cost price, Volume per pack and Weight per pack field values will all be re-calculated when you enter the Cost price field value or click on the OK button. A warning in red text will be displayed on the window if the preference is turned on so that you don't get any nasty surprises when the values suddenly change!

PLEASE NOTE: There is a preference to prevent the adding of expired stock to supplier invoices. See the 26.07. Virtual stores page for details.

Editing lines on a supplier invoice

Supplier invoice lines can be edited at any time until the invoice is finalised.

If the SI has been finalised, it needs to be un-finalised in order to edit lines. Contact support on support@msupply.org.nz

To edit a line, simply double-click on the line you wish to edit.

Editing lines if stock has been issued

If you have already issued stock of this line to a customer, you will be warned with a window like this:

Clicking View issued invoices will show you a list of customer invoices containing stock entered on this particular line:

Clicking OK will take you to the item issue window:

The item and pack size fields will not be editable and you may not reduce the received quantity to a figure lower than the quantity already issued. However, if you have the Update pack size, cost and sell price preference turned on (see the 24.15 Managing users page for details) you will also be able to edit the pack size field. There is a caveat; if the stock has been involved in a repack or a split, the pack size field will always remain uneditable.

In the screenshot above you will notice the “units issued: 10” text in blue to the right of the Quantity field. This will only be present if stock has already be issued to customers. You can click on that text to display a list of issued invoices as described above with the View issued invoices button.

Note that the OK & Next button is very useful for editing a whole invoice. Simply double-click the first line of the invoice, then use the OK & Next button to go from line to line.

Vaccines

There is extra functionality for vaccines to enable you to record the VVM status. To turn it on, you must turn on the Able to specify VVM status when receiving items store preference; see the 26.07. Virtual stores page for details.

When this preference is turned on, the field appears on the supplier invoice line entry/edit window here:

The VVM status field is populated with the statuses set up in the system. See the 20.01. Vaccine Vial Monitoring (VVM) page for details on how to do that.

If you are editing an existing line on the supplier invoice then the VVM status field will display the status selected for the invoice line or Please select… if it doesn't have one set already.

Working with the list of invoice lines

Resizing columns: These columns are resizable. If any of the column data is cut-off or remains hidden, the column width can be increased or decreased by positioning the mouse at the borders of the column. The cursor changes to a cross with arrowheads on the horizontal bar. Click and drag the cursor to the left or right.

Sorting columns: Columns may be sorted either in ascending or descending order by clicking on the header.

The order of the columns can be re-arranged by clicking on the header and dragging it to the new position.

Deleting a line on a supplier invoice

To delete a line, do one of the following:

  • Click on the line you wish to delete, then click on the Delete line button
  • Double-click the line to edit it (see above) and set its quantity to zero.

Click the OK button. You will be asked for confirmation. Click OK to proceed.

You cannot delete a line from a supplier invoice that has been finalised.

Selling price calculations in mSupply

mSupply uses a number of items of information to calculate the selling price of an item. This enables you to have the price calculated just the way you like it.

Here's the logic mSupply uses:

  • Does the item have a selling price specified? If it does, this price will be used regardless of any other information. Note that the price entered for the item is for one unit. The price will be multiplied by the pack size to get the selling price for the line.
  • If either the supplier margin or the item margin is specified as zero, then the other (non-zero) value will be used?
  • If a margin is specified for both the supplier and the item, the Preference Item margin overrides supplier margin will be examined to see if it is on or off. If it is set, the item margin will be used, if not the supplier margin will be used.

For example: <HTML>

</HTML>

Cost price Pack size Supplier margin Item margin Preference set for Item margin overriding Supplier margin Item price Price used
100 100 6 10 yes 1.15 115
100 100 6 10 no 1.15 115
100 100 6 10 yes 0 110
100 100 6 10 no 0 106
100 100 0 10 no 0 110
100 100 6 0 yes 0 106

<HTML>

</HTML>

Note that if you have turned on “allow editing margins and sell prices on supplier invoices” in the Preferences you will be able to over-ride the prices mSupply calculates.

Price tab

This tab provides functions for applying discounts and apportioning different charges to items.

Applying a discount to the whole invoice

If a supplier gives a discount at the bottom of the invoice rather than adjusting the price of each invoice line, you can use the discount button.

This window will be shown:

If you enter “5” the cost price of each line will be reduced by 5%, and the invoice total will be recalculated. It should then match the amount the supplier is actually charging you.

If you want the sell price calculated based on the new cost price, check the “Recalculate sell price” checkbox. The selling price rules as described above will still apply.

Applying local charges

Local charges are any charges you want to add to the cost of individual items on this invoice in your data file's local currency (i.e. the default currency used in your data file - this might not be the same as the currency you use when you visit a local shop!). These could be administration charges, local freight charges, handling charges etc.

You can either enter the amount of local charge to apply to each invoice line or the total amount of charges to apply to the invoice.

Entering local charge amounts on each invoice line

You do this by directly entering the amounts to apply to each line in the cells of the Local charge column in the table. As you do this, mSupply will automatically increase the sell price per pack by the amount you have entered divided by the number of packs for the line and will add the amount you entered to the current value in the Local charges field above the table.

Entering the total amount to apply to the whole invoice

To do this, you simply enter the total amount in the Local charges field above the table. When you do that, mSupply will automatically apply a portion of the local charges to each invoice line's sell price, according to the ratio of that line's Price extension to the sum of all the Price extensions of all lines on the invoice. You can see how much mSupply added to each line in the Local charge column. If you wish, you can edit the local charges applied to each line after this by simply clicking on the appropriate Local charge cell in the table and typing in the cost to apply. As you do that, mSupply will keep track of the total local charges applied to all lines in the Local charges field.

Applying foreign currency charges

These charges are applied in the currency selected in the currency selected in the Currency drop down list, following the rate displayed in the Currency rate field (which you can manually adjust if the default shown by mSupply is not what you require). The charges could be, for example, international freight charges or administration charges.

Simply type the amount of foreign currency charges to apply to the whole invoice in the Extra foreign currency charges field and mSupply will apply a portion of the whole amount to each line, according to the ratio of the line's Price extension to the sum of the Price extensions of all lines. mSupply will automatically update the sell price value for each item.

Applying other charges

These charges will NOT be added to the sell or cost prices of the items on the invoice. You enter them in the Other charges section below the table of items:

  • Item(s) field: Enter what the charges are for in this field.
  • Amount field: Enter the total amount of the other charges in here. When you do this, you will see the amount added directly to the Subtotal and Total amounts and none of it will be added to the sell or cost prices of the individual items in the table.
Applying tax to the invoice

Tax, like other charges, will not be added to the sell or cost prices of the individual items. To add tax, click on the % tax rate below the Subtotal field on the right hand side below the table of items and enter the rate you wish to use. mSupply will calculate the amount of tax (the % you entered of the Subtotal value) and automatically add it to the Subtotal value to give you the new Total.

If you have set a default tax rate in the preferences (see General preferences) you will see it applied as soon as you open the invoice. Also, you will only be able to edit the tax rate if the Allow editing tax rate and amount on invoices preference is turned on (see Invoices preferences).

Viewing supplier invoices

To view or edit any supplier invoice, choose Supplier>Show invoices. The details of how this works is virtually identical to that of viewing customer invoices.

Rapid access to Goods Received note from Supplier invoice, and vice versa

If the Supplier Invoice came from a Goods Receipt, (which in turn came from a Purchase Order), Supplier invoices show the Goods Received transaction number in the upper right area of the window. By clicking on that, the Goods received transaction will be displayed. Similarly, the Edit goods received list has a link Click here to open Supplier inv ……. which will display the required invoice.

Processing supplier invoices

In order to bring the stock on a supplier invoice in to your store, you will need to confirm it.

If the supplier invoice was created by mSupply, then depending on the store preferences, the supplier invoice may or may not be on Hold or Finalised:

  • If the supplier invoice is On hold, then the supplier invoice can not be processed (moved from one status to another). You will need to take the supplier invoice off Hold in order to process it.
  • To toggle the supplier invoice between on and off Hold, click on the Hold checkbox.
  • You can print the supplier invoice even if it is on Hold.
  • If the supplier invoice was finalised when you first opened it, then the stock has already been (logically) brought in to your store, and you don't need to do any processing! (In fact, you can't do any processing of it, even if you wanted to.)
  • If the supplier invoice status is nw, then the stock as described on the supplier invoice has not been brought in to your store yet.
  • To close the supplier invoice, click on the OK button. If the supplier invoice is not on Hold, then you should be prompted with the pop-up message below.

  • If you click Later, the supplier invoice will close, the supplier invoice status will stay at nw, and the stock will not be brought in to your store.
  • :Once you are happy with the details of the stock as described on the supplier invoice (taking special notice of the Cost Prices), and you are ready to bring the stock in to your store, click on the OK button, and then click Confirm. The supplier invoice will close, the stock will be brought in to your store, and the supplier invoice status will change to cn.
  • Depending on your user permissions, you may be able to edit details of the stock even after it has been brought in to your store - provided that the status remains at cn
  • If you click on the Finalise tick-box, then the status will change to fn and you will no longer be able to edit any details on the supplier invoice.

Printing supplier invoices

There are 2 ways to print a supplier invoice but both require it to be open. The first way is to check the print checkbox in the bottom right hand corner of the supplier invoice window:

When the checkbox is checked and you click on the OK button, the printing options window is displayed. The invoice will be closed after printing.

The second way is to hold down the Shift key on the keyboard and click on the printer icon in the bottom right hand corner instead of checking it. This will also open the printing options window but the invoice will stay open after printing.

This is the printing options window:

  • Form to use drop down list: Select the form you want to use to print the invoice. There may be several in the list. There is also a None option if you don't want to print the invoice but just want to print pallet labels.
  • Remember this choice checkbox: The form you choose in the Form to use drop down list will be selected (and everyone else!) next time the supplier invoice printing options window is opened if this checkbox is checked.
  • Print pallet labels checkbox: Check this if you want 100x150mm pallet labels in a specific format to be printed out from a label printer. A label will be printed for each line on the supplier invoice. Note: the label printer has to be installed and configured in mSupply before this option will work - see Label printer installation and Printing preferences (setup) for details.
  • Destination radio buttons:
    • Printer: the invoice will be printed out straight away.
    • Preview: a preview of what the invoice will look like when it is printed will be displayed in your installed PDF file reader. You might be able to print the invoice from the PDF reader, depending on its features.
    • PDF file on disk: the invoice will be saved to disk in PDF format.
    • Email PDF: the invoice will be created as a PDF file and attached to an email for you to send. You can double-click the email attachment to see a preview of the invoice. The email preferences in File > Preferences should be setup correctly before using this feature.
    • Export to Excel: the invoice will be exported as a spreadsheet file and opened for you (provided you have a spreadsheet application installed).

When you click on the OK button the invoice will be printed in the form you have chosen.

Previous: 7. Receiving Goods | | Next: 7.02. Goods receipt

8.06. Box management

Added: Version 3.1

Boxing is telling mSupply which boxes you packed issued stock into. This is helpful for transport and providing more information to your customers. You can either manually pack items into boxes or have mSupply suggest an optimal pack for you.

Manually packing boxes

On the transport tab of a customer invoice window, there are two methods for managing boxes.

  • The simple method allows you to directly enter any Box identifiers in the Boxes column
    • To use this method you should not turn on the preference mentioned below. You simply click twice (slowly) in the box numbers column of the “Transport details” tab on a customer invoice and enter box numbers.
  • If you want to assign exact quantities of each invoice line to a box or boxes, and also possibly record box weights and volumes, you need to turn on the Able to pack items into multiple boxes preference:
    • Choose Special > Show Stores
    • Double-click on the store in question (you might only have one)
    • Click on the preferences tab
    • Check the “Able to pack items into multiple boxes” preference - see details on the 24.08. Virtual stores page.

The rest of this page assumes you're using mSupply with the Able to pack items into multiple boxes preference turned on.

Setting up boxes
  • Once you've created a customer invoice, and picked goods, the pickers should have marked the pick slip with what quantities of each item were put into what box.
  • Now go to the Transport tab of your customer invoice.
  • Click Manage Boxes (Note: if you haven't turned on the preference as above, these buttons are hidden)
  • You'll see this window:

  • Click New to add boxes
  • We suggest you keep box names short. e.g. 1, 2, 3, 4 or A, B, C, D
  • Type a box name, click OK & Next (shortcut: the Enter key) to add another box.
  • On the last box click OK to save and close the window.
  • If you're Gary, you might have clicked OK & Next one too many times. In that case you can use the Cancel button to close the window. ;-)
  • Note that you can't have a blank box name, and you can't have two boxes on the same invoice with the same name (You can just use the same series of box names over and over on different invoices).
  • If you make a mistake with a box name you can double-click a row to edit it.
  • Click OK to close the Box Management window when you're done.
Using the Box Selected Button
  • In most cases you will be able to put the total contents of an invoice line in the one box.
  • In that case, click on a row, or hold down <control> (Windows) or <command> (Mac) and click on multiple rows.
  • In the example below we have highlighted rows 2, 3 and 4.

  • Now click Box selected
  • You'll be shown the “Pack selected boxes” window:

  • Choose the box for the items from the drop-down list.
  • Click OK to close the window.
  • You'll see the boxes column in the list has been filled out.
Splitting a single invoice line over multiple boxes
  • If you have bulky invoice lines or large quantities, you will need several boxes to hold the one line.
  • Double-click the line to assign to boxes.
  • Let's say in the example above, you got a supplementary request to increase the water for injection quantity from 100 to 2000. You go back to the “general” tab and do this. Now back on the transport tab you double-click the water for injection. This is what you would see:

  • Notice that at the top of the window “1900” is in red. That's the quantity still to distribute.
  • Click the Add to box button.
  • You'll see this window:

  • Let's say we're going to put 1000 in box A and the remaining 900 in box B
    • Enter 1000 in the quantity field
    • Choose A from the drop-down list
    • Click OK & Next
    • Fill out the window to enter 900 in box B and click OK to close the window.
    • Now your window should look like this:

  • You can double-click a row to edit it.
  • To delete a row, click on it to highlight it, then click Delete
  • Note that the weight and volume for the item will be calculated automatically if you have set them in the item details window, but you can also override the calculated weight/volume when you are assigning an item to a box.
Removing an invoice line from all boxes
  • You can use the Unbox button to remove an invoice line from all boxes at once.
  • Highlight one or more invoice lines.
  • Click Unbox
  • You're done.
Seeing what is in a box
  • If you click Manage Boxes and then double-click a box you will be shown a list of items in that box.
  • You can also set the measured weight and volume in this window, which will usually be somewhat higher than the calculated weight/volume:

Note that if the box has a Type then the Packed length (m), Packed width (m), Packed height (m) and Packed volume (m3) fields become read only and display the values of the box's type.

Printing packing list for each box
  • We have custom printing forms available that will print packing lists for each box. Ask us for more details.

Using mSupply to suggest an optimal pack

Rather than you manually entering which boxes the stock has gone into, mSupply can suggest an optimal pack for you. You can choose to accept or reject the pack it suggests. If you accept it, the stock is automatically packed into the boxes suggested and you can print out a guide for the packers to then follow this pack. Should you need to, you can still edit an optimal pack using the functionality described in the section above.

mSupply uses the volume of the stock and the volume of the boxes to determine what can be packed into which box so it needs both of these pieces of information. mSupply will also use the carton pack size to recognise manufacturer cartons and leave those out of the pack if you enter the carton pack size information when you receive stock.

Setup
Create the standard box types

Choose Customer > Show box types from the menus and this window will be displayed:

The window displays the current box types defined in the system. You can create a new box type by clicking on the New button or you can edit an existing box type by double-clicking on it in the list.

If you click on the New button this window opens (if you double-click on a box type to edit it, the same window is opened but it is populated with the selected box type's details, which you can edit as required):

Enter the details in the various fields as follows:

  • Description: The name of this box type (this is not the name that boxes of this type will be given when they are created. It is the name of the type of box only)
  • Length: The length of boxes of this type in metres
  • Width: The width of boxes of this type in metres
  • Height: The height of boxes of this type in metres
  • Volume: This is read only and will be calculated for you as the Length, Width and Height values are entered or edited. The value is shown in m3 and is the volume available for filling with stock.
  • Is active checkbox: Checked by default for new box types. If checked then this box type is used in suggested packs. If it is unchecked then this box type is not used in suggested packs.
  • Number available: The number of boxes of this type that are available for packing goods into. The number is automatically decremented as boxes are used in packs. If it reaches 0 then boxes of this type are no longer used in suggested packs.

When you have finished entering or editing the information, click on the OK button to save the changes or the Cancel button to discard them. To save your changes and immediately add another box type or edit the next one in the list, click on the OK & Next button instead of the OK button.

Set the box packing preferences for the store

There are some store dependant preferences which you can set, as described on the 26.07. Virtual stores page.

Turn on the preference to use carton pack sizes

This is an optional step. If you don't want mSupply to recognise and exclude manufacturer supplied cartons from the pack (and therefore pack all lines on the customer invoice into boxes) then you can ignore this step.

To turn the preference on, choose File > Preferences from the menus and go to the Invoices 1 tab and check the Show inner and outer pack fields checkbox. The preference and what it does is described on the 16.03. Invoice preferences page.

When the preference is turned on, don't forget to tell the users to enter the carton pack size in the Quan per inner field on a supplier invoice when stock is received. Unlike volume per pack, there is no way to add the inner pack size to stock lines that have already been received because this could potentially lead to internal ledger errors.

Enter volume information when receiving goods

Not really a setup step but you need to make sure users know they must enter the volume per pack of stock as it is received. If there is no volume against stock then mSupply will just put it all in the first available box!

Volume per pack for each line of stock is entered at the time stock is received on a:

You can also edit an existing line of stock to add its volume per pack at any time by using the Edit stock line window, as described on the 4.01.05 Items - Stock tab page.

Getting a suggested pack

To create a suggested pack, go to the Transport details of a customer invoice and click on the Suggest boxes button shown here:

mSupply will calculate the suggested pack and display it in a new window like this (note: any lines that are already partly packed in a box are not included in the suggested pack):

The columns in the table display the following:

  • Box: the name of this box (manufacturer cartons do not have a name since they are not packed in a box, they are ready for shipping as they are).
  • Type: the type of this box. All manufacturer cartons have the type Manufacturer carton.
  • % full: the percentage of the total volume of the box that is filled with stock.
  • % empty: the percentage of the total volume of the box that remains empty.
  • Item: the name of the item.
  • Pack size: the pack size of this line of stock.
  • Number of packs: the number of packs of this stock line to be packed in this box.
  • Batch: the batch of this line of stock.
  • Expiry date: the expiry date of this line of stock.

The manufacturer cartons are shown first (if any have been detected) and will always be shown as 100% full and 0% empty.

They are then followed by the boxes to be packed. The box name and type is shown for the first line of each box only and different boxes are separated by a blank line. So, in the example suggested pack shown above, box 1 is a medium box and should have 1 pack of Test item 03 (pack size 25, batch ZXCV1234, expiry date 31/08/2025) and 2 packs of Test item 01 (pack size 1000, batch ABCD1234, Expiry date 31/05/2024) packed in it.

If you are not happy with the suggested pack you can reject is by clicking on the Reject button. This will close the suggested pack window and log that it was rejected.

If you wish to accept this suggested pack, click on the Accept button. This will log the acceptance and create the boxes and pack the items into them as shown in the suggested pack. The Transport details tab is then updated ot show the lines packed into the appropriate boxes. This is what the example above looks like after the pack has been accepted:

If you want to print out the suggested pack (might be helpful to help the packers!) check the printer checkbox in the bottom right hand corner before clicking on the Accept or Reject buttons.

Please note: you can edit a suggested pack and the individual boxes created by it after the pack has been accepted if you wish. All the standard box management functions described above will work for boxes created by a suggested pack (including emptying and deleting boxes).

If you accept a suggested pack, partially unbox it (i.e. leave one or more lines still boxed), then click on the Suggest boxes button again, you might end up with one or more different boxes with the same name because the suggested pack function does not check for any existing boxes using the same name as one it is creating for the pack. This might cause confusion when the contents of the boxes do not match what you expect. For this reason, we recommend you always fully unbox an accepted suggested pack before trying it again.

Accepted pack report

You can run a report on how mamny customer invoices were packed using the suggested pack. To do this, choose Report > Suggested pack acceptance from the menus. The report options window will open:

Select the dates between which the creation date of customer invoices must fall to be included in the report. The Previous month is selected by default but you can select different From and To dates manually, by using the calendar icons or by using the quick selector drop down list.

Click on the OK button to run the report, which will look like this:

The final column shows a Y if the suggested pack was accepted for this invoice, an N if it was rejected and is blank if an invoice has never had a suggested pack.

The report uses the pack acceptance/rejection log entries to decide whether the pack was accepted or not. The last pack acceptance/rejection log entry for an invoice is the one that tells mSupply whether the pack was finally accepted or rejected, regardless of how many suggested packs have been carried out on an invoice.



Previous: 8.05. Transferring goods to another store | | Next: 8.07. Stock control methods for your customers

8.08. Customer budgets

This feature enables you to manage the budgets of customers in your system. Remember, in mSupply customers are names to which you supply goods. To enable the feature you need to turn it on and then set preferences for its use and allocate budgets to your customers. When using it, you see extra fields on a customer invoice which tell you how much budget the customer has been allocated and the amount you have remaining. Once a customer has reached their budget limit a customer invoice cannot be confirmed unless it is first authorised. All the details you need are below.

Setting up the customer budgets feature

Turning the feature on: File preferences
  • Go to File > Preferences…
  • Select the Invoices 1 tab.
  • Check the 'Per customer budgets' checkbox. Note that 'Activate budget module' must be checked first and you should have previously set up your budget periods (see Budgets for details).
  • After clicking Per customer budgets checkbox confirm dialog box is shown with message “Turning on the customer budgets functionality requires that the preferences for authorising customer invoices be turned on and automatically confirming and finalising customer invoices be turned off. Is this OK?”
  • You must click OK to activate the functionality. When you do, the “Customer invoices must be authorised” and “Authorisation needed only if over budget” store preferences are turned on for all stores.
  • Optionally, you can divide budget periods up into smaller equal parts and apply the same fractional amount of the period budget to each part-period. For example, if your budget period is a year you might want to split this up into quarters and allow customers to freely spend up to a quarter of their annual budget in this time. To activate these additional limits check the Apply part-period limits checkbox and type into the textbox the number of part-periods you want to split the budget periods into. To split annual periods into quarters you would enter 4 into the textbox:

Note that any unused amounts of part-period budgets roll over to the next part-period. Full period budget amounts do not roll over to the next period.

Configuration: Store preferences
  • If Per customer budgets is turned on then “Customer invoices must be authorised” checkbox and “Authorisation needed only if over budget” are turned on. This is done automatically for you when you turn the feature on (as mentioned above). You can, however, uncheck these checkboxes for individual stores to have the feature work in different ways:
    1. “Customer invoices must be authorised” and “Authorisation needed only if over budget” both checked - customer invoices can be confirmed freely until the budget limit is reached. After that, customer invoices must be authorised before they can be confirmed.
    2. “Customer invoices must be authorised” and “Authorisation needed only if over budget” both unchecked - mSupply will display the budget information on the customer invoice but it will not enforce the budget.
    3. “Customer invoices must be authorised” checked, “Authorisation needed only if over budget” unchecked - all customer invoices must be authorised, regardless of whether the customer has exceeded their budget.

Add budget periods
  • These are the system-wide budget periods that mSupply uses for its budget functionality. Customer budgets are assigned to these budget periods so you must set them up before you can start setting up individual customer budgets.
  • From the Navigator click the drop down menu Special > Show budgets…. You click on the New button to create a new budget period but for the full details please see Budgets.
Setup: Set individual customers' budgets

If you have a lot of customers to setup budgets for, you might like to import them instead. See the 17.06. Importing customer budgets page for details on that.

  • Note that if you want to set up many or all customers' budgets at one time you can use the import feature, details of which are here
  • To set up the budget for each customer, go to Customer > Show customers…, click on the Find button, and double click on the first customer to show their details
  • Click on the Budget tab
  • Add budget: Click on this button to add a budget. This opens the edit budget window shown below.
  • Delete budget: Select a budget in the list and click on this button to remove the budget for the customer.
  • Edit a budget by double clicking on a budget in the list. This will also open the edit budget window (shown below) pre-populated with the budget's current settings, all of which are editable.

Customer budget edit window

  • Description: The description for the budget. This is for your reference, only displayed in the budget tab of the customer details window.
  • Budget period: The period that the budget applies to. This list contains only the budget periods previously set up using Budgets.
  • Amount: The amount of the budget in your local currency
  • Additional budget: If checked this tells mSupply that the budget amount is to be considered as an additional amount available only from the part-period in which its effective date falls. For example, if you have a budget of 100,000 which runs from 1st January to 31st December in a given year and is split into 4 part periods and you then have an additional budget amount of 10,000 with an effective date of 30th July, the following budget limits will apply: for the 1st quarter the customer has 25,000 available, the 2nd quarter 50,000 available (25,000 + 25,000 because part period amounts roll over), the 3rd quarter 85,000 available (25,000 + 25,000 + 25,000 + 10,000) and the 4th quarter 110,000 available (25,000 + 25,000 + 25,000 + 10,000 + 25,000).
  • Effective date: This field is only visible if the Additional budget checkbox is checked. The date that the budget amount is to be effective from: mSupply applies the additional budget amount to the part period in which this date falls. Note that if part periods are not in use then additional amounts simply add to the total budget available for the whole budget period.

Using the customer budgets feature

The customer invoice window

This is where you see the customer budgets feature doing its job; when you're distributing goods to a customer:

  • Create a new customer invoice (Customer > New invoice…)
  • Enter the customer name
  • Select the budget period that this invoice belongs to from the Period drop down list (this list contains the periods you set up using Budgets).
  • If you haven't set up a budget for the customer you are warned with this message: “There is no budget set for this customer in that period. You will not be able to confirm the invoice until the budget has been set.”.
  • If you've followed the instructions above and setup the customer's budget correctly then the Total budget used and total budget fields are populated to show you exactly how much of their budget the customer has used so far.
  • Add items to the invoice as required.
  • Everything will behave exactly as it has done before until the customer's budget amount has been exceeded.
  • When the customer's budget has been exceeded (this can be the full period amount or the part-period amount if the part-period limits are turned on) and the confirm button is clicked you will be alerted with the message “This invoice exceeds the budget set for this customer. You cannot confirm it without authorisation (Note: you cannot confirm the invoice at the same time as authorising it, you must save the authorisation first by clicking the OK button, then re-open the invoice and confirm it)”.
  • The invoice must now be authorised by a user with suitable permissions before it can be confirmed: See Invoice Authorisation for details on authorising customer invoices.

Reporting on customer budgets

There are several reports that provide various information on customer budgets, they are:

  • Disbursement Report - shows items with their values which have been distributed to customers during a budget period.
  • Expenditure report - shows spending against budgets with remaining available budget.
  • Trend Report - shows, in graph format, spend against budgeted amount.
Disbursement report
  • From the Navigator click drop down menu Reports and click option Customer Budgets.
  • Choose budget_balances from the print options window which appears:

  1. Budget period: select the period you want to report on.
Expenditure report
  • From the Navigator click drop down menu Reports and click option Customer Budgets.
  • Choose budget_district_expenditure (or budget_facility_expenditure) from the print options window which appears:
  1. If District: Select “All” to see expenditure for all districts, or select a district to see expenditure for the facilities in that district
  2. If Facility: Select the facility to see expenditure for that facility, and select the reporting interval
  3. Select the date range you want to report on.
Trend report
  • From the Navigator click drop down menu Reports and click option Customer Budgets.
  • Choose budget_trend_district (or budget_trend_facility) from the print options window which appears:
  1. District/Facility: Select “All” to see a graph for all, or select a district/facility to see a graph for just the selected district/facility
  2. Interval: Choose the intervals you want for the horizontal axis, eg. quarterly, yearly, etc.
  3. Select the date range you want to report on.

Note that this is a cumulative report, so the graphs generated need to include the entire budget period. This means that the date range is only used to determine which budget periods intersect with the selected dates e.g. if the date range covers more than one budget period, a graph will be generated for each one.



Previous: 8.07. Stock control methods for your customers | | Next: 9. Returning goods

8.04. Electronic invoices

mSupply has a system that allows users to send electronic invoices to other users of mSupply.

Possible uses include:

  • If you have a manufacturing unit and a separate warehouse, you can run two copies of mSupply and move stock from one location to another using electronic invoices.
  • If you have customers using mSupply, they can import a 100 line invoice in a few seconds, where entering manually might take thirty minutes to an hour.

Setting up electronic invoices

Supplier
  • In the Preferences of the copy of mSupply that is sending invoices, enter the supplier code that your customers will use for you.
  • If your customer(s) have an email address and you want to send the electronic invoices via email, then enter their email address in the customer details window.
Customer
  • For each item that will be received from a particular supplier, enter a quotation for the item. This is most easily done from the quotes tab of the supplier details window.
  • For each quotation, enter the supplier code for that item. This means your own code for the item does not need to match the supplier code. (Note that you do not have to enter quotation prices for the electronic invoice system- just the item code).
Steps to use electronic invoices
  1. Supplier creates an invoice
  2. Supplier chooses customer | export invoice to create an invoice
  3. Supplier sends the invoice to the customer (If the customer has an e-mail address entered, the invoice can be automatically attached to an email, or, the file produced can be attached to an e-mail using your normal e-mail client. Alternatively it may be transferred on removable medium (floppy, Zip, CD etc..)
  4. Customer receives electronic invoice
  5. Customer chooses Supplier | import invoice to import the invoice.
  6. Customer checks the supplier invoice that is created against other documentation and against actual goods received.

Note:

  • The invoice can still be edited after import
  • The standard rules for calculating selling prices are used.
  • If you want your suppliers to send you electronic invoices, persuade them to buy mSupply! Alternatively, we can supply the mSupply invoice format to their software vendor for inclusion in their own software.
  • We recommend you perform a trial of the system on a backup data file before using in a production situation.



Previous: 8.03. Backorders | | Next: 8.05. Transferring goods to another store

8.01. Issuing goods to a customer (customer invoices)

Creating a new Customer Invoice

Choose Customer > New invoice from the menus. A window like this will open:

Variations you might see in this window
  • A user defined field (the Truck No field) is displayed in the above screenshot. To show or hide user defined fields go to File> Preferences> Invoices 2 (see the 16.03. Invoice preferences page for details).
  • If the Able to specify VVM status when receiving items store preference is turned on (see the 26.07. Virtual stores page for details) then an additional Doses column will be displayed in the table. If the item is a vaccine then the column will show the number of doses the line represents. If it is not a vaccine then it will show N/A.
  • The Confirm date can be made editable if the Allow confirm date to be edited on invoices preference is turned on. See the 15.03. Invoice preferences page for details.
Information to enter in the main window
Name

Type as much of a customer name here as you know and then press Tab. If there is only one name that matches your choice, it will be entered automatically for you, otherwise you will be presented with a list of available choices. Once you have entered a valid name, the New line button will be enabled. If you can not find the name you are looking for, you can add a new name by clicking the person icon () to the left of 'Name'.

By default, names with their code starting with a tilde (~) are not shown. This is a great way preventing a user selecting a name when it can't be deleted or hidden in a store - put a tilde character at the beginning of its code.


The downward pointing arrow to the right of the Name field takes you directly to the Edit Customer/Supplier window, giving access to all the information relating to the name entered

Their ref

Enter the customer's order number if there is one

Comment

Click on the downward pointing arrow to the right of the Comment field to display a window where any comment relating to this invoice can be noted.

Category

If you are using the category feature, and have defined them, the appropriate category is selected from the drop-down list.

User-defined transaction fields

If you are using the user-defined transaction fields, they will appear and can be filled in here. Should you wish to use them, they have to be activated in Preferences>Invoices 2, refer Show customer transaction fields.

Read-only information on the invoice

There is some information on the top of the invoice that is read-only and cannot be edited:

  • Confirm date: The date the invoice was confirmed. “00/00/00” if the invoice has not been confirmed. Note: this date can be made editable if the Allow confirm date to be edited on invoices preference is turned on. See the 15.03. Invoice preferences page for details.
  • Invoice: This is the invoice number. The number is automatically incremented and assigned when the invoice is first saved (which actually occurs when the first line is added to it) and is unique within a store. Note that customer invoices in different stores could have the same invoice number.
  • Entry date: The date the invoice was created.
  • Requisition: If the customer invoice is linked to a requisition (because it is supplying goods to a customer because of a requisition they sent to you or you created for them) then its number will appear here in blue, indicating that it is a link and, if clicked, will open the requisition. If the number is 0 this indicates that the customer invoice is not linked to a requisition.
  • Status: The current status of the customer invoice:
    • nw = new (just created, can still be edited, stock not yet removed from mSupply but available stock reduced so reserved stock can't be assigned to another invoice)
    • sg = suggested (has been opened since first creation, still editable, stock not yet removed from mSupply).
    • cn = confirmed (stock has been removed from mSupply but invoice is still editable).
    • fn = finalised (stock has been removed from mSupply and the invoice is no longer editable).

      In a multi-store system, a CI will not translate into a SI in the receiving store unless it is finalised. mSupply will warn you if the customer is another store in your system and you are trying to close a CI with status = cn.

  • Entered by: The user name of the user who created the customer invoice.
  • Store: The name of the store the customer invoice belongs to.
Buttons at the top of the customer invoice window

At the top of the Customer invoice window, there are a series of buttons:

New line

Will add a line to the invoice. This command can be used on any invoice that is not finalised. Clicking the button will present you with the window for adding a line from stock. See the Adding lines to an invoice section below for more details. To select a line to edit, simply double-click on it. Note that new line and edit line are disabled on finalised invoices.

Delete line(s)
  • Will delete any selected line(s).
  • Selected line(s) will appear highlighted.
  • Multiple selected lines do not need to be adjacent.

Once an invoice has been finalised, you can not delete an item line from it.

Backorders

This icon is displayed only if `We run a backorder system' is checked in the Preferences > invoices 2 options - refer We run a backorder system. Clicking this button shows you a list of items that are on backorder for the customer you have chosen. To view the backorder list of items, you must first confirm the transaction.

Refer to Issuing Goods - Managing Customer backorders for a full coverage of the backorder topic.

History

Clicking on this icon will display a record of all that this customer has purchased in the past. This may produce a very long list! The list appears in chronological order, but clicking on any of the column headers will sort the list according to that parameter.

Confirm

When this button is clicked, the status of the order changes from nw (new) or sg (suggested) to cn (confirmed).

If you have “confirm invoices automatically” set in the Preferences, the Confirm button will not be visible. The invoice will be confirmed as soon as you click on the OK button. Read below to see what confirmation does.

  • The confirm button is only available for invoices with status nw (new) or sg (suggested).
  • Confirming an invoice should be done when the goods have been removed from the shelves and have left the store or have been packed ready for dispatch). Most importantly, as far as mSupply is concerned, this stock is no longer in the store and a stocktake will not find it!

More detail around confirming a Customer Invoice:

  • Each item line records two stock levels- the Tot in store is the total stock in the store. the Available amount is what can be issued on an invoice.
  • For example:
    • You have 10 bottles of Paediatric Paracetamol Elixir in stock.
    • You get an order for 3 bottles from Fred, and create an invoice for Fred and set the Issued amount to 3. The Tot in store is still 10, but Available amount drops to 7 as these 3 bottles are 'reserved' for Fred and can't be issued to anybody else.
    • You are about to dispatch the order. At this point you confirm the order. The Tot in store also drops to 7.
  • In summary, the Confirm button does the following:
    • Each line has its Tot in store reduced by the Issued amount on that line
    • The Customer Invoice status changes to cn
  • If you are running a backorder system, confirming a Customer Invoices also deletes any placeholder lines (those with a batch entry of “none”) and adds them to that customer's backorder file.

Modifications may still be made to the invoice (and those changes therefore directly affect the stock in mSupply). See Confirming an invoice.

If you have the store preferences set to force customer invoice authorisation, you will not be able to confirm customer invoices until they have been authorised. See here for details.

If your system has multiple stores, you will not be able to transfer stock to a store if the item is not visible in the receiving store. There are many checks in mSupply to make sure that stock cannot be hidden in a store.

Buttons and checkboxes at the bottom of the Customer invoice window

At the bottom of the Customer invoice window, there are a series of controls.

Hold

Checking the Hold checkbox prevents the Customer Invoice from being confirmed or finalized.

Finalize

Checking the Finalize checkbox allows you to finalize an invoice when you click the OK button. Only users with Can finalize individual invoices checked in their user permissions can check this box. Other users will be warned if they try to turn it on, and the Finalize checkbox will automatically uncheck.

If the Finalize checkbox is checked and you click the Confirm button, the invoice will be confirmed as well as finalised when the OK button is clicked, so be very careful! A finalised invoice may be viewed and/or printed, but it can not be edited.

If the Finalize checkbox is checked but dimmed out, it means that File>Preferences>Invoices 2>Finalize customer invoices automatically is checked and all confirmed invoices will be finalised whether you like it or not!

Delete

The Delete button allows the deletion of an invoice. If the invoice has a status of 'nw' you can delete the invoice even if has lines added. If the status is 'cn' or 'sg' you will have to delete the lines manually first - refer Deleting line(s). When an invoice has been deleted the invoice number that it was assigned will be reused.

OK

The OK button saves the changes you have made and exits the window. You are given the opportunity to print if the Print checkbox is ticked.

PLEASE NOTE: Before the window is closed, a check is made that none of the stock being issued on the invoice was received before the invoice was confirmed. If this condition is encountered, an alert will inform you that you must choose another line of stock or change the confirmed date of the invoice. This condition is only possible if the Allow confirm date to be edited on invoices preference (see the 15.03. Invoice preferences page for details) is, or has been, turned on.

OK & Next

The OK & Next button does the same as the OK button but it then opens the next customer invoice in the list, if this one was opened from a list. If there is no next invoice, or you've reached the end of tha list then the window just closes, exactly the same as if the OK button had been clicked.

Printing the invoice

If the Print checkbox is ticked then print options will be presented when the OK or OK & Next buttons are clicked.

If the invoice status is 'nw' (new) or 'sg' (suggested), pick list options will be printable.

If the invoice status is 'cn' (confirmed) or 'fn' (finalized), invoice options will be printable.

If the option to turn on the print check box has been set under File>Preferences>OK and print, you can override the printing process by holding down the Shift key as you click OK, and no invoice will be printed.

Instead of an invoice, should you wish to print a pick list for an invoice whose status is 'cn' or 'fn', hold down the Alt key (Windows) or the Option key (Mac) while clicking OK.

Tabs in the customer invoice window

The three tabs allow the invoice to be viewed in three different formats, but note that the lower area of the window remains the same and is available for appropriate input in all views.

General tab

Once an invoice has been created, a detailed view of the items on it may be seen by selecting this tab; where the supply of a single item is made up of different batch numbers, they will be displayed as separate lines:

Buttons in the General tab

There are a row of small icon buttons at the bottom left of the window. Hovering the mouse over each button gives a description of what it does.

Process button (grinder icon)

Clicking this button shows a menu with the following choices:

1. Renumber lines: will re-assign line numbers to all lines on the invoice according to their current order (you can move lines around by dragging and dropping to a new position.

2. Issue stock for all placeholder lines: This option will go through each placeholder line on the invoice and issue stock to them by taking stock from stock lines in the order described in the Selecting from stock lines section below. This can be really helpful but, beware, there are good reasons why you might not want this to happen, including:

  • Availability of sufficient stock of the line in question
  • Pack sizes that fit with the quantity/pack on the placeholder line. mSupply will happily issue parts of a pack. In reality, you may wish to choose from a different stock line with different pack sizes!
  • You might want to issue stock belonging to a particular program or donor.
Financial summary

Clicking this button shows you a summary of the cost and selling price information for the invoice.

If you check the Print as Pro-forma invoice checkbox in this window, rather than printing a pick slip, a pro-forma invoice will be printed, allowing you to give a paying client a form showing expected charges.

Transaction note

Allows you to make a note relating to this invoice.

Copy to clipboard

Copies the entire invoice to the clipboard.

Summary by item tab

The Summary by Item tab displays the items on the invoice, consolidating different batch numbers and displaying the total quantities for each item only; the invoice above appears in the following format when the Summary by Item tab is selected.

Summary by batch tab

The Summary by Batch tab displays the items differentiating between batches, and showing a breakdown where more than one batch has been supplied on the order. The above invoice appears in the following format when the Summary by Batch tab is selected; note that two different batches of metronidazole tablets were supplied.

Transport details tab

Selecting this tab displays the following window:

Here you can add information about the method of transportation and other related information. You can then report on performance of your transport operations in various ways using the Transport Report.

Order tracking data

The five date boxes enable you to track your order from it being generated (written) to the customer confirming receipt of it (actual arrival date):. The five date fields are:

  • Order written date: The date the customer wrote the order (this will usually be on their requisition form).
  • Order received date: The date the customer's order was received by you
  • Order shipped date: The date the order left your store
  • Expected arrival date: Given the shipping method you're using, when you expect the goods to arrive at the customer's premises.
  • Actual arrival date: The date the goods reached the customer you are supplying. Obviously you will only know this if they report the information back to you (e.g. via SMS message)

If you use these date fields, it allows reporting using the Transaction Report using the report form Order Processing time. Sometimes it is necessary to edit these dates after finalisation of a customer invoice so there is a special permission for users to allow them to do this (on the User details page, Permissions 2 tab - see Managing users, the Permissions tabs for details.

  • You can make the Order written date and Order received date fields compulsory in File > Preferences, Invoices 2 tab as explained in Invoices preferences.
  • You can add a Shipped to contact name if you select Choose contact for transport details in File > Preferences, Invoices 2 tab as explained in Invoices preferences
Shipping method

The list of options in the Ship method drop down list is set by choosing Customer > Show shipping methods…, when you are shown a window with a list of existing shipping methods:

Plan carefully before creation of shipping methods. Once created, a shipping method can be edited, but it can't be deleted if even a single customer invoice is using it…

  • To enter a new method, click the New button.
  • To edit an existing method, double-click the item in the list and edit its details.
  • To delete a method, click on it in the list to select it then click on the Delete button. You will not be able to delete a shipping method if it is being used by a customer invoice. Depending on the status of the CI, you may be able to change a shipping method ;-)
Responsible officer

The choice list for Responsible officers is a list of mSupply users for whom the “Can be responsible officer” check box has been checked. Choose File>Edit users…, then double-click a User Name to set up each user as a responsible officer (or remove them from the responsible officer list)

Box management and label printing

The Box Management feature is used to tell mSupply which items were put in which 'box' or container for transporting to your customer. This has a few advantages:

  • You can print labels from mSupply to stick on each box (either from a label printer or a normal A4 paper printer - see the Printing an invoice: Picking slips and delivery notes section below for details).
  • You can create (automatically or manually) weight and volume information which can be printed on the packing list or passed to your freight handlers.
  • It tells the customer what's in each box to help their goods-inwards processing.

For full details about this feature see the 8.06. Box management page.

The Print labels button at the bottom of the page will enable you to print labels from a label printer to stick on the packaging. When you click on the button, a list of the available formats will be shown; simply click on the one you want and the appropriate label will be printed from your label printer. Don't forget to set up your label printer first! See the 10.08. Label printing preferences page for details.

You can also have box labels printed automatically from an A4 paper printer: this is an example of such a box label:

Documents tab

The Documents tab on a customer invoice enables you to save documents and other files relating to the invoice. The tab looks like this:

The table shows you all the files currently uploaded to this invoice.

  • Upload document button: Click this to upload a document to the invoice. This will open a window enabling you to search for and select the file on your computer. After you've selected it, click on the Open button to upload it. If you upload a file with the same name as one already uploaded, mSupply will upload it as a new version of the already uploaded file.
  • Delete document button: Select a file in the table by clicking on it and click this butotn to remove it from the invoice.
  • Download document button: When you click on this button you are presented with two options:
    • Download: this will download the file to a location you select on your computer.
    • Download and open: this will download the file to a location you select on your computer and then attempt to open it using the default application on your computer for that file type. If there is no application associated with the file type on your computer then mSupply will tell you that the file could not be opened.
Log tab

Added: version 3.1

The log tab displays changes to the invoice that have been logged. Details of all logged activities are record in the mSupply Log.

MoneyWorks tab

If you are using the Moneyworks accounting software then the link between mSupply and Moneyworks will need to be enabled in File>Preferences>Moneyworks - refer General Preferences - Moneyworks. If this option has not been enabled, then the Moneyworks tab will not be visible.

The Moneyworks tab will show the status of the invoices inside Moneyworks accounting software once mSupply has carried out an export.

Custom data tab

This tab shows the custom fields that have been set up for customer invoices (see the Custom fields section for details).

All custom data will be saved with the invoice (i.e. when you click the OK or OK & Next button).

Adding lines to an invoice

Clicking New line will bring up the Add Item… window:

Finding the item you want

The first thing to enter is the Item Name or Item Code in the Item field. Type as much of the Item Name as you know, then press Tab. mSupply searches for all Items whose Name or Code starts with the text you have typed.

By default Items with a Code starting with a tilde (~) are not shown. This is a great way preventing a user selecting an item that shouldn't be used when it can't be deleted or hidden in a store - put a tilde character at the beginning of its code.

If no entries match the request, the Item field will read 'try again'. You can try as many times as you like! If you conclude that the Item you want does not exist in your system, click New item to add the Item.

Caution should be exercised before adding a new Item to your mSupply system. Duplicate items cause problems. Ensure that the item you are looking for does not already exist in your system and is hidden in the store you are logged into or is under a different Item Name and Item Code.

If only one Item matches your request, it will be chosen automatically and you will be returned to the Add item… window with that Item already selected.

If your mSupply system has been set up with unique Item Codes for each Item, then the experienced user will find that typing in the full Item Code here will save mouse clicks and/or key presses.

If more than one Item matches your request, all of them will be displayed.

Note: if the Show item unit column when issuing store preference is turned on (see the 25.08. Virtual stores page for details) then an Item unit column will also be included in the table.

If the wanted Item is visible, double-click on it or click on it once and then click Use.

If the wanted Item is not visible, click Cancel to try again to find it.

Selecting from stock lines

Once the item you want has been selected, the Add item… window will display a list of available stock lines (if any). Each stock line may be a different pack size, batch, expiry, or price. The stock lines are sorted by expiry date; first expiry at the top.

By default, the lines are numbered in the left hand column and sorted according to these values, in this order:

  • Expiry date (earliest expiry date at the top i.e. in FEFO order; First Expiry, First Out)
  • Then, for all stock lines with identical expiry date, by location priority (lowest priority number first; see the 4.06. Stock locations and location types page for details).
  • Then, for all stock lines with identical expiry dates, in locations with identical location priority, by Location code in ascending alphabetical order.
  • Then, for all stock lines with identical expiry dates, in locations with identical location priority, in locations with the same code (including the same location!) by batch number (ascending alphabetically).
  • Then, for all stock lines with identical expiry dates, in locations with identical priority and code and with identical batch numbers, the number of available packs (in ascending numerical order i.e. smaller quantities first).

This sort order will be slightly different if the Sort available batches by VVM status rather than Expiry store preference is turned on (see the 26.07. Virtual stores page for details):

  • VVM status (lowest first)
  • Then by expiry date
  • Then by location priority
  • Then by location code

The first line in the table is selected by default but you can choose another line in one of three ways:

  • Type the line number into the Line field and press Tab. The cursor moves to the Quan field.
  • Double-click on the line in the list. That line number is displayed in the Line field and the cursor moves to the Quan field.
  • Single-click on the line in the list. Clicking again in the Issue column will allow you to directly edit the issue amount in the list - see following.

Once you have chosen your line, the number of packs available will be shown to the right of the Quan field, the Pack size will be shown in the Pack field, and the total quantity to be issued will be shown below the list of lines.

In the Quan field, you can enter any number greater than zero.

If you want to enter directions or notes for customer invoice lines (that will be printed after each line when you print it out) then you can turn these on in the preferences. See the 16.03. Invoice preferences page for details.

If you need to see the full details of the item itself, click on the down arrow icon to the right of the item name field and you will be taken to the item's details window.

The number entered in the Quan field is the number of packs. The pack size of the currently selected line will be used to calculate the total quantity of units issued - which is shown below the list of lines as Total quantity issued.

Vaccines

If an item is designated as a vaccine (see the Is a vaccine and Doses fields on the 4.01.01. Items - General tab page for details of how this is done) then an additional Doses field is displayed on this window:

When you enter a figure in the Quan field the equivalent number of doses is automatically entered in the Doses field.

This works the other way round too, so you can enter the number of doses in the Doses field and mSupply will put the equivalent number of packs in the Quan field. This is useful because some users will think in terms of doses and others in terms of packs.

If the preference to display the Total field is turned on (The Allow users to enter total quantities to distribute preference, see the 26.07. Virtual stores page for more details) then this also works for the Total field: if a figure is entered in either the Quan, Total or Doses field then mSupply will put the correct equivalent figure in the other two fields.

Custom data fields for invoice lines

If you have entered any custom data fields for the trans_line table (see the 16.11. Custom fields page for details) then, when you have selected the item, the stock lines will appear on a Select stock tab like this:

and the Custom data tab will display the trans_line custom data fields you created in the preferences like this:

These custom data fields are all enterable and you can enter values as required. If you come back to this window when editing customer invoice lines later, the custom data fields will also be available for editing.

Issuing from a single line

If the number entered in the Quan field is less than or equal to the number available for the selected line, then that value will be shown in the Issue column in the list.

Click OK to return to the main invoice screen, or OK & Next to add another Item.

Please note: If the Allow editing selling price on customer invoice lines store preference is turned on (see Virtual store preferences) and the Price editable when issuing checkbox on the General tab of an item's details page (see Item basics - General tab) is turned on then there will be an extra Sell price field for the user to enter the desired selling price for this customer invoice line:

Issuing from multiple lines

If the amount to be issued is greater than what the top line can issue, then you can issue from multiple lines without leaving the window. There is an automatic and a manual way of doing this.

Manually issuing from multiple lines

For each item line that stock is to be issued from:

  1. Click once on the list to select the line
  2. Click again in the Issue column
  3. Enter / edit the issue amount in the Issue column

The Tab / Shift-Tab keys move the focus up and down the Issue column.

The Total quantity issued is updated at the bottom of the Add Item… window.

Automatically issuing from multiple lines

If the amount to be issued is greater than what the top line can issue, mSupply can automatically select stock from multiple lines on a FEFO basis. To allow mSupply to do this, simply enter the total quantity you wish to issue into the Quan field.

If the quantity typed in the Quan field is more than there is available for the selected line, and the Tab key is pressed to leave the Quan field, this message is displayed:

If you accidentally entered more than you intended, click Try again, otherwise click the Distribute button.

Issuing when there is not enough stock

If the amount to be issued is greater than the total stock available from all of the available lines, then a placeholder line may be used, if your mSupply preferences allow.

Placeholder lines

If there are no lines available, or none of the lines are suitable (for example, this order needed strip packaged stock, and the available lines are all bulk packs), then you can add a placeholder line that will record the desired quantity and pack size until either you get stock, or go to confirm the order, at which time the item will be either moved to backorder or deleted (depending on how you have set your Preferences).

A Placeholder line can be added manually or automatically.

Manually adding a placeholder line

A Placeholder line can be added by clicking the Add Place holder button.

As shown in the window displayed below, placeholder lines are coloured in red and have a batch of “none” so you can easily identify them.

The quantity to be issued in the placeholder line is entered in the same way as any other Item Line - refer Manually issuing from multiple lines

Automatically adding a placeholder line

If the number entered in the Quan field is greater than the total stock available from all of the available lines, then mSupply will prompt you with an Alert:

After clicking OK, all existing stock lines will have the Issue column populated with the total quantity available for each line, and a placeholder line will be created with the outstanding quantity inserted in the Issue column.

If you have allowed placeholder lines in the Preferences, and you choose an item that has no available stock, a placeholder line will be created automatically.

Confirming an invoice with placeholder lines

When confirming an invoice that has placeholder lines, the following actions will occur:

  • If you have activated backorders, a backorder line will be created for each placeholder line.
  • If you have set the Preferences to delete placeholder lines when confirming, they will be deleted, otherwise they will remain on the invoice to show the client that their order was received, but the goods were not supplied.
Issuing all available stock of a batch

Sometimes you might end up with an unusual available amount of a particular batch. Due to the fact that mSupply rounds the available quantity, it may be hard to enter the exact amount to completely issue the batch. In such situations you can issue the total amount available by holding down the shift key while you double-click a line. This will issue the total available amount of that batch.

Lines on hold

Sometimes you will see that a stock line has a tick in the tick-box in the Hold column and the line cannot be selected for issue, like the bottom one in this screenshot:

There are two possible reasons for this:

You can find out whether it is the stock line or location (or both!) that is On Hold by double clicking on the line in question. If it is the location that is on hold then, in the window that has opened, the Hold checkbox on the General tab will not be checked. If the item line itself is on hold then it will be checked.

If there is insufficient stock in 'off-hold' stock lines to fulfill the invoice, a placeholder line can be created.

Adding lines from a bill of materials

Added: version 3.72

If the “Show 'Add from BoM' button” preference is turned on (see here for details) there will be an additional Add from BoM button on the customer invoice form:

When you click this button it shows you a list of all the Bills of Material that exist in mSupply. Select one of those then mSupply will add all the items on that bill of materials (with the quantities they have on the bill of materials) onto the customer invoice as placeholder lines. You can then assign stock to the placeholder lines in the normal way (see, for example, Editing a placeholder line on an invoice below).

See the Bill of materials section for details about creating and using bills of material.

Editing an invoice line

To edit an invoice line, double-click on it. You will be presented with the Edit line window, which is identical to the New line… window, except that the item name is already chosen.

In the Edit line window the quantity you have already chosen is added back into the Available stock column. You are viewing the stock records as if the line has not yet been processed.

Similarly, any other invoice lines for the same item are also shown in the same way; the Issue column is filled out with the the amount being issued from each batch on the invoice and the Available column includes the Issue amount.

For example, in the window below, there are two lines on the invoice for different batches of paracetamol, and all are shown when editing, irrespective of which of the lines was double-clicked.

At this stage you can:

  • Edit the Issue value for the selected line item, or change the value in the Quan field
  • Select a different item line (that is, a different batch) and edit it's Quan or Issue value.
  • Click in the item name field, and select an entirely different item!

Selecting a different item has the following effects

  • If you proceed to issue the new item, all invoice lines for the item you were editing will be deleted, and invoice lines will be added for batches being issued of the new item.
  • If you choose a new item for which there is already one or more lines on the invoice, the stock to be issued on those lines will be shown in the “issue” column. If you proceed you are effectively editing the quantities of the item you have just selected, and you are deleting all invoices lines of the item that was originally on the invoice.

PLEASE NOTE: If the customer invoice is confirmed then you will not be allowed to issue from stock lines that were received after the customer invoice's confirm date. This condition can only be possible if the Allow confirm date to be edited on invoices preference (see the 15.03. Invoice preferences page for details) is, or has been, turned on.

Changing the batch to be issued

If you want to choose a different batch for an existing invoice line:

  • double-click the invoice line
  • set the quantity of the batch you don't want to zero,
  • double-click the batch you do want, and enter the quantity you want to issue.
  • Note that if possible the new batch will be added to the invoice at the bottom of the other lines, and the former invoice line will be deleted. You can use drag and drop to reorder invoice lines if this is a problem.
Editing a placeholder line on an invoice

When you double-click a placeholder line, an extra button is displayed:

The Redistribute all button takes the quantity on placeholder lines and re-assigns it to actual batches in stock, assigning stock from stock lines in the order described in the Selecting from stock lines section above.

When you are not editing a placeholder line, the button is not visible.

Invoice line custom data

If you have custom data fields created for the trans_line table in the preferences then the custom data tab will be visible and you can also edit the custom data field values. See the Custom data fields for invoice lines section above for more information.

Reordering invoice lines

Invoice lines can also be reordered by drag-and-drop of a line to a new location. This can be useful to group lines for the same item.

If the invoice lines are currently sorted by line number, the renumbering will happen, otherwise you will be shown an alert message.

If you really want to reorder lines when sorted by a different column, hold down the shift key as you drag-and-drop to override the message.

Note that reordering can not be undone, apart from you manually dragging lines back to their original location.

  • Lines in most mSupply forms can be sorted according to any column by clicking on the heading of the column that you want to sort by.
  • To make any sort order 'stick' when it is printed, you will need to renumber the lines - refer Issuing Goods to a Customer (Customer Invoices), The Grinder button above.
  • A common desired sort order for a pick slip is to sort lines by Location, so that when a pick slip is printed, the picker can work their way through the store systematically by Location. In fact, this is such a popular feature, we have set a printing preference so that it will happen automatically without needing to manually sort the list - refer Printing Preferences 8-).

Currency settings

If you have customers that use a currency other than your own, mSupply can be configured to use your customer's own currency. Firstly you need to make a selection in the Store's preferences to enable issuing in a foreign currency.

Once you have done this, you can select a currency for a customer from the edit customer window.

You can also select the customer's currency when entering an invoice.

Currency: This is the currency your customer uses. It is set in the Customer Details window of the Customer record and is displayed when you add your customer's name to the invoice.

Currency rate: Gives the exchange rate stored in mSupply.

Foreign currency total: Provides the invoice total in the currency the customer uses.

Printing an invoice: picking slips and delivery notes

You can print an invoice at any time when it is open in two ways:

  1. by checking the print icon checkbox (next to the OK button) and clicking the OK button:
  2. by holding down the Shift key on the keyboard and clicking the print icon instead of checking it.

Method 1 will close the invoice after printing, method 2 will leave it open after printing.

But note: you print different things depending on what status the invoice has:

  • If the invoice is suggested (sg) then a picking slip is printed.
  • If the invoice is confirmed (cn) or finalised (fn) then a customer invoice or delivery note is printed.

Whether you use method 1 or 2, you are shown the print options window:

Form to use

The Form to use drop down list contains all the options for the format of the print out you will get. All the standard mSupply options will be here, as well as any custom forms we have created for you.

If the form you selected to use wasn't the one offered by default and you want to set it to be the default from now on (beware, this will set it for everyone!) then check the Remember this choice checkbox before you click on the OK button.

Dispatch labels

If you want to print dispatch labels to go on each box then check the Print dispatch labels checkbox. This will print labels on 100x150mm labels on a label printer, not the usual A4 paper printer you print the picking slips and delivery notes with so you must have configured that in mSupply first - see Printing preferences (setup) for details on how to do this. If you only want to print the dispatch labels and not a delivery note then select the None option in the Form to use drop down list.

The print Destination options:

  • Printer: the invoice will be printed out straight away.
  • Preview: a preview of what the invoice will look like when it is printed will be displayed in your installed PDF file reader. You might be able to print the invoice from the PDF reader, depending on its features.
  • PDF file on disk: the invoice will be saved to disk in PDF format.
  • Email PDF: the invoice will be created as a PDF file and attached to an email for you to send. You can double-click the email attachment to see a preview of the invoice. The email preferences in File > Preferences should be setup correctly before using this feature.
  • Export to Excel: the invoice will be exported as a spreadsheet file and opened for you (provided you have a spreadsheet application installed).

The recommended process for distributing your goods is this:

  1. Create the customer invoice (new or suggested status).
  2. Print the picking slip and give it to the staff who will pick the goods off the shelves.
  3. As the goods are picked, note down any discrepancies between what was actually picked and what was on the picking slip.
  4. When the pick is complete, enter any changes into the customer invoice in mSupply (Note that inventory adjustments or location adjustments of stock may be needed to correct issues found by the pickers). This step is very important to make sure your stock remains accurate in mSupply.
  5. Confirm the customer invoice when it matches exactly what was picked.
  6. Print the invoice again - this time a delivery note is printed.
  7. Send off your goods with the delivery note!

A note about picking order on picking slips

You can print picking slips by item name in alphabetical order (the default) or, if this does not match the way goods are stored in your warehouse, you can change the order to make the top-to-bottom picking order more efficient. Use location priority (see Locations and location types) and the printing preferences (see Printing preferences) to achieve almost any order you want to match the most efficient way of picking in your warehouse.

Entering a service line on an invoice

All “normal” customer invoice lines represent the issue of stock lines to a customer. (These lines appear in the large section in the middle of the “Customer invoice” window).

mSupply also allows you to charge a customer for “service” item(s) such as freight, or advice or a refundable deposit on a cool box.

Enter the description and amount at any time until the invoice is finalised.

Note: the “subtotal” amount on the invoice includes any service charges, and tax (if any) will be added to the amount you enter.

Editing tax on invoices

The tax rate on an invoice is determined by the “default tax rate” setting in the mSupply Preferences.

To edit the tax rate on an invoice, click on the tax rate box at the bottom of the invoice entry window. You will be asked to enter a new percentage tax rate. Click the cancel button if you do not want to change the tax rate.

Note: you can not change the tax rate on finalised invoices.

Confirm and Finalise the Customer Invoice

  1. Confirming the Customer Invoice changes its status to cn and takes the stock lines out of stock.
  2. Finalising the Customer Invoice changes its status to fn and prevents any further editing of the invoice. It makes no further change to the level of stock in your store.

If the customer is a store in your mSupply system then:

  • You MUST finalise the customer invoice for the stock to be transferred to the receiving store and for the receiving store to be able to process receipt of the stock. mSupply will prompt you for this when you click OK on a customer invoice with status = cn.
  • Finalising the customer invoice in your store will result in creation of a Supplier Invoice in the receiving (ordering) store.



Previous: 8. Issuing Goods | | Next: 8.02. Viewing customer invoices

8.03. Backorders

Overview

mSupply's backorder system allows you to record items you were unable to supply to clients, and (hopefully) supply them at a later date when you have enough stock.

When you do not have enough stock of an item that a customer orders, it is normal to add a placeholder line to the invoice you are creating. If you have local suppliers, it is possible you will be able to receive stock in time to fill the order, and the placeholder line can be edited and replaced with a normal stock line.

Once it is time to ship the order, placeholder lines will be converted to backorder lines, and you will be invited to enter a comment for each item (e.g. “We're very sorry- it's coming next week.)

Backorder preferences

The behaviour of mSupply in handling backorders is controlled by several preference settings:

  • To do anything at all with backorders, you need to choose File > Preferences and go to the Invoices 2 tab . There, check We run a backorder system

  • If you wish to have customer invoices automatically created when goods on backorders are received, the appropriate box should be checked.

  • On the same tab, check Allow placeholder lines on customer invoices . This allows you to use placeholder lines to record stock ordered by a customer but not able to be issued.

  • On the right side of the same tab is the option to Delete placeholder lines when confirming invoices. If this option is not checked, placeholder lines will be left on an invoice when it is confirmed. Otherwise they will be deleted. In either case, as long as the We run a backorder system option is checked, confirming an invoice will result in placeholder lines being transferred to backorders.

How much is on backorder?

There are four ways in which you can view backorders

  • When creating a customer invoice, there is a backorders button. This is described in detail below.
  • Use the backorders report to view some or all backorders.
  • When viewing details for a particular item, see all the backorders for that item on the backorders tab.
  • When viewing details for a particular customer, see all the backorders for that customer on the backorders tab.

Backorder management from the Customer invoice window

Clicking the Backorders button when viewing a customer invoice will show all lines for the entered customer that are on backorder.

The Backorders button will be hidden if ” We run a backorder system “ is not checked in Preferences > Invoices2.

If you are entering a new invoice, you need to have entered a customer name on the invoice before clicking the button.

The window also shows current stock, so you can easily see which backordered lines can be added to the current invoice

Buttons in the backorder window

New backorder: Placeholder lines are automatically changed to backorders when an invoice is confirmed, but there may be occasions when the manual entry of a new backorder is necessary: click this button to create one.

Delete backorder: You can delete an item line or multiple item lines by selecting the line(s) and clicking on Delete backorder button.

Modify line: This button is used to edit the item line. Select the desired line and click on Modify line button to display the following window.

Add lines to invoice

Highlighting lines and then clicking the Add lines to invoice button will (surprise) add the highlighted lines to the invoice. The backorder quantity will be set to zero, and may then be deleted.

Note that as you issue lines on an invoice, the quantity on backorder is automatically reduced. However, once a line reaches zero, it is not automatically deleted. This is because it is possble the user will delete or edit the line on invoice, and hence the reduction in backorder quantity may have to be reversed.

Backorder report

Choose Reports > Backorder report.

You can enter settings to reduce the scope of items or customers for which the report is produced.

The first drop down list allows the report to be filtered by many options, but note that if Item name is chosen, then the full name must be entered and not just partial details.

Two options are available: for display:

  • each customer and the items on backorder for that customer
  • each item and the customers having backorders for that item.

Note that this report does have limitations, as if a customer orders the same item more than once, it is likely that demand will be overstated.

Viewing backorders for a customer or an item

Clicking the backorders tab when viewing a customer or item details shows a window where you can view or edit items on backorder. The example shows backorders for an item, ibuprofen 200mg tablets.

Notes

  • If you have set the preference to leave placeholder lines on confirmed invoices, then you can use the Item ordered shortfall report to display the difference between customer demand and what was actually supplied.

Automatic creation of customer invoices for backorders

With the required boxes checked under Files > Preferences > Invoices , mSupply will automatically create invoices for those customers having items on backorder when the items are received from suppliers.

This description is illustrated by the situation in which two customers, Urban Clinic and Rural Clinic both have Promethazine 25mg tablets on backorder - Urban Clinic awaiting 5 x 100, and Rural clinic awaiting 2x 100. The supplier is Arbuckle.. This may be confirmed by previewing a backorder report:

On receiving the goods from the supplier, a new goods received record is created in the usual way, and finalised. When you click on OK to create the supplier invoice, you are required to confirm your intention to finalise the order, which you would normally do. The supplier invoice is displayed, and in the bottom left corner of the supplier invoice, you will see that the Hold box is checked. You should click on it to remove the check mark.

and this alert message is displayed:

Review the invoices as alerted, and for this example the invoice generated for the Urban Clinic is shown:

The invoice generated has all the relevant details, e.g. batch no., expiry, etc., copied across from the supplier invoice, and the comment has been added to the effect that the invoice has been generated automatically, and also identifies the Goods Received ID:



Previous: 8.02. Viewing invoices | | Next: 8.04. Electronic invoices

8.07. Stock control methods for your customers (requisitions)

Stock supply philosophy

mSupply is designed for situations such as a central supply facility within a country or region, or within a hospital where the supply of stock to customers is controlled by the supplying facility. That is, supply of stock to customers is managed by the supplying store.

Regardless of who controls the supply of stock, it needs to be made principally on the basis of information about the customer's anticipated usage. mSupply has several ways of arriving at quantities to be supplied to customers, in rough order of sophistication:

  • If there is NO information from the customer about item usage (AMC) or stock levels, then the supplying store can only 'push' stock to the customer by Creating a new Customer Invoice with quantities derived from some other sources.
  • If the customer has sent an 'order' or 'requisition' for stock, containing just the quantities of each item required, then the supplying store can at least be informed by these quantities when preparing the Customer Invoice.
  • The imprest method is common in hospitals where the customer can provide the current Stock on Hand (SoH) and there is a long and relatively stable track record of item consumption, from which 'Imprest values' have been calculated manually, outside of mSupply.
  • The stock history method is similar to the imprest method, but lets mSupply calculate the 'imprest values' automatically.
  • Response requisitions is more accurate method for cases where the assumptions required for the imprest and stock history methods are not correct.
  • Full Entry of Request & Requisition Forms by the Supplying Facility is an enhancement to the standard response requisition method. This feature was developed for Côte d'Ivoire but can be activated for any country on request.

With the exception of the 'Push' method, collectively, these are grouped together as different types of requisition. When editing an item, you can view all types of requisition records for that item. More information is available on the requisitions page (if you can think of better names, please tell us!).

Please note that it is possible for all of these to be done by programme if required - see the 4.05. Programs page for details.

Defining the list of items to be included in the re-supply

The lists of items that a customer can receive can be dfined by master lists.

See the 4.04. Item master lists page for information on managing master lists and see the Assigning a list to a customer section for how to assign a master list to a customer.

Viewing existing requisitions

Choose Customer > Show requisitions… from the menus or click on the Requisitions icon on the Customers tab of the Navigator:

This window will open, showing you a list of the requisitions already in the system:

Columns in the table:

  • ID: Unique identifier of the requisition.
  • Name: The name of the customer the requisition has been entered for.
  • Date entered: The date the requisition was first saved in mSupply.
  • Requisition date: The date the requisition as given by the customer.
  • Status: The status of the requisition (sg, cn, or fn nomally, web requisitions can also be wf or wp).
  • Type: The type of requisition; sh for customer stock history, im for imprest or response for a response requisition.
  • Comment: The comment entered on the requisition.

Buttons and fields in the window:

  • Show drop down list: Use the Show drop down list to filter the requisitions by status.
  • Search field: If the list of requisitions is too long to find a particular requisition you are interested in then you can type something in the Search field. If you type anything in the Search field, only requisitions with a customer name, requisition number, program or comment that contain what you typed will be displayed.
  • New XX buttons: To create a new requisition of a particular type (see below), click on the appropriate button - a new, blank window will open ready for you to enter the requisition.
  • Delete button: To delete a requisition, click on it in the list to select it then click on the Delete button. You will be asked to confirm the deletion before it is carried out. Please note: You cannot delete a requisition if a customer invoice has been created from it - mSupply will tell you if this is the case. You can still delete the requisition but you must delete the customer invoice first.
  • Finalise button: This button allows you to finalise multiple requisitions at once. Simply highlight a selection of requisitions in the list and click on the button. Only Confirmed status requisitions will be finalised; requisitions of any other status will be ignored. After finalisation has been carried out you will be told how many were successfully finalised and how many couldn't be updated because they weren't confirmed or because they were in use by someone else.

To edit a particular requisition, double-click on it in the list. A window will open, populated with the requisition's details; the window will be different depending on the type of requisition (see sections below).

Stock history method

The theory behind the stock history method (sometimes referred to as the Historical Logistics Method) is based on the assumption that future customer usage will be similar to historic usage.

We can calculate the customer's average usage over time if we know their stock levels at two points in time, and what stock they received from us in that intervening period. We assume that this average usage rate will continue over the coming supply period.

There are three more variables that need to be estimated:

  • The number of months in the coming supply period
  • The lead time required to supply them (that is, the time lag between the customer doing a stocktake in order to trigger re-supply, and receipt of the stock)
  • The number of month's worth of buffer stock they need

With this data, the calculation is like this:

  • A = Stock on hand on date1
  • B = Amount supplied to customer between date1 and date2
  • C = Stock on hand on date2
  • D = Quantity used in period between date1 and date2 = A+B-C
  • E = number of months between date1 and date2
  • F = Usage rate = D/E
  • G = Number of months in coming supply period
  • H = Number of buffer stock months desired
  • I = Lead time (months) between date2 and delivery of stock
  • J = Amount to supply = F*(G+H+I)-C

Using the stock history method:

  • A and C are reported by the customer on date1 and date2 respectively
  • B is calculated by mSupply based on mSupply records
  • G, H and I are entered by the user
  • D, E, F and J are calculated by mSupply

mSupply uses stock issued by the supplying store to arrive at the parameter B.

Obviously, if the customer has received goods from other sources during the calculation period, B will be inaccurate!

First stocktake record

In order to calculate the usage rate, mSupply requires stock on hand figures of the items on the list recorded on an earlier date (date1) = A, above. This becomes the initial stock history record.

To create such a record, follow the procedure described below for entering a stock history, noting particularly, the following:

  1. Enter the date as the correct date at the time the stocktake was performed.
  2. Ignore the figures that automatically appear along each row, except for the Their current stock column.
  3. Enter their current stock figures in the Their current stock column
  4. Close the window using the OK button.
Regular use

Once your customer's first stocktake record has been entered, and a period of time has passed with some customer stock usage, re-supply can be be generated on the basis of this usage.

A re-supply using the stock history method needs to be triggered by a customer stocktake. If your customer is set up with mSupply customer web interface, then this process can be initiated by the customer directly, and then completed in the supplying store as described below.

If your customer has not used the mSupply customer web interface to report their stocktake, then their stock data needs to be entered in manually to the supplying store.

Manual entry of customer stock history

To begin the process, choose Customer > Show requisitions, and the list of any historic customer stock histories is displayed along with the other requisition types. The Status column lets you know the status: sg (suggested) or cn (confirmed). The Type column shows the stocktake type: im (Imprest), sh (Stock History) or response (Requisition):

Double-clicking on a line will allow you to edit the selected record (provided that you have permission to do so).

With the passage of time, entries on the list will rapidly grow in number, and so mSupply allows you to apply a filter selecting exactly what will be displayed. The default display is for Suggested, as these are most likely the ones you will be processing; other options include All, Confirmed, Web entries to be processed - this covers histories submitted via the web customer interface - and Entered today

Add new customer stock history

Click the New customer stock history button, to display the Enter new customer stock history… window:

Enter the first few letters of customer's name in the Name field, then press the Tab key to call up the list of customers' names from which the required customer may be chosen. In this example, our customer is Medical Ward.

Once you have chosen a customer, the window is populated with the items that are members of any item lists that:

  • Have been assigned to that customer (both master lists and local lists)
  • and that have the “Stock history” check box checked for that list

You are presented with this window:

Fill in customer stock history

The Our SOH column is the stock on hand in our own store, while figures in all subsequent columns are the customer's data.

The first entry to be made is in the Days to supply field, where the appropriate figure should be entered - e.g. 30 if the ordering frequency is monthly, 90 if it is quarterly, etc.

You will see in our example that

  • 29 days have passed since the last stocktake
  • The column headed Their old SOH shows their stock on hand at the last stocktake
  • The column headed They received shows the amounts supplied when their last order was processed
  • The column headed Their current SOH is the column where the customer's current stock figures (as provided by the customer) are entered. But note that, just as with the imprest method, if the name you entered in the Name textbox is actually another store then this column will be automatically filled in with the current stock in the store - saving you a lot of time (you only need to edit those figures where the stock in mSupply does not actually match what's on the store's shelves).
  • As figures are entered, mSupply® calculates a suggested quantity to order, and this appears in the Suggested quan column. These suggested quantities should be reviewed, and any adjustment entered in the Actual quan column to reflect, for example, pack sizes and to ensure that actual quantities match exact multiples of the pack size.

After entries have been made in the column Their current SOH the window will look like this:

All that remains is to make adjustments in the Actual quantities column, to reflect appropriate pack sizes.

Once you are satisfied, the Confirm box (bottom left corner) should be checked, the Create customer invoice button should be clicked, and you will proceed to creating the customer invoice, which is the same for all requisition types.

Printing forms

Clicking the Print button provides several options for printing forms:

  1. Customer stock takes: This form you can give to the customer (for example, if they are a ward in a hospital that has mSupply running in it's pharmacy store), and they can fill out the quantities they have on hand, and then values are entered into mSupply.
  2. Customer stock supply: This form provides information to give to the customer about the quantity they will be supplied.
  3. Customer stock request and issue: This form provides information for the customer comparing what was requested with what was actually supplied.

The second two reports are for use after you have entered quantities to be supplied into the customer stock history window.

Imprest method

The Imprest method is probably the most commonly understood and used method of stock control, and has been used for many years, probably since before the invention of the computer!

As can be seen by the discussion below, the Imprest method is a simplification of the Stock History method discussed above. We argue that the Stock History method is superior to the Imprest method because it dynamically calculates a number of values based on live customer consumption data, rather than relying on some historic calculation that is likely out of date. It is quite understandable why the Imprest method is the standard approach in hospitals - because it was developed before the computer age, and its hard to change old habits. However, now that you have mSupply ready to do the number crunching, we suggest that you seriously consider using the Stock History method instead of the Imprest method… :-)

With the Imprest method, the quantity to be ordered is the quantity necessary to restore the stock on hand to a pre-agreed fixed quantity. This imprest stocktake must be carried out on a regular fixed frequency (daily, weekly, fortnightly, monthly, whatever.) This pre-agreed fixed quantity is arrived at on the basis of a number of simplifications to the stock history method:

  • A = Stock on hand on date1
  • B = Amount supplied to customer between date1 and date2
  • C = Stock on hand on date2 THE ONLY INFORMATION COLLECTED
  • D = Quantity used in period between date1 and date2.
  • E = number of days between date1 and date2
  • F = Usage rate PRE-DETERMINED AND FIXED
  • G = Number of days in coming supply period PRE-DETERMINED AND FIXED
  • H = Number of buffer stock days desired PRE-DETERMINED AND FIXED
  • I = Lead time (days) between date2 and delivery of stock = 0

The Imprest Quantity = F*(G+H+I)

  • J = Amount to supply = Imprest Quantity -C

If stocktakes are not taken at the pre-determined frequency, and particularly if they are missed, the system will fail. It is a fairly rigid system, in that once set, F, G and H must remain constant. It is frequently used for supplying wards in a hospital setting, where operations are generally more rigidly controlled.

Using the imprest system

The imprest system operates in this way:

  • The stock of a particular item which a customer (usually a clinic, ward or department) should hold is agreed. This is the Imprest quantity.
  • A stocktake is carried out at the facility, giving us a Stock on hand.
  • The amount to be ordered by the facility is calculated as:

Order quantity = Imprest quantity - Stock on hand

For example, take the case of a rural clinic which receives a monthly order from a central store:

  • It is agreed that the clinic, when fully stocked, should hold 10,000 paracetamol 500mg tablets. This is the Imprest quantity.
  • At the end of a particular month, a stocktake shows that the Stock on hand is 2,400 paracetamol tablets.
  • To restore the stock of paracetamol tablets to the Imprest quantity, the amount to be ordered is calculated as:

Order quantity = 10,000 (Imprest quantity) minus 2,400 (Stock on hand) = 7,600

This feature caters for mSupply users who operate an imprest system, where a central store supplies goods on a regular basis to a number of customers, who may/may not be mSupply users themselves. We advise that the customers should be provided with a list - perhaps for a 12 month period - of the dates on which they should perform a stock check and submit the figures, ideally on a customised form, to the central store acccording to the prearranged schedule. It is important to note that the customer needs to supply only the current stock on hand figures, a relatively simple task; customers are not required to submit details of what they perceive to be order quantities.

It should be remembered that the items to be included in the list and their imprest quantities must be defined for each customer individually. The imprest quantity defined for a particular customer is unique to that customer, and has no bearing on imprest quantities defined for other customers.

Processing the order from the customer

The central store, on receiving the stock on hand details from the customer, selects from the Navigator or Customer menu the item Show requisitions, which displays this window:

If you are working with a customer for whom no imprest list has been defined, clicking on the New customer imprest will display the Enter new imprest window, where appropriate entries are made.

Continuing to use Highland Health Centre as our example (for whom we have created an imprest list), double clicking on that entry displays this new window on which the imprest list appears:

You will note that there are no entries in the Their current stock column, and the figures supplied by the customer should be entered; click on each line, and after a second or two the zero appearing in that column can be edited with the required figures.

There is an important exception here: if the name you entered in the Name textbox is actually another store in mSupply then the Their current stock column will be automatically filled in with the stock in the store. Very useful time saving feature!

Simultaneously, mSupply completes the next two columns, Suggested Quantity , and Actual Quantity. The Actual Quantity entries may be edited to reflect, for example, pack sizes, to ensure that actual quantities match exact multiples of the pack size. After editing, the window may appear like this:

Should you have any reason to identify one or more lines, this may be performed by highlighting the line(s), and changing the colour of the font. Black is the default, but other options may be selected from the drop-down list:

Selecting 5 or more lines brings up an alert requiring confirmation of your intention.

Once you are satisfied, the Create customer invoice button should be clicked, and you will proceed to creating the customer invoice, which is the same for all requisition types.

Response (internal) requisitions

These work in much the same way as customer stock histories, but with some notable differences:

  • Most importantly, you don't need to create it! A response requisition will be automatically created in your (supplying) store as a result of a request requisition from an mSupply mobile (see here for details) or an internal order from another store (e.g. on another mSupply 'desktop' site). In both of these cases, the customer is another store in your mSupply system and most of the data will have been entered already by them. You can create one manually if you need to though, as we'll describe below.
  • It doesn't attempt to calculate usage or suggest an amount to supply - this data is expected to have come from the customer.
  • It is possible to generate multiple customer invoices from a single response requisition e.g. if not all of the requested stock is available at the time the requisition is entered, this allows for an initial customer invoice to be sent to partially fulfil the request and another to be sent at a later date when more stock becomes available.
  • It provides a more accurate way to track demand vs supply.
Entering a requisition

To begin the process, choose Customer > Show requisitions, and the list of any historic response requisitions is displayed along with the other requisition types. A Status of sg (suggested) means that no customer invoices have been created yet - as soon as the first customer invoice is created, the status will go to cn (confirmed). The list looks like this:

  • Show drop down list: Set to Past 30 days by default which will show requisitions created in the last 30 days. You can select other options to show thiose with a particular status or entered in different time periods.
  • Type here to search field: If you type in here, requisitions for customers with names containing what you type only will be displayed. A good way of finding a particlar requisition if the list is long.

Either double-click on a requisition in the list to edit it, or click the New customer requisition button to create a new one. The example below is for a manually entered requisition:

If this is a manually entered requisition:

  • Enter/update the customer Name in the same way as a customer stock history (i.e. enter the first key characters and hit the Tab key to find matches), but note that changing the customer will invalidate any other data that you've already entered.
  • If necessary, update the Requisition date, Order received and Required date - these will default to the current date.
  • Select a Category if required (see below for setting these up).
  • Use either the New line button to manually add a single item, or Add from master list to add all items from a master list.

When you click on the Add from master list button you will see a list of all the master lists assigned to your store and your customer (see the 4.04. Item master lists page for details on master lists and how to assign them). Whichever master lists you choose to add items from, only the items visible in your customer's store will be added to the requisition. This will avoid the situation where you send a store an item that they didn't previously have visible to them!

  • If the customer is another store, mSupply already knows their current stock, otherwise adding a single item will give you the opportunity to enter the customer's current stock for that item. Either way, the cursor will go into the Customer current stock on hand cell, which will already be filled in.
  • If adding from a master list, the cursor will go into the first new item's Customer current stock on hand cell, but you'll then have to type in a value (unless the customer is another store, in which case the value will have been filled in for you).
  • Either way, hitting the Tab key will move the cursor into the Customer requested cell. Type in a value and this will be automatically copied to the Remaining to supply cell and also the Supply this invoice cell, which will now have the cursor.
  • Amend the Supply this invoice value if necessary and optionally enter a Comment (e.g. if the amount supplied is less than requested).
  • If necessary, use the Delete line(s) button to remove selected item lines.

If the requisition has come in automatically from another store (e.g. mobile or an internal order):

  • The customer Name is already filled in and cannot be changed.
  • The Customer current stock on hand and Customer requested columns are already filled in and cannot be changed i.e. only the Supply this invoice and Comment columns are editable.
  • If necessary, you can still add and/or delete item lines manually.

If the requisition has a lot of item lines, you can filter them by typing into the Filter items field. If you do that, only the lines with items beginning with the letters you have typed in the field will be displayed. The text X/Y will be displayed after the search field to indicate that X lines of the total Y lines in the requisition are currently being displayed (2/8 in the following screenshot):

Note that, while a filter is active, some of the other buttons are disabled e.g. you can't create an invoice or save the sort order unless all lines are visible. To make them active again, simply delete any text in the Filter items textbox (which will remove the filter).

Once you are satisfied, the Create customer invoice button should be clicked, and you will proceed to creating the customer invoice. The Supply this invoice values will be used to populate the new customer invoice and the requisition status will change to confirmed.

Finalise Checkbox

Clicking on the “Finalise Checkbox” finalises the requisition form. After this no changes can be made.

Finalised requisitions will no longer appear on reports that show “Remaining Quantities” as pending. Finalised requisitions are be considered as fully processed.

Reference documents

The Reference documnents tab on a requisition enables you to save documents and other files relating to the requisition. The tab looks like this:

The table shows you all the files currently uploaded to this requisition.

  • Upload document button: Click this to upload a document ot the requisition. This will open a window enabling you to search for and select the file on your computer. After you've selected it, click on the Open button to upload it. If you upload a file with the same name as one already uploaded, mSupply will upload it as a new version of the already uploaded file.
  • Delete document button: Select a file in the table by clicking on it and click this button to remove it from the requisition.
  • Download document button: When you click on this button you are presented with two options:
    • Download: this will download the file to a location you select on your computer.
    • Download and open: this will download the file to a location you select on your computer and then attempt to open it using the default application on your computer for that file type. If there is no application associated with the file type on your computer then mSupply will tell you that the file could not be opened.
Requisition categories

You can assign requisitions to a category for reporting. To setup the categories that users can select from, choose Special > Requisition categories from the menus. This window will open:

This window shows a list of all the requisition categories currently setup. The ones with a tick in the Is active column are the ones that can be selected on a requisition. If there is a long list then you can type in the Type here to search field to show only categories that contain what you type.

To add a new category, click on the New button. This window opens:

Enter a Description, click the OK button and the new category is added to the list.

To edit a category, double-click on it in the list and the same window as creating a new one will open but populated with the selected category's settings. Edit the category's name or the active status and click the OK button to save your changes.

You can quickly set a category as inactive (which means that it will no longer appear in the drop down list for selection on a requisition) by selecting it in the list and clicking on the Set inactive button.

Requisition status

Summarising from above, the status of the requisition has the following meanings:

  • Status = sg (suggested): No customer invoices have been created yet
  • Status = cn (confirmed): At least one customer invoice has been created from the requisition
  • Status = fn (finalised): No changes can be made to the requisition. It will no longer appear on reports that show “Remaining Quantities” as pending. Finalised requisitions are be considered as fully processed.

Creating the customer invoice

Regardless of the requisition type, when the Create customer invoice button has been clicked, and the following window appears:

If the customer invoice has been generated from an original internal order in another store, the customer invoice window will have a red Stock transfer label.

Similarly, if the customer invoice has been generated from an original internal requisition in another store, the customer invoice window will have a red Internal requisition label.

All the entries appear as (red) placeholder lines. The operator needs to allocate stock to each of these placeholder lines before a pick list can be printed. The operator can either manually allocate stock or by using the Grinder button.

Manually allocate stock

The next step is to double click on each entry and allocate stock. In the example, the 1st item on the invoice, Ibuprofen 200mg tablets, is being processed; there are several batches in our store, some of which have reached their expiry; although line 4 indicates there are sufficient to meet this order in the store, you will note that only 106 tablets are available, so we select line 6.

Clicking on OK & Next displays the next item on the invoice, Prednisolone 5mg tablets.

Click Redistribute all, which is the normal procedure. There is only one batch available, but there is insufficient stock to meet the order, so mSupply® creates a placeholder line for the outstanding amount.

When the final item has been processed, clicking on OK will display the completed invoice.

The Grinder button

If your store is organised well, particularly by use of location priorities, you can automatically allocate stock to all placeholder lines by use of the grinder icon at the bottom left.grindericon.jpg

issuestock.jpg


Make sure the Hold checkbox is not checked, and at this stage the invoice may be confirmed.

If the customer invoice is for another store (i.e. if it has a red Stock transfer label or red Internal requisition label), it must be finalised in order to transfer the goods to the other store:

After creating a customer invoice

  • The Already issued column will be updated to reflect any non-placeholder lines (i.e. those not coloured red in the customer invoice) in any customer invoices which have been generated from the requisition regardless of the customer invoice status (i.e. it doesn't have to be confirmed).
  • The Remaining to supply column will be reduced by the amount already issued, and Supply this invoice will be updated accordingly:

In the example above, a single customer invoice has been created to supply most of the requested stock, apart from two items. You can then create a second customer invoice to supply the outstanding amounts.

Details of the related customer invoices can be seen in the Invoices created tab:

Double-clicking on any of these lines will open the corresponding customer invoice.

Danger of failing to re-supply in time

Obviously, regardless of the calculation method employed, if the supplying store fails to re-supply the customer within the supply period (G) then the customer will start eating into the buffer stock and is in danger or running out of stock!



Previous: 8.06. Box management | | Next: 8.08. Customer budgets

8.05. Transferring goods to another store

This feature is available only to those users who are managing more than one store in their mSupply system e.g. a central warehouse that supplies district or regional warehouses, or a general store for holding stock and you supply a dispensary with their day to day needs - see Virtual stores.

Create a Customer Invoice

If you're not able to perform a transfer, there are several possible reasons:

  • The customer you're trying to use is not set up as a store in your copy of mSupply.
  • You don't have the user permission to perform transfers.
  • The store you're transferring to is not visible to the store you're logged into. To make it visible choose Special > Show stores and double-click the store you want to transfer to, then on the preferences tab click the View name button and set the visibility on the Stores tab.

This procedure follows closely the steps as described under Issuing Goods to a Customer (Customer Invoices); to avoid unnecessary repetition, please make sure you are familiar with that procedure.

You must be logged in to the issuing store (the store you're transferring stock from); the 'customer' in this process is the receiving store. So, you create a new invoice from the Customer menu, and in the Name field you put the name of the receiving store in the normal way (i.e. type the first few letters of the store's name, press the Tab key on the keyboard, and select the store in red colored text from the list displayed)

As soon as you select the receiving store name a red Stock transfer label confirms that you are creating a stock transfer:

The procedure from this point is identical to that described under Issuing Goods to a Customer (Customer Invoices).

Need to finalise Customer Invoice

It is necessary to finalise the transfer when you have finished entering the items to be transferred. Only after finalising the transfer will the new invoice appear on the system, as a supplier invoice in the receiving store, linked to the customer invoice in the issuing store. The status of the supplier invoice in the receiving store will either be confirmed and on hold or finalised, according to the setting you have for the “For stock transfers, the supplier invoice in the receiving store should be…” store preference. See here for details.

If you confirm the stock transfer but do not finalise it, you will be shown a warning if you try to close it, just in case you have forgotten the finalise step: If you did forget to finalise it then click on the Finalise button and mSupply will finalise the invoice for you (and create a supplier invoice in the receiving store). If you want to keep the invoice at confirmed status (and not create the supplier invoice in the receiving store) then click on the Leave as confirmed button.

Visibility of items in both stores

If the item(s) you are transferring are not visible in the receiving store the following message will appear: Check whether there is any reason for the item(s) in question not to be visible in the destination store. If there is no reason to prevent visibility click OK.

If you are running a syncing system (see Remote Synchronisation) and the receiving store is active on another site, the receiving site will send back a confirmation log message to confirm that it has received the transfer. This will show up in the Log tab of the sending customer invoice.

On a syncing system, the sending site does not have access to the item visibility records in the receiving store if it is a transfer store, so it cannot do the item visibility check above. In this case, the primary server will automatically make the items visible in the receiving store when it receives the transfer.

Reversal of stock transfer

Should a reversal of a stock transfer be necessary, this may be achieved by the operator at the sending store, and only if the receiving store has not issued any of the transferred stock.

Receiving the goods (customer store)

When a Customer Invoice (CI) is created and finalised (see above!) in a Supplying store, a Supplier Invoice (SI) will be automatically generated in the customer store. You can view the customer invoice via the Suppliers tab on the Navigator or via the Supplier > Show invoices… menu item:

  • Double-click on any supplier invoice in the list to open it.
  • On the supplier invoice, the lines from the customer invoice will have been filled in automatically.

For instructions on processing the stock from the Supplier Invoice in to your store, refer Processing supplier invoices



Previous: 8.04. Electronic invoices | | Next: 8.06. Box management

8.02. Viewing customer invoices

To view or edit any customer invoice, choose Customer > Show invoices from the menus or click on the Show me a list icon in the Customer invoices section on the Customer tab of the Navigator:

Find transactions window

You will be presented with this window:

If you just press Enter, that is the same as clicking on the OK button, and it will display a list of the 15 most recent invoices.

Click on the drop down list on the left to display the options available for determining which field to query:

Choose the comparison from the next drop down list (equals, starts with etc.)

The comparison popup menu will change depending on the type of field you have chosen in the first list.

Enter any values that you want to query against in the field at the bottom right.

Some examples:

If you.. Transaction(s) Displayed
Type 1 and press Enter You will be taken directly to the most recent invoice entered
Type 25 and press Enter A list of the 25 most recent invoices
In the lower, right field, type 123 Invoice number 123 will be displayed.
Click on the invoice number dropdown button and select one of the other search filters (e.g. Name)
Click on the equals dropdown button and change it to, say Starts with
Type the first few letters of the name of a customer, e.g. maj and press Enter 		A list of all customer invoices to customers whose names start with maj (this is not case sensitive)

This window is very useful for quickly finding a group of invoices. If you'd like the challenge of engaging with mSupply's data structure, you can query on multiple criteria. Click on the Complex Find button, which takes you to the Query Editor, which has powerful features to perform queries with multiple conditions. Detailed guidelines for using the Query Editor are to be found in Working with lists

The list invoices window uses the Transactions list window, which looks like this:

Note. All of the columns may be adjusted in width to meet your requirements; for the screenshot above to fit on the page, most of the columns were reduced in width.

Dynamic filter

Down the left side is a sidebar, with 6 headings:

  1. Types
  2. Find…
  3. By date
  4. By status
  5. My transactions
  6. My custom filters.

You can click on them and some of them will expand to show sub-headings (and contract to show just the heading if you click them again). This is what the bar looks like when it is first shown, with the Types heading expanded and all the others contracted:

The Find… option does not expand but shows the Find Transactions window again when clicked.

Once the type of transaction has been selected, it remains selected while you further refine the required criterion from one of the four remaining headings, By date, By status etc. Be aware that a single criterion only from this group of 4 headings may be selected.

At the bottom left of the window you'll notice there are 3 numbers separated by slashes, “1/15/67” in the example above. These numbers, in order, are the number of highlighted rows, the number of found rows, and the total number of transactions in the database.

Selecting multiple tansactions

Once you have a list which includes the transactions you are interested in, you may wish to carry out certain actions (described below) on more than one of them. To do this, control-click (command-click on Mac) the lines you wish to highlight.

Buttons

Along the top of the window are these buttons:

Their functions are:

Find

Click on this button to bring up the Find Transactions window again.

Sum

Click on this button to display the total value of the highlighted invoices. Highlight more than one invoice by control - clicking (Mac: command-clicking) invoices. Highlight a block of invoices by clicking on the first invoice of the series, then shift-clicking on the last invoice in the series.

Order by

The invoices displayed may be sorted according to any of the columns by clicking the column heading. A more comprehensive sort facility is available when you click the Order by button. This displays the order by window, where you can drag fields from the list on the left to the right-hand pane to sort the list by the fields you have chosen.

Print

Click on this button to print the list of invoices displayed. This does not print the actual invoices, just a list of them.

Finalise

Only users with Finalise permission will be able to do this action. Click on this button to change the status of the invoice to finalised.

mSupply also has a Bulk Finalise feature

We can bulk finalise normal invoices; however, this functionality is not available for invoices related to stock transfers. To finalize “stock transfer” invoices, you must open each specific invoice and finalize it individually. As stock transfer involves distributing physical stock to your client stores, this action cannot be un-done easily. Hence mSupply will expect you to finalise the invoice after careful consideration.

When performing a bulk finalise, all selected normal invoices will be finalised. However, the following types of invoices will not be finalised:

  • Stock transfer invoices. (read above)
  • Invoices that are on hold.
  • Invoices that are not confirmed.
  • Invoices containing only placeholder lines.
Duplicate

Click on this button to duplicate the transaction. You would use this feature, for example, to supply exactly the same items to another customer. You will be asked if you want to duplicate all lines on the invoice, or just the placeholder lines.

If the invoice was part of the internal requisition process (from one virtual store to another) then the links to the originating purchase order will be maintained, and a goods receipt will be created if you finalise the customer invoice at a later date.

Please note: you are not allowed to duplicate some transactions such as payments, cash receipts and any type of cancellation transaction (an “inverse” transaction created to cancel another).

Cancel

Click on this button to cancel the highlighted transaction 11). This command only works on finalised invoices. The invoice is not deleted from the system; mSupply makes a duplicate finalised invoice with the same invoice number but with negative quantities matching those on the invoice you're cancelling. This ensures that all transactions are preserved and will appear in an audit trail. But note that you will not be able to cancel a finalised customer invoice which put stock into mSupply and some of that stock has been used. An exception to this is a stock transfer: if none of the transferred stock has been issued then the original finalised customer invoice which initiated the transfer can be cancelled if the supplier invoice produced from it is first deleted.

If you have accidentally finalised a transaction you can use the cancel and duplicate buttons to

  • Highlight the finalised invoice and click Cancel
  • Hightight the finalised invoice again and click Duplicate to duplicate the original transaction
  • You can then edit the duplicated transaction to the correct values before finalising it again.
Filters

Click on this button to apply filters to reduce the volume of information displayed to reflect more precisely what you require.

Take as an example, a hospital where you have searched on a large number of customer invoices, but you are really only interested in issues to the Orthopaedic Clinic during the first six months of a year.

Clicking on the New Filter icon presents you with a window where you can define the criteria for your filter, in our case the customer's ID is entered, and the period under review - i,e, January to June 2009 using the syntax of a WHERE clause in SQL

The Respect selected invoice type checkbox has the effect of applying the filter to the type of invoice which has been selected in the sidebar, and if we do this in our example, instead of displaying several hundred invoices, only the handful of invoices for the Orthopaedic clinic will be shown.

Any filters so created are listed under My custom filters , and are available for use as required until they are deleted.

Customise

This button allows you to change the columns of information that appear for you when this window is displayed in future. Please note that this same window is used to display a list of different types of transactions, not just customer invoices.

The button also allows you to change the order the columns appear in the list.

Display the information you require

When you click on the Customise button this window opens:

Displayed under Available on the left are the available fields (these columns are all hidden), while displayed under Chosen on the right are the presently selected fields (these are the ones that are displayed).

To add a column to the display, click on the required one to select it in the Available column, then click the upper button between the two displays, and it will appear at the bottom of the Chosen list.

The Program column (shown in the Available table in the above screenshot) will show which customer invoices belong to which programs (obviously, the column will be empty if the customer invoice doesn't belong to a program because it was not created from a program based requisition).

mSupply provides the feature of analyzing customer invoices by their despatch/delivery/arrival dates. Once a customer invoice has delivery dates entered for it, Transport details, choose the customer delivery columns 'Order written', 'order received', 'dispatched', 'expected arrival', 'actual arrival' to be included in your transaction list:

This list shows customer invoices in mSupply ordered by Expected Arrival Date. Click on the column header to order on that column (as with nearly any column in mSupply).

Arranging column order

This is done by clicking then dragging the column heading to the required position in the Chosen table. The highter it is in the table, the further left it appears in the transactions list window.

Sorting the list

Click a column heading to select it, then click on the small triangle on the right to display the list in order or reverse order as required. This is the same for nearly all column headers throughout mSupply.

Modify

Click on this button to edit the selected invoice. This is the same as double-clicking the invoice.

Export to MYOB

Click on this button to export the selected invoices to the MYOB software - refer to Exporting to MYOB.



Previous: 8.01. Issuing goods to a customer (customer invoices) | | Next: 8.03. Backorders

11.01. Payments to suppliers

Updated: version 3.1

The best practice payment flow is diagrammed below. These steps ensure accuracy is maintained and payments are made for the correct amounts based on the actual goods received.

mSupply can be used to record payments that you have made to suppliers for goods received from them. To do this, you need to activate the payment module in the preferences (Invoices 1 tab, 'Activate supplier payment module' check box) first.

  • Any Supplier Invoice that is finalised after the Payments Module is activated will have its amount outstanding recorded (the amount left to pay to the supplier). Payments can then be entered against those Supplier Invoices.
  • Therefore, it is important to finalise any Supplier Invoices that have already been paid before the Payments Module is activated. Any Supplier Invoices finalised before the Payments Module is activated will have their amount outstanding set to zero, and so will not show for payment. Use the File > Finalize supplier invoices command to finalise all invoices. Or, view invoices (Suppliers > Show supplier invoices) and finalise them individually once all the details are correct.
  • You cannot pay a supplier more than the total outstanding (as if you'd want to!). This is different to a cash receipt, where you can accept an overpayment from a customer.

Entering payments

To enter a new cash payment, choose Supplier > New Cash Payment from the menus (or click on the icon in the Payments section on the Suppliers tab of the navigator to be shown the new cash payment window:

The table of invoices you can enter a payment against is populated with all the finalised invoices in the store you are currently logged into (in all currencies).

Entry steps
  1. Enter the supplier name or code in the Name field. Once you have chosen the supplier, a list of finalised supplier invoices for that selected supplier that still have an amount outstanding will be displayed.
  2. Enter a comment about the payment in the Note box. If you leave this blank mSupply will automatically create a note containing a list of the invoices the payment is paying off.
  3. Select the currency you want to pay in. You can only enter payments in one currency at a time so all those invoices that are in a different currency to what you have selected will be greyed out in the list and you will not be able to enter a payment amount against them.
  4. The rate stored in mSupply for the particular currency you have selected is displayed in the Rate box. If you wish to use a different rate (e.g. the rate you know the bank will use ) you can change the rate to match it (and the calculated payment amounts will be updated automatically). Note that the rate is set to 1 and is unchangeable if you have selected your local currency.
  5. Enter the total amount you wish to pay in the Payment box and click the Distribute button. This will distribute as much of your payment as it can among all the outstanding invoices in the currency you selected, in the order they appear in the list. If there is any left over it will be shown in the To allocate box.
  6. Alternatively, you can shift-double-click each non-greyed out invoice to pay the full amount of that invoice. (Note that shift-double-clicking toggles between allocating nothing and full payment against an invoice). A quick way to find out the total outstanding amount for a supplier in the selected currency is to shift double click all the non-greyed out invoices. The total will then be displayed in the Allocated amount.
  7. To partially pay an invoice you can double-click it's line and enter the amount you wish to pay.
  8. If there are any local charges that need to be added onto the payment, they can be entered after you have allocated the full amount entered in the Payment box to invoices.
  9. As well as adding in local charges you can edit the total amount of the payment in local currency if needs be so that the actual payment amount matches your bank records (such a situation might arise if your bank uses a different currency conversion rate to that stored in mSupply® but you don't know what it is).
  10. Once you are happy with the details, click the OK or OK & Next button. If you want to print the information, make sure the print checkbox is checked.
  11. Note that the OK and OK & Next buttons will remain disabled until the Payment amount is non-zero and the To allocate amount is zero (i.e. a payment amount has been entered and has all been allocated to invoices).

Viewing cash payments already made

Choose Suppliers > Show cash payments… from the menus or click on the icon in the Payments section on the Suppliers tab of the navigator. You will be presented with the standard transaction find window which allows you to filter the cash payments you see:

When you click on the Find button will be taken to the usual transaction viewing window with the cash payments you selected displayed:

To view an individual payment simply double click on its line in the list and you will be shown a read-only view of the cash payments form containing all the details of the payment you made and the invoices it was paying. If you have the correct user permissions you can edit the payment note at this stage even if the payment has been finalised.



Previous: 11. Payments and Receipts | | Next: 11.02. Receiving payment from customers

11.04. Cash register

The Cash Register allows you to see and create in and out payments for the customers and patients in your store. It also shows you the current balance of the cash register and you can use it to manage cash reconciliation in a store if you are using a physical cash repository of some sort.

Any payments made in the customer receipts module, supplier payments module or made on a prescription will also be show here. Those payments differ to those made in this module in that they are attached to a transaction (customer invoice or prescription). Any payments made in this module are not attached to any other transactions.

Viewing the cash register

1. Click the Special tab in the navigator.

2. Click the Cash Register button:

3. The Cash Register will open:

By default the window will show all of today's transactions when it opens but you can use the filters at the top in the Filter by section to see just the payments you want in the table:

  • From and To date fields: include only cash transactions that have an entry date between (and including) these 2 dates
  • Patient/Facility drop down list: has Patient/Facility and Comment/Reason options.
    • Patient/Facility: the search will be for all facilities with a name or patients with a surname that starts with what is entered in the text box (can separate surname and first name by a comma i.e. surname,first name to refine a patient search)
    • Comment/Reason: the search will be for any cash transactions with a comment or reason starting with what ius entered in the text box
  • Transaction type drop down list: has All transactions, Cash receipts and Cash payments options. Will include transactions of the selected type only in the list.
  • All these search fields are ANDed together so only cash transactions that match all of the filter values set will be shown in the list.

Note that only finalised cash transactions will show in the cash register.

The Current register balance shows you the current balance of all the in and out payments in the datafile - this is the amount of cash you should have in your physical cash repository if you're using one.

For each transaction in the table you can see:

  • Who the cash was received from or paid to
  • Payment type:
    • rc is a cash receipt (cash paid to you by a customer or patient)
    • ps is a cash payment (cash paid by you to a supplier)
  • Amount received or paid, where a positive number is cash in and a negative number is cash out
  • Date of the transaction
  • Other details such as reasons and comments

Adding or removing cash

All transactions involving payments will be automatically added to the cash register. Those payments are made using the customer receipts module, the supplier payments pmodule or by receiving payments on a prescription and all those payments are cponncted to their transaction.

You can use this cash register functionality to manually add cash in or take cash out from the cash register, without it being attached to another transaction. For example, this may be necessary for depositing cash in the bank.

You can set permissions to allow users to manually add cash in or take cash out from the cash register.

Permissions for manual cash in/out transactions

Users need to have the Create cash transactions permission set on the Permissions(2) tab of the user's details window to be able to add or remove cash from the cash register. See the Managing users page for details.

Manual cash in/out transactions

1. Click the Add transaction button:

Note: If the user does not have permission to make cash register transactions, an alert message will appear and they will not be able to proceed.

2. The Add cash transaction window appears:

Add the Name of the person/organisation who is giving you the cash or receiving it from you. Type the first few characters of the patient or organisation name and press the Tab key on the keyboard to select the right name from the list of those matching what you typed.

If you are searching for a patient, you can enter their surname followed by a comma and their first name (e.g. Smith,Deborah to search for Deborah Smith) to narrow the search.

3. Select the Transaction Type from the dropdown list: Cash out (remove cash) or Cash in (add cash) and enter the Amount of cash being removed or added:

4. If you are making a cash out transaction and the Option dropdown list is activated, you must select a reason for removing cash. You may also add a Description to give further details of the transaction:

The Option drop down list will be activated when you are making a Cash out transaction if you have entered Cash out transaction reasons on the Options tab of the Preferences (see the Preferences > Options section for details.

5. Click OK, then click Save & Close to finalise the transaction:

Once finalised, the transaction can no longer be edited.

6. The new transaction will now appear in your cash register and the Current register balance will be updated.

Cancellations for prescription payments

When a prescription is cancelled, any payment made against it is not automatically cancelled because the patient might give you the goods back but not receive a cash refund. However, a patient credit is automatically created equal to the amount of the payment and assigned to the patient. This means the patient is refunded in credit, not cash.

If you really wish to refund cash to the patient, you need to find the patient credit created for them, cancel it and then go to the cash register and enter a cash out transaction for the patient. This will appear as a “ps” type transaction in the register. It is a good idea to have a separate Option (16.10. Options (standard reasons)) for this type of cash out payment to allow you to report on them separately from other types of cash out transactions.

Printing a cash transaction report

1. Click the Print button:

2. An Excel spreadsheet will open containing the list of transactions shown in the table:

If you want different transactions to appear in the report, change the filters before clicking the Print button. You can then save and/or print the spreadsheet from Excel. The Search by comment or reason filter will remove any transactions from the selection that do not have a comment or reason that starts with what is typed into the field. In this way, you can report on any different selection of payments and receipts, including cancellations.



Previous: 11.03. Prescription payments and credits | | Next: 12. Reports

11.03. Prescription payments and credits

Prescription payment preferences

To receive payments for prescriptions in a dispensary, go to Dispensary Mode Preferences and check the Receive payments from prescription window box.

Once activated, a Payment tab will appear in the Prescription Entry window:

Entering the payment

To enter a payment from the Prescription Entry window:

1. Click on the Payment tab.

2. The Total payment field shows the amount that needs to be paid by the patient. Enter the amount the patient actually gives you in the Amount given field, then press the Tab key on the keyboard:

3. In this example, the prescription cost is $300 and the patient will pay with a $500 note, so 500 is entered in the Amount given field and the Tab key pressed. mSupply then shows you the change that is to be given back to the patient in the Change to give back field:

If payment types have been set up, then you can select the type of payment being made in the Payment type drop down list.

Please note: You cannot overpay a prescription. If you edit the Amount given field to be more than the Total payment amount the Amount given field will be reduced to the Total payment amount and the Change to give back will be increased by the difference.

4. Click OK to finalise the prescription and payment and close the window (if a payment is entered the prescription will be automatically finalised, you have no choice). If the Print receipt checkbox is checked then a payment receipt will print at this point.

Once you click OK, the prescription and payment are finalised and can no longer be edited. Check carefully before pressing OK!

Please note: You can save a prescription without a payment when the Receive payments from prescription window preference is turned on (see the top of this page) but the prescription will not be finalised, it will only be confirmed. You will be warned and asked to confirm that this is what you want to do if you do not enter a payment. If you want to enter the prescription payment later, you can find the prescription, open it and enter the payment then.

Paying with credit

Patients can be given a credit limit (see 10.03. Patients) and can use some or all of that credit at any time to pay off some or all of a prescription. Patient credits (see below) and cash paid into the cash register by a patient (see the 11.04. Cash register page for details) will add to the amount of credit a patient can use.

The process of using credit in a payment is exactly the same as the payment process described above, the only difference is that, if the patient has some credit available, mSupply will automatically use as much as it can to pay for the patient's prescription. You can see the amount of credit the patient has available (made up of their credit limit, patient credits and cash they have paid in) in the Patient's credit status section and the amount of credit used to pay for the prescription in the Amount paid by credit field:

In this example, the patient has 100 credit available (made up of their credit limit only, which is 100) and all of that credit has been used to pay the prescription charge.

If you or the patient does not wish to use their credit, or wishes to reduce the amount of their credit used to pay the prescription, simply change the amount of credit used in the Amount paid by credit field and press the Tab key on the keyboard so that mSupply re-calculates the amount to be paid by the patient. Here is a screenshot if the patient in the example above decides to pay 250 towards their prescription and only use 50 of their credit:

Patient credits

You can allocate funds in a patient's favour by giving them a Patient Credit. You might need to do this if, for example, a patient returns faulty medicines they already paid for. Creating a patient credit increases the amount of credit a patient has. Patient credit can be used to pay for future prescriptions.

View patient credits

To view already created patient credits, choose Patient > Show prescriptions in the menus or click on the show prescriptions icon on the Patients tab of the Navigator:

In the filter window that appears, select the appropriate filter options and click on the Find button to show the prescriptions that match the filters (just click on the Find button without changing nything if you want to see the default 15 most recent prescriptions):

Patient credits have cc (for “customer credit”) in the Type column, prescriptions have a type of ci. Iy you only wish to see patient credits then click on the Customer credits item on the left hand side.

Create patient credits

To create a new patient credit:

1. In the menus, choose Patient > New patient credit…:

2. Enter the patient in the Name field just as you would for a prescription. You can also enter other details such as a Reference (e.g. the prescription number this patient credit is related to) and a Note explaining why a patient credit is being issued.

3. Click the History button to view the items previously dispensed to this patient:

4. Select the item(s) to be returned from the patient's dispensing history, then click Add to credit. Multiple items may be added at once:

5. Review the patient credit. Note that the price appears as a negative value in the patient credit window since it is a credit to the patient, not a charge.

You can also add items not linked to a patient's history by clicking the New line button and entering item details just like you would for a prescription.

If you only want to allow users to issue patient credits for items linked to a patient's history, turn on the Limit patient credits to previously prescribed items preference in the Invoices 2 tab of File > Preferences (see Invoices 2 Preferences). This will disable the New line button, and all items must be selected from the History button.

6. Once you are sure the patient credit is correct, check the Finalise box and click OK.

Remember you have also just returned items to your mSupply inventory! If you are going to destroy returned items, you now need to remove them from your mSupply inventory in a separate transaction (either a Reduce stock Inventory Adjustment or a Stocktake).

When the patient pays for their next prescription, their credit will be automatically applied in the Payment window.

In this example, the patient's current prescription is $300 but they had a $100 credit which is automatically applied to the invoice. Now, they only need to pay $200.

Cancellations for prescription payments

When a prescription is cancelled, any payment made against it is not automatically cancelled because the patient might give you the goods back but not receive a cash refund. However, a patient credit is automatically created equal to the amount of the payment and assigned to the patient. This means the patient is refunded in credit, not cash.

If you really wish to refund cash to the patient, you need to find the patient credit created for them, cancel it and then go to the cash register and enter a cash out transaction for the patient. This will appear as a “ps” type transaction in the register. It is a good idea to have a separate payment type Option (16.10. Options (standard reasons)) for this type of cash out payment to allow you to report on them separately from other types of cash out transactions.



Previous: 11.02. Receiving payment from customers | | Next: 11.04. Cash register

11.02. Receiving payment from customers

Note that the “Activate customer receipts module” checkbox on the Invoices 2 tab of the Preferences must be checked before you can use the Customer Receipts module (see the 14.03. Invoice preferences section). Once this option is checked, new invoices will have the outstanding amount recorded. If this option is not checked, the outstanding amount of invoices is set to zero.https://docs.msupply.org.nz/preferences:invoices

A payment from a customer (which can be a standard customer or a patient) is referred to as a Cash Receipt in mSupply (regardless of whether the payment is by cash, cheque, transfer or some other method).

The system mSupply uses to record payments is the accounting standard “open invoice” system, which means that the outstanding (that is, unpaid) amount of each invoice is tracked by mSupply.

Payments from customers can be received in any currency that customer invoices have been issued in. But a single payment transaction can only record payment in one currency - if you need to record multiple currency payments from a particular customer then record a separate payment for each currency.

Viewing cash receipts

To view the existing cash receipts that have been entered, choose Customer > Show cash payments in the menus or click on the 'Show me' icon in the Cash receipts group on the Customer tab of the Navigator:

The usual transaction filter window opens to enable you to choose which cash receipts you want to see. By default you will be shown the 15 most recent receipts. When you have finished your selection, click on the Find button to be shown a list of the matching cash recipts (Note: if only 1 receipt matches, you will taken straight to it rather being shown a list):

Creating cash receipts

To begin the process of recording a received payment choose Customer > New cash receipt… and you will be presented with this window:

The Their ref field label can be customised in the preferences to be anything you want. Please see General preferences for more details.

  1. Enter the customer name or code into the first field and press Tab. You will be shown a list if there is more than one matching entry for what you have typed.
  2. Once a customer is chosen all customer invoices that have unpaid amounts and customer credits that have unused credit for that customer in the store you are currently logged into will be listed.
    • Note: only finalised invoices are shown. If there are no finalised invoices with outstanding amounts, this alert appears:
    • If you wish to receive a payment and there are no invoices available to record the payment against, you can either record the amount as an overpayment (see below) or, if the invoices requiring payment are in mSupply but not showing here, click Cancel and then finalise the invoices to make them show in the payment window, then restart the payment process (If the customer is paying you it most likely means they agree with the invoice and it is OK to finalise it!)
  3. Enter the cheque number or similar in the Their ref field and a note in the Note field if you want to.
  4. Select the currency of the payment you are receiving (your home currency will be chosen by default). Any invoices that are in currencies different to the one selected are disabled and cannot have a payment entered against them. If you are receiving a payment in a currency other than your home currency you can manually adjust the conversion rate that mSupply uses by entering the rate you want to use in the Rate field.
  5. Enter the total amount of the payment you are receiving into the Receipt field.
  6. You have a number of choices to allocate payment amounts to the various invoices:
    • Click on the Distribute button.
      • This will allocate payment to the top invoice first and work its way down the other invoices until the payment is all allocated (note that disabled invoices in a different currency are ignored). Note that the negative amounts on any customer credits are added to the amount to distribute before the distribution begins.
      • If the amount being received is not enough to cover all invoices then one will receive a partial payment and some may receive no payment.
      • If the amount received is more than the amount on the invoices, the extra amount will be an overpayment.
    • Double-click an invoice in the list to be shown a box to enter the payment amount, or
    • Hold down the shift key while double-clicking an invoice to allocate the full outstanding amount of that invoice.
  7. Click the OK button to record and finalise the payment (you will be warned that the payment cannot be edited).

Note: If you receive more than the total amount of the invoices you will be asked to confirm that this is OK and the extra received amount will be recorded as an overpayment - see below.

Note: customer credits should be entered as a negative Receipt amount. It is generally good practice to allocate credits as soon as they show in the list.

Finding a customer's current balance

When the customer receipts module is turned on, you can find out how much a customer currently owes you in 3 ways:

1. View the Invoices tab of the customer's details (Customer > Show customers… - see 5.01 Viewing a customer's invoices for details)

2. When you enter the customer's name on a new customer invoice, their current balance will be shown on the invoice as in this screenshot:

3. Run a customer statement report (see the Customer statements section below).

Overpayments

  • Sometimes a customer might pay you more than the amount owing (not so likely, but it does happen to some nice organisations!), or the customer might pay you for an invoice that is not yet finalised. If this happens, allocate any amount that relates to invoices in the list. When you click OK you will be warned there is an overpayment and you will be asked if you want to continue.

  • Click OK if you want to continue, or Cancel if you want to allocate the extra amount to invoices.
  • The next time you enter a payment for that customer you will be presented with a window asking you if you want to use the overpayment for this transaction:

  • Click Use if you want to use the overpayment, or Don't use if you want to enter another payment (Some customers just keep sending in the money…)

Customer statements (reporting on customer payments)

To see each customer's payment history and their current outstanding balance, run the Customer statements report - go to Report > Debtors and Creditors > Customer statements… in the menus (it's also on the Reports tab of the Navigator) and use the filters to select which customers you want included in the report.

To see details for an individual customer you can go to their details page. See the instructions in the Viewing a customer's invoices section for that.

Cancelling payments

All payments, whether they are for prescriptions or customer invoices will appear in the cash receipts list described in the Viewing cash receipts section above.

If you wish to cancel one (because it was a mistake or the customer brings the goods back), select it in that list and click on the Cancel button above the list:

You will be asked to confirm that you want to cancel the selected payment - make sure you have selected the right one and you really want to do it because you can't undo the cancellation once it's done!

When you cancel a payment, the transaction that the payment was for is not also cancelled i.e. if you cancel a payment of a customer invoice, the customer invoice is not also cancelled.



Previous: 11.01. Payments to suppliers | | Next: 11.03. Prescription payments and credits

10.06. Abbreviations for dispensing

Abbreviations are the short codes you can use to quickly enter the patient directions for a medicines when you dispense it to them.

When you are issuing an item you can mix abbreviations and your own text to add common directions quickly.

It is worth mentioning that abbreviations may also be used in other situations e.g. if a significant number of customers live in the same locality, an abbreviated form of their address could be employed. All abbreviations are created in the same way as described below.

To access the functionality, click on the Special > Abbreviations menu option. The following window opens, showing a lost of all the current abbreviations that have been entered:

As usual, you can sort the list by clicking on the column headers.

Add an abbreviation

If you change an abbreviation or add a new one, you will see the change immediately (v317 or later), but in a multi-user environment other users will have to log out and log in (use Switch user to do this quickly) to see the edited or added abbreviations.

To add an abbreviation, click on the Add button and the following window opens:

Enter the abbreviation that you will type in the Abbreviation field and the text that it will be expanded to in the Expansion field. When you're done click on the OK button.

Do not use actual words in your abbreviation, or else attempting to type the word will result in the expanded text appearing on your label!

Note: your abbreviations cannot contain the underscore (_), period (.) or comma (,) characters.

Any non-printable characters entered before or after the abbreviation will be removed. Any entered in the abbreviation will be replaced with an underscore (_).

Edit an abbreviation

To edit an abbreviation, double-click it in the list. A similar window to the add abbreviation window will open, pre-populated with the abbreviation's details:

Edit the abbreviation and expansion as required then click on the OK button to save it.

Delete an abbreviation

Select a single abbreviation in the list by clicking on it then click on the Delete button. You will be asked to confirm the deletion - if you do, it is deleted from the list.

Click the Report button to construct a simple report listing all abbreviations. This report can be previewed or printed.

After clicking on the button, you will be shown the report editor window. In older versions of mSupply it looks like this:

  1. Double-click on Abbreviation
  2. Double-click on Expansion
  3. Right-click on Detail and set font size to 8 or 9
  4. You can use the lines on the column headers to adjust column width
  5. Choose File > Generate to print the list

In newer versions of mSupply, the report editor will look like this:

Click on the Fields button and then double-click on abbreviation then expansion in the left hand Available fields section to move them to the Report columns section like this:

Click on the OK button then click on the Execute button to run the report and print it out.

Importing abbreviations

The procedure for importing a file containing your abbreviations is found here.

Item default directions

Once you have entered abbreviations, don't forget to enter the default directions for all common items - the default directions are the abbreviations that are used by default for an item when it is added to a prescription. Instructions are here.



Previous: 10.05. Prescribers | | Next: 10.07. Diagnoses

10.07. Diagnoses

The Diagnoses functionality allows you to quickly save a diagnosis on a patient’s prescription.

Viewing and Adding Diagnoses

Select the Diagnoses icon from the Special tab on the mSupply navigator window.

This will open the Show diagnoses window with a list of all diagnoses.

  • The list will initially be ordered by date created. However, the list can be sorted by the ICD code or ICD description by clicking on the respective column header.
  • You can use the search box to search for a diagnoses using either an ICD code or the ICD description.

Standard mSupply search functionality applies when searching for diagnoses.

The list can be filtered using the Show drop-down box on the top right of the window:

  • All: active and inactive diagnoses.
  • Active: diagnoses that have not yet reached their specified valid till date.
  • Inactive: diagnoses that have passed their specified valid till date. Inactive diagnoses will not appear in other windows, and cannot be saved to a patient prescription.

Click on the New diagnosis button on the top-left of the window to add a new diagnosis. This window will open:

Enter the ICD Code and Description. Please note:

  • Both code and description boxes are mandatory.
  • mSupply does not check the data entry in these boxes. Please double-check that you have entered the information correctly.

Enter the Valid till date. You can use the date selection tool by clicking on the calendar to the right of the box.

  • The date entered determines how long the diagnosis will remain active. After this date the diagnsis will be automatically made inactive.
  • The valid till field is non-mandatory. Leaving this field blank results in the code remaining permanently active.

Diagnoses on Prescriptions

You must first turn on the Allow users to choose diagnoses on prescriptions store preference to allow diagnosis selection on prescriptions. See the 25.08. Virtual stores page for details.

When this preference is turned on, when you create a new prescription you will be able to select a diagnosis using a drop-down list. The drop-down list will display and allow selection of any active diagnosis:

The diagnosis selected will be saved against the prescription together with all other information provided in the Prescription entry window.



Previous: 10.06. Abbreviations for dispensing | | Next: 10.08. Label printing preferences

10.01. Dispensary mode

Dispensary mode allows you to issue medicines to individual patients. It is ideally suited for pharmacies, clinics, hospital dispensaries, and facilities where medicines are supplied to individual patients.

In dispensary mode:

  • Labels can be printed with:
    • Item description and quantity issued
    • Patient name
    • Prescriber name
    • Directions
    • Institution name
    • More…
  • Use of Dispensary mode depends on your mSupply registration type. Contact Sustainable Solutions if you wish to upgrade your registration.
  • Regardless of mode, each user can only use those functions for which they have permission.
  • In client-server versions of mSupply, different users can be logged in in different modes at the same time, allowing you to dispense to patients and supply wards, stores, clients or cost centres simultaneously.
  • Users whose permissions allow them to operate in either Store mode or Dispensary mode may change from one to the other by pressing Ctrl+2 on the keyboard. Re-entry of the user's password is not necessary.

Activating dispensary mode

Prior to version 3.5 you controlled dispensary mode for each user, and had to choose File > Edit users…
Now it's a setting for a store.

  1. Choose Special > Show stores… from the menus.
  2. Double-click on the store you want to set to dispensary mode.
  3. Select Dispensary in the drop down list next to the store's code field.
  4. Log out of the store and log in again to activate dispensary mode.

Setting dispensary mode preferences

Choose File > Preferences > Dispensary mode tab to set preferences. See the 16.01. General preferences page for details about all the preferences but here are some important preferences to consider:

  • Ensure the Show direction entry in dispensary box is ticked. This allows users to enter patient directions for dispensed items.
  • Specify what information will be printed on dispensing labels.
  • Specify if you want a receipt to automatically print on labels.
  • Specify if you want mSupply to auto-generate patient codes (alternatively, the user must enter a unique code for each patient).
  • Specify if a prescriber must be entered for each prescription.
  • Specify if you want to be able to receive payments from the prescription window.

What changes in dispensary mode?

Most of the things you can do in store mode are also available in dispensary mode. The main differences are:

  • The Customer menu becomes the Patient menu; and
  • The Customers tab on the navigator becomes the Patients tab, which has a slightly different selection of icons
  • The windows displayed are appropriate for dispensing medicines to individual patients. For example, a patient's dispensing history is maintained and you can also record patient notes (e.g. allergies).

Note that a facility using dispensary mode can distribute stock to both patients and customers (e.g. hospital wards, outreach programs), and can still handle customer requisitions.



Previous: 10. Dispensing Goods | | Next: 10.02. Prescription entry

10.03. Patients

Updated version 5.01

In mSupply, patients are a type of name. They are a special form of customer that can have first names, last names, genders and dates of birth. You dispense stock to a patient on a prescription, rather than distributing it to a customer on a customer invoice.

Entering a new patient

You can enter a new patient by clicking on the Patient > New patient… menu item to by clicking on the New patient icon on the Patient tab of the navigator.

If you are already creating a prescription and discover the patient is missing you can click on the New patient button on the prescription (Shortcut: Ctl-Shift-P):

Either way, the same window will open:

  • Code and Last are the only required fields but all applicable fields should be completed so that it is easier to recognise the patient next time. Please note that if there are non-printable characters before or after the First, Last or Code they will be removed. Any non-printable characters in the First, Last or Code (and spaces in the Code) will be replaced with an underscore (_).

If the new patient's date of birth is known, it should be entered, otherwise an entry should be made in the Age field; for a patient aged 18 months, valid entries in the Age field may be in one of 3 formats, namely 18m, 1.5, or 18/12.

  • When a patient's code is known, that patient's record can be rapidly displayed. Note also that the Male radio button is checked; if you are entering details of a female patient, remember to check the Female radio button!
  • Custom fields are available for storing extra information relevant to your situation.

Viewing and editing patient details

You can view a patient's details from a prescription; just click on the patient details button next to their name when they have been selected on a prescription (Note that this button is not enabled until a patient has been selected on the prescription):

If you are not entering a prescription then you can select the Show patients icon on the Patients tab of the navigator or click on the Patients > Show patients menu item:

Enter the details you want to search for the right patient (or leave everything empty to show a list of all patients) and click the Find button.

You will be shown a list of matching entries (double-click on the one you want to view or edit), or taken directly to the detail view if only one patient matches the values you entered:

Show patients search results

Whichever way you access the patient's details, the same window opens:

Home store

Updated version 4.10 Updated version 4.12 Updated version 7.13

As of version 4.10, you'll notice that at the top of the details window is the Home store. For new patients, the home store is the store the patient was created in; for previously existing patients the version upgrade will assign the home store to be the store where the patient was most recently issued a prescription.

  • A patient's details can only be edited in any dispensary store which is active on the same site as the home store (i.e. on their Home site). This ensures that a patient can only be edited in one location at a time.
  • In version 4.10 and 4.11, a patient's home store cannot be changed. However, from version 4.12 it will be possible to edit the home store (if you're logged into the central server). Doing this will make the patient's records (repeats, patient medication records and insurance policies) available to the new home site. If the patient has previous prescriptions from stores which are visible in the new home store, these will also be made available to the new home site, but will only show up in the patient's history if the Share patient prescriptions over stores preference is turned on (see setting_dispensary_mode_preferences). Note that you will not be able to edit a patient's details if their record is currently waiting in the sync queue to be transferred to another home store. A “Not editable pending transfer to XX” (where XX is the new home store) message will show at the bottom of the screen and all fields will be disabled if this is the case.
  • You can create prescriptions for a patient in any store they are visible in, not just their home store, but repeats can only be processed in any dispensary store on the home site.
  • If you're on the central server, you can make a patient visible in other stores (just like any other type of name) - doing this will make the patient's records (repeats, patient medication records and insurance policies, but not their prescription history) available to the store.

The patient detail window tabs

General tab

The date of birth field for a patient uses the same date format as your computer's operating system. If you enter an age, the date of birth is guessed and a patient comment is added to mention that the date was guessed so you know it's not accurate.

Hold do not issue: If this is checked then no stock can be dispensed to the patient

Credit limit: This is the maximum debt that a patient's account can have when the payments module is activated. Enter as a number greater than zero. They will not be able to be dispensed a prescription without paying for it when they reach this limit.'

If the payments module is not activated, the value in this field has no effect.

Prescriptions tab

Here each prescription created for the patient in this store is shown. Double-clicking a row in the list will open that prescription.

Notes tab

Any notes/events you enter in the notes tab will display each time you enter the patient name in the Prescription entry window. These notes can be used to remind you of patient Preferences for certain dosage forms, or drug sensitivities.

Before you add an event for a patient, you need to make sure that patient events have been set up.

Patient events

This is the term mSupply uses to denote any item of information relating to a particular patient; for example, you may want to record the patient's weight, the patient's blood pressure, any allergies from which the patient suffers, vaccination records, etc. - a wide range of information relating to a particular patient may be recorded here.

First, some definitions of patient events need to be made;choose Patient > Show Patient events , then click the New button.

One patient event is already defined, the code is `NT', the description is `Note', and the type is Text; you can also have events of type Numeric or Boolean . For example, to create a patient event recording a patient's weight, the completed Add patient event window would look like this:

A further example, this time using the Boolean type - i.e. where the options are limited to two, `Yes' or `No' - could be to identify patients who have insurance cover to meet the cost of their prescriptions; for this event, the Add patient event window, once completed, would appear like this:

Once a number of patient events have been defined, choosing Patient > Show Patient events, will produce a window like this:

Now it is possible , using the Notes tab of the patient details window, to add individual items of information to the profile of any patient.

View the record of the patient in the normal way (from Patient > Show Patients, enter the patient's name & double click the appropriate patient from the 'names output' ) , and select the Notes tab. Click on the Add event button to bring up the window shown above.

In the Event field, Search event type appears by default. To display all the events you have defined so that you may choose the one you require, enter the character “@” (without the quote marks), press the TAB key, and make your required selection from the list.

Alternatively, you may enter a word from the description of the event - e.g. if you have defined Patient's body weight as an event, you may enter the start of the event name or code (e.g. pat ), and that event will appear in the Event field. If more than one event matches what you have entered, a list will displayed for your to choose the event you want to enter.

Should you wish to add any note or comment, you may do so by moving the cursor into the Note area, clicking, then typing your entry. You can customise the note in terms of when it will be displayed on screen etc. as described in the Items chapter of this guide. Here's the link - The Notes tab.

After a period of time, a patient's notes may look like this:

The default view shows all patient events, but you have the ability to vew single events by selecting the event code from the drop down menu Patient events under Show

A new event may be added by clicking on the Add event button, and an event which is no longer of any relevance may be deleted by clicking on the Delete event button.

Events may be edited by selecting the specific event, double clicking on it, when the Edit patient event window appears.

History tab

This tab shows a list of all the items dispensed ot this patient. Double-clicking an item will open the prescription it was dispensed on.

PMR (Patient Medication Record) tab

See the separate section on this here Patient Medication Records

Backorders tab

If you are using a backorder system and you have any backorders for this patient, they will show here.

Store Visibility tab

The tab shows which stores the patient is visible in. Only when the visibility checkbox is checked will the patient be visible to that store. The patient must be visible in a store to be able to create prescriptions for them in that store.

Visibility for patients created on a synced system

Remember that in a synced system, patients can be created in any dispensary on any sync site. This is unlike ‘normal’ Names (customers, suppliers, etc.) that can only be created on the primary server.

When a patient is created on any site, it will be made visible in:

  • Its home store (i.e. the current store), and
  • All other stores of type “Dispensary” which have their store preference Patients created in other stores not visible in this store switched OFF.

Data that syncs with a patient:

  • Their insurance policies
  • Their repeats (Note, other sites won't be able to see and use them)
  • Their PMR records

Data that does NOT sync:

  • Transactional/prescription history
  • Patient events

While it can be used to make all patients visible across all dispensary stores across all sync sites, use caution with the store pref Patients created in other stores not visible in this store. Doing so does not scale well on large systems if it is turned OFF for many stores as it causes exponential data growth and sync traffic:

  • (50 stores) x (100,000 patients) = 5 million visibility records
  • Initialising a site with 3 dispensaries with the pref off will require syncing 100k patients, and 300k visibility records.
  • It does not include prescription data. If it did it'd only add to the above.

Once a patient has been created in a dispensary, its store visibility can then be amended in this tab.

Merging patients while dispensing

Updated version 4.12

While dispensing, you may observe that a patient has been inadvertently entered twice. For example:

When the Choose patient window appears, you can highlight the two patients to be merged, then clicking on the Merge button displays this window:

Here you need to decide which record should be kept, and which one should be merged, and check the appropriate radio buttons. This combines the information in the record to be merged with the information in the record to be kept.

Note that, from version 4.12, merging patients will be restricted to only those having the same home site - see home_store.



Previous: 10.02. Prescription entry | | Next: 10.04. Prescribers

10.04. Patient insurance

Updated version 4.10

Insurance policies are used by patients to pay part or all of the cost of a prescription.

Insurance policy details for a patient are set up on the Insurance tab of the patient details window. These policies are then available for selection when receiving payments from the prescription entry window (see the 11.03. Prescription payments and credits page for details).

At the moment, this functionality is only available in Côte d'Ivoire (see Insurance for a description of how it is used). Please contact us if you need to use this functionality.

Insurance providers

Insurance providers are the institutions which provide the insurance policies for patients. They are recorded by selecting them from a drop down list when adding an insurance policy to a patient. This functionality is for managing the contents of that drop down list.

To see a list of all the current insurance providers, choose the Special > Insurance providers… menu item. This window opens:

To add a new provider click on the button. This will add a new entry top the end of the list in the table with the Name “new provider”. Edit the values for this entry in the fields at the top:

  • Name: the name of the insurance provider. This will appear in the drop down list for the user to select when adding an insurance policy to a patient
  • Prescription Validity Expiry (days): The maximum number of days that can elapse between a prescription being created by the prescriber and being presented to the mSupply dispenser and the provider's insurance policy can still be used against a prescription's cost. 0 days means no expiry. mSupply will not allow an insurance policy to be used to pay for a prescription if this number of days has been exceeded.
  • Comment: Anything you wish to remember about this provider. Will not be displayed anywhere else.
  • Is active: Check this if the insurance provider can be used for assigning to new insurance policies for patients. If this is unchecked, the insurance provider will not appear in the drop down list when recording new insurance policies.

To remove a provider click on the button. This will delete the currently selected provider, but only if you have not saved it before. If a provider has been saved, edit it and uncheck the Active checkbox to remove it from future selections.

To edit a provider select it in the list by clicking on it and then edit the details shown in the Name, Prescription Validity Expiry (days), Comment and Is active fields.

The Save button will save any new providers you have entered and will also close the window.

The Cancel button will close the window without saving any new providsers or unsaved edits.

Previous: 10.03. Patients | | Next: 10.05. Prescribers / Clinicians

10.10. Patient medication records

Added: Version 3.11

Introduction

A Patient Medication Record (PMR) is a way of recording all the medications a person is using, whether or not they were dispensed by you. The record contains useful information for the patient such as

  • The dosage in a clear easy-to-understand format.
  • An (optional) picture of the dose form (tablet, capsule, etc)
  • The medication's purpose.
  • Common instructions for taking/using the medicine, which may be customised for each patient
Setting up items

Before adding items it is good to set up the standard purpose, instructions and item photo for common items at least. Once set up, you can add these to a particular patient's PMR with just the click of a button.

  1. Find the item you are interested in and go to the dispensing tab
  3. Enter purpose and instructions. Both these fields can take as much text as you wish to enter.
  4. Add a photo by either dragging a photo from another application or pasting a photo from the clipboard.

mSupply will automatically resize large photos when you add them- there is no need to resize photos yourself first.

Default direction

On the default direction list, you can add a combination of abbreviation which can be used to fill in the direction while issuing drugs to patients.

To set up abbreviation, view 10.05. Abbreviations for dispensing

Add This is to add default directions. You may combine multiple abbreviation code to make up a sentence. You may even add a full sentence.

Delete This is to delete direction.

Direction for items that were added above will be available when dispensing to patients.

Note the Drop down list will now be populated by the default directions. Once a direction is chosen, mSupply will expand valid abbreviation to sentences. It is possible to have more than one set of direction as options.

Adding items to a PMR

There are 2 ways of adding items to a PMR

  1. From the patient history tab:
    • Highlight the items from the patient's history you wish to add, then click the Add to PMR button.
    • The record will be shown on the “PMR” tab if you switch to it.
    • Note that on the PMR tab you still have to double-click on the added record and fill in the dose, instructions etc.
  2. From the Patient details PMR tab
    • Here you can add any item that is in the mSupply catalogue.
    • For example, a patient might be regularly taking paracetamol or aspirin that they buy themselves. You can add such items here.
    1. To add an item, click the Add item button. You will be shown a new window:
    2. Item name: type the start of the item name and press <tab>, then select from the list
    3. Dosage: Enter the number of tablets/drops/whatever to be taken/administered morning, noon, evening and bedtime.
    4. Purpose: If the item has a purpose entered, click the copy button to copy it to the right-hand box. Here you can edit the details if you want to.
    5. Instructions: If the item has instructions entered, click the copy button to copy them to the right-hand box. Again, you can edit the details if you want to.
    6. Click OK when you're done, or cancel if you decide not to add a record.
Editing a PMR entry

To edit a PMR, double-click the entry you wish to edit, change details, and click OK to save the changes and close the window.

Deleting a PMR entry

To delete a PMR entry, highlight the record(s) you wish to delete, then click the delete button. (Do be careful- it's not reversible!)

Printing a PMR
Setting up printing preferences

When a PMR is printed, it has a header and footer. These are set up by choosing File > Preferences and then clicking the Patient Medication tab.

Note that you can style the text in these boxes by selecting text and right-clicking on your highlighted text to get a contextual menu to apply font styles, colour and size.

Printing a PMR

Simply click the Print button. Note that you do not have to highlight records- all records will be printed.

Currently we have included a single PMR printing form in mSupply. We are happy to include others- send us your designs.



Previous: 10.09. Warnings | | Next: 10.11. Printer setup for Remote Desktop Client

10.12. Patient type and Ward setup

Patient types and Wards are two fields that are enterable on a prescription. But before they will appear on a prescription for display, you must set them up. Have no fear, the instructions are here :-)

Patient types

Patient types are actually transaction categories. To set them up, choose Special > Transaction categories… from the menus or click on the Transaction categories icon on the Patient, Customer or Special tab of the Navigator:

On the Transaction categories window that opens, click on the Transaction type drop down list and select Prescriptions (2):

Click on the New button to add one or double-click one already in the list to edit it. This window opens (populated with the current details of the category if you're editing one, empty if you're creating a new one):

  • Master category: You can ignore this, it isn't used for patient types.
  • Category code: Enter a short code for each patient type. If you are wanting to enter wards for patients then you need to add an Inpatient category with a code of IP and a Discharge category with code DI.
  • Description: The name of the category as it will be seen throughout mSupply (if you are using wards then two of these will be Inpatient and Discharge).

Click on the OK button to save your changes.

Wards

If you want to select the patient's ward on a prescription you must first turn on the Allow users to select ward on prescriptions preference. See the 16.01. General preferences page for details on that.

In mSupply, wards are names that have been assigned a tag of Ward:



Previous: 10.11. Printer setup for Remote Desktop Client | | Next: 11. Payments and Receipts

10.05. Prescribers / Clinicians

Updated version 4.10 Updated version 4.12 Updated version 5.01

From the Special menu choose Prescribers

When you are in dispensary mode, issuing items to a patient allows you to add a prescriber. This menu item allows you to set up your list of prescribers.

To add a new prescriber, click the “New” button.

Add a code for the presciber. You can use the code quickly to look up the prescriber when dispensing. Any non-printable characters before or after the code will be removed and any spaces or non-printable characters in the code will be replaced with an underscore (_).

Other fields are fairly self-explanatory. Note that the code, first name and last name can all be used for looking up prescribers when dispensing. Also note that any non-printable characters before or after the Last name or First name values will be removed and any non-printable chanracters in either of the values will be replaced with an underscore (_) - this will make sure that your searches work as they should!

From version 4.10, prescribers will have a home store like patients (see the 10.03. Patients page for details), which will be the current store for new prescribers or the store with the most recent prescription (assigned during the version upgrade):

  • A prescriber can only be edited in any dispensary store which is active on the same site as the home store (i.e. on their Home site). This ensures that it can only be edited in one location at a time
  • From version 4.12 it is possible to edit the home store (if you're logged into the primary server). Doing this will make the prescriber available to the new home site. If the prescriber has previous prescriptions from stores which are visible in the new home store, these will also be made available to the new home site, but will only show up in a patient's history if the Share patient prescriptions over stores preference is turned on (see Setting dispensary mode preferences)
Initials

The text you put in the “Initials” field will print on dispensary labels.

Active status

If you have a prescriber that is no longer used, you can change their status to “inactive” and the prescriber will not show in the choice list when dispensing. Inactive prescribers will still show when you choose Special > Show Prescibers…

We suggest you might want to add a “Miscellanous Prescribers” item to the list, and use this if you have a lot of prescribers whose prescriptions you only dispense infrequently.

Category

This field can be used to group prescribers together, and can then be used to filter prescribers when producing a transaction report.

Merge prescribers

Updated version 4.12

This item from the Special menu is used to merge two prescribers, where the same prescriber has inadvertently been entered twice. You are shown a window like this:

Enter the two prescriber names by entering the start of their surname or their code, and then pressing Tab . The top prescriber is the one who will be kept. The lower prescriber will be deleted.

Once you have entered the two names, check the details are correct, and then click OK. You will be warned one last time, and then the operation will be completed.

All transactions that recorded the deleted prescriber will now show the name of the prescriber that was kept.

Note that, from version 4.12, merging prescribers will be restricted to only those having the same home site.

Import prescribers

For information on the procedure for importing a file containing your prescribers see Importing prescribers



Previous: 10.04. Patients | | Next: 10.06. Abbreviations for dispensing

10.02. Prescription entry

In dispensary mode, supply of items is made using a patient's prescription (rather than a customer invoice for a standard customer in store mode). Choose Patient > New prescription from the menus or the new prescription icon on the Navigator:

This will show the prescription entry window:

Selecting the patient

Type something in the Name field in the prescription entry window shown above and press the Tab key on the keyboard to see a list of patients matching what you typed.

Anything you type before a comma is treated as the start of a last name, anything typed after a comma is treated as the start of a first name.

  • For example, to find John Smith, you could enter “Smi,J” or “smith,joh”

If you know the patient's code, enter the start of it prefixed with an asterisk (*)

  • For example, to find the patient with code 5829854 you could enter “*58298”

If your patient has already been created in the system, then these entries should bring up the patient in question, or a small enough list of patients for you to choose from.

Always search for your patient in this way first, before entering a new patient, to avoid entering the same patient multiple times.

If only one patient matches what you have typed, after pressing the Tab key on the keyboard their last and first name will be put in the Name field separated by a comma and their other details will be filled in on the rescription entry window e.g. patient code, date of birth, gender, address.

If more than one patient matches what you have typed, after pressing the Tab key on the keyboard you are shown a list of the patients that matched:

  • Find the correct patient in the list and double-click on them or single-click on them and click the Use button to select them.
  • If you can't see the correct patient, click on the Cancel button to try the search again or to add them as a new patient as described on the Patients page.
  • When you select a patient a few of their details will be displayed in the Patient details section of the window and any Notes they have will be displayed (see here for details on how to update their notes).

The Remote search button is only visible if you are on a remote site in a synchronisation system. If the patient you want is not shown then you can click on the button to include all patients that are not visible in your store to be included in the search. If you select one of those patients they are made visible in your store and their details are downloaded for you.

Please note that if you are on a remote site in a synchronisation system then this window will appear, regardless of whether 0, 1 or more patients match what you typed in the Patient field - this is to ensure you always have the option of doing a remote search for the patient.

Editing patient details

Once you have chosen a patient, you can click the small down-arrow to the right of the patient name to display a window where the patient details can be viewed and edited (see below):

Clicking the Print icon at this point will give you access to reports showing all prescription history.

Entering the prescriber

Once you've chosen a patient, the cursor will automatically advance to the prescriber entry field.

To enter a prescriber, you can type either their code, their last or first name in full or abbreviated, or “last comma first”. For example for the prescriber Dr Felix Brown (whose code is 123) any of the following are acceptable:

  • 123
  • bro
  • fel
  • bro,fe

Press the Tab key on the keyboard after making the entry to show a list of matching prescribers. If only one prescriber matches, the name will be entered directly without the list being shown. This is the window that appears to allow you to select the prescriber:

Double-click the prescriber you want or single click it and click on the OK button.

The Remote search button will only be displayed if you are on a remote site in a sync system. Click it to include prescribers that are not visible in your store in the search. Note that if you are on a remote site in a sync system, this window will always be shown when you search for a prescriber, regardless of whether there are 0, 1 or more prescribers that match what you have typed in the Prescriber field so that you always have the chance to do a remote search for a prescriber.

Patient type and ward entry

The Patient type and Ward fields only appear if their contents have been setup in mSupply first. See the 10.12. Patient type and Ward setup page for details on setting them up.

When the prescription window first opens, the Ward field will be disabled. It will only be enabled when a Patient type of Inpatient or Discharge is selected. So a ward can only be selected for a patient of Discharge or Inpatient type.

Other fields

  • Confirm date: this is read only and is automatically set for you when the prescription is confirmed.
  • Prescription date: Enter the date the prescription was written for the patient here.
  • Reference: Enter any reference, such as a prescription number, that you need to record in here.
  • Category: Choose a category in this drop down list. The list will show all the Prescription type transaction categories set up in your system. See the 26.06. Transaction categories page for details on setting up transaction categories.
  • Note: Enter any notes, comments or other things that need to be remembered for this prescription. You can enter a lot of text in this field. If you need to see more than the single line shown, click on the button next to it to show a larger window containing all the text. You can enter text in that window too.

Entering prescribed items

On the Prescription entry window click on the New line button and the Add item window appears:

Type the first few characters of the item's name or code in the Item field and press the Tab key on the keyboard to select the right item from a matching list. Tip: if you enter the complete code mSupply will be able to identify the item and will select it straight away, saving you time and mouse-clicks. Another tip is that if the Show item unit column when issuing store preference is turned on (see the 25.08. Virtual stores page for details) then an Item unit column will also be included in the table used to select the items from.

When you have selected the item, the details of the stock available for that item are filled out:

After you have selected the item, if you have told mSupply to inform you of interactions (see the 15.01. General preferences page for details) then an additional Interacting items button will be displayed on this window. Click on it if you wish to see interactions that this item has with other items. If there are any interactions between this item and any dispensed to the patient within the set length of time, you will be shown a warning message.

The first line of stock in the table is selected by default (the first expiring one). If you want to dispense from another, double-click it in the list. Enter the amount you want to give the patient of the selected stock line in the Quan field and click on the OK button if you've finished adding lines or the OK & Next button if you want to add another line.

Note that if the store preference Edit prescribed quantity on prescription is turned on (see Store preferences for details), an additional Prescribed quantity field is present for you to enter the appropriate quantity:

If the Show direction entry in dispensary mode preference in File > Preferences (Dispensary mode tab) is turned on then you can now enter the directions telling the patient how to take the medicine.

Entering directions

For many commonly prescribed items, default direction abbreviations can be defined - refer to the section on Item Default Directions. In the example below, the item being dispensed is FRUSEMIDE 40mg tablets, and the default directions are “Take ONE tablet in the morning”. Alternative directions present may be displayed by clicking on the down arrow to the right of the abbreviated direction field; directions not already present may be typed in using either the Abbrev entry area, or the Expanded entry area.

Note that you can mix abbreviations and text like this.

The drop-down list shows any default abbreviations you have entered for the chosen item. If one or more default abbreviations exists, the highest priority default abbreviation will be 'suggested' when you choose the item. If there is more than one standard abbreviation available, you can choose another one by choosing it from the drop-down list.

mSupply stores the expanded text for each line, not the abbreviation. This means that there is a full audit trail of what was printed on the label (unless you edit the directions after printing!).

Default directions

The set up of default directions is done on the dispensing tab when editing an item. You will find it described here.

View history

In the new prescription entry window, once you have entered a patient name you can click the “history” button to view a patient's history of what you have dispensed.

Duplicating a prescription

Once you have a history window open you can click to select a single entry or control-click to select multiple entries, then click the “duplicate” button to create new prescription line(s) with exactly the same details. Stock will be issued for these lines automatically.

Repeats

mSupply allows for the recording of repeat prescriptions. This is achieved when the prescription is first dispensed; in the Add item window, click on Total field in Repeats box in the top right corner of the window, and enter the number of repeats that the prescriber has authorised. The Repeat Dispensing procedure is described below.

Repeat dispensing

The Repeats panel (upper right of the window shown below) allows details of repeat prescriptions to be recorded. Take the example of a patient presenting a precription for Frusemide 40mg tabs x 30 on 1st January 2007, with the prescriber requesting “Repeat monthly x5”; in the Total field you should enter “5”, and in the Expiry Date field you have the option of entering (a) the actual date on which the final repeat may be issued - in this example, “1 July 2007” (allowing the patient one month's grace) - or (b) “6m” for 6 months. Note that the characters “D”,“W” & “M” in upper or lower case are interpreted in this particular field as the specified number of days, weeks or months before the repeat instruction expires. mSupply defaults to an expiry date two months later than the current date, but this may be edited as appropriate. The system automatically updates the number of repeats remaining as the patient makes further visits to have the repeats dispensed. The window below is displayed when you click on the New line in “ Prescription window ”

The number of repeats is assigned in Total field in Repeats box, and as the repeats are dispensed, the number remaining is displayed in the Left field.

When you click on the blue arrows on the upper right side ,the total repeat number and total quantity for each repeat is shown. Clicking on the small arrow displays the window below.

This window allows the user to alter the quantity of a particular repeat - e.g. if there is insufficient stock on a particular visit of the patient; the quantity can be edited by clicking on the quantity line, and again clicking on the quantity, which may now be edited. The arrow on the left bottom corner enables you to restore the default quantity setting.

Once you have filled repeat and other details on the Add item window properly, click on OK button to save details.

The Repeats icon is contained in Prescription entry.

When the Repeat function is used, and there are future repeats to be issued, the icon appears on a red background:

The red background disappears when either:

  • expiry date is reached
  • all repeats have been dispensed

You can issue the repeat to a particular patient. Clicking on the Repeats icon displays this window:

The repeat window shows items to be dispensed, quantity, total repeats, repeats remaining and expiry date for a particular repeat.

  • Process repeats button: This button is used to issue the repeat for a particular patient and for a particular item line. For issuing the repeat, first select a desired item line and then click on the Process repeats button. Now the system automatically manages the repeats internally.
  • OK button: Click the OK button to exit from the Repeats window.

There is an Alert if repeat is dispensed before the defined interval of X days preference you can set to ask the user to donfirm if they wish to proceded if a repeat is issued within a selected number of days of confirmation of the original prescription. See the 15.01. General preferences page for details.

Printing labels

Dispensing labels are printed when the Print labels box is checked in the Prescription Entry window. You can specify what information gets printed on dispensing labels in Dispensary Mode Preferences.

Sample labels, produced by the Zebra TLP2844 printer are reproduced below:

mSupply currently is designed to work with the Zebra label printers. Zebra printers can use either thermal labels or a thermal ribbon which gives non-fading results.

We currently support plain 90 x 40mm label stock as this is cheap and readily available. The Zebra printer is auto-sensing of the ending of a label, so you can most likely use labels longer than 40mm with no problems.

Label specifications:

  • 90mm x 40mm high
  • White Matt Thermal Transfer Paper
  • Wide Edge Leading
  • 1 Across on a roll
  • Perforation between each label
  • Produced on 1“ core to suit TLP2844

We are happy to support other printers if you use a different brand.

Reprinting labels

If you need to print the labels for an item again, choose Patient > Show Prescriptions to locate the prescription entry.

In the list of items dispensed, click on the line you wish to reprint, and then click OK (with the printing checkbox checked)

If you wish to reprint labels for all the items on the prescription, first click in the list of items below the last item so that now one item is highlighted. Then all labels will be preprinted when you click OK

Printing multiple labels

If you want to print more that one label for an item, hold down the Alt key ( Option on Mac) as you click the OK button. You will be asked for the number of labels required as the label is about to print.

What if there is not sufficient stock of one batch?

As the quantity of a particular batch of an item gets used up, you will need to issue stock from more than one batch to a patient. mSupply handles this when printing labels, and combines the totals for any item on a prescription so that only one label is printed for the total quantity.

The directions for the item with the first line number will be used, so enter directions for the first batch you dispense, and leave the directions empty for subsequent batches.

Note: if you have the rare situation where you need to issue the same item to one patient with different directions you should either combine the directions onto the one label, or enter two prescriptions with the directions entered differently on each prescription (That is enter the line, then print the label(s), then choose Patient > New prescription and issue the item again with the second set of directions).

Receiving payments

You can receive payments for prescriptions directly from the prescription window if you wish (an alternative is to receive them using the customer receipts module. Both result in the same transactions being created in mSupply but will suit different physical workflows).

See the special page on receiving payments from the prescription window here 11.03. Prescription payments and credits.

Printing receipts

You can print a receipt for a patient's payment of a prescription if you have the Receive payments from prescription window preference turned on (see Dispensary preferences for details) .

Receipts are printed (from the same printer as the labels) when the Print receipt box is checked on the Payment tab of the prescription entry window:

Receipts may also be reprinted later by opening the prescription and checking the Print receipt box again - in which case they will have the text “COPY” printed at the bottom.

After printing the medicine labels, a patient receipt will be printed as shown below.

If you don't have a printer setup in Special > Printing preferences you will be prompted to select one or set one up. If that is not possible, receipt printing will be cancelled.

Prescriptions and barcode scanners

It is possible to print barcodes on prescription labels and use barcode scanners to open the prescription quickly. For details, please see the 15.07. Barcode scanning and prescriptions page.



Previous: 10.01. Dispensary mode | | Next: 10.03. Patients

10.08. Label printing preferences

In mSupply the settings for label printer are set in the “Choose label printing preferences window”, which you open by c choosing Special > Printing preferences from the menus.

This window will show you ALL mSupply printers that have been set up in this mSupply server.
If you have several printers connected to the same server then we suggest you include the room, area or site name in the printer descriptions so that you manage the correct printer. Make sure that you do not delete printers for other sites connected to the same server!!!

Changing your mSupply default printer

To change the mSupply default printer in the “Choose label printing preferences window” simply click the checkbox in the right-hand Default Printer column for the printer you wish to use.

Note this is different from your Windows default printer. You are setting the default printer for mSupply to use (the default printer you have set for Windows can be another printer altogether).

The mSupply printing preferences are stored for the computer you're setting it from (not the mSupply user or the mSupply site you're logged in to). When you change the mSupply default printer you are changing it for everyone who uses the computer.

Editing a printer

In the “Choose label printing preferences” window double-click the printer entry in the list. This will open the “Add label printing preferences” window - see below for info on each setting.

Adding a printer

If you are setting up up your label printer hardware for the first time, you will first need to follow the instructions here: 25.18. Label printer hardware setup.
When your printer hardware is connected and ready to be set up in mSupply open the “Choose label printing preferences” window and click the New Printer button. This will open the “Add label printing preferences” window - see below for info on each setting.

The printer preference settings

Description
Since the mSupply printing preferences window lists ALL the mSupply printers for your organisation it is vital that the Description includes the site name to avoid confusion.
e.g. Busby Pharmacy GK420t

Connection Type
If printer connected with a network cable (recommended) choose network
If printer connected with USB choose USB
If printer connected with a serial cable choose serial
See below for the printer connection settings for each type of connection

Label Type
One-Part
Three-Part See below for the label settings for each type of connection

Make this printer default
Checking this box means that mSupply on this computer will always print to this printer. Refer to the Changing your mSupply default printer section above to find out what setting a default mSupply printer does.

Reset printer
You can use this button to send a command to the printer to reset it. Occasionally a printer may misbehave if it's memory is corrupted by an electricity spike or the like, and this button may help. If your printer is not behaving we recommend you contact Sustainable Solutions support@msupply.org.nz rather than charging ahead on your own.

Printer connection settings
Network
Port number
For network connections this will usually be 9100

Address
The IP address of the printer
e.g. 10.1.1.253
For info on creating a static IP address for the printer refer to label_printer_hardware_setup
USB
Address
Enter the Windows name of the printer. It must be entered exactly. There is no need for the Windows printer name to match the mSupply printer description.
To confirm the Windows printer name go to the Windows Control Panel > Printers and Scanners.
Right click on the printer and select properties.
The Windows printer name is recorded on the General tab.
Serial
Port number
Enter the Windows serial port number for the printer.
To confirm the port number go to the Windows Control Panel > Printers and Scanners.
Right click on the printer and select properties.
The Windows port number is recorded on the Ports tab.
Printer label settings
One-Part label
Label width: the physical width of the full label
Label height: the physical height of the full label

Label top: the height of margin wanted from the top of the label
Label left margin: the width of margin wanted from the left of the label
Three-Part label
Label width: the physical width of the full label
Label height: the physical height of the full label

Label top: the height of margin wanted from the top of the label
Label left margin: the width of margin wanted from the left of the label

Label bottom margin: the margin between the top label and lower labels.
Bottom left label width: the width of the bottom left label.

Other settings

There are other general preferences that can affect the way your labels are printed. See the 15.01. General preferences page (label printing section) for details.



Previous: 10.07. Diagnoses | | Next: 10.09. Warnings

10.11. Printer setup for Remote Desktop Client

In low bandwidth situations the mSupply client can become laggy and unstable, in these cases it may be recommended to use RDP through the Windows Server Remote Desktop Client application. If the site is dispensing and using a printer, this introduces some complicated steps.

Requirements

At dispensary: - A computer with serial/com port and with RDP access to server - A Zebra printer with serial/com port

Server/machine that is remoted to: - mSupply Client installed and can connect to mSupply server - Windows server installed that has Remote Desktop Client

Setup the Remote Windows Server Machine

Use Windows Run (i.e. command prompt/powershell) to run tsconfig.msc and gpedit.msc.

- In the tsconfig window, right click on “RDP-Tcp” and click “properties”. Go to client settings and make sure that the COM port is unchecked in “Redirection - disable the following” list. - In the gpedit window, follow the hierarchy shown below and make sure “Do not allow COM port redirection” is disabled (not configured probably fine).

Setup the Local Machine

- The machine that you will be dispensing from needs to have the appropriate Zebra printer. - Check that your printer has a 9 pin serial/com port on the rear - Check your Computer also has a 9 pin serial/com port (right most port below).

- You can verify that the computer has detected its external ports via device manager

- Using a RS232 serial cable, plug the printer into the computer.

Caution: If you have a cable that has the female plug at both ends, it is likely a Null Modem cable. This cable will not work (even with adapter).

- If you have mSupply available locally on the machine, you can try testing printing a label to confirm your local setup is correct using misc. labels in the special menu.

Remote Desktop Connection Settings

You must enable port sharing on the remote machine (at dispensary) in Remote Desktop Client for the machine you are going to remote into.

  1. Enter the connection details for the machine you are going to RDC into
  2. Show connection options
  3. Select “Local Resources” tab
  4. In the section “Local devices and resources” click the “More…” button
  5. Ensure that the “Ports” checkbox is ticked
  6. OK!

Open mSupply Client in the rdc window and test printing, hopefully it works!



Previous: 10.10. Patient medication records | | Next: 11. Payments and Receipts

10.09. Warnings

From the Special menu this command allows you to view and edit the standard list of warnings.

Once this list is created, you can apply one or more warnings to each item, and choose which warning will be automatically printed on labels.

To apply a warning to an item, see Adding a New item

Double-click a warning in the list to edit its details.

Click the “New” button to add a new warning.

We suggest you use the standard set of warnings as specified by the pharmaceutical authorities in your country.



Previous: 10.08. Label printing preferences | | Next: 10.10. Patient medication records

13.10. ATC and DDD code based reports

ATCs and DDDs

“ATC” stands for “Anatomical, Therapeutic, Chemical”, and is a method of classifying chemical entities, and identifying them by category.

“DDD” stands for “Defined Daily Dose”, and provides a means of comparing the utilisation of different drugs in a meaningful way. - e.g. if a dispensary has issued 10,000 x doxycycline 100mg and 20,000 x amoxycillin 250mg, a greater number of amoxycillin capsules has been used; but according to the DDD method, a greater number of patients have received doxyxcycline.

Thanks to the help of the WHO Collaborating Centre on Drug Statistics and Methodology, we are able to offer a starting drugs file with their codes; we have plans (not yet implemented) to maintain on our website an up-to-date list of ATC and DDD codes for essential drugs.

Reports using ATC and DDD codes

mSupply is designed for the ATC code to be entered in the Category field for each item, and is then able to report on supply transactions, giving a breakdown according to the different levels of the ATC code.

The DDD Factor field is intended to store the item's number of dose units in its DDD; for example, if an item's DDD is 1,000mg, and the supply is made using 250mg units, the DDD factor is 4. When designing a report, the total quantity of this item used should be divided by the DDD factor to obtain the number of DDDs supplied.

Should you wish to store an item's DDD value (1,000mg in the above example), it is suggested that you record it in one of the available user fields. The DDD value should not be recorded in mSupply's DDD factor field

The category analysis report is designed to be used in conjunction with the “category” field and the “DDD factor” field for each item.

When you produce a report, only some simple criteria are entered in the form. It is a simple matter to create reports giving, for example:

  • A level one ATC summary for all items supplied to a specific hospital during a 12 month period
  • A level two ATC summary for all items in ATC category “J” supplied to customers who are coded as “h” (for hospital) for a particular month.
  • A level three ATC summary for all essential drugs supplied to all customers for a particular quarter.

The report provides you with the number of DDDs supplied for each category at the level requested, presuming you have “DDD factor” values entered correctly. Only the totals for each category are shown (not each individual transaction). The report may be printed, or exported for use in another application.

Let's run through the different options in the window… summary level…- enter the summary level. The category field is then evaluated based on the ATC coding system. Note that the code is “broken down” as follows

level position
1 character 1 (A-Z)
2 characters 2 & 3 (01-99)
3 character 4 (A-Z)
4 character 5 (A-Z)
5 characters 6 & 7 (01-99)

So, for example the code for “caffeine” is N06BC01. “N” is the level 1 code, “06” the level 2 code, “B” the level three code, “C” the level four code, and “01” the level 5 code.

Note that if you choose “level 3”, you will also be shown the summary values for “level 1” and “level 2” as well.

Which type of item?

You can report on all items, or you can report on just a certain category. For example, you can enter “J” here to report only on items whose ATC code starts with “J”. Note that you need to set the summary level to “level 2” or your report will only report the total for category “J” without any further breakdown of data.

Only report on essential drugs

Check this if you only want to analyze items whose essential drug check box is checked.

Transaction type?

- Normally we will be interested in supply to customers. However, we might also be interested in “what percentage of purchases from IDA (a supplier) are aniti-infectives?”, in which case we would click on the “items received from suppliers”

Date range...

Enter a starting date and an ending date. Only transactions whose confirm date was within the range will be analyzed. The default range is the last 90 days. Note that the dates you enter are included in the range (that is the “from” date is “on or after” and the “to” date is “on or before”)

Which customers/suppliers...

Leave this value blank to report for all customers. Otherwise, choose “code” or “category” from the popup menu, and the appropriate comparison from the second popup menu. For example, if you want to report on a certain group of hospitals, you could enter those hospitals as having a category “h”, and then report on “names whose category starts with 'h'”



Previous: 13.09. Customer ordered shortfall report | | Next: 13.11. Other reports

13.09. Customer ordered shortfall report

When you choose Report> transactions and then select Customer ordered short fall report , the transaction report like the one below will be produced. This report is used only for sales to customers.

For this report to make sense, make sure that:

  • The Allow placeholder lines on customer invoices preference is checked
  • The Delete placeholder lines when confirming invoices preference is un-checked

From the report window, select the desired parameters and click OK . An example report is shown below.

Previous: ATC based reports Next: Purchasing

Setting up mSupply to use the customer ordered shortfall report

For this report to be used, you need to do the following

  • Choose File > Preferences > Invoices2 and ensure “Delete placeholder lines when confirming invoices” is not checked.
  • Staff must enter requested amounts on invoices as placeholder lines.
    • For example, a customer orders 1000 x Paracetamol syrup 60ml. You have 800 in stock, so you add 800 to the invoice, and you also add a placeholder line for 200 bottles.

You need to decide whether to (and if yes, how to) use the backorder system. If customers can rely on you to record shortfalls as backorders, then they will no need to re-order the shortfall in subsequent ordering cycles, as they know you will deliver it when available.

In our experience, general custom and practice in places that use mSupply is for facilities to simply re-order stock that wasn't delivered 'last' time. In this context, it would not be useful to turn the backorder system on.



Previous: 13.08. Dashboard | | Next: 13.10. ATC and DDD code based reports

13.14. Custom reports

Choosing this item brings up a window for creating a custom report:

The custom report window is displayed allowing you to create a report according to your own requirements using the Quick Report editor; once created you may save the form of the report in the custom reports folder for future use.

The window requires you to make three choices:

Report table

A list of tables on the left to choose which table (which type of records) you want to report on, e.g. Names, Items, etc.

As of version 1.6 there are two options for transaction lines. The “Transaction lines (Transaction query)” option allows you to search much faster on a large number of transaction lines. For example, if you are wanting to get the quantity of each item given to customers in a specific month, you would use this option.

Which records

A series of radio buttons to choose which records to examine

  • All records
  • New search (query), if you want to report on records meeting specific criteria. If chosen, you will be presented with the Query (search) editor, where you can build search statements to your heart's content! A short description of using the query editor is given below, and two example searches are later described. For a more comprehensive description, a range of books is available either in electronic or hard copy versions. Please email info@msupply.org.nz for more information.
  • The “Current selection” is the group of records that were last displayed. For example, you can use the Item | View or edit item command quickly to find all items starting with “a”. When you click the OK button, the items in the list are the “current selection”. If you are not sure which records represent the current selection, you should click the “new search” radio button.
Report form

A drop down list displaying available options:

  • New report
    • After clicking the OK button you will be presented with the report editor where you can design a report. The report editor is somewhat complex, but time spent in learning how to use it is time well spent. It is a powerful and invaluable feature. A brief introduction together with designing two simple reports are given in Designing a Report below, and more details are available in training courses on using mSupply, and in publications available from Sustainable Solutions.
    • If you want to save a report or search (query), you can save them on your hard disk, and retrieve them next time you run the report.
    • If you save the report you have created in the Custom reports folder it will show up in the report form drop-down menu on future occasions when you choose custom report.
    • The default location for saving your custom reports is My Documents\mSupply\custom reports; it is important to note here that any custom reports you have created should not be saved in the My Documents\mSupply\Reports folder, otherwise problems may arise.
  • New label layout
    • Presents you with the label editor, where you can design and save label layouts. These are useful for use with names for addressing envelopes, and with Items for making tags for labeling shelves in your warehouse.
    • If you choose this option the “Order by” window will appear after a query. This allows you to sort the records into a particular order before printing labels. (In a nutshell: Drag fields from the list on the left to the list on the right to use them for sorting)
  • Other items in the menu
    • If you have saved any reports in the custom reports folder they will be listed here.

A list of the fields in each table, and what each field contains is given in section 24. Data Tables and Fields.

Using previously saved layout

Any report layouts which you have used previously, and saved, may be accessed by clicking on File >Open on the menu bar, and selecting the required layout.

Using the Query search editor

There are now many reports included in mSupply®, but there may still be occasions when you require a report that we have not included. The query editor is a bit daunting, but is very powerful and once you are familiar with its capabilities, your competence to access the precise information you may require from within the mSupply database will increase significantly.

When you open the Custom Report editor, it is ready to take input values for a simple single line query.

  1. The field to query. Choose this by clicking on the Find drop-down list which allows you to also choose fields from related tables. If you want to perform related queries, see note below.
  2. The Comparator. Choose the comparator from the list of fields by using the middle drop-down list.
  3. The Query value. Is entered in the third box. In the example above, the field chosen is an alphanumeric field (the item ID), so an entry area is displayed where you can enter text or a numeric value - in this instance the item code “amox” has been entered. Note that you can also use the “@” symbol as a wildcard in your query value to perform “contains” queries.
  4. The Conjunction. This does not apply to the first line of a query, but the second and any further lines need to start with a conjunction. Set the conjunction for the selected line by clicking the appropriate button in the left area of window ( And, Or or Except )

To add lines to a query, click the Add Line button.

Related queries: If you want to perform related queries, you need to know a little about the internal structure of mSupply data. Please contact us if you would like a diagram of the table layouts. A simple example of a related table is that each transaction line is related to a transaction (many to one relationship). The means that you can use the information stored in the transactions table (eg invoice date, number, status, etc.) to query transaction lines.

If you have created a complex query that you might wish to use on future occasions, you can save it to your hard disk and select it again using the Save and Load buttons in the window.

Once your completed query is entered, click the Query button to proceed.

For more detailed information on the Query search editor see: http://doc.4d.com/4Dv16R6/4D/16-R6/Query-editor.300-3561635.en.html

Designing a report

The designing of two custom report is now described:

  1. listing in alphabetical order the small number of items which may be supplied to staff or customers who wish to make a purchase without a prescription. These items have already been identified by making use of their User field 2, which contains the entry “Retail permitted”.
  2. listing the sources (suppliers) and the distribution (customers) of a particular batch number of an item - useful if a manufacturer recalls a particular batch of an item.

It is recommended that you study both examples, as features described in the first example will not be repeated in the second.

Report 1

Having selected Custom Report from the Reports page in the Navigator, you are presented with this window:

For our example report, we select the Items table, and to perform a New Search, using a new report form, so with these options selected, the window now looks like this:

Click OK, and the Query Editor window appears, as shown in the upper figure below; this is where you specify the criteria on which you wish to create your report - in our simple example, the single criterion is that there should be stock on hand of the item. In the lower window, we have specified this by:

  1. clicking on user_field_2 in the Available Fields panel on the left,
  2. clicking on contains in the Comparisons panel on the right, and
  3. entering “Retail” in the Value panel below.

You will see that the conditions we specified now appear in the upper panel - it's always a good idea to check here to confirm that the report will conform to your specified criteria.

Now click on the Query button in the lower right corner.

The Quick Report window appears; this is where you can design the layout of the report, and specify how you want the records to be sorted:

We'll start by taking a closer look at the Quick Report features.

There are two operation modes available which generate two specific types of reports: List and Cross table . Our examples are limited to the List mode. The Cross table mode will not be described.

In the List mode, reports typically display records as a list with break rows where calculations are performed.

When you create a quick report, you can specify the following:

  • Columns that display fields or formulas, either from the current table or from related tables.
  • Sort levels and order.
  • Summary calculations.
  • Display format.
  • Text for labels.
  • Formats for numeric and Boolean data.
  • Font, font size, style, and justification for labels, summary calculations, and data.
  • Background colours on a cell column or row basis.
  • Borders, Page headers and footers.
  • Presentation style from a wide range of templates.

  1. Master Table: This is the master table that will be used as a basis for generating the report. The fields of this table are displayed in the Fields list and the related fields will be displayed in relation to this table.
  2. Fields list: This list lets you select the fields to be inserted into the report by double-clicking or by drag and drop. You choose the type of display in the Field selection list located just above the area. Indexed fields appear in bold. You can also display and select the fields of related tables.
  3. Column dividers: These lines show the boundaries between columns of the report. They can be moved manually to enlarge or reduce the size of each column. Manual resizing deselects the Automatic Width option if it has been activated for the column concerned.
  4. Cells: A cell is the intersection of a row and a column.
  5. Scroll bars: You use the scroll bars to view parts of the quick report design that extend beyond the area of the quick report form.
  6. Sort list/Sort order display area: This list displays the fields of the report on which the sort will be carried out, as well as the sort order and whether it will be ascending or descending. Each field inserted into this list causes a sub-total row to be added in the Quick Report area.
  7. Quick Report area: This area lets you build your report by inserting fields using drag and drop, double-clicking or via the contextual menu; you can also adjust the width of the columns added, or delete breaks or formulas, define the colors and borders of cells, etc.

  1. Title row: This row displays the names of fields or formulas that have been inserted into the report. It is repeated for each page of the report. The Quick Report editor inserts field names by default, but you can modify the contents.
  2. Detail row: This row contains information drawn from each record and is repeated in the report for each record. You can associate a display format with it, depending on the type of data represented.
  3. Subtotal rows: These rows display intermediate calculations as well as the wording that is associated with them. A row is created for each sort order.
  4. Column data sources: These titles indicate the source of the data for each column.
Contextual menus

The Quick Report editor has contextual menus that make it easy to access certain row, column, and cell operations. Instead of making menu selections or working with the Cell or Column properties areas, you can perform certain operations by displaying a Quick Report contextual menu.

There are separate contextual menus for row, column, and cell operations.

To use a contextual menu:

  1. Position the pointer in a cell, a row title, or a column heading and hold down the right mouse button (on Windows) or press the Control key while clicking in the report area (MacOS).
    A contextual menu appears. The commands in the contextual menu depend on where your pointer is (i.e., a row label, column heading, or cell). Also, menu commands that are inappropriate for the particular row, column, or cell are disabled..
  2. Choose the desired menu command:

Selecting rows, columns, and cells

When designing a Quick Report, you need to select rows, columns, and cells in the quick report form. A cell is the intersection of a row and a column.

  • To select a row: - Click on the Title, Detail, Subtotal, or Grand total cells in the row label area.
  • To select a column: - Click the Header row of a column.
  • To select a cell: - Click the cell.
Adding and modifying text

You can add or modify text in the quick report form to label parts of the report. For example, if you requested summary calculations, you can label them by adding text to other cells in the Subtotal and Grand total rows.

You can add and modify text as follows:

  • Edit the text that automatically appears in the Title row of the report,
  • Insert text in empty cells of the Subtotal and Totals rows,
  • Insert the value of a Subtotal field in the Subtotal rows,
  • Specify the font, font size, justification, and style for any text that appears in the report.

Returning now to our first report, we want two columns only, the first listing the items in alphabetical order, and the second confirming the entry in User field 2. This is achieved by double clicking on item name in the list, and then to have the list sorted alphabetically, make sure item name remains highlighted, and click on the green arrow in the centre:

The second column in our report will show the present stock of each item, and the same procedure is followed; select the user_field_2 entry in the list, and double-click on it. You should be aware that items which are presently out of stock will not appear in the report.

The Quick Report window should now look like this:

The column widths can be adjusted as appropriate by positioning the cursor on the dividing line between the column headings, clicking and dragging to the left or right until the desired column width is obtained:

The vertical red line to the right of the columns indicates the right hand edge of the page as it will be printed, so to keep the report to single page width, columns should be positioned to the left of this line.

To preview on screen the report as it will be printed, click on File on the menu bar, and select Print Preview. Our example is very brief, but in reality, reports may run to two or more pages, and you can scroll through the pages of the report. This shows how our simple report will appear:

The printed report may benefit from shading or colouring of alternate rows, and this is achieved while the report format is being set. In the Quick Report editor, click on Detail to highlight the row, then click on the Alt.background colour icon, and a chart appears from which you can select the colour(s) of your choice.

For our report, pale yellow has been selected for the alternate row colour, and the report now has this appearance:

Adding report title

You may want to give your report a title to appear at the head of each page; this is achieved by clicking on File , then Header and Footer ; a window appears in which you can create and/or edit such a header You will most probably want the header to appear in the centre of the line, and in this case, type your entry into the Center panel in the Text Settings area; here you can also select the font of your choice, and features such as bold, underlined, etc.; these apply only to the header, not to the body of the report. A title has been added to our example:

To print the report, click on File on the menu bar, and select Generate and - provided that your printer is connected, online and loaded with paper - your report will be printed.

Report 2

The second report lists the sources (suppliers) and the distribution (customers) of a particular batch number of an item - useful if a manufacturer recalls a particular batch. The item chosen for our example is Metoclopramide 10mg tablets, the code for which is Metclp10, and the batch no.is BN1234

Having displayed the custom report window, this report requires us to select the trans_lines table, and to perform a New Search, using a new report form:

When the Query Editor window appears, expand the [Items] table, and once expanded, move down the list until code appears, and select it by clicking on it;the upper panel now shows [items]code , the default comparator is equal to ,and so to complete the line, move the cursor to the Value entry panel in the lower part of the window and enter 'metclp10'. Click on Add Line and accept the default conjunction And ; In the Available Fields panel, shrink the [Items] table, expand the [item_lines] table and select batch, accept the is equal to comparator, and enter 'BN1234' in the Value entry panel. You have now defined the criteria for the report, and the Query Editor window should look like this:

You are now ready to click on the Query button.

The Quick Report design window appears, with the Master Table - in this example the 'Transaction lines' table - expanded for selection of the fields required by our report; we'll be using four fields from the master table, namely item name, batch, pack and quantity; double-click on each of these in the list, and the Quick Report design window should appear as shown:

Don't be concerned at the order in which these fields appear in the report - we'll rearrange the order once all the fields have been selected. The fields we now need to add are in other tables; presently Master Table is selected ,and we need Related Tables , which is selected from the drop-down menu.

The table to access is the Transactions table, and the fields we require are Invoice number, type, and confirm date. Double-click on each, then expand the Names table, and double-click on [names]name.

All eight fields for the report are now selected, and we can arrange them in their required order. This is easily performed by selecting the column to be repositioned - we want the item name to be the first column, so we select it by clicking on the column heading, and move it by clicking on the 'Move Left' icon.

Select and move the columns using the 'Move Left' icon and the 'Move Right' icon until the column order from the left is:

  • Item_name
  • Batch
  • Name
  • Type
  • Invoice_num
  • Confirm_date
  • Pack_size
  • Quantity

The report will look better in landscape rather than portrait form, so click on File > Page Setup , and select landscape Once you have done this, you can view your report on screen by clicking on the 'Print preview' icon.

The next steps are :

  1. to sort the report
  2. to perform some simple calculations
  3. to display this information.
  4. to adjust the column widths

All these are simple to perform on the Custom Report window:

  1. Sorting the report. Drag and drop in the 'Sort order' panel the parameters required - in this example [Transactions]type and [Transactions] confirm_date.
  2. Performing calculations and displaying the information. We need to count the number of transactions, and display the totals involved. Observe the two rows added to the report annotated with the sort parameters followed by 'change'; these are the break points in the report, and the results of any calculations are displayed in these rows ….. here's how:
    1. position the cursor in the Invoice column on the [Transactions]type changed row
    2. click Cells on the menu, and check Count; we need to know how many customers have been supplied with this batch, so the Count icon is inserted in the row - it does not matter which column has the Count icon - for the time being it is entered in the 'Invoice' column, and the reason for this will soon become apparent.
    3. also required is the total quantity ordered, and the total quantity distributed, so the cell in the same row but in the Quantity is selected, and this time the Sum box is checked in the Cells drop down list.

  1. Column widths can be adjusted as described earlier, and having a look at the Print preview will enable appropriate widths to be defined.

The report should now appear something like this:

Only two tasks remain! It's not necessary to display the Invoice type, so this column may be hidden - right click on the column heading, and from the contextual Column menu, click on 'Hide'.

mSupply® by default enters the field name in the displayed column heading, but you can edit these column headings by double clicking on the cell in the 'Title' row, when an insertion point cursor appears and the current entry is highlighted; you can replace the default text with whatever you consider appropriate. This has been done in our example.

Finally, there is a large selection of presentation styles available, any of which can be applied to your report. On the menu bar, click on Style > Presentation. In our example, after defining a header for the report, we have opted for Report 1, giving our report the appearance you see below.

At some time in the future, you may wish to run your reports again. You should, therefore, save a copy of each report in the Custom Reports folder; this is performed by clicking on File on the menu bar, and selecting Save or Save as, giving the report a name, and saving it in the Custom Reports folder, or any other appropriate location of your choice. Then when you're ready to run the report next time, having specified your criteria in the Query Editor, when the Quick Report window first appears, click on File on the menu bar, select Open, and retrieve the desired report from its saved location, preview it and print it.

Using custom methods in quick report columns

Sometimes you will need to use a custom method in a column to extract data from a related table.

The following methods are available.

Method Description Parameters
date_day_number_to_text returns 1 for Sunday, 2 for Monday etc.
qr_account_code_return Returns the account code of an item item_id
qr_flag_value_change
qr_get_currency
qr_get_current_patients_stat
qr_get_item_store_field return value of field as text 1:item.id 2:“price” or “is_in_catalogue” or “sellprice”
qr_get_location-from_key
qr_get_loc_from_key_new_process
qr_get_Name_code_from_key
qr_get_stockOnHand_from_itemKey
qr_get_store_name
qr_keep_accumulative_value
qr_ns_customer
qr_responsible_officer
qr_ship_method



Previous: 13.13. Saving report templates | | Next: 13.15. SuperReport editor

13.08. Dashboard

The mSupply dashboard is very helpful for providing visual representations of your data to support analysis and decision making at all levels of the supply chain.

To see all the information about the dashboard, please see the separate documentation for it here https://docs.msupply.foundation/dashboard.

To access the dashboard, you can click on the Dashboard button on the Reports tab of the Navigator:

If your dashboard has been setup and you have permissions to login to it (see details on setup here https://docs.msupply.foundation/en:dashboard:getting_started) then the dashboard will be opened in your browser and you will be automatically logged into it.

If your dashboard hasn't been setup then you will be shown an alert giving you an option to view the demo mSupply dashboard (which shows you a selection of visualisations and functionality for some dummy data) or to cancel and contact Sustainable Solutions to set your dashboard up for you:



Previous: 13.07. Dispensary/prescription reports | | Next: 13.09. Customer ordered shortfall report

13.07. Dispensary/prescription reports

Patient prescription notes report

Choose Report > Dispensary > Patient prescription notes report from the menus and the options window will open:

In the date range section select the confirmed date range of prescriptions you want to include in the report. The drop down list to the right of the date fields is a great way of quickly selecting them.

Check the Open in Excel checkbox if you want to open the report in Excel rather than as a pdf or to print it then click on the OK button to run the report. This is what the report looks like:

Prescriptions by patient type report

Choose Report > Dispensary > Prescriptions by patient type report from the menus and the options window, which is exactly the same as for the report above, will open. Make you selections then click on the OK button to run the report. It looks like this:

Others

The are other transaction report that specifically deal with prescriptions and prescribers. Please see the transaction reports page (13.03. Transaction reports) for details on how to run these. They are selected in the Type of report drop down list on the transaction reports options window, these are the types available:

  • Prescription and general issues over time
  • Prescriber report
  • Dispensing with patient name and prescriber
  • Prescription report based on transaction categories
  • Prescriptions by patient type report



Previous: 13.06. Requisition reports | | Next: 13.08. Dashboard

13.01. Report basics

Choose Report from the menus and this menu appears:

For some reports, the default setting includes all items, and as most stores will have several hundred items - maybe over 1,000 - reports on all items will, if printed, use a great deal of paper. If you must have a printout of your report, please exercise caution when selecting the criteria, and so avoid wasting paper.

Reports on purchasing are displayed when Purchasing is selected:

Reports on items and stock are displayed when Items and Stock is selected:

Reports on debtors and creditors are displayed when Debtors and Creditors is selected.

Many reports are available from the Reports page of the Navigator, as shown below:

Many of the reports present you with a window like this before printing the report:

This window allows you to set various options:

Report destinations

Printer: Select this option to display.the print window. The preview of the report can be displayed by turning on the print preview.

Open in Excel: If the Open in Excel box is checked, mSupply will immediately open the report as a spreadsheet in the spreadsheet application (MS Excel, OpenOffice/LibreOffice Calc etc.) you have installed on your computer.

  • When this box is checked, you will first be asked to save the report. Once you have given it a name, the report will be saved, and then automatically opened in spreadsheet form.
  • mSupply automatically detects any spreadsheet application you have installed on your computer (i.e. any application that is associated with .xls or .xlsx files). You do not have to set the location of this application.

Save to HTML file: If this option is selected, your report will be saved with extension “.html”. Hence, it can be opened by any web-browser or spreadsheet application on any platform or operating system.

Save as Text file: Your report will be saved to a file as a tab-delimited text file. (That is, a tab character between each column and a return character at the end of each row). After saving, you can open the file in a spreadsheet or word processing program.

You can choose what information will be displayed at the top and bottom of each page. The default report heading appears in the right hand Heading field and is automatically set according to the report you are printing: you can edit this as required and what is entered in this field is what will be printed as the report title. By default, the date will print on the left and the page number on the top right of each page.

If you have filled in a default header and footer in the Preferences, these will be displayed at the top left (for the header) and the bottom centre (for the footer)

Preview on screen before printing

This option turns on print preview. Note that you can also turn on print preview from the print window that is displayed after you click the OK button.

Output to Excel

Most reports can be output to an Excel file. This is particularly helpful if you are wanting to analyse a large amount of data.

As at July 2021, there are three methods of producing Excel reports from mSupply:

  • Quick reports - Easiest to create, fastest to run, but least flexible in terms of formatting. mSupply users can create these - refer Custom reports
  • SRP reports - More powerful than Quick reports
  • XL Plugin reports - Most powerful in terms of formatting, but slowest in terms of operation.

Sometimes new, more powerful versions of existing reports have been created using the XL Plugin specifically for the purpose of analysis using pivot tables and filters. We have not wanted to delete the older reports, so we have kept them, and named the new report with [Excel] in the title.

Reports produced for Excel will sometimes not have the data formatted correctly, particularly, dates - refer to this.

Supervisor mode (reporting over mutiple stores)

If you wish to report over mutiple stores at once, you can be given permission to use Supervisor mode. When you are in this mode, report filter windows will have an additional store list added ot the window so that you can choose which stores' records are to be included in the report.

See the 25.01. Miscellaneous topics: Supervisor mode - all stores page for details.



Previous: 13. Reports | | Next: 13.02. Stock and items reports

13.02. Stock and items reports

When Reports > Items and Stock is chosen, a range of available reports are displayed; click on the one you require to select it:

Current stock

A report will be produced that lists each stock line that is currently showing stock greater than zero. Should you wish the report to include items/batches with zero stock, the box in the lower left needs to be checked.

Item filter

A “Item filter” allows you to enter the normal find item filter criteria to choose which items to include.

Random

A 'Randomly' filter allows you to enter a number of items that will be randomly chosen, and stocktake sheets for those items printed. This facilitates spot checking of your actual stock situation.

Additional options

Should you wish the report to be department specific, then that department should be selected from the drop down list of the departments which you have created.

Should you wish the report to give information on a particular location, then that location should be specified , selecting the appropriate operator of the three available in the drop down box alongside the Filter by actual stock location option.

Report format

You can choose from three formats:

  • “Each batch shown separately” will also give you a column on the right where, having done a physical stocktake, you can enter the quantity that is actually in stock, allowing any corrections to be made in mSupply.
  • “Total stock for each item” will not show individual batches, but the total quantity on hand of each item.
  • List the price of each batch in stock, with a total at the end of the report.

The lines are reported alphabetically either by item name or shelf location, depending on what you have chosen in the “Sort report by” options

Donor reporting

mSupply provides the feature of printing the Donor name on the Current Stock report so that organisation donating the goods can be identified and tracked.

Stock on date

This report allows you to produce a report for the stock in your store on a particular date. The stock shown will be the stock at the END of the day. If you want to see the stock at the beginning of the day, choose the day before in the date selector.

You are shown a window like this:

Enter the date for which you wish to show the stock for.

Type of report

You have 3 options:

  1. Show items only: each item in your system will have a single entry with the total quantity on that date.
  2. Show items with batches: each batch, its expiry and batch number along with the quantity of stock will be shown.
  3. Show batches with summary: as 2, but every item has an aggregate line before the lines for each batch, showing the total quantity for all batches of the item. So it's a bit like a combination of 1 and 2.
  4. Monthly stock & consumption history (Excel): Each item has 3 rows showing its consumption, days it was in stock and its mean stock on hand for each month from the current month to the number of months in the past selected in the Months to look back field.

The Report on items whose box allows you to restrict the report to certain items only, using item properties or different categories as filters.

If custom stock fields are set to be used in the datafile then they will also be shown in filters beneath the item filters.

Open report in Excel

Check this checkbox to view the report directly in your chosen Spreadsheet program.

Show total stock value

This report is used to find the total stock value either for a particular department or all departments. The drop down menus allow customisation of your report by entering appropriate search criteria from the many options.

Check this checkbox to directly open the report in Excel rather than printing.

Graph: stock by item

This report shows a graph for an item or items showing the quantity of stock on hand for each day over a defined period.

Note that if you have allowed editing of confirm dates on transactions, mSupply's ability to calculate accurately the data used in this report may be affected.

Choosing this item from the menu displays this window:

Enter the date range, or select the required period from the drop down list, the items on which you wish to report, and appropriate filters, if any. Remember you can use the item flag field to select an ad hoc list of items to include in your report.

Clicking OK displays a window where you are shown a graph of the quantity in stock on each day for the first item that matched the criteria you entered.

This window also displays a list of items that were found. To display the graph for a different item, choose it from the list.

This report can be used as one of a set of key indicators for performance of a facility by comparing days out-of-stock of key items from one year to the next.

Graph: total stock

The total stock graph report allows you to view the value of your stock over a desired period of time. When you choose total stock graph, you are able to enter the required period which you would like to view:

Select OK and a graphical stock history report showing stock value will be displayed

Item list

This report allows you to print a list of you items in certain formats.

There are 3 options in the Report form to use drop down list:

  • Code, Name and Shelf Location: Shows exactly what is says with current stock on hand:
  • Code, Name, Shelf Location with Item Long Description: Shows the same as the previous one but includes the Item long description.
  • List of items in Catalogue: Shows item details including the catalogue pack size and item custom field 6 value all separated out by the hierarchical item category 1. Looks like this:
Local / remote report

This option will only show “local data” as an option unless you purchase a web services enabled version of mSupply, in which case you can view reports from remote locations running mSupply. Contact us for more information.

Items out of stock

Selecting this report displays this window:

Specify your required options from the drop down lists;

Days out of stock

Selecting this report displays this window:

Specify your required options from the drop down lists; the desired period may be identified either by entering dates in the From and To fields, or by using the drop down list to the right.

Clicking ok will generate a report like the one below:

Clicking the Complex find button opens the Query Editor, allowing you to enter specific criteria relating to your search.

You may also specify what level in percentage terms of the maximum stock should be considered as being “out of stock..” Here's an example over 1 month:

Day of month 123456789101112131415161718192021222324252627282930
stock on hand 20000200002000020001000500300200300002520020200180001800018000100005000500020002000800800200002000020000200002000020000200002000020000
Out of stock m(m( m( This day had maximum stock. 5% of 30000=1500 m(m(
Note the 5% stock out level = 1500
Item usage

The Item usage report gives you a breakdown of item usage for the last few months, with summaries for the last 2 years, It also includes stock on hand and stock on backorder for each item in the report.

The report produced is very useful for forecasting or for seeing a list of items that need to be ordered.

When you choose the menu item you are shown a window like this:

You can choose the type of report you want to run from the drop-down menu. Select the Item usage [Excel] report to create an Excel report.

This menu also includes an item usage report, a suggested ordering amount report, or to auto generate a tender from the drop-down list at the top. This form is used for all 7 functions. (Note that the Item usage report with pending purchase order option will show you item usage with details of items currently on order and their expected date of delivery).

If you want to report on all items, leave the item name field blank:

otherwise enter an item name or code. For example, to report on amoxycillin stocks, you could enter “amox” into the field.

Depending on the entry in the first field, further options are available in the following two fields, but these will vary according to the entry in the first field. Among the options, he first field allows you to make your selection from the names given to custom item fields in the Preferences if this feature has been used.

If you wish to use shelf locations, then select the shelf location option and specify the desired shelf.

You can use the drop-down list to find Items with a particular code, or to use the values you have entered into one of the custom user fields. If this isn't powerful enough, use the complex find button to display the full query editor.

Click the refresh button to calculate the number of items these basic parameters will find. This screenshot shows that 17 items meet the parameter specified, i.e. items whose names begin with 'pro';

Only include items whose stock cover is less than...

If you want only to report on items whose stock is low, enter the threshold for days of stock on hand into the second field. For example, entering 90 into this field will only include items in the report whose stock is not sufficient to cover average usage for the next 90 days.

The default of 0 (zero) in this field will include all items with any amount of stock remaining.

Include items with no usage in the last 12 months

If this box is checked, items with no usage over the last year will be included. This will include items for which there are no transactions at all. This check box will have no effect if the previous “days cover” field is filled in, as an item with no usage will have “infinite” cover- any stock you do have is going to last you forever!

Include usage for build ingredients

If you manufacture items, you can choose whether the use of ingredient lines in manufacturing is included in the report or not.

Open report in Excel

Checking this box opens the report in Excel (or any installed spreadsheet program).

Note: If you chose the Item usage [Excel] report from the dropdown list, the Excel box will already be checked.

If you want to save the report in Excel (or any installed spreadsheet program), choose File > Save as.

Item usage report preview

Suggested ordering report

This report shows usage data, months cover of stock remaining and a suggested quantity to order for each item. The Purchaser can review this report to make a final decision on how much stock to order.

From the Item usage report dialogue box, select the Suggested ordering report option from the drop-down menu. Alternatively, select the Suggested ordering [Excel] report to create an Excel report:

Note the extra options for including item usage when calculating item ordering quantities. Also note the option to include ordering for build items. See item builds for more on built items.

Open report in Excel

Checking this box opens the report in Excel (or any installed spreadsheet program).

Note: If you chose the Suggested ordering [Excel] report from the dropdown list, the Excel box will already be checked.

If you want to save the report in Excel (or any installed spreadsheet program), choose File > Save as.

Suggested ordering report preview

Item usage with outstanding purchase orders

The window that appears when you choose this report is the same as the previous one; with exactly the same options available; the report produced differs only in that any lines having outstanding Purchase Orders have the relevant details of the Purchase Order displayed.

Item slow movers

The Item slow movers report shows all items that have more than a specified number of months worth of stock. TIt is very useful for managing under-performing inventory and allows you to quickly to obtain a list of items where a reduction in stock might be desirable.

You will be shown a window to enter the report options:

Enter your search criteria in the top section.

Item name field
  • If you want a report for all items, leave this field blank. Otherwise enter some text to reduce the report to just a few items (e.g. entering “am” will produce a report of just the items whose name starts with “am” (Amitriptylline, Amoxycillin, etc)
Category and department
  • Use the drop down boxes as appropriate to select Category and/or Department if required.
Base analysis on X months of usage data

This is the number of months of usage data (working back in time from the current date) to use to calculate the AMC (Average Monthly Consumption). The months of stock on hand is then calculated as current stock/AMC.

Report on items that have more than X months stock on hand

Only items that have stock that will last this or a greater number of months will be included in the report. Those with less stock will not be included.

You can check the Open report in Excel checkbox to open the report in Excel, or any installed spreadsheet application.

When you click on the OK button you are taken to the printing options window:

There are two versions of this report, the standard one or one showing the individual batches of each item. Choose the one you want using the Form to use drop down list.

The standard report looks like this:

The one with batches looks like this:

Please note that:

  • The months of stock is calculated for all batches together, not for individual batches.
  • The maximum months of stock shown is 1200 i.e. 100 years! This figure will be shown for all items that have no consumption as well as those for which you genuinely have that much stock.
Expired stock

This is a customised report only available for few of our clients.

This report shows the stock that expired while it was on your shelves between the dates you seec in the options. It includes current stock that expired between the dates selected and also stock on confirmed customer invoices and inventory adjustment-reduces that was expired when it was put on those transactions (so if you removed stock from the store after it had expired, that is also included as stock that expired on the shelf).

Donor and custom stock fields are included as filter options if they are turned on in the current store.

The report looks like this when exported to Excel:

Expiring items

This report will ask you to enter a date, and will then give a report of all item lines in stock whose expiry date is before the date you have entered.

For example, entering 31/8/11 will display all items with expiry dates before 31st August 2011 (Enter the date in short format in the way your computer is set to handle dates (DD/MM/YY or MM/DD/YY or YY/MM/DD).

You can additionally filter the stock by the location type or the actual location in the warehouse. This is helpful for reporting on items in certain sections of your warehouse.

Three report type options are offered; select as appropriate. You may refine the search by using the Name filter and/or the Item filter..

Donor reporting

mSupply provides the feature of printing the Donor name on the Expiring Items report so that the organisation donating the goods can be identified and tracked. This can help with disposing of or returning goods to the Donor.

Expiring items vs. cover

The Expiring items vs. cover report shows the number of months of cover for items you have in your store. The cover calculation uses the last 12 months of usage data to calculate the AMC which is used to determine months of cover.

Many filters may be applied in the drop down lists, which are the same as described under Item usage… above.

Note that If the field you are searching is a boolean field, e.g.Essential Drug List, “false” appears as the default entry, which you may change to “true”.

Cover calculation

This allows the user to include or exclude specific categories to be used in calculating coverage. Clicking the magnifying glass to the right lists categories to be chosen.

If you wish mSupply to remember the criteria which you have entered, click on the paperclip icon, and your selections will appear the next time you open the report.

Once you have selected your required criteria, click on the Refresh icon to show the number of items which match your criteria, and which will, therefore, feature in the report.

Item ledger

Ledger entries may be viewed in this report; different formats of report are available in addition to several filter options from the drop down lists, so the report may be designed to meet your specific requirements.

The Purchases by suppliers report relates stock received to purchase orders made and looks like this:

The Stock movement with stores report looks like this:



Previous: 13.01. Report basics | | Next: 13.03. Transaction reports

13.12. Manage reports

Choosing this item shows a list of built-in reports and any custom reports which have been added to your system:

The built-in reports may well be sufficient for your needs, but mSupply's versatility allows you to add and manage custom reports to meet any specific requirements you have.

Options in the Report Management window:
Delete selected reports

Report(s) no longer required may be selected and deleted from mSupply. This only applies to custom reports (cus in the Type column); standard reports (std in the Type column) cannot be deleted.

Disable reports

You can disable reports that you no longer wish users to be able to select when printing. Do this by checking the checkbox in the report's Is disabled cell. This applies to ppro type reports only (see the Editor column); qrep type reports cannot be disabled.

Duplicate report

Should one of the built-in reports not quite meet your needs, you have the opportunity to create a duplicate of that report, and then modify it to meet your needs. The first step is to select the closely matching in-built report; in our example we'll use the expiring_items_date report, then click on the Duplicate report button;

the window that appears has already selected a name for your report, using the name of the in-built report prefixed by “my_ ”; you may change this name should you wish. The Permissions drop down list allows you to specify users having access to your report; the options are All users , or Only me . Should you wish your report to become the default one rather than the in-built report, then check the Make default checkbox. When you click on OK, the report you have just created now appears at the foot of the list of reports from the item on the menu Report>Manage reports.

Edit report

The editing of reports using the powerful editor has been extensively covered earlier in this section.

Using the report editor is complex, but it has the potential to produce a wealth of useful information. Contact Sustainable Solutions for a link to download a separate manual on the subject.

Note that in a multi-user installation, changes you make to a report will affect all users, so don't change a report without some forethought.

Add report

Click on this button, and the following window appears:

Report type: Select the type of report you are going to add; PagePro if it was created using the PagePro editor, Quick Report if it was created using the Quick Report editor (shown in the Edit report section above) or PPro Multiple if you want to select 2 or more previously created PagePro reports to be printed out at the same time.

Custom name: Enter the name the report will have in the system. Users will select this from the appropriate list to run the custom report.

Permissions: Defines who has permission to edit this report, you only or everyone who has the Edit reports permission (“All”). Normally you would set this to “All”.

Type of form: This defines where your report will appear in the system i.e. its context in the report manager list (Note: this only applies to PagePro reports, not Quick reports - Quick reports do not have a type). For example, if you select “Pick list” then the custom report will be available when a printing a suggested status customer invoice, if you pick “Supplier invoice” it will be available when printing a supplier invoice. If your custom report should be available as a normal report and not for some specific purpose in the system then select “Report” here.

Comment: Enter anything here that you want to remember about the report or to help you recognise it in the future. The comment will only appear in this window, when you open it to edit the settings of the report in the future.

Make this report default: Check this box if you want your report to be the default one of this type for all users of the system. You would check this if, for example, you were adding a new supplier invoice printout that everyone should use.

Report file: This is the actual file containing the report. Locate it on your computer using the Open button.

Revert selected reports

This button allows intrepid souls to save face by undoing the damage they have done to a particular report! The report that was installed with mSupply will be reloaded from the disk, and any changes you have made to the version stored with the data will be discarded.

Revert all

This button returns all in-built reports to their original state when you installed mSupply; exercise caution when using it. Custom reports which you have designed are not affected.

Save selected reports

All reports are automatically saved by mSupply in the default folder. There may be occasions when you wish to save one or more reports on a removable storage medium - e.g. a pen drive - and this button allows you to do this; a window appears allowing you to specify the location in which you wish to save the selected reports.



Previous: 13.11. Other reports | | Next: 13.13. Saving report templates

13.11. Other reports

ABC analysis

This report will rank the items based on the value sold in the period specified. Sometimes such a report is referred to as an “ABC” analysis or a “pareto” analysis. Statistics show that 20% of the items supplied by an organisation usually generates 80% of the total value of sales. Therefore, it is useful (and wise!) to concentrate first on the 20% of items that are most important. This report makes it easy to do just that.

You might be interested in what Wikipedia has to say about ABC analysis

You need to enter the following information:

Number of items to include in report: Enter the number of items to be included in the report.

Date range: Enter the dates you wish here. Each item will have its “analysis” field updated with the total value of sales during the period specified.

Filters: Should you wish to apply filters to the report, three are available - for items, categories and departments.

Which mode: You can choose store mode, dispensary mode or both modes of transactions for inclusion in the report.

Exclude Ad Hoc and non stock items: If you check this box then Ad Hoc and non stock items will not feature in the report.

The report lists the number of items specified, ranked by value of sales, starting with the highest. The value of sales and the percentage of the total value are also shown. Note that the total value is the total for the items in the report, not the total sales for all items. If you want to report on the total for all items, set the Number of items to report on to a number greater than the number of items in your data file (Note that this may make the report very long, but you can choose just to print the first few pages if you wish).

Management summary

This report is designed with line managers in mind, or other people who want to “keep their finger on the pulse” of their organisation but are not interested in the fine detail!

You'll be shown a window where you can choose a date range for the report:

The report provides the following information:

  • The total value of stock on hand
  • The 10 items with the largest stock value
  • The 10 items with the largest value of supply to customers in the date range chosen.
  • The 10 suppliers from whom you have purchased the most in the date range chosen.
  • The 10 customers to whom you have supplied the most in the date range chosen.
  • If you check the “Include section on expiring items” checkbox, a section will be included that lists:
  • The cumulative liability for expiring items for each of the next 12 months.
  • The 12 most valuable expiring items (or at least batches of particular items)
Preview on screen before printing

Check this box if you want to view your report on screen first.

Open report in Excel

Check this box to view the report directly in your chosen Spreadsheet program.

Quotation summary

There are two options in Report on section, namely: All quotations and Preferred quotations , and there are two options in Group together by section, namely Supplier and Item

All quotations shows the quotations in which Preferred is set to “true or false”.

Preferred quotations shows only those quotations in which Preferred is set to “true”.

Supplier option displays the quotation report on the basis of supplier.The quotations for the items related to a particular supplier are listed along with that supplier.

Item option displays the quotation report with the items arranged in alphabetical order along with the corresponding supplier's name.

In addition there are filters allowing you to narrow your search further by:

  • limiting the report to suppliers meeting your specified criteria - e.g. the supplier's name code may be entered, so the resulting report will display only quotations from that particular supplier.
  • specifying criteria relating to the item by choosing from the many options in the drop-down boxes as shown below:

There is an additional filter, the Date filter, allowing you to specify the dates on which the Quotations you are examining were created or modified, and the radio button toggles display of the quotations' expiry date ( Quotation valid date ) on or off.

Sync report

This report allows you to track simple remote site activity. There is more in depth remote site activity available on the mSupply dashboard (see the https://docs.msupply.foundation/dashboard/introduction/ page for details). To run it, choose Report > Sync report… from the menus. There are no filters and the report will open automatically in your default spreadsheet application. It looks like this:

Debtors and creditors

The following reports are available:

Select the required report by clicking on it.

Debtors

This report will produce a list of all debtors. mSupply uses an open-invoice system of accounting for debtors, so the outstanding amount for each debtor is displayed; for debtors with more than one invoice outstanding, the amount displayed is the cumulative total of all outstanding invoices.

Note that the total outstanding on invoices is not reduced for any previous overpayment by a customer, but this is listed in a separate column in the report.

To remove overpayment amounts from the system, choose customer | new payment… and enter the name of the customer with an overpayment. You will be asked if you want to use the overpayment amount for this payment. Choose use, then allocated the overpayment to outstanding invoices.

Creditors

Aged debtors

Customer statements

You will be presented with a window to find customers.

If you want a report for all customers, leave the entry field blank. Click OK and a report will be produced for any customers who match the criteria entered. Note that customers with no amount outstanding will not have a statement printed for them.

Transport report

This report allows you to print information about the transport details for a range of invoices.

First you are shown a window where you can select a date range and choose to report on only invoices supplied by a particular method, by a particular responsible officer, or to a particular name or names.

Click “OK” to run the report.
Note that transport details can only be entered on customer invoices if you have checked the “We use box numbers” option in the Preferences

Prescriber report

The Prescriber report allows you to view the total value, mean item value and item count for prescriptions dispensed for each prescriber.

You will be shown a window with the normal date range options, and the option to report only on prescibers whose type field is set to a certain type.

Click OK to proceed.

The window that appears is the Transactions report, but you will see that the Prescribers report is highlighted.

As usual, the report options window is shown where you can choose the destination and set headers and footers.

User activity totals

This report was initially made for use in dispensing situations where you want a quick count of the number of prescriptions and items issued in a day. However, it is also useful for getting a quick view of workload for a month or a year in store mode. This report gives the number of supplier invoices (or prescriptions) and the number of stock lines on them, reported by user.

Choosing this menu item shows a window like this (once you have selected a date range).

You can drop down to view data by clicking on the green arrows. Alternatively, you can click on the printer icon on the bottom right and export the full list to Excel.

Date range

You can either enter dates manually or choose from the drop-down list to the right of the date fields.

Time range

Enter times here in 24 hour format (e.g.. 9:00 in the “from” field and 17:00 in the “to” field. Leaving these fields on 00:00:00 will calculate for the whole day.

To calculate totals, click the Show button. If there are a lot of transactions to evaluate, a progress bar will be shown.

Click the OK button to close the window when you are finished.

Backorder report

This report shows the backorders that have been placed for items. Backorders are made when there is insufficient stock to meet the requirements of an order placed by the customer. Information about the item code, item name, current stock, customer code, the backordered quantity (number of units, not packs) and the date of the backorder is displayed.

If you are running a backorder system this gives you a quick way to check if backordered items are now in stock so they can be supplied to customers.

Suggest price list additions

Note: the price list menu items are for those organisations that produce a price list or price indicator. (It is useful to call your publication a “price indicator”, as it implies the published price is a guide, and not a fixed price). You are asked to specify the number of transactions and the number of months (e.g. 2 transactions in the last 3 months) that would make an item eligible for inclusion in the price list. A search is performed using the criteria you enter, and a list of items is shown that meet the criteria but are marked as not being in your price list. You can double-click on items in the list and click their “price list” check box to add them to the price list.

Update price list

This item updates the catalogue or price list prices of items with prices from their current stock lines. All items have separate catalogue prices in each store and they are displayed on the Misc tab of an item's details window catalogue (see the 4.01.03. Items - Misc(ellaneous) tab page for details).

When you click on the Update price list option, the report options window is shown, allowing you to check what price is used:

  • the price of the largest batch in stock: sets the price list (catalogue) price to the sell price of the batch with the largest number of units (pack size x number of packs) in stock.
  • the price of the highest priced batch in stock: sets the price list (catalogue) price to the sell price of the batch with the highest price (i.e. highest sell price/batch pack size value) of all current batches in stock.

Note that in both options, the Catalogue pack size is also set to the pack size of the batch that is used to set the catalogue price.

Only items whose On price list check box is checked are updated. If no items have this checked then mSupply aill tell you so and the update won't run.

Note that if an item has no stock, then the price for that item will not be altered.

mSupply will show you the progress of the update and will also tell you when it is complete.

It is a good idea to run the “suggest price list additions” report before running this function.

Price list

Only items that are marked as included in the price list (Item > Misc tab) are placed in a report, whether or not you have any in stock.

If you wish to export to a text file, choose “save to disk” in the report options dialog that is shown.

The exported file has fields separated by tabs and records separated by returns. The field order is:

  • Item
  • pack size
  • price.

If you wish to include different information, you can create a custom report to do this.

Location report

This report is available in version 1.96 and later.

This report lists the location description, type, capacity, used volume and percentage available. Choosing this menu item shows you the location report filter options widnow as below:

The report may be restricted to certain locations by using specific search criteria. Choose either “Code” or “Volume” from left drop-down list is . The centre drop-down list allows you to choose a comparitor.

You have to make an appropriate entry on the right-hand field. Leaving the field blank means no filter will be applied.

Location type

It allows you to choose a location type. You can select the one from the drop-down list on the right side. The graphic of location type is shown below.

For example, you can specify the location type“COOL” to show only refrigerated locations.

Check the “open in Excel” checkbox if you wish to directly open the saved report in Excel (or any installed spreadsheet).

Click the OK button to run the report.

Manage reports

Choosing this item shows a list of built-in reports and any custom reports which have been designed:

The built-in reports may well be sufficient for your needs, but mSupply's versatility allows you to manage the reports to meet any specific requirements you have.

Options in the Report Management window:
Delete selected reports

Report(s) no longer required may be selected and deleted from mSupply

Duplicate report

Should one of the built-in reports not quite meet your needs, you have the opportunity to create a duplicate of that report, and then modify it to meet your needs. The first step is to select the closely matching in-built report; in our example we'll use the expiring_items_date report, then click on the Duplicate report button;

the window that appears has already selected a name for your report, using the name of the in-built report prefixed by “ my_ ”; you may change this name should you wish. The Permissions drop down list allows you to specify users having access to your report; the options are All users , or Only me . Should you wish your report to become the default one rather than the in-built report, then check the Make default checkbox. When you click on OK, the report you have just created now appears at the foot of the list of reports from the item on the menu Report>Manage reports.

Edit report

The editing of reports using the powerful editor has been extensively covered earlier in this section.

Using the report editor is complex, but it has the potential to produce a wealth of useful information. Contact Sustainable Solutions for a link to download a separate manual on the subject.

Note that in a multi-user installation, changes you make to a report will affect all users, so don't change a report without some forethought.

Add report

Click on this button, and the following window appears

Revert selected reports

This button allows intrepid souls to save face by undoing the damage they have done to a particular report! The report that was installed with mSupply will be reloaded from the disk, and any changes you have made to the version stored with the data will be discarded.

Revert all

This button returns all in-built reports to their original state when you installed mSupply; exercise caution when using it. Custom reports which you have designed are not affected.

Save selected reports

All reports are automatically saved by mSupply in the default folder. There may be occasions when you wish to save one or more reports on a removable storage medium - e.g. a pen drive - and this button allows you to do this; a window appears allowing you to specify the location in which you wish to save the selected reports.



Previous: 13.10. ATC and DDD code based reports | | Next: 13.12. Manage reports

13.15. SuperReport editor

  • mSupply includes the SuperReport editor plugin.
  • This gives almost unlimited customisation possibilities for forms and reports.

Due to security issues, report customisation using SuperReport can only be done by Sustainable Solutions. Contact us for more details.



Previous: 13.14. Custom reports | | Next: 15. Barcode Scanning

13.04. Purchasing reports

Purchasing reports (focused on what you have ordered and what you have received and what you want to order) are available at Report > Purchasing. The following report types are available:

The first 2 options contain several different reports (see below). Select the required report type by clicking on it.

Purchase orders

Types of report

There are seven reports currently available:

  • The Ordered Item Report will list items that are on Purchase Orders according to criteria specified.
  • The Goods Received date vs Order date report lists each Goods Receipt for a particular Purchase Order and the number of lines received, then follows with details of the number of lines and date of the original Purchase Order, as in the example below. This is useful for tracking supplier delivery performance.

Note that the number of lines received may not match the number ordered as a single Purchase Order line may be supplied in split deliveries, as in example shown, or an ordered line may not be supplied at all.

  • The Goods Received date vs Order date - Show items report.
  • The Outstanding Purchase Order Lines report, which will display all Purchase Order lines for Purchase Orders provided that
    (1.) delivery is incomplete, and
    (2.) the Purchase Order has a Confirmed (“cn”) status.
  • Note that Purchase Orders whose status is Finalised (“fn”) will be ignored when producing this particular report.
  • The Goods Received date vs Order date - show Delivery days report shows the number of days taken to deliver items.
  • The Purchase order vs goods received broken down by batches report shows the dates particular batches were received.
  • The Purchase order cashflow planning report shows you the values and times of expected deliveries so that you can plan when money needs to be available to pay for them.
Date range and date type

A date option, for selecting which items/purchase orders to include in the report must be selected; options are:

  • creation date - the date purchase orders were created
  • sent date - the date purchase orders were confirmed
  • expected delivery - the expected date of delivery for items
  • actual delivery - the actual date that items were delivered

The report will include items/purchase orders with the selected type of date falling between two specified dates entered in the From and To fields. The drop-down list on the right affords many quick-choose preset date range options such as “today”, “yesterday”, “this week”, “last week”, “this month” etc.

Report on names...

The report may be confined to suppliers meeting specific criteria by selecting one of several supplier properties (“Name”, “Name code”, “analysis”, “category”, “Price code” etc.) in the left dropdown list, “equals”, “starts with” or “contains” in the centre dropdown list and making an appropriate entry in the field on the right. If this field is left blank, the report will include purchase orders from all suppliers within the chosen date range.

Report on items...

Similarly the report may be confined to items meeting specific criteria; you choose an item's property to filter on in the left dropdown list followed by the comparator in the centre dropdown list and finally making an appropriate entry is made in the field on the right. Again, leaving this field blank will produce a report on all items within the chosen date range.

You can also report on items that have a certain category and/or department. By default these options are set to “Don't care”, which means the item categories and departments will be ignored.

Note that only reports that report on invoice lines will produce meaningful results when you choose item criteria. Reports that report on whole transactions (e.g. “Each invoice grouped by name” or “Each invoice grouped by date”) will not produce meaningful data, as any one invoice can contain multiple items. Choose reports that report on invoice lines (e.g. “Each invoice line by item” or “Totals for each item grouped by month”) for these filters to have an effect.

Report on purchase orders...

In the same way, you can also filter your reports on properties of the purchase orders involved: category, status and both purchase order custom fields. For more information on purchase order categories see here.

Please note there is also a Purchases by suppliers report that relates stock received to purchase orders made. This is one of the item ledger type reports and details can be foiund on the 13.02. Stock and items reports page.

Purchases

This report finds all purchasing transactions over a certain value within a specified time period

You should enter:

  • The date range of transactions on which to report
  • Four filters are available to refine the report - a name filter, and three item filters; all are optionally and will be ignored if nothing is entered in the textbox or drop down lists are left at “Don't care”.
  • The value of a transaction line above which the report will cover.

It may be good for your organisation to have a purchasing policy that stipulates that transactions over a certain value must be authorised by a second party (that is, someone other than the purchaser). This report allows you to monitor such a policy easily.

Suggested order quantities

Use this report for mSupply to analyse your current stock and, based upon a required number of months of stock cover which you enter, suggest how much of each stock item you should consider ordering.

There are currently 3 options for the suggested order quantities report: Suggested ordering report, Suggested order quantities with prices and price extension (see below for details on this report and its additional option) and Suggested ordering [Excel] report. They all have the same options as defined below but the last two will run much more quickly than the first one, even if the first one is exported to Excel. This is a temporary situation: the first option will be removed in a later version of mSupply and the last two will be the only options available.

Quantification

Some logic behind the calculations involved in this report is described in detail on the 6.01. Ordering stock from suppliers page.

As of version 7.15, mSupply supports a wide array of options for calculating forecast Average Monthly Consumption (AMC), which is then used to forecast needs and then to calculate a requested order quantity.

The options are:

Don't Adjust AMC

This has been the default in mSupply up until this point. The historic consumption is summed up for the number of months specified in the lookback field, and divided by the number of months. This works well if the item was fully stocked for the whole time. This method results in the forecast AMC being too low if stock was low or zero in the past.

Consumption vs Distribution vs Issuance: Stock may be consumed within the facility for the care of patients, or distributed to other facilities, but for the purposes of the supply chain, whatever a store issues out of stock is 'consumption', and these terms all have the same meaning. In mSupply, we use the term Consumption.

Adjust by % of days out of stock

This method takes each historic month's consumption, and adjusts it for the number of days in the month the item was out of stock. We multiply the consumption for the month by (Days in month divided by Days in stock) to get an Adjusted AMC Take this example for a single month where Item B had nil stock for a period of time:

  • Item B was in stock for 10 days in the month
  • Its historic consumption was 500
  • The adjusted AMC is 500 x 31 / 10 = 1,550
Only consider fully stocked months

Here, we are attempting to address months with low stock by excluding them from our calculations, rather than adjusting their consumption. There is a field shown % of days in stock to be considered fully stocked that defaults to 90%

For this method to work, you need to set the lookback period long enough that mSupply will be able to find enough fully stocked months to run the calculation. You can also include more low stock months by setting the % of days in stock to be considered fully stocked field to say) 50%. Do this with caution, as there is a real danger that it will result in an underestimate of AMC.

mSupply's better algorithm

We've tried to come up with a better algorithm here by:

  • ignoring months that are in stock for < 33% of days. That is, if the item was in stock for less than 10 days in the month, the consumption on those days is too erratic to draw conclusions about what the consumption for the whole month would have been.
  • For months with stock >= 33% of days, Multiply the consumption for the month by √(Days in month/Days in stock) to get adjusted AMC. This adjusts the consumption up due to being out of stock, but by a factor up to 1.7 - so not as big an adjustment as the “Adjust by % of days out of stock” method.
  • We also ignore months where the mean stock on hand is less than “% of typical AMC that stock level is considered compromised:” value you enter. This is a bit complicated, but here's an example:
    • Consider Item A - we have set the “when we calculate consumption there are 3 months that were “fully stocked” - those three months give us an AMC of 1500 per month.
    • Now, there's another month that was fully stocked (as in, on all 31 days in the month, there was some stock on hand.
    • But it turns out that the average stock on hand was only 50 - clearly they could never have had “normal” consumption, although they did have stock - if the cut-off is set to 100%, we're saying “ignore this month unless the average stock on hand was 1500 - in this case it's 50, so this month isn't used in the AMC calculations

We then sum the adjusted consumption for all the eligible months & divide by the number eligible months to get the best forecast AMC eva ;-)

Here's a diagram:

graph TD A(Was the Month fully stocked?)-->|Yes|B(Use consumption from these months to calculate typical AMC) A-->|NO|C(Ignore these months) B-->D(Was there months having <10 days with stock)-->|Yes|E(Ignore these months) D-->|No|F(Increase consumption with adjusted AMC to account for days out of stock for these months) classDef OR fill:Orange class A,B,C,D,E,F OR

Let's take an example of how this is done:

Lets say we are using:

Step 1: First we are adjusting by % days in stock to be considered fully stocked. This calculation will be used in Step 2 to calculate the typical AMC. So if this is set as 90%, only months with ≥90% stock will be considered. In this case, Nov 2023 (202311) and Oct 2023 (202310) are excluded as it is less than 90%.

Step 2: We then calculate the typical AMC which excludes the months Nov 2023 (202311) and Oct 2023 (202310) from step 1. To do this, we use: (Total consumption of only months included in Step 1)/(Number months usage basis) = 100 / 7.8 = 12.82. Red coloured boxes indicate exclusion. (Note: We have 7 full months, and 0.8 of a month due to July 2024 (202407) as 26 days is 0.8.

Step 3: Next there is an automatic exclusion for days of low stock ≥33% in the month. Note: This is automatic and is not set by the user. In the example, this is Nov 2023 (202311) as it is the only month with less than 33% days in stock in the month.

Step 4: Now we consider the criteria of “100% of typical AMC that stock level is considered compromised” which we entered in the Report options. Since this is set as 100% by us, we now take the typical AMC (12.82) and check the Mean SOH of each month to make sure that this is equal or higher than 12.82. If stock level is not higher than 12.82, that month will be excluded from the Adjusted AMC calculation (Step 5). Note: If we had selected 90% of typical AMC to be considered compromised, this means we will be looking at 90% stock or more of the typical AMC (12.82) and anything less than this will be excluded.

To now obtain the number of months to be considered for the adjusted AMC: We will exclude the 33% low stock month from Step 3. We will exclude any months with (x)% typical AMC stock level that is considered compromised (which in this case, there is none). We will be including the month with 11 days in stock however, as it is more than the 33% exclusion step and the first step where it was excluded was just for calculating what months to use for typical AMC.

From the example, we will now have 8.8 months that we will be considering for the Adjusted AMC.

Step 5: We can now calculate the Adjusted AMC with the formula: Square root[(Days in month)/(Days in the stock)] * Consumption We check this individually for each month that has not been excluded. So, if the “Days in month” = “Days in Stock”, the square root of this = 1. In Dec 2023 (202312) = 1 x 100 (consumption) = 100. In Oct 2023 (202310) = Squareroot(31/11) = 1.6787. Then 1.6787 x 100 (consumption) = 167.87.

Add these together: 100 + 167.87 = 267.87 total for all included months that we will use to calculate adjusted AMC.

Step 6: For the Adjusted AMC = 267.87/8.8 months = 30.34 units per month.

Steps Summarised:

Step 1: Adjusting by % Days in Stock

  • Set threshold for fully stocked (e.g., 90%)
  • Exclude months with < 90% stock

Step 2: Calculate Typical AMC

  • Use months not excluded in Step 1
  • Calculate Typical AMC = (Total consumption of only months included in Step 1)/(Number months usage basis)

Step 3: Automatic Exclusion for Low Stock

  • Exclude months with < 33% days in stock

Step 4: Compromised Stock Level Check

  • Set threshold (e.g., 100% of typical AMC)
  • Exclude months below threshold

Step 5: Calculate Adjusted AMC

  • Apply formula to each included month = Square root[(Days in month)/(Days in stock)] * Consumption
  • Sum the results

Step 6: Final Adjusted AMC Calculation

  • Divide total consumption by number of months
  • Calculate Adjusted AMC

Note: If all months have been excluded due to the first or second exclusion criteria, then the typical AMC calculation will automatically be used instead.

Report options

You'll see this window:

If you want to report on all items, leave the item name field blank, otherwise enter an item name or code. For example, to report on amoxycillin stocks, you could enter “amox” into the field.

The drop down list, after the item name and code choices, lists several other fields, including any user defined fields, where the names that you have defined for custom item fields in the Preferences are displayed.

If you wish to use item categories, then use the Item category list to choose the one on which you want to report.

You can use the drop-down list to find Items with a particular code, or to use the values you have entered into one of the custom user fields. If this isn't powerful enough, use the Complex Find button to display the full query editor.

Click on the refresh button (double orange arrows) to show the number of items these basic parameters will find.

Only include items whose stock cover is less than…: If you want to report only on items whose stock is low, enter the threshold for days of stock on hand into the second field. For example, entering 90 into this field will only include items in the report whose stock is not sufficient to cover average usage for the next 90 days.

Enter “0” (zero) for this field to report on items with any amount of stock remaining.

Expected delivery: Enter an appropriate date that you expect the stock to arrive with you based on previous delivery times.

Include usage for build ingredients: If you manufacture items, you can choose whether the use of ingredient lines in manufacturing is included in the report or not.

Basis of analysis: Enter the number of months of data (form the current date) mSupply should use to calculate your consumption.

Exclude transfers from calculations: Check this box if you wish transfers within your organisation to be excluded from the calculations.

Include items with no usage in the last 12 months: If this box is checked, items which have not been used over the last year will be included. This check box will have no effect if the previous “days cover” field is filled in, as an item with no usage will have “infinite” cover- any stock you do have is going to last you forever

Months stock required: In this field, enter the number of months stock cover you want to have available. The report will automatically take into account any stock you already have, so all you need to do is enter how many months cover you want.

AMC Adjustment for Out of Stock: See the “Quantification” discussion above on the different options available.

Exclude stock that will expire within 3 months of projected consumption date a checkbox that allows you to accurately predict the amount of stock that is likely to be wasted due to expiry and current consumption rate. In this current example, mSupply will only aim to distribute stock if the expiry is more than 3 months away. This updated feature is only available in mSupply v7.12 or later.

This topic is huge so it may be worth reading this topic Stock wastage prediction for ordering

Open report in Excel: Checking this box opens Excel (or any other installed spreadsheet application) and displays the report as a spreadsheet. If you want to save the report, choose File > Save as… in your spreadsheet application.

Report output

A typical `Suggested Order` report will look something like below.

Definitions of each column after item properties:

  • Stock on hand : Total quantity of stock currently available in your inventory
  • Expiring stock : Calculated by (Total stock that is set to expire) - (Daily stock usage [which is derived from the AMC e.g., AMC / 30 days if 30 days in the month]). The amount of expiring stock to be accounted for is selected in the reports option:

  • Effective SOH : Calculated by ('Stock on hand') - ('Expiring stock'). This is the usable stock available.
  • Backorder : Quantity of stock that has been ordered by customers but not yet fulfilled due to insufficient stock.
  • Stock on order : Quantity of stock that has been ordered from suppliers and is expected to arrive but not yet received.
  • AMC 12 months : Average quantity of stock used per month over the last 12 months.
  • AMC 24 months: Average quantity of stock used per month over the last 24 months.
  • Monthly usage for the last (x) months : Calculated by ('Total consumption for the last (x) months of usage data') / ('(x) months of usage data'). This value is set by the user in the Report options:

  • Number of months considered for adjusted AMC : After the AMC adjustment is made (and months with low stock has been excluded), this value indicates the number of months that have been included for calculating the adjusted AMC. This value is derived from whichever formula has been chosen in the “AMC Adjustment for out of stock”:

  • Adjusted AMC : This adjusted value is based on the formula selected in the Report options:

  • Number of months in stock : Calculated by ('Effective SOH') / ('Adjusted AMC'). This gives the number of months the current stock will last based on adjusted consumption rates.
  • Ordered Quantity used : This is how much of the stock you have ordered that you will actually need to use, based on how much you use each day and how much stock you already have (Note: forecast calculation will affect this). This is determined by:
    • Calculate the “usage per day of stock” = AMC / 30.4375
    • Multiply “usage per day of stock” with the “total number of days in your months stock required” to get “Total usage required” = Usage per day of stock x Total number of days in your months stock required
    • Calculate your “Future stock on hand” = Stock on order + Effective SOH - Backorder
    • Subtract “Total usage required” from “Future stock on hand” to get the “Net stock difference to be used” = Total usage required - Future stock on hand.
    • This value (“Net stock difference to be used”) now determines the “Ordered Quantity used”.
      • If the value is a negative value and there is “Stock on order”, add the “Net stock difference to be used” with “Stock on order” = “Net stock difference to be used” + “Stock on order”
      • If the value is a positive value and there is “Stock on order”, if “Net stock difference to be used” is greater than “Stock on order”, the “Ordered Quantity used” will be the same value as the “Stock on order” as all the stock on order will be used up.
  • Suggested Order calculated by:
    • If expected delivery date has not been adjusted: ('Months stock required' x 'Adjusted AMC') - ('Effective SOH' - 'Stock on order') + 'Backorder'.
    • If expected delivery date has been adjusted, this will be accounted for as it will only look at the stock required from date of expected delivery to the end of months stock required:
  • Usage per day = Adjusted AMC/30.4375 (which is from 365.25/12 which is days in the full year)
  • Suggested order quantity = Usage per day x Days needed (which is 'Expected delivery date' - End date of the 'Months stock required', or days needed in total - days of lead time) - ('Effective SOH' - 'Stock on order') + 'Backorder'
  • This determines the quantity of stock that needs to be ordered to maintain the desired inventory levels after considering current stock, back orders, and stock already on order.
  • Note: if you are using the “Minimum stock” function, the suggested order will also take this into account to ensure that there is enough stock to meet this value. This will be calculated by taking the minimum pack size to cover the minimum stock.
  • Note: if you are using forecasting this can affect suggested order quantity. Please check forecasting settings on mSupply if it is indicated as being used in the spreadsheet.
  • Note: The “maximum” quantity field is only a UI feature and does not have any other functionality apart from allowing users to see their recorded maximum quantity. Anything in this field will not be accounted for in the SOQ report.

  • Forecast used : Based on forecasting options under “Usage” in “Item details” if this has been used or not (yes / no):

For a more detail guide click on this topic : Stock wastage prediction for ordering.

Suggest order quantities with prices and price extension

This report is an extension of the previous one, allowing you to see what the suggested order will cost. The filter choices you have are the same as for the suggested order quantities report but you get an additional option to say how your suggested order will be priced:

Key Columns in the report output:

  • Unit Price: Calculated via the latest price or by supplier quotes or using average prices received during the look back period. The `look back period` is the same setting that is used to calculate average monthly stock usages.
  • Price extension (Suggested): This is the predicted cost of a future order based on Unit Price.
  • Annual consumption (quantity): This is the predicted stock usage over a year based on the latest average monthly consumption.
  • Annual consumption (cost): Potential annual cost based on unit price.



Previous: 13.03. Transaction reports | | Next: 13.05. Stocktake reports

13.13. Saving report templates

Report templates are pre-set values for the filters used to create particular reports. They are a great way of assembling a set of frequently run reports and making sure they are generated with the correct settings.

Creating templates

To create a template, simply choose a report to run by clicking on its option in the Navigator or menus, choose all the filter settings that are to be part of the template then click on the Save Template button on the bottom of the report's filter window. Here's the current stock report's filter window showing the button:

You can choose settings for any of the drop down lists, checkboxes or radio buttons or enter any text in any of the text fields, in fact any of the elements that make up the filter - all will be remembered in the template. Below is an example for the current stock report which is set to report on all items with a name beginning with 'a' in the category 1 of 'Antibiotics', showing the Total stock for each item and which will be opened in Excel:

If you are in supervisor mode, you can select which stores the report is run over. The stores you include in the report are also saved with the template. The first store in the list is selected by default so that at least one store is always selected so, if you forget to select the correct stores you wish a report template to be run over, you might get a shock when you run it outside supervisor mode - the report might be run over a different store!

If you want the report to be run over the currently logged-in store only then don't create it in supervisor mode, create it while logged into any store.

When you click on the Save Template button, a window opens for you to enter the template's details:

  • Report name: Enter the name the template will have in mSupply. Make it meaningful so that you know what report you're running when you select it. e.g. “Monthly stock report”
  • Form to use for printing: Select which of the report printout forms you want to use for this template. If you have had a custom report made for you, it will probably appear in this list. If you haven't there will only be one item in this list.
  • Comment: Enter anything you want to remember about the template for you and others to see. You could enter the purpose of the report or the reason the template was created.
  • View preferences: Check the Public checkbox if you want all users to be able to see the template in the list and therefore run it. If you leave it unchecked then this template will only be visible, and therefore runnable, by you.
  • Edit preferences: Check the Public checkbox if you want all users to be able to edit the template, leave it unchecked if only you should be able to edit it. Please note that you can only edit the details on this window for a template, not the actual filter settings made on the previous screen. If you want to edit those, just delete the template and re-create it with the changed filter settings.

When you're finished, click on the OK button to save the template.

Running templates

To run the templates you have created, choose Report > Run saved report… in the menus:

or click on the Run saved report item on the Reports tab of the Navigator:

Either way, a window is displayed containing all the names of the report templates that have been created and that you are allowed to run (either you created or others created with the Public viewing preference checked):

Note that the report templates are displayed in alphabetical order of name so, if you want them to appear in a particular order in this window, put a number at the beginning of all your template names.

To run a report template, simply double-click on it and the report filter window will appear with the settings you selected when you created the report template. In this example, selecting the “Monthly stock report” template, created in the Creating templates section above, opens the report filter window like this:

Note that the filter settings are exactly the same as saved in the template. You can still manually change the filter settings in this window if you wish. Clicking on the OK button will run the report as usual and bring up the print options window:

The Form to use drop down list will be set to the form you selected in the Form to use for printing drop down list when you saved the template. Again, you are free to manually change any of the settings in this window if you want to. To finally print out the report, click on the OK button.

In this way, you can see that to run any particular report template takes only 3 mouse clicks, no typing and no thinking. That's very helpful if you have to run the same set of reports every month for example!

Editing and deleting templates

To edit or delete report templates, choose Reports > Manage report templates… in the menus or click on Manage saved reports on the Reports tab of the Navigator to open this window:

The table contains a list of all the report templates that have been created in the system.

The Quick search text field allows you to filter which templates are displayed: only templates with names containing the text you type in here are displayed in the list. Handy for finding a particular template if there are a lot in the list.

  • Delete button: to delete a template, click on it in the list to select it then click on the Delete button to delete it. After you confirm the deletion the template will be removed.
  • Run button: select a template from the list then click on this button to run it (same as selecting Report > Run report templates… from the menu and selecting the template there).
  • Duplicate button: you can duplicate a template by selecting it in the list and clicking on this button. The duplicate is added to the end of the list and has the same name as the template you selected but with “ [duplicate]” added to the end.
  • Edit button: To edit a report template either select it in the list and click on this button or double-click on it in the list. When you do so, the template's details window is displayed and you can edit the details as required: Note that these are the only details you can edit for a template; you cannot edit the template's filter settings. If you want to do that, delete the template and re-create it with the new filter settings.



Previous: 13.12. Manage reports | | Next: 13.14. Custom reports

13.06. Requisition reports

You can report on requisitions in 2 ways:

  • grouped by item, showing which customers the item was requisitioned by, what has been sent and what is outstanding or
  • grouped by customer, showing which items a customer has requisitioned, what has been sent and what is outstanding.

You can access the reports from the Reports > Requisitions menu option of by clicking on the Requisitions option on the Reports tab of the navigator:

Whichever way you choose, the requisition report options filter is displayed:

Use the Report type drop down list to select which type of report you would like: Grouped by item, Grouped by Item (Pivot table/Excel friendly) or Grouped by customer.

The Grouped by item and Grouped by Item (Pivot table/Excel friendly) reports have the same contents, they are just formatted slightly differently. The Grouped by Item (Pivot table/Excel friendly) format is made to be immediately usable as a pivot table in Excel; a blank row between the column headers and the data, no gaps in the data and no total rows (see screenshots below).

The Requisition filter settings enable you to select which requisitions you want to include in the reports, based on their entry date (this month so far is set by default but note the quick date selection drop down list and the date pickers to enable quick selection of reporting dates) or status.

If you leave the Include lines that have been fully supplied checkbox unchecked, the report will only include lines where not all the stock requested has been sent to the customer i.e. outstanding requisition lines only. If you check the checkbox, all requisition lines will be included in the report.

If the Issued quantity accounts only for confirmed and finalised customer invoices checkbox is checked then the Quantity already issued column in the report (see below) includes quantities issued on confirmed or finalised status customer invoices (created from the requisitions) only. If it is not checked then quantities on all status customer invoices are included in the report.

The Item filter section allows you to select which items will appear in the report (only requisition lines for items matching these filters will be included in the report. If you don't set any of these, there will be no filtering by item.

Finally, the Requisition customer filter section allows you to select the customers whose requisitions will be included in the report. If you don't set anything in this section, requisitions for all customers will be included in the report.

Output

The Type column tells you what type of requisition the information came from:

  • response (from purchase order): a requisition created from a purchase order made in the customer's store.
  • response (from requisition): a requisition created from an internal order (request requisition) made in the customer's store.
  • response: a requisition made for the customer in the supplier's store.

The other fields are all self explanatory and are shown in the screenshots below.

Note that all the columns that refer to a quantity of an item (e.g. Their stock on hand, Quantity requested, Quantity already issued and To be supplied) refer to the number of units, not the number of packs.

Examples

These are examples of what the requisition reports like like: Grouped by item

Grouped by item (Pivot table/Excel friendly))

Grouped by customer



Previous: 13.05. Stocktake reports | | Next: 13.07. Dispensary/prescription reports

13.05. Stocktake reports

Stocktake reports enable you to report over multiple stocktakes. If you want detail from a single stocktake, there are several options for reports you can run from within a stocktake, see the 4.17. Stocktakes page for details.

Choose Report > Stocktakes… from the menu. The report options window opens:

  • From and To dates: Enter the range of dates of stocktake to include in the report. This range will be compared to the Stocktake date of a stocktake, not its created date. Enter the dates manually, by clicking on the calendar icons or selecting something from the quick range chooser drop down list on the right.
  • Include stocktakes with suggested (sg) status: If this is checked then lines from stocktakes with suggested status will be included in the report.
  • Include stocktakes with Finalised (fn) status: If this is checked then lines from stocktakes with finalised status will be included in the report.

When you have entered your various choices, click on the OK button to run the report. The report will be created and automatically opened in you spreadsheet application. It looks like this:

The report shows details of all the stocktake lines on stocktakes that match the report filters you selected above. The lines are grouped by stocktake and shown in line number order. What the columns contain:

  • Status: The status of the stocktake this line came from.
  • Stocktake date: The stocktske date of the stocktake this line came from.
  • Line number: This stocktake line's line number.
  • Location: The location of the stock in this stocktake line.
  • Item code: The code of the item this line is for.
  • Item name: The name of the item this line is for.
  • Brand name, Sources of supply and Project: The values entered for custom stock fields (see the 16.01. General preferences page for details). Any custom stock fields that are turned on will appear here and the column headings will be the names the fields are given in the settings.
  • Snapshot expiry date: The expiry date for this stocktake line when the stocktake was created. Will be “00/00/00” if the line was added after the stocktake was created.
  • Expiry date: The expiry date for this stocktake line when the stocktake was finalised (also called the “counted expiry date”).
  • Snapshot batch: The batch of this stocktake line when the stocktake was created. Will be empty if the stockline was added to the stocktake after creation.
  • Batch: The batch of this stocktake line when the stocktake was finalised (also called the “counted batch”).
  • Snapshot packsize: The packsize (number of units in a pack) for this stocktake line.
  • Snapshot quantity: The number of packs of this stocktake line when the stocktake was created.
  • Stocktake qty: The number of packs of this stocktake line when the stocktake was finalised (also called the “counted packs”).
  • Snapshot qty units: The number of units of this stocktake line when the stocktake was created (= Snapshot packs x Snapshot quantity).
  • Stocktake qty units: The number of units of this stocktake line when the stocktake was finalised (= Snapshot packs x Stocktake qty). Also called “counted units”.
  • Difference units: Stocktake qty units minus Snapshot qty units (can be negative).
  • Absolute difference: Difference units with any negative sign removed.
  • Comment: The comment entered for this stocktake line.
  • Reason: Only shown if reasons are being used (see the 16.10. Options (standard reasons) page for details) and there is a reason entered for one of the stocktake lines included in this report. The column shows the reason chosen for the difference between Snapshot quantity and Stocktake qty for this stocktake line.



Previous: 13.04. Purchasing reports | | Next: 13.06. Requisition reports

13.03. Transaction reports

Transaction based reports are accessed by choosing the Report > Transactions… menu item or by clicking on the Transactions item in the Transactions section on the Reports tab of the Navigator:

All these reports (and there are many!) summarise supplier or customer transactions in many different formats. Many different filters have been incorporated, allowing filtering on transactions, names, prescribers, items, categories and departments. The filters that do not apply to different reports are hidden as required. Feel free to mix and match and experiment with the filters and different reports to see the different views of information that you can get.

The basic sequence for creating a transaction report is this:

  1. Select the type of report you want from the Type of report list in the top left.
  2. Select the date range of transactions you want included in the report in the Date range section.
  3. Select the transaction type you want the report to run over in the Transaction type section.
  4. Set any other filters/settings you need to refine the contents of the report (Transaction category, Name, Item, Stock, Prescriber filter etc. sections).
  5. Click on the OK button to run the report - you can select whether you export it to Excel or print it in the next window that opens (well, mostly - some reports are exported to Excel only so you won't have a choice for them).

See below for more in-depth detail on all these steps.

Standard transaction reports

This is the window you will see:

Type of report

Choose from several formats for displaying transaction information by:

  1. selecting the report type in the Report list on the left, and
  2. choosing the required radio button under Transaction type

The following table lists the available report names, and gives brief details of the information provided by each report .

Report name What it does Sample
Each invoice grouped by name The report will sort each invoice in the date range according to the name (Supplier or Customer) and give totals for each name. Sample
Each invoice grouped by date As above, but totals given for each day. Sample
Each invoice line by item Lists each batch supplied or received, and the transactions for that item. This report can be very long Sample
Invoice line with donor As above, but including the 'donor' field and formatted to be most useful for analysis using Excel filtering and Pivot Tables. This report can be long.
Each invoice showing profit The cost and selling price totals for each invoice are displayed. Sample
Each invoice line grouped by item department then item The invoice lines are grouped by item department assigned to each item. Each item department is then sorted in alphabetical order. Includes batch information. Sample
Each invoice line grouped by name The value of batches received/supplied from/to each name. Includes batch level information. Sample
Each invoice line grouped by item and then name Invoice lines are all displayed, grouped by item and then, within those groups, by name. Includes batch information. Sample
Totals for each item category The total value for each category will be displayed - each transaction will not be shown. Sample
Totals for each item Each item that has been received (or issued) will be shown with the total quantity and value received/issued Sample
Totals for each item - Net Inventory adjustment Each item on which an inventory adjustment has been made is shown; the net adjustment is displayed, with both quantity and value shown. Sample
Totals for each name The invoice lines for the chosen date range are grouped together for each name. This report allows you to see quickly what has been issued to a customer or customers. Sample
Totals for each item broken down by name Lists all items, showing their distribution to recipient customers or delivering suppliers Sample
Totals for each item dept broken down by item Sample
Totals for each name broken down by item As above, but listing customers or suppliers and items received by or delivered by them Sample
Totals for each item department The total value supplied/received for each item department is shown Sample
Totals for each item grouped by day The total quantity and value of each item is shown for each day. Sample
Totals for each item grouped by month. The total quantity and value of each item is shown for each month. Sample
Totals for each item grouped by item description. First the report is sorted by item then the total quantity and price of each item is shown. It also provides a grand total for the item quantity and price columns. Sample
2 period comparison by item category User selects two periods, and the transactions for each period form a column. The rows are determined by the item category. This is a special report that has different input options. See entry below.
Totals for each item broken down by packsize The packsize for each item and the number of packs issued. Sample
Prescription and general issues over time This report shows the quanity of items given to patients and other customers over a period of time, separated by month. It exports to Excel only and has 2 tabs; the By Item tab shows which prescribers prescribed what items and the By Customer tab shows which items were issued to which customers Sample
Prescriber report This report allows you to view the total value, mean item value and item count for prescriptions dispensed for each prescriber Sample
Dispensing with patient name and prescriber This report shows who dispensed what to which patients with which directions Sample
Historic prices - Volume weighted average price This report produces a volume weighted average price for all transactions within the specified time period, for items that are On the price list in the store that you are logged in to.
Transactions that have have no transactions or a Cost price of 0 are ignored.
Calculations are done on the basis of the Price list Catalogue pack size. (This is normally the same as the Preferred pack size, but not always!) Transactions that are not in the Price list Catalogue pack size will have their calculation adjusted accordingly. Items affected by this will have an asterisk (*) appended to the Item Description in the report.
Cross tab: items in rows, names in columns, quantity in cells These reports are like Excel pivot tables. Warning: they can be slow to produce if you have a lot of data. Start with small date ranges until you are comfortable your machine can handle the load. Note that reports that produce a lot of columns won't print well - it is better to export them to a spreadsheet and print from there. Sample
Cross tab: items in rows, names in columns, value in cells See above Sample
Cross tab: items in rows, days in columns, quantity in cells See above Sample
Cross tab: items in rows, days in columns, value in cells See above Sample
Cross tab: items in rows, months in columns, quantity in cells See above Sample
Cross tab: items in rows, months in columns, value in cells See above Sample
Cross tab: names in rows, months in columns, quantity in cells See above Sample
Cross tab: names in rows, months in columns, value in cells See above Sample
Distribution of quantities issued First the report is grouped by item name and then by the pack size issued. It displays the total quantity and total count for each item. Sample
Totals for each item grouped by transaction category then item The report is grouped by each item's transaction category first and then by each item.The report shows the total count, total quantity and total value for each item. Lastly it also calculates a grand total of the items count, quantity and value columns. Sample
Each invoice sorted by Name >Address1 field then by name The invoices are firstly sorted by the address1 field, and then by the name they were supplied to. This groups invoices together by whatever you entered in the “Address1” field for each name - e.g. you might enter the region or province. Sample
Each invoice sorted byName >Address2 field then by name As above, but the first sort is by the entry in “Address2” field. Sample
Customer ordered short fall report Where there has been a shortfall, this report shows the shortfall of each item and of each item category by quantity and percentage. It shows what demand from customers has been met and what has not. It applies only for issues to customers. Sample
Customer transaction report 1 This report and the following three are, in fact, templates, and are the starting point for designing reports on specific criteria not covered in any of the existing reports. Sample
Customer transaction report 2 Sample
Customer trans line report 1 Sample
Customer trans line report 2 Sample
Received vs. sent Shows the difference between stock issues from a supplier and stock receipts for the same lines at the customer. If you choose Purchases from suppliers as the Transaction type then the report will run over supplier invoices and show differences between what the current store was sent from the supplying store (on customer invoices) and what the current store received on the corresponding supplier invoices. If you choose Sales to customers as the Transaction type then the report will run over customer invoices and show differences between what was sent from the current store (on customer invoices) and what was received on the corresponding supplier invoices in the receiving store. WARNING: any non stock-transfer transactions included in the report (if you select Normal transactions or Both normal transactions and stock transfers in the Transaction type section) will show a full difference because there is no corresponding customer or supplier invoice. So it is recommended to only choose the Stock transfers option in the Transaction type section for this report. received_v_sent.pdf
Months to expiry Sample
Order processing time If you are filling out the order written date and order received date for incoming customer orders, then this report will show you how long it is taking for orders to reach the store, and how long it is taking to process orders from receipt to order entry and to order dispatch
Historic prices - Volume weighted average price Calculates the Volume weighted average price for all items in the catalogue in those stores (i.e. where the item's On price list checkbox is ticked (see the 4.01.03. Items - Misc(ellaneous) tab page for details)) for all confirmed or finalised supplier invoices within dates provided by the user for all selected stores. Please note:
* Transactions where the stock has a cost price = 0 will not be included in the calculation.
* Items that have had no transactions within the selected period will not appear in the report.
* The On price list checkbox must be set for each store. This will be important if you're running the report over more than one store.
Transaction type

In the first drop down list, you can choose to report on:

  • Sales to customers: customer invoices i.e. transactions of type ci
  • Sales to and credits from customers: customer invoices & customer credits i.e ci and cc transaction types
  • Purchases from suppliers: supplier invoices i.e. transactions of type si
  • Purchases from and credits to suppliers: supplier invoices & supplier credits i.e. si and sc transaction types
  • Inventory adjustment - Add stock: All inventory adjustment transactions that resulted in stock additions (e.g. when you did a stock take of an item and counted more on the shelf than the total shown in mSupply).
  • Inventory adjustment - Reduce stock: All inventory adjustment transactions that resulted in stock reductions (e.g. discarding stock due to it being expired). Note that using a report that shows the total for each transaction category can give totals for expired/damaged etc.
  • Inventory adjustment - Net movement: Taking into account both reductions and additions, the nett change in inventory due to adjustment transactions.
  • Customer invoice cancellations: These are the “inverse” invoices created when a customer invoice is cancelled
  • Credits to customers: The credits applied to customers when invoices are cancelled or when goods are returned.
  • Payment cancellations: The “inverse” payments created to reverse a payment made by a customer for a customer invoice that has a payment against it and has been cancelled.

In the second drop down list, you have the following options:

  • Both normal transactions and stock transfers: this is the default option and means that both stock transfer and non-stock transfer transactions will be included in the report
  • Normal transactions: all transactions that are not stock transfers will be included in the report
  • Stock transfers: only stock transfers will be included in the report

A stock transfer is a transaction made when the supplier or customer is another store in your datafile. A normal transaction is when the customer or supplier is a normal customer or supplier in your datafile, and not a store.

Date range

Enter the date range of transactions to report on, having selected Confirmed date or Shipping date. Note that the date used may differ from the original entry date, depending on how your system is configured in the Preferences.

  • Note the popup menu to the right of the date entry fields that allows you to choose quickly from a list of common date ranges:

  • Note that “last year” refers to the year preceding the current year (that is, if the current year is 2012, choosing “last year” will set the dates from 1st Jan 2011 to 31st Dec 2011).
Transaction category filter

Assuming you have set up transaction categories, your report may be filtered by category. For help setting up Transaction categories click see sectrion 22.07. Transaction categories.

  • Transaction source: Options are “All”, “Customers, Suppliers and Stores” or “Patients”. This allows you to select the type of Name the transactions must belong to. If you select Patients, only transactions which have a name that is a patient will be inccluded in the results (e.g. prescriptions). If you select Customers, Suppliers and Stores then transactions that have a name which is a normal supplier (e.g. supplier invoice) or customer (e.g. customer invoice) or store (e.g. stock transfer) will be included in the report. If you select All then this filter is effectively not used and transactions with any name type are included in the report.
  • Transaction category: Use the magnifying glass to choose the transactions categories to be included in the report. Note that you can select more than one category. The types of categories offered in the list will match your selection in the Transaction type section.
  • Master transaction category: If you prefer, you can choose to filter by master transaction category instead. Master transaction categories are used to group together transaction categories (so selecting one of these is like selecting multiple categories in the Transaction category filter - it's just more convenient to do it this way if you regularly need to choose several. We love to make things easier for you!). Again, see 22.07. Transaction categories for details on setting them up.
Name filter

You can enter a particular customer code or category of transactions to be displayed.

  • You can choose from either equals for an exact match or starts with to search for all names whose code or category starts with the entered text.
  • Each name has 6 different categories that can be used to group certain kinds of names together. You can filter on category 1 (which is hierarchical) using the Category 1 filter in the screenshot at the top of the page (note that the Category 1 text will be replaced with any name you have assigned to this category in the preferences) and one of the other categories using the Category 2 filter shown in the screenshot at the top of the page.
  • If you want to report on transactions for a single name, you can find their code by looking up their details using Supplier > Show suppliers or Customer > Show customers.
  • There is also a Customer group filter you can use to include names based on their customer group.
Item filter

Here you can specify the items to include in the report.

Note that sometimes the item choice options will be hidden because the chosen report is reporting on transactions, not on transaction lines:

Donor filter

If you have donor tracking turned on in the preferences, and choose a report that bases it's data on invoice lines, then you will be given the option to filter the report for a particular donor or group of donors.

Which mode?

If you are using mSupply in both store and dispensary mode, you might want to report only on transactions in store mode (items distributed to customers) or in dispensary mode (items distributed to patients). You can do this by checking Store mode or Dispensary mode radio button depending on your requirements.

Exclude transfers from calculations

This checkbox enables you to choose whether you include stock transfers (where stock is transferred from one store to another in mSupply) in the report calculations. If you want stock transfers to be included in your report then uncheck this checkbox. If you want stock transfers to be left out of the report then check this checkbox.

Include nw or sg status transactions

By default only confirmed ('cn') or finalised ('fn') status transactions (i.e. those that have affected stock) will be included in transaction reports. If you want to also include new ('nw') or suggested ('sg') status transactions in your report (i.e. those that have not affected stock yet) then check the Include nw or sg status transactions checkbox.

Note that, for confirmed and finalised transactions, the confirmed date is used to compare with the date filter to decide whether it is included in the report or not. New and suggested transactions do not have a confirmed date so the entered date is used instead to compare against the date filter.

The 2 period comparison by item category report

This report allows you quickly to compare sales or purchases for 2 periods of your choice based on item categories.

When you choose this report a different set of options is shown.

Set the date range for each of the columns and then choose a summary level. It should be noted that if no data is present for the first period defined, this report will not run.

Dot notation and summary levels

The summary level is based on the item category field. If you have set up item categories using dot notation, then you can summarise categories.

To set up item categories, choose Items > Show item categories

Take the following simple example of categories that have been set up as follows:

The rules for dot notation are

  • Separate each level of your hierarchy with a period (dot).
  • Within a level you can have as many characters as you like
  • You can use any characters, as long as you don't use a period or a space within one level; e.g. “surgical.gloves.small” is a valid entry. (Level one is “surgical”, level two is “gloves” etc.).
  • When the hierarchy part of the category name is finished enter a space character. You can then enter a description for that level of the hierarchy.

If we run the report with a summary level of “none” each category is shown

If we run the same report with level one chosen, only the first level of the hierarchy is shown. Items with categories 1.1 and 1.2 and 1.1.1 have all been summarised under “1 Antibiotics”

And with level two chosen, items with category 1.1.1 and 1.1.2 are summarised under the heading “1.1 Penicillins”

Note that if you have items to which no category has been assigned, they are shown under the heading `none“ at the top of the report.

The categories are printed in the order that you have specified by drag-and-dropping in the window shown by choosing Item > Show item categories….

Transaction filter: Filters the report for given category

Prescriber filter: Reduces the found transactions to those for the given prescriber only, depending upon the selection made (equals, starts with, contains, is not equal to).

  • Obviously only useful in dispensary mode.

Exclude transfers from calculations: The check-box Exclude transfers from calculations when checked will ignore transfers between stores within the organisation.

Exclude Ad Hoc and non stock items: The check-box Exclude Ad hoc and non stock items is displayed accordng to the type of report selected. By default, it is checked.

When checked, the transaction report generated will not include any Ad Hoc items or non stock items (items you don't normally keep in stock).

Custom transaction and trans lines reports

These four reports should be regarded as templates for you to design your own report .

Having decided whether you wish to report on transactions or transaction lines, you need to design the report according to your specific needs. Coose Reports > Manage Reports :

You are presented with the Report management window. In this example, our report will be on transactions, so you should highlight custom_transaction_report_1 , and click onthe Duplicate report button:

Choose an appropriate name for your report, and any comment you wish, and click OK. You are returned to the Report management window, where you should scroll down until you reach the report you have created; note that the name you gave the report will appear in the Custom name column; highlight the row and click Edit report .

This brings up the Edit report window. Creating custom reports is described in detail earlier in this chapter. See the Custom Reporting Tutorial

Save template button

The save template button allows you to save a given report as a template once you have input your chosen settings. Templates can be reused as needed.

Pressing the Save Template button brings up the following window:

This dialog allows you to set a name and description for the report template. You can also define user permissions: at the moment, you can define these as ‘Public’ - for anyone, or ‘Private’, in which case the permissions only apply to the user who created the template.

  • View Preferences: define which stores will be able to view and use the template on the ‘Manage Reports’ tab (next screenshot).
  • Edit Preferences: define which stores will be able to edit or delete templates on the ‘Manage Reports’ tab.

  • Displays all template reports that the user has permissions to view.
  • Allows user to use the template:
    • Redirects user to ‘Create Report’ tab
    • Settings here will be set according to the preferences of the template report
  • Users can also edit, delete, and duplicate the reports if user permissions allow.
    • Duplicated reports will be named ‘ReportName[duplicate]’
  • Quick search searches in all text columns of the table.
Pivot table friendly transaction report

There is an almost infinite range of reports that you might want to generate from transaction data. If you are comfortable using Excel Pivot tables, there is an mSupply transaction report format that you will likely find quite useful. This report has been designed to work in Supervisor Mode but will also work in a single store.

To generate it:

  1. click on Reports > Transaction
  2. After configuring the various date range, Item, Name, transaction type, etc. filters
  3. Select the Each Invoice Line by Item report in the top left
  4. Then, select CustomTransactionByItem report type and send the output to Open in Excel

The report will open in Excel in a form that can then be easily filtered, sorted and manipulated through a Pivot table. If fact, the records are not sorted at all, so they must be processed to make any sense!



Previous: 13.02. Stock and items reports | | Next: 13.04. Purchasing reports

15.02. Adding barcodes to items

Added: Version 4.01

In a synchronising system (29.01. Introduction to Synchronisation) barcodes:

  • can be added to items at any site and they will then synchronise to all other sites.
  • that are created as a duplicate of one that already exists elsewhere in the system will be automatically merged into the existing barcode. This will be completely invisible to the user.
  • can only be edited on the primary server.

Assigning barcodes to items is an important setup activity. It is this step that enables mSupply to recognise which item a particular barcode belongs to. Note: this is strictly assigning the GTIN to an item, not the rest of the barcode which includes things like batch, expiry, serial number etc.

You can add barcodes to items before or during the goods receipt process. The process described here is used for both - to see how the goods receipt process fits in, see Barcode scanning and receiving goods.

To start the process, view the details page of the item you want to add barcodes to (go to Item > Show items…, click on the OK button, double-click on the item you want in the list). Then click on the Barcodes tab on the left hand side of the details window:

This will show you a list of the current barcodes assigned to the item:

This item currently has no barcodes assigned to it but this is the information each column displays:

  • Number: a sequential number for each barcode, starting at 1
  • Manufacturer: the name of the manufacturer of the medicine
  • Pack size: the number of individual items (tablets, bottles etc.) in the pack this barcode represents
  • Barcode: the human readable form of the barcode, just the type identifier (01) and the 14 digit GTIN (it could be a 13 or 8 digit (or any valid length!) GTIN but it must be padded with leading zeros to 14 digits in total - this is part of the GS1 standard). A barcode that starts 0104 identifies an internal mSupply barcode (assigned because the manufacturer didn't put one on the item's packaging). A barcode that starts with 01 followed by anything else is a global barcode not assigned by mSupply.
  • Parent: the number (shown in the Number column) of the barcode that is the parent (i.e. has the next largest pack size) of this barcode

Deleting a barcode

To delete a barcode, click on it in the table to select it and click on the Delete button. You will be asked to confirm the deletion. But please note, you will not be able to delete any barcode that has been assigned to a line of stock.

Editing a barcode

To edit a barcode, simply double-click it in the table. This will open the 'add a barcode' window shown in the Adding a barcode section below but the window will be populated with the barcode's details. Simply edit the details as described in the Adding a barcode section. Please note that, if a barcode has already been assigned to stock, you will not be able to edit the pack size or the barcode itself.

Adding a barcode

To add a barcode to the item, click on the Add button. This window appears:

Item: this is the name of the item you're adding a barcode to, followed by its code. It is non-editable

Barcode: the human-readable form of the barcode; the 2 or 3 digit type identifier followed by the 14 digit GTIN only (it could be a 13 or 8 digit (or any length!) GTIN but it must be padded with leading zeros to 14 digits in total). You can't type anything in here, you have two options:

  • Scan the item's barcode with a barcode scanner - the barcode's identifier and GTIN will appear in the textbox. If the barcode is not GS1 compliant you will see a warning message and you will not be able to save the barcode (just in case you've scanned the wrong thing. Why would anyone go wild with a scanner and start scanning anything they can find? ;-))
  • Click on the icon next to the Barcode field to have mSupply supply its own unique, internal GS1 compliant barcode. Each time you click on the icon, mSupply will supply a new barcode.

Pack size: the pack size (number of individual items in one pack) that this barcode belongs to.

Manufacturer: the manufacturer that this barcode belongs to. Type the first few characters of the manufacturer's name and press the Tab key to select it from a list of matching names. If the manufacturer you want doesn't exist in mSupply, click on the button next to the manufacturer field to add it.

Barcode for parent level packaging table: this is where you select the barcode that is the 'parent' of this one i.e. the one with the next biggest pack size. Selecting one is optional but it allows mSupply to identify barcodes that should go on tertiary level packaging (they can have different printing requirements). The table will show all the other barcodes entered for this item. To select the parent, simply click on the checkbox in the Select column to check it.

GS1 barcodes are unique to the combination of item, pack size and manufacturer. So you won't be able to add 2 barcodes to the same item with the same pack size and manufacturer.

Here is an example of an item with several barcodes added:



Previous: 15.01. Barcode scanning | | Next: 15.03. Barcode scanning and receiving goods

15.06. Barcode label printing

Added: Version 4.01

You might want to print barcode labels for your stock if an existing label is damaged, if you break a box down into smaller pack sizes and the contents don't have individual GS1 barcodes or if some stock comes into your warehouses and it doesn't have valid GS1 barcodes on it.

mSupply prints barcode labels onto stocky labels using a label printer. Before you try to print any barcode labels you must setup your printer. See for Label printing preferences details.

Please note that any stock or invoice lines that are not associated with a barcode will NOT have a label printed for them. If all lines you have selected to print labels for have no barcodes associated with them then no labels will be printed. The associaiton of invoice and stock lines with a barcode is carried out during goods receipt (see Barcode scanning and receiving goods)

There are several places in mSupply where you can print barcode labels for your stock.

Item details page

You can print out the barcode labels for a single line at a time. Select the line you want to print the labels for then click on the Print barcode labels button:

mSupply will offer to print a label for each pack in the selected line by default:

You can edit the number to something else if you wish. When you click on the OK button, the entered number of labels will be printed from your label printer.

Supplier invoice

When the preference to use barcode scanners is turned on, a supplier invoice has a Print barcode labels button:

After adding lines to the supplier invoice you can print barcode labels for them. If you select a single line then click the button, mSupply will by default offer to print a label for each pack in the line:

You can edit the number to something else if you wish. When you click on the OK button, the entered number of labels will be printed from your label printer.

If you select multiple lines on the supplier invoice before clicking on the Print barcode labels button, mSupply will print a label for each pack in the lines selected. This could be a lot of labels so mSupply asks you to confirm before telling the label printer to print them all:

Stock list

Like a supplier invoice, the stock window (Item > Show items with stock on the menus) has a Print barcode labels button when the preference to use barcode scanners is turned on:

You can click on a single line before clicking on the Print barcode labels button, in which case mSupply offers to print a label for each pack in the selected line. You can edit the number to something else if you wish:

When you click on the OK button, the number of labels entered will be printed from your label printer.

You can also select multiple lines before clicking on the Print barcode labels button. If you do that, mSupply will offer to print a label for each pack in all the lines you have selected. Obviously, this could be a lot of labels, so mSupply asks you to confirm before it asks the printer to print them all:



Previous: 15.05. Barcode scanning and pick list checking | | Next: 15.07. Barcode scanning and prescriptions

15.07. Barcode scanning and prescriptions

Added: Version 5.01

If you have turned on bacrode scanning for prescriptions (see the 15.09. Barcode scanning preferences page for details) then, when you print out a prescription label, a second label containing a barcode will be printed with it. The label will look something like this:

When you scan this label from the prescription search window (choose Patient > Show patients in the menus) with a barcode scanner, it will open the prescription at the Payment tab ready for payment to be entered. See the 11.03. Prescription payments and credits page for details on Prescription payments.



Previous: 15.06. Barcode label printing | | Next: 16. Preferences

15.01. Barcode scanning

Added: Version 4.01

mSupply has the ability to use barcode scanners to read the barcodes on stock to help speed up and improve the accuracy of some processes.

Introduction

A warning

Please be aware that using barcode scanning is not to be entered into lightly and is not the problem-free solver of all supply chain problems that some people think it is. It can have large implications for your organisation, in terms of changing processes and increasing workload in other areas.

Currently, very few barcodes on pharmaceutical products contain batch and expiry information. Our own checking (2018) shows it's only around 10% in typical warehouses. So, for barcodes to be really useful, you will probably need to print and stick new labels on most stock as it comes into your warehouse. And you'll need to do it again if you have barcode labelled the outer carton and you need to split the carton - you will need to label each of the inner packs. This alone can be a huge amount of work and can easily outweigh any benefits of using barcode scanners.

With those warnings out of the way, let's find out how barcode scanning works in mSupply.

mSupply and barcodes

mSupply follows the GS1 specification for the barcodes that it uses and you can find out all about them here. Barcodes are stored against items in mSupply and these stored ones are compared with what is read by a scanner to tell mSupply what it is dealing with.

Setup

The barcode scanner

The Zebra DS2208 barcode scanner has been tested with mSupply

A single barcode scanner can be attached to each computer running mSupply. The barcode scanner must:

  • be able to read both the 1D 128 bit barcodes and 2D datamatrix barcodes used by the GS1 standard.
  • communicate with the computer through a serial port. Note that this does not mean that it must connect to the computer via a serial port (these disappeared from computers many, many years ago!). The best way of achieving this is to buy a scanner that connects by USB and has serial port emulation software provided by the manufacturer.
  • append a carriage return character to the end of all its scans. Other whitespace characters can also be appended but a carriage return character must be appended as mSupply will use this to detect that a scan has been completed.

To set the barcode scanner up, the first thing to do is connect it to the computer (usually by a USB port) and make sure it can communicate with it. You may need to install a driver for the scanner, depending on the scanner make and model and the operating system of the computer. The best way to check the scanner is communicating correctly with the computer is to install a piece of dedicated serial port reading software, and make sure that scans from the scanner appear in the software. If you are using Windows, you could use this one here.

Once you are happy that the scanner is communicating correctly with the computer, you can open mSupply, enter the port settings and check that mSupply can receive the scans. See the mSupply settings section below for details.

The label printer

The label printer is used for printing barcode labels for the stock in your warehouse. You will need to do this if the stock does not have barcodes containing batch and expiry information already on it, or if you repack the stock into a different pack size.

The label printer must:

  • be able to communicate with the computer by Ethernet, USB or serial connection
  • be able to understand ZPL 2 (Zebra programming language 2) commands

We recommend Zebra printers, like the GK420t model for this purpose.

To set the printer up, attach it to the computer or your local area network (if using an Ethernet connection), and enter the settings into mSupply; see instructions for this on the Label printing preferences page here.

mSupply settings

See the full description of the preferences and their use on the 16.09. Barcode scanning preferences page.



Previous: 15. Barcode Scanning | | Next: 15.02. Adding barcodes to items

15.05. Barcode scanning and pick list checking

Added: Version 4.02

Another way barcode scanning can be useful is in checking that goods picked off the shelf for distribution to a customer match what was on the pick list.

This is done when distributing goods to a customer on a customer invoice. When the preference to use barcode scanners is turned on (see Barcode scanning preferences), the customer invoice window for new or suggested status customer invoices has a new Pick list check button:

When you have finished adding lines to the customer invoice, you print the pick list in the normal way (see Issuing goods to a customer), pass the pick list to the warehouse staff and they pick the goods off the shelf.

You can then check the right goods have been taken off the shelves as they are picked or when the pick is complete. To do this, click on the Pick list check button and the following window will open:

The Customer and invoice number fields are for reference and are read only. The table contains all the lines on the customer invoice. The status column contains a symbol for each item, indicating that less packs have been scanned than are on the pick list.

Scan the GS1 barcode on each item and mSupply will increase the Number scanned value of the correct line as you scan.

Symbol Meaning
The number scanned is the same value as the Number of packs , indicating it is the correct number.
More have been scanned than are on the pick list
Less have been scanned than are on the pick list
An item has been scanned that is not on the pick list. It will be added to the bottom of the table with Number of packs set to zero. Subsequent scans of the same item will add to the Number scanned value but the Status will not be changed.

The number scanned column is editable as a time-saving measure for large picks. If you have many packs of the same item, you can manually count them then add the correct number to the value in the column.

If you scan a barcode that is not a valid GS1 barcode or is a valid GS1 barcode but not linked to an item in mSupply, you will be shown an error message and the scan will be ignored.

When you have finished scanning all the picked items, a simple look at the Status column will tell you if the pick matches the pick list. If every row has a then all is well. If any row doesn't have this status then something needs to be changed:

  1. either put the wrong item back on the shelf and pick the correct one or
  2. return to the customer invoice and edit it to match the items picked (this might involve inventory adjustments so that you can put the correct stock on the customer invoice)

When you have finished checking the pick, click on the OK button. Nothing is saved, the pick list check is for reference only.

You can run the pick list check as many times as you like after correcting the picked items or the customer invoice.

But, once you have finished picking the items and have confirmed the customer invoice, the picking process is counted as complete and the Picklist check button is removed.



Previous: 15.04. Barcode scanning and stocktaking | | Next: 15.06. Barcode label printing

15.03. Barcode scanning and receiving goods

Added: Version 4.01

When you receive goods into mSupply, that is when you tell mSupply about the barcode that belongs to each line of stock. It is not possible to receive stock using a barcode scanner in mSupply, but this is still the point in your process where you tell mSupply about the barcode that belongs to each line of stock.

This is a vitally important step: once the barcode associated with the stock you receive is recorded, mSupply can recognise it anywhere when you scan it later.

The linking of barcodes with received stock is carried out on a supplier invoice.

Create a supplier invoice in the normal way (either manually (see Receiving goods - a supplier invoice or by finalising a goods received note (see Goods receipt notes)). If the We use barcode scanners preference is turned on (see Barcode scanning preferences), this is what a blank supplier invoice invoice window looks like:

It is exactly the same as a standard supplier invoice, except for an additional Print barcode labels button (see Barcode label printing for details)

Clicking on the Add line button shows an extra Barcode field on the invoice line window:

When the item has been selected in the usual way, the Barcode drop down list is filled with a list of all the barcodes already assigned to the item, showing the pack size and manufacturer for each:

If one of the barcodes matches the stock that is being received, select it: this will set the Pack size field to match the pack size that belongs to the barcode. You can still manually edit the Pack size field but if it doesn't match the barcode you have selected when you click on the OK or OK & Next buttons, you will be warned and told to correct it (either select another barcode with a matching pack size or alter the pack size).

If none of the barcodes in the drop down list match the one on the stock, you can click on the Add one… option. This will immediately open the Add barcode window so you can add the new barcode. See Adding barcodes to items for details.

Note that once you have selected a barcode, the Please select… option in the Barcode drop down list becomes Remove barcode to show that selecting this option will remove the barcode from this line.

When you are using barcode scanning, you must select a barcode from the Barcode drop down list, you will not be allowed to add the line without it.

Manually assigning barcodes to stock lines

Sometimes it might be necessary to manually add or edit the barcode that belongs to a stock line. For example, any stock you have in mSupply before you turn on the barcode functionality will not have barcodes entered against it they will need to be added manually. Or an incorrect scan may have been made at goods receipt and the barcode might need to be changed.

To do this, first choose Items > Show items from the menus, search for the item whose stock you wish to edit and open its details window by double-clicking on it. Then click on the Stock tab:

Now double-click on the stock line whose barcode you wish to change. This will open the stock line details window:

The Barcode drop down list displays the current barcode assigned to the stock line (it will say Please select… if it has no barcode assigned). The current barcode will also be shown to the right of the drop down list, as in the screenshot, if one is currently assigned.

Click on the drop down list and you will be shown a list of all the barcodes of the same packsize as this stock line for this item. You can select any one of these or the Add one… option to open a new window to add a new barcode (see the 14.02. Adding barcodes to items page for details on that window).

If a barcode is already assigned to the stock line, the first option in the Barcode drop down list will be Remove barcode - select this if you want to remove the barcode current assigned ot this stock line.



Previous: 15.02. Adding barcodes to items | | Next: 15.04. Barcode scanning and stocktaking

15.04. Barcode scanning and stocktaking

Added: Version 4.01

During a stocktake, it is possible to save a lot of time and increase accuracy by using barcode scanners to scan stock instead of manually counting it.

Stocktaking with barcode scanners is a little different to doing it without them. With barcode scanners, the assumption is that you will go to a particular location in your warehouse and then scan everything in that location. As you scan, mSupply counts the stock in that location. This means two things:

  1. You must tell mSupply which warehouse location you are currently counting
  2. When first created, a stocktake with barcode scanning turned on has a zero in the Counted number of packs column for every line. Without barcode scanning turned on, the Counted number of packs is set to the Snapshot number of packs when it is first created.

Here's how it all works.

Create a stocktake in the usual way (see Stocktakes for details). The stocktake window is exactly the same as when not using barcode scanners, except that the item filter has changed to a location filter:

Edit the Description and Stocktake date fields as required as usual and enter any comments in the Comment field. Now enter the location you are going to count in the Scanning for location field. As you type the location name, the lines that have locations starting with what you have typed remain displayed in the table, all others are hidden (The line's locations are shown in the Location column). What you enter in the Scanning for location field must result in lines for a single location only being displayed in the table. If you start scanning before this is the case you will be shown a warning message and nothing will be counted.

Note:

  • The Scanning for location field is not case sensitive
  • You can enter “none” in the Scanning for location field if you want to count the lines that have no location. Very handy if you don't use locations in your warehouse.

When you have correctly entered the location you want to count in the Scanning for location field, you can start scanning the physical stock in that warehouse location. Be careful to scan the correct GS1 barcodes on the stock. mSupply will ignore anything you scan that is not GS1 compliant.

There are a number of possible outcomes of the scan:

Scan result What mSupply does What you should do
The barcode you scanned matches one of the lines in the location you are scanning for The line's Counted number of packs value is increased by 1 Scan the next box in the location
The barcode matches a line in the stocktake that is not in the current location mSupply asks you whether you want to move the line to the current location. If you say yes, the line's location is changed to the current location and its Counted number of packs value is increased by 1. If you say no, the line is left unchanged and the scan is ignored. Scan the next box in the location
The barcode matches an item not in the stocktake A line is added to the stocktake in the current location for the item with the pack size assigned to the barcode. The batch and expiry date of the line are taken from the barcode, the Snapshot number of packs is set at zero and the Counted number of packs is set at 1 Scan the next box in the location
The barcode is not a valid GS1 barcode mSupply displays an error message and the scan is ignored Scan the correct GS1 barcode on the box. If the item doesn't have a valid GS1 barcode on it, either:
1. print a barcode label for the box (see Barcode label printing) and try the scan again or
2. manually edit the appropriate line in the stocktake or add it as a new line
The barcode is a valid GS1 barcode but it is not registered against an item in mSupply mSupply displays a warning message and ignores the scan Register the barcode with the item (see Adding barcodes to items) then try the scan again

Continue scanning items until you have scanned everything in the location.

Then, enter the next location in the Scanning for location field and start scanning the items in that location.

When you have scanned the stock in all the locations in the stocktake, you've finished the count. When you're sure you have finished, click on the Create inventory adjustments button as normal to finalise the stocktake and make the stock in mSupply match what you counted.



Previous: 15.03. Barcode scanning and receiving goods | | Next: 15.05. Barcode scanning and pick list checking

16.09. Barcode scanning preferences

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.

If you want to use barcode scanners in mSupply, this is where you set up the preferences for communicating with your barcode scanner.

Note: Only a single barcode scanner can be connected to a computer running mSupply

We use barcode scanners: Check this if you will use barcode scanners with mSupply on this computer. When it is checked, mSupply will automatically try to connect to the scanner when it starts. You will get an error message if the port in the settings is closed (usually caused by the scanner not being connected or turned off). When this is checked, it also modifies the way certain things work in mSupply. For example, when checked, a new Barcode drop down list appears on the new line window of a supplier invoice and stocktakes work differently.

Scanner interface settings

Listen for barcode scanner on serial port drop down list: contains a list of all the serial ports available on the computer. Select the one the barcode scanner is connected to. Note, if the barcode scanner was previously connected to a port but it is now turned off or disconnected and the port is no longer available, the port will appear as “Disconnected port” in the list and will be selected by default.

Speed drop down list: the speed that data is communicated over the serial connection in Baud (900 to 230400).

Number of data bits drop down list: the number of data bits in a packet of information sent over the serial connection (5,6,7 or 8).

Number of stop bits drop down list: the number of stop bits in a packet of information sent over the serial connection (1, 1.5 or 2).

Parity drop down list: the type of parity used in the serial communication (Odd, Even or None).

Flow control drop down list: the type of flow control (None, RTS/CTS or Xon/Xoff).

Test area

Start listening button: When you have made your selections in the Scanner interface settings section, you can click this button to test whether the port settings are correct and mSupply can receive scanned output from the scanner. When you click it, mSupply attempts to open the selected port with the selected settings and listens to the scanner.

If you get an error message, that means the port you selected in the Listen for barcode scanner on serial port drop down list couldn't be opened. That will be because the barcode scanner isn't connected or turned on or the scanner driver isn't properly set up.

If you don't get an error message and the scan appears but it's garbled or doesn't match what the barcode contains then one or more of the settings below the Listen for barcode scanner on serial port drop down list are wrong. Refer to your scanner documentation to determine what the correct settings are (or configure you scanner to match the settings you've chosen).

If the port settings are all correct and communication with the scanner is good, the contents of the scan will be displayed correctly in the text box.

To change the settings, click on the Stop listening button (the button label toggles between “Start listening” and “Stop listening”), adjust the settings, and click on the button again before trying another scan.

When you are happy the scans are being read by mSupply, your setup of the scanner is complete.

Use barcode scanners for

This section is where you tell mSupply in which areas to use barcoding:



Previous: 16.08. FrontlineSMS | | Next: 16.10. Options (standard reasons)

16.11. Custom fields

In a synced system, Custom fields must be added on the central server and will then sync to other sites where they will apply to all stores on each site.

Only edit custom fields if you are confident with the information in this page and fully understand the content. Otherwise you could cause some things to stop working in your copy of mSupply! This is true for all settings, but please be especially careful with custom fields.

You can create custom fields that appear in different areas in mSupply. These allow you to record additional information and customise mSupply for your needs.

You can create custom fields in the following areas:

  • Customer invoice
  • Supplier invoice
  • Store
  • Item
  • Item category
  • Quote line
  • Name (of customers, suppliers, prescribers etc.)
  • User
  • Purchase orders
  • Transaction categories
  • Item Category Level 1
  • Transaction lines

Creating custom fields

1. Navigate to the Admin tab and click the Preferences button.

2. Select Custom Fields from the list on the left.

3. Select the area requiring custom fields from the Table to set custom data fields for dropdown list.

4. Click the New Field button.

5. Click on the new line in the Field Label column to change the name of the custom field.

6. Click the small arrow in the Field Type column and choose from the drop-down list. The options for your new field are:

  • Text: User can type free text.
  • Number: User can only type a number.
  • Boolean: User can tick a checkbox.
  • Date: User can only enter a date.
  • List: User can only select an option from a list.

6. If you choose a List field type, highlight the line and click Add Item to enter the options that will appear in the list. To delete an option, select it in the list and click Delete Item(s).

7. Click OK.

If you want to delete a custom field, highlight the line and click Delete field(s).

Using custom fields

This section shows how custom fields appear after they are created.

Customer invoices

When creating a customer invoice:

Click the Custom Data tab.

In this example, we added two custom fields: a Date and a List field type.

Supplier invoices

When creating a supplier invoice:

Click the Custom Data tab.

In this example, we added two custom fields: a Boolean and a Text field type.

Stores

When creating a store:

Click the Custom Fields tab.

In this example, we added one custom field: a Number field type.



Previous: 16.10. Options (standard reasons) | | Next: 17. Data Import and Export

16.05. Mobile Dashboard set up (before v4.0)

August 2020: The instructions on this page are for configuring mSupply's legacy web dashboard and mSupply Mobile dashboards. mSupply's legacy web dashboard has been superseded by the mSupply Grafana web dashboard.

The following instructions are for setting up dashboards for mSupply versions prior to v4.0.
For mSupply v4.0 and later please refer to the Dashboard set up (after v4.0) chapter of this user guide.

Before you set the dashboard up you must:

  • know what ports are already in use on the server
  • have an appropriate SSL Certificate set up.
  • make sure your webserver is currently running.

Sustainable Solutions can help with these.

To setup the dashboard (refer figure below):

  1. Open File > Preferences > Dashboard
  2. Check the “We use the web dashboard” checkbox.
  3. In the Dashboard web URL field enter the base URL to reach the dashboard, e.g. http://yoursystem.msupply.org:2048/.
    Don't forget the trailing slash (/) otherwise it won't work!
    If you are running from localhost, use your IP address, e.g. http://127.0.0.1:8080/ rather than http://localhost/.
  4. The URL users type in to the address bar of their browser to access the dashboard will be this base URL with dashboard on the end, e.g. https://yoursystem.msupply.org:2048/dashboard/
  5. Tick the reports in the Is active column to select them for display on your dashboard.
  6. You can choose how often these reports are updated by clicking in the Update Period (mins) column and entering a number of minutes.
  7. Setup which reports appear on which tabs - refer Dashboard tabs.
  8. Setup which dashboard reports each user can access - refer The dashboard.

Editing dashboard reports

Double-click a report in the list shown above and the following window will open:

If there are any properties shown in the list, these can be edited to change what is displayed.

To edit a property or value, click once to select the row, and then click again in the appropriate cell to edit it.

To add or delete a row use the New line and Delete line(s) buttons at the top of the window.

In the example shown in the screenshot above (a map report), the coordinates of two of the map corners and the item code of the item whose stocks will be shown on the map have been entered. Note that if you add extra properties to the default reports they'll be ignored.

See the section below for details of the various dashboard reports available and the settings that can be edited.

What the dashboards show and what can be edited

There are several built-in dashboard reports that everyone can use. Here's what they show and what properties can be edited to change what they show:

Report name Property Value
VEN items in stock: Shows stock on hand of each items that belongs to the VEN (Vital, Essential, Necessary) category.(Method: dashboard_rep_item_ven) Report format : Table
store_code store code if empty then default store is chosen
ven_category V,E,N or E,N or V ..etc will filter the VEN items. If blank all visible items for the store are chosen
Total stock value: A single figure in your default currency, showing the total value of the stock you have in the store you are viewing the dashboard for. (Method: dashboard_rep_total_stock_value)
None None
This month's transactions: Shows a bar chart of the number of purchase orders, goods receipts, supplier and customer invoices created this month. (Method: dashboard_rep_month_transacs)
None None
Expiring stock: Shows the cumulative and monthly number of all items expiring within the year, split into columns by month of expiry. (Method: dashboard_rep_expiring_stock)
None None
Top facilities supplied: The 10 customers in your store to which you have sent the greatest value of stock in the past 90 days. Shows the value of stock for each customer. (Method: dashboard_rep_top_facilities)
None None
Transactions per store: Shows a table of all transactions per store within the past 7 and 30 days (Method: dashboard_rep_month_transacs)
store_tags A comma-separated list of tags - or omit this parameter if you want to show stock for all stores.
Vital items in stock: Shows a bar graph of the percentage of medicines of the chosen category in stock at each facility. (Method: dashboard_store_stock_percent)
ven_category v or e or n if you want to include items that are Vital or Essential or Necessary
user_field_4 TRUE if you want to include items with this field checked
user_field_7 TRUE if you want to include items with this field checked
Note that the labels for fields 4 and 7 may be different, as they are set up in the mSupply preferences (misc tab)
critical_stock TRUE if you want to include items with this field checked, false for all items
store_tags entering healthcentre will only include stores with the “healthcentre” tag
Map stock on hand: Shows a map of the area specified, with an “X” if the facility is out of stock of the item, or a dot representing the amount of stock on hand. (Method: dashboard_map_stock_on_hand)
lat_nw_corner the latitude of the North-West corner of the map
long_nw_corner the longitude of the North-East corner of the map
lat_se_corner the latitude of the South-East corner of the map
long_se_corner the longitude of the North-East corner of the map
item_code the item code of the item to display
country compulsory parameter
store_tags A comma-separated list of tags - or omit this parameter if you want to show stock for all stores
Sync sites last connection date: Shows the last connection date and current mSupply version of each sync site. (Method: dashboard_report_last_sync_date)
None None
Sync sites sent and received statistics: Shows number of records sent and received by each syc site within the last day. (Method: dashboard_report_sync_stat)
None None
Stock_for_category_1_stores_by_item_list: Shows… (Method: -)
None None
Trends in critical stock: Shows the historical stock on hand using parameters to filter store and/or items. Will show the current percentage, and percentages from the last day of each month for the prior six months. (Method: dashboard_rep_in_stock_trends)
store_id the ID of the store you're interested in, or no value for all stores
critical_stock TRUE if you want to include items with this field checked, false for all items
Output: use the type “time_series_chart”
Reports Monthly Transactions Shows how many transactions of each type the chose store has processed this month (Method: dashboard_rep_month_transacs)
store_name the name of the store which you are interested in, or no value if you want all stores
Items Issued This Month: Shows items issued by the facility within the last 30 days. (Method: dashboard_itemRow_storeCol_usage)
store_tag include stores with this tag
master_list include items on this master list
period 30 ( currently only 30 days is supported)
Stock each item in each store: Shows a table of items in rows and stores in columns, with the stock on hand for that item in that store in each cell. (Method: dashboard_rep_stk_StoreCols_Itm)
store_code store code attached to the store. multiple stores can be specified by adding more parameters that begin with store_code (e.g. store_code2). The item_code parameter must be specified if using store_code
item_code items whose code matches this code (append “@” for a “starts with” search)
master_list selected master list of items. Category1_description must be specified if using a master_list
Category1_description Items with this category1
Unfinalised Stock Transfers: Table of unfinalised stock transfers (between mSupply stores) for each facility. (Method: dashboardReportUnfinalisedStock)
store_tags(optional) A comma-separated list of tags - or omit this parameter if you want to show transfers for all stores.
days_older_than(optional) show only transactions that are older than this value (days).

If you can't make a dashboard report that does what you want then please speak to us, it's usually a fairly simple matter for us to create one for you.

August 2020: The remaining instructions on this page are for configuring mSupply's legacy web dashboard. This may still work, but is no longer supported as it has been superseded by the mSupply Grafana web dashboard. The instructions are left here for historic reference only.

Dashboard tabs

You set up Dashboard tabs which will display on your dashboard. Dashboard tabs are “containers” for one or more dashboard reports. To edit them go to File > Preferences and click on the Dashboard tabs tab on the left hand side:

To add a tab click the Add button. To edit a tab, double-click it. You will be shown a window for editing a dashboard tab:

Now you add reports that will show on this tab.

Understanding rows and columns

Take this example dashboard tab:

  • The tabs themselves occupy their own space on the left of the window- they aren't considered when laying out the dashboard
  • The first row has two reports- each report takes up half the row. So for the first report:
    • Row 1, Col 1, width 6 (“12” means it takes up the full width of the cell it is in- “4” would mean it would take up 1/3 of the width)
  • For the report at the top right:
    • Row 1, Col 2, width 6
  • For the map
    • Row 2, Col 1, width 12
  • The next two reports are on the same row, but are divided into 5/12 and 7/12 of the width of the window, so we put them in the same cell but change the width settings:
    • Row 3, Col 1, width 5
    • Row 3, Col 1, width 7
To add a report to a dashboard tab

Click New Line to add a new report to the tab. Then edit the values in each column

  • Row: The row it will be in
  • Column: The column within the row- set to “1” if you don't have multiple reports on this row.
  • Report tite: The title that will show in the Orange heading bar for the report. Note that the same report can display different information depending on the parameters you set for that report- hence the need for the ability to customise report names
  • Type: You'll need to know the appropriate type for the report you're displaying. The options are
    • bar_chart
    • table
    • pie_chart
    • time_series
    • map
    • line_chart
  • Width: The fraction of the cell width in “twelfths” that this report will take up (“6” will make it take up half the cell width)
  • Report: Choose the report name from the drop-down list of available reports
Add a dashboard tab to a user's dashboard

This is the final step in setting up dashboards: once the tabs have been setup you have to choose which users will see which tabs. You do this in individual users' settings. See managing users for instructions on how to do this.

Some of these dashboard reports can be used for mSupply Mobile. Users do not need to be set up to have access to mSupply Mobile dashboards. The mSupply Mobile store will see the dashboard reports provided that on the mSupply central server:



Previous: 16.04. Printing preferences | | Next: 16.06. Entering a new logo

16.08. FrontlineSMS

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.

If you use FrontlineSMS for sending information to mSupply via SMS messages (using mobile phones), this is the page where you enter all the settings.

The settings and what they mean are as follows:

We use FrontlineSMS:

Checking this makes mSupply periodically check the FrontlineSMS database for messages that have been sent to mSupply. If this checkbox is left unchecked, mSupply ignores all the settings on this page and will not check the FrontlineSMS database for new messages.

FrontlineSMS database (MySQL) settings

To use FrontlineSMS with mSupply, FrontlineSMS must be configured with a MySQL database. In this section you tell mSupply the details of this database to enable it to connect to it and retrieve new messages.

Server:

The name of the server hosting the FrontlineSMS database. You can enter the server's name e.g. myserver.mydomain or its IP address.

Database name:

The name of the FrontlineSMS database. This is the name it was given when it was created in MySQL.

User:

The username that mSupply will use to log into this database.

Password:

The password that goes with the username above.

Port:

The port that the database is served at on the host. If you leave this blank, mSupply will set it to the default port used by MySQL (3306).

Test Connection Button:

This button will test the connection to the FrontlineSMS database using the settings above. You should click it after you've entered all the settings or when you change any of them. It will tell you whether the settings allowed mSupply to connect to the database.

If a connection cannot be made to the database when clicking the Test Connection button, the exact error message returned from MySQL is stored in the log. To view it go to Special > View log. This can be very handy when trying to figure out why you can't connect to the FrontlineSMS database.

Check database every //x// mins. for new messages:

This is the time in minutes between checks of the FrontlineSMS database for new messages. The minimum is 2 minutes and if you don't set it, this is the value it will be given.

Message settings
Keyword to identify mSupply message:

This is what mSupply looks for at the very beginning of an SMS message received by FrontlineSMS to identify it as one that it must process. Can be made up of any alphanumeric characters. Keep it short and unique - not something that will appear at the beginning of any SMS messages not intended for mSupply.

Error messages and notifications

Because the process is otherwise silent, mSupply needs to notify users when a new message has been processed or if errors occur in the process (e.g. a message is missing some information). mSupply will email such error messages and notifications to the users ticked in the list in this section. The list contains all users in the system and you must select at least one of them.

Previous: Synchronisation Next: Reports Basics



Previous: 16.07. Synchronisation preferences | | Next: 16.09. Barcode scanning preferences

16.01. General preferences

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.

Preferences are used to configure some of mSupply's functionality to more closely match your needs. mSupply is very flexible and highly configurable so there are lots of preferences! To access them, choose File > Preferences… from the menus. There is a scrolling side bar on the left containing a list of tabs; click on the one you want to see the preferences on that tab.

General tab

Organisation name

What is filled in here is quite important. Not only will it print on the top of invoices and various reports, but it is also tied to your registration code. Please think carefully about what it should be before entering it. If you need to change your organisation name, please do so and then re-contact info@msupply.org.nz for a new registration code.

Address lines (1, 2...)

Enter the address information about your organisation that you wish to appear on invoices.

Close mSupply if user is inactive for ''#'' minutes

This preference is only available in a multi-user system on an mSupply client. It will not be visible in any single user copies of mSupply.

This determines how long a user can be inactive on mSupply before mSupply window closes. Entering any value bigger than 9 will close mSupply if the user has been inactive for that many minutes (note: entering any value smaller than 10 will currently not do anything OR will produce a warning - depending on your current version of mSupply. The inactive user logout is disabled if you set a time less than 10 minutes OR if you set the time to 0 - depending on your current version of mSupply). This timer is re-set when:

  • a user clicks on a:
    • supplier invoice
    • customer invoice
    • request/response requisition
    • stocktake
  • anytime the software checks a user's permission (normally when creating a new transaction)
  • anytime the software updates some (but not all) progress bars
Synchronisation section
  • This datafile is part of a synchronisation system: If checked it means that the synchronisation system is enabled in this datafile. This means that records to be synchronised will be created at appropriate times. If this is unchecked it means that the synchonisation system is disabled completely and records to be synchronised will not be created in this datafile.
  • Synchronisation is active: If checked, synchronisation is operating as normal. If it is unchecked, the synchronisation system is paused. Records to be synchronised will still be created but they will not be shared between the central server and remote sites. This is sometimes useful when carrying out maintenance procedures.
Register button

This button is used for registering mSupply. (It will be dimmed if you have already registered). If you have not registered, clicking this button will display the registration details window:

If you check the Connect to hub server checkbox then your copy of mSupply will periodically send information to our hub server. This information includes the mSupply version, operating system details, the active stores and the last date they synchronised with the server and other synchronisation information. This information is used in our hub to support your system and contains no user or personal information.

  • Here you are provided with the information needed to register. Two of these, if changed, will invalidate your mSupply registration:
    • Your organisation name
    • Your hardware ID
  • Clicking the Copy details button will copy this information to the clipboard, which you can paste into an email and send to support@msupply.org.nz.
  • Once we have received this registration information we will generate a registration code and send it back to you.
  • The code is entered by clicking the Enter code button in the window shown above. You will then be shown another window where you can enter the registration details you have been supplied: Your registration instructions supplied with the registration code will describe what information to put in each field.
  • mSupply registration codes are specific to the Hardware ID, organisation name, Number of users and Expiry date of your licence (if it is time-limited - nearly all mSupply licenses are NOT time limited).
  • If you change either your organisation name or the computer on which you are running mSupply, you will need to contact Sustainable Solutions for a new code.
  • The registration code depends on the machine UUID which is unique to every single computer and consists of 36 characters. If your machine UUID is blank, please make sure that windows program CMD is allowed to run (it may be blocked by anti-virus or anti-malware software). Please make sure you keep mSupply as a trusted application and unblocked by any anti-virus or anti-malware software you are using.
  • If the Hardware ID field is empty, mSupply or the Windows CMD programme is being blocked by anti-virus or anti-malware software. If you need help, please consult Sustainable Solutions.
  • If you move your data file to a new computer you will need to obtain a new registration code from us and enter it within 3 months to prevent mSupply from not working.

After entering your registration details and clicking on the OK button in the screenshot above, if the datafile is set to use synchronisatino (see the 29.01. Introduction to Synchronisation page for details) then the following window will appear:

This is a very important window and you must be careful to make the right choice! When a datafile is unregistered, synchronisation is prevented from running for data security reasons. Your datafile is just about to be registered so you are being asked whether you want synchronisation to continue working or whether it should be stopped.

If you select “Stop Synchronisation”, then the synchronisation settings will be cleared and synchronisation will not work. You would select this option if you were using a copy of live data for training, for example.

If you select “Keep Synchronisation working”, then synchronisation will keep working (surprise!). You would use this option if you were using this datafile in a live synchronisation system, either for the first time or if you've moved it to a new computer.

When you have made your choice, type “I understand” in the textbox as confirmation (the consequences of turning on synchronisation to the live system for a duplicate datafile intended to be used in a training environment can be dire!) and click on the OK button. Whichever choice you have made, mSupply will now quit and you will need to restart it.

Hooray, the registration process is now copmplete!

Other fields on the General tab
Default customer

Leave this field blank for normal operation. If you usually (or always) only issue to one customer, enter that customer's code here. You must set the value to the name code of an existing customer. Doing so will mean that this customer's details are automatically filled in when you create a new customer invoice.

Default margin for suppliers

The percentage margin that will be filled in when you enter a new supplier. This value can be edited for each supplier at any time. Enter “0” if you do not apply a mark-up to items you sell (for example, if you are issuing stock to hospital wards at cost).

Default tax rate

The rate entered here will automatically be applied to customer and supplier invoices. Note that this amount can be edited when you are entering an invoice by clicking on the tax rate at the bottom of the invoice entry window.

Period closing

There are two fields allowing the entry of dates:

  • The Closed date is the date prior to which no transactions can be entered. Setting the closed date means that all transactions up to that date are finalised and mSupply will not allow the entry of any transactions with an earlier date. The closed date can not be moved backwards- only forwards.
  • The Locked date is the earliest date that can be entered for a transaction. The lock date can be moved forwards as far as the oldest non-finalised transaction, and backwards as far as the closed date

If you try to set an invalid locked or closed date you will be warned.

Be very careful setting the closed date. Changes to the closed date can not be undone.

Inactive user logout

This setting is only visible if you are using an mSupply client in a multi-user setup, not if you're using the single user version of mSupply (because it's not applicable to the single user version). This is where you set the time in minutes before the mSupply client is closed and the user is automatically logged out. To disable the function, set the time to 0 minutes (the default setting). This is really useful for preventing inactive users holding onto a user license when they've forgotten to logout of mSupply. Any unsaved work will be lost when mSupply is closed so remember to save your work regularly. The good news is that most of the things you do in mSupply are automatically saved as you do them (adding and removing lines to customer and supplier invoices, inventory adjustments, stocktakes etc.) so the chances of losing work is actually very small!

Misc tab

Own code for electronic invoices The code that customers must have for your organisation in their copy of mSupply. This code is added to invoices you export, and allows customers to import the invoice into their system automatically.

This is an old copy: warn me at startup. You may want to save an old copy of your data (for example the data as it stood on the last day of the financial year). If you check this box, you will be warned at startup if the database is an old copy, to reduce the risk of accidentally entering current transactions into an old file rather than your current file.

Use a lock file to warn if data already open If this box is checked, mSupply will maintain a record of when it is open outside of the database. This option only applies to the single-user version of mSupply. This means that if a second user attempts to open your data file while the data file is already in use, the user will be alerted, and no damage to the data will occur. Note that this option only applies to the single user version of mSupply. The client-server version of mSupply allows multiple users to access mSupply at the same time.

What if your machine crashes? If, for example, you have a power failure and your computer shuts down suddenly, mSupply will not be able to delete the lock file, and you will get a message when you attempt to restart mSupply that another user is already using the data file. If you are sure this is not the case, use Windows Explorer or the Mac Finder to locate the folder that contains your mSupply data. Delete the file that has the same name as your data file but ends in “_locked.txt”. You will now be able to start mSupply.

We recommend you do not turn this option on unless you understand the above paragraph or have a system administrator who authorises your use of this option.

An example of where turning on this option might be useful is when you store your mSupply data on a file server, and allow multiple single-user copies of mSupply to access the same data file. In such a situation to have 2 users attempt to access the data simultaneously would be disastrous.

JSON logging Check this checkbox to turn on JSON format logging of everything that happens in the database. When this is turned on, you must enter a value for the maximum size of the Log folder (once the logs in th folder occupy this much memory, no more logs will be added) and you must select a path to save the file in using the Choose… button.

Allow users to attach documents after transactions have been finalised When this box is checked, mSupply will allow to upload documents on finalised customer invoices, Supplier invoices, Purchase Order and Good receipt.

Currency formats This option specifies the format in which currencies will be displayed in mSupply. We provide two preset formats for currencies with 2 decimal places and currencies with none. If you want to enter a custom format you can change the field below the drop-down list. For example you may want to use a different separator than a comma. Note that if you type illogical values into the field the numbers may not display at all, or display erroneous data. Contact Sustianable Solutions if you need more information.

Service items Service items are items that do not have any stock associated with them. For example, a fee for special handling of goods, or for reprinting an old invoice, or a consulting charge.

These Preferences determine whether new items are allowed to be service items or not. Note that changing this preference will not affect existing items.

AMC Data Element The Id of the AMC data element in DHIS2. Now obsolete, see the 23.01. DHIS2 integration page for details on setting up an integration with DHIS2.

Names

  • Customer code and charge code must match - If checked, when entering or editing a Customer, you will have to enter the same code for both the “code” and the “charge code” fields. (It is a good idea to leave this checked unless you have several customers that are invoiced separately, but whose invoices are collated onto a single statement at the end of the month)
  • Supplier code and charge code must match - If checked, when entering or edit a Supplier, you will have to enter the same code for both the “code” and the “charge code” fields. (It is a good idea to leave this checked unless you have several suppliers that are invoiced separately, but whose invoices are collated onto a single statement at the end of the month)
  • Name code for all codes to be unique (both 'store' and 'dispensary' mode) - If checked, when entering or editing a customer or supplier mSupply will not allow the creation of a second name with the same name code.
Labels for custom item fields

mSupply provides you with seven custom fields that you can use to record your own data for each item.

  • the first three fields hold text or numbers,
  • the fourth field is yes/no (or true/false)
  • the fifth field is a numeric field
  • the sixth field holds text or numbers
  • the seventh field is yes/no (or true/false)

Here you can specify the label(or name) for each field. Note that field one is also displayed when you list items. Note also that when using the search editor to search for items (for example when producing a custom report), the fields are labeled “user field 1” etc.., and not with the labels you might have assigned.

Label for 'Their reference' fields

On various transactions, there are Their ref fields for containing the other party's reference (delivery note number, order reference etc.). You can change the label for these fields on the various different transaction types; simply enter the label you want to see in the text boxes.

Purchase order defaults tab

For an explanation of the sections on Purchase order defaults see the 16.02. Purchase order preferences section of this user guide.

Purchase order 2 tab

For an explanation of the sections on Purchase order 2 go to Purchase Order Preferences

Invoices 1 and 2 tab

For an explanation of these sections see Invoices Preferences

Item tab

Default account code for new items

  • There are 3 spaces for you to select the accounts to use. Choose one account for expenses when buying, one account for income when selling and an asset account for stock.
  • The accounts you enter here will become the default accounts for newly created items.
  • The accounts are used when running reports or exporting to financial software.

Default service item for accounting purposes: This field contains the name of service items that will be used when exporting invoices to financial software.

Title for “N” classification for VEN items: You can choose what the “N” in the “VEN” classification of items stands for in mSupply; Not essential or Necessary. The classification is set for an item in its detail window, see the Item basics, General tab page for details.

Item list (master and local): If you check this box, then the visibility of items in stores will be set to match the items on master list(s) selected to be used by that store. For details on how this works and how to set it up, see Controlling item visibility - the Master lists tab.

This preference can drastically affect item visibility. For instance, if a store has no master lists assigned, all items will be made invisible in that store. Could lead to a scary moment!
If some items that are currently visible in a store need to be made invisible when this preference is turned on but they can't (because they have stock, for example) then a temporary master list is created for each store containing the problem items. mSupply will inform you but you should use that list to deal with those items.
Do not turn it on unless you know what you are doing! It affects ALL stores in the system.

If the box is unchecked then the visibility of items in a store is not affected by master lists.

Suggest the next available number for new item code If you want item codes to be assigned automatically (they can still be overridden), check this checkbox. If it is checked, when you create a new item mSupply will automatically set the item's code to the next number in an automatically incrementing sequence. You can override this and edit the code as you are creating the item if you wish.

Universal code Enter the URL of the universal code server, used for providing universal item codes for compatibility between different systems. This is set to the default for you but can be edited if necessary. See the 4.01.01. Items - General tab page for details on setting universal codes for items.

Price tab

On checking the box for “Use customer price categories”, mSupply will activate the price categories.

Price categories

By default all customers are assigned a price category of “A”

To assign a different category to a customer, choose Customers > Show customers… and find the customer entry. Then set the price category field to a different value

Here in the Preferences, you specify what percentage change to the default price will be made for each category.

For example, you might have a group of customers to whom you charge commercial prices, which are 20% above your normal price. Enter “20” in the “B” category field, then assign your private customers a price category of “B”

Ignore price categories for items supplied by these suppliers

Suppliers in this list will have no price category assigned to the items they supply. To add a supplier in this list, click the Add supplier button. A window will appear with a space to write the supplier's name. You can write the first character or two and press enter/return to bring up a list of suppliers that start with those letters. You can then select your chosen supplier from the list. To delete a supplier from the list, highlight it by clicking on it and then press the Delete Supplier button.

Quotes tab

Require entry of quote validity date

Check this box if you want a validity date for a quote to be compulsory.

Automatically turn off preferred status after validity date

If you check this box then the preferred status will not appear when the validity date has passed.

Reports tab

Check this box if you want negative stock values to be ignored on stock history reports (negative values can be legitimate but concerning for some users so negative values are left as zeroes if this preference is turned on).

Names tab

Default field name/Custom field name table: In this list you can change the labels for name categories and custom fields - not the categories themselves (see Name categories for instructions on how to do that) but the labels for the categories. To change one of the labels click on it in the Custom name column to select it and click on it once again to begin editing it. Type the new name and then click outside the label to finish editing it. Now, wherever you would have seen that label in mSupply you will now see the name you have given it. The defaults are shown in the screenshot above.

Example: If category 1 was to be called 'Ownership' and category 2 was to be called 'Classification' then you could change their labels like this:

Now, wherever you would have seen the label 'Category 1' or 'Category 2' in mSupply, you will now see the label 'Ownership' or 'Classification' e.g. in report filters or, as in this screenshot, the General tab of the name details form:

Labels for custom fields on name category: Here you can enter labels for the custom fields used when creating or editing name categories. The labels you enter here will appear on the New/Edit category window instead of the Category_user_field_1 and Category_user_field_2 labels. These labels are used in some reports.

Tenders tab

Tender letter section
  • Title: The title for the printed tender letter. If nothing is entered in here mSupply will use 'Invitation to tender'.
  • Tender reference: The reference for the tender so that, when you communicate with others, you both know which tender you are referring to. If nothing is entered in here mSupply will use 'Tender reference'.
Health Supply Hub section

Note: From version 7.04 of mSupply, the Health Supply Hub has replaced the remote tender module, which is now obsolete and will be removed.

This section of preferences is for the connection to the Health Supply Hub, the replacement for the remote tender module where you can upload yourt tenders for suppliers to enter their quotes and many other things.

  • Use Health Supply Hub integration checkbox: If checked, this tells mSupply that the you are using the Health Supply Hub and certain small changes (extra buttons) will appear in the tenders module. All the other fields in this section are disabled until this is ticked.
  • Integration username: enter the username provided by mSupply for you to login to the Health Supply Hub.
  • Password: enter ther password provided for you to login to the Health Supply Hub.
  • Use custom server checkbox: If checked, tells mSupply to use the server defined by the preferences below it rather than the default, mSupply Foundation server.
    • Health Supply Hub URL: The URL of the server.
    • GraphQL port: The port used by the Health Supply Hub database.
    • Front end port: The port used by the Health Supply Hub interface.
  • Test connection button: When this is clicked, mSupply will attemnpt to use the settings you have entered to connect to the Health Supply Hub. You will be told whether the connection is successful.

Reminders tab

Reminders provide a simple to-do list built into mSupply.

If the Show reminders on startup box is checked, any reminders that are not completed and whose due date has been reached will be displayed in a window when a user logs on.

See Reminders

Patient medication tab

Here you can add a header and a footer that will appear on patient medication records.

Drug interactions tab

When operating in dispensary mode, you can choose to have mSupply alert you to drug interactions. Dispensary mode is covered fully in this section

The number of days of patient history… field determines how far back from the current date mSupply should look for drugs that have a known interaction with the drug you have just entered.

When drug interactions are activated, you will be shown a warning message when you enter a drug on a patient invoice that interacts with other medicines dispensed to that patient during the history period specified.

See the 10.02. Prescription entry page for details about how interactions are used while dispensing to a patient.

Registration tab

If you have a license for the Registration Module (see 26.12. Product (drug) registration), you will need to check this tick-box, and click OK in order to activate it.

You can specify the number of months before a drug registration expires. So when you register a drug, the expiry date of your registration will be calculated automatically by adding the number of months you have specified to that day`s date. For example, if you specify 24 months until a drug registration expires and you register a drug on 24/07/2016, the expiration date will be set automatically to 24/07/2018. If you leave the number of months at 0, you will have to set the drug registration expiry date manually.

Printing tab

For an explanation of this tab please refer to the 16.04. Printing preferences section of this user guide.

OK and print tab

For an explanation of this section please refer to the ok_and_print section of this user guide.

Logo tab

Here you can paste in a logo you have copied to the clipboard - you must copy the contents of a file to the clipboard, not the file itself. The file can be in .jpg, .png, .bmp, .gif, or .tiff format. This logo will be displayed at the bottom right of the navigator.

Make sure the image you use is twice as wide as it is high. If it is not, mSupply will convert it to this ratio which will make it look squashed or stretched, sometimes with interesting results!
For more information on this see the 16.06. Entering a new logo section of this user guide.

If you want the logo to be printed on invoices, check the display logo on invoice checkbox.

Please note that not all printing forms include the logo. If you would like customisation or assistance, Sustainable Solutions can quickly customize forms for you to meet your requirements.

If you have set a separate store logo (see the 26.07. Virtual stores > logo_tab) for the store you are logged into this will be displayed on the Navigator and invoices instead of the one saved here.

Dispensary mode tab

See Dispensary mode preferences for more details about how these preferences are used in practice.

Label printing section

Message on labels The text you type here will be displayed on medicine labels on the last line.

Label format Select the format you want you labels to print in:

  • Default. Example:
  • Item name large, over two lines. Example:
  • Store at the top, no item expiry date and other details. Example:

Custom identification code If you wish to identify the origin of the dispensed item, e.g. In-Patient Dispensary or Out- Patient Dispensary, create an identification code, and enter it in this field. It will then appear as the last item printed on the the right of the third line of each label.

Label body font size The font size, in points, to use for the font in the main body of the label. Selecting Auto means that mSupply will adjust the font size depending on the amount of text to fit in the space.

Footer font size The font size, in points, to use for the font in the footer of the label (the part right at the bottom that is repeated on every label). Selecting Auto means that mSupply will adjust the font size depending on the amount of text to fit in the space.

Printing options for units These are the units applied to items (tablet, vial, tube etc.). Three options are available from the drop down menu. You can choose to always print the units on labels, you can choose for each item whether or not to print the unit or you can choose to never print the units.

Label body font size This defines the size of the font used in the body part of dispensary medicine direction labels. It is set to Auto by default, which means that the text will change size as the amount of text grows so that it can all fit onto a single label. If you choose one of the other sizes (the bigger the number, the bigger the font size), the body text will remain fixed at that size and, if the text cannot fit on a single label, it will overflow onto another label. Please also note that, by default, a double separator line is printed below the header of the label. The second of these lines will be removed if needed to give more room to print text.

If you use a fixed font size, be careful to make sure you get all the labels that belong to a particular prescription after printing them out, you could easily miss one if the directions are unusually long!

Footer font size This defines the size of font used to print the footer of the label, the part that prints at the bottom of every label. It is set to auto by default, which means it will change its size depending on the amount of text there is - more text means a smaller foint so that it fits on the label.

Print prescription label per item If checked, when prescription labels are printed, a separate label will be printed for each line on the prescription. If it is unchecked (the usual setting), lines for the same item will be consolidated into a single line (with the correct total quantity).

Show direction entry in dispensary If checked, users can enter patient directions for dispensed items on a prescription.

Turn off cell padding in between direction and patient name mSupply will automatically pad the cell (leave some space in the cell) between Direction and Patient name. If you do not want this to happen then check this box.

Print full prescriber name on label To have the prescriber's full name printed on labels, check the box in Print prescriber full name. Otherwise, the initials will be printed.

Print organisation address 1 as separate line By checking the box Print organisation address 1 as separate line , you can print organisation address 1 as separate line . You have to set the text in Preferences: General »address 1 field. The text which you type here will be displayed on medicine labels on its own line.

Print patient category on label If checked, when a prescription label is printed the patient's category will be printed alongside the patient's name in the following format; Patient name (category). Note that if the Print Patient code on label option is also checked then the patient's code and category will be printed alongside their name in the format Patient name (code/category).

Print Expiry date of Item on label When checked, the stock line's expiry date will be printed on the label.

Rotate label 180 degrees When checked, labels will be printed out rotated by 180 degrees. Perfect for turning labels the right way up if they come out upside down. Can be an issue if pre-printed labels are used and they are the opposite way round to what you expected.

Allow users to select ward on prescriptions If checked, Patient type and Ward drop down lists are displayed on prescriptions. If Inpatient is selected as the patient type then the Ward drop down list is enabled and the patient's ward can be selected.

Print Sales value of item on label When checked, the stock line's sales value (based on its sell price) will be printed on the label.

Print Patient code on label If checked, when a prescription label is printed the patient's code will be printed alongside the patient's name in the following format; Patient name (code). Note that if the Print Patient category on label option is also checked then the patient's code and category will be printed alongside their name in the format Patient name (code/category).

Print Batch on label When checked, the stock line's batch number will be printed on the label.

Don't print placeholder lines If this box is checked, placeholder lines will not be printed.

Print a receipt on labels by default mSupply allows you to print a patient payment receipt on a label. If you check this checkbox it means that the Print receipt checkbox on the Payment tab of a prescription will be checked by default for all prescriptions.

For more information on printing receipts, see 10.02. Prescription entry

Patients section

Default Patient category The text you enter into this field will be assigned to the category field for new patients.

Default Prescriber name With the cursor in this field, enter the first letter or first few letters of the prescriber's name and press Tab. A window appears displaying prescribers who meet the criteria typed; note that both first and last names appear, and you should select the desired prescriber and click OK to make that prescriber the default one.

Auto-generate patient code If this box is checked each new patient created will have a serial number assigned to them. The assigned code can be overriden by the user.

Prefix codes with The text you enter in this field will be used as a prefix for automatically generated patient codes. e.g. if you enter “t” codes will be assigned “t1”, “t2” etc.

Capitalise patient names Does what it says. The shift key will still override this option.

Prescriber must be entered If this checkbox is checked, then the user will be warned if a prescriber has not been entered when they click the OK button for accept and print a prescription.

Expand abbreviations in patient address fields In the patient address fields, any abbreviations will be written out in full instead of the abbreviation if you check this box.

Share patient prescription over stores If this box is checked, viewing a patient history in one store will show transactions entered in other stores.

Alert if repeat is dispensed before the defined interval of X days If checked then, if a repeat prescription is issued to a customer before the elapsed number of days, an alert is shown to the user for them to confirm whether they wish to continue dispensing the repeat.

Payments section

Default prescription status to finalised: If this is checked the Finalise checkbox on a prescription will be checked when it is first created so that it will be finalised by default when the prescription is first saved. Payments can only be received against finalised prescriptions so if you're going to receive payments from the prescription window on the Payment tab it would be wise to check this preference too.

Receive payments from prescription window: If checked then a Payment tab is added to the prescription entry window and the patient's payment can be entered there. You can still enter a patient's payment separately in the Customer receipts module if required. Whichever of the 2 places you enter the payment, they create an identical transaction. Please note that to activate this preference requires the Activate customer receipts module preference to also be turned on (see General preferences, Invoices 2 tab). If it isn't turned on already you will be asked to confirm that turning it on is OK.

Apply stock to placeholder lines section

This section gives you the ability to apply stock to placeholder lines on prescriptions. We know that in a fast moving dispensary it's sometimes hard to keep up with the stock coming into the dispensary so, sometimes you can get into the position where you physically have stock on the shelves to dispense to patients but you haven't been able to enter it into mSupply yet. mSupply allows you to keep dispensing by automatically adding placeholder lines to the prescriptions instead of normal stock lines. When you eventually enter the stock that you physically dispensed to the patients into mSupply, you need to allocate it to the prescriptions to keep your mSupply stock levels correct. This is the function to enable you to do that.

Simply select the dates between which you want mSupply to look for placeholder lines on prescriptions by manually entering them in the From and To fields or selecting one of the preset selections in the drop down list. Then click on the Apply stock button. mSupply will then search for placeholder lines on prescriptions between the dates you chose. If it finds one it will attempt to replace the placeholder line with real stock from your store on a FEFO basis. If there is enough stock then mSupply will replace the placeholder with a real stock line. If there is only enough to replace part of the placeholder line then it will allocate what stock there is and will leave a reduced quantity placeholder line to represent the stock that still couldn't be allocated.

HIS tab

Backup tab

This tab is used to configure 'primary' backups to be performed automatically according to a schedule.

  • These Preferences are applicable only in single user mode (including single-user sync).
  • In client-server mode, these 'primary' backup details are set on the server.
  • Supplementary backups need to be configured on the Backups 2 tab, regardless of whether you have a single-user or client / server machine.
  • You can perform a manual backup (File > Backup) at any time, independently of this automatic backup schedule.
  • Manual backups will be performed according the the configuration in the lower half of this tab, which can only be changed after automatic backups are enabled.
  • It is not necessary to quit the database before performing backups, manual or automatic.

Automatic Backup
  • To enable automatic backups, the Automatic Backup checkbox needs to be checked. This will then allow you to configure the backups.
Choose backup folder
  • Click the “Choose” button to specify the destination of the backup files.
  • The default location is the same folder as the database itself.
  • If possible, select a different physical volume from the one where your mSupply data is stored.
  • In any case, it is better to locate this in a folder which is available to any user, e.g. D:\mSupply backups
Compression rate
  • This option selects the compression of the backup.
  • Unless you have a very large database and a big bandwidth secondary backup solution, choose Compact. This will give the smallest backup size, but it will take longer to run.

The duplication and block-level comparsisons that services such as Spideroak use mean that it may be better for you to use fast (uncompressed) mSupply backups, as then only the changed portion of your data file will be backed up.

Verify data file after backup
  • This option causes the backup to be verified after each backup is made. This is extra insurance against hardware failures and other factors that can lead to data corruption.
  • We recommend selecting this option.
Restore last backup if database is damaged
  • This option will cause mSupply to attempt to restore from the last backup if the database is found to be damaged.
  • We recommend selecting this option.
Use log file
  • This option causes a log file of mSupply activity to be created. This is like a running an interim backup in that it can be used with the next option to recover any lost activity since the last backup.
  • We recommend selecting this option.
Integrate last log if database is incomplete
  • If your database becomes damaged and this option is checked, then mSupply will automatically restore the data from a backup and use the log file to restore all transactions between the last backup and the end of the log.
  • We recommend selecting this option.

Backup 2 tab

The Backup 2 tab allows configuration of supplementary backups. This is useful for making copies of just some of your backups that you can then send off-site, e.g. using Dropbox or Google Drive, etc.

Automatic backup to secondary folder:
  • Checking this option results in mSupply trying to copy completed backups to another folder which you specify with the Choose button below. Fill in the Backup every …..th file… field with number of backups out of which one copy will be kept. That is, entering 7 will result in one backup per week being copied.
  • You will need to configure your online backup software to use the folder chosen as the secondary backup location as the source folder for backups. Note that if you have plenty of upstream bandwidth, you might choose to ignore this Backups 2 tab and simply set your main mSupply backup folder as the source folder.
Secondary backup options 1, 2, 3

mSupply allows you to make up to 3 secondary backups to separate locations if you would like to. You can use 1, 2 or all 3 if you would like to. At least one is recommended for security purposes.

E-mail tab

You can choose to send orders, reports, invoices and notifications to recipients using e-mail in mSupply. However, before mSupply can send anything by e-mail you must tell mSupply about the server you wish to use and details of the e-mail described below:

Provide me with a mail server to send emails

If this is checked you will use mSupply's own internal email server to send emails. The sender email address will be set to remote@sussol.net and the email address will be set to the sender's email address for all mSupply generated emails.

If it is unchecked you will use your own email server, the details of which you must enter in the Mail server name, Username, Password, Port and Use SSL fields described below.

Please note: it is possible that emails sent from mSupply could end up in the recipient's spam or junk folder. If this happens, ask the recipient to find the email and mark is as not spam to fix the problem. This problem could be particularly present with Google controlled email addresses because of the way Google processes emails. Please be assured that our email servers are fully compliant with all the latest security procedures and protocols.

Mail server name

The name of your mail (SMTP) server. eg “mail.mac.com”. You can only enter this if you are not using mSupply's inbuilt e-mail server (i.e. Provide me with a mail server to send emails is unchecked).

User name

The username mSupply will use to authenticate itself to the mail server. Only needed if you are not using mSupply's inbuilt e-mail server (i.e. Provide me with a mail server is unchecked).

Password

The password which goes with the username. (Only when not using mSupply's e-mail server)

Use SSL

If this is checked mSupply will use the Secure Socket Layer protocol to send e-mail. A more secure way of sending e-mails but only check this if your mail server can support SSL.

Port

The port on the mail server which mSupply will send e-mail to (must be the same port the mail server is listening on!). (Only when not using mSupply's e-mail server)

Return email address

Enter an email address you would like any response to come to. mSupply cannot send email unless it also has a return address for email.

Signature

The text you enter here will be added to the end of all e-mails you send. You might want to put your organisation contact details here. It is generally poor etiquette to make your signature too long.

By default use a mono-spaced font to view text

A mono-space font such as “Courier” or “Monaco” is better for viewing text in columns, such as is produced by the automatic order generation in mSupply . However, visually it has less 'eye appeal'.

Default subject line when creating orders

When mSupply automatically turns an order for a supplier into an email, the text entered here will be put in the subject line. For example you might want to put “Acme Hospital order” to advise the supplier of its contents. Note that you can edit the subject line of automatically generated emails before you send them.

Sort order lines for email and HTML export by item name

This option allows emails generated automatically to be sorted alphabetically by item name before the email is created. If this option is left unchecked, emails will use the creation order of the order lines to create the email.

Server tab

These settings are all for mSupply's built-in webserver, which is used for things such as the Dashboard, mSupply mobile, online catalogue and the Customer interface. Note: To use this feature an additional license is required. Please contact The mSupply Foundation for further information.

Start web server on the server when mSupply server starts

The web server can be started automatically when mSupply starts by checking the box (it will only start on the central server!), or manually when you want to use it by clicking the Start Web server button.

Run the web server on port

The default port is 8080. This is the port used for non-secure http connections.

Use the following port for SSL

The default port is 2048. This is the port used for secure https connections.

Web URL

The URL of the web server to connect to. If this does not begin with “https://” you are shown an alert. You most likely do want to use https if you're making these settings in a live envoronment. And if you're setting up synchronisation then you won't get any connection if you don't use https.

Enable Support DB Integration

If this checkbox is checked (only possible on the central server) this copy of mSupply will send support information to The mSupply Foundation's support database once a day during a time of low activity on the server at night: this is information about all the remote sites, their names, the type and version of mSupply they are running, whether they are registered, the time they last synchronised with the central server, when their latest transaction was entered and when their first stocktake was created.

  • Username: The username to use when connecting to the support database.
  • Password: The password to use when connecting to the support database.
  • URL: The URL of the support database.
  • Test connection button: Click this to validate your settings and check the connection to the support database. An alert message will tell you whether the test was successful or not.
  • Push now button: Click on this button to send the support information immediately rather than waiting for the automatically scheduled time. You will be shown the progress of the data send and told whether it is successful or not.
Disable the customer order web module and display the following message:

Check this if you want to take the customer ordering module off line and enter the message you want to display to customers who access the module.

Web URL

The address of the remote authorisation web app. This is used by mSupply when emailing authorisers to tell them that a requisition needs their attention in the remote authorisation web app. Enter the full URL, starting with “http” and including any port that is used. See the 26.15. Remote authorisation page for details.

Inactive users are logged out after X minutes

For clients connected to an mSupply server, this is the maximum period of inactivity after which the user is automatically logged out. The user must then log in again to continue using mSupply. A setting of 0 disables this function and then inactive users are never logged out.

Default store for web interface

Choose which store you want to be the default for the web interface (only applicable if you have more than one store). Be careful when changing this option because it will change the default store that all the web interfaces will use to get information from mSupply, not just one of them.

User can create XX uncompleted orders at a time

This limits erroneous submission of too many orders. Choose the maximum number of orders that a customer can make. If they have reached the maximum amount, they will be able to create more when other ones are completed.

Maximum allowable time a mobile interface request can take

This sets how long mSupply will keep trying to supply report data before it gives up and displays an error message.

Synchronise tab

For an explanation of this section please see the 16.07. Synchronisation preferences section.

Customisation options

Should a client wish to have customised features which are specific to their version of mSupply, we are happy, whenever possible, to incorporate such features.

If you are running such a customised version of mSupply, you will have received from us a Customisation code . To activate the customised features, that code must be entered in this field.

Moneyworks tab

If you use the superb Moneyworks accounting software, you can have mSupply directly input invoices into Moneyworks.

Contact info@msupply.org.nz for more information on these options.

Visit http://www.moneyworks.sussol.net for more information on Moneyworks, including a free demonstration version.

The Moneyworks application must be installed on your machine, and this option establishes a link between mSupply and Moneyworks. Don't turn it on if you don't know what you're doing, or if you haven't set up Moneyworks as described below.

Three options are presented in the drop down menu:

  • Gold - select this option if the Moneyworks application you are using is the one installed on your computer.
  • Gold Client - select this option if you are connecting to the Moneyworks application installed on another machine on your network.
  • Data Centre Client - select this option if you are connecting to a Moneyworks Data Centre
Export to Moneyworks when finalising individual invoices

This allows for production of individual invoices, e.g. for non credit customers, who make cash purchases; if you have such customers, check this box , but if all your customers are credit customers, receiving monthly statements, it may be left unchecked.

Location of the Moneyworks application

mSupply needs to know the location on your computer of Moneyworks , and by clicking on the Choose button, a window appears, and you should navigate to the location of the Moneyworks .exe file

Document log on

Enter your logon details to access the Moneyworks document that you want to access.

Data center log on

If you are using a partitioned data center, enter your logon details to gain access to the partition where your document resides. If you are not using a partitioned data center then leave this section blank.

Location of the Moneyworks document (datafile)

You need to identify the Moneyworks document (datafile) you are using

If your link is to Gold, this is done by clicking on Choose , and navigating to the file's location. If access to the file is restricted, you need to complete your user name and password in the fields under Document Logon

If your link is to the Client option, when you click on Choose , a window appears and you need to enter the name of the Moneyworks datafile to which you are connecting; the file's restrictions will require you to enter your user name and password in the fields under Data Centre Logon

Type of customer invoice export

The drop down menu allows you to choose from several options:

  • Single income account
  • Separate income accounts by item account
  • Choose for store
I.P. address of machine using Moneyworks

You only need to fill in the I.P. address here if:

  • You are on Macintosh and
  • You are connecting to a remote machine across a network.

If you are on Windows or a Mac connecting to a local installation of Moneyworks, make sure this field is empty.

Notes on setting up Moneyworks
  • The import into Moneyworks relies on using an import map. The map for supplier invoices must be named “si_import.impo” and the map for customer invoices “ci_import.impo”. These map files must be stored in the “Import Maps” folder inside the “Moneyworks Customer Plug-Ins” which is next to your data file.
  • The advantage of using import maps is that it gives you flexibility in deciding which accounts will be designated for sales and purchases, and the way the fields exported from mSupply are used inside Moneyworks.
  • If you would like sample import maps from Sustainable Solutions, please email us at info@ss.org.np.
  • Once you have set up the import maps and turned on the “Link to Moneyworks accounting software” checkbox, mSupply will attempt to send invoices to Moneyworks that are finalised using the “finalise customer invoices” and “finalise supplier invoices” commands.
  • Note that the “Export invoices when finalising” option must also be checked. (See Preferences> Invoices)
  • If you get an error when exporting, usually you will get a message telling you what the problem is. Things to check include
  • Is Moneyworks running …… it must be!
  • Make sure the correct I.P address is specified if connecting to a remote machine on Macintosh.
  • Make sure any charge codes used are actually present in the Moneyworks data file you are using. We can supply a version of mSupply that automatically adds names to the Moneyworks data file if they aren't found when exporting, but this costs extra!
  • Make sure that Moneyworks has open periods for the dates of the invoices that are about to be imported.
  • If you still have no success, turn off the Link to Moneyworks. .. checkbox, and produce a file. Then manually import the records into Moneyworks using the File > Import > Transactions command (making sure you load the correct import map using the “Load” button). The file has errors, Moneyworks will give a more complete error report.
  • Note that if export to Moneyworks is not successful, the transactions will not be finalised in mSupply, so you will not get invoices that are missed in Moneyworks.

We are also able to provide a similar option to link with Quickbooks accounting software. Please contact info@ss.org.np if this is of interest to you.

FrontlineSMS tab

If you use FrontlineSMS for sending information to mSupply via SMS messages (using mobile phones), this is the tab where you enter all the settings.

For an explanation of this tab please go to FrontlineSMS preferences.

eLMIS tab

This tab contains 2 different interfaces to OpenLMIS variants. The first is for an earlier variant and uses a common internet based folder to process incoming orders and create outgoing shipment files in csv format (for more information on this interface please see the 23.04. mSupply eLMIS interface section). Countries such as Zanzibar and Tanzania use this variant.

The second is for a slightly newer variant of OpenLMIS used by countries like Côte d'Ivoire and sends requisition information from mSupply directly to the OpenLMIS database.

The eLMIS Preference fields:
Fields updated in mSupply v4.03

  • eLMIS Interface
    • Use the eLMIS interface: Check this box to enable the interface.
    • Interface Folder: Click on the Choose… button to select the main folder that eLMIS and mSupply will use to share data. For information on creating this folder please see the 23.04. mSupply eLMIS interface > setup section in this user guide. DO NOT click on the Choose… button unless you're using an mSupply client that is running on the mSupply server computer. Otherwise, you'll set a local folder on your local computer which the server will not be able to reach and the interface will not work.
    • Time between scans for new information from eLMIS: Enter the number of hours mSupply will wait between checking for new files to process.
      When the Use the eLMIS interface checkbox is checked this setting tells mSupply to check the Interface folder > Orders > Incoming folder every X hours for any new order files to process.
    • Scan now button: Click this to make mSupply check the /Interface folder > Orders > Incoming for new files to process immediately. Useful if you have manually added a file to the folder and want mSupply to process it immediately instead of waiting for the Time between scans for new information from eLMIS interval set above to elapse.
    • Send errors to this email address: The email address mSupply will send any error information to. This would normally be the address of your eLMIS helpdesk.
  • eLMIS Requisition Integration
    • Use eLMIS requisition integration: Check this box to enable the interface.
    • URL: The URL for the eLMIS server. This must be in the form http://xxx or https://xxx
    • Username: Your eLMIS database username
    • Password: Your eLMIS database password
    • Test connection button: Click this to test the account credentials you have entered. You must have the Use eLMIS requisition integration: check box ticked to use this. An alert will tell you whether the test connection was successful or not.

LDAP tab

This section is where you define the details of the LDAP (Lightweight Directory Access Protocol) server you are using to provide user authentication for logging into mSupply. There is no need to fill in these fields if you are not using an LDAP server to check user logins:

Server URL or IP: enter the URL or IP address for your LDAP server.

Port no.: enter the port number your LDAP database is being served on.

Dashboard tab

See the 16.05. Mobile Dashboard set up (before v4.0) section of this user guide for a detailed description of the process.

Note, from mSupply v4.0 and later, this dashboard tab has been removed and a new and improved dashboard has been introduced. The new dashboard has a different setup process, see the 19.06. Mobile Dashboard set up (after v4.0) section for details.

DHIS2 tab

See the 23.01. DHIS2 integration section of this user guide for a detailed description.

NHLMIS tab

This is for integration with the Nigeria Health Logistics Information System. Please see the 23.07. NHLMIS integration page for detailed information.

NHLMIS 2 tab

This is for integration with the Nigeria Health Logistics Information System. Please see the 23.07. NHLMIS integration page for detailed information.

Stock tab

This section is where you tell mSupply which custom stock fields a user can fill in when receiving stock on a supplier invoice. There are 8 fields available. Fields 1 to 4 are free text but fields 5-8 contain values which are selected from a list you define:

Each of the fields you tick the “Show” checkbox for will appear on the bottom of the supplier invoice line detail form when receiving stock. The first 4 fields will also appear in a goods received note and several other places throughout mSupply where stock lines are shown. They will appear with the label you give them in the “Display name” column (click once in the column to make the cell editable then type the name).

The values you enter in these fields (or select for the fields if it's one of fields 5-8) will be attached to the stock and follow it through the system. See the 7.05. Custom stock fields section of this user guide for details.

Custom fields tab

You can create custom fields that appear in different areas in mSupply. These allow you to record additional information and customise mSupply for your needs. See the 16.11. Custom fields section of this user guide for details.

Barcode scanning tab

This contains the settings for your barcode scanner. See the 16.09. Barcode scanning preferences section of this user guide for details.

Options tab

You can create a list of options (or reasons) for the user to select from when they use perform certain transactions in mSupply. See the 16.10. Options (standard reasons) section of this user guide for details.

The mSupply Link is an intermediary service for requesting, sending and receiving stock between discrete mSupply instances. For information on this please see the 12. mSupply Link (Supplier Hub) section.

Alternate server tab

The alternate server is used for sending cold chain notifications. For more detail please see the Setting up Cold Chain App Notifications page.

Assets tab

  • Send insurance renewal emails checkbox: If this is checked then mSupply will check every night for assets with an insurance renewal date that is X weeks away from the current date (where X is set in the next preference below). If there are any then mSupply will send an email with a list of all the assets whose insurance renewal date is X weeks away to the email address specified. Only one email will be sent for the assets.
  • Send email X weeks before insurance renewal date text field: The number of weeks before the insurance renewal date that an email should be sent. Must be greater than 0 and must be entered if the checkbox is checked.
  • Send email to text field: The email address to send the email to. Must be in the right format and must be entered if the checkbox is checked.

Web catalogue tab

This tab determines all the settings for the online catalogue:

If the web server is running (see the Server tab section above for details on how to turn it on) but the Publish item list on web checkbox is not checked, when a user goes to the catalogue web page (see the 19.07. Online catalogue page for details) any message you enter in the Would you like to display any messages on the web? text field will be displayed on the page instead of the item catalogue. This would typically be used if the catalogue is under maintenance because the prices or other item details were being updated.

If you check the Publish item list on web checkbox the Would you like to display any messages on the web? text field is removed and replaced with a Catalogue display settings section:

In this section you select which columns are displayed, what their label will be in the catalogue and whether they are searchable in the web catalogue.

For details on how to configure the web catalogue generally, see 9.07. Online catalogue.

In the catalogue, the details of items matching the search filters are displayed in a table. That table has various columns which can be selected and defined on this tab.

  • The Available list shows all the columns that are available but not chosen for diaply in the catalogue.
  • The Chosen list shows you all the columns that are chosen for display in the catalogue - they will be displayed when the user visits the item catalogue.
  • The Display list shows the display name of the corresponding Chosen column i.e. what name it will have in the catalogue.

To make a column shown in the Available list display in the catalogue, select it by clicking on it and then click on the button to move it to the Chosen column.

To remove a column from display in the catalogue, click on it in the Chosen list then click on the button to move it back into the Available column.

By default, any column in the Chosen list is given the same Display name. If you want it to have a different display name in the catalogue, simply click on it in the Display list and edit the name there.

To allow users to search by a column, check the checkbox in the Search by list. Any columns that have this checked will be added to the filters available in the catalogue.

HL7 Integration tab

See the 23.08. HL7 and Tamanu/Patis Plus integration page for details on this tab.

Previous: 16. Preferences | | Next: 16.02. Purchase order preferences

16.03. Invoice preferences

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.
Invoices 1 tab

All invoices
Allow editing tax rate and amount on invoices

When checked the tax rate can be changed when entering an invoice. Otherwise, the default tax rate is always used. (On supplier invoices the actual tax amount can be directly edited if this option is checked. This allows perfect matching of tax amounts with amounts charged by a supplier).

Allow entry of dates on invoices

Normally the confirm dates on invoices are read only and are filled in automatically by mSupply when the invoice is confirmed. If you need to enter your own dates, check this option and enter a number in the 'Maximum days before current date' box (you might see a default number of 30 days in here which you can change). Note that you will not be able to modify the dates on finalised invoices.

The entry date is still maintained by mSupply. You can only edit the confirm date.

Export invoices to disk when finalising

If this box is checked, each time you finalise customer or supplier invoices, a tab-delimited text file of the finalised invoices will be created. This allows you to import the data into an accounting application.

After deleting lines, redo the numbering

If this box is checked, deleting invoice lines will result in all invoice line numbers being updated so there is no gap in the numbering.

Activate budget module

In order to use the Budget feature, this box must be checked. This feature is applicable to store mode only. For more information on the budget module see Customer Budgets

Activate ad hoc items

Ad Hoc items allow you to receive and issue items that you will only use once. That is, you have ordered the item for a particular customer, and do not want to hold it in stock. For further information, see Ad Hoc items

Reuse deleted invoice numbers

If checked then, when a customer or supplier invoice is deleted, the invoice number will be used again when a new invoice is to be created.

Use program pricing

If checked then the sell prices for items on customer invoices are taken from the first master list that is to be used as a price list.

Round prices

You can choose to round prices to a given number of decimal places. By default prices will be rounded to 2 decimal places.

Supplier invoices
Allow editing margins on supplier invoice lines

If this option is chosen, you can edit the margin for individual supplier invoice lines. Otherwise the margin will be locked at the margin set for that supplier in the window for editing supplier details (reached from the supplier > edit supplier menu.)

Hide batch number and expiry date entry

Some people use mSupply for inventory control of all sorts of general goods. Hiding these fields will speed up entering information if you do not use those fields.

Item margin overrides supplier margin on supplier invoices

When receiving an item where there is a margin set for both the supplier and the item, if this option is checked the item margin will be used. If unchecked, the supplier margin is used.

Activate supplier payment module

Check this box if you want mSupply to record the outstanding amount to be paid on each supplier invoice. If this system is not activated, supplier invoices will display a zero amount outstanding. (If you use a separate accounting system, and us mSupply's export facilities, there is no need to use the inbuilt payment system).

Warn if expiry less than XX days

An appropriate figure can be entered.

Disallow remove hold status if zero sell price

If this option is checked you can't receive goods that haven't had their sell price set.

Sell price changes affect un-finalised customer invoices

If you tick this, when you update a sell price the change will be reflected in all non-finalised customer invoices. You will be asked to confirm ticking this box because it can make irreversible changes to customer invoices. Here is a table that shows the differences with having this preference turned on or turned off

Original invoice

Item Date Invoice type status price
Amoxy 250 15 Feb Supplier invoice cn 8.00
Amoxy 250 15 Mar Customer invoice cn 8.00
Amoxy 250 15 Apr Customer invoice cn 8.00
Amoxy 250 15 May Customer invoice fn 8.00

With preference turned off

Item Date Invoice type status price
Amoxy 250 15 Feb Supplier invoice cn 9.00
Amoxy 250 15 Mar Customer invoice cn 8.00
Amoxy 250 15 Apr Customer invoice cn 8.00
Amoxy 250 15 May Customer invoice fn 8.00

You have found that the price should have been 9.00 No customer invoices are updated. Reports on old customer invoices will show the old price of 8.00

With preference turned on

Item Date Invoice type status price
Amoxy 250 15 Feb Supplier invoice cn 9.00
Amoxy 250 15 Mar Customer invoice cn 9.00
Amoxy 250 15 Apr Customer invoice cn 9.00
Amoxy 250 15 May Customer invoice fn 8.00

You have found that the price should have been 9.00 Old customer invoices are updated unless their status is “fn”. Reports on old customer invoices will show the new price of 9.00 (as long as no invoices were finalised)

Show inner and outer pack fields

If checked, mSupply will allow the entry of the “inner” and “outer” pack sizes. The “inner” pack size is the number of primary packs that fit in a carton and the “outer” pack size is the number of cartons that fit on a pallet. So, for example, if an item is packed in packs of 1000, there are 24 of those in boxes and then there are 15 boxes on a pallet, the “inner” pack size would be 24 and the “outer” pack size would be 15.

When turned on, this preference results in an extra Quan per inner and Inners per outer field being displayed on the supplier invoice line input window shown on the 7.01. Supplier invoices page like this:

Hold invoices by default

If checked all newly created invoices will be on hold

Allow tracking of received stock by donor

If checked, this option allows the user to track donated stock from source (supplier Purchase Order) to store (available for distribution in mSupply).

Invoices 2 tab

Customer invoices

These options apply to customer invoices only.

We run a backorder system

Check this item if you want to record backorders for customers for supply at a later date (For suppliers, backorders are recorded in the ordering system as partially supplied orders).

Note that if you use a backorder system it will affect the way “placeholder” lines are handled.

A placeholder line is a line entered on a customer invoice which does not have any stock associated with it. Placeholder lines can have an item name, a quantity, and a pack size, but the batch number is set to “none”.

When you confirm an invoice, if you are using a backorder system, placeholder lines will be transferred to make backorders. If you are not using a backorder system, placeholder lines will be deleted if the option below is turned on.

Auto-issue customer backorders when stock arrives

Check this item if you want stock to be automatically issued to a customer with a backorder when it becomes available.

Allow placeholder lines on customer invoices

If you leave this box unchecked, all lines on an invoice will have to be actual stock. If you run a backorder system you must check this box.

Show notes in store

If this box is checked, the customer invoice line edit window for issuing stock will be enlarged to show the Notes area to enter customer directions or notes, like this:

These notes print on invoices after each invoice line.

Show abbreviation fields

This preference only has an effect if the Show notes in store preference mentioned above is turned on. When it is turned on, additional abbreviation fields are displayed with the Notes field to allow the user to use shortcut abbreviations, like this:

Abbreviations help fill in the notes field quickly, including with default directions or text set for the item. See the 10.06. Abbreviations for dispensing page for details of how to set them up.

When the item is selected on this window, the abbreviations avsilable are populated in the drop down list and the item's default dorections (if set) are selected by default.

Activate customer receipts module

Check this box if you want mSupply to record the outstanding amount to be paid on each customer invoice. If this system is not activated, customer invoices will display a zero amount outstanding. Please note that if the Receive payments from prescription window preference is turned on (see General preferences, Dispensary mode tab and you want to trun this preference off, you will be asked if it is OK to turn off the Receive payments from prescription window preference too - that preference requires that the customer receipts module is turned on.

Show item category while issuing goods

If you are making use of the item category facility, checking this box will allow you to see the category of the item you are issuing as it is being issued.

Show 'nw' transaction created by user on log-in

If you check this box then, after a user has logged in, if there are any customer invoices created by this user that are still at 'nw' (new) status then they will be shown a message:

Clicking on the OK button will take the user to a list of their nw status invoices and they can double-click on any of them to edit as usual:

Handy for helping invoices to not get forgotten!

Choose contact for transport details

Checking this box allows you to choose a contact from your list of contacts when entering transport details.

Show 'Add from BOM' button

Checking this box allows you to create an invoice using a Bill of Materials. The function inserts placeholder lines from BOM into the invoice - see here for details.

Show custom transaction fields

There are 4 customer transaction fields available for customised entries; their use is optional, and should you wish to use them, they have to be activated here, where the Show custom transaction fieldscheckboxes should be checked. You will note that they are grouped in pairs, 1 & 2 and 3 & 4, and this is also the window which allows you to define names for the fields; for example, you might wish to identify the person preparing the invoice and so give field 1 the name “Prepared by”; similarly the person authorising the invoice could be entered in field 2, which would be named “Authorised by”.

Warn if expiry is less than XX days

Entering a number in this box causes mSupply to alert the user when any batch selected for issue is due to expire before this number of days has passed. An alert will be displayed when manually selecting stock for issue on a customer invoice or automatically selecting it with the Issue stock for all placeholder lines function, Backorder button, History button and Prescription repeats functionality.

Disallow issue of goods with short expiry

If this option is checked, mSupply will not allow issue (on customer invoices and prescriptions) of goods with an expiry date less than the number of days specified here. Goods with no expiry date will not be affected. Note that once this preference is checked, there is no way for the user to override it; the rule is enforced until the preference is turned off.

Enter zero in the field to disallow entry of goods that have expired.

The restriction is applied to manually selecting stock for issue on a customer invoice or prescription or automatically selecting it with the Issue stock for all placeholder lines function, Backorder button, History button and Prescription repeats functionality.

Note that inventory adjustments and supplier credits can still be issued to remove goods from stock or return goods to a supplier.

Activate restricted item access by customer group

When this check box is checked, any item that is assigned to a department may only be supplied to customers who are members of groups linked to that item's department.

See the section in the Item Menu chapter on the Manage item access… for more information on how to set up item departments, customer groups, and how to link groups to departments.

Warning: Checking this item may mean that some items can not be issued. Make sure you have set up the item access system properly before proceeding.

Delete placeholder lines when confirming invoices

When checked, placeholder lines are deleted when the invoice is confimed.

Require category entry on customer invoices

If this option is checked, when entering customer invoices the user will be required to select one of the available transaction categories. Transaction categories are set up using the Special > Show transaction categories menu item. If no transaction categories for customer invoices have been set up, this option will have no effect.

Hold invoice by default

Invoices will be put on `hold' if this box is checked.

Customer order written date must be entered

If checked, the Order written date field on a customer invoice (on the Transport details tab) must be filled in - if it isn't the user will be shown an alert message and asked to fill it in.

Customer order received date must be entered

If checked, the Order received date field on a customer invoice (on the Transport details tab) must be filled in - if it isn't the user will be shown an alert message and asked to fill it in.

Other invoices
Allow customer to enter stock balances and request on stock history

Checking this box allows a customer to enter the quantity of stock they have and mSupply will file it as part of their stock history and calculate how much needs to be sent to them to replenish their stock.

Limit patient and customer credits to previously prescribed items

Users can only issue patient credits or customer credits for items previously dispensed/issued to the patient/customer. When this box is checked, users must select items to credit from the History button and cannot manually add new items using the New Lines button.

Invoice printing preferences

Please see 16.04. Printing preferences

Previous: 16.02. Purchase order preferences | | Next: 16.04. Printing preferences

16.10. Options (standard reasons)

In a synced system, Options must be added on the central server and will then sync to other sites where they will apply to all stores on each site.

You can create a list of options (or reasons) for the user to select from when they perform certain actions in mSupply (in drop down lists etc.). Options are an alternative to the user typing free text, and can help standardise information being recorded in mSupply, which facilitates reporting.

You can enter options for:

  • Requisition Line Variance: Reasons for a variation between the suggested quantity and entered quantity in a requisition line.
  • Positive Inventory Adjustment: Reasons for a positive adjustment between the snapshot quantity and entered quantity in a stocktake line (to help answer the question why is there more stock than expected?).
  • Negative Inventory Adjustment: Reasons for a negative adjustment between the snapshot quantity and entered quantity in a stocktake line (to help answer the question why is there less stock than expected?).
  • New Cash Out Transaction: Reasons for a cash out transaction (taking cash out of the cash register).
  • Open vial wastage: Reasons for open vial wastage when dispensing vaccines (see the mSupply mobile user guide for details).
    • Closed vial wastage: Reasons for closed vial wastage when handling vaccines in Open mSupply.

Creating options

1. Go to the Admin tab on the Navigator and click the Preferences button:

2. Click on the Options tab in the list on the left hand side to see this page:

3. Select the transaction type requiring options from the dropdown list at the top. When you do that, the table will show all the existing options for that type.

4. Click the Add Option button and this window will open:

5. Enter a name for the option in the Option field, then click on the OK button to save it.

Once an option is saved, it cannot be deleted. Check carefully before pressing OK! If you need to prevent an option being available for selection by users then make it inactive. This will mean old options can be displayed correctly in historical records but they are no longer available for use by users.

All options in use have the Active box ticked and will now appear for selection in the given transaction type.

If an option is no longer in use, find it in the list, double-click on it and uncheck the Active checkbox. This will remove it from the list of options available for a user to select.

This is what the list looks like with some active and some inactive options:

Using options

This section shows how options appear in each transaction type after they are created.

Requisition line variance

This type appears when creating a Requisition.

If there are any active options of this type, when a user enters a User Requested Quantity that is different from the Calculated Quantity, the list of active Requisition line variance options automatically appears in the Reason column and one must be selected:

Positive or negative inventory adjustment

When any active options of these two types are available, they are used in a stocktake (see the 4.17. Stocktakes page) or when manually creating inventory adjustments (see 4.19. Inventory adjustments).

Stocktakes

In the main stocktake window, if the Enter Quantity value is adjusted to be different from the Snapshot Quantity value like this, for example:

then the edit stocktake line edit window is automatically opened and you must select an option from the Adjustment reason drop down list:

If you click on the OK button before selecting a reason you'll be prompted to choose one:

Of course, the same is true if you double-click on a line in the main stocktake window and edit the Stock take qty value to be different from the Snapshot Quantity in the stock take line edit window; you must select a reason from the Adjustment reason drop down list before you can proceed.

If the Counted quantity is greater than the Snapshot quantity the Adjustment reason drop down list is populated with Positive inventory adjustment options, if it is smaller then it will be populated with Negative inventory adjustment options.

Any reasons entered on a stocktake are carried through to the corresponding inventory adjustment lines that are created when the stocktake is finalised.

Inventory adjustments

If there are any active Positive inventory adjustment type options, you must select one of them from the Adjustment reason drop down list when adding a line to an Inventory adjustment - add stock transaction and they will appear in the Adjustment reason column:

If there are any active Negative inventory adjustment type options, you must select one of them from the Adjustment reason drop down list when adding a line to an Inventory adjustment - reduce stock transaction:

New cash out transaction

When creating a new cash out transaction (see the Cash Out section for details), if there are any active New cash out transaction type options then you must select a reason from the Option dropdown list that is displyed in the window:

Payment type

When entering payments on a prescription (see the 11.03. Prescription payments and credits page for details), if there are any active Payment type options then you must select one from the drop down list in the Payment details section on the Payment tab of the prescription before a payment can be saved:



Previous: 16.09. Barcode scanning preferences | | Next: 16.11. Custom fields

16.04. Printing preferences

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.

Preferences related to the printing of invoices appear in this window, allowing users to customise the printing of customer invoices.

Don't print placeholder lines on invoice

Check this option if you don't want placeholder lines to appear on your printed invoices.

Don't use label printer for prescriptions

Check this option if you want to use a normal printer (not a label printer) to print prescriptions.

When printing a pick list...
Sort by

This refers to how the items on the list are ordered. You can choose to sort by

  • line number: the order in which they were entered
  • shelf location: which will enable a “logical” order for picking goods from the shelves

You can also set a priority for shelf locations, and this will override the default alphabetical ordering i.e. locations with a priority of 1 will come first (in alphabetical order), then those with a priority of 2 etc., with priority 0 locations at the end. See Locations and location types for more details.

By default mSupply will print a single pick list for all locations. If, for instance, you need separate pick lists printed for cool store items (whose locations in your store start with “CS”), and for Dangerous drugs (whose locations in your store all start with “DD”), you would enter “CS,DD” (no quotes, each location separated by a comma) in this field. If a pick list being printed contains CS items, they will be printed separately, and the same for items with a ”DD” location.

Edit messages on printed forms

If you would like to print a particular message on one or multiple printed forms you can do that here. Choose the appropriate form from the drop-down list (menu), and then click the Edit button to edit the message that will appear on the bottom of every form of that type. For example, you may use the special invoice for issuing narcotics, and have the following message: 

  * I have received the above Narcotics.
  * Signed:.........................
  * Print name:..................
  * Position:.......................
  * Date:.............................

A message on a pick list might be as follows: 

  * Packed by:..................
  * Date/time:..........................
  * Checked by:........................

When you have written the message, click OK and you can either add another message to another form (choose another one from the drop down list) or move on to another preference.

Other

If this item is checked and you are using the mSupply cash receipts system, the outstanding customer balance will be printed at the bottom of each invoice.

There are two spaces here. In one you can enter the header that you would like to appear on reports by default. The text will appear on the top left header for most reports. A common use of this space is to include your organisation name.

In the other you can enter the default footer. Text you enter here will appear on the bottom centre space of each page of reports. You might use this space to include a confidentiality clause on your reports.

OK and print

Checking these boxes means that the printing checkbox will be checked by default when the corresponding window is opened.

Note that you can still manually turned the option on or off in a window- these settings just affect the default value.



Previous: 16.03. Invoice preferences | | Next: 16.05. Mobile Dashboard set up (before v4.0)

16.02. Purchase order preferences

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.

There are two tabs of purchase order preferences in the File > Preferences… menu item.

Purchase order defaults tab

This window allows you to enter text that will be printed on Purchase Orders.

The easiest way to see how these fields will look on a Purchase Order is to fill in the fields and then print a sample Purchase Order. Note that we are willing to design custom Purchase Order forms to meet individual needs.

Purchase order 2 tab

When this box is checked a section will be printed on Purchase Orders that shows the authorising officer(s) and includes a space for signatures. This is applicable if you print Purchase Orders and post them to suppliers, but should most likely be turned off if you send Purchase Orders via email.

Number of decimal places for price

This field allows you to specify the number of decimal places that may be entered in the price field on Purchase Orders. This will override the currency format setting in tne Misc tab only for the price field on Purchase Orders.

Prefix printed purchase order number with

Enter any required prefix in this field

Default number of days usage to evaluate when creating an order

Enter the number of days to “look back” when evaluating each item's usage to calculate the amount of stock needed. Entering a higher number will give a better long term average, but will mean that orders take longer to create.

Purchase order category must be chosen

Check if you need a Purchase order category to be chosen on every purchase order.

This can be overridden by the user if they hold down the shift key as they click OK

Expected delivery date must be chosen

Check if required, leave unchecked if not.

Show purchase order custom field

Check this box if you would like an extra field added that you can customise and use for your own purposes.

The space below this check box is for you to enter the name of your custom field.

Purchase order contract date must be entered

If you require this information on your purchase orders then check this box - this will force users to enter it when a purchase order is created.

Purchase order advance payment date must be entered

If you check this, the Advance paid field must be completed when a purchase order is created - a user will not be able to save a purchase order without entering it.

Purchase order received at port date must be entered

If you check this, the Received at port field must be completed when a purchase order is created - a user will not be able to save a purchase order without entering it.

Procurement is done centrally

This option is only relevant for a synchronised system (refer Remote Synchronisation). If you select this option, purchase orders for stores on sync satellites can only be prepared, confirmed and finalised on the sync primary. There is a work-around if you need some stores on some sync satellites to do their own purchase orders. For help with setting that up, contact support@msupply.org.nz.

Requested delivery date must be entered

If this is checked, the requested delivery date (RDD) on the purchase order must be entered before you can add lines to it. RDDs must also be entered for each line. If unchecked, entering a requested delivery date is optional.

Unit cost (price before discount) must be entered

If this is checked, the Price before discount field must be entered for every purchase order line. If unchecked, entering it is optional.

Re-use deleted purchase order numbers

If this is checked, the numbers of deleted purchase orders will be re-used on the next new purchase orders created. For example, if I delete purchase orders 7 and 10, the next purchase order to be created will be given the number 7 and the second to be created will be given the number 10.

Labels for custom fields on purchase order categories

Fields 1 and 2 accept text entries, field 3 accepts numeric entries. The use of these fields is optional.



Previous: 16.01. General preferences | | Next: 16.03. Invoice preferences

16.07. Synchronisation preferences

  • The preferences described here (accessed through File > Preferences…) apply to all stores on an mSupply server.
  • In a synced system there will be multiple 'sync satellites' and these settings can be different on each sync satellite.
  • There are some settings that are 'per store' - refer Store preferences, and store preferences can be different for each store on an mSupply server.

To view the synchronisation settings choose File > Preferences from the menus and click on the Synchronise tab on the left hand side. This is the window you will see:

When you first arrive at this window, all fields will normally be disabled. If this is a datafile for a correctly configured sync site then all the settings and fields except the Sync time interval field and the Test connection button will be disabled and cannot be edited.

Unlocking the settings for editing

Click on the Click to un-lock button and this window will open:

Enter your unlocking code in the Authorisation code field and click on the OK button. If the code you enter is valid, the various fields and buttons will be unlocked for editing and using, otherwise you will be told that the code is invalid and everything will remain read-only.

The preferences

  • This site: these fields contain the settings for the sync site this datafile belongs to
    • Sync ID: An integer that is greater than 0, the unique ID of this sync site. This is the ID the site is identified with to all other sync sites in the system.
    • Sync time interval: the number of minutes between attempts to synchronise with the primary server. Setting this to 0 pauses sync. Editable without clicking on the Click to unlock button but only if sync is enabled on this site (i.e. if Sync ID is greater than 0).
    • Sync request size: the number of requests to lump together when communicating with the primary server. If the internet connection is stable it is more efficient to have a larger number here. If the connection is less stable then it is better to have a smaller number.
  • Use js node HTTP client checkbox: 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.
  • Check connection button: click on this to check the connection to the primary server. The button is available even if the settings have not been unlocked and will send a test request to the primary server (but only if sync is enabled on this site i.e. if Sync ID is greater than 0). The result of the request will be displayed in a message and will tell you whether this site can reach the primary server.
Synchronise parameters section

This list contains the names of all the sites to synchronise with. If this is the primary server all the satellite servers will be identified in this table. If this is a satellite server then the primary server only will be identified in here.

Sometimes there can be hundreds of sites in this list. To find the one you're interested in, you can click on the column headers to order the list by them (click again to reverse the sort order - same as with most columns throughout mSupply) or enter a site sync ID or user name in the field just above the list to reduce the list to those with an ID or user name starting with what you have entered.

Editing an existing row

Double-click on a row to edit its details. This window will open:

  • Sync ID: The ID of the site in the synchronisation system. You choose this; it MUST be unique to each site to be synchronised. ID 1 is reserved for the primary server (so, if this is the primary server put 1 in here).
  • User name: Communication between the primary and satellite servers is authenticated. This user name and the Password field must match what the primary server is expecting for communication to be successful. So, you can enter any valid username and password in these fields but they must all be the same for the primary and satellite servers.
  • Password: as above.
  • URL: On a remote site, this should be the central server's URL or IP address, including the port if the default is not used. On the central server, if any sites have this field populated it'll disable sync.
  • Hardware ID: This is a unique hardware identifier of the remote machine. The primary server has a copy of this information and, if the value here differs from that on the central server, sync will be diabled for this site. If the remote machine hardware has actually changed (e.g. a new computer) then clearing this value on the primary server will allow the new value to be saved and sync will resume.
  • Generate sync records button: If this is the central server, this button will generate all the sync records to initialise a new data file; if you're on a remote site, it will generate the sync records for stores active on this site (e.g. if you need to refresh the central server copy). After clicking on the button you will see this message: New Data Sync Alert
    • New button: Clicking this will create sync out records for system and transactional data (users, preferences, customer invoices, supplier invoices etc.).
    • Existing button: Clicking this will create sync out records for store data only.
  • Retrieve sync records button: Does a manual pull of sync records waiting for this site on the primary server.
Adding a site

To add a new site to sync with, click on the button to the right of the list. That will open the same window as editing a row but it will be empty, ready for you to enter the appropriate values.

Deleting a site

To delete a site from the list, simply click on it to select it and click on the button to the right of the list.



Previous: 16.06. Entering a new logo | | Next: 16.08. FrontlineSMS

17.23. Exporting assets

This function allows you to export all of the assets in the current store to an Excel spreadsheet file (.xlsx type) that can be imported into mSupply.

Choose File > Export > Assets from the menus. You will be asked to choose the folder on the computer where you want the spreadsheet to be saved, then it will be created and saved there. The spreadsheet will have columns for all the standard mSupply asset fields followed by columns for all the active asset properties.

If there are no assets in the current store, you will be told there is nothing to export and the process will be cancelled.

The format of the spreadsheet created can be used with the asset import feature and is described on that page (17.09. Importing assets).

Previous: 17.22. Exporting sites | | Next: 17.24. Exporting to the dashboard

17.19. Exporting invoices

From the Customer menu the Export invoices command exports any customer invoice to a file. The file created is in a special format that can be imported into another copy of mSupply using the Supplier>Import invoice… menu command. Do not use this command for sending invoices to customers for them to view or print - use a PDF file for that purpose.

When using this command you will be asked to enter an invoice number. The default choice is the last invoice created. The invoice will exported to the export folder you have set in the Preferences, and will be labeled with the invoice number.

Before you can export, you must set your “own code” in Preferences > Misc > 'own code for electronic invoices'. This is the supplier code that your customers will use to identify you when importing the invoice.

Once the invoice is exported, you will be told where to find the file on your hard disk.



Previous: 17.18. Exporting records | | Next: 17.20. Exporting invoices to Moneyworks

17.15. Exporting items, exporting items and stock

Exporting items

Choosing Export items from the File menu allows you to export all of the stock items in your data file to a text file; see the 17.01. Importing items page where the format of the text file is described under 'Field order for the text file'. This allows you to import them to another data file. When you select this option you will see this dialog box:

Click continue to carry on. The standard file dialog window for your operating system will appear, allowing you to select a file name and location to save the text file.

Exporting items and stock

This option, like the previous one, allows you to export all of the stock items in your data file together with the stock on hand; all details are exported, including:

  • Pack size
  • No. of packs
  • Cost price (per pack)
  • Sell price
  • Batch number
  • Expiry date
  • Description (detailed)
  • Department
  • Location

The output is a text file, in a format recognisable by mSupply so that you can later import it to another data file.



Previous: 17.14. Importing tenders | | Next: 17.16. Exporting locations

17.16. Exporting locations

This function allows you to export all of the locations in the current store to a text file that can be imported into mSupply. This is very useful if, for example, you want to create the same set of locations in another store or datafile.

Choose File > Export > Locations from the menus. You will be asked to choose the folder on the computer where you want the text file to be saved, then it will be created and saved there.

If there are no locations in the current store, you will be told there is nothing to export and the process will be cancelled.

The format of the file created can be used with the Location import feature and is described on that page (17.07. Importing locations).

Previous: 17.15. Exporting items, exporting items and stock | | Next: 17.17. Exporting names

17.17. Exporting names

Choosing Export names from the File menu exports all the names (suppliers, patients, manufacturers, donors and customers etc.) in your data file in exactly the same way as for exporting items.

By default, Export Names does not include stores. If you want stores included, be sure to tick the 'Stores' tick-box as well as any other tick-box. If you only want to export the names that are stores, then you only need to tick the 'Stores' tick-box.

The field order of the exported file and the contents of the various fields are exactly the same as for importing names so please see the 17.03. Importing names page for details.



Previous: 17.16. Exporting locations | | Next: 17.18. Exporting records

17.18. Exporting records

Choosing Export on the File menu will display the export window, allowing you to export records from mSupply to a file.

You can search for a set of records by checking the New search check box, which displays the Query editor for you to specify your search criteria, or else use the currently selected records.

If you tick the Open in Excel button mSupply will export any output to your spreadsheet application and will allow you to edit the Headings etc within your spreadshhet. Otherwise mSupply will open a basic editor that will allow you to shape the look of the document.

After you click OK the Query Editor will open allowing you to filter the data you would like to export. Clicking on a field on the left will add it to the filter criteria shown at the top. You then can add from the list of Comparisons and enter your own value in the text field below. To add another line of criteria click the Insert Line button. Likewise to remove a line highlight the line and click the Del Line button.

Once you have chosen your filtering criteria and if you did not click Open in Excel the the Export Editor will open. This is where you can choose what fields to export.

You can add a field by highlighting it in the Fields box and clicking on the down arrow below it or you can remove a field by highlighting it in the preview window at the bottom of the page and clicking the up arrow. If you want to add or remove all fields click the double arrows.

If you want the fields to be ordered ready for item import, unzip the attached .4si file.

items_export_order.4si.zip



Previous: 17.17. Exporting names | | Next: 17.19. Exporting invoices

17.22. Exporting sites

This function allows you to export selected sync sites from a central server so that they can be imported into a fresh, new datafile for use at a remote site.

For details about this function, see the 29.04. Sync Site Export page.

Previous: 17.21. Exporting to MYOB | | Next: 17.23. Exporting assets

17.24. Exporting to the dashboard

Function fixed: mSupply version 5.03.00

This information is for sending data from your mSupply database to the mSupply dashboard database. The dashboard has a separate Postgres database so that its use does not slow down or interfere with your use of mSupply.

To access Dashboard export settings (administrators only), click on the Admin tab of the Navigator and click on the Dashboard icon:

Click on the Export Settings tab and you will see this window:

Postgres server section

In here you enter the details of the dashboard database server:

  • Server: the URL or IP address of the dashboard database server
  • Port: the port on the server that the database is listening for connections
  • User: The user name that mSupply will use to access the Postgres database
  • Password: The password mSupply will use to access the Postgres database
  • Database Name: The name of the database that mSupply is to access

To make sure the details are correct and your copy of mSupply has access to the dashboard database, click on the Test connection button. A message will tell you whether the connection is successful or not.

Once the dashboard is enabled and the correct Postgres settings entered, there will be an automatic (scheduled) export every 24 hours. The next scheduled export is shown in the Next scheduled export field. This export process can be edited to run at different intervals based on your needs.

Export settings section

This section enables you to manually export data to the dashboard apart from the scheduled dashboard export.

The time and date of the next scheduled export to the dashboard database are shown in the Next scheduled export field. By default, all table data is exported incrementally — that is, only records that are new or have been changed since the last export are exported, which saves a substantial amount of time in the export process.

Redirect URL field: contains the URL that you should be redirected to after login or logout of the dashboard. The URL must not contain the https:// part. When the dashboard is on the same server as the mSupply server this will be the same as the URL in the URL field, if they are on different servers then it will be different.

URL field: contains the URL of the dashboard, including the https:// and port e.g. https://localhost:8080.

The Run Next Scheduled Export Now button gives you a way of exporting the data immediately, without waiting for the next scheduled export. Useful if you want the dashboard to be updated immediately.

The Full export of Checked Tables button gives you a way of re-exporting the specific table data from scratch immediately. The table contains a list of all the database tables in mSupply that can be exported to the dashboard. Simply check the checkbox in the Export column to set that table to be exported to the dashboard when you click on The Full export of Checked Tables button. The All/None checkbox is a quick way of toggling between all tables selected and non-tables selected.

It is not advisable to run a full export of the database (i.e. including all database tables) unless really necessary. This is because it can take a loing time if the database is large and, during that time, some tables will be inaccessible so reports and other functions might not work in mSupply.

If you do run a full export (i.e. including all database tables) then you must enter your name and give a reason for the export in the Add your name and reason for running the full export! text field. This text will be added to the log.

When you click on either of them you must enter your authorisation code before the export will be carried out.

Click on the OK button to save your changes and the Cancel button to cancel any changes you have made.



Previous: 17.23. Exporting assets | | Next: 18. Tenders

17.21. Exporting to MYOB

Function added: mSupply version 3.05

If you use MYOB for your accounting then you may well want to export invoices from mSupply into MYOB. If that's the case then this is the page that will tell you how to do it.

Setting up MYOB/mSupply

  • set up mSupply to use the same account codes as MYOB (See Item units and item accounts). If necessary, the accounts associated with any item can be edited via the Misc tab after selecting an item (See Item basics)
  • set up MYOB to use the same suppliers and customers as mSupply (See Names: Using, adding and editing) - the suppliers and customers in mSupply need to be added to the Card List in MYOB, where the Charge to field in mSupply corresponds to the Card ID field in MYOB.

Exporting from mSupply

This can be done from two places:

  • from Files>Export invoices for MYOB
    • You can choose a range of dates, either from the drop-down list (e.g. last year) or by typing the date values directly
    • You can choose either supplier or customer invoices
    • If the show all item lines box is checked, then you will get a line for each item line in the transaction, otherwise you will just get a line for each different account code used in the transaction
    • If transaction categories have been setup, you can also select only transactions from a single category, or where the category name matches
    • Clicking OK will prompt you to create a tab-delimited text file in the folder of your choice.
  • from the transaction list: See Viewing invoices
    • Select the transactions you wish to export, and click the Export to MYOB button. This will create a text file in the same way as before.

Importing to MYOB

  • Select File>Import Data>Purchases>Service Purchases for supplier invoices (or File>Import Data>Sales>Service Sales for customer invoices)
  • In the Import File window, make sure that the settings are Tab-delimited, Data Record, Reject Them, and Card ID respectively
  • Select Continue and browse to your exported file
  • Double-click on the text file, and select the Match All button, and then Import
  • MYOB will then attempt to import the records. If it reports that no records have been skipped, then all is well, otherwise you need to view the MYOBPLOG.txt file (which will be in the same folder as the .MYO accounts file that you are logged into).

Understanding the MYOBPLOG.txt file

  • MYOB inserts an error (negative number) or warning code (positive number) at the start of each line, and adds an explanation of the codes at the bottom of the file
  • You can most likely ignore warning messages
  • The most likely errors will be because the supplier/customer code doesn't exist in MYOB, or there is a duplicate invoice number (i.e. the record has already been imported)
    • If the error is because of a missing supplier/customer, then you can see the mSupply code at the end of each record line
    • Search for that name code in mSupply and create the corresponding Card record in MYOB
    • Then you can try to re-import the same file (and this time, it will reject all of the records that it managed to import first-time around).

Notes

  • mSupply will only export finalised customer or supplier invoices, and it will ignore stock transfers and inventory adjustments → sometimes it may not export as many records as you might think.
  • mSupply doesn't export the customer/supplier name, otherwise MYOB will reject the invoice even if the customer/supplier code matches.
  • mSupply will attempt to export as much reference information as possible into the Journal Memo field in MYOB - this will include the Tender reference, Purchase order reference, and the Invoice reference.
  • mSupply will include the quantity of each invoice line inside brackets, appended to the item name e.g. 'Amoxycillin (200)'
    • MYOB doesn't have a field for unit price, but you can work out the unit price by dividing the total price by the quantity.
  • MYOB expects every line to have a unique invoice number → the item line number has been appended to the invoice number when exporting i.e. each line will have an invoice number like 812-1, 812-2 etc.
    • The invoice number shown in MYOB will reflect the total number of lines in the invoice
    • The same applies to purchase order numbers
    • If a blank purchase order number is exported from mSupply, then MYOB assigns the next one in it's internal sequence.
  • MYOB will not allow you to import invoices with dates outside of the current financial year → make sure that you export everything you need to from mSupply before the new year starts.
  • The export format that mSupply uses is based on the current version of MYOB (version 12). If MYOB is upgraded, there is a good chance that the format will change → importing to MYOB will no longer work until mSupply is updated to output the new format.



Previous: 17.20. Exporting invoices to Moneyworks | | Next: 17.23. Exporting assets

17.09. Importing assets

Assets are imported directly from Excel spredsheets so there is no need to export data from the spreadsheet to a tab delimited text file first (as you need to do for other imports).

Import spreadsheet format

The first row of the spreadsheet is for the column headers and is not imported.

The first 34 columns (up to, and including column AH, “Notes”) represent standard asset fields in mSupply and the column headers for these are completely ignored in the import. Any columns after that are for asset properties and their headers are important; those headers must be in this format:

<HTML>

Property name (Property type)

</HTML>

where Property name is the description the property will be given and Property type is one of “Text”, “Date” or “Drop down list”.

For example, a column header of Project name (Drop down list) will represent a drop down list property with the description Project name.

During the import process, if any properties or entities (like asset locations) do not exist, they will be created. If any options for drop down list properties or standard asset drop down lists (categories) are found not to exist, they will also be created.

The import spreadsheet must contain these columns in this order (Description and Current status are mandatory, the others are all optional):

Column number Column letter Field Description
1 A Code 255 alphanumeric characters. A code that the asset can be recognised by
2 B Description Mandatory. 255 alphanumeric characters. The name the asset will have and be recognised by throughout the system
3 C Make 255 alphanumeric characters
4 D Model 255 alphanumeric characters
5 E Serial number 255 alphanumeric characters
6 F Supplier name 255 alphanumeric characters. Name of the company/person who supplied the asset
7 G Purchase order number 255 alphanumeric characters
8 H Purchase order date Valid date in current operating system format. The date the purchase order to buy the asset was confirmed
9 I Acquisition date Valid date in current operating system format
10 J Next maintenance due date Valid date in current operating system format. The date the next maintenance is due to be carried out on the asset
11 K Disposal date Valid date in current operating system format. The date the asset will be or was disposed of
12 L Last verification date Valid date in current operating system format
13 M Location code 20 alphanumeric characters. The code the location name will have. Will be matched against the names currently in the database. If a name with this code does not exist, one will be created with the name provided in the Location name field. If the Location name field is empty the name will be created with the code as its name. This field is mandatory if you want mSupply to create the name.
14 N Location name 255 alphanumeric characters.
15 O Asset user name 255 alphanumeric characters. The name of the asset user in the format “last name,first name”. Will be created if the user does not exist as a contact of the location (the first and last names only are used to determine whether the asset user exists. Phone number and email address are ignored in the check).
16 P Asset user phone number 255 alphanumeric characters
17 Q Asset user email 255 alphanumeric characters
18 R Custodian location 255 alphanumeric characters. Where the custodian of the asset (the main person responsible for it) is located
19 S Custodian name 255 alphanumeric characters. The name of the custodian
20 T Custodian phone number 255 alphanumeric characters
21 U Custodian email 255 alphanumeric characters
22 V Current status Mandatory. 255 alphanumeric characters. Will be created if it doesn't exist
23 W Proposed status 255 alphanumeric characters. The proposed next status of the asset. Will be created if it doesn't exist. Please note that there is no way of telling mSupply what proposed statuses are allowed to follow which current statuses during import. This can only be done manually in the asset settings (see the 21.01. Assets setup page for details). During import all proposed statuses are assumed to be valid and will not be checked. There are, however, some important exceptions:
1. If the current status of an asset is designated to be a final status, any proposed status will be ignored.
2. If an imported asset has a current status which has some possible proposed statuses assigned, if the proposed status is not included in these, it will be added to them.

So, be careful with the proposed statuses in the import file: you could make a mess if you have already set up which statuses can follow which and you don't follow that in the import file.
24 X Type 255 alphanumeric characters. Will be created if it doesn't exist
25 Y Condition 255 alphanumeric characters. Will be created if it doesn't exist
26 Z Purchase price Number, currency. The cost of the asset when it was purchased
27 AA Purchase costs Number, currency. Any costs that are ot be added ot the purchase proce to arrive at the total value of the asset to be depreciated
28 AB In service date Valid date in current operating system format. The date the asset starts to depreciate from
29 AC Useful lifespan (months) Number, integer. The number of months the asset can be used for
30 AD Disposal value Number, currency. The value of the asset at the end of its useful life
31 AE Insurer name 255 alphanumeric characters
32 AF Insurance policy number 255 alphanumeric characters
33 AG Insurance renewal date Valid date in current operating system format. The date the insurance should be renewed by
34 AH Notes Lots of alphanumeric characters! Any other information that needs to be stored against the asset
35 onwards AI onwards User-defined property columns You can add user-defined property columns in any order from column AI onwards. Column header must be in the format “Property name (Type)” where Property name is the name of the property and Type is the type of the property (either Date, Text or Drop down list). If the property does not exist it will be created and if the option of a Drop down list property does not exist it will also be created.

Here is an example spreadsheet you can use (contains no property columns, only the standard mSupply columns): asset_import_blank_template.xlsx

When entering dates in the spreadsheet, make sure they are counted as text in their cells. Sometimes Excel will autoconvert dates to date or numerical format and then they will import into mSupply as blank dates. You can make sure that dates will import correctly by using the row preview functionality (see below) - if the dates look correct here then they will import correctly.

Doing the import

Go to the File > Import > Import assets menu and you will be asked to select the import file from a file window. After you have selected the file (if it is valid) you will be shown this window:

mSupply uses the code field to determine whether the asset being imported is a duplicate; an asset with the same code as one already in the database is determined to be a duplicate. Any assets with no code are ignored during duplicate checking i.e. an asset with no code can never be a duplicate and will always be imported as a new asset. In the If duplicate codes are detected section you tell mSupply what to do if it encounters a duplicate asset during the import:

  • Import as new asset: this option will import the duplicate as a new asset
  • Skip the duplicate without asking: the duplicate will not be imported and that row of the spreadsheet will be ignored
  • Stop the import: as soon as a duplicate is encountered, the import will stop and all assets imported so far will be removed so that nothing is imported.
  • Update the existing asset: the asset that already exists with the code in the database will be updated with the information contained in the spreadsheet row. A new asset will not be created. BE CAREFUL WITH THIS OPTION: if a cell is blank in the spreadsheet then the corresponding value is removed from the asset (if it had a value set for it), not left as it is.

The Field column of the table shows you all the columns that mSupply has detected in your import file, the Value column shows the values it has found in the cells for that row of the spreadsheet. You can move through the rows of the spreadsheet using the Previous and Next buttons. If you try to go beyond the first or last row of the spreadsheet mSupply will let you know.

You can carry out the import by clicking on the Import now button or cancel it by clicking on the Cancel button.

When the import has finished you will be shown a message telling you how many assets were imported and how many rows of the spreadsheet were skipped, ignored or failed.

All the assets created by the import will have the text “Created by import on xx/xx/xxxx” (where xx/xx/xxxx is the date of the import) appended to the end of their Notes field.



Previous: 17.08. Importing supplier invoices | | Next: 17.10. Importing regions

17.08. Importing supplier invoices

From the Supplier menu, the Import invoice command allows you to import an invoice generated by one of your suppliers who also uses mSupply. You will be presented with an open/save window where you should locate the invoice file to be imported.

  • The invoice must have been generated by the “export invoice” command in another copy of mSupply.
  • The item codes in your copy of mSupply must have your supplier codes entered (see below). If mSupply attempts to import a code that it does not know, the import process will stop.
  • Once an invoice has been imported, you are still free to edit it. You should check the invoice against a paper copy when it arrives.
  • After import the file is edited so that if you attempt to import an invoice again you will not be able to. This prevents accidental double-importing of the same invoice.
Entering supplier codes

If you are importing invoices from a supplier, you must perform the following steps:

  1. enter a quotation for each item you receive from the supplier. This is done from the quotes tab of the item details window, or from the quotes tab of the supplier details window.
  2. enter the supplier code for the item in the supplier code field of the quotation. There is no need to enter other details for the quotation if you do not want to.



Previous: 17.07. Importing locations | | Next: 17.09. Importing assets

17.06. Importing customer budgets

You can set up budgets for customers manually if you wish (see here) but if you have to set budgets for many customers at a time then this feature will save you a lot of time. As with the other import features of mSupply, this import uses a tab delimited text file (easily produced by exporting a spreadsheet from Excel or other spreadsheet programme). The columns that must be present in the file and their contents are as follows:

Column number Column letter Field Description
1 A budget description The description for the budget, as it will appear in the list of budgets for a customer.
2 B customer code The customer's code as entered in mSupply. If this code does not match a customer in mSupply an error will be generated.
3 C customer name For your reference only. This column is ignored during the import and can be left empty, but it must be present.
4 D budget period start date The start date for the period to which the budget belongs in the format dd/mm/yyyy or mm/dd/yyyy (whichever your copy of mSupply is using).
5 E budget period end date The end date for the period to which the budget belongs in the format dd/mm/yyyy or mm/dd/yyyy (whichever your copy of mSupply is using). The budget period start and end dates must match an existing budget period period in mSupply (set up using Budgets), otherwise an error will be generated.
6 F budget amount The amount of the budget. Must be a positive number with or without a decimal point.
7 G additional budget Whether the budget amount is to be considered an additional budget. A “T” or “Y” is interpreted as true, anything else is interpreted as false.
8 H effective budget date The effective date for an additional budget in the format dd/mm/yyyy or mm/dd/yyyy (whichever your copy of mSupply is using). Ignored if the budget is not additional. If this field is left blank and the budget is additional then the current date is used.

When you have created the import text file go to File > Import > Import customer budgets and select your text file. You will be show the following window:

Now choose the import settings to match your file:

  • First line contains column headers: check this if the first row in your text file contains the column descriptions. If checked, mSupply will ignore the first line of the file.
  • Remove quote characters on import: check this if fields in your file is surrounded by quote (“ or ') characters. If checked, mSupply will attempt to remove them from each field.

And select how duplicates are to be handled (a duplicate is a row which matches another line in the file or a budget already in mSupply):

  • Skip the duplicate without asking: The duplicate record is ignored completely
  • Stop the import: mSupply will stop importing from the file if it detects a duplicate. Any budgets already imported will be kept but no further lines in the file will be processed.
  • Update customer budget: The budget already in mSupply will be updated with the new details found in the file and the import will continue.

You can also click the Next and Previous buttons to see a preview of what mSupply will import on each row from your file. This can be useful for showing differences in the contents of your file and what mSupply is expecting.

When you're ready to carry out the import, click on the OK button. mSupply will carry out the import and tell you how many lines were imported, how many budgets already in mSupply were modified and if there were any errors. You can see more details by viewing the log (see The log).



Previous: 17.05. Importing abbreviations | | Next: 17.07. Importing locations

17.01. Importing items

You can import a tab-delimited text file of items by choosing File > Import > Import items….

  • This command only imports (creates) items. You will need to do this when you are configuring mSupply for the first time, or when you are wanting to create a number of new items to your system or amend a number of existing items.
  • This process does not introduce stock. If you would like to import stock, see the 17.02. Importing stock page.

You can download the mSupply Item Import template as a starting point for creating your item list. Reading through this document before proceeding with the import process is highly recommended.

During import you can specify a number of things including:

  • What happens with duplicates
  • Which master lists the new items will be added to.
  • Which stores the new items will be visible in (if master lists aren't controlling visibility)

After selecting the menu item you are shown a message asking you to select the file to be imported on the next window:

After clicking OK, a window opens allowing you to select the file to import. After selecting it (by double clicking on the file in the window or clicking on it and clicking on the Open button) this window is displayed:

First line contains column headers: If you have used the first line of your import file for column headers, check this box. Then mSupply will ignore the first row in the file, and start importing items from the second row.

Remove quote characters on import: If this is checked then double quote characters (") are removed from item names as they are imported. This is useful if you have exported the import file from spreadsheet software and it has placed double quote characters around the text.

If you have used double quote characters in item names (e.g. as a symbol for inches) then they will also be removed if this option is checked.

Handling duplicate items: During the import process, mSupply compares the item code in the import file (1st column - see below) against the codes of items already in its database to determine whether an entry is a duplicate item or not. If a duplicate item is found in the import file mSupply will handle it according to your radio button selection in the If duplicate codes are selected section:

  • Create new duplicate items and continue and Ask each time options are disabled for Item Import.

As of v5 it should not be possible to create an item with the same code as another item. Hence, item with duplicate Item code will be ignored.

  • Skip the duplicate without asking: the duplicate is ignored and not imported.
  • Stop the import: if a duplicate is detected mSupply will stop and cancel the whole import i.e. the database will be exactly that same as it was before you started the import.
  • Update the existing item: the item with the same code already in mSupply will be updated with all the details of the item in the import file.
Preview tab

This tab enables you to see a preview of what will be imported into mSupply and helps you check that mSupply is reading what you expect from the import file.

The left hand column of the table (“Field”) shows you all the fields mSupply is expecting to see (in that order, first at the top, last at the bottom of the table). The right hand column (“Value”) shows you the value that mSupply has read from the file for that field. Use the Next and Previous buttons to move between the records in the import file.

Stores tab

If the preference Automatically update item visibility in all stores to match master lists used by that store (see Preferences > Item) is checked, then item visibility is controlled by master lists and you do not have the option of selecting stores in which the item is visible. The table on this tab will be replaced with this message telling you to use the Master lists tab instead:

Item visibility in each store will be turned on in accordance with the master lists you have selected, but visibility won't be turned off in stores in which the item is already visible but not associated with the selected master lists. This prevents inadvertently removing existing items from stores when your intention is to import items to specific master lists.

  • This is the tab you use to specify which stores the items you import will be visible in.
  • The store you are logged into is ticked by default. Simply check the “Visibility” column checkbox for the stores you wish all imported items to be visible in.

Only imported item visibility is affected during the import. If a duplicate item is found in the import file then:

  • If you choose to ignore duplicates, then the visibility of the item already in mSupply is not affected by the import process.
  • If you chose to update duplicates, then the visibility of the item already in mSupply will be updated to match what you have set on this tab.
Master lists tab

This is the tab you use to determine which master lists the items in the import file will be added to as they are imported. Simply check the “Add to list” column checkbox for the master lists you wish all the items in the import file to be added to.

Any master lists that have the “Automatically add new items to this master list” option checked will have their “Add to list” checkbox checked by default on this tab and you will not be able to uncheck them.

Note that only imported items will be added to the master lists selected. This means that items already in mSupply which match duplicates in the import file that you choose to ignore will not be added to the selected master lists. Similarly, items already in mSupply which are updated because they match duplicates in the import file and the “Update the existing item” option was chosen are added to the selected master lists. And don't worry, if an item is already on a msster list it won't be added again.

Import file format

Field order for the text file:

Column number Column letter Field Description
1 A item code 18 alphanumeric characters (must be a unique value)
2 B item name 80 alphanumeric characters
3 C units 3 alphanumeric characters recommended (ea, ml or mg). Entries in the units list will be created
if you import a unit that does not already exist in the data file.
60 characters supported
4 D reference pack size integer
The above fields are mandatory, while the following fields are optional and may or may not be included
as per your requirements
5 E Default shelf location code 60 alphanumeric characters. The code of the shelf location that stock of this item is normally placed in. Will be offered by default when stock of the item is received on a goods received note or supplier invoice.
6 F user field 1 30 alphanumeric characters
7 G user field 2 30 alphanumeric characters
8 H user field 3 30 alphanumeric characters
9 I user field 4 “true” or “false”
10 J edl “true” or “false”
11 K ATC category 30 alphanumeric characters
12 L ddd value 8 alphanumeric characters- the ddd and its units
13 M ddd factor number greater than zero (default=1)
14 N item description The long description for the item. Do not include carriage returns
(new lines made with the return or enter key) in your text file.
15 O item department The name of the department that the item belongs to.
If the department does not exist, mSupply will create it.
16 P account code for stock The account code used for stock purchases .
Note that these accounts will be created if they don't exist.
17 Q account code for cost of goods sold
18 R income account code
19 S Default sell price
20 T Category Category 1. This category is hierarchical and has 3 levels. You can enter different levels separated by :: (for example “Pharmaceuticals::Controlled::Anti-depressants” or “Controlled::Anti-depressants”) or just the lowest level with no separator (for example “Anti-depressants”). mSupply will look for an existing category with the levels you define, if it doesn't find one then it will create it and assign the category to the name. If you enter only the lowest level category (for example “Anti-depressants”), mSupply will look for any lowest level category “Anti-depressants” with any or no parent. If it finds one, it will assign the first one it finds to the name being imported, otherwise it will create it with no parent and assign it to the name.
We strongly recommend you use the WHO EDL categories for this field
21 U Category 2 60 alphanumeric characters
22 V Category 3 60 alphanumeric characters
23 W VEN category The WHO VEN category of the item. One character only, must be V, E or N, will be ignored of it is neither of these.
23 X Weight The weight per default pack size (column D) in kg
24 Y Critical stock “true” or “false”
25 Z Normal stock “true” or “false”
26 AA User field 5 number
27 AB User field 6 30 alphanumeric characters
28 AC User field 7 “true” or “false”
29 AD Default volume per pack The volume of a single pack of the default pack size in m3. This volume is filled in by default when receiving stock but can simply be overridden.
30 AE Default outer pack size The number of default packs that fit in a carton. Filled in by default when receiving goods but can be simply overridden.
31 AF Default outer pack volume The volume of an outer pack in m3, filled in by default when receiving goods but can be simply overridden.
32+ AG+ Item custom fields After column AF (31), any custom item fields set up in the preferences (see the 16.11. Custom fields section for details) can be added. The column header must be exactly the name of the custom field (case insensitive). The values entered in these columns will be saved to the item's appropriate custom field.

All these are in this handy template: mSupply Item Import template

The chances are that you already have a set of codes that you use internally. In this case open up Excel or a similar spreadsheet program, fill in the item description in the order shown above. For a quick solution, you only need to fill in the first four columns, the rest can be ignored.

The third column representing “Units”, can be left blank, however, it is better to fill this in. The fourth column “reference pack size” can be set to “1” for all rows unless you know what pack size you want to use as the “standard” (Don't worry about this. The reference pack is used for comparing quotations. You can receive and issue any pack size you like).

Save a spreadsheet file as shown above as a tab-delimited text file, and then import it as described at the top of this page.

If the file you are importing has non-English characters (for example, accents), it is important to make sure the file is saved with a UTF-8 charset. You can check this by opening the file in Notepad (for Windows). When you save the file, you can choose the Charset used, as shown in image below.

If there are non-printable characters before or after the item name and code they will be removed. Any non-printable characters in the name or code will be replaced with an underscore (_).

Import new item codes

If you need to change the item codes for a selection of items, it is a technically challenging process that is easy to get wrong if done manually, especially if you intend to re-use existing codes (not recommended!). Custom code has been developed to do this in bulk. Please contact Sustainable Solutions on support@msupply.foundation to discuss this. Include a link to this heading Import new item codes :-).

The relevant details are:



Previous: 17. Data Import and Export | | Next: 17.02. Importing stock

17.07. Importing locations

Locations are the labelled places in your warehouse where you store stock. Locations can be created individually (see here) or can be created automatically when you import stock (see here). The functionality to import locations described here will save you a lot of time if you need to put a lot of locations into mSupply separately from importing stock.

This import uses a tab delimited text file (easily produced by exporting a spreadsheet from Excel or other spreadsheet programme). The columns that must be present in the file and their contents are as follows:

All columns must be present in the import file but only the first 2 (Location code and Store code or name) are mandatory. If either of these fields do not have values entered then the location will be ignored.

The import must take place when the user is logged in to the store on the site where the store is Active

Column number Column letter Field Description
1 A Location code The code of the location. This is used to identify and select the location throughout mSupply and is the label you apply to the location in your warehouse e.g. “A01” or “A01.03.C”.
2 B Store code or name The code or name of the store the location is to be created in. You can see the list of store names and their codes currently in your copy of mSupply by going to Special > Show stores…
3 C Location description For your reference only, a longer description of the location e.g. “Aisle A, shelf 1, position C”.
4 D Volume The total storage volume of the location in m3 (cubic metres).
5 E Priority A whole number from 0 upwards. This is used when printing a picking slip. Setting a priority for a location will override the default alphabetical ordering of shelf locations in a picking list. A location with a lower priority number will be printed before a location with a higher priority number. All locations with 0 priority are counted as having no priority and will be printed, in alphabetical order, after all locations with a priority.
6 F Is summary location Whether the location is a summary location that cannot hold stock. y, yes, t or true is interpreted as true, anything else (including nothing) is interpreted as false.
7 G Location type The name of the location type for this location (must be an exact match and the location type must already exist in mSupply, otherwise the location will be created with no location type).
8 H Parent location code or description The code or description of the location which is a parent to this one. If the parent does not already exist in mSupply the location will be imported without the parent. Please make sure that the parent location are imported first.

An empty Excel spreadsheet containing these columns for you to use as a template is here: location_import_template.xlsx

When you have created the import text file go to File > Import > Import locations and select your text file. You will be show the following window:

Now choose the import settings to match your file:

  • First line contains column headers: check this if the first row in your text file contains the column descriptions. If checked, mSupply will ignore the first line of the file.
  • Remove quote characters on import: check this if fields in your file is surrounded by quote (“ or ') characters. If checked, mSupply will attempt to remove them from each field.

And select how duplicates are to be handled (a duplicate is a row which matches another line in the file or a budget already in mSupply):

  • Import and continue: The duplicate record is created and import continues normally
  • Ask each time: You will be asked what you want to do with a duplicate each time one is detected; ignore it, create it or stop the import
  • Skip the duplicate without asking: The duplicate record is ignored completely
  • Stop the import: mSupply will stop importing from the file if it detects a duplicate. Any locations already imported will be kept but no further lines in the file will be processed.

When you're ready to carry out the import, click on the OK button. mSupply will carry out the import and tell you how many locations were imported, how many already in mSupply were modified and if there were any errors. You can see more details by viewing the log (see The log).

If there are non-printable characters before or after the location description or code they will be removed. Any non-printable characters in the description or code will be replaced with an underscore (_).



Previous: 17.06. Importing customer budgets | | Next: 17.08. Importing supplier invoices

17.03. Importing names

In mSupply, Names are customers, suppliers, manufacturers, patients, donors and benchmark suppliers.

Introduction
  • Importing a large number of names can really bog down the server. How much depends on many factors, but a realistic minimum is an hour per 10,000 names. This will increase dramatically with the number of names and sync sites that are visible to the names…
  • We recommend that you do it when other users are not trying to do anything with mSupply!

The File > Import > Import customers & suppliers… menu item allows you to import all name types into an mSupply data file. You can import any name type in any store.

  • If you are in a multi store system, do the names need to be visible in all stores? If not, consider setting the Names created in other stores not visible in this store or Patients created in other stores not visible in this store preferences in other stores. See the Store preferences section for details.
  • If the relevant preference is turned on, all new names will be visible in the store you are logged into only. If it is turned off, then all new names will be visible in all stores.
Setting up the import file

A Tab-delimited file (see notes below) must be set up to import the data. The required field order is:

Column Field
A Code. Mandatory
B Name. Mandatory
C Type - see below for more details. Mandatory
D Address 1
E Address 2
F Country
G Email
H Phone
I Category 1. This category is hierarchical and has 3 levels. You can enter different levels separated by :: (for example “State1::District2::Area1” or “District1::Area3”) or just the lowest level with no separator (for example “Area2”). mSupply will look for an existing category with the levels you define, if it doesn't find one then it will create them and assign the category to the name. If you enter only the lowest level category (for example “Area1”), mSupply will look for any lowest level category “Area1” with any or no parent. If it finds one, it will assign the first one it finds to the name being imported, otherwise it will create it with no parent and assign it to the name
J Customer group. If the group name does not exist, it will be created by mSupply on the fly.
K Last name. This column is the difference between a customer and a patient: A customer will have a blank last name, a patient must have a non-blank last name
L First name (applies only to people)
M Date of birth (use 4-digit years)
N Gender (enter “F” or “True” for females. All other values taken as male)
O Custom 1
P Custom 2
Q Custom 3
R Category 2
S Category 3
T Address 3
U Address 4
V Address 5
W Postcode (Zip code)
X On hold (“T” or “Y” for true, anything else, including blank, for false)
Y Latitude (positive or negative decimal number)
Z Longitude (positive or negative decimal number)
AA ID. The ID of the name record in the mSupply database. Optional and ignored unless updating a name. If you're updating a name then it is mandatory. During an update, the name this ID belongs to is compared with the name the code in column A belongs to. If they are the same record then the update will proceed, otherwise this line in the import file will be skipped.
AA+ After column AA, any custom name fields set up in the preferences (see the 16.11. Custom fields section for details) can be added. The column header must be exactly the name of the custom field (case insensitive). The values entered in these columns will be saved to the name's appropriate custom field.

Column C describes the type of the name being imported. That is, whether it is a customer, supplier, manufacturer, donor or patient. A name could be any one of these or several of them. To indicate which of these the name is, simply include the letter shown in the table below in the type field (letter order is not important):

Value Meaning
C Customer or Patient. To be recognised as a patient, the line in the import file must have a non-blank last name
P Patient
S Supplier
M Manufacturer
D Donor
B Benchmark supplier (for use in tenders)
(blank) Both a customer and a supplier

So, for example, a name which is a donor and supplier would have DS or SD in the type field.

You might find this template useful: name_import_template.xlsx or this export settings file: names_export_order.4si.zip

The first 3 fields (Code, Name and Type) are mandatory for each name imported. If a row in the import file does not have values for these 3 fields then it will be skipped and ignored during the import process.

  • The customer or supplier category1, 2 and 3 fields will be created if they don't already exist. If the name is a customer and a supplier, a customer category will be created.
  • You must always include every column in every import file. For all names except patients, the first 3 columns are mandatory. You can leave the other columns blank and mSupply will only import the information you have provided. See below for more on importing patients.
  • When you import the file you can choose whether or not to:
    • Ignore the first line. You will want to if you have used the first row for column headings
    • Strip out line feeds and quote characters. You will want to do if you've used Excel to save the text file.
  • If there are non-printable characters before or after the name, code, last name or first name they will be removed. Any non-printable characters in the name, code, last name or first name will be replaced with an underscore (_) - but note that spaces in the code will not be affected.
  • Save the template as tab-delimited text (rows end with a carriage return, line feed and columns are separated with a tab character) before importing into mSupply.
  • MS Excel tends to add extra characters (line feeds and quotes), but mSupply will gracefully remove these without complaining providing you select that option -see info box above.
  • Avoid having the Code field containing a space character as this can cause problems during import
  • If the file you are importing has non-English characters (for example, accents), it is important to make sure the file is saved with a UTF-8 charset. You can check this by opening the file in Notepad (for Windows). When you save the file, you can choose the Charset used, as shown in image below.

If you import patients into a store which is not a dispensary, they will be imported but they will be invisible everywhere. You must make them visible in the appropriate dispensary stores before they can be used.

Importing the file

When you choose File > Import > Import customers & suppliers… you'll be shown an open/save window where you choose the file to import.

Once you've done that, you'll be shown this window:

If the first line of your import file contains column headers then check the First line contains headers checkbox. This tells mSupply to ignore the first line and start importing form the second line.

Check the Remove quote characters on import checkbox if some of the fields in the import file have had quote marks added to them. This can often happen if you have created the import file by exporting it from Excel or some other spreadsheet application.

Now, in the If duplicate codes are selected section, select what you want to happen if a name code is found in the import file which is already used by a name in mSupply.

You can use the Previous and Next buttons to go through the import file one line at a time to see what mSupply can see in each field and therefore what it will try to import. Can be useful for checking whether extra quote characters have been added to any fields or if the first line of the text file contains column header information only.

Importing patients

If you are importing patient names, leave column B (the full name) blank and make entries in the Last name (col K) and First name (col L) columns. Below is an example of a spreadsheet for importing patients, customers and suppliers which demonstrates how to fill in the fields with respect to each import type.

Column K is what defines the difference between a customer and a patient: A customer will have a blank last name, a patient must have a non-blank last name. A customer can have a blank first name.

If you have a lot of patients there will be a short delay once you have chosen the import file while mSupply counts how many records there are to import, then a progress window will be shown displaying the rate of progress:

Update Name codes in bulk

If you need to change many Name Codes at once, custom code has been developed for this purpose. It is a technically challenging process that is easy to get wrong. Please contact the mSupply Foundation on <support@@msupply.foundation> to discuss this. Include a link to this heading Update Name code in bulk :-).

The relevant details are:



Previous: 17.02. Importing stock | | Next: 17.04. Importing prescribers

17.10. Importing regions

Regions are geographic boundaries, currently used in mSupply to help in displaying data on maps. At the moment they are only used in certain customisations but more use of them will follow as development progresses.

Import spreadsheet format

The first row of the spreadsheet is for the column headers and is not imported.

There must be 3 columns in the spreadsheet in the order shown in the following table:

Column number Column letter Field Description
1 A Region name Mandatory. 255 alphanumeric characters. The name of the region
2 B Geometry Optional. Lots of alphanumeric characters. The JSON geometry definition of the region. If it is entered then it must be valid according to the geoJSON FeatureCollection schema.
3 C Parent Optional. 255 alphanumeric characters. The name of this region's parent region.

Here is an example spreadsheet you can use: region_import_blank_template.xlsx

Doing the import

Choose File > Import > Import regions from the menus and you will be asked to select the import file from a file window. After you have selected the file (if it is valid) you will be shown this window:

mSupply uses the Region field to determine whether the region being imported is a duplicate; a region with the name as one already in the database is determined to be a duplicate. In the If a duplicate is detected section you tell mSupply what to do if it encounters a duplicate region during the import:

  • Import as a new region: this option will import the duplicate as a new region
  • Skip the duplicate without asking: the duplicate will not be imported and that row of the spreadsheet will be ignored
  • Stop the import: as soon as a duplicate is encountered, the import will stop and all regions imported so far will be removed so that nothing is imported.
  • Update existing region: the region that already exists with the name in the database will be updated with the information contained in the spreadsheet row. A new region will not be created.

The Value column shows the values mSupply has found in the cells for that row of the spreadsheet. You can move through the rows of the spreadsheet using the Previous and Next buttons. If you try to go beyond the first or last row of the spreadsheet mSupply will let you know.

You can carry out the import by clicking on the Import now button or cancel it by clicking on the Cancel button.

During the import:

  • if the row has no region name it will be skipped
  • if the row has an empty Geometry field, it will be imported with no geometry
  • if the row has content in the Geometry field that does not match the geoJSON FeatureCollection schema it will be skipped
  • if the parent region does not exist or is empty the region will be imported with no parent

When the import has finished you will be shown a message telling you how many assets were imported and how many rows of the spreadsheet were skipped.



Previous: 17.09. Importing assets | | Next: 17.11. Importing requisitions

17.11. Importing requisitions

This is a way to import standard customer requisitions (response). Requisitions created by this import are not connected to any internal order. You cannot import internal orders (request requisitions), customer stock history requisitions or imprest requisitions.

Import spreadsheet format

The first row of the spreadsheet is for the column headers and is not imported.

There must be 6 columns in the spreadsheet, in the order detailed in the table below. They must all be present but some of the columns (the optional ones) are for your reference only and can be empty (the whole column is ignored during the import so it doesn't matter whether some or all the cells of the column are empty):

Column number Column letter Field Description
1 A Customer code Mandatory. 20 alphanumeric characters. The code of the customer the requisition is for. When the value in this column changes, mSupply will begin a new requisition.
2 B Customer name Optional. The name of the customer the requisition is for.
3 C Item code Mandatory. 18 alphanumeric characters. The code of the item that the customer is requesting stock of.
4 D Item name Optional. 255 alphanumeric characters. The name of the item that the customer is requesting stock of.
5 E Customer current stock on hand Optional. Integer. The number of units of the item (not packs) the customer currently has in stock. If there is no value in this column, it is assumed to be 0.
6 F Quantity requested Mandatory. Integer. The number of units (not packs) of the item that the customer is requesting.

Rows belonging to the same requisition must all be grouped together in the spreadsheet; mSupply will interpret a change in customer code to mean that this row is for a new requisition.

Here is an example spreadsheet you can use (contains no property columns, only the standard mSupply columns): requisition_import_blank_template.xlsx

Doing the import

Choose File > Import > Import requisitions from the menus and you will be asked to select the import file from a file window. After you have selected the file (if it is valid) you will be shown this window:

The Value column shows the values mSupply has found in the cells for that row of the spreadsheet. You can move through the rows of the spreadsheet using the Previous and Next buttons. If you try to go beyond the first or last row of the spreadsheet mSupply will let you know.

You can carry out the import by clicking on the Import now button or cancel it by clicking on the Cancel button.

When the import has finished you will be shown a message telling you how many requisitions were imported. If there is an error (a customer code or item code doesn't exist or a mandatory column value is not present) you will be told what the error is and the import will be cancelled (nothing will be imported). In this case, correct the error in the spreradsheet and try the import again.



Previous: 17.10. Importing regions | | Next: 17.15. Exporting items, exporting items and stock

17.13. Importing stores

We strongly recommend:

* You take a backup of your datafile before attempting any imports.
* You test any import on a copy of your data before you do it on the real data.

Don't say you haven't been warned ;-)

The Import stores function allows you to import stores into your datafile. If the store does not exist already it will be created, if it does already exist it will be updated with the contents of the import file.

This function is currently not available to general users and is not available from the standard user interface. You can create the import spreadsheet of course, but the actual import will need to be done by The mSupply Foundation staff.

Import file format
  • The import file must be an “.xlsx” (Excel) type file.
  • The first row must contain the column headers shown in the Column heading column in the table below.
  • The store code is used to check whether a store exists already. If it does not exist in the datafile it will be created with the values in that row of the spreadsheet. If a store with the store code does exist in the datafile already, its values will be updated with the values contained in that row of the spreadsheet (blank cells will be ignored so values will not be updated with empty cells).
  • The currently logged in user (the one doing the import) is given login permission to the store.
  • The table below details the fields you should have in each row of the file.
Column Column heading Description
1 (A) store_name Mandatory, Text. The name of the store .
2 (B) code Mandatory, Text. The code of the store.
3 (C) store_mode Optional, Text, one of “store” or “dispensary”. The mode of the store.
4 (D) site_code Optional, Integer. The synchronisation site the store belongs to. Leave empty if this is not part of a synchronisation setup. Will be set to 1 by default if not provided.
5 (E) organisation_name Optional, Text. The name of the organisation this store belongs to. No functional value but can be included in reports etc.
6 (F) address_1 Optional, Text. The number of packs (containing the number of units in column 4) in this stock line. Equal to the total quantity if the Pack size is 1.
7 (G) address_2 Optional, Text. The first line of this store's address.
8 (H) address_3 Optional, Text. The first line of this store's address.
9 (I) address_4 Optional, Text. The first line of this store's address.
10 (J) address_5 Optional, Text. The first line of this store's address.
11 (K) postal_zip_code Optional. Text. The store's postal or ZIP code.
12 (L) phone Optional, Text. The phone number of the store in no particular format.
13 (M) tags Optional, Text. The tags belonging to the store. Separate individual tags with a space.
14 (N) copyStorePrefFromStoreCode Optional, Text. The code of the store to copy store preferences, custom data, master list associations and user permissions from (for the user in column 19 (S)). If none is provided the store is given a default set of preferences, empty custom data, no master list associations and no user permissions.
15 (O) Type Optional, Text. .
16 (P) Create Date Optional, .
17 (Q) Server Optional, Not used.
18 (R) Version Optional, Not used.
19 (S) User Optional, Text. The name of the user to copy permission from to give to the currently loggfed in user for this store.

Here is a blank spreadsheet you can use with the right columns: importstores.xlsx



Previous: 17.12. Importing supplier quotes into Tenders | | Next: 17.14. Importing tenders

17.12. Importing supplier quotes into Tenders

See the 18.04. Adding supplier responses to a tender page for details.



Previous: 17.11. Importing requisitions | | Next: 17.13. Importing stores

17.14. Importing tenders

This function allows you to import a tender into the store you are currently logged into. To access it, choose Supplier > Import tender from the menus. A window will open for you to select the import file (details given below). Browse to the file and double-click on it or click on it to select it then click on the Open button to carry out the import.

mSupply will then read the import file and create a suggested status (sg) tender with a default, system-generated description (which you should change later) and add the lines in the spreadsheet to the tender. The tender will then be automatically opened for you to continue editing.

Import file format
  • The import file must be an “.xlsx” (Excel) type file.
  • The first row must contain the column headers shown in the Column heading column in the table below.
  • The table below details the fields you must have in each row of the file:
Column Column heading Description
1 (A) Item code Mandatory, Text. The code of the item this tender line is for.
2 (B) Item name Optional, Text. The name of the item. Ignored during import but useful for you when reading the file.
3 (C) Unit/Pack Optional, Text. The unit of the item. Ignored during import but useful for you when reading the file.
4 (D) Pack size Mandatory, Integer. The number of units in a pack.
5 (E) Total quantity Mandatory, Integer. The total number of units for this tender line.

Here is a blank spreadsheet you can download with the right columns: tenderimporttemplate.xlsx



Previous: 17.13. Importing stores | | Next: 17.15. Exporting items, exporting items and stock

17.05. Importing abbreviations

Importing abbreviations is a great way of quickly entering a large number of abbreviations for use in dispensary mode (see the Abbreviations section for details).

To create the import file, create a spreadsheet with two columns like this:

Enter the short abbreviation you will type in the Abbreviation column. Enter the text this will be expanded to in the Expanded text column. Make a new row for each abbreviation.

Note: your abbreviations cannot contain the underscore (_), period (.) or comma (,) characters.

If there are any non-printable characters or spaces in the abbreviations they will be removed on import.

When the spreadsheet is complete, export it as a tab delimited text file.

Close the spreadsheet application then choose File > Import > Import abbreviations… from the menus in mSupply. Select the file you just created in the window that opens (navigate to it and either double-click it or single-click on it and click on the Open button). The following import options window will be displayed:

If the first row in your spreadsheet contained the column headers and not an abbreviation, check the First line contains column headers checkbox to tell mSupply to ignore it.

If the spreadsheet software has added quotes around any of the fields during the export to a text delimited file then check the Remove quote characters on import checkbox (you can use the Previous and Next buttons in the preview panel to see if quote characters have been added).

Select one of the options in the If duplicate codes are detected section to tell mSupply what it should do if an abbreviation already in mSupply or previously in the spreadsheet is detected.

When you're ready, click on the Import now button to carry out the import.



Previous: 17.04. Importing prescribers | | Next: 17.06. Importing customer budgets

17.02. Importing stock

We strongly recommend:

* You take a backup of your datafile before attempting any imports.
* You test any import on a copy of your data before you do it on the real data.

Don't say you haven't been warned ;-)

The Import stock function allows you to import stock into a store after the items have been created (manually or by using the item import function).

Choose File > Import > Import stock from the menus. You will be shown a warning:

This is telling you to take care! The stock you are importing will be imported on top of the stock you already have in the store you are currently logged into. If you are not sure what you are doing, stop and make sure!

After clicking the OK button you will be told the next step is to select the import file:

Click the OK button on this window and an operating system window will open for you to select the import file. Find the file and double-click on it or click on it and click the Open button.

This window will open:

  • First line contains column headers checkbox: Check this by clicking on it if the first line of your file contains the column headers. If this checkbox is checked, mSupply will ignore the first row of the import file and only import from the second row onwards.
  • Remove quote characters on import checkbox: Check this if you want mSupply to remove quote (“) characters from the various fields as it does the import. This is often needed if your import file has come from Excel or another spreadsheet application. You can check if there are unwanted quote characters in the fields using the preview Next and Previous buttons (see below).
  • Next and Previous buttons: Use these to move through the rows in the import file. mSupply will show you the information is is going to import from each field in the import file. You will be shown a warning if you try to view lines before the start or after the end of the file.

If you spot any problems, click on the Cancel button, fix them and try again. If all is well, click on the Import button and mSupply will carry out the import. A progress bar will show you how far through the whole process mSupply is. When it gets to the end you will be shown a message telling you how many lines were imported successfully and how many were skipped (because the item could not be identified - because the item code was missing or did not match an item in your datafile).

Import file format
  • The import file must be a tab delimited text file.
  • The first row can contain the column titles but all other rows in the file should contain data to be imported.
  • The table below details the fields you should have (and the order they must be in) in each row of the file.
Column Field Description
1 (A) Item code Mandatory, Text, up to 18 characters. mSupply uses this to recognise which item this row of stock belongs to. If this code is missing or does not belong to an item already in your datafile, this line of the import file will be skipped.
2 (B) Item name Optional, ignored during the import. Text, up to 80 characters. The name of the item, here for reference so you can easily tell which item each row refers to.
3 (C) Units Optional, ignored during the import. Text up to 60 characters, for your reference only. The unit the item is to be measured in e.g. Tablet, Each, ml, g, bottle, vial, Ampoule.
4 (D) Pack size Mandatory, Integer. The number of units in a single pack for this stock line.
5 (E) Quantity Mandatory, Integer. The number of packs (containing the number of units in column 4) in this stock line. Equal to the total quantity if the Pack size is 1.
6 (F) Cost price Optional, Real number. The price you pay for one pack.
7 (G) Sell price Optional, Real number. The price the customers of this store pay for one pack. Set this to the same as the cost price or leave it empty if you do not actually sell the stock that you issue.
8 (H) Batch Optional, Text, Up to 20 characters. The batch of this stock line.
9 (I) Expiry Optional, Text, in short format (dd/mm/yy or mm/dd/yy, depending on the format set in your computer's operating system). The date this stock line will expire.
10 (J) Description Optional. Text, Up to 32,000 characters. The full description of the item. Be careful not to have any carriage return characters in the text though, or the import file will not be valid!
11 (K) Item Department Optional, Text, up to 30 characters. If you import a department name that doesn't exist, the department will be created.
12 (L) Shelf Location Optional, Text, Up to 60 characters. The code for the shelf location of this stock line.
If the location does not exist, the location will be created as the stock is loaded. You can then edit the location details after the import.
13 (M) Donor Optional, Text, Up to 60 characters. The name of the donor of this stock line. If the donor doesn't exist, it will be created.
14 (N) Custom stock field 5 Optional, Text. The value to be entered in custom stock field 5 for this batch. If the value doesn't already exist as an option for custom stock field 5 then it will be added. See the 7.05. Custom stock fields page for details of custom stock fields.
15 (O) Outer pack size Optional, Integer. The number of packs that fit in a carton (NOT the number of units in a carton!).
16 (P) Volume per pack Optional, Decimal number. The volume that a single pack of this batch occupies on the shelf in m3.
17 (Q) Weight per pack Optional, Decimal number. The weight of a single pack of this batch in kg.
18 (R) Manufacturer Optional, Text. The code of the manufacturer of this batch. If a manufacturer with this code doesn't exist in the datafile then it is created with the Code, Name and Charge to values all set to the contents of this cell.

Please note: It is not part of the import file but, if an item's default Volume per pack is set (see the Volume per pack field on the 4.01.02. Items - Storage tab page for details) then this will be applied to the stock line's volume per pack. The value will be proportionately increased or decreased if the stock line's pack size differs from the item's default pack size (Preferred pack size field on the 4.01.02. Items - Storage tab page).

Here is a blank spreadsheet you can use with the right columns: msupply_stock_import.xlsx

Note: the first row of data in red is an example row - delete it before you import it!

You can create the import file in various ways:

  1. Manually using the blank template above.
  2. Manually using any text editor.
  3. Export the current stock from a store in this or another mSupply datafile (and modify it if necessary) and import that.

If you use a spreadsheet application like Excel remember to export the file in Tab delimited text format before trying to import it into mSupply.

You can import as many batches of an item as you wish, there is no limit. And it doesn't matter whether batches of the same item are next to each other in the import file.



Previous: 17.01. Importing items | | Next: 17.03. Importing names

17.04. Importing prescribers

You need to be logged in to the store (dispensary) where the prescribers will prescribe before carrying out these steps.

Applicable in Dispensary mode only

From the File menu, choose Import Prescribers, and the Import alert window is displayed.

You may import a list of prescribers who have the authority to prescribe medicines.

Your list should be in the format of a 6-column spreadsheet, saved as a tab delimited file. The columns should be in the following order:

Column Contents Unique code for each prescriber
A Code Unique code for each prescriber
B Last name The prescriber's last name
C First name The prescriber's first name
D Initials The prescriber's initials. These will appear on patient labels
E Registration code The prescriber's registration code
F Category The category the prescriber belongs to

Your tab delimited spreadsheet file would appear something like this:

If the file you are importing has non-English characters (for example, accents), it is important to make sure the file is saved with a UTF-8 charset. You can check this by opening the file in Notepad (for Windows). When you save the file, you can choose the Charset used, as shown in the image below.

Choose import options from the preview window and click OK to begin import.

If there are non-printable characters before or after the first name, last name or code they will be removed. Any non-printable characters in the first name, last name or code will be replaced with an underscore (_).



Previous: 17.03. Importing names | | Next: 17.05. Importing abbreviations

17.20. Exporting invoices to Moneyworks

If you are using Moneyworks accounting software, you can export invoices directly to Moneyworks.

If you have turned this option on in the Preferences, rather than exporting a text file to disk, mSupply will attempt to connect to Moneyworks, and directly send the invoice data to Moneyworks, where a debtor invoice is created for each invoice in mSupply. You can then use Moneyworks superb statement production (with full control over the form design) along with it's open item handling of debtor and creditor payments to take over the handling of payments and receipts. Contact info@sussol.net if you would like more information.

Finalising. Note that if “export invoices when finalising” is turned on in the Preferences, invoices that have been finalised but not yet given an export batch will also be included in the list. If any such invoices exist you will be alerted to the fact. A text file called “supplier_invoice_expt.txt” will be created at the location you have specified in the Preferences.

Note: if you are using mSupply in Client/Server mode, exports will be sent to the “export” folder located in the same folder as the 4D client application.



Previous: 17.19. Exporting invoices | | Next: 17.21. Exporting to MYOB

18.06. Benchmark prices for tenders

A benchmark price can be considered to be a standard price to which other prices can be compared once you are at the stage of evaluating quotations. mSupply provides the ability to set up benchmark prices to help you make such a comparison. This section describes how to set them up and how to use them.

The International Medical Products Price Guide, published and maintained by MSH, is available on their website (http://mshpriceguide.org/en/home/) and is a good source of information on medical products from a range of international distributors.

Setting up

You need to create a dummy supplier, that is to say a `virtual' supplier, whose only purpose is to store benchmark prices.

From the menu, or the Navigator, choose Supplier > New supplier

mSupply® requires that the Code, Charge to and Name fields are completed, so you should choose appropriate entries. In the Category section, the checkbox Supplier should already be checked, and you must check the Benchmark checkbox.

You may set up more than one benchmark `Supplier'

Entering benchmark prices

Once you have the required benchmark prices, they should be entered into mSupply, and here's how to do it:

Open the Edit supplier window for the Benchmark supplier and click on the Quotes tab

Click on the New Quote button to enter the benchmark figure for each item - in our example we're entering the details for Albendazole 400mg tablets:

Points to note:

  • If the figure you have is for a single tablet, we suggest you multiply it by 100 and change the pack size to 100 to avoid working with very small figures.
  • Make sure that the currency used for the entry is correct, remembering that it might be different from your default currency.
  • Make sure that your pack size matches the pack size of the benchmark figure.

Once a number of entries have been made, the window may appear like this:

You will note the difference for each item in the Price column and the Cost column; the explanation is that the default currency in this example is AUD (Australian dollars), while the benchmark figures are in US dollars; the Cost (and Adjusted cost) columns show the figures converted by mSupply to their AUD equivalents.

Using the benchmark figures when evaluating submitted quotations from suppliers is discussed here

Previous: 18.05. Tender reference documents | | Next: 18.07. Analysing supplier responses and creating purchase orders

18.03. Adding suppliers to a tender and inviting responses

Adding suppliers ot the tender can be done while the tender is at suggested or confirmed status. But it is good practice to confirm your tender after adding items and conditions, then add suppliers. After confirmation you can no longer add items or conditions to your tender.

To add suppliers to the tender, click the Choose suppliers and enter responses tab to open this window, where the suppliers to whom your tender will be sent may be added, or subsequently deleted:

Note: The HSH Link column in the table shows whether the selected supplier has been linked with the Health Supply Hub (checked if it has). See the 18.10. Using web tenders page for details on the remote tender module.

To add suppliers to the list, click the Add Suppliers button.

A list of all suppliers is shown:

You can add multiple suppliers by holding down the control key (command key on Mac) and clicking on those suppliers you wish to add. Once you have selected a supplier or suppliers, click the Use button to add them to the list. To create a new supplier, click the New button.

Note: You cannot add suppliers more than once to a tender; you will told that a supplier is already part of the tender if you try to add it again.

Once suppliers are added, they will appear in the list:

Double clicking a supplier will open a window for adding and editing quotations - see below.

It there are any suppliers listed that do not have a tick in the RTM Link column and you intend to publish the tender to the web, you will need to contact mSupply Support: support@msupply.org.nz

Deleting a supplier

Highlight the supplier you wish to remove from the tender, then click the Delete supplier button. This will remove the supplier from the tender - it will not delete the supplier from mSupply. Note: you cannot remove a supplier from a finalised tender, or if the supplier has quoted on one or more tender items. If you want to remove a supplier for which quotations have been entered, delete the quotations first, then you can delete the supplier.

Inviting quotations from suppliers

Clicking this button prints an “Invitation to tender” letter ready for dispatch to the highlighted supplier; the letter includes all the items, quantities, etc. as specified in the tender. The default date for a response is one month after the date of the letter, but this can be amended to a date of your choosing.

If the default format of the Invitation letter does not meet your requirements, please let us know and we will customise the print format to meet your individual requirements.

Email Selected button

Clicking this button produces email documents for each of the highlighted suppliers. A PDF document (the same as the printed document) is produced, attached to an email and stored in the email queue. This option will work only if you have entered email addresses for the chosen suppliers.

Whichever method you choose, you will be given the option for the Date sent field to be filled automatically with today's date.

To Spreadsheet button

Clicking this button gives you two options:

  1. Supplier response template
  2. Tender lines with supplier response

Both open a spreadsheet in you spreadsheet application. The first is used to import a supplier's quotes into the tender (see the 18.04. Adding supplier responses to a tender page for details). The second has all the items and quantities required on the tender document and any supplier responses already entered. It is useful for sending to the supplier along with the tender letter or as a record of their responses entered into the system.

Previous: 18.02. Standard tender conditions | | Next: 18.04. Adding supplier responses to a tender

18.07. Analysing supplier responses and creating purchase orders

Review

At this stage you should already have performed the following:

  1. Created a new tender
  2. Quantified how much you need to order and added these lines and quantities to the tender
  3. Decided which suppliers should be invited to tender, and added them to the tender
  4. Sent out the tender and invitation to take part to the suppliers you selected
  5. Entered responses to your tender (quotations) from suppliers

Having performed these steps, your tender should be set to confirmed status and you are ready to compare the prices quoted, and decide upon a preferred supplier for each item.

Benchmark supplier

Before analysing the various responses to your tender, you may wish to set one of the suppliers to be a benchmark (or maybe you had specifically added a dummy benchmark supplier to the tender and added benchmark prices in their quote). If you so this, mSupply will indicate how much higher or lower than the benchmark supplier's quote, all the other suppliers' quotes are. It can be a handy indicator to help the analysis process.

To set a benchmark supplier, open the tender (choose Suppler > Show Tenders… from the menus and double-click on the tender in the list) and on the Tender preferences tab, in the Benchmark supplier section select the desired benchmark supplier in the Benchmark supplier drop down list:

For more details on using benchmark price see Using benchmark prices.

Analysing the responses

Once you have the tender open (choose Suppler > Show Tenders… from the menus and double-click on the tender in the list), select the Items and compare prices tab:

Note that mSupply will remember any changes you make to the widths of the columns on this tab. This can be very useful if you want to minimise columns you are not interested in to make room for other, more important columns over several sessions to select the winning bids. This also applies to the Compare supplier responses tab shown below.

Then double-click the first item in the list, which in our example is Acetazolamide 250mg tablets, to bring up the Edit tender item window, which opens at the Compare supplier responses tab:

In our example, 5 suppliers have been invited to tender, and 4 have submitted tenders, one supplier having submitted prices for two different pack sizes. One supplier has not submitted a quotation, so all the entries for that supplier are zero.

The important column is the Adj Cost column, this allows you to compare prices which have been evened out to cater for differences in pack sizes, currencies and freight costs. mSupply makes it easy to identify the lowest price quoted because it appears in blue type. Clicking the Adj Cost column header will sort the entries so that the cheapest one appears at the top of the list.

If a benchmark supplier had been selected then the +/-% column would display what percentage above or below the benchmark supplier's quote that particular quote was. A negative value indicates that the quote is below the benchmark quote, a positive value that it is above. e.g. a figure of -2.78% would mean that the quote was 2.78% less than the benchmark quote.

If you want to highlight any particular line for any reason, you can change its colour by clicking on it in the list to select it then selecting the desired colour from the colour drop down list (currently showing “Black” in the screenshot) in the top right hand corner.

Note that if you want historical data of all previous stored quotes for an item, including those from previous tenders, this is available by choosing Items > Show items… from the menus, locating the item, then viewing the Quotes tab.

Before marking the supplier of the cheapest item as the preferred supplier, there are other factors to be considered, including:

  1. Has the supplier met all the tender conditions?
  2. Is the proposed delivery schedule acceptable?
  3. Is the product being supplied by a reputable manufacturer?

The Disqualified column allows you to disqualify the quotation from a particular supplier if required by checking the box in the relevant row.

Note: If you want to quickly add an Evaluator comment, click in the appropriate cell of the Evaluator comment column and type the comment directly into the cell. This saves you double-clicking on the line and entering it in the Evaluator comment field on the line detail window that opens.

If you want to see more information about a particular quote line, double-click its row to open the Edit quote line window to view all the details of the quotation (and edit it too - useful if you discover a data entry error, for example). You may want to fill out the Quote Comment to record any decisions you made e.g. reason for disqualification.

When you have decided on a supplier for an item, check the box in the Preferred column in the row for that supplier. Proceed to the next item by clicking the OK & next button and repeat the process. When you have finished, click the OK button to return to the Edit Tender window.

It is, of course, not necessary to complete the selection of preferred suppliers at one session on the computer; it can be done in stages. Actually, you don't have to select preferred suppliers for all items before you complete the tender; you may want to wait for more favourable market conditions before purchasing some items, for example.

Please also note that all changes to tender lines are logged by mSupply.

Here is an example of a tender that has been partially processed, looking at the Items and Compare prices tab:

Two of the lines have been changed to a green colour. The Preferred supplier column can contain the following values:

  • No bids: no bids from any supplier have been entered for this item.
  • Not selected: bids have been entered for the item but none has been selected as preferred yet.
  • A supplier name: bids have been entered for the item an one, from the displayed supplier, has been selected as preferred.

The Show drop down list just above the list of items is currently showing all lines but it has these options:

  • All: show all tender lines, no filtering.
  • Filled: show only those lines that have had bids entered for them, whether a preferred one has been selected or not (helpful for showing what still needs to be processed).
  • No bids: show only those lines that have had no bids entered for them.
  • Lowest cost not chosen: show only those lines where a bid has been selected as preferred and it did not have the lowest cost.
  • 0 number of packs: show only those lines that have zero packs entered for them. This is not possible for manually created tenders but could, in certain circumstances, be possible with auto-generated tenders or tenders downloaded from the Health Supply Hub.

Back to the Items and compare prices tab

Once you have finished editing, click OK (or Cancel if you want to close the window without saving changes to the current tender line).

The column Preferred Supplier will now display either the name of the supplier you have chosen or Not chosen where you have not yet processed the item.

The Original column will display the cost of that line if you purchase the tender quantity of that item from the preferred supplier in the currency quoted (The Original Local column displays the cost in the local (default or home)currency you are using in mSupply). Note that you might end up editing the quantity on the purchase order to a different value, and then the PO local column will have a different value.

Back to the Choose suppliers and enter responses tab

Just before you create purchase orders for the winning suppliers you might like to see the value that each supplier has won. To do this, click on the Choose Suppliers and Enter responses tab and the total value that each supplier has won (i.e. the total value of all the lines where they were selected as the preferred supplier) will be shown in the Tender value column. The total amount that each supplier bid will be displayed in the Total bid column.

Reports

You might need to provide reports to a tender board, or for internal records. The tender module has several reports built in, accessed by clicking on the Print internal report button on the Items and compare prices tab of the tender details window. Clicking on the button displays this window with a drop down list of reports to choose from:

Winning tender lines: Shows all the items in the tender which have been allocated a preferred supplier and the costs of those lines. This is an example:

Supplier quotes for each item: Shows quotes from all suppliers for all items, grouped by item. Handy for a summary of all received quotes.

Tender lines with predicted cost: Can be used to give an approximate cost of the tender before choosing preferred suppliers for all items has been completed. Where items have not been allocated a preferred supplier, mSupply will use previous purchase costs as an estimate of what the cost will be in this tender.

Tender lines: lowest price not chosen: Shows all tender lines which have been chosen as the winning bod when their price was not the lowest. Summary detail shows how much more you will pay than choosing the cheapest lines.

Evaluation report: Useful for showing all evaluation details or for using during a manual evaluation exercise. Shows all quotes for each item and the outcome of the evaluation (or space for you to enter the outcome). It looks like this: Note that the Number of suppliers invited figure at the bottom of the report actually shows the number of suppliers who responded and submitted bids to the tender.

Setting up purchase order (PO) preferences

Once the choice of preferred supplier has been made for all the items you want to purchase in the tender, the next stage is to generate the Purchase Orders.

Click on the Tender Preferences tab on the Edit Tender window:

mSupply offers two options for creating Purchase Orders:

  1. Recalculate PO quantity according to usage should be chosen if you wish mSupply to take into account the usage during the period since the tender was generated; this may be significant depending on the length of that period of time.
  2. Distribute Tender quantity evenly should be chosen if you wish to make no changes to the quantities calculated at the time the tender was generated.

For our example, we are choosing Distribute Tender Quantity evenly because we are content with the quantities which mSupply has calculated and we do not want to make any adjustments. In this case, the Based on field should be ignored.

Split deliveries

If you want to receive split deliveries, then mSupply will create multiple purchase orders for you, each with a different requested delivery date.

mSupply will behave differently when creating Purchase Orders depending on whether this option is checked or not.

Note that the creation of purchase orders from tenders will be logged by mSupply.

When creating purchase orders from a tender, mSupply will use the winning bid quantities and packsizes, rather than those requested in the tender. A supplier may have offered different pack sizes and quantities to what you set in the tender.

Creating purchase orders with split deliveries
  1. Go to the Purchase Orders tab
  2. If you have checked the “Split deliveries” checkbox in the preferences for this tender, the first button on the toolbar will be Create blank POs.

You will need to confirm that this is what you want to do by clicking the Yes button on the confirmation window which appears:

You are then shown a list of suppliers:

Click on the supplier(s) you want to add, and enter the requested delivery date, then click OK.

You will need to add each supplier twice if there are to be 2 deliveries, or 3 times for 3 deliveries (etc) Make sure you get the delivery date right for each one.

You can double-click an already entered line to change the delivery date.

Use the Delete PO button to remove a purchase order (highlight to one(s) to delete before clicking the button).

Creating purchase orders without split deliveries (single delivery)

If you aren't creating split deliveries, the first button will be labelled Create PO

  1. Click this button, and the needed Purchase orders will be created.
  2. Double-click a row to see the order.
  3. Return to the “Suppliers” tab if you want to see the value of the purchase orders in total.
Viewing tender purchase orders

When you have created purchase orders in a tender you can view them at any time by clicking on the Purchase order tab which will look like this:

To see the details of the items on any of the purchase orders in the list, simply double-click on the purchase order's line in the table and you will be shown the details in a window which looks like this:

Editing purchase order quantities

Once you have created Purchase orders you might want to edit some quantities (for example, you might want the first of two purchase orders for a supplier to have 60% of the total order, and the second purchase order only 40%)

  1. Go to the “items and compare prices” tab
  2. Double-click a line to edit
  3. Go to the Purchase Order tab.
  4. You will see your purchase orders for that item.
  5. To edit the first row, click once on the quantity, wait 2 seconds and click again.
  6. You can now change the quantity.
  7. Use the tab key to advance to edit the quantity of the second row, etc.

Converting to a "normal" purchase order

While a purchase order is being created and edited inside the tender module, it has the status of “tn” and isn't visible in the same way that purchase orders created outside the tender module are. Purchase orders that are visible in the main mSupply system have a status of “sg” (or “cn” or “fn”). Once you are satisfied with your purchase order in the tender module do this:

  1. Go to the purchase orders tab
  2. Click on a purchase order to convert (only one at a time at the moment, sorry)
  3. Click Convert to SG
  4. Confirm the warning window, and the purchase order will now:
    1. no longer be editable in the tender module
    2. be available using Suppliers > Show Purchase orders from the mSupply menu or navigator.
  5. Repeat the process with other purchase orders that are ready to send to a supplier.

You can now view the purchase order, confirm it, and send to a supplier - see Purchasing: Ordering from Suppliers: Viewing a purchase order.

Finalising a tender

This should be done when all processing of the tender is complete and the purchase orders have been created and sent to the suppliers. The tender will not be editable after this so PLEASE make sure you are sure that all processing is complete!

When you finalise a tender you will be warned if there are no Purchase orders associated with it because you won't be able to create them later!

Field Descriptions and Formulae

Column name Description Formula
Price The price per pack offered by the supplier
Net Cost The cost in local currency (i.e. datafile default currency) of the offered pack size, multiplied by freight factor Offered price * currency rate * freight factor
Local Cost Alternative name for Net Cost
Total Cost The Total cost of the offered number of packs in Local Cost Net Cost * Offered Number of Packs
Adjusted Cost The cost adjusted by currency, freight factor and item's default pack size for direct comparison between quotes Net Cost * (Default packsize/Offered packsize)



Previous: 18.06. Benchmark prices for tenders | | Next: 18.08. Tender currencies

18.08. Tender currencies

You will have noticed that responses from suppliers can be received in any currency in an mSupply tender. For comparison with other tender lines, all lines are converted to the home currency of the datafile using a rate that is defined by the user. These rates are stored and managed separately for each tender so that historical records of the rates used in any particular tender are retained permananetly. The rates used for currency conversion throughout mSupply will change over time to keep up with fluctuations but any such changes will not affect tenders and their historical records.

The conversion rates used for each currency in a tender are shown and managed on the Currencies tab, which looks like this:

Whenever a tender is created all foreign currencies with their current rates are added to the table. If a new currency is added to mSupply (see the 26.10. Currencies page for details) then it is added to this table. When responses are downloaded from the Health Supply Hub (HSH), any currencies used but not already in this table are added.

The columns in the table display the following:

  • Currency: The three letter abbreviation of the currency.
  • Tender Rate: The rate used to convert this currency to the home currency of the datafile.
  • Last Updated: The date the rate was last updated (empty if it has never been updated in the tender).
  • New Rate: The new rate to set the Tender Rate to (doesn't do anything until the Update Selected Rates button is clicked).
  • New Rate Date: The date to say the rate was updated on.
  • Number of Quote Lines: The number of supplier response lines on this tender that use this currency. This value is updated whenever a line uses a currency or is added or deleted.
  • Total Cost: The total value of the supplier response lines using this currency in this tender. This value is updated when the cost of a line is changed, added or deleted.

Update Selected Rates button: Sets Tender Rate to the New Rate and the Last Updated to the New Rate Date column values for the rows you have selected. The tender now uses this rate to convert this currency to the home currency of the datafile. The home currency row cannot be updated and the no update will occur if the New Rate and New Rate Date values are not different from the Tender Rate and Last Updated values. Please note that you can also manually update the New Rate and New Rate Date columns.

Get Central mSupply Rates button: Populates the New rate column with the current rates set in mSupply (see the 26.10. Currencies page for details) and the New Rate Date column with the date that rate was set. In a synchronisatin system the values are retrieved from the central server.

Get Internet Rates button: Populates the New rate column with the latest currency rates from the internet and the New Rate Date column with the current date. A progress window will show you how complete the process of getting the internet rates is.



Previous: 18.07. Analysing supplier responses and creating purchase orders | | Next: 18.09. Supplier instructions for using tender submission web interface

Updated: Version 3.1

18.01. Introduction to tender management

Introduction

In order to achieve the best value for available funds, it is common practice to seek out the best prices for the medicines that will be required, usually for the forthcoming year, by publishing a tender. Normally, the full tender process creates a lot of work which can be very time consuming and error prone. The mSupply tender module is designed to make the process as simple as possible, to minimise the work involved and to reduce the chance of errors.

As usual in a tender process, forward planning is necessary, as the process must be started several months before the goods will be on site and available for use.

The work flow for using the tender module is:

  1. Prepare list of items and quantities. See Creating a new tender. When all items have been added to the tender, it should be set to confirmed status.
  2. Distribute list to suppliers. See Adding suppliers to a tender
  3. Create benchmark prices. See Using Benchmark prices
  4. Evaluate received quotations. See Receiving Quotations from suppliers
  5. Select preferred suppliers. See Accepting tenders. After selecting the preferred suppliers for all items, the tender should be set to finalised status.
  6. Create Purchase Orders. See Supplier responses & Creating Purchase Orders

From your usage history, mSupply can prepare a list of items and anticipated quantities. This list is distributed to suppliers, who are invited to submit, after a reasonable period of time, their quotations, inclusive of all additional charges., e.g. freight.

The list may be uploaded to the web, and interested suppliers invited to submit their quotations online. Conventional methods of submitting quotations are also available. We recommend the online method, as it reduces paper consumption, and is less labour intensive and less error-prone.

Once all the quotations have been received, mSupply will assist in processing them, comparing quotations, performing necessary currency conversions where appropriate, applying freight charges etc. mSupply will mark the lowest item price blue. If two lines are the same price and are the lowest price both will be coloured blue.

The user then has all the relevant information enabling informed choices to be made in selecting which supplier for which item.

Finally mSupply will create Purchase Orders for the successful bidding suppliers. While mSupply can perform all these tasks from stored usage data, it will allow users to change supplier and/or quantities, should special circumstances prevail in particular situations.

Preferences: There are preferences that can be set for the tender process, see tender preferences.

Note that for multi-user installations, Tender management activation requires payment of a fee. Please see the website here or contact Sustainable Solutions for more information.

Getting started

Select Show tenders… from the supplier menu or from the Navigator's Suppliers tab.

A window is shown with a list of current tenders (if any) and some options:

The Show drop down list is a filter which allows the list of tenders displayed to be changed:

Creating a new tender

Three options are available :

  • New Generated Tender Once you have been running mSupply for a year, and providing that year is fairly typical of your overall usage, the New Generated Tender is recommended; this option will suggest quantities based on actual usage, having regard to seasonal fluctuations, thus eliminating any guesswork. Quantities are suggested only, and may be amended as required.
  • New Tender - allows you to create the tender manually and is a more labour intensive process.
  • Duplicate - select a single tender in the list and click on this button to create a tender that is a duplicate of the one you selected with the same items but no invited suppliers. The duplicate will have the same name but with “ - COPYX” after it, where X is the duplicate number. The duplicate will also have a status of “sg” (suggested), regardless of the status of the tender it was copied from.
  • The creation (or deletion!) of a new tender will be logged by mSupply.
  • All tenders belong to the store they are created in and will not be accessible in other stores (but supervisor mode users can view tenders in all stores). This also means that you can only access items visible in the store the tender is created in, whether you manually create or auto-generate your tender.
New generated tender (auto-generation)

To have mSupply automatically create a suggested tender based upon your projected demand, click on the New Generated Tender button, and confirm your intention by clicking Yes on the Confirm window.

This window will appear. You may recognise it from the Item usage report, the Suggested order report, and 6.01. Ordering stock from suppliers - it uses the same functionality (please see those pages for a detailed description of how to decide what to enter for the various options):

You can tailor your search by item in the usual way. Clicking the refresh button (double arrows near the centre) shows an estimate of how many items will be processed. Further refinements can be added. It is recommended to use the Calculate button to refine the Months of stock required figure by entering Lead time, Ordering Cycle and Buffer stock values directly. To find out what all the options do and how the calculation works, please see the 13.04. Purchasing reports page for details.

Processing all this data may take some minutes if you have a lot of stock items recorded in your system, so mSupply will ask you if you've got the time to do it. If you do, click `Yes'. A progress indicator will show you how much work is left to be done. When mSupply has finished processing everything, it will let you know:

Auto-generated tenders may be rather large, so you may wish to process several tenders with more specific criteria rather than one huge one at once.

You can choose to look at your tender immediately, or return to it later. If you click `Yes', you'll see something like this:

  • Several default values have been entered for the Description (made up of the tender number, date and time of creation and number of months stock required), Issue (the current date) and Response by (one month from the current date) dates and Our ref (AUTO followed by the tender's number) fields at the top that you're going to want to change.
  • The pack size will be determined by the preferred pack size. If no preferred pack size has been set, then a pack size of 1 is used.
  • If the item has no defined units, this it leaves units blank, and enters a `Check units!' warning into the comments.
  • Tender auto-generation will therefore be most useful if values are set for preferred pack size and units for the items.
New tender (manually entered)

To create a new tender manually, having opened the Tenders window by clicking on Show tenders on the menu, click the New Tender button.

This window opens:

Here you can fill in basic information about the tender.

  • Description: Enter a description that will help you to recognize this tender and distinguish it from others. For example: RFQ 18-013 It is helpful if this Description matches any register of tenders / quotes that is already being maintained by your organisation.
  • Creation date: The date the tender was created. This defaults to today's date.
  • Issue date: The date the tender is/was sent to suppliers. This also defaults to today's date, but can be changed.
  • Response by date: The date by which suppliers must respond to the tender. It is left empty by default: if you leave it empty you will be prompted to enter it. When entering this date it must be after the current date (it cannot be today or in the past).
  • Status: Tenders can have a status of sg/cn/fn (suggested, confirmed or finalised), which signifies its passage through the overall tender process. To change the status of the tender, simply select the new status from the drop down list and click on the OK button to save all changes. You will be asked to confirm a change because it has a significant impact on the editability of the tender. These are what the statuses mean:
    • Suggested status - tender is still being built. Everything is editable.
    • Confirmed status - list of items & quantities is complete and can no longer be edited. Suppliers invited to provide quotations may be added, and, once received, their responses may be added. Decisions may then be taken regarding which quotation is preferred for each tender item.
    • Finalised status - no further editing may be performed, and the tender can now be used as a basis for purchasing
  • Locked checkbox: Check this box to ensure the tender is not accidentally deleted.
  • Our ref: This field may be used to enter a short reference code to appear in tender-related correspondence.
  • Comment: The comment field is for your internal use. It is not printed on any tender documents.

Tabs on the tender details window

Details of the tender are managed through the tabs on the Tender Details window:

Items and compare prices tab
  • This tab displays by default when you open a tender for editing. It displays the items currently included in the tender, and by selecting 'All', 'Filled' or 'Unfilled' from the drop-down list above and to the right of the list, you can select which items are displayed.
    • New line button: click this to add a new item line to the tender. The addition of the new line will be logged by mSupply.
    • Delete line button: select an item line from the list and click this button to remove it from the tender.
    • Print reports button: click this to select one of several reports to print out or export to a spreadsheet. There are several to choose from and will give you the information you need to help evaluate or analyse a tender:
      • Preferred suppliers only
      • Winning tender lines
      • All supplier responses
      • Supplier quotes with adjusted price
      • Supplier quotes for each item
      • Tender lines with predicted cost
      • Tender lines where the lowest price was not chosen.
    • Confirm button: Click on this to confirm your tender. After confirmation you will not be able to add more items or suppliers.
    • View on HSH button: If the tender has been uploaded ot the Health Supply Hub, you can click on this button to view it there.
    • Export/Import Tender lines button: Only enabled if the tender is not confirmed or finalised status. When you click on this you are given an option to Import or Export the tender lines. If you click on the Export option then the existing tender lines will be exported to a spreadsheet which will be immediately opened for you if you have a spreadsheet application installed on your computer. The spreadsheet is in the correct format to allow importing into another tender. If you click on the Import option this window will open: Click on the Replace all lines option if you want the contents of the import file to replace all existing lines on the tender or the Update existing lines option if you want any lines with matching item codes to be updated with the details in the import file (all lines in the import file for items that are not already on the tender will be added to the tender). The click on the Import button and you will be shown a window for selecting the import file. The file must be in the format described on the 17.14. Importing tenders page. After selecting the import file, double-click it or click on it to select it then click on the Open button to carry out the import. The tender will be updated and you will see the lines now on the tender.
    • Incoterm drop down list: Allows you to select an incoterm to apply to the tender. If you will be uploading the tender to the Health Supply Hub (see the 18.10. Using web tenders page for details) then the incoterm must be selected before you can upload the tender. You must also select it before you can confirm the tender.
    • Search items text box: as you type in this text box, only items whose names start with what has been typed will be displayed in the table. You can use the “@” character as a wildcard to represent anything. For example, typing “@ol” will display only items with names which end in “ol”. This box is helpful for quickly finding a specific item. Overrides any selection made in the Show drop down list (see below).
    • Show drop down list: is another way to change what items are displayed in the table. Selecting one of these options will override anything typed in the Search items text box:
      • All - display all items without filtering
      • Filled - display only those items for which a bid has been accepted
      • No bids - display only those items for which no suppliers have made a bid
      • Lowest cost not chosen - display only those items where the lowest offered cost price was not chosen as the preferred bid

Note that changes to tender lines will be logged by mSupply.

Notes tab

  • This tab shows a field where you can add notes about your tender. This will not print on the documentation sent to suppliers.
  • To start a new line (as with any text box), press Shift+Enter (although any long lines will wrap). See below for an example:
Choose suppliers and enter responses tab
Standard conditions tab
Purchase order tab
Reference documents tab
Tender preferences tab
Synchronise tab
  • This tab will only appear if you are using the remote tender module have set up your remote tender preferences. The process and use of this tab is described on the 18.10. Using web tenders page.
Log tab
  • This tab shows recent events relating to this particular tender. It will show, for example, changes in prices or other significant events. You cannot edit the details on this tab. If an event fails to be logged for any reason while the tender is being processed, you will be given an appropriate warning message.
Currencies tab
  • This tab shows the currencies available in mSupply and the rates that were used in the tender. It is also the place to change the rates that are used to convert prices between the datafile's home currency and any other currency. See the 18.08. Tender currencies page for details.

Adding items to a tender

To add an item to a tender, click the New line button on the Items and Compare Prices tab.You will be shown a window like this, which opens at the Set tender item criteria tab:

  1. Type as much of the item name or code as you know, then press the Tab key. If only one item matches your entry, it will be filled in. If multiple items match, you will be shown the standard item choice list to choose the item you want. Any details completed in the Full description under the General tab of the selected item are displayed (Description).Should you wish to identify a line (or lines) for any reason, clicking on the Colour button presents you with a selection of colours available for the type on that line.
  2. Fill in the pack size and number of packs you wish to purchase, or the total quantity of individual units. mSupply will calculate the figure you don't enter for you. The Round quantities button will round the number of packs to the nearest reasonable number of whole packs (most useful for auto generated tenders when the number of packs can sometimes be set to a decimal number).
  3. Choose the units you wish to use.
  4. You may optionally enter a price per pack figure in the Estimated price field.
  5. Entries in the Comment field are for your internal use, and won't be printed on the tender documents you present to suppliers.
  6. In the Conditions field, enter any conditions which are specific to this item of the tender , but NOT applicable to the tender as a whole. These conditions will be printed on the tender letter with the item details.
  7. The Product specifications field is read only and automatically populated with anything entered in the item's Product specification field; see the 4.01.01. Items - General tab page for details,
  8. Click on OK & next to add the next item to the tender, and when you are finished, click on OK.
  9. The addition of a new line will be logged by mSupply.

It is perfectly possible to add the same item more than once to a tender. Each entry will be treated separately. This allows for the same item to be added, for example, in different pack sizes.

Note that it is also possible to use decimal pack sizes and number of packs, but not advisable. mSupply will ask you to confirm if you do use decimal values for either of these.

The second tab Compare supplier responses, is for use after suppliers have responded to the tender - refer Receiving quotations from suppliers - Comparing quotations from different suppliers.

Deleting tender items

Click the line you wish to delete so that it is highlighted, then click the Delete line button. If a supplier has already quoted on a tender item, you will be warned before deletion. The deletion of any tender lines will be logged by mSupply.

Editing tender items

From the Items and compare prices tab, double-click the tender line you wish to edit. The 'Edit tender item' window will open, allowing you to edit the details in the same way as entering a new tender item, above. Note: you cannot edit or delete lines on finalised tenders.

The Search item field allows you rapid access to any item in the tender - just enter the name (or first few letters of the name) of an item in the tender, and it will be displayed.

Here's how the Edit tender window looks when the item Ranitidine 25mg/mL injection has been selected; the automatically generated tender has calculated that 1023 ampoules are required; here you can edit the quantity to conform with, say a pack size of 10, so you would adjust the pack size to 10, and the quantity to 102 or 103.

You can use the OK & Next and OK & Previous buttons to go straight to the next or previous item in the list.

Note that any changes to a tender line are logged by mSupply.



Previous: 18. Tenders | | Next: 18.02. Standard tender conditions

18.04. Adding supplier responses to a tender

Supplier responses can only be entered when the tender is at confirmed status.

Suppliers respond to your invitation to respond to a tender with quotations. To process a quotation from a supplier, open a tender (choose Suppler > Show Tenders… from the menus and double-click on the tender in the list) and go to the Choose suppliers and edit responses tab:

Note: all bid values are converted to the local currency of the datafile for display in this window. That currency is shown just above the table on the right hand side.

Double-click the supplier name you want to enter a response for. The Edit Quote window will appear:

What you do from here depends on whether you want to enter the supplier responses manually or import them from a spreadsheet.

Entering responses manually

The Date sent field may be edited if necessary. You should enter the date the supplier responded, and in the Valid till field, the expiry date of the quotation. Also, enter the reference that the supplier is using for their own records (to be quoted in future correspondence) in the Their reference field, and, importantly, the currency in which the supplier has responded (on the Edit Quote tab). If you have previously set a default currency for this supplier, this drop-down list will already be set to that currency. Otherwise, your own default currency will appear.

The freight charge per cubic metre [m3] should be entered; if the volume of each item's pack is known, this can also be entered (at a later stage), allowing a more accurate total cost of each item to be evaluated.

Multiple currency tender quotations

A quotation may be received from a supplier which has used one currency for some items, and another currency for others; or has submitted more than one quotation for the same item, each one in a different currency (e.g. Euros and US dollars). Should this occur, it is strongly recommended that you process the quotation as two or more separate quotations, each one restricted to a single currency. That is, enter the supplier twice in the list of suppliers, then add a comment to the quotations to distinguish which quotation is in which currency. We have designed mSupply like this so that when Purchase Orders are created, a single Purchase Order only uses one currency. Mixing currencies on a Purchase Order is likely to cause confusion and errors.

Adding quotation lines

Now you can add the supplier's quotation line by line. On the Edit Quote tab, click on the New line(s) button. A window will open showing you a full list of all the items on the tender:

Select from the list all the items you want to enter quotes for. You can use the usual Control+click (Cmd+click on Mac) to add/remove an item to your selection, Shift+click to add/remove a range of items from your selection or Control+A (Cmd+A on Mac) to select all items. Now click on the Use button and all the items you have selected are added to the quotation with zero cost. In this example we chose to add the first 5 items in the tender:

To add the same item twice to a quotation from a supplier, click the Add lines(s) button and choose the item a second time. You will be shown a warning that the item is already on the quotation, and be asked if you want to add it again. You might need to do this if the supplier has supplied two prices for the same item based on differences in packaging or other specifications. Note that if you entered an item twice in a single tender to account for such differences, it will appear twice in the list and you won't need to carry out two selections.

In the event that the currency of the quote from the supplier is not the same for each line, mSupply allows each line's currency to be edited, and the appropriate one selected.

Entering prices for each quotation line

When you have added all the items you want to the quotation, it's time to add the prices and other details of the supplier's quotation. To do this, double-click on the first quote line to open the Edit Tender Response Item window:

The tender details are shown at the top.

In the fields below, enter the price and other details the supplier has provided. Enter as much as you can because you'll use this information when comparing quotes from different suppliers.

General

The Date, Item and Supplier fields are filled in automatically

Manufacturer

Type the first few characters of the manufacturer's name and press the Tab key on the keyboard to see a list of matching manufacturers. Select the one you want.

Price

The price you enter is the price for ONE PACK of the pack size shown in the Pack field.

Valid until

The date this quote will expire.

Pack

The pack size (number of single items in one pack) this quote is for. This value should be the preferred pack size

Currency

The currency the Price is in.

Rate

The rate used to convert the Currency of this quote line to the currency you are using in your datafile.

Rate to use

You can use a different rate to convert the Currency of this quote line to the currency you are using in your datafile if you like - just enter it here.

Disqualified

Check this if the quote line is disqualified for any reason (excluded manufacturer, for example).

Preferred

Check this if this is the quote you want to accept as the best - see later sections on comparing quotes from different suppliers for more on this.

Cost Local/Pack

The quoted cost per pack in your local datafile currency when converted from the quote line currency using the rate entered in the Rate to use field. This number is calculated; you can't enter it.

Evaluator comment

Enter anything you need to remember or need others to know when evaluating the quote and comparing this quote with those from other suppliers.

Price break

You can add price break information that the supplier has provided you in this Price break section. A price break is a reduction in price when you order over a certain quantity.

Price Break quantity

This is the number of items at which the reduction occurs and the Discount will apply.

Discount

This is the percentage reduction that will apply to the price entered in the Price field once the Price break quantity is reached.

Freight

If you are calculating freight based on volumes or weight, or using a freight factor, enter that information in this section.

Volume per pack

This is the volume, in cm3, for the preferred pack size.

Freight factor

The amount to multiply the quotation price by to account for freight charges. By default this will be set to the supplier's freight factor, set on the General tab of a supplier's details page; see the 5.06. Suppliers: adding and viewing page for details of that.

If the supplier's freight factor is edited then quotations will be updated with the new freight factor (and therefore price) accordingly.

Freight for preferred pack

This is the cost of freight for the preferred pack size. This will be added to the Price per preferred pack size.

Freight notes

Any notes.

Supplier

Enter any extra details about the supplier in this section.

Supplier's code

The Supplier's code for the item. This will appear on the Purchase Order. This field will be filled in automatically from a tender downloaded from the Health Supply Hub.

Supplier bar code

The Supplier's bar code for the item. If this is entered correctly, then the correct item can be picked up by a barcode scanner when receiving the goods.

Exp date

The expiry date for the stock of the item.

Delivery time

How long it will take for the supplier to deliver the stock.

Method of delivery

A free-text field to record the method of delivery (e.g. air, sea, sea and land etc.). This field will be filled in automatically from a tender downloaded from the Health Supply Hub.

Supplier comment

Any comments the supplier has made about this line or the stock they will supply.

When you have finished entering details for the quote for this item, click on the OK & Next button to move to the next item or OK to save the current quotation line, close the window and go back to the Edit Quote window.

When you have finished adding all suppliers' quotes to the tender we recommend that you set the tender's status to confirmed (on the Edit tender window at the top).

If you're finding that entering all the supplier's quotes is too much work then there's help for you! The Remote tender module is what you need. All the suppliers enter their own quotations to the remote tender module and, when the tender closing date has passed, you can simply download them to mSupply. See Uploading and downloading web tenders for details and contact support@msupply.org.nz if you're interested.

Deleting an item from a supplier's quotation

If you wish to delete an item from the quotation, click on the line to highlight it, then click the Delete line button. Note that this action deletes the selected item from the quotation only, not from the tender!

Reference documents tab

This is used for saving documents which refer to the Supplier's quote, not the whole tender - use the Reference documents tab on the Edit tender window to do that (see Reference documents for more details). You might want to use this to save a scanned version of a paper copy of the supplier's quotation, for example.

Upload document button: Click on this to store a document with the quote. You will be shown a window allowing you to browse to the required document. Double-click on the document or click on it and click the Open button to add it to the quote (called “uploading” it). Once it has been successfully uploaded it will appear in the list of documents below the buttons.

Delete document button: Click on a document in the list to select it and click on this button to delete the file and remove it from the quote. You will be asked to confirm the deletion.

Download document button: This will allow you to save one of the files in the list to your computer (called “downloading” it) so that you can view or edit it. Click on the file you want to view or edit to select it in the list then click on the Download document button. You will be shown two options: click on Download to just save the file on your computer or Download and open to save the file on your computer and open it for viewing or editing. A window will open for you to select the location to save the file on your computer. Browse to the folder you want to save it in then either double-click on the folder or click on it to select it then click on the Open button. The file will be saved in the location you chose. If you selected the Download and open option the file will also be opened for you to view or edit.

If you want any edits you make to the document to be saved to the quote, when you have finished editing, you must upload the edited version to the quote using the Upload document button. Don't forget or your edits will only exist on your computer, not on the quote! It is not necessary to change the document's name so that you don't overwrite the original, as mSupply will recognise that changes have been made, and will save it as a new version (and keep the old version too). The file's version number will appear in the Version no column. The Show drop down list above that column allows all versions to be displayed, or only the latest one.

Comments tab

This is used for adding comments from you or the supplier, things that need to be remembered or considered later.

Simply type the comments you want to save in the appropriate box. When you click the OK or OK & Next button the comments (and all other changes to the tender) will be saved.

To view comments saved on the quote, simply view this tab.

Importing responses from a spreadsheet

You can import a supplier's responses to a tender using a spreadsheet. The spreadsheet has a special format and the best way to create it is to export it from the tender. After entering all the items and quantities that the suppliers are to bid on and set the Incoterm for the tender (on the Items and compare Prices tab - see the 18.01. Introduction to tender management page for details), go to the Choose Suppliers and Enter responses tab of the tender:

Click on the To Spreadsheet button and select the Supplier response template option. The spreadsheet will be created and opened for you. It has 3 sheets:

  • sheet 1 contains the tender, supplier and quote information. When you first open the spreadsheet, this sheet contains the details of the items and quantities to bid on only: do not alter them!
  • sheet 2 contains details of all the manufacturers used on sheet 1. Do not alter any of these details.
  • sheet 3 contains details of all the currencies used on sheet 1. Do not alter any of these details.

Sheet 1 looks like this:

Enter the details of the supplier's bid for each item in each row of sheet 1, starting at column I:

Column Mandatory? Title Description
I Mandatory Offered pack size The pack size offered by the supplier for this item
J Mandatory Offered price per pack The price for a pack for this item
K Mandatory Currency The three letter currency code of the price
L Mandatory Expiry Date The expiry date of the stock being offered
M Mandatory Delivery time The number of days between the closing date of the tender and delivery
N Optional Supplier item code The code of the item in the supplier's item catalogue
O Optional Manufacturer name The name of the manufacturer
P Optional Comments Any remarks that the supplier wants to make about this line

If you add new manufacturers or currencies on sheet 1 they will be created for you during the import. You do not need to add them to sheets 2 and 3.

When complete, save the spreadsheet and close it (if you don't close it, mSupply will not be able to open and read it). then double-click on the supplier's name in the list to see the supplier's quotes window:

Click on the Import tender button, select the spreadsheet file and click on the Open button. mSupply will carry out the import and you will see the results in the table in the supplier's quotes window.

After the import, you can still manually edit any of the supplier's quotes by double-clicking on the individual lines, as described in the Entering responses manually section above.

Previous: 18.03. Adding suppliers to a tender and inviting responses | | Next: 18.05. Tender reference documents

18.05. Tender reference documents

Note: If you are using Health Supply Hub for tender submissions, you will have to upload your documents in Health Supply Hub as well. You can read here for more information on uploading documents in Health Supply Hub.

While managing a tender, several documents may be consulted - for example, the quotations received from bidding suppliers, quality assurance documents, or pre-qualification documents. These documents, provided they are in electronic form (or have been scanned into electronic form if they were supplied as paper copies), may be uploaded and conveniently stored so that they may be readily consulted.

To access this functionality, open a tender by choosing Supplier > Show Tenders… from the menus and double-click on the tender you want (or create a new one) to add reference documents to. Finally, click on the Reference documents tab:

Upload document button: Click on this to store a document in the tender. You will be shown a window allowing you to browse to the required document. Double-click on the document or click on it and click the Open button to add it to the tender (called “uploading” it). Once it has been successfully uploaded it will appear in the list of documents below the buttons.

Delete document button: Click on a document in the list to select it and click on this button to delete the file and remove it from the tender. You will be asked to confirm the deletion.

Download document button: This will allow you to save one of the files in the list to your computer (called “downloading” it) so that you can view or edit it. Click on the file you want to view or edit to select it in the list then click on the Download document button. You will be shown two options: click on Download to just save the file on your computer or Download and open to save the file on your computer and open it for viewing or editing. A window will open for you to select the location to save the file on your computer. Browse to the folder you want to save it in then either double-click on the folder or click on it to select it then click on the Open button. The file will be saved in the location you chose. If you selected the Download and open option the file will also be opened for you to view or edit.

If you want any edits you make to the document to be saved to the tender, when you have finished editing, you must upload the edited version to the tender using the Upload document button. Don't forget or your edits will only exist on your computer, not on the tender! It is not necessary to change the document's name so that you don't overwrite the original, as mSupply will recognise that changes have been made, and will save it as a new version (and keep the old version too). The file's version number will appear in the Version no column. The Show drop down list above that column allows all versions to be displayed, or only the latest one.

The ability of users to upload and download documents to and from tenders is covered by permissions. To set these permissions choose the File > Edit users… menu item, double-click on the desired user, and set their permissions on the Permissions(3) tab:

See Managing users if you need more detail.



Previous: 18.04. Adding supplier responses to a tender | | Next: 18.06. Benchmark prices for tenders

18.02. Standard tender conditions

mSupply allows you to set up a list of standard tender conditions called master conditions. These are all the conditions you will apply to tenders from year to year. Each time you create a tender you can copy the master conditions you want to your tender as required - these form the standard conditions list for that one tender. These instructions cover managing master conditions and applying them to individual tenders as standard conditions.

When you print your tender invitation letter, you can choose to have the list of standard conditions print (not all the master conditions!), followed by the list of items for which you are requesting prices.

Setting up conditions and their categories

Choose Suppliers > Show tenders, and open the Master Conditions categories tab

Here you may define categories for your master conditions. Examples shown above are Annual, Supplementary and Emergency. Subsequently you can restrict the display to a single category by selecting that category from the Show drop down list.

Choose Suppliers > Show tenders, and open the Master Conditions List tab:

You can print a master condition selected in the list by clicking on the Print conditions button. To add a new master condition, click on the New Condition button. This window opens:

Point: The conditions will sort by their point entry when printed. We suggest you label your points 1.1, 1.2, 1.3, 2.1, 2.2 etc.

Note that if you have more than 9 points in one of the levels, you should add a leading zero so that they sort properly (01.1, 01.2, etc)

Heading: Enter the Heading.

Body: The body can be as long as you like for each entry.

Category: If you have defined categories, they will be displayed in the drop down list, and you may select the appropriate one.

Flag: Say you have some entries that need changing after copying to an individual tender (e.g. a closing date). You can enter a value in the flag field to identify such entries.

Print heading and body: Use this drop-down list to choose what will print. Normally you'll want to print both heading and body, but near the top of a tender form you may want several headings together.

Click OK & Next to add further conditions.

Editing and deleting conditions

Double-click an entry to edit it.

To delete a condition click on it to highlight it, then click the Delete condition button.

Copying master conditions to a tender

When you enter a new tender, go to the Standard conditions tab.

Click the Copy from master button to copy conditions from the master list

Once you have copied conditions, you can add, edit and delete them in the normal way.

when deleting rows you can highlight multiple rows by holding down the control key (command key on Mac) as you click rows, or press control + A to highlight all rows.

Printing the standard conditions with the invitation letter

To have the standard conditions printed at the end of the suppliers' tender invitation letters, go to the tender's Tender Preferences tab:

In the Acceptance letter section, check the Print tender conditions checkbox. That's it, all done!

Previous: 18.01. Introduction to tender management | | Next: 18.03. Adding suppliers to a tender and inviting responses

18.11. Supplier instructions for submitting tender responses via Excel

Introduction to the tender response template

As a supplier, you may be invited to participate in a tender managed using mSupply. The client may send you a tender response template Excel document in xlsx format, which you are expected to complete and submit for evaluation. This allows the client to import bid responses from multiple suppliers, and easily compare them within the mSupply Tender Module.

You must use Microsoft Excel 2016 or newer to view and edit the tender template.

The tender template will look like this. You can also download a reference template from here: supplier_tender_reference_template.xlsx

The yellow section contains the item that you may bid for. Do not modify any contents of the yellow section.

The blue section is where you can enter the price for the items you wish to bid on.

The Excel template contains three worksheets. Do not modify the name of the worksheets.

  • TenderItems: Main worksheet containing the tender items, as shown above.
  • ManufacturerList: Contains the manufacturers that populate the manufacturer dropdown list in the main worksheet. If a new manufacturer is required, add it directly in the TenderItems worksheet.
  • CurrencyList: Contains the available currencies that populate the currency dropdown list in the main worksheet. If a new currency is required, add it directly in the TenderItems worksheet.

The currency and the manufacturer column should appear as a dropdown list. If this doesn't work, please make sure you are using Microsoft Excel and that the version supports xlsx file format.

Do not change the cell format. If the cell is set to text or number, then it must be left as it is. Changing the cell to a different format will cause issues later with information potentially being lost.

The Excel file has the header row frozen, allowing you to scroll down the list and enter data while still being able to view the corresponding header.

Completing the tender response template

Fields

More detailed information regarding the tender template fields is described below.

Serial number Column Field Description
1 1(D) Organization name Pre-filled. Displays the mSupply store's organization, cannot be changed.
2 2(D) Supplier code Pre-filled. Cannot be changed.
3 3(D) Supplier Name Pre-filled. Cannot be changed.
4 4(D) Supplier ID Pre-filled. Cannot be changed.
5 5(D) Tender ID Pre-filled. Cannot be changed.
6 10(A) Internal Line ID Pre-filled. Cannot be changed.
7 10(B) Line # Pre-filled. Cannot be changed.
8 10(C) Item Code# Pre-filled. Fixed by the tender, cannot be changed.
9 10(D) Item Name Pre-filled. Fixed by the tender, cannot be changed.
10 10(E) Requested Number of Packs Pre-filled. Cannot be changed. 30 alphanumeric characters.
11 10(F) Requested Pack size Pre-filled. Cannot be changed.
12 10(G) Requested Total Qty Pre-filled. Cannot be changed.
13 10(H) Units Pre-filled. The unit the quantity is measured in e.g. tablet, mL, g, bottle, vial, ampoule
14 10(I) Offered Pack Size Mandatory. Number greater than zero (default = 1).
The pack size (number of units in one pack) you are offering.
15 10(J) Offered Price per Pack
[DAT - Deliver at Terminal] 		Mandatory. The price you are offering for each pack.
16 10(K) Currency Mandatory. The currency of the quoted price.
Choose the required currency from the dropdown list.
If the currency does not exist, enter the new currency here manually.
17 10(L) Expiry Date Mandatory. Expiry date of the quoted product, which can be a specific date or an expiry from delivery (e.g. 12 months). This field can be plain text.
18 10(M) Delivery Time Mandatory. Estimated time between the goods leaving the supplier’s premises and delivery to the customer (.e.g. 5 months).
19 10(N) Supplier Item Code Optional. Your supplier item code, if any.
20 10(O) Manufacture Name Optional. Choose the required manufacturer from the dropdown list.
If the currency does not exist, enter the new manufacturer here manually.
21 10(P) Comments Optional. Enter any comments that should be considered in the evaluation process (e.g. brand provided, quote only applicable if all needle sizes are awarded etc.).
Currency

This specifies the currency for your quote, which is set for each item. Select an available currency from the dropdown list.

If the required currency is missing, it means the client has never handled this currency in mSupply before. You may enter the new currency in this column using the appropriate three letter abbreviation from this link:Currency Abbreviation.

The example above shows Canadian Dollars (CAD) is being quoted for this item. Excel will alert you that this is a new currency. Click OK to continue with the new currency.

On your next tender with the same client, your currency of choice should already be present on the spreadsheet.

Manufacturer

This specifies the manufacturer for your quoted item. Select an available manufacturer from the dropdown list. Typing the first few letters will show a list of matching manufacturers.

If the required manufacturer is missing, it means the client has never recorded goods from this manufacturer in mSupply before. You may enter the new manufacturer in this column. Excel will alert you that this is a new manufacturer. Click OK to continue with the new manufacturer.

On your next tender with the same client, the newly added manufacturer should already be present on the spreadsheet.

Tender response rules

If you choose not to bid for an item: Leave the blue section for that row blank. Do not delete lines.

If you wish to make multiple bids for the same item: Copy and paste the entire row. Ensure all the fields in the yellow area remain unedited. Enter your bids in the blue section.

If you wish to rearrange the items: Rows do not need to be in any particular order. You can rearrange the spreadsheet as required. Ensure all the fields in the yellow area remain unedited.

Tender submission

After entering your bids, save the Excel spreadsheet (xlsx file) and email it to the client as guided.

18.09. Supplier instructions for using tender submission web interface

Introduction

This user guide explains how to use the web site at https://tenders.msupply.org.nz that is used by mSupply users to publish tenders. It is only relevant if you are a supplier who has been invited to tender by a user of this system. If you have been invited to tender and have questions that are not answered in this document, you may request support by emailing tender_support@msupply.org.nz.

  • Save the login credentials. The login credential for the website does not change. Once received, it is the responsibility of the supplier to securely save or note down the login credential for future tender participation.
  • Don't wait until the last minute. Many suppliers have left the entry of tender till the last moment, not followed instructions correctly, and bombarded Sustainable Solutions with support requests during the last 24 hours of the tender closing. Please do not do this.
    • Please carry out a dummy run of entering lines and saving. You can change your entries later before finalising the tender. This will allow you learn how the system works without the pressure of a submission deadline.
    • If you choose to populate the tender with an uploaded file, that too should be tried out in advance and not left till the last moment. The instructions need to be followed carefully. - Refer Uploading prices.

How it works - a summary

  1. The Client prepares tender documents and distributes them by email to suppliers.
  2. Each Supplier receives details, including a username and password, for accessing the secure website where the tender is to be found.
  3. The password provided is valid only for the first time the website is accessed, so the supplier’s first action will be to change it.
  4. During the period between receiving the tender document and the tender’s deadline, the supplier decides on the bids to be submitted, and enters the details on line. This may be done over multiple sessions.
  5. Before the deadline, the supplier finalises the bid; this action is not reversible and prevents any further changes being made. The status is changed from “SG” (suggested) to “FN” (finalised).
  6. Once the deadline has passed, the client will access all quotations which have been finalised, evaluate them, and notify successful suppliers.

How it benefits suppliers

  • Accuracy: you can be confident that the information entered by you will be accurately transferred. Manual systems are prone to transcription errors in the price, pack size, currency, etc.
  • Speed: while the tender process may be slightly slower for the supplier, the time between tender closing and bid evaluation is dropped from weeks to one or two days. This means tender closing dates can be moved closer to the date on which suppliers are notified of winning bids, benefiting all involved.

Costs

  • There is no charge to suppliers to use the system. Development and maintenance costs are covered by software support contracts with mSupply users.
  • Due to a steady stream of requests for help for issues that are covered in this guide, or issues that are not a system issue (e.g. password reset requests and requests for help with uploading bids where the instructions for formatting the file to be uploaded have not been followed), we will charge for support requests if it relates to such issues.

Security

  • We take the security of this module seriously.
  • Only https (secure) website access is allowed: observe the closed padlock icon in the corner of your browser. This means that no-one can read the interactions between you and the tender server.
  • Automatic disconnection: should there be no activity after a short time, you are required to confirm that you are still working on the website. In the absence of such confirmation you are disconnected and the login screen reappears.
  • One-time password: the password provided for the first time you access the website is valid only for that first occasion. You must change it to a password of your own choosing for continued access to the website.
  • The server running the Tender Management System is managed by Sustainable Solutions and is accessible by us alone. We know this system will only be successful if we maintain the highest standards of ethical, impartial behaviour and keep your data secure and accessible only to authorised parties.
  • Restricted access by IP address: if you wish to limit access to your online account to users within your office, let us know an IP address or subnet that you will use and we will put this restriction in place until you instruct us to remove it.
  • We track the IP address of all log on attempts. Repeated attempts from the same IP address will be blocked.
  • We have coded the software carefully to ensure that supplier information entered is only available to that supplier and to the customer (obviously once the customer downloads the submitted bids, we can not control the information flows outside of our system).
  • All emails sent by the tender module are sent by SSL (Secure Socket Layer) for added security.

First logon

Log on to https://tenders.msupply.org.nz and this is the window which appears when you log on

You should enter your supplier code and password, both of which were sent to you by email.

You will immediately be shown the window for changing your password:

In the Old Password field you should enter the password sent to you by email. You must then enter a password of your own in the New Password field, re-entering it in the Confirm Password field; when you have done this, and clicked on OK, the standard log on window appears again, and you should enter your user name and the password which you have just created. You will now be logged on to the system, and these are the details you will use for logging on in future..

Note that the web site uses a large Javascript library, so will take a few moments to load the first time you use it. In return you get a fast and easy-to-use interface.

If you have chosen to do so in the preferences, each time you log in, you will be sent an email saying that you logged in to the web interface - this means if someone else was to log in to your account, you would know about it.

Staying logged on

If no user activity is detected for a few minutes, as a precautionary measure to restrict unauthorised access, a window appears. You need to click Keep Working, otherwise you will be logged out.

Once you have logged on, you will be shown a list of tenders for which you have been invited to submit quotations.

The example shows that 4 tender documents from client Namaste Medical Stores, have been uploaded and await the supplier’s attention.

My Information button

Clicking the My Information button displays this window:

This is where the supplier’s details held on the server are entered and stored, and this is also where they can be edited. Those details include name, address, contact details, and the default currency for this supplier.

Default currency The default currency is that currency in which the you normally supply quotations - in the example shown, it is Singapore dollars, and this will normally remain unchanged for a particular supplier; suppliers located in another country are likely to use their own country’s currency as their default one.. In the case where a supplier submits a quotation with one or more lines quoted in another currency - e.g. Euros or US dollars - the particular currency used is entered on the appropriate line of the quotation Note that changing your default currency will affect new quotations, and won’t have any affect on existing quotations.

Inactivity time This is the length of time in minutes after which you will be logged out if there is no activity. 10 minutes is the default but you can choose from between 1 and 60 minutes.

Email me manufacturer list As the name suggests, this will email an Excel file with the complete list of manufacturer names and their corresponding codes to the email address specified. If you want to take advantage of the new facility to upload a quotation as an Excel file, you will need to use the manufacturer codes specified in this list.

Manufacturer List

Saving your settings and closing the window Click the OK to update button to save your settings. Click on the close box in the top right of the window to close it when you are finished.

Viewing the tender list and individual tenders

The window which appears when you log on is the Current Tender List, and it shows all of the tenders for which the supplier has been invited to submit a quotation; it also shows the status of the tender, which is set to SG (= suggested), and should remain at this status until all work has been completed, and the quotation is ready to be finalised. Access to a particular tender document is achieved by double clicking on the line. The tender and the items involved in it are then displayed in a window which looks similar to the following:

Description: This is the description or title of the tender. Use this whenever you refer to the tender so that everyone knows you're talking about the same one!

Customer: This is the name of the organisation who created and published the tender and then invited you to respond to it.

Currencies drop down list and Set currencies icon: This sets the default currency for your quote. Use the set currencies icon to change the currency for all items currently entered. If you struggle to find the correct currency, type the first letter of the one you want and you will be taken to the first currency beginning with that letter. The list is in alphabetical order so it should make it easier to find.

Show button: displays the whole of the customer's comment if they've entered one. May contain useful information for you.

Edit button: Displays a window to enable you to enter or edit a longer tender comment for the customer (the one who invited you to tender). Any information you want to convey to the customer about your quotes can be put in here. Note: you also have the opportunity to enter comments on individual quote lines. See Entering prices section below.

Duplicate button: Duplicates a selected quote line. Will put the new quote line at the top of the quote. Helpful if you want to enter a quote for the same item but with slightly different details. If you need to do this for many items, use the Upload button mentioned below.

Show totals button: Shows the total value of your quote for each currency you've included in your quote.

Reset lines button: Removes any changes you have made to the selected quote lines.

Email me this quote button: Sends you a copy of your quote as it currently stands. It will be sent to you as Excel file attachment to an email.

Email me a quote template button: Sends you a copy of the tender with all items included with no price or other information added. This is the perfect thing to use as a base for your quote if you are going to create it in a spreadsheet and upload it using the upload button (see below).

Browse button: Allows you to select an Excel file to upload as your quote.

Upload button: Uploads the selected Excel file as your quote (see the Uploading prices section below).

Entering prices

To enter the details for a line, double click on the line.

Details should be entered in each of the columns:

Item code, name and quantity These are fixed by the tender and cannot be changed.

Pack size The pack size requested by the customer is already on the form; if needed, it can be changed.

Price per pack The unit price of the pack you are offering to supply in the chosen currency.

Cost Including Freight (CIB): The quoted price should include international freight charges.

Expiry date and delivery time When completing these fields, it is suggested that a series of abbreviations be used:

  • min = minimum
  • max = maximum
  • w = week
  • m = month
  • y = year
  • So for example, if you want to indicate a delivery time of 3 months, enter “3m”

Delivery times should be specified from when you receive the purchase order, so must also include the time for order compilation by the supplier

The tender document is likely to specify minimum expiry dates, but it is important that there should be no misunderstandings. Delivery time is understood to mean the estimated period of time between the consignment leaving the supplier’s premises and delivery to the customer.

Currency: The relevant currency should be selected from the drop down list - it doesn't have to be the same as the default currency. If you're struggling to find the right currency from the list, type the first one or 2 letters of the currency you want - should make it easier to find.

Manufacturer: The name of the manufacturer should be chosen from the drop-down list. Typing the first few characters of the manufacturer's name will show a list of matching manufacturers. Click to select one.

Manufacturers are not linked to suppliers in our system, so multiple suppliers who source goods from the one manufacturer do not cause a problem.

Problems saving entered data ? : Simply entering price and saving is not sufficient. The website will not save the row of data. The Manufacturer column must also be filled with a valid manufacture. If you choose to not to specify a manufacture then simply choose : “Not Specified” as the options.

Adding new manufacturers into the tender module

Due to the desire of mSupply users to collate manufacturer data, you cannot enter manufacturer names yourself. If you want to have a manufacturer added to the list, please email to tender_support@msupply.org.nz and we will add the name(s) within 24 hours.

Please submit Manufacturers in the following manner:

The country where the manufacturer is based must be specified. The address column is optional.

If you have more than 5 manufacturers to add then it may be worth creating and a spreadsheet with the column headings described below, then sending to us as an attachment:

Manufacturer Country Address (optional)
John Western Pharmaceutical US 32 Obama Road, Virginia
Jürgen Klinsmann Group Germany Göppingen, West Germany
Universal Supplies Great Britain

If you do not want to or cannot specify the manufacturer, choose the entry 'Not specified' from the list. You may wish to add a comment to that quote line to explain your entry. Alternatively you can specify the manufacturer in the comment column if the manufacturer is not in the list provided and if you have run out of time for the manufacturer list to be updated.

Country of Origin: Some tenders require you to specify country of origin instead of manufacturer. Common countries are specified in the Manufacturer list, so you can just choose a country rather than a specific manufacturer if you wish.

Comment: Use this column for entering any comment or note you may wish.

Once you have made all the entries for a row, click Save to update the tender document with the details you have entered. It is quite possible that you will not have all the necessary information to complete a tender document at a single session; this is not a problem - just close the document at the stage you have reached and later, once you have the further information you require, reopen the document and continue with the process.

Submitting multiple quotations for the one item If you wish to do this, then select the line you wish to submit a second (or third) price for and click the 'Duplicate' button in the toolbar. Fill in the details of the second quotation.

Tender conditions Some tenders may have more restrictive conditions than the web site allows for. For example, a tender may specify only one currency, or that multiple quotations for the same item are not allowed. Currently the web site will NOT reflect such conditions, and it is your job to read the tender conditions and respond accordingly.

Uploading prices

This facility allows you to upload an *.xlsx file containing a header line and one or more item lines for your quotation. The template for the *.xlsx spreadsheet is provided with your invitation to tender.

As of August 2019, spreadsheets are now provided and to be uploaded in *.xlsx format.
You can use Microsoft Office or the Free Libre Office.

Preparing the quotation file

You can download a suitable template for your quotation file by clicking the 'Email me a quote template' button on the top-right of the tender items window. This file will have the first four columns pre-filled for your convenience and is the best way to start if you intend to upload your quotes.

The file should be in *.xlsx format, having the following 10 columns:

  • Item code
  • Item name
  • Quantity
  • Pack size [Must be number, not words like “each”, “box”..etc ]
  • Currency (in 3 letters international code format: e.g. AUD USD EUR )
  • Price per pack
  • Expiry date
  • Delivery time
  • Manufacturer code (as per the manufacturer code list you can download from the “My info” button when logged in)
  • Comments



Please note:

  1. The Item Name and Quantity columns are only included for the sake of human readability, and will be ignored
  2. This table uses the manufacturers code rather than the manufacturers name (the code is shorter so less likely to make mistakes)
  3. You can download a manufacturer list of names and codes from the 'My information' page (see the 'My Information button' section above)
Uploading the quotation file

First of all, you need to select the file that you wish to upload by using the Browse button on the far right of the tender items window. The selected filename will then be visible in the text field to its left. Then click on the Upload button and you will be presented with the following window:

Update existing quote lines: Select this if you want the contents of the file to update quote lines already in the tender. Note that information will only be updated for items in the tender where the current price for the line is 0. If a line in the tender has a non-zero price any line in the file with details for that item will be ignored. So, if you want item lines to be updated by the contents of the file reset their prices to 0 before you carry out the upload. Note also that if there is more than one matching zero-price tender item line with the same item code, then it will select the first match it comes to i.e. the system will cope with multiple quote lines for the same item. Therefore, if you want to upload multiple lines for an item, you need to duplicate that line in the tender first (using the Duplicate button on the toolbar) before uploading the file.

Replace existing quote lines: Select this if you want the contents of the file to replace everything already in the tender. All your existing lines will be deleted from the tender and the contents of the upload file will be entered into the tender. Note that if there are multiple lines in your upload file with the same item code this method will put them all into the tender. This is helpful if you keep your Excel file as a master copy and use it to update your quotes. And also means that you can easily input multiple quotes for the same item (with different pack sizes or manufacturers, for instance - but mSupply won't check so the multiple lines could be identical if you wish).

Click on the Cancel button to cancel the upload or the OK button to continue.

Having clicked on the OK button you will, after a short while, get a confirmation that the upload was successful and the list of displayed tender items will be updated to reflect the data that has just been uploaded.

Please note the following points regarding the file upload process:

  • Only Excel files (extension of '.xlsx') smaller than 1Mb are accepted.
  • Currently, the only web browsers which fully support file upload are Firefox and Chrome. The next versions of Safari and Opera are also planned to include support for this new HTML5 feature.
  • A successful upload message does NOT imply that the contents of the file are valid, simply that it has been processed. An email will be sent to your email address, with two attachments:
    • A text file which contains the output generated from the upload process i.e. the number of records which were successfully processed, and any error messages generated during the upload process.
    • An Excel file in the same format as produced by the 'Email me this quote' button, which will include the updated tender items - you should check that this reflects the changes you are expecting.
  • Any blank lines in the uploaded file will be ignored.
  • Any lines which do not contain the expected number of columns, or with data in the wrong format will generate an error message and will not be imported.
  • Any lines with an invalid item code or an invalid currency code will generate an error message and will not be imported. We use the standard 3-character currency codes - see here for a complete list.
  • Any lines with an invalid manufacturer code will still be imported but will be given a manufacturer of 'Not specified'.

Note also that it is possible to perform as many file uploads as you like.

Finalising a tender

  • Firstly, be warned: Finalising means exactly that. It can not be undone.
  • Only when you are satisfied that you have completed the details on all the lines for which you are quoting should you finalise your tender entry.
Email it to yourself first

We strongly recommend you use the button in the tender window to email yourself the tender, and then check that the entries in the online tender module match your intended entries.

To email a quotation to yourself, open the tender your wish to email, and then click the “Email it to me” button at the top-right of the window.

What finalising does

Clicking on Finalise does two things:

  1. It locks the tender document, changing its status to FN (finalised) and you can make no further changes to it.
  2. It makes the finalised tender submission accessible to the customer once the tender has closed. Only finalised quotations will be accepted by the customer.

Finalising the tender submission, therefore, must be performed before the closing date as specified by the customer.

How to finalise
  1. You need to be viewing the list of tenders, not the particular tender you have just entered.
    1. If you are not logged in: Log in and you will be shown the list
    2. If you are editing your tender, close it to return to the list of tenders.
  2. Check the checkbox in the left-hand column next to the tender you have completed
  3. Click on the Finalise button.
  4. You're done

Closing date and time

Note that closing date and time is specified as GMT (Greenwich Mean Time). This is NOT likely to be the same as your local time. Please take this into account when planning for when you will finalise your prices.

Results notification

The client will notify successful suppliers directly by submission of a purchase order. The web site will not show you any information about you or any other supplier’s success or otherwise

Obtaining support

Please email tender_support@msupply.org.nz if you have any problems. We are based in Nepal, but provide support 18 hours per day Monday to Friday while there are open tenders in the system.

Note that you should only communicate with us regarding technical matters. For all matters relating to tender conditions, pricing, etc., communicate directly with the client who published the tender.

The future

  • We hope you appreciate both the concept and the hard work we’ve put into making this system work for both clients and suppliers.
  • The system is used by several mSupply users, and is being taken up by more each year.
  • We have lots of our own ideas on how to improve the system, and we’d love to hear your criticisms, compliments or ideas as well. Use the email address above.

Warranty

There is none. Our software is provided “as is”. We take the responsibility to act fairly and carefully very seriously. We are replacing manual systems that are prone to gross errors, so even when our system experiences the odd (very rare) issue, it remains a vast improvement on what has gone before.

Infrequently asked questions

  • Q: What if your server failed just before a tender closed.
    • A: Our advice is: This isn’t an auction. There is no need to submit at the last minute. However, if there was more than a few minutes of downtime in the last 24 hours of a tender, we would ask the customer's permission to extend the closing date. Also, our server has been running for several months. Should the tender module prove popular we will transfer it to a data centre.
  • Q: Can we phone you for support.
    • A: Yes. But, if your question relates to issues that are explained in this document, we reserve the right to charge you for our time. (This includes the resetting of passwords which we have supplied in the past).
      • Nepal: +977 1 5548021
      • New Zealand: +64 22 519 0499

Thanks

Thanks to the staff of Republic of Kiribati’s Ministry of Health & Medical Services Pharmacy Department who pioneered the use of this feature! :-)

Previous: 18.08. Tender currencies | | Next: 18.10. Using web tenders

18.10. Using web tenders

NOTE: This page details the process for using our remote tender module. This module is being replaced by our new Health Supply Hub. See the Health Supply Hub Documentation Website for more details.

A web tender is one that is uploaded to our Health Supply Hub server and is made accessible to suppliers for them to enter their responses remotely. This greatly reduces the load on you to input all the responses from all suppliers and means there will be far less chance of data entry errors.

A tender cannot be deleted when it has been uploaded to the Health Supply Hub.

Setup

To use web tenders, there are several setup steps that only need to be done once:

  1. Contact The mSupply Foundation to arrange a user account. We'll send you your account details.
  2. In File > Preferences…, on the Tender tab, enter the account details Sustainable Solutions sent you. See 16.01. General preferences for details.
  3. Link each of your suppliers with the Supplier's master record on the tender web site. For further information see the 5.01. Names: using, adding and editing page.
  4. Tell Sustainable Solutions about any of your suppliers that are not in the Health Supply Hub list. We will then add them, and you can link the remaining suppliers.

The process

The following steps describe the whole remote tender process:

  1. Carry out the setup steps given above.
  2. In mSupply, create a new tender.
  3. Set up tender name, reference number, opening and closing date.
  4. Add items to the tender. Make sure you add a quantity and pack size for each item.
  5. Add suppliers to the tender.
  6. Go to the Synchronise tab on the tender details window and click on the Upload tender to web site button to upload the tender to the tender server. You will be given an error message if the upload is not successful. Note: any lines that have 0 quantity (possible with certain options when automatically generating a tender) will not be uploaded to the Health Supply Hub but you will be told that there are some before the upload takes place so you can fix or remove them before the upload if you wish. Also, after successful upload a tender will be changed to confirmed status (if it has not already been changed to this) so that items and quantities cannot be changed. If you get stuck, contact The mSupply Foundation for further assistance. For a tender to upload successfully:
    • Each supplier must be linked. You will be warned if they aren't.
    • You must have set a Response by date (see the 18.01. Introduction to tender management page). If it is not set you will be told to set it before you can upload the tender.
    • Your internet connection must be working.
    • You must have entered the user name and password correctly in the tender preferences (see above).
  7. Note: When a tender has been uploaded to the Health Supply Hub, it will appear in DRAFT status so that you can review it before finally publishing it.
  8. Inform suppliers by sending physical or electronic tender documents (both can come from mSupply) and send them a link to the Supplier instructions for using the tender submission web interface
  9. The suppliers enter their bids into their part of the remote tender server web site.
  10. After the tender has closed, download the tender by going to the Synchronise tab on the tender details window and clicking on the Download tender from web site button.You will be given an error message if the download is not successful. If necessary, mSupply will download from the Health Supply Hub the suppliers and manufacturers that are used in the tender responses that are not in mSupply. Progress bars will show you progress that has been made through the process. If you get stuck, contact Sustainable Solutions for further assistance. For a tender to download successfully:
    • Your internet connection must be working.
    • The tender closing date must have passed.
    • Suppliers must have confirmed their quotes in the Health Supply Hub.
    • If you're using the Health Supply Hub governance workflow then the tender must be unlocked by a user who is authorised to do so.
    • Please note that it is possible to redownload a tender again if changes have been made to it. All appropriate fields and responses will be updated or added if they have been edited or added since the last download (including submission dates etc.).
  11. Compare prices and print appropriate reports for the tender committee or others.
  12. Award each item to a supplier.
  13. Create purchase orders.
  14. Send the purchase orders to the suppliers.
  15. Sit back, relax and give yourself a pat on the back. Nice going.

Uploading the tender is final…

mSupply records when a tender has been uploaded, and will no longer allow the editing or deletion of tender lines on that tender. So make sure your tender is correct and complete before you upload it!

A note about currencies

If a quote from a supplier in the Health Supply Hub uses a currency that doesn't exist in mSupply, when you try to download the tender to mSupply you will be shown an error and the download will fail.

The way to correct the problem is to add the currencies that are shown in the error message to mSupply and then try the download again. For information on adding currencies to mSupply, see the 26.10. Currencies page.

After uploading the tender to the Health Supply Hub

When the tender has been uploaded to the Health Supply Hub it can be easily viewed by clicking on the View on HSH button seen on the Items and compare prices tab as shown below:

The button will be visible as soon as you have entered the remote server details in the preferences (see step 2 in the Setup section above). If you click it before the tender has been uploaded a message will be shown telling you that this is the case.

Previous: 18.09. Supplier instructions for using tender submission web interface | | Next: 19. Remote User Web Interface

19.10. mSupply legacy REST APIs

What is it?

This document describes an application programming interface for communicating with mSupply.

Basics

  • Communication is over HTTP protocol
  • All data is submitted and returned as JSON
  • HTTPS supported- you should use it. If you want to restrict to only HTTPS, then block the HTTP port mSupply is using on your router.

Authentication

  • All requests must have standard HTTP basic authentication headers
  • You must use SSL to secure your communications unless you want to tell the world your password.

GET - Getting data from mSupply

For all calls
  • The basic syntax 
  • http://server_ip_address/type/resource/id_of_resource
e.g. http://example.com/mobile/name/524
will retrieve the complete record for name whose ID=524
  • or
    http://server_ip_address/resource?field=blah,field2=blah2&sortby=+foo,-bar 
e.g. http://example.com/mobile/name?name=foo@,customer=true&sortby=+name
will retrieve all names whose name starts with "foo" and who are customers, sorted by name in ascending order (a to z)

Note that a "/" is also allowed before the "?" in the URL e.g. http://example.com/mobile/name/?name=foo@,customer=true&sortby=+name
  • Method: GET
  • Note that all price data will be returned rounded to 2 decimal places.
Paging
  • If you want a range of items, pass an HTTP header named “range” with a “from” and “to” value separated with a hyphen. See the following example to find out the right format for the “range” header.
    • e.g. to return the first 15 items: 
      range  bytes=1-15
    • The server will reply with a header containing the item range and the total number of items found: 
       items 1-15/568
Query notes
  • For string searches you can use “@” as a wildcard, as in the example above
    • ?name=@foo@ will return all names containing “foo”
    • ?name=foo@bah will return all names starting with “foo” and ending with “bah”
  • Allowed query operators are:
    • =
    • # (not equal to)
    • >=
    • <=
    • <
    • >
  • A query operator must be followed by a query value
  • All resources returned are first filtered by the server to only return valid results for the store the user is logged in to.
    • Transactions: only transactions created in that store
    • Items: only items visible in that store
    • Customers (names): only names visible in that store
    • More on stores here
    • There is a full list of field names here but note that as of Wednesday 31 October 2012 they haven't been updated for mSupply v3.2
Available resources
mobile/Items
Resource name item
Fields you can query any
Returns by default JSON array containing: id
code
item_name
stock_on_hand_tot
When a single item ID is requested department
category
category2
stock_on_hand
stock_available
An array with a key of “lines” containing pack_size, available_quantity, batch, expiry_date, sell_price
mobile/Transactions
Resource name transaction
Fields you can query any
Returns a JSON array containing: id
name (i.e. the name of the customer/supplier the transaction is to/from)
entry_date
confirm_date
status (a two letter code denoting the status of the transaction)
comment (the user-entered comment)
If you only request a single ID (e.g example.com/mobile/transaction/558 A JSON object containing every field for that record
Special case one:
Getting An ID to use when submitting a new transaction; submit example.com/mobile/transaction/new_id Returns: 		JSON object containing: new_transaction_id
mobile/Names
Resource name name (a name can be a customer, a supplier, a manufacturer or a donor or a combination of these)
Fields you can query any
Returns by default JSON array containing id
code
name
bill_address1
mobile/Invoice
Resource name: invoice
Fields you can query none. Just call the ID number like this 
http://example.com/mobile/invoice/578
Returns by default JSON array containing id
name_id
name_name (The actual name of the customer or supplier)
total
their_ref
type
entry_date
confirm_date
comment
entered_by (username not ID)
store (name not ID)
hold
lines: contains an array containing the lines on the invoice. Each array row contains:
item_id
item_name
quantity (no. of individual items i.e. pack size x quantity in a pack)
stock:
contains an array of all stock lines used on the invoice, and also any other stock lines for items on the invoice whose quantity is greater than zero. This means that for a “normal” invoice line editing operation (where you are not changing the item) you already have all the information that you need without a further call to the REST server when a line is edited)
Example 
{
  "id" : 587,
  "name_id" : 79,
  "invoice_num" : 256,
  "status" : "fn",
  "total" : 824.5,
  "their_ref" : "GIZ05",
  "type" : "ci",
  "entry_date" : "2012-09-30",
  "confirm_date" : "2012-10-30",
  "name_name" : "ZIGO HOSPITAL",
  "lines" : [ {
    "id" : 6396,
    "item_key" : 973,
    "item_line_key" : 960,
    "item_name" : "CLOXACILLIN TABS 250MG BOT/1000",
    "quantity" : 5,
    "pack_size" : 1000,
    "sell_price" : 161.61,
    "price_extension" : 808.05
  }, {
    "id" : 6397,
    "item_key" : 120,
    "item_line_key" : 14,
    "item_name" : "ATENOLOL TABLETS 50MG BOT/100",
    "quantity" : 5,
    "pack_size" : 100,
    "sell_price" : 3.29,
    "price_extension" : 16.45
  } ],
  "stock" : [ {
    "id" : 22126,
    "quantity" : 162,
    "batch" : "AD 1002",
    "expiry_date" : "2014-09-30",
    "pack_size" : 1000,
    "sell_price" : 147.09
  }, {
    "id" : 22307,
    "quantity" : 12,
    "batch" : "3026844",
    "expiry_date" : "2014-03-30",
    "pack_size" : 1000,
    "sell_price" : 139.3
  } ]
}
mobile/Stock
Resource name stock
Fields you can query any in the items table or for all the items of a particular invoice with the field “trans_id”
Typically, having located an item to add to an invoice you will want to locate the total stock available for that item 
http://example.com/mobile/stock?ID=123 // stock for item.ID 123


http://example.com/mobile/stock?trans_id=123 // stock for transaction.ID 123
Returned: an array of match records containing the item ID and the total stock quanitity like this 
[ {
  "id" : 5265,
  "quantity" : 30,
}, {
  "id" : 5275,
  "quantity" : 100,
}, {
  "id" : 5274,
  "quantity" : 50,
}
]
Stocktakes
Resource name stocktake
Fields you can query any
Fields returned from a query ID
description
stocktake created date
status
You can filter on type of stocktake by querying the status e.g. 
http://example.com/mobile/stocktake?status=sg
Requesting a particular stocktake returns the following fields for the stocktake itself description
stocktake created date
stocktake entered date
status
comment
An array whose key is “lines” containing an these fields for each item in the stocktake:
item code
item name
quantity (the pack size is assumed to be one)
snapshot quantity
Example the following request would return the information for the stocktake with an id of 123: 
http://example.com/mobile/stocktake/123
Special Case: Creating a stocktake First you need to get a stocktake id that you can use by requesting the resource “new_id” 
http://127.0.0.1:8081/stocktake/new_id

A note on creating stocktakes: the recommended process is:

  1. Get a new stocktake id
  2. Get items- this will also return the current stock on hand.
  3. Display this, along with a column for the user to enter current stock on hand
  4. When ready to save, post the data (below). Wasn't so hard!
Categories

Use this resource to return lists of different types of categories in mSupply.

Resource name category
Fields you can query any
Fields returned from a query id - the id of this category (unique only among categories of the same level)
description - the descriptive name of the category
type - the category's type. Can be one of 1level1, 1level2, 1level3, 2 or 3
parent_id - the id of the category which is the parent of this one. 0 means the category has no parent
You can filter on type of category by querying the type (which can take the values “item”, purchase_order“, “transaction” and “name”) The following query will return all the categories for items 
http://example.com/mobile/category?type=item
catalogue/Catalogue Items
Resource name catalogueItem
First URI segment catalogue
Fields you can query any
Fields returned from a query for each item id - the item's unique id code
Item - the item's code
item_name - the item's descriptive name
indic_price - the catalogue price of the item
description - the lowest level category (category 1, level 3) that the item belongs to
units - the units the item is provided in e.g. Amp (ampule)
Tab (tablet), report_quantity - the pack size of the item in the catalogue, e.g. the following query would return all items with an id greater than -1 and a name beginning with “a”

* You can filter on the category that items belong to by querying the category number and level. There are 3 categories (1-3) but please note that category 1 is hierarchical; it has 3 levels - level 1 is the parent, level 2 categories are children of level 1s and level 3 categories are children of level 2s. So, altogether you can query category1level1id, category1level2id, category1level3id, category2id and category3id. Note that all queries by category will return items that belong to that category and those which belong to all its child categories e.g. this query will return all items assigned to the level 2 category 1 which has an id of 4 and all items belonging to category 1 level 3 categories that are children of it:

Example 
http://example.com/catalogue/catalogueItem?category1level2id=4
Customer Stock History Items
Resource name customerstockhistory
Fields you can query any
Fields returned from a mulitple query id, date_entered
Fields returned from a single id id, date_entered,stock_take_date, lines (array)
The lines object array contains:
id (the id of the line, [name_s_h_line]id)
item_id (the id of the item, [name_s_h_line]item_id)
item_name (the name of the item - [item]item_name using [name_s_h_line]item_id)
item_code ([item]code using [name_s_h_line]item_id)
store_stock (the amount of stock (number of items not
packs) the supplying store has of this item)
stock_on_hand (the stock on hand entered by the user, [name_s_h_line]stock_on_hand)
usage (this store's daily usage of this item. Calculated as (stock on hand last stocktake + stock received last stocktake - stock on hand this stocktake)/number of days between this and the previous stocktake. Use new [name_s_h_line]previous_stock_on_hand and [name_s_h_line]previous_received_from_us fields in the calculation)
comment (the line's comment - [name_s_h_line]comment)
Version
Resource name version
Fields you can query none
Returned the current mSupply mobile version
Example: 
http://example.com/mobile/version
mobile/masterlist
Resource name masterlist
Fields you can query name_id, type (the type of list to return)
Returned JSON containing the items for the associated masterlist belonging to the name of the specified type
Example 
http://example.com/mobile/masterlist/name_id="123"&type=weborder
Settings
Resource name settings
Fields you can query none. Precisely.
Returned A JSON object with three entities: timeout, name_id, name- This is the id and name of the customer or supplier or store
Example 
http://example.com/mobile/settings
mobile/Purchase orders
Resource name po
Fields you can query id
Returned JSON containing the Purchase Order details for the ID you queried
Example 
http://example.com/mobile/po/id="123"
Reports
Resource name report
Query type with one of three options: type=currentstock or type=expiringstock or type=orderedvsreceived
Query parameters type=currentstock: none
type=expiringstock&nummonths=xx where nummonths is the number of months in advance of the current date to compare expiry dates with
type=orderedvsreceived&from=yyyymmdd&to=yyyymmdd where the from and to dates in yymmdd format are entered.
Returned JSON containing the “Successfully sent” or any errors encounters
Example 
http://example.com/mobile/report/type=currentstock
Patients
Resource name patient
Query parameters first_name: first name of patient
last_name: last name of patient
dob: patient date of birth (DD:MM:YY)
policy_number: patient insurance policy number
Returned JSON array of patient objects matching query parameters: 
[{
  "ID":,
  "name",
  "phone",
  "customer",
  "bill_address1",
  "supplier",
  "email",
  "code",
  "last", 
  "first",
  "date_of_birth",
  "type",
  "manufacturer",
  "bill_address3",
  "bill_address4",
  "bill_postal_zip_code",
  "supplying_store_id",
  "nameNotes": ["note1","note2", ...],
  "nameInsuranceJoin": [{ 
    "ID",
    "insuranceProviderID",
    "nameID",
    "isActive",
    "policyNumberFamily", 
    "policyNumberPerson", 
    "type", 
    "discountRate",
    "expiryDate",
    "policyNumberFull",
    "enteredByID" }, ... ],
 }, ... ]
Example 
http://example.com/api/v4/patient?first_name=j@&last_name=doe&dob=01/01/1960
Prescribers
Resource name prescriber
Query parameters first_name: first name of prescriber
last_name: last name of prescriber
code: prescriber code
Returned JSON array of prescriber objects matching query parameters: 
[{
   "ID",
   "code",
   "first_name",
   "last_name",
   "initials",
   "registration_code",
   "category",
   "address1",
   "address2",
   "phone",
   "mobile",
   "email",
   "female",
   "active",
   "store_ID"
}, ... ]
Example
The Stock Endpoint

This API is used by the mSupply stock web app.

POST/PUT - Sending data to mSupply

  • Must include authentication header
  • Data in HTTP body as JSON
  • Two types of POST/PUT: New and Update
  • For New records:
  • For Updates to an existing record:
Transactions
  • Resource name: transaction
  • Create a transaction
    • Submit a JSON object containing:
      • new_transaction_id (you must have already requested this from the server - see above )
      • comment
      • name_id
      • lines (contains a JSON array:)
        • item_id
        • quantity
        • directions (new in v3.84)
    • Payload. 
      {"id": 34592,"comment":"test 1","name_id":3,
   "lines":[
       {"item_id": 19697,"quantity":10,"directions":"1t tid uf"},
       {"item_id": 22845,"quantity":5,"directions":"Take 5 tablets at 9 a.m. tomorrow"}
       ]
     }
    • successful completion returns a JSON object with “invoice_num” and a number
    • Assumed data: The following data is assumed and can not be submitted (will be ignored if you try)
      • The transaction type: it's a customer invoice (“ci”)
      • The store ID: it's the store you're logged in to.
      • The user: it’s the user who is logged in.
      • The entry_date: it's today.
      • The confirm_date: it's today.
      • The status: will always be “cn” (confirmed).
  • Updating a transaction:
    • for supplier invoice we are editing only hold status for now. So json payload would be: 
{"id":1002,"hold": "true"}
  • for customer invoice we can also update line quantity
{"id": 34592,"comment":"test 2",
   "lines":[
       {"transline_id": 19697,"quantity":20},
       {"transline_id": 22845,"quantity":10}
       ]
     }
  • Delete transaction lines:
    • {"id": 34592,"comment":"test 2","lines":[<all_lines>]
Stocktakes
Resource name stocktake
Method POST
Submit a JSON object containing id (you must have already requested this from the server - see above )
Finalising a stocktake body: include an item “status” with value “fn”
Assumed fields stock_take_created_date created_by_id finalised_by_id store_id
example 1 Submit a stocktake and finalise http://example.com/mobile/stocktake/123
 {"status": "fn", id:123, stock_take_date:2013-02-08, description:8/2/2013 Stocktake, Comment: "test",
     "lines":[
         {"id": 123,"item_id":234,"item_line_id":345,"item_name";"test_item1";"snapshot_qty":300,"stock_take_qty":310},
         {"id": 222,"item_id":232,"item_line_id":212,"item_name";"test_item2";"snapshot_qty":400,"stock_take_qty":300}  
     ]
     }

if the previous status was “sg”, the mSupply server will now create the appropriate inventory adjustments, as well as changing the status of the stocktake.

example 2 Submit a stocktake with status “sg” http://example.com/mobile/stocktake/123 
{"new_stocktake_id": 34592,"description":"stocktake test", "status":"sg",
   "lines":[
       {"item_id": 19697,"stock_take_qty":100},
       {"item_id": 22845,"stock_take_qty":80}
       ]
     }
example 3 Finalise an existing stocktake http://example.com/mobile/stocktake/123 
{"status":"fn"}
Customer Stock History
Resource name customerstockhistory
Method POST
Submit a JSON object containing an array with 3 fields id
requested_quantity
user_comment

DELETE - Delete Records

Available resources
Stocktake
  • Deleting a stocktake
    • e.g. http://127.0.0.1:8081/stocktake/123
    • Method: DELETE
    • Returns a JSON object containing a Description field with the value “stock take id xxx is deleted.” where xxx is the id of the stocktake deleted.
Invoice
  • <add here>
Item
  • <add here>
Errors
  • Errors are returned as a JSON object with one item “error” whose text content is the error message
  • e.g. 
    {"error":"we can't take you seriously while you insist on wearing that cardy"}
  • Here is a list of error messages you might see. Most are self-explanatory:
    • “No search parameter specified”
    • “No query parameter specified”
    • “Invalid resource specified”
    • “Invalid sort field specified”
    • “Invalid range header specified”
    • “No transaction with that ID found”
    • “Invalid transaction ID specified” (Different to above, in that you specified a non-numeric or negative ID)
    • “Yikes! Multiple transactions with same ID found” (you'll never see this error, or we'll be eating hats).



Previous: 19.09. mSupply REST API | | Next: 19.11. mSupply sync API

19.06. Mobile Dashboard set up (after v4.0)

August 2020:

The following instruction are for setting up dashboards for mSupply versions 4.0 and later. For mSupply versions earlier than v4.0, the dashboard setup is accessed and configured via the mSupply Preferences menu, refer to Dashboard set up (prior to mSupply v4.0).

Before you set the dashboard up you must:

  • know what ports are already in use on the server
  • have an appropriate SSL Certificate set up.
  • make sure your webserver is currently running.

Sustainable Solutions can help with these.

Access the dashboards configuration

  1. On the Admin tab of the Navigator click on the Dashboard button:
  2. This will show you a list of the available dashboard reports:
Configure the dashboards
  1. Tick the box in the Is active column for each report that you want generated. Note that if one or more reports are selected, the scheduled process for generating and refreshing the dashboard reports is automatically started, there is no separate setting for turning it on and off. Similarly, if no reports are selected the dashboard report generating process will be turned off automatically.
  2. Set the number of minutes in the Update Period (mins) column to set how often each of these reports is generated. 1440 is one full day.
  • The Export settings tab is for telling mSupply when and how to update the data behind the dashboard (see the Exporting msupply data to the dashboard tab section below).
  • The Dashboard Tab tab is for setting up Dashboard tabs (see the Dashboard tabs section below) for the Legacy mSupply dashboard. As of 2024, this section is most likely irrelevant.
Available dashboard reports

There are several built-in dashboard reports that everyone can use. The table below documents what they show and what properties can be edited:

If you would like help with adding one of these reports to your list, contact Sustainable Solutions on support@msupply.org.nz

Report Method Format Parameters
Expiring items for Store Shows a list of items, for a given store, which will expire within a specified number of months. v4.01 dashboardReportExpiringItemList Table, Bar chart monthsToInclude The number of months before expiry that the report includes (defaults to 3 if this parameter is missing)
storeCode search for a single store matching this code
dataElement Looks for the dataElement in the aggregator table. If blank, will default to AMC
customisation allows for a client customisation: currently supports MAM.
ven_category V, E, N or E,N or V,E ..etc will filter for the respective VEN values. If blank, no filtering by VEN value
chartType bar, table. If blank, will default to table
Report Method Format Parameters
Expiring Stock Shows a graph of total value of stock expiring grouped by the number of months in which the stock will expire. dashboard_rep_expiring_stock Bar chart None
Report Method Format Parameters
Items issued this month Shows a list of items, per store, which were issued in the last 30 days. Uses store tag and master list to select items to be displayed. dashboard_itemRow_storeCol_usag Table store_tag Identifies stores to display. Multiple stores can be selected by separating them by comma or space e.g. “bacau,CHC” or “bacau CHC”
master_list Show items which are included in this master list
period Number of days from the current date to look back
Report Method Format Parameters
Map stock on hand Shows a map of the area specified, with an “X” if the facility is out of stock of the item, or a dot representing the amount of stock on hand. dashboard_map_stock_on_hand Map country Name of country - compulsory but not shown
item_code the code of the item to display
lat_nw_corner the latitude of the North-West corner of the map
long_nw_corner the longitude of the North-West corner of the map
lat_se_corner the latitude of the South-East corner of the map
long_se_corner the longitude of the South-East corner of the map
store_tags A comma separated list of tags - or omit this parameter if you want to show stock for all stores
Report Method Format Parameters
Monthly transactions Shows a bar chart of the number of purchase orders, goods receipts, supplier and customer invoices created this month. dashboard_rep_month_transacs Bar or Line chart None
Report Method Format Parameters
Stock_for_category1_stores_by_item_list Shows a table of items in rows and stores in columns, with the stock on hand for that item in that store in each cell. dashboard_rep_stk_StoreCols_Itm Table store_code code or codes of stores to show. to specify multiple stores enter multiple store_code params (append @ for a “starts with” search)
master_list VHP - All Items Will search for items that are part of the master list : “VHP - All Items”
item_code items whose code matches this code (append @ for a “starts with” search)
Category1_description private Will search for names whose name category 1 is “private”
Report Method Format Parameters
Store Transaction Count Shows a count of each store's transactions for the past 7 and 30 days dashboard_rep_count_store_trans Line or Bar chart store_tags matches stores with this tag
Report Method Format Parameters
Sync sites last connection date dashboard_report_last_sync_date Table None
Report Method Format Parameters
Sync sites sent and received statistics dashboard_report_sync_stat Table None
Report Method Format Parameters
Sync sites statistics Shows a range of statistics related to synchronisation v4.02+ dashboardSyncSiteStatistics table storeTag (default = %) - report will select stores where tags match %{storeTag} and sync_id_remote_site > 1
syncDayThreshold (default = 5) - color cell red when days since last sync > syncDayTreshold
unfinalisedSIThreshold (default = 0) - color cell red when number of unfinalised supplier invoices > unfinalisedSIThreshold
stocktakeDayThreshold (default = 30) - color cell red when days since last stocktake > stocktakeDayThreshold
requisitionDayThreshold (default = 30) - color cell red when days since last requisition > requisitionDayThreshold
lookBackPeriod (default = 50) - Look back number of days for Supplier Invoice, Stocktake and Requisitions
lookBackPeriodCI (default = 30) - Look back number of days for Customer Invoice
daysWithCIThreshold (default = 0.2) - color cell red where 'days with customer invoice' divided by `number of working days` < daysWithCIThreshold
Report Method Format Parameters
This month's transactions Shows a bar chart of the number of purchase orders, goods receipts, supplier and customer invoices created this month. dashboard_rep_month_transacs Bar chart store_name If provided the report shows details for the given store, otherwise the default store is used
Report Method Format Parameters
Top facilities supplied The 10 customers in your store to which you have sent the greatest value of stock. Shows the value of stock for each customer. dashboard_rep_top_facilities Bar chart None
Report Method Format Parameters
Total stock value A single figure in your default currency, showing the total value of the stock you have in the store you are viewing the dashboard for. dashboard_rep_total_stock_value h2 None
Report Method Format Parameters
Transactions per store Shows a table of the transactions per stores within 30 days dashboard_rep_month_transacs Table store_code Specify a store by entering a store code, or leave blank for the default store
Report Method Format Parameters
Trends in critical stock dashboard_rep_in_stock_trends Time series chart store_id the ID of the store you're interested in, or no value for all stores
critical_stock TRUE if you want to include items with this field checked, false for all items
Report Method Format Parameters
Unfinalised Stock transfers Shows unfinalised stock transfers within the specified time period for each facility which matches the “store_tags” parameter. If no store tags are passed in, transactions are shown for all stores. dashboardReportUnfinalisedStock Table store_tags Queries only stores with matching store tags
days_older_than Queries transactions that were created 'x' number of days ago
Report Method Format Parameters
VEN items in stock Shows stock on hand of each items that belongs to the VEN (Vital, Essential, Necessary) category dashboard_rep_item_ven Line or bar chart store_code store code - if empty then default store is chosen
ven_category V,E,N or E,N or V,N ..etc will filter the VEN items. If blank all visible items for the store are chosen
Report Method Format Parameters
Vital items in stock Shows a bar graph of the percentage of medicines of the chosen category in stock at each facility dashboard_store_stock_percent Bar chart ven_category v or e or n if you want to include items that are Vital or Essential or Necessary
user_field_4 TRUE if you want to include items with this field checked
user_field_7 TRUE if you want to include items with this field checked
Note that the labels for fields 4 and 7 may be different, as they are set up in the mSupply preferences (misc tab)
critical_stock TRUE if you want to include items with this field checked, false for all items
store_tags entering healthcentre will only include stores with the “healthcentre” tag
Report Method Format Parameters
Item Stock on Hand and Months Cover Shows a table of item VEN status, Stock on Hand, Monthly Consumption, and Months Cover dashboard_rep_stock_on_hand Table store_code search for a single store matching this code
lookBack_months how many months of data to review when calculating; defaults to 6
ven_category V,E,N or E,N or V,N ..etc will filter the VEN items. If blank all visible items for the store are chosen. If not supplied the filter is not used; specify 'blank' to show items with empty ven. Note: each category in combination must be separated by comma, example: either v,e,n or v,e or v,n
item_code Searches for items matching this code
customisation Allows for a client customisation: currently supports MAM.

If you can't make a dashboard report that does what you want then please speak to us, it's usually a fairly simple matter for us to create one for you.

Editing dashboard reports

Double-click a report in the list shown above and the following window will open:

Parameters tab
  • If there are any properties shown in the list, these can be edited to change what is displayed.
  • To edit a property or value, click once to select the row, and then click again in the appropriate cell to edit it.
  • To add or delete a row use the New line and Delete line(s) buttons at the top of the window.
  • In the example shown in the screenshot above (a map report), the coordinates of two of the map corners and the item code of the item whose stocks will be shown on the map have been entered. Note that if you add extra properties to the default reports they'll be ignored.
Method code tab

This tab is password protected. After entering the password you are shown the code used to execute the report, which you can edit as necessary.

Json tab

This tab shows the JSON formatted text that was returned from the last successful execution of the report.

Notification Rules tab

On this tab you can enter JSON formatted text to define the rules for notifying users with the results of the report. To Add, edit or delete any rules you must first click on the Click to unlock button and enter the password to allow editing.

An example of a valid rule is: 

{"Rules":[{"userTags":["Monthly_report_emails"],"notificationPeriod":1,"lastSentAt":"2022-02-07T08:28:42Z"}]}

The elements are as follows:

  • userTags defines the tags the users must have to be sent the report. Add as many as you wish.
  • notificationPeriod the period in whole days between sendings of the report.
  • lastSentAt the date and time the report was last sent, in the format YYYY-MM-DDTHH:MM:SSZ. If set to “” (blank) this will trigger the sending of the report when the time in notificationPeriod has elapsed, measured from the time the OK button is clicked on this window.

Exporting mSupply data to the dashboard

The mSupply Grafana dashboard has its own separate Postgres database to improve performance and prevent use of the dashboard slowing mSupply down. This means that the data for the dashboard must be exported from the mSupply database to the dashboard's database. You control the settings for this process by clicking on the Export settings tab of the window which is displayed when you click on the Dashboard icon on the Admin tab of the Navigator:

Postgres server section

Enter the details of the dashboard's Postgres server in here:

  • Server: the URL of the server the database resides on
  • Port: the port the database is being served on
  • User: the username mSupply will use to login to the dashboard's database
  • Password: the password ms will use ot login to the dashboard's database
  • Database name: the name the dashboard's database has been given in Postgres

Test connection button: when you have enetered all the details in this section, click on this button to test the connection to the dashboard's database. mSupply will tell you whether the connection is successful or not.

Export settings section

In the table select the tables in the mSupply database that you want to export to the dashboard. Care needs to be taken here; you need to choose all the tables that will provide the information you need in the dashboard but not those you do not need as this may impact on the speed of the export, and therefore how quickly your dashboard can be updated.

Use the All/None checkbox to quickly check or uncheck all the tables in the list.

The URL field shows you the URL that mSupply is exporting the data to.

Full export of Checked Tables button: Clicking this will force mSupply to empty the dashboard database and export all the data from the selected tables to the dashboard database.

Run Next Scheduled Export Now button: Clicking this will make mSupply immediately export to the dashboard database all the data that has changed in its database since the last export to the dashboard.

When these settings have been saved, mSupply will use them to automatically export the selected data to the dashboard according to the schedule that has been set.

August 2020: The remaining instructions on this page are for configuring mSupply's legacy web dashboard. This may still work, but is no longer supported as it has been superseded by the mSupply Grafana web dashboard. The instructions are left here for historic reference only.

Dashboard tabs

You set up Dashboard tabs which will display on your dashboard. Dashboard tabs are “containers” for one or more dashboard reports. To edit them click on the Dashboard Tabs tab of the window which is displayed when you click on the Dashboard icon on the Admin tab of the Navigator:

To add a tab click the Add button. To edit a tab, double-click it. You will be shown a window for editing a dashboard tab:

Now you add reports that will show on this tab.

Understanding rows and columns

Take this example dashboard tab:

  • The tabs themselves occupy their own space on the left of the window- they aren't considered when laying out the dashboard
  • The first row has two reports- each report takes up half the row. So for the first report:
    • Row 1, Col 1, width 12 (“12” means it takes up the full width of the cell it is in- “4” would mean it would take up 1/3 of the width)
  • For the report at the top right:
    • Row 1, Col 2, width 12
  • For the map
    • Row 2, Col 1, width 12
  • The next two reports are on the same row, but are divided into 5/12 and 7/12 of the width of the window, so we put them in the same cell but change the width settings:
    • Row 3, Col 1, width 5
    • Row 3, Col 1, width 7
Adding a report to a dashboard tab

Click New Line to add a new report to the tab. Then edit the values in each column

  • Row: The row it will be in
  • Column: The column within the row- set to “1” if you don't have multiple reports on this row.
  • Report tite: The title that will show in the Orange heading bar for the report. Note that the same report can display different information depending on the parameters you set for that report- hence the need for the ability to customise report names
  • Type: You'll need to know the appropriate type for the report you're displaying. The options are
    • bar_chart
    • table
    • pie_chart
    • time_series
    • map
    • line_chart
  • Width: The fraction of the cell width in “twelfths” that this report will take up (“6” will make it take up half the cell width)
  • Report: Choose the report name from the drop-down list of available reports
Configure users to have access to dashboards

Once the tabs have been setup you have to choose which users will see which tabs. You do this in individual users' settings. For instructions on how to do this, see:



Previous: 19.05. Web Dashboard | | Next: 19.07. Online catalogue

19.05. Web Dashboard

August 2020: The instructions on this page are for configuring mSupply's legacy web dashboard. This may still work, but is no longer supported as it has been superceded by the mSupply Grafana web dashboard. The instructions are left here for historic reference only.

Legacy Web Dashboard

Once the dashboards have been set up (refer Dashboard set up (before v4.0) or Dashboard set up (after v4.0)), it can be used to monitor and access reports from anywhere using an internet browser (such as Chrome, Safari or Firefox).

The address for the dashboard is the public IP address of the server (or its web address if one has been assigned) on the port setup in the web server preferences (see the server preferences section for details) with /dashboard added. For example, if port 3000 is specified in the server preferences and the server is at web address example.com, users would browse to https://example.com:3000/dashboard using their internet browser.

This means users can access dashboard reports using their computer at home or even their tablet or cell phone!

Using the dashboard
Login

You'll need to be given the right URL (“web site”) to go to in your browser. Type it into the address bar of the browser you want to use (on the device of your choice) and click on the Go button or tap the Enter key. You will be shown the login page:

Enter your normal mSupply login username and password and click on the Log in button.

You will be taken to your dashboard which will show the first “page” or tab set up for you by default. You can click on other tabs at the left of the screen (if they have been set up for you) to see other reports:

The dashboard works just as well on a tablet or your phone, but the different “pages” will be at the top of your screen, not on the left.

There are several very useful reports on the dashboard, helping you to keep up to date with current stock levels and much, much more. And, if one of the standard reports doesn't give you what you want then it's fairly simple to create a new one from scratch or by duplicating and editing an existing one (see Setting up dashboards). Below are just a few examples of the kinds of reports the dashboard can show for you:



Previous: 19.04. mSupply customer web interface: guide for customers | | Next: 19.06. Mobile Dashboard set up (after v4.0)

19.04. mSupply customer web interface: guide for customers

The first section of this page covers the use of the interface itself by the customer. There is a small Back at the supplying store... section at the end which describes what happens in mSupply in response to the orders sent by the customer.

Logging in

You will be given an website address for the customer interface. e.g. http://example.com:8080/customer/. Go to that address using an internet browser running on a smartphone, laptop, tablet or desktop computer etc.

When it has loaded (the time this takes will depend on the speed of your internet connection), you will be shown the login page:

Enter your username and password and click Login

The navigator

You are now shown the mSupply customer navigator screen:

Here we are logged in as user “afms” who works for the customer “Ames Free Medical Clinic”.

The “Ames Free Medical Clinic” is set to use the store “General Warehouse” as their supplying store.

Click on:

  • Show Orders to view a list of orders that have been created but not yet completed.
  • Create Order to create a new order for stock from the supplying store.
  • Search Items to search a list of Items available in the supplying store.
  • Show Invoices to search for and view a list of invoices from the supplying store.
Show orders

Select Show Orders to display a list of orders that have been created.

To view or edit an existing order, click on the order in the table to highlight it, then click on the View/Edit button (top right)

To delete an existing order, click on the order in the table to highlight it, then click on the Delete button (top right)

Status wp indicates web interface orders that have been created and are still in progress (not yet finalised). These can be edited/deleted.

Status wf indicates web interface orders that have been finalised by the customer. These can be viewed, but not edited or deleted.

Click on HOME (top left) to return to the main options screen.

Create orders

Click on Create Order to display the screen for entering an order:


To add an item to the order, click the Add line button.

In the pop-up window clicking the Item name field will open a drop down list to select from Enter the quantity and click Add to order to proceed

Repeat this to add further items to your order.

Information can be entered in the fields Our ref and Comment, but these are optional.

If you wish to continue working on the order later, click the Save changes button.

When you have completed the order, click on the Finalise button. This will submit the order to the supplying store in mSupply and no further changes will be possible. It will now be visible under the Show Orders option until the supplying store processes it. It is also visible and available for processing in mSupply at the supplying store.

A note for the mSupply user processing the order in the warehouse:

  • The customer's order will appear in mSupply Desktop as a Customer Invoice with status of wf (web finalised). This means that while the customer can no longer edit the order, the supplying store's desktop user can.
  • The customer invoice displays the customer's order with placeholder lines by default. This gives the mSupply Desktop user control to choose the stock for the customer's order. To apply stock to the placeholder lines, refer to Redistribute placeholder lines.
  • When stock has been applied to the various lines, the invoice is processed in the normal way (refer Issuing goods to a customer (customer invoices)) to create the picking list and dispatch note as required before the goods are dispatched to the customer.
Using an order list

If you have been assigned an Order List of the items you are allowed to order, this can be used when you are creating an order. Clicking the Add lines from Order list button will display the items on the list(s) defined for the customer logged in.

For setting up a default order list, see Names: Using, adding and editing

The list will be displayed with the items in the same order as was specified when setting up the list in mSupply.

(Back up to The navigator)

Search items

Click Search Items to make a search of items available in the supplying store. It will display this screen:

Choose your search options using the selectors and enter something to search for in the textbox (or leave it empty to list all the items). Click on Search and the search will be made. When the search is complete the list of items matching your search criteria will be displayed:

Click the row of a specific item and click on Item details to see the details:

Note: The Stock on Hand figure is the supplying store's stock on hand, not the Customer's stock on Hand.

(Back up to The navigator)

Show invoices

Select Show Invoices to display a list of invoices that have been created in the supplying store for you:

Columns
Name

The Name of the customer. If this isn't the customer's name, then there is a problem - contact support@msupply.org.nz

Invoice Number

The Invoice Number as recorded in the supplying store

Status

The Status indicates at what stage each invoice is in processing:

  • sg (suggested): The supplier has started to process it, but is not finished.
  • cn (confirmed): The supplier has completed processing the order but has likely not yet dispatched it.
  • fn (finalized): The supplier has likely dispatched the order and the stock should be on its way to you.

Depending on the configuration of mSupply, it is possible to dispatch an order without actually finalizing it. So you may find yourself receiving an order that hasn't actually been finalized.

Entered Date

Date that the invoice was first entered in the supplying store.

Comment

Comment added by the supplying store

Find invoices

To find a particular invoice:

  1. Click on the FIND button at the top right
  2. Fill in the details in the search options provided
  3. Click on the SEARCH button

View invoice details

To view details of an invoice:

  1. Click the row of a specific invoice
  2. Click on the VIEW button at the top right

(Back up to The navigator)

Previous: 19.03. mSupply customer web interface | | Next: 19.05. Web Dashboard

19.03. mSupply customer web interface

What is it?

The mSupply Customer Web Interface allows the staff of Customers in your mSupply system to order stock from a store in your mSupply system. It runs on a browser on any device: tablet, smartphone, net-book, desktop computer etc.

While the Customer Interface will run on smaller devices like smartphones, it is generally impractical to use with screens smaller than 5 inches across the diagonal.

Features and limitations

The Customer Interface is designed to be used by staff of Customers in your mSupply system i.e. people working in places you supply. They could be people outside of your organisation.

The Customer Interface's features are:

  • Show Orders: Display a list of the user's orders that are waiting to be processed by the supplying store. These orders can be opened to display further info.
  • Create Orders: Orders for stock from the supplying store can be created, deleted and edited.
  • Search Items: Search a list of Items available in the supplying store.

Obviously, this interface is for ordering stock only so there is no place for batch number or expiry date to be displayed or selected in the Customer Interface. However, mSupply does keep a record of the batch and expiry date of all stock issued to the Customer from the supplying store.

Turn on the customer web interface

To do this you simply need to turn on the mSupply web server. You can find details of how to do this on the mSupply Web Server page.

Setup each customer

There are 2 simple setup steps you need to carry out for each customer.

1. Set the supplying store for each customer

Go to the customer's detail page (Select Customer > Show customers… from the menus, click on the Find button, find the customer in the list and double-click on them):

In the Customer details section, select the customer's supplying store from the drop down list. This is the store the customer's orders will be sent to and therefore the store that will send them goods in response to the orders.

2. Add logins for each customer

The logins for each customer are setup as contacts of the customer in mSupply. To set them up, go to the customer's detail page and go to the Contacts tab (Select Customer > Show customers… from the menus, click on the Find button, find the customer in the list and double-click on them. Finally, click on Contacts in the tab list on the left hand side.). This window is displayed:

To add a new login (contact), click on the Add contact button to open this window:

Enter the contact's name last and first names in the Last and First fields

In the Web login section check the Can login to the web interface checkbox then enter the contact's username and password in the Username and Password fields - these are the details they will login with.

Click the OK button to save the details. You can add as many contacts for a customer as you like, and they will all be able to login to the customer interface and create orders for that customer.

You can edit a contact's details by double-clicking them in the customer's list of contacts shown in the screenshot above.

To stop a contact from accessing the customer interface you can either delete them or you can uncheck the Can login to the web interface checkbox on their details page.

Repeat these 2 steps for all the customers who need to login to the interface.

Connecting to the customer web interface

Once the mSupply web server is running, your customers can access it by opening an internet browser on any device and navigating to URL:PORT/customer/ where URL is the internet address of your mSupply server and PORT is the figure you entered into the Run the webserver on port field in the preferences mentioned in the section above

With URL re-directing, you can create a web link like : https://demo.msupply.org/customer/

The hyperlink above links to a demonstration site. Send us an email at info@msupply.org.nz if you would like a temporary username and password to try it out.

Once it has been setup correctly, get your customers to bookmark the customer interface web page to save them typing it in every time.

Your customer can then use the following guide to login and order stock on-line. mSupply customer web interface: guide for customers



Previous: 19.02. mSupply web server | | Next: 19.04. mSupply customer web interface: guide for customers

19.07. Online catalogue

The online catalogue is a searchable list of items you stock, driven by data in mSupply. The information can easily be updated and items added to or removed from the catalogue. By enabling the online catalogue you can, for example, replace the expensive printing of hard copy catalogues.

Setup

1. Tell mSupply which columns to display in the catalogue

This is done in the mSupply preferences. Choose File > Preferences… from the menus and go to the Web catalogue tab. For the details of the settings and what they do, see the 16.01. General preferences > Web catalogue tab page for details.

2. Tell mSupply which store to run the catalogue from

Choose File > Preferences… from the menus, and on the Web server tab select the store in the Default store for web interface drop down list. If the mSupply web server isn't already running you'll also need to click on the Start web server button. More information about these options can be found on the 16.01. General preferences > Server tab page.

3. Tell mSupply which items are to be included in the catalogue

The only items that will appear on the web catalogue are all those that have their 'On Price List' flag set in the Default store for web interface.

To set an item's 'On Price List' flag, you will need to do this from the Item > Misc tab - refer to 4.01.03. Items - Misc(ellaneous) tab page.

You need to set these values for all the items you want to appear in the catalogue. As with many repetitive tasks in mSupply, the OK & Next and OK & Previous buttons at the bottom of the item details window are your friends here. If you are going to need to work with hundreds, or even thousands of items, then the Update On Price List in bulk feature is your even greater friend.

Operation

Once the mSupply web server is running, users access the catalogue using a web browser (Firefox, Chrome etc.). The address to visit is 

https://example.com/catalogue/

where example.com is the domain of your web server.

This is what the user will see:

The catalogue can be searched by either item name (or other property that you have set to be searchable) or the categories that items belong to.

Searching by item name/property

Searching by item name is the default search when the online catalogue first loads in the browser, shown in the screenshot above.

To search by item name, type something in the Search field, select the appropriate comparator in the drop down list (set to Starts with by default, as shown in the screenshot above) and click on the Search button.

If you leave the Search field empty, all items in the catalogue will be returned by the search.

If you have set other item properties to be searchable in the 1. Tell mSupply which columns to display in the catalogue setup step (above) then you can click on the Item name drop down list and select another searchable property, as shown here:

As you do that, the options in the search comparator drop down list (Showing Starts with in the Operation section screenshot above) will change to match the type of property you have chosen.

Searching by category

The category used to search for items in the catalogue is item category 1. This category is hierarchical and has 3 levels. For more details about this category, including setting it up and assigning it to items, see here. Note that in the catalogue, Top level corresponds to level 1 of category 1, Mid level to level 2 and Bottom level to level 3.

We say that Mid level categories are children of the Top level categories and Bottom level categories are children of Mid level categories.

To search by category, click on the By category slider in the top right hand corner:

The window will change to show the category search options:

By default the search filters are set to search for all items that have a category. If you click on the Search all Categories button, all items that have a category will be returned (and if no items have a category set then no items will be returned!)

If you want to find all items that have no category set you can change the Bottom level category drop down list to None (this is the only category filter that has a None option). The Search all categories button will change to Search bottom category with a for items with no category subtitle to make it clear what will happen:

If you change the drop down list of one of the category levels away from All, the child level drop down list will change to contain only categories that are children of the one you selected. Using this, you can refine your category search as much or as little as you wish.

So, if you select a category in the Top level category drop down list and click on the Search top level category button (the Search all categories that is automatically renamed) then all the items that have a category that is a child of that top level category will be returned.

Before you click on the Search top category button, if you look at the options in the Mid level category drop down list, you will notice that it now contains only categories that are children of the selected top level category. If you select one of those, the Search top category button will become Search mid category and, if you click on it, all items that have a category that is a child of the selected mid level category will be returned.

Similarly, if, before clicking on the Search mid category button, you selected one of the Bottom level categories then the Search mid category button will become Search bottom category and, if you click on it, all items that have the selected bottom level category will be returned.

The results

Whatever search filter you choose, the search results are shown after you click on the Search button like this:

Note that the filter is still available at the top of the window so that you can change the search if you wish. If you click on the Expand results button is removed to give the resultds as much screen space as possible. Click the button again and the search filter will be displayed again.

The columns shown in the search results table are those you selected in the 1. Tell mSupply which columns to display in the catalogue setup step above. They are also displayed with the display names you sent for them.

Previous: 19.06. Mobile Dashboard set up (after v4.0) | | Next: 19.08. Stock web app

19.09. mSupply REST API

What is it?

mSupply has a REST API that enables certain actions to be carried out externally, by external applications for example. This API allows you to:

  • Send an order (response requisition) to mSupply
  • Retrieve customer invoices that have been confirmed but not yet been acknowledged or received
  • Mark a customer invoice as acknowledged (shipped)
  • Mark a customer invoice as received (arrived)
  • Retrieve stock information

Response requisitions will be processed in mSupply as normal in the supplying store, and can be fulfilled by generating and processing one or more customer invoices, depending on stock availability.

Basic usage

  • Communication is over the HTTP protocol. HTTPS is supported and you should use it to keep your passwords and other information secure. If you want to restrict to only HTTPS, then block the HTTP port mSupply is using on your router.
  • All data is submitted and returned as JSON.
  • You must always login first. This will return a JWT token that you use in further requests to authenticate each request.

The details of the requests you can make and what information you need to send with each request are in the section below.

Authentication

Logins (user name and password) are set up per store as contacts of store names. This uses exactly the same mechanism as customer web ordering. See the 19.03. mSupply customer web interface page for details.

All requests relate to transactions, stock and orders only in the store that the user used to authenticate with is a contact of. The customer and supplier's details are derived from the log-in details i.e. the customer will be the store the logged in user is a contact of and the supplier will be the supplying store of that store.

API definition

See the Examples section below for payload details for each request.

All below URLs should be prefixed with `api/v4`:

URL HTTP Verb Description
/login POST Login with username and password setup in mSupply. Returns a JWT cookie to be used in following requests (send it in an Authorization header with scheme Bearer i.e. Authorization: Bearer <jwt_token>). Include the loginType = “invoice” element in the request body or, for the /storeCustomerInvoice endpoint, include the loginType = “storeInvoice” element.
/stock GET Returns an array of stock details for all items in the customer's master list(s).
* Quantities are specified in number of packs and pack size.
* Separate lines for each different batch, expiry date or pack size.
/stock?code=xxx&name=yyy GET Returns an array of stock details for all visible items, optionally restricted to those starting with the specified code/name.
* Quantities are specified in number of packs and pack size.
* Separate lines for each different batch, expiry date or pack size.
/customerOrder POST Create a new customer order with the supplied array of order lines. Returns the ID of the order created.
* The customer and supplier's details are derived from the log-in details i.e. the customer will be the store the logged in user is a contact of and the supplier will be the supplying store of that store.
* An order (serial) number will be automatically assigned by mSupply (unique per store).
* Item codes must match the codes (the mSupply item code or the catalogue code) of items already existing in mSupply.
* Requested quantities are specified in number of packs and pack size.
* Customer stock on hand quantities (if available) are specified in units.
* Customer orders are created as response (customer) requisitions in mSupply. These are then processed manually in the supplying store to generate one or more customer invoices to fulfil the order (see the 8.07. Stock control methods for your customers (requisitions) page for details).
* Customer invoice numbers will also be automatically assigned by mSupply (unique per store).
* Generated customer invoices will be linked back to the original customer order via the order number.
* Customer invoices are confirmed when the stock has been picked and packed for shipment.
* Comments can be entered for the order and also for individual lines.
/customerOrder/{order number} GET Return the details of the specified order number.
/customerInvoice GET Returns an array of customer invoices which have been confirmed but not acknowledged, received or cancelled.
* Invoices are linked to the original order via the order number.
* Quantities are specified in number of packs and pack size.
* Prices are per-pack and a line total, with an invoice total which includes any extras (e.g. shipping).
/customerInvoice/{invoice number} GET Returns a particular customer invoice.
* Invoices are linked to the original order via the order number.
* Quantities are specified in number of packs and pack size.
* Prices are per-pack and a line total, with an invoice total which includes any extras (e.g. shipping).
/customerInvoiceReceived/{invoice number} PATCH Set the specified customer invoice's received (arrival) date to the date specified (in ISO format).
/customerInvoiceAcknowledged/{invoice number} PATCH Set the specified customer invoice's acknowledged (shipped) date to the date specified (in ISO format).
/storeCustomerInvoice?startDate=YYYY-MM-DD&endDate=YYYY-MM-DD GET Return all confirmed (and not cancelled) customer invoices in the default store of the user logged in with, which were confirmed between the startDate and endDate.

Examples

URL HTTP Verb Response
api/v4/login POST Request: 
{
    "username": "Admin",
    "password": "Admin",
    "loginType": "invoice"
}

Response: 

// success (HTTP status 200)
{
    "status": "success",
    "authenticated": true,
    "username": "Admin",
    "userFirstName": "Minnie",
    "userLastName": "Streator",
    "userJobTitle": "Boss",
    "userType": "contact",
    "service": "invoice",
    "storeName": "General Warehouse"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Username/password/login type missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "Failed to authenticate/No store found for user"
}
api/v4/stock GET Response: 
// success (HTTP status 200)
[
    {
        "itemCode": "ABC012",
        "itemName": "Amoxycillin 250mg tab",
        "batchName": "SD34567",
        "expiryDate": "2021-05-05T12:00:00.000Z",
        "unit": "Tab",
        "barcode": "0123456778899",
        "packSize": 100,
        "quantity": 23, // in packs
        "costPricePerPack": 1.23, // in default currency
        "sellPricePerPack": 1.33, // in default currency
        "storeName": "General Warehouse"
    },
    ...
]
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

The stock levels will be those of the supplying store for the logged in customer, with separate lines for different batches, expiry dates or pack sizes. By default, the items included will be those in the customer's master list(s), unless overridden by the optional item name/code parameters, in which case the results will be filtered by items with a name/code starting with the specified value(s).

api/v4/customerOrder POST Request: 
{
    "orderReference": "VS2345",
    "comment": "Test order",
    "lines":[
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "packSize": 100,
            "quantity": 3, // in packs
            "SOH": 3500, // current customer stock on hand (in units)
            "comment": "something about this line"
        },
        {
            "itemCode": "CYZ456",
            "itemName": "Paracetamol 500mg tab",
            "packSize": 100,
            "quantity": 5, // in packs
            "comment": ""
        },
        ...  
    ]
}

Response: 

// success (HTTP status 200)
{
    "status": "success",
    "numberOfRecordsUpdated": 1,
    "orderNumber": 23425
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Item code not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "Duplicate line for item"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Order already exists"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Item is not available to order"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invalid pack size/quantity"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Order reference/order lines/item code/item name/quantity missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

The customer order (response requisition) will be created in the logged in customer's supplying store, set to confirmed with the current date, and the new (automatically assigned) customer order number returned

api/v4/customerOrder/23425 GET Response: 
// success (HTTP status 200)
{
    "ID": "UID23425",
    "confirmedDate": "2020-12-27T17:51:00.000Z",
    "orderNumber": 23425,
    "orderReference": "VS2345",
    "comment": "Test order",
    "storeName": "General Warehouse",
    "lines":[
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "packSize": 100,
            "quantity": 2, // in packs
            "comment": "Reduced quantity supplied"
        },
        {
            "itemCode": "CYZ456",
            "itemName": "Paracetamol 500mg tab",
            "packSize": 100,
            "quantity": 5, // in packs
            "comment": ""
        },
        ...  
    ]
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Order not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one order found"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Order number missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Returns the specified customer order in the logged in customer's supplying store

api/v4/customerInvoice GET Response: 
// success (HTTP status 200)
[
    {
        "ID": "UID8567546AS",
        "invoiceNumber": 8567546,
        "confirmedDate": "2020-12-29T12:45:00.000Z",
        "receivedDate": "",
        "acknowledgedDate": "",
        "cancelledDate": "", // blank unless the invoice has been manually cancelled after it has been confirmed
        "invoiceReference": "REF222",
        "comment": "From order reference VS2345",
        "orderNumber": 23425, // original order number (can have multiple invoices from a single order)
        "storeName": "General Warehouse",
        "invoiceTotal": 135.55, // sum of all lines plus any extras e.g. shipping
        "lines": [
            {
                "itemCode": "ABC012",
                "itemName": "Amoxycillin 250mg tab",
                "batchName": "SD34567",
                "expiryDate": "2021-05-05T12:00:00.000Z",
                "unit": "Tab",
                "barcode": "0123456778899",
                "packPrice": 3.65,
                "packSize": 100,
                "quantity": 2, // in packs
                "comment": "Reduced quantity supplied; Requested pack size 100",
                "lineTotal": 7.3 // pack price x quantity
            },
            ...
        ]
    },
  ...
]
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Returns all customer invoices for the logged in customer in their supplying store and confirmed, but which haven't yet been acknowledged, received or cancelled. Note that a single customer order can be split into multiple customer invoices

api/v4/customerInvoiceReceived/8567546 PATCH Request: 
{
    "receivedDate": "2020-12-31T09:23:00.000Z"
}

Response: 

// success (HTTP status 200)
{
    "status": "success",
    "numberOfRecordsUpdated": 1
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Invoice not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one invoice found"
}
// failure (HTTP status 503)
{
    "status": "error",
    "error": "Unable to update invoice"
}
// failure (HTTP status 503)
{
    "status": "error",
    "error": "receivedDate is invalid"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invoice is not yet ready for dispatch"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invoice has been already been received/cancelled"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Invoice number/received date missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Updates the received date for the specified customer invoice → it will no longer appear in the GET response above

api/v4/customerInvoiceAcknowledged/8567546 PATCH Request: 
{
    "acknowledgedDate": "2020-12-31T09:23:00.000Z"
}

Response: 

// success (HTTP status 200)
{
    "status": "success",
    "numberOfRecordsUpdated": 1
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Invoice not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one invoice found"
}
// failure (HTTP status 503)
{
    "status": "error",
    "error": "Unable to update invoice"
}
// failure (HTTP status 503)
{
    "status": "error",
    "error": "acknowledgedDate is invalid"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invoice is not yet ready for dispatch"
}
// failure (HTTP status 403)
{
    "status": "error",
    "error": "Invoice has been already been acknowledged/cancelled"
}
// failure (HTTP status 400)
{
    "status": "error",
    "error": "Invoice number/acknowledged date missing"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Updates the acknowledged date for the specified customer invoice → it will no longer appear in the GET response above

api/v4/customerInvoice/8567546 GET Response: 
// success (HTTP status 200)
{
    "ID": "UID8567546AS",
    "invoiceNumber": 8567546,
    "confirmedDate": "2020-12-29T12:45:00.000Z",
    "receivedDate": "2020-12-31T09:23:00.000Z",
    "cancelledDate": "", // blank unless the invoice has been manually cancelled after it has been confirmed
    "invoiceReference": "REF222",
    "comment": "From order reference VS2345",
    "orderNumber": 23425, // original order number
    "storeName": "General Warehouse",
    "invoiceTotal": 135.55, // sum of all lines plus any extras e.g. shipping
    "lines": [
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "batchName": "SD34567",
            "expiryDate": "2021-05-05T12:00:00.000Z",
            "unit": "Tab",
            "barcode": "0123456778899",
            "packPrice": 3.65,
            "packSize": 100,
            "quantity": 2, // in packs
            "comment": "Requested pack size 100",
            "lineTotal": 7.3 // pack price x quantity
        },
        ...
    ]
}
// failure (HTTP status 404)
{
    "status": "error",
    "error": "Invoice not found"
}
// failure (HTTP status 409)
{
    "status": "error",
    "error": "More than one invoice found"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}

Returns the specified customer invoice for the logged in customer in their supplying store

api/v4/storeCustomerInvoice?startDate=2023-07-23&endDate=2023-09-23 GET Response: 
// success (HTTP status 200)
{
    "ID": "ABCD1234EFGH5678",
    "customerName": "Customer01",
    "customerCode": "CT32695",
    "invoiceNumber": 25387,
    "orderNumber": 4578, // Requisition number
    "confirmedDate": "2023-07-30T09:32:00.000Z",
    "receivedDate": "2023-07-22T19:11:00.000Z", // Invoice entry date
    "invoiceReference": "NEW3756",
    "comment": "From order reference ORD768",
    "storeName": "General Warehouse",
    "invoiceTotal": 742.56, // sum of all lines plus any extras e.g. shipping
    "lines": [
        {
            "itemCode": "ABC012",
            "itemName": "Amoxycillin 250mg tab",
            "batchName": "SD34567",
            "expiryDate": "2026-05-31T12:00:00.000Z",
            "unit": "Tab",
            "barcode": "0123456778899",
            "packPrice": 3.65, // Sell price of one pack
            "packSize": 100,
            "quantity": 2, // in packs
            "comment": "Requested pack size 100",
            "lineTotal": 7.3 // pack price x quantity
        },
        ...
    ]
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "Selected store is not default for user"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "JWT token/user ID/store ID not found"
}
// failure (HTTP status 401)
{
    "status": "error",
    "error": "End date/Start date is mandatory"
}

Returns customer invoices in the logged in user's default store that were confirmed and not cancelled between the startDate and endDate



Previous: 19.08. Stock web app | | Next: 19.10. mSupply legacy REST APIs

19.08. Stock web app

You can use the Stock web app to look up the stock on hand of items, including batch and expiry information, from anywhere you have access to the internet. Very handy if you are away from the computer you normally use to access mSupply, or travelling overseas and still need to check the stock information in your store.

Users will be able to see the stock information for their default store only (Note: in a sync system, it is the primary server information that is shown).

To access the Stock web app, point your browser to https://yourserver.msupply.org:2048/stock where yourserver.msupply.org is the domain name and 2048 is the port for your mSupply web server (these details will be supplied to you by Sustainable Solutions if you are using this functionality). If you are going to use the App a lot, it would be a good idea to set its location as a bookmark or favourite in your browser.

This is the screen you will see:



Type in your normal mSupply username and you normal mSupply password and click on the Login button to move to the search screen:



You can either search by item name or stock location code - select “Location code” instead of “Item name” in the screenshot above to search by location code. mSupply will search for stock belonging to items with names or in locations with codes that begin with what you type in the “Search by item or location code” field shown in the screenshot. When you have entered the text to search for, click on the magnifying glass icon to make the search. The results are displayed below the search filter, as shown in this screenshot:



And this is an example of a search by stock location code:



You can use the “@” character as a wild card e.g. just typing “@” (without quotes) on its own will show all stock

Previous: 19.07. Online catalogue | | Next: 19.10. mSupply legacy REST APIs

19.11. mSupply sync API

What is it?

There are multiple ways to configure an mSupply installation. Where the internet is good, or you are using a local area network, you can have real-time communication with an mSupply server. Where internet access is poor or non-existent, we have mSupply sync. You can have a local application that saves all the changes the user makes to a local database - this can be a mobile app, a single user application on a PC or a tablet, or a client-server application on a local LAN.

The machine on which the data is stored, which we call a satellite, then periodically communicates with a central mSupply server, which we call the primary - this may be in a central location in the country, or it may be a cloud-based server. The REST API described here is used to send and receive data from the primary server to keep both satellite and primary sites up to date with data additions, modifications and deletions. See 29.01. Introduction to Synchronisation for more details on how sync works.

Basics

You might want to read about our mSupply Mobile API, as the basics are the same. That is:

  1. The SYNC API is a subset of the mSupply REST API.
  2. All calls to the sync API use a pseudo-resource of “sync”.
  3. The second URI segment is the API version. Allowable values:
Value Release Date
v1 25 Jan 2016
v2 01 Mar 2017

Our Android mobile app uses v2 exclusively to communicate with the primary mSupply server, whereas mSupply itself uses v1 for synchronisation between different instances of mSupply. For example, you call “https://example.com/sync/v1/somethinghere”.

Server requirements

You will need to be querying an mSupply standalone or server that:

  1. Has a fixed IP address.
  2. Ideally has a domain name and a valid SSL certificate - we rely on SSL for stopping your communications and password(s) being acquired. You should use it.
  3. Is reachable from the machine you are using these APIs on.

Authentication

We use basic HTTP authentication:

  1. v1 of the API only supported a simple username:password, with each satellite sharing the same credentials for a single special sync user on the primary server.
  2. v2 expects the password part to be SHA256 encoded i.e. sitename:SHA256_encoded_password, and each satellite can have its own individual site name and password credentials on the primary server.
  3. v1 now also supports SHA256-encoded passwords and individual satellite site credentials.

Available calls (v1)

Note that each site has a unique integer ID, and that the ID for the primary server (running a web server) is always set to 1.

HTTP GET
https://example.com/sync/v1/queued_records/count?from_site=4&to_site=1

will retrieve the number of sync records in the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1. 

https://example.com/sync/v1/queued_records/?from_site=4&to_site=1&limit=10

will retrieve the first 10 sync records in the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1. If limit is missing, it will only retrieve a single record from the head of the queue. 

https://example.com/sync/v1/queued_records/?from_site=4&to_site=1&sync_id=GSHJDJKSKS

will retrieve a single sync record from the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1, where the sync record ID=GSHJDJKSKS (UUID). 

https://example.com/sync/v1/initial_dump/?from_site=4&to_site=1&type=full

will request the sync site with ID=1 to regenerate all sync records for the sync satellite site with ID=4 (the requesting site). This is used to (re)initialise a new satellite. If type is missing, or has any other value, then only the subset of sync records necessary for a mobile store will be generated.

HTTP POST
https://example.com/sync/v1/acknowledged_records/?from_site=4&to_site=1

will inform the server that the sync records whose IDs (UUID) are specified (as JSON) in the HTTP BODY have been consumed from the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1. 

https://example.com/sync/v1/queued_records/?from_site=4&to_site=1

will apply the sync record data specified (as JSON) in the HTTP BODY from the sync satellite site with ID=4 (the requesting site) to the sync site with ID=1. Multiple sync records can be sent in one packet.

Format of a record
  • The format is JSON.
  • If there is more than one record returned or to be sent, each record is an element of a JSON array.
  • v1 uses internal field numbers and table numbers.
  • Text ID fields are always UUIDs.
  • Blobs, pictures etc. are BASE64 encoded.
  • Example for v1:
[
  {
    "SyncID": "asdlkfj",
    "TableNumber": 3,
    "RecordID": "dkfaadj",
    "KeyFieldID": 5,
    "SyncType": "U",
    "StoreID": "knvslkj",
    "fields": [9, 11, 3],
    "values": ["sadflkj", "Trinity", "12"]
  }
]

Available calls (v2)

The v1 API calls above behave in exactly the same way for v2, except that the format of any sync records transferred is different. The extra v2-specific API calls below are used to retrieve the necessary parameters for our mobile app, which is designed to host a single store.

HTTP GET
https://example.com/sync/v2/queued_records/count?from_site=4&to_site=1

will retrieve the number of sync records in the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1. 

https://example.com/sync/v2/queued_records/?from_site=4&to_site=1&limit=10

will retrieve the first 10 sync records in the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1. If limit is missing, it will only retrieve a single record from the head of the queue. 

https://example.com/sync/v2/queued_records/?from_site=4&to_site=1&sync_id=GSHJDJKSKS

will retrieve a single sync record from the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1, where the sync record ID=GSHJDJKSKS (UUID). 

https://example.com/sync/v2/initial_dump/?from_site=4&to_site=1&type=full

will request the sync site with ID=1 to regenerate all sync records for the sync satellite site with ID=4 (the requesting site). This is used to (re)initialise a new satellite. If type is missing, or has any other value, then only the subset of sync records necessary for a mobile store will be generated. 

https://example.com/sync/v2/site/?site_name=Satellite4

will retrieve the site ID (integer) and the corresponding store ID (UUID) and store-name ID (UUID) for the sync satellite site with name=Satellite4 on the primary sync site. Used by mobile during login to lookup the store for the site. 

https://example.com/sync/v2/user/?store=CVCBNXNSHHSH

will retrieve the user ID (UUID) for the sync satellite site having store ID=CVCBNXNSHHSH (UUID, returned by the above REST call) on the primary sync site. Used by mobile during login to lookup the user for the store.

HTTP POST
https://example.com/sync/v2/acknowledged_records/?from_site=4&to_site=1

will inform the server that the sync records whose IDs (UUID) are specified (as JSON) in the HTTP BODY have been consumed from the outgoing queue for the sync satellite site with ID=4 (the requesting site) on the sync site with ID=1. 

https://example.com/sync/v2/queued_records/?from_site=4&to_site=1

will apply the sync record data specified (as JSON) in the HTTP BODY from the sync satellite site with ID=4 (the requesting site) to the sync site with ID=1. Multiple sync records can be sent in one packet.

Format of a record
  • The format is JSON.
  • If there is more than one record returned or to be sent, each record is an element of a JSON array.
  • v2 uses field names and table names as described in the Field descriptions chapter.
  • Text ID fields are always UUIDs.
  • Blobs, pictures etc. are BASE64 encoded.
  • Example for v2:
[
  {
    "SyncID": "kjhkljg",
    "RecordType": "trans_line",
    "RecordID": "dsfhjd",
    "SyncType": "I",
    "StoreID": "klsvnsl",
    "Data": {"item_name": "hello", "quantity": "95555", "cost_price": "65.5"}
  }
]

Available calls (v4)

HTTP POST
https://example.com/sync/v4/name_store_join

will tell the server to create a name_store_join record for the store and name records defined in the body. Used to make a patient visible when their first prescription has been processed in a store.

Body
{
    "name_ID": "xxx",
    "store_ID": "xxx"
}
Response

If all is well, 200 OK and the payload: 

{
  "name_ID": "6F0EA445B35F479AA1020BD2D24B9755",
  "store_ID": "8D967C2618BE4D78B3A6FAD6C1C8FF25",
  "inactive": false,
  "ID": "C6C0A32C1E9841FF93735144F0114290",
}

A 400 will be returned if either of the payload elements are missing or the IDs are not present.

A 401 will be returned if authentication fails.

HTTP GET
https://example.com/sync/v4/patient_history?id=[name id]

Requests patient dispensing history for the specified name record

Response

If all is well, 200 OK and the payload: 

[
    {
        "confirm_date": "2019-02-22",
        "store": {
            "name": "Hogwarts Dispensary"
        },
        "transLines": [
            {
                "quantity": 5,
                "item_name": "Amoxicillin 250mg tabs",
                "ID": "4C8C08880A20490A9F2B9EC6EC9700A1",
                "itemLine": {
                    "item": {
                        "code": "030453",
                        "doses": 0,
                        "is_vaccine": false
                    }
                }
            }
        ]
    },
    {
        "confirm_date": "2021-05-07",
        "store": {
            "name": "Hogwarts Dispensary"
        },
        "transLines": [
            {
                "quantity": 0.16666666666667,
                "item_name": "Pfizer/BioNTech COVID-19 vaccine",
                "ID": "a53a3350aec411eba43c6dc4a1371348",
                "itemLine": {
                    "item": {
                        "code": "C19PB",
                        "doses": 6,
                        "is_vaccine": true
                    }
                },
                "medicineAdministrator": {
                    "first_name": "Melaia",
                    "last_name": "Baleinausori"
                }
            }
        ]
    }
]

An empty array will be returned if the ID does not match a name record or there is no history to return.

A 401 will be returned if authentication fails.

Available calls (v5)

HTTP GET
central_records
https://example.com/sync/v5/central_records?cursor=0&limit=1000

Requests sync change log records for the sync site matching the authentication sent in the header.

Attributes
  • cursor: the record number to return from. e.g. cursor=10 means start returning from the 10th record onwards.
  • limit: the maximum number of records that can be returned. If omitted, the limit is set to 1000. If a limit value above 1000 is used, the limit is set to 1000.
queue
https://example.com/sync/v5/queue?limit=[number of records]

Requests sync records that require processing for the sync site which matches the authentication passed in the header.

Attributes
  • limit: the maximum number of records that can be returned. If ommitted, the limit is set to 1000. If a limit value above 1000 is used, the limit is set to 1000.



Previous: 19.10. mSupply legacy REST APIs | | Next: 19.12. UNFPA LMA reports app

19.12. UNFPA LMA reports app

What is it?

Some UNFPA users are periodically required to produce Last Mile Assurance (LMA) reports. These can be time consuming and difficult to produce manually so we've created an app for that!

This app runs on the central server of your mSupply installation and will create a selection of UNFPA formatted LMA reports as spreadsheet files for you; all you have to do is make some selections to define what transactions and stock should be included in the reports.

The reports take data from the mSupply dashboard and generate excel reports in pre-defined templates. The mSupply server exports data to the mSupply dashboard periodically, normally no less frequently than daily, so the data is 'near-live'

So, for the app to reliably generate data, all these services need to be operating:

  • mSupply server
  • mSupply dashboard
  • UNFGPA LMA reports app
  • mSupply Web server - refer Server tab page for details.

Setup

Store tags

For the purposes of the LMA reports, mSupply needs to know which of the stores in your datafile are the 'Central store' and which are 'Decentralised stores'. You do this by adding appropriate store tags to the stores:

  • 'Central store' must be given the UNFPA_Central store tag
  • 'Decentralised stores' must be given the UNFPA_decentralised store tag

For details of how to add tags to stores, please see the Store tags page.

User permission

Make sure that the user has right to “Use the Dashboard”. This check box control the login rights to the “UNFPA LMA reports app”, without this the user will not be able to login.

Using the app

  • Since this is a web application, it cannot generate reports larger than 6 MB in size. If the report exceeds 6 MB in size, the generation process could fail.
  • We recommend using the filters (date, master-list and donors) to reduce the size of reports. Leaving these filters blank would include all data, except for:
    • The store by tag filter which defaults to all UNFPA_Central and UNFPA_decentralised stores.
    • The date range filter which defaults to a single day, 'Today'. You will likely want to change this, especially since unless you run this at the very end of the day, your will not even get a full day's worth of data!
  • We recommend keeping the number of stores to a minimal number.
  • The report that generates the largest size file is the Item Ledger report, the above recommendations should specially be followed for it, however, sometimes other reports may also generate large reports.

In your browser, enter the URL of your server followed by the port the app is running on (if you don't know what this is, ask the mSupply Foundation support@msupply.foundation. It should be something like this: 

https://example.com:4000

The login window will load which looks like this:

To login enter your mSupply username and password in the Username and Password fields and click on the Sign in button.

After successfully logging in, the report options window will be displayed:

On this window, make your selections to define what will go in your report:

  • Report to create drop down list: Select one of the following options:
    • Quarterley review report
    • LMA IP SC Fact Sheet report
    • Stock on date
    • Ledger
  • Include transactions in this date range in the report fields: click on the From and To dates to select the dates from calendars. Only transactions with a confirmed date that falls between the From and To dates will be included in the report.
  • Items to include in report drop down list: Contains a list of all the master lists in your datafile. Select one to include only items from that master list in the report.
  • Include stock from these donors in the report drop down list: You can choose one or more donors - if you do then only stock that came from them will be included in the report. You can also choose None (the default option), in which case a donor filter will not be applied, and all transactions will be included.
  • Store selection
    • If you selected the Quarterley review report, then it is only run on the UNFPA_Central store and you are not given a list of stores to include. If no store is tagged as UNFPA_Central, then this report is likely to fail.
    • If you select any report in the Report to create drop down list EXCEPT the Quarterley review report, an additional store filter is added to the bottom of the options:

The table shows a list of all the stores in your datafile.

  • To make it more manageable you can choose to display only stores with particular tags by selecting them in the Filter stores by tag drop down list.
  • If there are many stores, you can use the paging controls at the bottom of the window to move through the different pages and choose how many stores to display on each page.

Click on the SELECTED column checkbox to select a store to include in the report. You can click on the All on/off checkbox to toggle the SELECTED checkbox on and off for all stores on all pages at once. Only transactions and stock from the stores that have a check in the SELECTED checkbox will be included in the report.

When you are happy with your selections, click on the Create Report button to create the report. mSupply will tell you the report is being generated and will ask you where to save it or which application to open it with when it is finished. The files generated are .xlsx format spreadsheets.

Some of the reports do a huge amount of work and calculation so can take a long time to run, especially if you have chosen a lot of stores, a lot of items or a long period to be included in the report. So make yourself a good cup of coffee and go do something else for a while. Better that the computer does all the hard work instead of you, right? 8-)

Example report outputs

Quarterly review report

LMA IP SC Fact Sheet report

Stock on date report

Ledger report



Previous: 19.11. mSupply sync API | | Next: 20. Cold Chain Equipment

19.02. mSupply web server

About the mSupply web server

When mSupply's web server is running, it allows you to access mSupply data from any networked computer that has a web browser.

Security warning: We have had thousands of uses of our mSupply web server on the public internet since 2005. To date we have not had a security problem reported. However, we recommend you use SSL and a proper SSL certificate if your mSupply web server is publicly accessible. mSupply fully supports SSL. Contact us for certificate installation instructions.

The advantages of accessing mSupply in this way are:

  • It's easy. Most people are familiar with using a web browser.
  • It's low maintenance. You do not need to install any client software.
  • It's cost effective. Once you have purchased a web server licence an unlimited number of people can connect.
  • it's secure. The web server supports access using SSL, the standard for securing internet connections, stopping any malicious snooping of passwords or data.
  • It allows customer access to information. The web interface built into mSupply can easily be customised to allow clients, supplier or other interested parties to have restricted access to the mSupply information you wish to show them. We are also able to include order submission by customers, making it easy for them to place small orders, and have real time information on stock availability.
  • You can access mSupply from anywhere on the internet. Once we supply you with a password protected version of the web interface, you can access mSupply data from any internet connected computer.
  • It's fast over low bandwith connections. The mSupply web server allows you to provide access to mSupply from locations with only dial-up access.

mSupply web server functionality is being continually expanded according to client requirements. We welcome suggestions for more features.

Turning on the web server

The mSupply web server feature is not included in the regular mSupply licence; in order to use this function, an additional license is required. On application to Sustainable Solutions this can easily and swiftly be arranged.

For practice purposes, an evaluation version is available on our server - should you wish to access this, please contact us for instructions.

Choose File > Preferences, then click on “Web server” in the list.

You can choose to start the web server or have it start automatically when mSupply starts (see General preferences for more details on these preferences).

Technical note: By default mSupply is set to use port 8080. This is because the default port number for http access (80) on unix systems running mSupply can only be used by applications that have root privileges, and we don't want you to have to run mSupply as root! If this is a problem, we can supply you with an application that redirects traffic on port 80 to port 8080.

Setting up mSupply desktop users for mSupply Mobile (browser)

Your mSupply server needs to be set up for mSupply Mobile (browser) use. Follow these simple steps to get started:

  1. Create a virtual store to hold the remote facility's stock.
  2. Create new users for the store or give some existing users permission to login to it. Note: Make sure that only the users who will use the mobile interface have permission to login to this store.
    1. Note that the important setting for mobile access is the “Default store.” You'll need to turn on “store mode” for the store too, else you can't turn on “Default store.” For example, here's user Debbie set up so that when she logs into mSupply mobile she'll be logged into Tulagi Mini Hospital:
    2. Note that other user permissions (on the Permissions, Permissions(2) and Permissions(3) tabs) only apply to mSupply Desktop Users, not to mSupply Mobile Users.
  3. For the steps below, refer to Virtual stores for detailed instructions
    1. Make only the items which the remote facility will use visible in the new store.
    2. Make only the names which the remote facility will use visible in the new store.
    3. Ensure the store can receive transfers from the store that will be supplying it (This is done by ensuring that the receiving store's name record is visible to the sending store)
    4. Ensure “Pack to one” is turned on for visible items in each store.

Now you're ready - have fun!

Previous: 19.01. Introduction to web interfaces | | Next: 19.03. mSupply customer web interface

19.01. Introduction to web interfaces

mSupply data can be accessed through simplified web interfaces for a number of purposes. These web interfaces are simpler than the standard mSupply desktop interface described throughout most of this documentation. These web interfaces allow users to communicate over the internet with a store on your mSupply server. They are very flexible, being able to run on a wide variety of devices:

  • desktop / laptop
  • tablet (recommended for most applications)
  • smartphone (practicality depends on screen size and resolution!)

and operating systems:

  • iOS
  • Android
  • Windows
  • MacOS
  • Linux
  • any other operating system

In fact, anything which can run a browser and can get an internet connection can use an mSupply web interface. It means that you can now use the power of mSupply to manage stock at remote sites which don't have access to local IT infrastructure, except, of course, access to the internet!

We are continually developing the web interface services. For details on various components see:

  1. The mSupply Web Server
  2. The Web Stocktake module
  3. Customer Interfaces
    1. Mobile Customer Interface
    2. The 'Last Mile' Interface (under development)
  4. Supplier Interface
    1. Uploading and Downloading Web Tenders
    2. Supplier instructions for using the tender submission web interface
  5. mSupply Mobile API

To stop many large, simultaneous requests overloading the server, most calls to it from the web interfaces will return a maximum of 256 records. Pagination is provided in the interfaces to allow the retrieval of records above this.



Previous: 19. Remote User Web Interface | | Next: 19.02. mSupply web server

22.02. mSupply Mobile technical instructions for setup

The mSupply Mobile information has now been moved to the open source project website here: https://docs.msupply.foundation



Previous: 22.01. mSupply Mobile user guide | | Next: 22.03. mSupply configuration for mobile

22.03. mSupply configuration for mobile

Some configuration is required in mSupply to enable mobile usage. See the mSupply mobile user guide for details.

Previous: 22.02. mSupply Mobile technical instructions for setup | | Next: 23. Integration with other systems

22.01. mSupply Mobile user guide

The mSupply Mobile user guide has now been moved to our open source project website mSupply.foundation


Previous: 22. mSupply Mobile (Android) | | Next: 22.02. mSupply Mobile technical instructions for setup

20.06. Encounters

In mSupply-HIS an encounter is a record of an interaction between a patient and a hospital service. In this first version, the only type of encounter handled is an inpatient admission, but we will be able to use “encounter” to allow for outpatient consultations and interactions with laboratory, x-ray and other services in the future.

Entering a new inpatient encounter

Choose Patient > New encounter, or click the New Encounter button on the navigator.

Enter as much of the patient surname (and a comma, then the first name if you want to) then press <tab> to show a list of matching entries.

You can enter an expected discharge date (defaults to the next day), and where the patient was referred from and how they arrived at the hospital.

Once you choose a ward, a list of available beds is shown. If you choose to show the graphical view, you can see each bed, and you can click on a bed to assign the patient to that bed.

Available beds are shown in green, and beds that are occupied are shown in red (or if you are using the drop-down list, only beds that are available are shown). The selected bed is shown in yellow.

The admission date defaults to the current date and time, but you can change these and the available beds will be updated accordingly. Once you have chosen a bed, click OK or OK & Next.

Showing encounters

Choose Patient > Manage encounters, or click the Show Encounters button on the navigator.

The window has a side bar where you can show currently admitted patients or historical records. By default, it shows encounters for currently admitted patients who have been admitted in the last 30 days.

Clicking the Find entry in the side bar allows you to search for specific records.

Click the triangle beside the “By date” entry allows you to search for encounters entered today, yesterday, etc…

In the tool bar there is a New Encounter button, allowing you to add an encounter directly from there.

If you double-click an encounter you are shown the encounter details. The first tab lists the location(s) (i.e. the beds/wards occupied) during this encounter, and the fourth tab shows log records related to the encounter.

Once a patient has been discharged, their encounter data can now longer be edited.

Adding disease records

The second tab shows the disease records entered for this encounter. Clicking the Add Encounter Disease button will show this window:

The cursor will be in the ICD field, and you can type as much of the code or name as you know to find matching records. Double-click the record you wish to use in the list.

Choose from primary/secondary/tertiary for disease rank.

Enter any notes you wish to record.

You can enter the name of a clinician who diagnosed the condition if you want to. To do so, enter the start of the name and press <tab>… a list of matching clinicians is shown. Double-click on the clinician you wish to choose. If you want to add a new clinician, click the New button. A window to enter the clinician’s details is shown (see Prescribers). Enter details and click OK.

Once you have entered the disease details, click OK to close the list of diseases for the current encounter. You can now click the Add encounter disease button again to add another disease, or double-click an entry to edit it.

Adding procedure records

The third tab shows the procedure records entered for this encounter. Clicking the Add Procedure button will show this window:

As for encounter locations (see Encounters), you can specify a “bed” location (e.g. in a “ward” designated as an operating theatre) which is free for the specified time slot, and this can be viewed graphically. The list of procedures is generated from those previously entered via Procedures.

From the procedure list, you can also double-click on an existing procedure record to view/edit it.

Adding birth records

If the patient is female, there is an extra fifth tab which shows the birth records entered for this encounter. Clicking the Add Birth button will show this window:

  • The date/time defaults to the current date and time.
  • The last name defaults to that of the mother.
  • You can enter the birth weight (kg) and length (cm).
  • You can specify if it is part of a multiple birth, and whether the birth was normal, premature, or stillborn.

When the record is saved, a new patient record will be created for the baby, with its next of kin set to its mother. You can then add a separate encounter record for the baby if needed.

You can also double-click on an existing birth record in the list to view/edit it.


Previous: 20.05. Patients | | Next: 20.07. Other lists

20.03. ICD disease codes

ICD disease codes can be imported from File > Import ICD-10 codes.

They need to be formatted in a text file with 2 tab-delimited columns, defined as follows:

Column A B
Field ICD10 code disease description
Format Up to 8 alphanumeric characters (must be a unique value) Up to 30 alphanumeric characters

We have prepared a list of 65,000 ICD10 codes which can be imported. This could be a little large for practical use, as it may take too long for the user to select the code that they are after. It may therefore be appropriate to edit it down to a much smaller list of the diseases of interest.

In a synced system, this list will be synced out to all satellite sites, so there is a potential here to create several million sync out records. You have been warned.

Show ICD10 codes

On choosing Special > Show ICD10 codes you will be shown the current disease list.

Find

To search for a particular code, type as much of the code or description as you know, and matching entries will be shown. For example, typing “foot” will show all entries that have “foot” in their code (not that many, we imagine“!) or their description.

To Add a new entry, click the New button.

To Modify or view an entry's details, double-click the row.

Valid until...

This field allows you to use a code up until a certain date.

After that date is reached, you can't assign that code to any new encounters.

Note that you can use this field to disable use of a code at any time by entering yesterday's date and saving the record.


Previous: 20.02. Setting up wards and beds | | Next: 20.04. Procedures

20.01. Why a HIS module for mSupply?

As mSupply has become more widely used, it has become clear to us that many hospitals that use mSupply now have a functioning computer system in their pharmacies, and not much anywhere else. Other clients have spent close to $1 million on systems that we don't think are financially justified in their environments.

mSupply and mSupply-HIS

While mSupply and the HIS module are integrated, they also operate independently, and it is possible to use either module without using the other one.

By incorporating an HIS module into mSupply, it allows a hospital to cover the basics while sharing a server with the pharmacy, so a hospital that uses mSupply can start using the HIS module with little or no extra hardware costs. mSupply and the HIS module share a common patient database, meaning that the pharmacy and other hospital functions are integrated.

Many of the menu items in HIS mode are similar (or the same) as the equivalent menu items in mSupply e.g. Show clinicians, Show connected users, View log, Misc labels and Reminders.

What does mSupply-HIS do?

First, we should say that mSupply-HIS is not a fully-fledged Hospital Information System. It is designed to concentrate on a subset of a hospital's activities that form the core of its operations. The software is under constant development. As new features and facilities are added, we strive to ensure that the user guide and the graphics that it contains reflect these developments, but occasionally you may find that there are slight differences between the program itself and the documentation. These are usually of a minor nature, but should you have any difficulties, do please send us an email with details of your problem.

It does handle:

  • Patient registration and recording common static patient data.
  • Recording a hospital's wards and beds.
  • Recording inpatient admissions (admitting a patient, assigning them to a ward and bed).
  • Recordng ICD10 disease codes for each patient admission. You can assign multiple disease codes, and prioritise them (primary, secondary, etc..).
  • Moving patients to different wards/beds.
  • Recording discharge data (patient status at time of discharge)
  • Reporting on:
    • Bed occupancy rates as a whole and by ward, and other useful statistics e.g. average length of stay.
    • ICD10 statistics.


Previous: 29. Hospital Info System (HIS) Module | | Next: 20.02. Setting up wards and beds

20.05. Patients

Adding a new patient

Choose Patient > New Patient, or click the New Patient button on the navigator. This will show the following window:

Most of the fields are self-explanatory..

  • First & last name (mandatory)
  • Next of Kin
    • Here you can link a patient to another existing patient.
    • Type the last name then a comma, then the first name (or part thereof), and press tab. A list of matching names will be shown. Double-click on a name to select that person.
  • Patient Picture
    • You can add a patient picture by clicking the Add button.
  • Address and other contact details can be entered on the Contact details tab.

Showing and modifying patients

Choose Patient > Show Patients , or click the Show Patients button on the navigator.

To edit or view a patient’s details, double-click on their name in the list.

Finding patients

Click the Find button, and a small window is shown:

Type as much of the Last name, First name or Code as you know, and matching patients will be shown. Note that you can search all patients or restrict your search to only those in the already displayed list (the selection).

When you have a list of patients you can double-click on one to view the patient's details which will display up the following window:

Click on the different tabs to view different details. Note that on the Encounters tab you can double-click on the encounters shown to get their details.

Showing current admissions

You can also select Patient > Admitted to show a list of currently admitted patients.


Previous: 20.04. Procedures | | Next: 20.06. Encounters

20.09. HIS preferences

Organisation name: Enter the hospital name here.

Country: Enter the country you are located in.

Max picture size: Enter the maximum size of patient pictures that can be inserted. We suggest you set this value to 500KB.

Maximum number of users: Enter the maximum number of users that can log into the HIS system at one time. For example, if you purchase a 10 user licence, and assign 6 users to the HIS system, it will allow 4 users to log in to the pharmacy (mSupply) module.


Previous: 20.08. Statistics | | Next: 23. Integration with other systems

20.04. Procedures

Internally, a procedure in HIS is treated like a service item in mSupply, so many of the same concepts apply - see Items

The Special > Show procedures menu item allows you to track surgical and other procedures performed on patients. It brings up the following window:

After setting the parameters, and clicking on OK, it will either show the list of procedures:

in which case, you can double-click on a procedure to view/edit it or select New item to create a new one. Or, if there are no existing procedures, it will go straight to the Add procedure window:

The type of a procedure is fixed as “service”. As for items, once a procedure has been added, there are extra fields and tabs available. However, only a subset of the normal item fields are available.


Previous: 20.03. ICD disease codes | | Next: 20.05. Patients

20.02. Setting up wards and beds

Wards

Choose Special > Show Wards

You will be shown a window like this:

Click New Ward to add a ward.

Fill in the name and description. You can also add a note if you want to.

For now, you can ignore the coordinates.

Click OK to save the information and close the window.

Repeat the process for each ward.

Beds

Make sure you have set up wards before setting up beds.

Choose Special > Show beds…

Click New Bed to add a bed.

Fill in the bed number (or name).

If your wards have rooms, you can enter the room number or name. This is optional.

Choose the ward the bed is in from the drop-down list.

Click OK to save and close the window.

Modifying wards and beds.

To modify a ward or bed, show the list from the Special menu, then double-click on the entry you wish to modify.

Note that if you modify a ward or bed, all historical records will be updated. Therefor, don't change the name of a ward to a totally different name, and don't move a bed to a different ward.

Setting up user access

Preferences

Choosing the Preferences menu item from the file menu opens a window with a side bar. Clicking on a subject in the side bar shows the options for that subject:

General

Organisation name: Enter the hospital name here.

Country: Enter the country you are located in.

Max picture size: Enter the maximum size of patient pictures that can be inserted. We suggest you set this value to 500KB.

Maximum number of users: Enter the maximum number of users that can log into the HIS system at one time. For example, if you purchase a 10 user license, and assign 6 users to the HIS system, it will allow 4 users to log in to the pharmacy (mSupply) module.


Previous: 20.01. Why a HIS module for mSupply? | | Next: 20.03. ICD disease codes

20.07. Other lists

Apart from setting up beds, wards, ICD10 codes and clinicians, there are a number of other lists which can be customised from the Special menu:

  • Show discharges - add/edit the list of possible discharge reasons
  • Show religions - add/edit the list of possible patient religions (optional)
  • Show occupations - add/edit the list of possible patient occupations (optional)
  • Show ethnicities - add/edit the list of possible patient ethnicities (optional)
  • Show admitted from - add/edit the list of possible referrers (optional)
  • Show arrived by - add/edit the list of possible modes of transport used by the patient to attend the hospital (optional)


Previous: 20.06. Encounters | | Next: 20.08. Statistics

20.08. Statistics

Select Reports > HIS Statistics to bring up the statistics window.

You can select a time period from the date range pull-down menu or enter specific dates. By default, the summary statistics page is shown. A bar chart by ward for any column (except the first) can be generated by holding down the SHIFT key while clicking on any of the cells belonging to that column. If you prefer a pie chart, hold down CTRL instead of SHIFT.

If any of the individual wards are selected from the pull-down menu (instead of “Summary”), then it displays the data for that ward on a daily basis. In this case, a bar chart for any column (except the first) can be generated by holding down the SHIFT key while clicking on any of the cells belonging to that column.

In either mode, the displayed columns can be exported as a tab-delimited text file (which can then be imported into Excel or other spreadsheet application) by clicking on the Export button.


Previous: 20.07. Other lists | | Next: 20.09. HIS preferences

23.01. DHIS2 integration

DHIS2 is an open source data warehouse that can be used to store, aggregate and display health data. mSupply can push data periodically to a DHIS2 instance. Before this can happen, the data to be sent and any calculations that need to be made will need to be configured, as shown below.

DHIS2 data

DHIS2 stores data values that have 3 dimensions:

DHIS2 Dimension Description mSupply typical mapping
organisation unit Can be a facility, or a region The customer or store in mSupply
data element The type of data that is stored Usually a combination of an item code and the type-
for instance “SOH_368c74bf” for the stock on hand of Amoxycillin 250mg Capsules (using the universal code from https://codes.msupply.foundation/detail/368c74bf)
Period The historical time period associated with the data Same in mSupply

With these DHIS2 has the power to show different types of data for different places of interest on various graphs. It can also aggregate those values in hierarchical groups.

The types of data that you can send to DHIS2 from mSupply for an item:

  1. Current stock on hand
  2. Current months of stock on hand
  3. The amount of stock in adjustments
  4. The amount of stock received
  5. The amount of stock issued
  6. The amount of stock expiring within 90 days
  7. The amount of stock expired
  8. Average monthly consumption
  9. Days out of stock
  10. Stock at the beginning of the month
  11. Stock at the end of the month
  12. Whether the item is currently stocked out

Setup

Items

To send item details to DHIS2, mSupply has to know the identity of each of its items in DHIS2. There are two options for doing this:

  1. Use the item's universal code. See the 4.01.01 Items - General tab section for details on setting this.
  2. Use the DHIS2 UID or the DHIS2 code. Choose which one you want to use then enter those values in an item's custom field 1, 2, 3 or 6 (the 3 text custom fields).

The final step in setting up items is to tell mSupply which ones to send data to DHIS2 for. Do this by checking the Include in DHIS2 data push checkbox on an item's details window - see the 4.01.01 Items - General tab section for details on setting this.

Stores

Stores in mSupply correspond to org units in DHIS2. mSupply needs to know the Org unit reference for each of the stores that data needs to be sent to DHIS2 for.

To do this, add a “Dhis2Code” store custom field containing the Org unit reference to each store you want to send data to DHIS2 for. For all stores you don't want to send data to DHIS2 for, simply leave the “Dhis2Code” custom field empty.

For details on how to set store custom codes see the 26.07. Virtual stores section.

mSupply preferences

Before you can send mSupply data to a DHIS2 instance, you need to tell mSupply where the data has to go, what data to send and where the information comes from. To do that, go to File > Preferences and click on the DHIS2 tab to get to this window:

  • Use DHIS2 checkbox: If checked then the DHIS2 interface is turned on and data is sent to DHIS2. If it is unchecked then the interface is turned off and no data is sent to DHIS2. Turning it off also disables data entry in the other fields on this page.
  • Basic authentication checkbox: If checked then mSupply will use basic authentication in the call headers when sending data to DHIS2. If it is unchecked then mSupply will use authentication in the body of the calls. This setting should match the way the DHIS2 instance has been configured.
  • URL: The URL of the DHIS2 database including the port if any.
  • Username: The username mSupply will use to access the DHIS2 database.
  • Password: The password mSupply will use to access the DHI2 database.
  • Client: Only visible and used if Basic authentication is not checked. The client name mSupply must use to access the database.
  • Secret: Only visible and used if Basic authentication is not checked. The secret that is used for mSupply to access the DHIS2 database. No need to enter this if none was provided.
  • Setup: Here you choose how to identify the elements of data that you send to DHIS2 must be identified. Your choice depends on how DHIS2 is configured.
    • Using category option combo: Choose this if DHIS2 is using attribute option combos where there is one category option combo assigned per data element (AMC, stock on hand etc.) for an entire data set. For this option, you need to tell mSupply what the DHIS2 category option combo ID is for each data element you want to push (i.e. Active column is checked) in the Data elements to push table.
    • Different data elements per item: Choose this if there is a different identifier for each data element for each item. These identifiers need to be entered for each item in item user fields or item custom fields - you enter the name of the field the value is stored in into the Data elements to push table in the Custom field name column.
    • Push only 1 data element: Choose this if you are only pushing a single data element (e.g. AMC, stock on hand etc.) for each item to DHIS2. In the Data elements to push table you must check only a single box in the Active column and no values need to be entered in the Category option ID or Custom field name columns.
  • Data elements to push In this table, select the data elements that you want to push for each mSupply item.
    • Active column: Check the checkbox for each data element you want to send for an item. Click on the checkbox to toggle it on and off.
    • Category option ID column: Required if Using category option combo is selected in the Setup section. This is the DHIS2 category option ID for the data element.
    • Custom field name column: Required if Different data elements per item is selected in the Setup section. Enter the corresponding item custom field name used to identify the item corresponding DHIS2 data element code.
    • Interval column: Select the interval between successive sends of the data element. Select one of monthly, weekly, daily, first day of the month and last day of the month by clicking on the down arrow in the cell and selecting the appropriate option.
    • Push data basis column: Select the basis of the data to be sent, one of previous month or current day. Again, click on the down arrow in the cell and click on the appropriate option to select it.
    • Prefix column: If the data element ID needs to have a prefix added to it before it is sent to DHIS2 then enter that in this column.
  • Data set ID: Enter the ID of the dataset in DHIS2 that you want to push the data to.
  • Period format: Enter the format to send the period information to DHIS2. Something like “YYYYMM”, where YYYY represents the year, MM represents the month and DD represents the day.
  • Item field reference: Required for “Using category option combo” and “Push only 1 data element” setup. This tells mSupply where the DHIS2 item reference is stored in mSupply. If Universal code is selected then the code shown in the Universal code field of an item's details page is used (see the 4.01.01. Items - General tab page for details). If Custom field is selected then the DHIS2 item reference is taken from the item custom field entered in the accompanying text field (which should contain one of “user_field_1”, “user_field_2”, “user_field_3” and “user_field_6” (see the 4.01.01. Items - General tab page for details of these custom fields).
  • Data element ID scheme: This tells mSupply what kind of DHIS2 item identifiers are stored in mSupply (in the place defined by the Item field reference section above), item codes or UIDs.
  • Store field reference: Enter the name of the store custom data field that identifies which stores to send data to DHIS2 for. Data will be sent for all stores that have a value in the store custom data field with this name.
  • Round off checkbox: If checked then mSupply will round numerical data values to the nearest whole number as some DHIS2 setup only accept integers.
  • No. of items per payload: Enter the number of pieces of information to send in a particular call to the DHIS2 server. If there are more than this number of pieces to send then they will be split up into separate calls with this number of pieces of information in them. Helpful if there is a lot of information to send but the DHIS2 server can't handle the volume of information (which usually results in internal errors being returned).
  • Test connection button: Click this to test the connection to the DHIS2 server. You will be shown a message that tells you whether mSupply was able to connect to the DHIS2 server with the credentials you have provided.
  • Manual push data button: Click this button to immediately attempt to push the data as setup in this window to DHIS2. The data will, of course, be pushed on a current day basis. View the log (see the 25.19. The system log section for details) to see the results of the attempt.

If this page already has settings entered and they have been used to successfully connect to the DHIS2 database then a “Last successful connection: date & time” message will show next to the Test connection button.

After entering the values you should click on the Test connection button to save the credentials and check that mSupply can now access the DHIS2 database. If the connection is successful you will see a green “Connection successful” message next to the button.

If the connection is not successful you will see a red “Authentication failed” message next to the button. Check your settings, edit them as necessary and try again. The connection problem may not be the credentials, it could be something else like the settings for firewalls between mSupply and the DHIS2 database.

Once configured, a scheduler will run and regularly send data from mSupply to DHIS2. If there are any errors these will be saved in the log (see the 25.19. The system log page for details).

Of course, once you have told mSupply where all the data is stored, you have to actually enter the DHIS2 item identifiers and Store identifiers into mSupply.

Connections to DHIS2 have been configured successfully for Laos and countries that are part of the Tupaia project including Kiribati, Tonga, Solomon Islands, Cook Islands and Vanuatu. And lots more!

Previous: 23. Integration with other systems | | Next: 23.02. DHIS2 LMIS integration

23.02. DHIS2 LMIS integration

DHIS2 is an open source data warehouse that can be used to store, aggregate and display health data. It has also been modified to be used as a simple stock reporting and ordering tool at small health facilities. mSupply can interact with this functionality to receive the stock on hand reports and requisitions and create replenishment orders for the facilities based on that information. This page describes how it works and what setup must be carried out in mSupply.

The process

Fetching requisitions

In this scenario, the supplying facility is using mSupply and the requesting facility is using a DHIS2 Event app. The requesting facility creates and saves a requisition in the event app and it is saved to the DHIS2 database. On a daily basis, mSupply checkes the DHIS2 database for completed requisitions, retrieves them and sends them to the supplying store's copy of mSupply as a customer requisition. The process is illustrated in this diagram:

Acknowledging shipment receipts and sending shipment transactions

The next part of the process is that the sending store sends goods to the facility that requested them with the requisition. The goods are sent with a packing list that contains a QR code. When the receiving facility receives the goods they add the consignment to the DHIS2 RTS capture app by scanning the QR code and check what has arrived. When they are happy the receiving facility marks the consignment as complete.

On a daily schedule mSupply checks the DHIS2 database for complete consignments and retrieves them (at the same time mSupply fetches stock on hand figures for the items in the various facilities. This is not shown in the diagram below). mSupply processes the details of the consignment and sends details of the stock supplied for the consignment to the DHIS2 server. The DHIS2 server then sends the updated stock levels to the RTS capture app at the requesting facility.

This process is illustrated in the following diagram:

Setup

Items

To send item details to DHIS2, mSupply has to know the identity of each of its items in DHIS2. There are two options for doing this:

  1. Use the item's universal code. See the 4.01.01 Items - General tab section for details on setting this.
  2. Use the DHIS2 UID or the DHIS2 code. Choose which one you want to use then enter those values in an item's custom field 1, 2, 3 or 6 (the 3 text custom fields).

The final step in setting up items is to tell mSupply which ones to send data to DHIS2 for. Do this by checking the Include in DHIS2 data push checkbox on an item's details window - see the 4.01.01 Items - General tab section for details on setting this.

Stores

Stores in mSupply correspond to org units in DHIS2. mSupply needs to know the Org unit reference for each of the stores that data needs to be sent to DHIS2 for.

To do this, add a “Dhis2Code” store custom field containing the Org unit reference to each store you want to send data to DHIS2 for. For all stores you don't want to send data to DHIS2 for, simply leave the “Dhis2Code” custom field empty.

For details on how to set store custom codes see the 26.07. Virtual stores section.

mSupply preferences

Before you can send data to and retrieve data from a DHIS2 LMIS instance, you need to tell mSupply where the data has to go and come from. To do that, go to File > Preferences and click on the DHIS2 LMIS tab to get to this window:

  • Use DHIS2 checkbox: If checked then the DHIS2 interface is turned on and data is sent to and pulled from DHIS2. If it is unchecked then the interface is turned off and no data is shared with DHIS2. Turning it off also disables data entry in the other fields on this page.
  • Basic authentication checkbox: If checked then mSupply will use basic authentication in the call headers when sending data to DHIS2. If it is unchecked then mSupply will use authentication in the body of the calls. This setting should match the way the DHIS2 instance has been configured.
  • URL: The URL of the DHIS2 database including the port if any.
  • Username: The username mSupply will use to access the DHIS2 database.
  • Password: The password mSupply will use to access the DHI2 database.
  • Client: Only visible and used if Basic authentication is checked. The client name mSupply must use to access the database.
  • Secret: Only visible and used if Basic authentication is checked. The secret that is used for mSupply to access the DHIS2 database. No need to enter this if none was provided.
  • Test connection button: Click this to test the connection to the DHIS2 server. You will be shown a message that tells you whether mSupply was able to connect to the DHIS2 server with the credentials you have provided.
  • Send errors to this email address textbox: All errors will be sent to theis email address. Enter multiple email addresses by separating them with a semicolon (;).
  • Data set ID: Enter the ID of the dataset in DHIS2 that you want to push the data to.
  • Period format: Enter the format to send the period information to DHIS2. Something like “YYYYMM”, where YYYY represents the year, MM represents the month and DD represents the day.
  • Item field reference: Required for “Using category option combo” and “Push only 1 data element” setup. This tells mSupply where the DHIS2 item reference is stored in mSupply. If Universal code is selected then the code shown in the Universal code field of an item's details page is used (see the 4.01.01. Items - General tab page for details). If Custom field is selected then the DHIS2 item reference is taken from the item custom field whose name is entered in the accompanying text field (which should contain one of “user_field_1”, “user_field_2”, “user_field_3” and “user_field_6” (see the 4.01.01. Items - General tab page for details of these custom fields).
  • Data element ID scheme: This tells mSupply what kind of DHIS2 item identifiers are stored in mSupply (in the place defined by the Item field reference section above), item codes or UIDs.
  • Round off checkbox: If checked then mSupply will round numerical data values to the nearest whole number as some DHIS2 setups only accept integers.
  • Name field reference textbox: The name of the name custom field used to store the ID of the corresponding name in DHIS2.
  • Store field reference textbox: The name of the store custom field used to store the ID of the corresponding store in DHIS2
  • Order program ID textbox: Put the ID of the DHIS2 Order program used for requisitions in this field. Click the Manual pull data button next to this field to immediately fetch completed requisitions from DHIS2, rather than waiting for it to be done on the automatic schedule.
  • Receipt program ID textbox: Put the ID of the DHIS2 Receipt program used for shipment receipts in this field. Click the Manual pull data button next to this field to immediately fetch completed consignments from DHIS2, rather than waiting for it do be done on the automatic schedule.
  • STR program ID textbox: Enter the ID of the DHIS2 STR program used for storing Stock on Hand values into this field. Click on the Manual pull data button next to this field to immediately fetch stock on hand figures for facilities, rather than waiting for it do be done on the automatic schedule.
  • RTS SOH Raw data button: Click this to display the raw stock on hand data pulled from DHIS2.
  • Data elements table In this table, select the data elements that you want to pull from DHIS2 for each mSupply item.
    • Active column: Check the checkbox for each data element you want to pull for an item. Click on the checkbox to toggle it on and off.
    • Data element column: Read only, the name of the element the settings in this line are for.
    • Program data element ID column: The ID of this data element in the Program.
    • Program stage ID column: The ID of the program stage this data element belongs to.
    • Attribute ID column: The ID of the attribute this data element has in the program stage.

If this page already has settings entered and they have been used to successfully connect to the DHIS2 database then a “Last successful connection: date & time” message will show next to the Test connection button.

After entering the values you should click on the Test connection button to save the credentials and check that mSupply can now access the DHIS2 database. If the connection is successful you will see a green “Connection successful” message next to the button.

If the connection is not successful you will see a red “Authentication failed” message next to the button. Check your settings, edit them as necessary and try again. The connection problem may not be the credentials, it could be something else like the settings for firewalls between mSupply and the DHIS2 database.

Once configured, a scheduler will run every 5 minutes and regularly pull data from and send data to the DHIS2 LMIS instance. If there are any errors these will be saved in the log (see the 25.19. The system log page for details).



Previous: 23.01. DHIS2 integration | | Next: 23.03. FrontlineSMS integration

23.04. mSupply eLMIS interface

eLMIS stands for Electronic Logistics Management and Information System and is a version of OpenLMIS developed under the USAID Deliver project. mSupply has an interface for receiving orders from eLMIS and sending shipment details back to it.

Because eLMIS does not have an API, the mSupply interface uses files stored in a commonly accessible location to share information.

Setup

Before the interface can be used it has to be setup correctly. These are the setup steps you need to follow:

1. Create folders in a commonly accessible location

A computer file storage location must be created somewhere that is accessible by both the mSupply and eLMIS servers to directly write files. If a common location does not exist because the mSupply and eLMIS servers are on separate non-linked networks you can create a separate location on each of the mSupply and eLMIS servers and link them using a file synchronisation utility such as Dropbox.

When you have the centrally accessible location sorted out, create a main folder then some sub-folders according to the following:

In this picture we have called the main folder Transfer. You can name yours anything you like but the other folders must have exactly the same names as shown.

2. Enter the setup information into mSupply

Go to the mSupply Special > Preferences window and select the eLMIS tab. Please see the 16.01. General preferences > elmis_tab section in this user guide for information on these settings.

3. Setup the customer budgets in mSupply

The interface assigns the incoming orders (turned into customer invoices in mSupply - see below) to the correct annual budget period for customers. The budget year is assumed to start on 1st July. So, create a budget period starting on the 1st July in the current budget year and assign that budget period to all the customers you will be importing orders for via this interface. See the 8.08. Customer budgets page for details on doing that.

4. Setup eLMIS
  1. Set eLMIS to export its order files to the main folder/Order/Incoming folder when orders are created.
  2. Set eLMIS to look for incoming shipment files in the main folder/Shipment/Incoming folder on a regular basis.

Please consult your eLMIS documentation for information on these steps.

What the interface does

When it's running the interface does 2 things:

1. Processes new orders from eLMIS

Each time the interval set in the settings elapses, mSupply checks the main folder/Order/Incoming folder for new order files from eLMIS. If it finds one it reads the file and turns it into a customer invoice. The customer invoice will have these features:

  • its status will be “sg” (suggested)
  • its Their ref field will have the value “eLMIS:XXXX.” where XXXX is the eLMIS order number
  • it will have a placeholder line for every item in the order file

The Their ref field makes a customer invoice created by the interface easy to spot. Feel free to add anything to the Their ref field after what the interface has put in there but not before. mSupply uses it to generate the shipment file for this order later on.

See the Order file format section below to see the format the order file must have.

If the order is successfully converted into a customer invoice the eLMIS order file is moved from main folder/Order/Incoming to main folder/Order/Processed.

If there is a problem and the order file is not converted into a customer invoice then the order file is moved to main folder/Order/Error. In addition, an error file is created and is also placed in main folder/Order/Error. The error file has the name “XXXX-YYYY-MM-DD-HH-MM.err.csv” where XXXX is the order file's filename without its extension. See the Error file format section below for the format of the error file. An error email with the error file attached will also be sent to the error email address set in the mSupply preferences.

2. Creates eLMIS shipment files for confirmed customer invoices

When a customer invoice that was created by this eLMIS interface (mSupply recognises them by the contents of the “Their ref” field) is confirmed then mSupply will create a shipment file for it. The shipment file will have the filename “SHPXXXX.csv” (where XXXX is the invoice number of the customer invoice) and will be saved to the main folder/Shipment/Incoming folder.

See the Shipment file format section below for the format of this file.

If there are any problems creating the shipment file, mSupply will display a message describing the problem. Please note that you will not be able to confirm the customer invoice until all the problems preventing the creation of the shipment file are corrected.

Using the interface

Well, the good news is that day-to-day you don't have to do anything. The interface will continue running quietly in the background processing order files and creating shipment files as the customer invoices are confirmed.

Periodically you should check the error email address set in the eLMIS preferences for messages about errors. Remember the order files that have caused errors can be found on the main folder/Order/Error folder. Note that mSupply does not put anything in the main folder/Shipment/Error folder - eLMIS only uses that folder when processing the shipment files.

The only other time you will hear anything from the interface is if mSupply detects an item on a customer invoice that wasn't in the original eLMIS order. This will happen if one of the item placeholder lines was replaced with a different item (e.g. because of low stock or a preferred item is to be used). In this case, mSupply will show a window and ask you to tell it which item on the original order you replaced with the item in question. Once you have selected the item that has been replaced mSupply will continue creating the shipment file.

eLMIS order file format

This a text file in csv format, each element of data is enclosed in “ characters. The first line of the file will contain headers only (ignored by mSupply), subsequent lines contain data in the following order:

  1. Warehouse code. This is the code the store in mSupply that this order (customer invoice) belongs to.
  2. eLMIS order ID. Stored in the Their ref field of the customer invoice.
  3. Item code. The code of the item being ordered.
  4. Product name. The name of the item, as stored in eLMIS. For reference only, not used by mSupply.
  5. Customer ID. The code of the customer this order is from.
  6. Quantity. The number of packs (default pack size) of this item ordered.
  7. First day of reporting Period. The date of the first day of the reporting period (budget period in mSupply) to which this customer invoice is to belong in the format YYYY-MM-DD.
  8. Line number. The number of this line in the order.
  9. Order date. Date the order was placed.
  10. Price. The unit price of the item. Optional, might not be sent from eLMIS, not used by mSupply.

Shipment file format

This a text file in csv format with the name “SHPinvoice number.csv” where invoice number is the customer invoice's number in mSupply (e.g. “SHP1234.csv”). The first line will always be “Order No, Product Code, Batch, Quantity Shipped, Cost, Packed Date, Shipped Date, Facility Code, Quantity Ordered, Substituted Product Code, Substituted Product Name, Substituted Product Quantity” (i.e. the column headers only), subsequent lines contain data in the same column order, each element enclosed in ” characters.

Error file format

A text file with the name “filename without extension-YYYY-MM-DD-HH-MM.err.csv” where filename without extension is the filename of the order file which the error file is generated for and YYYY-MM-DD-HH-MM is the current date and time in 24 hour format (e.g. ORD12345-2015-05-30-14-35.err.csv).

The file contains 3 lines:

  1. file name without extension: Error description where file name without extension is the eLMIS order file name without its extension and Error description is a description of the error that has been found e.g. “ORD10002: Facility code not found”
  2. Line number: XX where XX is the number of the line in the order file which has the error. e.g. “Line number: 3”
  3. Hint: Hint to fix it where Hint to fix it is a hint on how to fix the error e.g. “Hint: Make sure facility code is available in eLMIS, enter the facility code into the file”



Previous: 23.03. FrontlineSMS integration | | Next: 23.05. Moneyworks integration

23.03. FrontlineSMS integration

mSupply has the ability to integrate with your FrontlineSMS installation. This allows you to send your current stock levels to mSupply using an SMS (text) message from any mobile phone. This is particularly useful if, for example, you are a mobile or remote health post or dispensary which doesn't have internet access and only needs to send in information about a few items at a time.

To get mSupply talking to your FrontlineSMS installation, follow these simple steps:

1. Tell mSupply the details of your FrontlineSMS database

You do this on the FrontlineSMS tab of the mSupply preferences page (File > Preferences). See here for a detailed description of how and what to set.

2. Set the SMS code and pack size of the items you want to receive information about

Because SMS messages need to be kept short (they are only allowed a limited number of characters), instead of writing the full name of an item in an SMS message you simply write a short code which represents it. It is impossible for mSupply to know the pack size of the items being counted in the remote store so you also need to enter a pack size to be used for calculating item quantities from the pack quantities supplied in an SMS. You set both the SMS code and SMS pack size for an item in the Misc tab of the item's Item details window (via the Items > Show items menu). For detailed instructions see the 'The Misc(ellaneous) tab' part of 'The Item Details Window' section on the items basics page here.

3. Add SMS senders as contacts to customers

mSupply needs to know which of your customers an SMS message has been sent from. To give it this information you simply add each mobile phone number that will be sending messages to mSupply to the appropriate customer as a contact. To do this use Special > contacts (see here for details) or Customers > show customers, select the customer, go to their contacts tab, click on the Add contact icon and enter the contact's details.

Please note: whichever way you do it, the phone number must be entered exactly as it is recorded in FrontlineSMS (it will probably include the international dialling code e.g. +977 but this will vary with phone service providers). You can find out how FrontlineSMS stores a sender's number by sending a dummy text message and viewing its details in FrontlineSMS.

4. Make sure that emailing is turned on in mSupply

mSupply will inform the people selected in the preferences (see step 1 above) by email when a message has been received and is successfully processed or has an error. But mSupply can't send the emails if you haven't configured it to. To set up emailing, go to File > Preferences and click on the Email tab. See the E-mail section of the general preferences page here for details of the various settings.

OK, that's the setup complete and you're ready to…

5. Send an SMS message to mSupply

The text message you send to mSupply must be in the correct format. Any mistakes and the message will be rejected and will have to be resent. The correct format is this:

keyword item_code item_value item_code item_value…

keyword: This is the keyword you set in the Frontline preferences (step 1 above) that enables the software to recognise a message as intended for mSupply. If this keyword does not exactly match what is set in the FrontlineSMS preferences mSupply will ignore the message.

item_code: An SMS code identifying an item in mSupply. You set these in step 2 above.

item_value: The number of the item represented by item_code that you have in stock. Obviously, the number must not be negative!

You can have as many item_code and item_value pairs as a single text message will allow. But they must always be paired. If mSupply finds an item_code not matched with an item_value it will reject the message and it will need to be resent.

Every single element (the keyword, an item_code or an item_value) of the message must be separated by a space.

To make all this clear, let's have some examples:

  • A valid text message: msm am 1000 lp20 2000 cf 1 (msm is the keyword; am, lp20 and cf are item SMS codes; 1000, 2000, 1 are amounts of the corresponding items in stock and each element is separated by a space)
  • An invalid text message: msm am 1000 lp202000 cf 1 (msm is the keyword; am, lp20 and cf are item SMS codes; 1000, 2000, 1 are amounts of the corresponding items in stock but the space between lp20 and 2000 has been missed out. mSupply will interpret lp202000 is an item SMS code which doesn't have a paired value and reject the message)
  • A valid text message: s 201 1000 102 3000 lf 200 (s is the keyword; 201, 102, 1f are item SMS codes; 1000, 3000, 200 are amounts of the corresponding items in stock and each element is separated by a space)
  • An invalid text message: msm am 1000 lp20 -2000 cf 1 (everything's OK except the -2000. A stock value can't be negative so mSupply will reject the message)

It is OK to enter multiple spaces where there should only be one or to add leading and trailing spaces to the message. Because mSupply is clever software it will know what you meant and ignore the extra spaces.

When an SMS message has been received by mSupply an email will be sent to the recipients selected in the FrontlineSMS preferences (set in step 1 above). It will tell them that it has been successfully processed or that there was an error (and will give details of the error). In the case of a successful message mSupply will also create a reminder (see here for information about reminders) for the recipients selected in the FrontlineSMS preferences. In the case of an error, the e-mail recipient should contact the sender to correct the mistake and resend their message.

6. View and complete the stock history record

When mSupply has successfully processed an SMS message it produces a Customer stock history record of the appropriate type (imprest or stock history) for the appropriate customer in their supplying store. See Customer stock history records for more information on these. The stock history record will have a status of 'suggested' and must be viewed and completed by someone in mSupply before it is turned into a customer invoice.

The point of creating reminders for people on successful receipt of an SMS message is that the customer stock histories don't get forgotten!

7. If anything goes wrong

Any errors which occur during the processing of SMS messages are sent by e-mail to the people selected in the FrontlineSMS preferences so that appropriate action can be taken. The error messages detail the problem to make troubleshooting easier. The most likely problems with SMS messages are:

  • Sender phone number not added as a contact to a customer in mSupply or not added exactly as it appears in the FrontlineSMS database.
  • Keyword forgotten or wrongly typed. In this case the message will appear to have disappeared into thin air! mSupply will ignore it because it is the keyword that identifies it as an mSupply message.
  • Space missing between message elements. You will receive an error message about item codes and item values not being paired in this case.

Please note that all SMS and FrontlineSMS database error messages are also written to the log: to view them go to Special > View log (if you want to display only SMS errors select the 'SMS error' item in the right hand drop down list in the log display window). This can be very helpful for working out if anything's gone wrong, especially if emailing is not working (because you've forgotten to set it up - in step 1 above - or your internet connection is broken or slow).



Previous: 23.01. DHIS2 integration | | Next: 23.04. mSupply eLMIS interface

23.08. HL7 and Tamanu/Patis Plus integration

mSupply supports HL7 integration with HL7 compliant APIs. Currently, this is limited to retrieving information from HL7 Servers, mSupply does not send patient data.

When using mSupply Synchronisation systems, this must be configured on the central server. Data retrieved from the integration is stored on the mSupply Central Server and distributed via sync to remote sites. Data is also available via remote patient search.

Tamanu and Patis Plus are the primary use cases for this integration at the moment, and the only products we actively test the integration with. If you require integrating with other HL7 servers, please contact us!

Configuration

Choose File > Preferences from the menus and click on the HL7 Integration tab on the left hand side. This window opens:

To turn on HL7 configuration start by ticking the option Use HL7 integration. Then select either Use HL7 patient feed or Use HL7 patient search; these are explained below.

Then enter:

  • URL: The URL of the HL7 compliant server you wish to connect to.
  • Host name: The name of the service that you are integrating with. e.g. “Demoland Tamanu Server”
  • Email: The username being used for the integration authentication. May be an email or any other text value.
  • Password: A strong password provided for integration authentication.
  • Limit: The maximum number of patient records to fetch for each API request.
  • Suffix path: The extra part to add to the URL above to reach the endpoint for pulling patient information into mSupply.
  • Last updated: Read only field showing when the last successful data pull was made.
  • Medication dispense: Check this checkbox if you want to send dispensed data (i.e. prescriptions) to Patis Plus.
  • URL: Enter the URL of the Patis Plus or other prescription consuming software here.
  • Send emails to this email address: Enter the email address you want errors encountered when sending prescriptions sent to.
  • Start date: the date to start sending prescriptions to the software in the URL field.
  • Manual push data button: Click this to send the prescription informaiton immediately rather than waiting for the automatic scheduler to do it.

All these should be provided by the organisation hosting the HL7 server that you wish to integrate with.

Press the Test connection button to validate the details you've entered and save them.

Patient Feed

This is the default and recommended option to use if available. The patient feed will regularly request all recent changes to patients and their related documents available on the HL7 Server. Supported records will seamlessly be integrated into the mSupply Central Server database.

The patient search option allows remote searches done from mSupply remote sites to additionally search the integrated HL7 server seamlessly, and return both mSupply and HL7 results in the mSupply user interface.

Note that if there is an error communicating with the HL7 server during the in the patient search or feed function then an email is automatically sent to mSupply support so that they are aware.

Which one?

Patient feed is the recommended option as it solves multiple drawbacks of Patient search:

  • Patient search is only available when using “remote patient search” on remote mSupply sites. This means it does not work on non-sync systems, and on sync systems the option does not serve any dispensaries that are active on the central server. As Patient feed gets all updates of all patients from the HL7 server and saves them in the mSupply database, they are available in all contexts.
  • Patient search does not retrieve updates of patients from the HL7 server, only the state of the patient when first searched and added via the integration. Patient feed gets all future updates for all patients from the HL7 integration.
Medication dispense

If this is turned on then all finalised prescriptions are sent every hour to the prescription consuming software at the address given in the URL field.



Previous: 23.07. NHLMIS integration | | Next: 23.09. iVEDiX integration

23.09. iVEDiX integration

mSupply has an interface with the iVEDiX reporting API. The interface allows the automatic sending of batch and transaction information to the iVEDiX reporting platform.

The preferences that define how this interface works are managed on the iVEDiX tab of the File > Preferences menu. The tab looks like this:

NOTE: the fields on this page are disabled if mSupply's synchronisation system is not in use.

  • Send information to iVEDiX checkbox: If this is checked then mSupply will automatically send information about transactions and new batches to the iVEDiX platform. If it is unchecked then no information is sent to iVEDiX.
  • iVEDiX API URL: The URL of the iVEDiX API to send information to.
  • iVEDiX API key: The authentication key to be sent to authorise communictaion with the API.
  • Interval between retries: The number of minutes to wait between attempts to resend information that fails to reach the iVEDiX API for any reason.
  • Send now button: If this is clicked, all information waiting in the failed queue to be sent to the iVEDiX API is sent immediately.
  • Number of times to retry sending: The maximum number of times to retry sending information to iVEDiX. Once a piece of information has failed to be sent this number of times, the failure becomes permanent: it is removed from the send queue and the final failure is logged.
  • Send errors to this email address: All errors sending information to the iVEDiX platform are sent to this email address. You can enter multiple email addresses in here by entering them one after another separated with a semicolon (;).

What it does

Sending batches

Batches are sent to iVEDiX whenever a stockline is created (e.g. when a supplier invoice or inventory adjustment-add is confirmed) or updated (which means that either the batch or expiry date is changed) in any store with a WHXXXX code (where XXXX is a 4 digit number) or its corresponding malaria store (which will have a matching GF-MAL-XXXX code).

The batches are sent using the /batch/createUpdate endpoint of the API using these fields:

  • batchNumber: the stock lines's batch.
  • availableDate: the current date and time in ISO format.
  • expiryDate: the expiry date of the batch. “31/12/3000T00:00:00” is sent if the batch has no expiry date.
Sending transactions

Transactions are all sent to iVEDiX when they are confirmed. Transactions are only sent from stores having a WHXxXX code or a corresponding GF-MAL-XXXX code and transactions in any GF-MAL-XxXX store are sent as if they were in the WHXXXX store. Stock transfers (or credits) between a WHXXXX or GF-MAL-XXXX store are ignored and not sent to iVEDiX.

If a transaction is edited or a line added or removed from it, the whole transaction is sent again, in its new form, to iVEDiX.

The transactions are sent using the /inventoryStockStatus/updateInventory endpoint of the API using these fields:

  • transactionId: the transaction's UUID.
  • transactionDate: the transaction's confirmed date in ISO date format.
  • warehouse: the store code; WH0004, 6 or 7 and the corresponding Malaria stores take the corresponding main store code.
  • donor: the transaction category of the transaction.
  • productCode: the item code.
  • batchNumber: the batch of the stock.
  • creditDebit: “Credit” for credit (stock increase), “Debit” for debit (stock decrease).
  • transactionType: “GoodsIssued” for customer invoices, “GoodsReceived” for supplier invoices and customer credits, “TradeReturns” for supplier credits, “PositiveAdjustment” for inventory adjustment-adds and “NegativeAdjustment” for inventory adjustment-reduces. For a cancelled transaction the appropriate opposite type is used.
  • quantity: pack size x number of packs for this transaction line.

There are actually two schedulers running to control sending transactions to iVEDiX: one picks up all new transactions and sends them for the first time. The other picks up all the failed transactions and sends them again until they have reached the maximum number of retries before permanent failure.

Errors

If errors are encountered during either of the sending processes then the information to be sent is entered into a queue. All pices of information (batches or transactions) in that queu are attempted to be resent after the number of minutes stored in the Interval between retries field. When a piece of informaiton is successfully sent it is removed from the queue. If a piece of information is not sent successfully after the number of retries in the Number of times to retry sending field then it is removed from the queue, the final failure is logged (see the 25.19. The system log page for details on how to view the log) and an email giving details of the error is sent to the email address stored in the Send errors ro this email address field.



Previous: 23.08. HL7 and Tamanu/Patis Plus integration | | Next: 23.10. Siglofa integration

23.05. Moneyworks integration

For information regarding exporting date to the accounting software Moneyworks please refer to the 17.20. Exporting invoices to Moneyworks section.



Previous: 23.04. mSupply eLMIS interface | | Next: 23.06. MYOB

23.06. MYOB

For information regarding exporting date to the accounting software MYOB please refer to the 17.21. Exporting to MYOB section.



Previous: 23.05. Moneyworks integration | | Next: 23.07. NHLMIS integration

23.07. NHLMIS integration

Before you turn on the NHLMIS integration two important setup steps must be taken:

  1. All store, item, customer and supplier codes must match those used in NHLMIS. If this step is not taken;
    1. stock data you send will be rejected by NHLMIS because the items the stock belongs to will not be recognised
    2. requisitions (orders) you receive from NHLMIS will not be added because the customer or items are not recognised by mSupply
  2. NHLMIS must be configured so that the API key relates to the correct stores in your mSupply installation.

Currently, there is no functionality to show the program a particular order is for or to force the selection of stock that belongs to the correct program. This might be added in a future upgrade.

mSupply has an interface with the Nigeria Health Logistics Information System. The interface allows the automatic sending of current stock and pulling of orders from NHLMIS.

The preferences that define how this interface works are managed on the NHLMIS and NHLMIS 2 tabs of the File > Preferences menu. The tabs looks like this:

General preferences

  • Server URL: The URL of the NHLMIS interface. Enter everything without the resource to be called and the final “/” e.g. https://dev.api.nscip.field.supply/v1 (this is actually the URL of the NHLMIS test server).
  • API key: The authentication key for your organisation. This will be provided by the NHLMIS team.
  • Error email: The email address for error emails to be sent to. Separate multiple email addresses with a semicolon (;) if you want error emails to be sent to multiple addresses.
  • Stores to send stock and receive requisitions for table: This table contains a row for every store in the datafile. Check the checkbox in the Send stock & Fetch requisitions column (by clicking on it) for each store you want to send stock to and fetch requisitions for in the NHLMIS interface.

Send stock preferences

  • Send current stock to NHLMIS checkbox: If this is checked then mSupply will automatically send the current stock stock in each of the stores selected in the Stores to send stock and receive requisitions for table. If it is unchecked then no current stock is sent to NHLMIS.
  • No. of days between sends: The number of days to leave between each send of stock. If set to 0 then current stock is not sent to NHLMIS.
  • Time to send: The time of day to send the stock. Enter the value in 12 hour clock format and select whether it is AM or PM in the drop down list.
  • Manufacturer to use if none: By default, if the stock doesn't have a manufacturer set in mSupply then it is sent to NHLMIS with a blank manufacturer. If you enter something in this field then, if a line of stock has no manufacturer set, then the contents of this field are sent in the manufacturer field. Of course, if a line of stock does have a manufacturer set then it is sent with the name of that manufacturer, regardless of what is entered in this field.
  • Send now button: If this is clicked, the current stock in the stores selected in the Stores to send stock and receive requisitions for table will be sent to NHLMIS immediately. This will be an “extra” send and does not affect the automatic send defined by the No. of days between sends and Time to send fields.

Fetch requisitions preferences

  • Fetch requisitions from NHLMIS checkbox: If checked then mSupply will fetch all outstanding requisitions (NHLMIS orders) from NHLMIS. The stores they are received for depends on settings in NHLMIS (this is tied to the API key which identifies who is requesting the requisitions/orders).
  • No. of minutes between fetches: The number of minutes to leave between fetching requisitions from NHLMIS
  • Set “since” marker“ to drop down list: Will contain the date and time that up to 5 previous “since” markers were received from NHLMIS. Selecting one of these will reset the current “since” marker to the one selected and therefore cause mSupply to ask for requisitions ready since that date and time. Useful if you need to force the re-fetching of many previously fetched requisitions because of errors.
  • Order ID text box and Fetch now button: These are used to fetch a single order. Enter the NHLMIS order ID in the Order ID text box and click on the Fetch now button to fetch it immediately form NHLMIS. A progress indicator will show how the fetch is progressing.

Send shipments preferences

  • Send shipments checkbox: If this is checked then mSupply will send shipments to NHLMIS. If it is unchecked then no sipments will be sent.
  • No. times to retry sends: The maximum number of times to try resending shipments that failed to reach NHLMIS.
  • Minutes between retries: The number of minutes to leave between attempting to resend shipments that failed to reach NHLMIS.

Synchronise items preferences

  • Get new items checkbox: If this is checked, then mSupply will periodically check NHLMIS for new items.
  • No. days between requests: The number of days to leave between checking NHLMIS for new items.
  • Time to send: The time of day to check for new items in hh:mm format. Use the AM/PM selector to select AM or PM.
  • Get now button: When clicked makes mSupply check NHLMIS for new items immediately.

Synchronise customers preferences

  • Get new items checkbox: If this is checked, then mSupply will periodically check NHLMIS for new customers.
  • No. days between requests: The number of days to leave between checking NHLMIS for new customers.
  • Time to send: The time of day to check for new customers in hh:mm format. Use the AM/PM selector to select AM or PM.
  • Get now button: When clicked makes mSupply check NHLMIS for new customers immediately.

Click on the OK button to save any settings you have changed; changes will not be put into effect until they are saved by clicking this button

Other setup
  • Store codes: the codes of stores in mSupply must be given the same codes that they have in NHLMIS (warehouse identifiers in NHLMIS).
  • Stock: Any stock in a store that needs to be sent to NHLMIS must be assigned a program and donor and must belong to an item with a code that is recognised by NHLMIS. The program is set using the Program drop down list that appears on a supplier invoice line add/edit or stock line edit window when the Send stock checkbox is checked. It is populated with the names of master lists that have an “NHLMISProgram:program name” tag. The program is NOT assigned using custom stock field 5 (commonly used in other installations).
  • Master lists: master lists should be created for each NHLMIS program (with a tag in the format “NHLMISProgram:program name”), assigned to the stores that will use themn and then the preference ot control item visibility by item master list turned on. NOTE: this will mean a lot of configuration work when the interface first goes live!

What it does

Sending stock

The current stock in each store selected in the Stores to send stock and receive requisitions for table is sent to NHLMIS automatically on the schedule defined by the No. of days between sends and Time to send field.

Each time a send is made the following is done in this order, one store at a time:

  1. all the batches in stock (i.e. where available stock is more than 0) that have a program and donor assigned (any other stocklines are ignored) are sent to NHLMIS by calling the /batches endpoint. If all successful then proceed to the next step. If not all are successful then record error and stop.
  2. all current stock lines (i.e. where available stock is more than 0 and program and donor have been set) are sent to NHLMIS by calling the /stock-counts endpoint.
    1. Some items have an NHLMISChild property with values in the format ”code,pack_XXX“ where code is the item's code and XXX is the pack size. If the item of any stock line has an NHLMISChild property AND the line is not using the item's default pack size then the code of the item sent to NHLMIS for this line is replaced with the item code in the NHLMISChild property that has the matching pack size value (XXX in the example above). If there is no matching pack size value then no item code replacement is made.
  3. The success or failure of each send for each store is logged.
Fetching orders (requisitions)

All the outstanding orders (which become requisitions in mSupply) for this mSupply installation which have become outstanding since the last “since marker” are automatically fetched from NHLMIS on a schedule defined by the No. of minutes between fetches field. This is done by making a GET call to the /orders endpoint.

These calls are all made using genericParent=True which means that all items in the NHLMIS response will be replaced with their generic parent items (by NHLMIS). The quantities requested for each item in the order are multiplied by their default pack size to get the number of units for the requisition line.

If there are more than 50 outstanding orders then mSupply will automatically ask NHLMIS to send the next 50 until all outstanding orders have been retrieved.

Each time orders are successfully retrieved, the “since” marker that mSupply uses for the request is updated with the value returned by NHLMIS. And if the “since” marker is for a different day to the last since marker stored, it is added to the Set “since” marker” to drop down list (only the 5 most recent markers are stored in this drop down list - if there are already 5 then the oldest is replaced with the new one).

Each order received from NHLMIS is saved as a requisition in the appropriate store in mSupply. The NHLMIS order ID is stored in the Their ref field of each requisition.

Any orders that have already been received from NHLMIS and saved in mSupply are not saved again, they are ignored.

Fetching a single order (requisition)

This occurs when the Fetch now button shown above is clicked. This makes a GET call to the /orders/{suborderId} endpoint, where {suborderId} is the ID of the NHLMIS order to retrieve. As with the scheduled fetching of orders described above:

  • These calls are all made using genericParent=True which means that all items in the NHLMIS response will be replaced with their generic parent items (by NHLMIS).
  • The quantities requested for each item in the order are multiplied by their default pack size to get the number of units for the requisition line.
Sending shipments

When a customer invoice, which comes from a requisition generated from an NHLMIS order, is finalised it is sent to NHLMIs by making a PATCH call to the /orders endpoint. All shipments are sent with a “packed” status. If it is successful, all is well. If the send fails then it is added to a queue and the send is retried after the number of minutes in the Minutes between retries field. When the call is successful then the shipment is removed from the queue. If it fails the number of times in the No. times to retry sends field then the shipment is removed from the queue and an error email is sent to the email(s) in the Error email field.

Synchronising items

A GET call is made to the /products endpoint for all NHLMIS services. If an item code returned from these calls exists in mSupply already then it is ignored. If it does not exist in mSupply already then:

  • if it doesn't have a Generic parent ID or the Generic parent ID is the same as its ID then it is created as a normal item.
  • if it has a Generic parent ID which is different from its ID then it is created as an NHLMISChild property of the parent item (as long as it doesn't already exist as this property!) with a value of “item code,pack_pack size” e.g. “ghsc-mal0004,pack_100”.

In addition, new items will be added to master lists that have tags matching the item's program name (master list tag format is “NHLMISProgram:program name”). If the master list does not exist then it will be crerated by mSupply.

The pack size sent with an item is set as its default pack size.

Synchronising customers

A GET call is made to the /services endpoint to get all the services that belong to programs in mSupply then a GET call is made to the /locations endpoint for each service in turn. If a customer with the same code exists in mSupply already then it is ignored. If it does not exist in mSupply already then it is created:

  • the id is stored in customer custom data so that it can be used when sending shipment information back to NHLMIS.
  • state, zone and lga information are stored in the 3 levels of customer category 1 (which must be created before creating the customer).
  • the customer is made visible in stores with the same state.

Errors

If errors are encountered during any of the processes then information about the error is saved in the log (see the 25.19. The system log page for details) and an email giving details of the error is sent to the email address stored in the Error email field.

Visible changes in mSupply

Requisitions

When an NHLMIS order is received it is turned into a requisition in mSupply. The requisition has its donor set to the donor in mSupply that matches the value after funder: in the NHLMIS order. The donor is show in the requisition in a Donor drop down list (which is only shown if the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab), shown here:

The drop down list is active so the user can edit it if required.

Supplier invoices

Supplier invoices have a new Program drop down list, displayed ony when the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab. It is shown here:

It is populated with the names of all the master lists with a tag of NHLMISProgram:XXX where XXX is the name of an NHLMIS program. The user can set the appropriate program for the stock on the supplier invoice.

Customer invoices

Read only Program and Donor fields are displayed on a customer invoice if the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab. These fields display the NHLMIS progam and funder (mSupply donor) the customer invoice belongs to and are shown below:

The Program field is populated with the name of the master list which matches the NHLMIS program. It will be empty if there isn't a requisition linked ot the customer invoice.

The Donor field is populated with the name of the donor matching the NHLMIS funder (mSupply donor) associated with the requisition the customer invoice came from. It will be empty if there isn't a linked requisition.

The action of the Issue stock for all placeholder lines option on the grinder icon below the table on the left hand is modified if the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab: it still applies stock in FEFO order but it only uses stock which has a donor and program matching the customer invoice's. If the customer invoice does not have a donor then donor matching is not carried out, if it has no program then program matching is not carried out. If it has neither then the functionality is exactly the same as normal and no additional filtering is carried out.

Stock lines

A Program drop down list is displayed on the stock line edit window (opened by choosing Item > Show items with stock from the menus and double-clicking a stock line on that window). The drop down list will be set to the NHLMIS program associated with the stock and looks like this:

If the Fetch requisitions from NHLMIS checkbox is checked on the File > Preferences > NHLMIS tab, the Program is also offered as a column selectable for display on the stock line edit window (opened by choosing Item > Show items with stock from the menus). If you click on the Customise button on that window, you will see the Program field in the available columns as shown here:



Previous: 23.06. MYOB | | Next: 24. Data Tables and Fields

23.10. Siglofa integration

mSupply has an interface with Siglofa, a variant of OpenLMIS.

Settings

Choose File > Preferences from the menus and click on the Siglofa tab on the left hand side:

  • Use Siglofa integration: if checked then the other fields will be unlocked and mSupply will do what is described in the What it does section below.
  • URL: Enter the URL, including the port number if any, of the Siglofa application.
  • Username: The username mSupply should use to connec to Siglofa.
  • Password: The password mSupply should use to connect to Siglofa.
  • Client: The client name used to connect to Siglofa, provided by the Siglofa team.
  • Secret: The password to go with the Client name, as provided by the Siglofa team..
  • Test connection button: click this to test the connection to the Siglofs server when all the details above have been entered. mSupply will tell you whether it was able to successfully connect to Siglofa.

What it does

If the Use Siglofa integration checkbox is checked and the connection details result in a successful database connection, a scheduled task is started which will:

  • Once a day check Siglofa for new requisitions. If there are any then they will be retrieved and added as suggested status customer (response) requisitions in the central warehouse store in mSupply.
  • Once a day check mSupply for customer invoices created from Siglofa requisitions that have not been created as orders in Siglofa. If there are any then:
    • Create an order matching the customer invoice in Siglofa.
    • If the order has been created successfully then send the requisition lines as the order's lines.
  • A separate scheduled task will check for successfully created orders where sending the order lines has failed. If it finds any it will send the appropriate requisition lines to the order.



Previous: 23.09. iVEDiX integration | | Next: 24. Data Tables and Fields

25.07. Updating mSupply

Updates for mSupply are being released frequently. The method of update varies with the type of mSupply that you have:

  • The mSupply server must be manually updated by an administrator.
  • The mSupply client will update automatically from the mSupply server when it is first opened after a server update.
  • mSupply single user can be updated automatically by the user.
mSupply client

To automatically update your mSupply client, simply start it running. If it needs an update (because the server has been updated, for example) it will automatically update itself. You will see messages with progress bars describing what's happening. The update process should take less than 5 minutes, depending on the speed of your connection to the mSupply server and the speed of your computer. When the process is complete you'll see the usual mSupply login screen.

The only thing that can go wrong with this update process is if the connection to the server is broken or the client does not have the necessary permissions to create new files in the directory or folder it is installed. Symptoms of these failures vary from a failure message to the update process beginning then stopping without displaying the mSupply login window.

mSupply single user

mSupply single user is often used in a distributed sync setup where the various copies of mSupply are spread far and wide throughout a country. So the ability to remotely update them can be very useful!

Simply choose Special > Check for updates… from the menus or click on the Check for updates icon on the Admin tab of the navigator:

mSupply will then check whether there is an update available for your version. If there is, you will be shown the new version and asked whether you want to continue with the update. If you do, mSupply will download it and install it automatically. When the process is finished, you will be asked to restart mSupply for the changes to take effect.



Previous: 25.06. Backup | | Next: 25.08. Changing users and passwords

25.06. Backup

If your data is important, then data backups need to happen, because things can go wrong (power failures, disk failures, ransomware, etc.)

  • You can perform a backup manually and/or automatically. Automatic backups should be scheduled to run frequently (every day), manual backups should be done before updates or other potentially risky changes.
  • It is not necessary to quit the database before performing a backup.

While a backup is running, all user activity will be paused until the backup is complete. They won't even be able to log out of mSupply. So:

  • Make sure you only run a manual backup when users are not using mSupply.
  • Make sure you configure your automatic backups to run at a time when the system is not busy e.g. lunch time, the end of work or, if your system will stay up 24/7, the middle of the night.
  • The Backup function works in both single user and client / server (multi-user) environments. The main differences are that in client / server (multi-user) environments:
    • The configuration of the Primary backup is done on the Server computer.
    • The backup can be configured to include other files, such as the Index and log files, which is very handy when providing support.
    • The backup takes place on the server. A progress window will appear on the client to show how the backup is proceeding.
    • Restoration from a backup must be run from the server computer.
Running a backup manually

Choose File > Backup… to run a manual backup of your data. The backup will be carried out according to the configuration of the Preferences > Backup tab.

Backup: best practice

We recommend you set up your mSupply backups in the following manner

Disk configuration

If your machine has the capability (e.g. it is a server with multiple storage volumes), then there is additional data security in configuring a RAID array.

Use RAID 1
  • RAID 1 is two disks mirrored, so data is written to each disk
    • Advantages
      • if one disk fails you continue work from the other disk
      • if the RAID controller fails, you can directly connect one disk and continue work.

There are other forms of RAID, but their advantages are outweighed by their disadvantages, considering that even a large mSupply database will be of the order of 10 GB in size.

Use a hot spare

This is a spare disk that the RAID controller will use if a disk in the RAID set fails.

Add another single disk to receive backup data

This disk is not part of the RAID

This is still possible if your machine only has one disk drive and you can not configure a RAID array. This could be a volume attached to a USB port (e.g. a thumb drive) or a location on the network, provided that it is always available.

Configure Primary backups

We recommend that you configure the Primary backup as recommended in our user's guide section on the Preferences > Backup tab.

Configure a secondary backup
  • Configure a secondary backup to a destination on the same machine, or elsewhere on the network that will be synced off-site (e.g. Dropbox, OneDrive, Google Drive, etc.) - refer Preferences > Backup 2 tab.
Configure off-site backup

Use Spideroak™ or Dropbox™ to backup your secondary location to their internet servers.

If needed configure an off-site computer to also synchronise with the backup service provider so you have an off-site copy as well as the “cloud” copy.

Mirrored servers

We have the technology to provide mirrored servers when very high availability is required. Contact us if interested. A charge will apply for implementation

Use a standard place to store backups

We suggest that you store:

  • mSupply data in C:/mSupply_data/
  • Backups in C:/mSupply_backups/
  • Log file in C:/mSupply_data/

Backup for mSupply single user sites

If you have a synchronisation system with mSupply it's very important that the sync satellite sites have operating backups. By design, mSupply sync satellite sites can operate indefinitely without syncing to the Central server. There are numerous cases of Sync satellite sites operating for months without syncing, though this is not recommended! In such cases, a failure on the sync satellite site could result in months of lost data unless backups are operating on the such sync satellite sites. These sites are normally even more vulnerable to failure than 'Central' servers ….

Restoring your data

For data security purposes, the New data file, Restore and Open new datafile functions are disabled if you are on a satellite site in a synchronising system.

An mSupply database can be created from a backup:

  1. Quit mSupply if it is running.
  2. Start mSupply and then immediately hold down the Alt key. You will now be shown the following dialogue box with a number of radio buttons with the different options available:new_file_option.jpg
  3. Choose the 4th radio button Restore a backup file.
  4. Another window will open where you can choose the backup file to restore. Locate your backup file in the Open dialog that appears. Your backup file has file extension .4BK, eg. CMS.4BK. Hit OK.
  5. You will be prompted for where to create the data file. This should default to the location of the backup that you have selected. If you want to save it elsewhere, change the destination location of the data file by clicking on the … button. Once you are happy with the destination location, hit the Restore button.
  6. Once the restore has completed, mSupply will Quit.
  7. Restart mSupply
  8. You may be prompted for a log file. In that case:
    1. Click on the Create button. Select the suggested location, which can be the same as your new data file location. You may find that the parent location of the default location is where the log file is already created. You can overwrite it. Once you have specified a location, click on the Save button.
    2. You will be advised that The log file will be activated after the next backup of the data file. Do you want to start the backup automatically?. If you click OK here, then a backup will be created now. This can take many minutes if it is a large data file. It is not necessary to create the backup at this stage, but the log file will not be created until you create the first backup.
    3. After clicking OK or Cancel, the data file will open. This will take time (hours) if it is a large data file and the index file is not included with the backup.
  9. mSupply should open your restored data file and you should be presented with the log in screen to the new data file.



Previous: 25.05. Web browser access via TSPlus | | Next: 25.07. Updating mSupply

25.14. mSupply deployment

This document gives an overview of the process of installing mSupply at a new location.

Terms

  • A virtual store will usually map to a physical location- either a separate warehouse or an entity within a warehouse that has it's own items and facilities and transactions
    • All virtual stores share the same item and customer/supplier lists, but if an item is not used in all stores, it can be hidden in stores where it is not used. The same applies for customers/suppliers.
  • A transaction refers to a record that records stock movements- from a supplier, to a customer/facility, or to adjust stock
  • A name refers to a customer or supplier.
  • A customer may be a supply point- not necessarily an entity that pays for supplies.

Cloud or local

Criteria for for a robust local installation of mSupply:

Physical locations
  • Dry, secure locations with the infrastructure connections as detailed below
  • Management of security for human access.
Hardware
  • You will need to buy hardware as per specifications on this web site.
  • Scalability- as the size of your installation grows you might have to buy new hardware (more speed, RAM, storage)
    • Expect to purchase a main server plus one extra server for every 35 remote desktop users and one web server for every 1000 sync users.
    • This is much easier for a cloud or virtual server - you just assign more RAM, storage or CPUs to the server
  • Redundancy
    • if hardware failure will create more downtime than is acceptable (realistically it will create one or two days of downtime), then you need to have a redundant system. That is, you need to:
      • replicate the hardware at a different physical location
      • Have a fast network connection between the two sites.
      • The second site will need the same network connectivity for client access as your main site.
      • Have control of DNS to redirect users to the backup site when the primary site fails.
Electricity supply
  • Stable, earthed electricity supply
  • UPS systems with enough runtime to cover outages and the ability to communicate with the server so it can gracefully shutdown before batteries are exhausted.
  • A generator system with auto-start might be needed.
  • All of the above at the redundant site as well.
Network
  • Enough ingress and egress network capacity for the software's requirements.
  • Ability to expand the capacity as the system grows.
  • The same capacity at the redundant site.
  • A high capacity network connection between the main and the redundant site for realtime replication of server data so the redundant site is up to date.
  • You may also decide that redundant connections are needed to the primary server site.
Local IT expertise
  • Sufficient local expertise to distinguish between hardware, software, network and electricity issues.
  • The expertise must be available during all hours the system must be available
  • Written fail-over plans for failures in the above systems.
  • Ability to execute plans on time when there is a failure.
  • Knowledge transfer to new staff when existing staff leave.

Structure

It is important to design the overall structure to meet your organisation's needs. This mainly focuses on:

Importing data

Most sites will have existing lists of items and names. The user guide has sections on:

Users

The permissions system can be set up for individual users, or be based on groups. See Managing users

Warehouse management

If your warehouse has existing locations you can import them: Locations and Location types Otherwise you will need to design a location scheme.



Previous: 25.13. mSupply server administration | | Next: 25.15. Managing users

25.09. Diagnostics

This feature is primarily intended for use by our technical staff when there is reason to believe that there may be some errors in the database; it is unlikely to be of practical use to users of mSupply. However, feel free to run some checks if you're bored or need help to get to sleep ;-). This is a brief description of the functionality only - we don't want to be too good at helping you sleep after all…

The diagnostics will only run on the records for the store that you are logged in to when you run them.

Choose Special > Diagnostics… from the menus and this window will open:

Check all the tests you want to run (all are checked by default - might take a long time to run if your datafile is big):

Pack size integrity: Each item's pack size is examined by batch number to confirm that stock in balances with stock out.

Store integrity: Each customer invoice is examined to confirm that each transaction has been applied to the appropriate store.

Purchase Order integrity: A check is performed to confirm that Purchase Order quantities and Goods Received quantities tally.

Miscellaneous checks: Includes a check that any repacked items have not resulted in negative amounts being recorded.

Look for ledger problems: This report presents you with a list of items whose ledger balances (total in minus total out) does not equal the difference between the opening stock and the actual stock on hand. It is also useful for finding unauthorised adjustment of stock values.

Note: you can check for ledger problems in individual stock lines of an item on the Stock tab of an item's details window. See the 4.01.05. Items - Stock tab page for details.

Click on the Check button when you're ready, mSupply will start the tests and report the results in the blank area below it. When you've finished, close the window by clicking on the OK button.



Previous: 25.08. Changing users and passwords | | Next: 25.10. Finalising transactions

25.12. mSupply dispensary installation

mSupply provides a fully featured Pharmacy Dispensary module. The following steps describe how to configure mSupply for Dispensary use. This document specifically applies to Pharmacy Dispensary staff.

Users

  • Set up users to log in in dispensary mode

Permissions

Misc
  • Show direction entry: checked
  • Item codes must be unique: checked
  • Service items: can be set to “allowed” if recording non-stock charges- like a dispensing fee.
  • Show direction entry: checked
Invoices 2
  • Allow placeholder lines: checked

Handling stock on hand

You may want to consider setting stock to a very large number for each item. This will mean that stock is effectively ignored. Experience tells us it is very (very) hard to accurately track stock in a busy dispensary, and most likely unnecessary if you are tracking issues to the dispensary from another virtual store.

Per store preferences

Preferences in the dispensing store

Go to Special > Stores > Double-click the dispensary store and set these preferences (and maybe others)

  • Patients created in this store not visible in other stores: checked
  • Names created in this store not visible in other stores: checked (may vary depending on situation)
  • Your training will have to take into account the setting for stock transfers that you choose here.
Pack to one

As dispensing is invariably in multiples of single tablets etc, you will want incoming stock converted to packs of one. You can do this on a per-item basis, but the better way is to go to Special > Stores > Double-click the store you're logged in to, and you'll see a visibility tab. On that tab click “Set pack to one for all visible items in this store”

If your dispensary store is 'Active' (refer Remote synchronisation, Store sync types) on a Sync Satellite server, then you will not see the Visibility tab when logged in to the store on that Sync Satellite server. These settings need to be done while logged in to the Sync Primary server.

Abbreviations

Choosing a set of abbreviations should be a collaborative activity with staff. Note you can import abbreviations

If more than one language is used, you might want to make the same abbreviation with a suffix for the less common language. eg

Abbreviation Expansion Comment
tid dinko tin palta In your common local language (in this case Nepali)
tide three times a day add a suffix “e” to the same abbreviation when using for the English expansion

Latin abbreviations are universal

Abbreviation Expansion
od once a day
bd (or bid) twice a day
tid three times a day
qid four times a day
hs at bedtime
nocte at night
pr in the rectum
po orally (by mouth)
pv into the vagina
qqh every four hours
q6h every six hours

It is important to be consistent with choosing abbreviations so people can remember them. e.g.

Abbreviation Expansion
1t Take one tablet
2t Take two tablets
3t Take three tablets
ht Take half a tablet
1c Take one capsule
2c Take two capsules
wtf with tasty food

Users should be trained that you can mix abbreviations and normal text- wherever an abbreviation is encountered it will be expanded. It is important not to make an abbreviation that is a normal word in the language, else the expansion will happen when the word is typed.

Item abbreviation shortcuts

This is important. See here The aim should be that every common item has all common directions saved as a shortcut. Pay attention to having the most common shortcut at the top of the list.

Patients

In a dispensary, your customers are the patients. Their details need to be recorded. This can be done prior to implementing dispensing through importing of patients - refer Patients. In many cases, you will find that there is no accessible database of patient names and that you will need to enter patients 'on-the-fly'. A New Patient button is on the Prescription entry window for this purpose. This will slow down the dispensing process, but over time, as more and more prescriptions are for 'existing' patients (e.g. for inpatients and chronic patients), this will become less of an issue.

Patient Code

Each new patient requires a patient code. This patient code can be applied automatically be ticking File > Preferences > Dispensary Mode > Auto-generate patient code. You also have the option here to prefix the codes with a string of text. This is particularly helpful in a multi-facility installation where patients may be referred from one facility to the next and you would like to know in which facility they first entered into the system.

Prescribers

mSupply allows prescribers to be recorded against each prescription. This can be made a requirement by ticking File > Preferences > Dispensary Mode > Prescriber must be entered. Making the recording of the prescriber mandatory will obviously slow down data entry during the dispensing process. In order to record prescribers with prescriptions, prescribers must be entered into the system - refer Prescribers.

Printing

Set printing to be on by default for new entries, and off by default for edits.

Train users on changing printers using Special > Printing preferences

It is important that printers have a static IP address. You can do this in two ways:

  1. Set a static IP address on the printer. Log on to http://printer_ip_address to do this. It's under network settings. The default IP for Zebra printers is 192.168.254.254
  2. Use the DHCP server on your network to set a Static DHCP mapping. This is preferred, as it's much easier to change.

With a Zebra GK 420 you can hold the front button until it flashes once, release it, then it will print out the IP address. Read all about it



Previous: 25.11. Managing data files | | Next: 25.13. mSupply server administration

25.10. Finalising transactions

There are three methods of finalising invoices:

  1. The method described here.
  2. By highlighting transactions in the transaction list and clicking Finalise
  3. By checking the Finalise checkbox when viewing a particular invoice and clicking OK to close the window.

Finalising is controlled by user permissions. If you are not able to finalise invoices, you likely don't have the user permission to perform the operation. There is more information on permissions here

Finalise customer invoices

All invoices that have status “cn” (i.e. confirmed invoices) may be finalised.

If you have the export option turned on in the Preferences, finalised invoices will also be exported to allow import into an accounting program. They can also just be “exported” to a printed list.

Once an export is done, invoices can no longer be edited. (They have status “fn” for finalised).

Each time a group of invoices is exported, they are all assigned a common “batch” number. You can use this batch number to export an invoice again, should your export file become lost or damaged.

On choosing File > finalise customer invoices you will be shown a window displaying all the customer invoices that have not been finalised.

Note that if “export invoices when finalising” is turned on in the Preferences, invoices that have been finalised but not yet given an export batch will also be included in the list. If any such invoices exist you will be alerted to the fact.

The first screen advises you of the folder to which your file will be saved. The next screen displays a list of invoices not yet finalised.

Follow these steps:

  • Hold down the control key (Windows) or command key (Mac) while clicking on the lines you wish to finalise. The lines you have selected will be highlighted.
  • To reverse a choice click on the line again.
  • If you want to choose all the transactions displayed, type control “a” (Windows)/ command “a” (Mac)
  • Once you are satisfied with the records you've selected, click the OK button. (In fact, don't just be satisfied, be extra sure- you can't reverse a finalisation. It really is final).
  • The transactions will be marked as “finalised” (status “fn”), and they may no longer be edited.

You will be given the opportunity to print the list of finalised invoices.

If you have specified the option in the Preferences, a text file called “cust_invoice_expt.txt” will be created on the disk (& in the folder) you have specified in the Preferences, otherwise they will be created in the “Documents/exports” folder under the Application folder.

Each time you finalise a group of invoices, they are given an export batch. This is a unique number that allows you to recall those invoices.

Finalise supplier invoices

As for the finalise customer invoices…. section above, but for supplier invoices

The export file created is called “supp_invoice_expt.txt”

Finalise inventory adjustments

You need to finalise inventory adjustments so that they can be purged from mSupply at a later date. Also, you will not be able to set the start of year stock at the beginning of the next financial year until all inventory adjustments have been finalised.

On choosing item | finalise inventory adjustments … you will be shown a window displaying all the inventory adjustments that have not been finalised. Follow these steps:

  • Hold down the control key (Windows) or command key (Macs) while clicking on the lines you wish to finalise. The lines you have selected will be highlighted.
  • To reverse a choice click on the line again.
  • If you want to choose all the transactions displayed, type control “a” (Windows)/ command “a” (Macs)
  • Once you are happy with the records you've selected, click the OK button. (In fact, don't just be happy, be extra sure - you can't reverse a finalisation. It really is final).

The transactions will be marked as “finalised” (status “fn”), and they will no longer be able to be edited.

For exporting invoices to Moneyworks please refer to chapter 11. Exporting invoices to Moneyworks

Finalise builds

You need to finalise builds so that they can be purged from mSupply at a later date, or to disallow any further editing of particular builds. Also, you will not be able to set the start of year stock at the beginning of the next financial year until all builds are finalised.

See the sections above for the details of how to finalise transactions. The process is just the same for builds.

Export a batch again

Choosing this item presents you with a window where you can choose a batch number to export again:

Invoice batch numbers are shown on the right hand side of invoice lists.



Previous: 25.09. Diagnostics | | Next: 25.11. Managing data files

25.11. Managing data files

File > New data file...

This command will present you with a standard open/save window where you can choose the name and location of a new data file: If you click the OK button, mSupply will close the data file currently in use (saving any changes made automatically), and then open the new data file. The new data file will contain no items, names or transactions. You can either enter these manually or use the import commands (see later in this chapter) to import items, names and stock.

File > Open data file...

This command will present you with a standard open/save window where you can select an existing data file to open. If you click the OK button after successfully selecting a valid mSupply data file, mSupply will close the data file currently in use (saving any changes made automatically), and then open the new data file. Note that if you regularly use more than one data file, use the “About mSupply…”. Command from the help menu (mSupply menu on Macintosh), where the data file currently in use is displayed. Warning:: Do not try to open the same data file from 2 or more single user copies of mSupply at the same time. You will corrupt your data. If you require multi-user access, buy a multi-user licence!



Previous: 25.10. Finalising transactions | | Next: 25.12. mSupply dispensary installation

25.15. Managing users

About users and groups

User permissions are per-store, so a user can have different permissions when logged into different stores.

If you have many users that need to have the same permissions (because they carry out the same role, for example), you can create a group and assign the users to the group. Once a group is set up and permissions for the group assigned, any users that are assigned to the group will inherit the group's permissions, rather than having to set permissions for each user individually. When you change a group's permissions, you change the permissions for all users who belong to that group.

If you want to change a user's permissions and find out that all their permissions are greyed out and uneditable then it means they are a member of a group. To edit their permissions separately from the group, they must first be removed from the group:

  • Edit the user, change the Is a member of drop down list to None, click OK (see below for details).
  • Open the user again and their permissions will be editable.

Refer to Using groups below for more details. If the user is to remain part of the group then you must change the group's permissions (see Editing a group below) but beware, this will change the permissions for all users who belong to the group, not just the user you're interested in.

If you want to disable a user, perhaps because the staff member has left the organisation, then they must be made 'inactive':

  • Edit the user, uncheck the Active checkbox, click OK.

If the Active checkbox is greyed out, it is because they are a member of a group. You will need to first remove them from the group before you can make them 'inactive':

  • Edit the user, change the Is a member of to None
  • Edit the user, uncheck the Active checkbox, click OK.

Of course, if the whole group of users needs to be made inactive then you can just uncheck the Active checkbox for the group.

Adding and editing users and groups

mSupply has a comprehensive system of controlling user access, allowing you to manage in fine detail what each user can do and see in the system. You can manage users individually, in groups or a mixture of both - whichever is most suitable for your situation.

User access is managed by choosing File > Edit users from the menus, or by choosing Admin > Edit users in the Navigator. When clicking on this option you are presented with a list of current users:

The list shows you the following information:

  • User The user's name.
  • Job title The user's job title, as entered on the details tab of the user's details form.
  • Group The group the user belongs to. Will be blank of the user does not belong to a group.
  • Active Checked if the user is allowed to login to the system.

To view groups rather than users, choose Groups from the Show Drop-down list at the top-right of the window. The list changes slightly to look like this:

Now the list shows you slightly different information:

  • Group The name of the group
  • Active Checked if the group is active. If the group is active then all users in the group are allowed to login to the system. If the group is inactive (checkbox unchecked), all users in the group are inactive and are not allowed to login to the system.

To get a list of all current user permissions, click the Permission Report button. An Excel spreadsheet will be generated (see sample); it will have one worksheet for each store showing all the users and groups and what permissions they have in that store.

Double-click a user (or group) to edit their details or delete them. Click the New User button to add a new user (or the New group button to add a new group). Doing either will open the user details window (described below - for a new user or group all the tabs are empty, for an existing user or group the tabs are filled with their current settings)

User details window

This window has several tabs, all described below.

General tab
Is a member of

Used to select the user group the user belongs to (see below). When the window loads, it displays the group the user currently belongs to. It will show “None” if they are not a member of any group.

Password

This text box will always appear empty when the window is loaded. It must be set for a new user. It can be used here to change the password of an existing user.

Confirm password

If something is entered in the Password textbox, then the same text must be entered in this textbox. This step makes sure you set the password to what you think you're setting it to!

Active

If this checkbox is checked, then that user has permission to use the system, and their name will appear in the login window. If this checkbox is unchecked the user will not be allowed to login to the system and their name will not appear in the login window.

Can be responsible officer

If this checkbox is checked, the name of that user will appear for selection in the Responsible Officer selector on the Transport Details tab of a Customer invoice.

User initials

User initials should be entered in this field.

Language

Allows you to select which language the user wants to use in mSupply. As of August 2020, supported languages are:

  • English
  • French
  • Lao
  • Spanish
  • Khmer
  • Portuguese (partially complete)
LDAP section

This section can be used to check a user's login credentials against an LDAP (Lightweight Directory Access Protocol) server. If you are going to use LDAP you must fill in the server details in the General Preferences, LDAP tab first.

  • Login using LDAP: Check this if you want this user's login details to be checked against your LDAP server. Means that you can have some users logging in normally and some being checked against your LDAP server. Helpful if there's a delay in users being given LDAP credentials for any reason.
  • LDAP login string: Enter any string which has to be used with the LDAP login. Will be provided by the LDAP administrator if required.
Windows username

The username the user logs into window systems with. Used to provide single-sign-on capability when the user is logging in remotely to an mSupply client running on a Windows server.

License category

Used to select which user license category the user belongs to. This will contain a list of all user categories currently set up in the datafile. See License management for details.

User belongs to State/Region

Used to select the name category 1 that the user belongs to. Only used in some customised versions of mSupply.

Signature

Use to add or remove an image of a user's scanned signature for displaying on invoices for example

Tags

Use to apply 'tags' to a user. These tags can then be used to control access to various features for users according to the tag.

User Can:

Used to give the following controls to users:

  • Login as Desktop user
  • Use the Dashboard - this is necessary if you want the user to be able to see dashboards
  • Receive email notifications - this is necessary to enable reports to be emailed on a schedule to a user or group of users. Multiple reports for a User will appear on different tabs of an excel workbook. This needs to be configured by Sustainable Solutions, so get in touch if you're interested and we'll set this up for you.
  • Use system - if checked the user can login to the remote authorisation web app as an authoriser. See the 26.15. Remote authorisation page for details.

When a user is added to a group, the User can settings are set to those of the group i.e. they are inherited from the group. However, the User can section is still editable for an individual user - the settings are not controlled by the group after the user has been added to it.

Permissions tabs

These are where you can set access to the many features and functions on a store-by-store basis for each user or group. There are three Permissions tabs and each are shown in the screenshots below:

Buttons on the Permissions tabs
  • The Store drop down list: Selects the store for which permissions are being displayed and set on the current tab. Select the store you want to see or set permissions for in this drop down list.

    You can type in the drop down list. If you do this, when you click on the down arrow to open it, you will only be shown stores in the list which start with what you typed. Or, if you prefix it with the mSupply wildcard character, “@”, you only see stores which contain what you typed. Very helpful if you have many, many stores and want to find a specific one or group of stores.

  • The All on button: Checks all the permissions on the current tab i.e. turns them all on. There are exceptions to this for safety reasons; the Update pack size, cost and sell price, Add/edit users and Access server administration permissions on the Permissions tab are not turned on with the All on button.
  • The Copy button: Copies the state of all the checkboxes on the tab for this store to an internal clipboard for that tab. From version 5.03 onwards, the button opens this window:
    • In the Permission tabs section, select which tabs you want to copy the permissions from by checking their checkboxes.
    • In the table, select the stores you want to copy the permissions of the current store to by checking them in the Selected column.
    • Click the OK button to copy the selected permissions tabs of the current store to the selected stores. Click the Cancel button to close the window without doing anything.
  • The Paste button: Only exists for versions before 5.03. Pastes the checkbox settings saved to the clipboard for the current tab to the same tab for another store. In this way, the Copy and Paste buttons are a great way of copying permission settings for tabs between stores - really handy when users have similar permissions in different stores.

Most of the permissions are self explanatory. Those that need more explanation are given below:

Permission Details
Permissions Tab
View stock If not checked the user is not able to view the current stock list (see the 4.15. Show items with stock page), view the Stock tab of an item's details window (see the 4.01.05. Items - Stock tab page), not able to view stocktakes (see the 4.17. Stocktakes page) or view any reports in the Stock and items section on the Reports tab of the Navigator (see the 13.02. Stock and items reports page). If this permission is checked then they can do all these things unless they are prevented by not having other permissions e.g. if a user has this permission but they do not have the View stocktakes permission then they will still not be able to access Stocktakes.
Update pack size, cost and sell price If checked the user is able to edit the pack size, cost and sell price of supplier invoice lines that have already had stock issued from them, provided that the SI has not been finalised. See the 7.01. Supplier invoices page for details.
Add/edit users To prevent you being locked out of your datafile permanently, mSupply will not allow you to turn off this preference for the first 2 users which already exist when you open mSupply for the first time. You should always treat these users as admin users.
Access server administration If this is checked the user will be able to access the server administration windows, as described on the 25.13. mSupply server administration page. Only assign this permission to users who really know what they are doing!
Add/edit sync sites If checked the user is able to edit site settings in a synchronisation system (see the 29.02. Synchronisation Sites page for details). This includes being able to use the sync site wizard (29.03. Sync Site Wizard (Superseded)).
Disallow adding an unordered item to a Goods Received note If checked the user is not able to add items to a goods received note that are not included on a purchase order (see the 7.02. Goods receipts page for details)
Permissions (2) Tab
Add patients If checked, the user can add new patients into the system
Edit patient details If checked, the user can edit the details of patients already entered into the system. Of course, this means they can also view the details of patients in the system
View patients If checked, the user can view patients' details in the system. If not checked then the user will not be able to see any patient details.
Change transportation dates on finalised invoice If checked, the user can edit the Order written date, Order received date, Expected arrival date, Actual arrival date and Ship date fields on the Transport details tab of finalised customer invoices
Edit user fields on finalised invoices The user fields are the 4 custom transaction fields that can be enabled in the preferences - see Invoices Preferences for details. If this is enabled the user can edit the contents of these fields on transactions that have already been finalised
Change invoice category on finalised invoice If checked the user can edit the transaction category of invoices (customer, supplier and inventory adjustments)
Transfer goods between stores If checked the user can create a customer invoice with a store as the customer (i.e create a stock transfer)
Finalise stock transfers If checked the user can finalise a customer invoice where the customer is another store (i.e. a stock transfer)
Return stock from supplier invoices If checked a Return selected lines button will appear for the user on finalised supplier invoices, allowing them to return the goods on the invoice. See the 9.01. Returning goods section for details
Return stock from customer invoices If checked a Return selected lines button will appear for the user on finalised customer invoices, allowing them to return the goods on the invoice. See the 9.02. Receiving goods back from a customer section for details
Pack boxes If checked the user is allowed to manage boxes and assign stock to boxes on a customer invoice, even if the user does not have the Edit customer invoices permission. See the 8.06. Box management page for details
Permissions (3) Tab
Edit stocktake dates If checked the user can edit the Stock take date field at the top of a stocktake and the confirmed date of inventory adjustments created from the stocktake (see Creating a new stocktake) for details
Edit store details If checked the user can edit the store details and preferences, including using the bulk store preferences editor.
Edit visibility in stores If checked the user can edit the visibility of names and items in different stores. If it is unchecked they can't - either in the Store tab of a name or item's details window or the Visibility tab of a store's details window (in fact, the Visibility tab won't even be visible for them)
Add/import customer budgets If this is checked the user can import or add budgets for a customer, if unchecked they cannot
View temperature breach configurations If checked, the user can view temperature breach configurations in the vaccine/cold chain module. See the 20.01. Vaccine Vial Monitoring (VVM) page for details. Temperature breach configurations can only be edited in the Cold chain app or in mSupply mobile.
View and edit vaccine vial monitor status If checked, the user can view and edit the statuses that vaccine vial monitors have. See the 20.01. Vaccine Vial Monitoring (VVM) page for details.
View sensor details If checked the user can view temperature sensor details. See the 20.03. Cold Chain App Notifications page for details.
Edit sensor location If checked the user can edit the warehouse location attached to a sensor. See the 20.03. Cold Chain App Notifications page for details.
Edit/delete customer budgets If this is checked the user can edit or delete budgets for a customer, if unchecked they cannot
Create customer invoices from requisitions If this is checked the user can create customer invoice from the Create customer invoice button on requisitions. You can use this in conjunction with the Create customer invoices permission on the Permissions (2) tab to force all distribution to be carried out from requisitions.
View assets If this is checked, the user is allowed to search the assets in the system and see their details
Add/edit assets If this is checked, the user can also change the details of assets
Setup assets If this is checked a user can manage the setup of assets e.g. add or edit asset statuses, conditions, properties etc. (see the assets setup page for details of the various setup options)
Change asset status If checked, the user can make an asset's proposed status its current status.
Notifications tab

On this tab, you determine what notifications (alerts) a user will see, and when they will see them:

To enable a particular alert type for a user simply check the checkbox in the Is enabled column. Any alert type that has its Is enabled checkbox unchecked will not be displayed for a user.

Show notifications window on login: If this is checked, as soon as a user logs in, the notifications window (displaying all the notifications they have selected in the table above), will be displayed for them. If this is unchecked, the notifications window will only be shown when the user clicks on the notifications icon on the Navigator:

Please note that the notifications displayed realte only to the store that the user is logged in to.

Show cold chain breach alerts: If this is checked the user will see temperature breach alerts (in the store in the Store drop down list above the table - this is a per store permission) passed to mSupply by the cold chain app (see https://docs.msupply.foundation/coldchain/introduction/ for details). If this is not checked then a user will not see temperature breach alerts that occur in this store. Please note that a user must have login rights to a store to be able to see breach alerts, whether this permission is turned on or not.

Open mSupply permissions tab

This tab contains permissions that only affect Open mSupply users. Currently Open mSupply must connect to an existing mSupply server, which takes care of the authentication and synchronisation. Soon, when we've re-written the central synchronisation server in Open mSupply, there will be no need for this tab. Until then, permissions that only apply to users of Open mSupply will appear on this tab.

This tab is included in the permissions copying functionality of the Copy button at the bottom of the window (see the Buttons on the permissions tabs section for details).

Permission Details
Can confirm internal order as sent If checked then the user can Finalise an internal order in mSupply terms or Send it in Open mSupply terminology.
Cold chain API access If checked then the username and password of this user can be used to access the cold chain REST API built into Open mSupply.
Can modify central data If checked then the user can edit settings that are counted as central data in Open mSupply e.g. demographics indicators.
Program permissions This section is used to define which programs this user is allowed to view or edit data for. The table will contain a list of all the Open mSupply programs that have been setup in the datafile and there will be checkboxes for each in the View and Edit columns.

Click on the appropriate checkboxes to check them and give the user the appropriate permissions.
The Toggle view and Toggle edit buttons check or uncheck all the checkboxes in the View and Edit columns respectively.

If the list of programs is long you can type something in the Search programs box to make the list display programs that contain what you typed only.
Login rights tab

On this tab you set which stores the user can login to:

If there are too many stores in the list, you can restrict the display by typing in the Search stores text box: only stores with names starting with what you type will be displayed.

If you need a more complex type of search then click on the Complex search button and this filter window will open (you will recognise it as very similar to the customer or supplier search window):

Make your filter selections as required, click on the Find button and only the stores which match the filters you have set will be displayed in the table.

The Toggle all in selection button turns on (checks) all the Can login checkboxes for all the stores shown in the list. Clicking it again will turn them off.

The Is disabled column indicates whether a store is disabled or not and can't be edited.

You can check one box in the Default store column - this will be the store the user is offered by default every time they login or switch stores.

In the Can login column you can check the box for each store the user is allowed to login to. All the stores in your mSupply datafile are displayed here in alphabetical order. Please note:

  • The “Drug Registration” store is a special store used for the mSupply medicine registration functionality. See Registration for more details. Checking this box will allow the user to login to the Registration module.
  • The “Hospital Info System” is another special store used for mSupply's built-in Hospital Information system. See here for more details. Checking this box will allow the user to login to the HIS module.
  • “Supervisor - All stores” stores is a special mode to allow users to view information in and run reports over multiple stores. See here for more information.

Sync user across all login stores: This checkbox is only displayed if the currently logged in user is designated as a “special user” and they are logged into the primary server in a synchronisation system (the server where the system data iis edited). If this is checkbox is checked, when the OK button is clicked the user's details are synchronised with all the stores they are allowed ot login to. In this way, an administrator in a synchronisation system is able to edit user permissions and settings and have them automatically synchronised to all relevant sites.

Details tab

Here some personal details including job title, address and email address of the user can be recorded. The job title will appear in the Job title column in the list of users and the email address is used when using email functionality or other special functions in mSupply.

Other than that, these fields are for reference only, providing a handy place to record information about your system users.

Dashboard tab

On this tab you set which dashboard tabs will appear on the dashboard when the user logs into it. Of course, you have to set up the dashboard tabs before you can assign them to a user's dashboard. See Dashboard for instructions on doing that.

Once the dashboard tabs have been setup, they will appear in the Available column of this tab. You can see the “Test_tab” in the screenshot above. Anything in the Chosen column will be displayed on the user's dashboard. So, to make a dashboard tab appear on the user's dashboard, select it in the Available column and click on the >> icon to move the tab into the Chosen column. And to remove a dashboard tab from the user's dashboard, simply select it in the Chosen column and click on the << icon to move it back into the Available column.

Create a new user

To create a new user do this:

  1. Go to File > Edit users… and click on the New user button
  2. Enter the user name
  3. Assign a password
  4. Enter the password again in the Confirm password text box
  5. Go to the permissions tabs and set up permissions (3 tabs) OR select which group the user is to belong to using the Is a member of drop down list on the General tab (you must do one of these because you'll have noticed that when you create a new user they have absolutely no permissions at all!)
  6. Go to the Login rights tab and set the stores the user can login to.
  7. Click OK when you're done.
  8. The user should now be able to log in.
  9. After the user logs in, they may want to change their password.
Delete a user or group

To delete a user do this:

  1. Go to File > Edit users…
  2. Double-click the name of the user or group you want to delete in the list
  3. Click on the Delete button on the bottom of the edit user window that opens

Note that you won't be able to delete a group that has users belonging to it. If you really want to delete the group, remove all users from the group first by editing their Is a member of fields.

Managing and using groups

mSupply allows for a high granularity of user permission configuration. There are literally hundreds of user permissions possible for each store in an mSupply system. User groups assist with management of these user permissions.

  • Users can be configured to:
    • Log in to particular stores
    • Have a range of general user permissions such as access to the dashboard
  • Users can also be configured to have permission to view or edit data while logged in to particular stores.
  • If users are a member of a group, then permission to view or edit data while logged in to particular stores is governed by the group membership.

A user can have permission to view or edit data while logged in to a particular store, either directly or through membership of a group. If you want the user to exercise these permissions then they will also need to have permission to log in to the store ;-).

Adding a group

Show the list of groups by opening the “Edit user” window and then choosing “Groups” from the “Show” Drop-down menu

To add a group, click the Add Group button. You will be shown a window where you add the group name. You then set permissions for the group in the same way as you set permissions for a user (above):

You will only be able to set checkboxes which can have different settings in different stores. Anything that is not a checkbox and or any checkbox that applies across all stores cannot be set in a group's permissions (another way of saying this is that they cannot be controlled by a group). These items will all be disabled when creating or editing a group and are editable in the individual users' permissions only.

Editing a group

First, show the list of groups by opening the “Edit user” window and then choosing “Groups” from the “Show” Drop-down menu:

Then double click on a group in the list. The same window as for adding a group opens but it is populated with the group's current settings. Change these settings as described for a new group above and click on the OK button to save them.

Active users and groups

All permissions and most checkbox settings in a user settings are controlled by the group. One exception is login rights to different stores (managed for each user individually). Another exception is whether a user is active or not (active means that they are allowed to login to mSupply). By default, the active status of a group does not set the active status of all users in the group to match. However, you can make all users in a group inactive by editing the group and clicking on the Update status for all members button:

When you click on the Active checkbox for a group it does nothing except changee the state of the checkbox. However, when you click on the Update status for all members button, all members of the group have their Active status set to that of the checkbox in this group.

Using groups

Groups are a quick way of setting and managing permissions for many people at a time. Users belonging to a group take the permissions of that group: when a user is a member of a group you cannot edit their permissions directly, you must edit the group's permissions. And if you edit the group's permissions, you edit the permissions for every user in the group. To assign a user to a group, do the following:

  1. Go to File > Edit users
  2. Double click on the user you want to edit
  3. On the general tab of the window which opens, use the Is a member of drop down list to select the group the user is to belong to:
  4. Click on the OK button to save you changes.

User license categories

A menu item on the Special menu of the navigator gives access to a form to view and edit user license categories, including the number of users belonging to them that can be logged in at any one time. A DDL on the user input form allows a user to be assigned to a category and a new permission covers the ability to edit these license categories and membership of them. Finally, a check on the OK button of the login form will check that there are less than the maximum users belonging to the license category the user belongs to already logged in.



Previous: 25.14. mSupply deployment | | Next: 25.16. Show connected users

25.18. Label printer hardware setup

We recommend Zebra ZD421t 203dpi (which has replaced the Zebra GK420t which we recommended previously) label printer with a network port.

It is very important to order the 203dpi model of the ZD421t, as the 300dpi model will not work correctly with our code

You may use other printers that support the ZPL printing language (or EPL if using mSupply 3.2 or earlier), but we cannot provide much support for these models as we have not used them ourselves.

Setup
  1. Load the printer with ribbon and labels
  2. Turn on
  3. Plug in network cable
  4. By default the printer is set to obtain an address by DHCP. Assuming you have a DHCP server on your network: press the button on the front and hold until it flashes once, then release the button. A configuration label will print. Note the IP address. If the printout is the wrong width and unreadable, see “Setting label width” below
    1. You may also be able to get the IP address from the list of DHCP leases when logged in to your router (e.g. for pFsense: Status > DHCP )
  5. There are now 2 options for setting a static address
    1. (Preferred method): Configure your DHCP server to assign a static address to the printer. Note that after doing this, you may have to turn the printer off and back on to get the new address from the DHCP server.
    2. Alternative: Assign a static address to the printer.
      1. The default static address for the printer is 192.168.254.254.
      2. If you are connecting to that address, you must assign your own computer a 192.168.254.X address so it can connect to the printer. You can then log on to the printer using it's current IP address http://printer_ip_address where printer_ip_address is the current printer's ip address (So, out of the box: http://192.168.254.254 )
      3. Go to “Print Server Settings”, then click “Print Server” and log in
        • user: admin
        • pass: 1234
      4. Go to “TCP/IP Configuration” and set an IP address that is not within a range controlled by DHCP (Ping it to ensure it is not already assigned)
      5. Set the IP Protocol to “Permanent”, and submit
      6. Reset the printer (you can do this from the web interface)
  6. Ping the IP address you have set to ensure the printer has the right address
  7. Finally, tell mSupply about the printer: see 10.08. Label printing preferences for instructions on doing that.
GK420 Flash sequences

This is a feature on the printer itself that you access by holding down the Feed button. Refer here for full documentation: https://support.zebra.com/cpws/docs/gseries/gseries_button_modes.pdf

Calibrating the printer GK420

For various reasons the printer may need to be re-calibrated. The act of “calibrating” is essentially to allow the printer to work out the size of label that is being used.

There are many levels of Calibration but we will try the basic one.

  • Switch on the printer.
  • Press and continue pressing the Feed button until the light :
    • flashes once
    • flashes twice »> then let go of the button.
  • The printer will print one to four labels while calibrating.
Setting the label width GK420

Note that you do not have to do this to get the right width when printing from mSupply.

This is only for printing a configuration status label from the printer before using mSupply:

  • Hold down the feed button - the light will flash once, then twice, then three times, then four times, then five times: immediately release the button when it flashes 5 times.
  • It will print a succession of boxes starting at the minimum print width and ending in the printer’s maximum print width in 4mm increments. Press the Feed button once when the box has reached your desired maximum print width.

You can print out a configuration status label with the IP address and other information once you have the printer detecting the label width correctly.

  • Hold down the feed button - the light will flash once: immediately release the button when it flashes once.
Cleaning the printer

Over time, the printer will fail to perform due to collection of dust. We imagine sweat particles will cause friction on the moving parts of the printer and this hinders performance. So in many cases throughly cleaning the printer ends up reviving a printer that seems broken. Please follow the steps below to clean :

  • Take the printer off the mains… So un-plug the electricity.
  • Take out the ribbon and label roll. If you have been printing let the print head cool for a minute. Clean the printer with a small amount of Isopropyl wipes:
    • Wipe the print head
    • Wipe the label roll holder
    • Wipe the track that the paper travels on
    • The last black roller : Turn the roll and wipe.
    • Lastly clean the outside of the printer.
  • Leave the printer for 20 minutes.
  • Reload the ribbon and label roll.
  • Plug in the power cord and turn the printer on.
  • Go through the calibration process.
  • See if the printer behaves.

See the **Zebra GK420t Label Printer User Guide** for further information and diagrams.

Status light descriptions GK420t

What is the Status light on my Zebra GK420 printer trying to tell me???!!!
Info given here on the Zebra website.

LED status and colour Printer Status Details
Off Off Printer not receiving power
Check power connections from the wall outlet to the power supply, and from the power supply to the printer. Disconnect the printer from the wall outlet for 30 seconds and then reconnect the printer to the wall outlet.
Solid Green On The printer is on and in an idle state
No action necessary
Solid Amber Stopped A. After you have been printing
There is a memory error. Turn the printer power off and on, and then resume printing.
B. If this error continues
The printhead needs to cool down. Turn the printer power off for five minutes. If this persists the printer needs a service.
C. Right after you turn on the printer
The printer has failed its power on self test (POST), contact an authorized reseller for assistance.
When the printer is operating normally after power up the status light will be amber for about 10 seconds before turning green (solid or blinking).
Flashing Green Normal Operation The printer is receiving data
As soon as all of the data has been received, the status LED will turn green and the printer will automatically resume operation.
Flashing Red Stopped A. The printer has run out of labels
B. The printer ribbon ha run out
C. The printer is open
Double Flashing Green Paused The printer is paused
Press the Feed button to resume printing.
Flashing Amber Paused The printhead is over temperature
Printing will stop until the printhead cools to an acceptable printing temperature. When it does, the printer will automatically resume operation.
Alternately Flashing Green and Red Needs Service FLASH memory is not programmed
Return the printer to an authorized reseller.
Flashing Red, Red and Green Needs Service The printhead or motor has had a critical failure
Return the printer to an authorized reseller.
Flashing Red, Amber Green Memory Defragmentation The printer is running a defragmentation* process
Do NOT reset or turn off the power!

NOTE: Defragmentation is a normal operation of the GK420t printer. The printer will defragment its memory both after a factory default and when the printer detects that a defragment is required. When the printer is in this condition, allow it to finish defragmenting. If this warning occurs frequently then refer to the printer user guide as some label format changes could resolve this.

Zebra TLP 2844

You may have an old label printer : Zebra TLP 2844

Click to download the user guide for Zebra TLP 2844

On page 48 the manual has a guide on how to manually calibrate the printer.



Previous: 25.17. License management | | Next: 25.19. The system log

25.17. License management

On any mSupply server, you have concurrent user licenses. When a user logs in, they take one of these licenses, when they logout the license is returned. These licenses sit in a single pool, to be used by all users who login to that server.

Sometimes, it can be helpful to split this single pool up into multiple smaller pools. This would be the case when, for example, different organisations use the same server and buy licenses separately for use by their organisations. It is then important that one organisation does not start to use the other's licenses.

To help manage this kind of situation, mSupply has the concept of user license categories. Each of these categories has a maximum allowed number of users logged in at the same time. Each time a user logs in, mSupply checks whether they belong to a license category and, if so, whether there is already the maximum number of users for that category logged in. If so, then the user is shown a warning message and not allowed to login, otherwise they are logged in as usual.

Please note that user license categories are still subject to the concurrent user limit (set by the number of licenses you have purchased), they do not override it. So, if you have 10 concurrent user licenses on your server and you have one or more user license categories with a total maximum number of logged in users set at 20, only 10 users will still be able to log in to your server at any one time. This functionality is not a free way to get yourself extra mSupply licenses, rather it's a way of helping you manage access to the licenses you have purchased!

User license categories only apply to an mSupply server so you won't be able to set them on a single user copy of mSupply (including single user satellite copies in a sync system). There's no point since only a single user can log in at a time to these versions of mSupply!

It is also important that you understand that each mSupply server has its own pool of concurrent user licenses so, if you have more than one mSupply server in your system, you can set user license categories on each server. You cannot set user license categories that affect more than one mSupply server.

Viewing existing user license categories

Choose Special > Show user license categories… from the menus. The following window will open showing a list of all the user license categories you have setup in your datafile:

Creating a new user license category

To create a new license category, click on the New button in the window displayed above and a new window will open:

Enter the details of the new license category:

  • Description: the name the category will be known as throughout mSupply
  • Maximum number of users logged in: the maximum number of users that belong to this group that are allowed to login to this mSupply server at the same time

Click on the OK button when you're finished and you'll be taken back to the license category list window, which will now include your new license category.

Editing an existing user license category

To edit an existing user license category, view the list of existing ones by choosing the Special > Show user license categories… menu.

Now double-click on the license category you want to edit in the list and, in the window that opens, edit the category's description or maximum number of logged in users and click on the OK button to save your changes. You will be returned to the list of user license categories which will show the changes you just made.

Changing the maximum number of logged in users of a license category will not affect any users already logged in who belong to the category (even if there are more than that number already logged in) since the check against this number is only made when a user logs in. But it does mean that it will affect any users who login from that point forward. So, if there are more than the maximum number logged in after a change, then no more users belonging to that license category will be able to log in.

Deleting a user license category

To delete a user license category simply view the list of existing ones by choosing the Special > Show user license categories… menu, select the license category you want to delete in the list and click on the Delete button.

Note: you will only be able to delete a license category if it has no users assigned to it. If you receive a warning to that effect then edit all the users to remove them from the license category first (see below for details), then return here to delete the license category.

Assigning users to license categories

To complete the setup you must assign users to the different user license categories you have created.

You do this by selecting the user license category the user should belong to in the License category drop down list on the General tab of the user's details window. See Managing users for more details on how to set this.

Any users not assigned to a user license category will always be able to login (as long as there is a concurrent user license available in the server's pool). So be careful when using user license categories - leaving many users not assigned to license categories can undermine what you are trying to achieve.

Normally, you will assign more users to a user license category than the maximum number of users logged in setting for the category. Otherwise, the user license category check on login will have no effect!



Previous: 25.16. Show connected users | | Next: 25.18. Label printer hardware setup

25.04. Schedules and periods

Schedules and periods

Schedules are regular timeframes (e.g. monthly, fortnightly) that may be used for cyclical operations, such as program orders (special types of requisitions). There is no limit to the number of schedules.

Periods are specific timeframes which exist within schedules. Periods have a distinct start and end date. They must be sequential and must not have any overlapping dates or gaps between periods.

Permission to add/edit schedules and periods

In a sync system, schedules and periods must be added on the central server and will then sync to other sites. Permission must be switched on for a user to add/edit schedules and periods.

1. Go to Admin > Edit Users > double click the user to be edited > Permissions.

2. In the Admin section, check the Edit periods and period schedules box.

3. Click OK.

Adding schedules and periods

1. In the menu bar, click Special then Periods…

2. To create a new schedule, click the plus icon next to Schedules.

3. Name the schedule and click Save.

4. To add periods within a schedule, highlight the schedule and click the plus icon next to Periods.

5. Name the period, enter its start and end dates, then click Save. You can type dates in the boxes or click the icon to select dates from the calendar.

6. Keep adding all the periods within the schedule. If necessary, you can edit a period by double clicking on it.

7. When you are finished, click Save.

Once a schedule has been saved, it CANNOT be edited.

Check closely before clicking the final Save button!

Using Schedules in Programs

The most common use of schedules is for setting up programs for supplying different facilities on different schedules. You can read more about using programs here



Previous: 25.03. mSupply client / server installation part 3 | | Next: 25.05. Web browser access via TSPlus

25.13. mSupply server administration

mSupply server provides a number of administrative features that enable fine-tuning and robust management of the system.

The server can run as an application or as a service. Running it as a service has a lot of benefits, such as automatic restart when the server machine is restarted, but, for technical reasons, this is not always possible. Here's how you administer the server depending on how it is running.

When running the server as an application

Server monitor

The server monitor tells us our computer hardware specification, database engine version, and license information including maximum connections

Users

The Users tab shows us connected users with LAN information, IP address, machine name and Windows logon user name

Processes

The processes window shows system resource consumption for each process. This is a useful screen to analyse slow or otherwise unresponsive systems.

Maintenance

The maintenance tab is where data info and actions can be retrieved and performed. The window shows when tasks were last performed and provides the settings to perform verification, data compacting and log recording.

Backup

The Backup tab provides settings to manage the way your data is backed up and where the backup file resides. This is a critically important section to manage properly as your data is a key asset of your system.

Schedule a backup:

Configure content and destination of the backup:

Backup & Restore: Decide how many backups to store in your destination folder. You may also set the system to retry backups if a backup is not possible at the scheduled date and time. Eg. if the system is not running.

Backup and Memory settings - according to the datafile

The database backup settings were initially singular but since mSupply v4.14 we have extra options. On the server Settings menu we have the following options :

  • Structure Settings… [This has been widely used]
  • User Settings… [This is not frequently used]
  • User Settings for Data file… [We are now actively using this options]

The “User Settings for Data file…” options saves the backup and memory options as a folder and is located next to the data file.

Above, note that the Settings folder is next to the mSupply data. This setup allows for the mSupply server to be upgraded with backup and memory settings intact.

Application server

Application server: The application server provides settings to manage the structure (.4DC file) and data (.4DD) files. It also provides information about LAN and system memory.

Web server

Web server: The Web server tab shows the web server status and running ports. The web server can be started or stopped form this tab.

When running the server as a service

When the mSupply server is running as a service you need to access the monitoring pages shown above in slightly different ways.

1. By logging into a client

For this, open a client and login to mSupply. Then choose Special > Open mSupply server window from the menus to see the server administration window open as described above.

Please note: to be able to do this, the user must have the Access server administration permission as described on the 25.15. Managing users page.

2. By using a browser

To access the server administration pages from a browser, the mSupply webserver must be running (see the 19.02. mSupply web server page for details on how to turn it on).

Then open a browser and enter the mSupply server's URL followed by /admin/ini e.g. https://mymSupply.msupply.org:8048/admin/ini

A window like this will open in your browser:

Use the tabs down the left hand side to navigate to the different pages which work very similarly to the pages described in the sections above.

mSupply file extensions and types

This information is just for reference and to help your understanding.

On both Macintosh and Windows OS - five files.

  • A structure file (.4DC suffix)
  • A structure resource file (.rsr suffix)
  • An executable file (.exe suffix)
  • A data file (.4DD suffix)
  • A data resource file (.4DR suffix)

File arrangement

It is easiest to keep all relevant files in the same folder, in a reasonably accessible place on your hard drive. (For example, directly on your “C” drive.)

If you make copies, don't leave them in the same folder, or you'll just get confused!

There are several folders to store reports and queries that need to be in the same folder as your structure file. Note that these folders are automatically created when you unzip the program files the first time. They are mentioned here so those of you with an inquisitive streak won't unknowingly do damage!

  • A reports folder. This stores reports that are used by the program. Leave this folder alone- store your own reports in the custom reports folder.
  • A custom reports folder. Store the reports you create here.
  • A custom queries folder. Store the queries (searches) you create here.
  • A custom labels folder. Store any label templates you create here.

Note that on Windows or Macintosh the run time application (that is, the database engine- “4Drun.exe” file on windows) can reside anywhere on your hard disk, and does not need to be regularly backed up (although you should have one backup copy somewhere!)

Getting the right data file when you open mSupply

Important! If you open mSupply by double-clicking the “start mSupply” icon on the desktop (Mac users- by double-clicking the structure file), mSupply will try to open the same data file that was last opened. It will open the same file each time if you repeat the same procedure. If you make a copy, and then double-click the copy of the structure file, mSupply may still open using the data file from the original if it can find it.

To choose the data file manually do this:

Mac: hold down the option key as you click the OK button in the password window. You will then be given an open/save box to choose the correct data file.

Windows: Launch the program and then quickly hold down the Alt button until you see a box come up. It will give you an option to Select another data file.

If you are not sure which structure and data file you are currently using, on a pc logged into the correct datafile, choose about mSupply… from the help menu (Windows) or the apple menu (Mac).



Previous: 25.12. mSupply dispensary installation | | Next: 25.14. mSupply deployment

25.01. mSupply client / server installation part 1

  • mSupply Server can be installed on a range of Windows OS hardware platforms. Installations of the mSupply Server and client software on these different platforms will not be identical.
  • This page includes instructions for installing the mSupply Server and client software on a typical Windows 10 Pro platform. This will include many hardware configuration issues as these have been known to be important for mSupply Server operation and troubleshooting.

Refer to Windows and Mac hardware requirements for details of server hardware requirements.

Installation pre-checks
UPS (Interruptible power supply)
  • Unless you have extremely reliable power we strongly suggest you install a UPS with external batteries that will provide several hours run time, e.g.:
  • The UPS must be able to communicate with the server (usually with a USB cable) to initiate a graceful shutdown in advance of UPS shutdown.
  • For the UPS to protect the server from power surges / spikes, the UPS needs to be connected to a power socket that is properly earthed.

More details on configuration of the UPS is contained below.

ICT capacity

Do you have sufficient in-house ICT capacity to do the rest of the server installation yourself?

  • This server hardware belongs to you (or maybe not… see tip below).
  • Sustainable Solutions is a software development company and our core business is not hardware

However, we know that if the server is not installed and configured correctly, the mSupply software and your medical supplies data is vulnerable. Therefore, in most instances, we end up playing a significant role in installing and configuring the mSupply Server.

Over recent years, with the development of reliable and relatively low-cost cloud based server solutions, more and more mSupply client / server installations have used a cloud based server. In many cases, Sustainable Solutions has provided this cloud based server as a separate service, thus relieving you of any responsibility for installation, configuration and management of the mSupply Server hardware.

Initial server hardware setup

Set up the physical hardware including

  • RAID 1 volume with Spare (3 disks total)
  • Separate backups volume
  • OS install with correct region, and keyboard - refer Region / Language below.
  • Administrator account called Sussol (mSupply server will operate from this account.
Miscellaneous server tweaks

There are a number of miscellaneous server tweaks that we recommend:

Decimal Symbol

The PC can sometimes have the incorrect decimal symbol (e.g. $2,000,00 instead of $2,000.00).

You can update the decimal symbol through your regional settings. Start by opening Control Panel and choose Change date, time or number formats (as shown below).

You will have the Region window appear. Click Additional settings… in the bottom right.

You will now see the Customise Format window. Select the Decimal symbol drop-down list, and select the desired decimal symbol - for most countries, the default is a full stop.

Click Apply to save these changes!

Hibernation / sleep
  • The pc can go to sleep after a few hours so change the power settings to never sleep etc. Even after setting the sleep setting to never you still must go into the advanced settings and change the hibernate setting to never: How to turn off Hibernation on Windows 10
Set correct regional settings including keyboard, copy to 'New user accounts'

Microsoft keeps changing how these settings are accessed. You'll likely need to hunt around to find them :-(

Be sure to set the correct regional settings, particularly if this is a cloud server which may be physically located in a different region to the country where the server will be used…

  • Go to Settings → Time & Language → Region & Language → Language
  • Click on Change date, time, or number formats
  • A Region window will open, set your preferences on Formats and Location tabs.

Even if you chose the correct keyboard (normally US) during setup, another keyboard (like the UK keyboard) can sometimes still be the default keyboard. Check this by trying to type the @ character… To fix this, you will need to:

  • Add the correct language (e.g. English (Australia)). This will auto select US keyboard
  • Move it up to the default position and delete the other language option(s).
Date format
  • In the regional settings in Control Panel, we recommend that the short date format is set to display only 2 digits for the year (YY, not YYYY).mSupply lists are set up to allow only enough space for 4 digits with most font sizes, but occasionally 4 digit years may be truncated. Having the wrong setting here will only affect display, not the actual data. It does not matter if you use DD/MM/YY or MM/DD/YY or YY/MM/DD
  • If the display of lists in mSupply overlaps the separator lines, turn off large font in the display control panel.
Copy to New user accounts
  • Click Change date, time or number formats
  • Click Administrative tab.
  • Click on Copy settings button. On the next window:
  • Check Welcome screen and new user accounts settings will open.
  • Check New user accounts check box.
  • Click OK button on same window
  • Click Apply button and then OK button on Region window.

Trouble Shooting

Turn off UAC (User Account Control)

Only follow this step if the mSupply Client requires user permission every time to run. In that case, you may need to do the following to avoid the UAC popup:

User Account Control (UAC) can interfere with 4D - refer 4D Knowledgebase: Tech Tip: Windows UAC and the "Program Files" directory, so, we need to turn it off - refer https://social.technet.microsoft.com/wiki/contents/articles/13953.windows-server-2012-deactivating-uac.aspx

  • You have the option to turn off UAC via registry by changing the DWORD EnableLUA from 1 to 0 in HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\policies\system
  • You may get a notification that a reboot is required. Reboot anyway.
  • After the reboot, UAC is disabled.
Region / Language

After installation, if mSupply fails to start, then it's quite possible that the Language setting needs to be changed. Not all Windows OS languages are supported by the 4D database that mSupply is built on. Unfortunately, 4D does not maintain a list of unsupported languages.

For example with regional format setting of English (Nigeria) it is known that mSupply will not start.

The solution is to change the regional format setting to something more common like English (United Kingdom) or English (US):

For language tab, Drag and drop “English (United States)” at the top of the preferred list:

Known unsupported languages include:

  • English (Nigeria) (2019-08-28)
  • English (Papua New Guinea) (Win10 1903)
  • English (Cook Islands) (2020/10/1)

If you discover other unsupported languages, please let us know, and we'll update this list!




These steps need to be followed by the steps in 20.02 mSupply client/server installation part 2 and 20.03 mSupply client/server installation part 3



Previous: 25. Technical Administration | | Next: 25.02. mSupply client / server installation part 2

25.02. mSupply client / server installation part 2


These steps need to be carried out after completing the steps described in:
25.01. mSupply client / server installation part 1

Install associated server application software

It can be useful to Install Dropbox first so that you can use the Dropbox folder to transfer software and files to the server. But if the internet connection is fast enough, it is easier to start with Installing the remote support software, and then letting the Dropbox be configured remotely by mSupply Support.

Install remote support software
Installing the TeamViewer Host customised for mSupply

1. Uninstall - if TeamViewer is already installed on the machine, it is safest to uninstall it.

2. Change the Computer Name to something meaningful before installing TeamViewer. Using a name that reflects the site and / or user would be helpful. e.g. Auckland - Grafton Pharmacy - this is what the machine will show up as on our international directory.

The TeamViewer Host module appears to only use the first 15 characters of the name. If you are connecting several computers, make sure that the first 15 characters are unique for each computer.

3. To change the computer name in Windows go to: Control Panel > System and Security > System > Advanced system settings > Computer Name > Change…

4. Note that the Computer description is NOT the Computer Name

5. Download and save the zip file at the following link https://www.msupply.org.nz/files/Teamviewer/TeamViewer%20Deployment%20September%202024.zip

6. Extract the files from the Teamviewer Deployment March 2024.zip file onto the host computer.

7. Open the folder you extracted

8. Run as administrator - right click on the file Install TeamViewer.bat and select Run as administrator. The script will check to see if it is running as an Administrator, if it isn't running as an Administrator, the installation will stop.
The Teamviewer Customised Host window should appear on your screen:

If the above window does not appear, the full installation has not completed. It definitely helps to run the batch (Install TeamViewer.bat) file with a reasonable internet connection. If the internet connection is not good enough, then some or all of the actions in the batch file will not be complete. If that happens, please uninstall TeamViewer and re-run the batch file (as Admin) when the internet connection is better.

9. Notify mSupply Support When you see this TeamViewer Host window, send us a message or email (on support@msupply.org.nz) and give us the computer name that you gave the machine in step 4 above. Otherwise, the TeamViewer ID should also work (a screenshot is fine). We will then be able to confirm for you that the remote access is operational and ready for us to provide you remote support.

It is recommended to use Google Chrome as browser if you use teamviewer on web. It supports “WebClient” connection more than other browser

Install Dropbox

Sustainable Solutions recommends using Dropbox to assist with transferring installation files to the server, and as a means of moving mSupply secondary backups off site.

  • Contact Sustainable Solutions to organise a DropBox account for the server and for instructions on setting it up on the server.
Install UPS hardware and software if required

If it's not already done, install the UPS hardware and software, refer to the UPS requirements here.

Install anti-virus software

Anti-virus can be a hotly contended issue. This web page is pretty convincing: What’s the Best Antivirus for Windows 10? (Is Windows Defender Good Enough?)

Conclusion:

  • If the OS is Win8 or later, Windows Defender is probably good enough for anti-virus, and better than much of the competition.
  • Once configured, the server should not be vulnerable to exploit programs as these are usually downloaded and triggered by human activity! However, to be safe, it is recommended to install an Anti-exploit program such as Malwarebytes. The website suggests that Malwarebytes is not free, but as at the time of writing this (May 2018), Malwarebytes successfully reverts to a free version after the 14 days trial. The main 'cost' of the free version is means that it has to be manually executed rather than running automatically in the background.
Install another web browser

Don't use Microsoft Internet Explorer, (12 reasons not to use Internet Explorer, ever)

Install another browser:

Good options include:

Pin the browser to the taskbar

Install OpenOffice, Microsoft Excel or LibreOffice

mSupply can produce reports in Microsoft Excel format. Client machines will need to have software to open these reports. Occasionally there will be need to run and open these reports while logged in to the Server. If you do not have Microsoft Excel installed on the server, LibreOffice is a good alternative.

Install TurnedOnTimesView

As part of troubleshooting, it is valuable to be able to analyse when the server has shut down ungracefully.

  • If you get a security warning pop-up untick “Always ask before opening this file” and click Run

  • Right click on the icon on the Windows Taskbar & select to Pin to Taskbar.

Install Logoff and Lock utilities

It is too easy for support workers accessing the server remotely to accidentally shutdown the server. Therefore, two Windows shortcuts have been created to allow support workers to easily logoff or lock their windows session without having to go through the usual Windows procedure:

  • Lock computer
  • Logoff computer

Lock / Logout utilities

It's a good idea to stick this in to the following folder in Dropbox:

  • Lock Logout Shortcuts

The Yellow Lock computer utility needs to be copied to the Admin desktop and then pinned to the task bar.

The Green Logoff computer utility needs to be copied to the C:\Users\Public\Desktop folder. This will place the shortcut on the desktop of each normal user. Users of each normal user account will need to pin this shortcut from the desktop to the taskbar. Don't pin it to the taskbar of the Admin user account. We try to keep the Admin account open (but locked) so as to keep Dropbox working.

The C:\Users\Public\Desktop folder is normally a hidden folder. You will likely need to make it visible).



These steps need to be followed by the steps in 25.03. mSupply client / server installation part 3





Previous: 25.01. mSupply client / server installation part 1 | | Next: 25.03. mSupply client / server installation part 3

25.03. mSupply client / server installation part 3


These steps need to be carried out after completing the steps described in:
20.01 mSupply client/server installation part 1
20.02 mSupply client/server installation part 2

Obtaining a data file

If you are setting up a sync site for a synced system, then you will need to:

  1. Generate the XML file for the sync site from the central server - refer 29.04. Sync Site Export
  2. If creating a single-user sync site:
    1. Transfer the XML file to the sync site. The Dropbox that you configured in Install Dropbox is handy for this purpose.
    2. Create the datafile from this XML file through 29.05. Sync Site Import.
  3. If creating a server sync site:
    1. Create the datafile from this XML file through 29.05. Sync Site Import. This could be done on the server, but is normally easier to do 'locally'. Make sure you are NOT using a version of mSupply more recent than that being installed on the server. Contact support@msupply.foundation to confirm which version to install.
    2. Transfer the datafile to the sync site. The Dropbox that you configured in Install Dropbox is handy for this purpose.
Installing mSupply Server software
If you are upgrading from a previous version...

If you are upgrading from a previous version of mSupply, first perform a data backup:

  • With mSupply server open as an application click on File> Backup…. This will generate a backup file of your current data with file extension .4bk.
  • Copy this file to at least one safe place, e.g. USB drive, a cloud service such as Dropbox.
  • Continue only when the .4bk file has completed transfer to the remote location.

Moving from pre v3.50?

There was a major upgrade of mSupply's internal structure in v3.50. If you are upgrading from a pre v3.50 installation of mSupply, Sustainable Solutions will need to convert your data so that it can be read by mSupply versions after v3.50. This conversion process is provided free of charge.

Obtain and run the mSupply Server installer

The client/server version of mSupply has two installers:

  • One installer, with the word Server in the title, is used to install the mSupply Server software on a single server computer.
  • The other installer, with the word Client in the title, is used to install the mSupply Client software on as many computers as you wish including on the server computer. You will be limited in how many clients can connect at any one time by the server licence you have purchased.

You must be logged on as Administrator to install mSupply Server with the correct permissions. Please consult your IT support staff if you require assistance to achieve this.

Once you have obtained the mSupply Server installer file, double click it to install. Here is what the mSupply server installation window should look like:

  • You may be asked by the operating system whether 'you want to allow this app to make changes to your device?'. Click Yes
  • At the mSupply Server Setup Welcome screen, click Next
  • To proceed with the installation, you will need to click on the 'I agree to the terms of this license agreement' radio button and click Next
  • Unless you have good reason to do otherwise, don't change the installation folder, and click Next
  • Unless you have good reason to do otherwise, don't change the Shortcut folder, and click Next
  • At the Ready to Install window, click Next
  • After some time (minutes!) you will be shown the Installation Successful window. Click Finish
What is installed where:

We strongly recommend you do not change the default installation directories, which are as follows:

  • mSupply Server: C:\Program files\mSupply\mSupply Server
  • mSupply Client (see Installing mSupply Client below): C:\mSupply Client
mSupply Server installer also installs the following files and folders:

Starting the Server for the first time
  • There is no point in carrying out the following steps unless you are ready to create a new mSupply data file, or you have one to load.
  • If this is a satellite site on a synced system, you should have one to load - refer Obtaining a data file.
Run mSupply Server

We need to run mSupply Server as an application until all configuration is completed. Don't run as a Service now as some configuration functionality is not enabled when run as Service.

Sometime it has been useful to allow the mSupply.exe to run as Administrator by default. This gives the application the right to modify data in folders that may have been unknowingly restricted by operating system.

View the mSupply.exe file inside the mSupply installation folder. View properties then Compatibility tab and set the file to always Run this program as an administrator. View the image below for better guidance.

We need to run the mSupply Server software as Administrator.

Find the mSupply Server executable (C:\Program files\mSupply\mSupply Server\mSupply.exe), right-click on it and select Run as administrator

You will then be presented with the following dialogue box:

Click Create to create a new data file or Open to choose an existing data file. The below image shows an existing data file.

Since Windows version 1803 and following, there can be issues with permissions to access folders located in individual user folders such as under My Documents. Therefore, it is now highly recommended to save your data file in the folder: C:\ServerName_mSupply_data replacing ServerName with the mSupply server (site) name, eg. C:\Hagen_AMS_mSupply_data.

You may get a question from the Windows Firewall requesting permission for mSupply to communicate through the Firewall.

Allow mSupply to communicate on both private and public networks.

If the above steps have succeeded, you should see the 4D Server Administration window:

Configure backups
  • Edit > Settings > User settings for Data file > Backup tab
    • Scheduler: Set Automatic Backup: to Every day, at 20:00 or later, as long as it is a time when work is likely to be finished. It will have to be set earlier, say 16:00 if the server is switched off of an evening.
    • Configuration:
      • Content:
        • tick Data File
        • untick Structure File
        • untick User Structure File
        • Delete all 'Attachments' except the .4DIndx file.
        • Add the journal (journal) files to the backup. The Journal file cannot be selected until you have configured it under Log Management below, and run the backup once, which you can do once the backup settings have been configured. Once these have been configured, the backup contents should look something like this:
        • If this server uses the Dashboard, then add the dashboard configuration files (normally C:\Progran Files\mSupply Dashboard\data\grafana.db and C:\Program Files\mSupply Dashboard\conf\custom.ini) to the backup - see here (noting that the journal file hasn't been added yet!):
  • Backup File Destination Folder
    • If on physical hardware, this should be a separate physical disk (e.g. D:\mSupply_backups).
    • If on a virtual machine it is preferable to store the backups on a separate virtual disk.
  • Log Management: Set .journal to the same parent folder as the backups.

If a location of the log file is already specified, and you want to change it, you need to untick the “Use Log” tick-box and then when you re-tick it you will be prompted for a new location.

  • Backup & Restore
    • General settings
      • tick Keep only last 30 backup files (dependent on disk storage space).
      • tick Backup only if the data file has been modified
      • Delete oldest backup file after backup
      • If backup fails: select Retry after 30 Seconds
      • tick Cancel the operation after 5 attempts.
    • Archive
      • Segment Size (Mb): None
      • Compression Rate: Compact
      • Interlacing Rate: None
      • Redundancy Rate: None
  • Automatic Restore
    • tick Restore last backup if database is damaged
    • tick Integrate last log if database is incomplete
  • Click OK

You may see the following dialogue box:

  • Click OK to create the first backup.
Configure cache

Edit > Settings > User settings for Data file

Select Database and then set up the cache memory.

  • Tick Calculation of adaptive cache
  • Memory to be reserved for other applications and for the system: = 512 MB (default?)
  • Percentage of the available memory used for cache = 100%. According to the 4D v16.5 Database/Memory page, 'Percentage of the available memory used for the cache = 100% since there is only one 4D Server application.' If other applications running on the server need additional RAM, it should be added to the figure above.
  • Minimum size = 1,000 MB (default?)
  • Maximum size = can be set to any number, including greater than available RAM. If this number is greater than the available RAM, 4D will adapt the size of the cache according to the actual available RAM.
  • Flush Cache every: 2 Minutes

  • Click OK
  • Exit 4D Server Administration window.
  • Check that the settings.4DSettings file has been created in the <DataFolder>/Settings folder
Setting the server software to run as a service

The server should now be set to start automatically when the machine is turned on. This can be accomplished by setting the server to run as a service. Choose File > Register Current Database as Service.

If the Register Current Database as Service option is greyed out, you are probably not running the mSupply Server as Administrator. You need to quit the server and run as Administrator.

Once you have registered the Current Database as Service, Quit the 4D by clicking the close box on the top right (or choose File > Quit from the menus). You will then be shown a disconnect window something like this (you can select Disconnect all clients and quit if no users are currently active):

Pin Services to the taskbar

It is important to be able to quickly observe the status of the 4D / mSupply Service. Therefore, we pin Services to the taskbar:

  • Click Windows icon
  • Type Services
  • Right-click the Services Desktop App
  • Select Pin to taskbar
Configure mSupply Service settings

Click on Services in the task bar. You will be shown a window like this.

Double-click on 4DServer: mSupply - fortunately it is usually the first item in the list!

You will be shown the 4DServer: mSupply service properties window. Change the Startup type in the drop-down list to automatic (Delayed start).

Log on as administrator account

With mSupply 3.85+ on Windows Server 2012+ and Windows 10 1803+ the service has had to be assigned to “Log On” to an administrator account for mSupply service to start:

Configure the computer to restart if the mSupply service does not start
  • Sometimes, for some reason, including, for example, after certain Windows OS updates, the mSupply Service will not automatically start, even though you have configured it to.
  • To guard against this, it may be worth configuring the computer to restart if the mSupply service has not started after a LONG delay, say 120 minutes. This is done on the Recovery tab:

Manually starting the Service

Despite being configured so, the mSupply Service sometimes will not start when the server hardware starts. The service can be started through the Services:

Manually stopping the mSupply Server Service
  • To manually stop the mSupply Server Service, first make sure clients are not connected, then double-click the “Services” shortcut you made on the desktop, highlight the 4D Server service, and click the square “stop” button (looks like a “Stop” button on a media player)
Creating a new data file or choosing a different data file

From this point there should be no need to revisit any of the above procedures to operate mSupply. However, if you are testing, or starting a data file for a second organisation, you may wish either to change the data file mSupply is using or to create a new file.

The mSupply program (the files named “mSupply.4DC” and “mSupply.RSR”) store the path to the last data file used, and the next time mSupply is started, the previous data file that was open is opened again unless there is user intervention or the “old” data file has been moved to a new location.

To intervene, hold down the “alt” key as the 4D server starts up.

You will be shown the standard open/save window:

To create a new data file, click the “New” button.

To select an existing data file, navigate to the file's location then click the “Open” button.

SSL Certificate

The mSupply server also has a webserver as mentioned here.

It is recommended that a public facing web server should have an SSL certificate installed. For the mSupply server a 'cert.pem' and 'key.pem' need to be generated using the SSL certificate that has been purchased from a SSL vendor.

Theses files needs to be stored inside the folder C:\Program Files\mSupply\mSupply Server\Server Database as shown in the image below.

The cert.pem file contains the certificate in the following format and can have the root as well as the intermediate certificate. 

-----BEGIN CERTIFICATE-----
MIIGUzCCBTugAwIBAgIRAP9nsdfsfdsdfYH0oEZgg3k28WUoYQgQwDQYJKoZIhvc
gY8xCzAJBgNVBAYTAkdCMRswGQYDVQQIExJHcmVhdGVyIE1hbmNoZXN0ZXIxEDAO
BgNVBAcTB1NhbGZvcassdsdmQxGDAWBgNVBAoTsdfsD1NlY3RpZ28gTGltaXRlZD
AxMuU2VjdGlnbyBSU0EgRG9tYWluIFZhbGlkYXRpb24gU2VjdXJlIFNlcnZlciBD
QTAeFw0yMzA2MTYwMDAwMdsadsdDBaFw0yNDA2MTUyMzU5NTlaMCExHzAdBgNVB
Junk
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
MIIGEzdddhuyuyuyuCCA/ugAwIBAasdasdgIQfVtRJrR2uhHbdBYLvFMNpzANBg
iDELMAkGA1UEBhMCVVMxEzARBgNVBAgTCk5ldyBKZXJzZXkxFDASBgNVBAcTC0pl
cnNleSBDaXR5MR4wHAYDVQQKExVUaGUgVVNFUlRSVVNUIE5ldHdvcmsxLjAsBgNV
BAMTJVVTRVJUcnVzdCBSU0EgQsdsd2VydGlmaWNhdGlvbiBBdXRob3JpdHkwHhc
MTAyMDAwMDAwWhcNMzAxMjMxMjM1OTU5WjCBjzELMAkGA1UEBhMCR0IxGzAZBgNV
Junk
-----END CERTIFICATE-----

The the key.pem file contains 

-----BEGIN PRIVATE KEY-----
MIIEvAIBADANBgkasasdfqhkiG9w0BhgghAQEFAASCBKYwggSiAgEAAoIBAQCqPA
TZB5GnFAODhHMTU+pqGD8eS6NOzWwhoyb2dvZv1w2Gh6fcprPUpATltvcMe8q+fe
+ITiYylKfcs2nNYyirr2sdfsdfSPGMKR277MW6G7etFCGjBH/Ae9gRcFk4z8Arnj
e9oRf/UChO21bHjN9itHGIT/7ssp068EufJ+thAdDxzp3xNw70lkAXMxzsZhSJ8k
CTvUxUF6Niul/1ZReUURCZp6coIweewerRhoLe6KXpgfuuIqtpvyOs2AcGRI6qfx
iC20nTBKweefzPg4Uo9d6DdhQD7xdklD1SXlcTgEXpa0Cc/iUGthXWvyWyff5uB
junk==
-----END PRIVATE KEY-----

More recently we have moved towards using Caddy server software which setup a reverse proxy server which use Let's Encrypt to automatically update SSL certificates. This will avoid the need to manually watch and update expiring SSL

Installing mSupply Client

Needed: mSupply Client software of the same version (or relatively recent) as the mSupply Server.

  • The mSupply server should run as a service on the server computer - see above. If any user needs to use mSupply on the server (not recommended, but possible, and sometimes necessary) then they should not be running the mSupply Server software. They should run the mSupply Client software, which should be made available to all user accounts.
Obtain and run mSupply Client installer

You must be logged on as Administrator to install mSupply Client with the correct permissions. Please consult your IT support staff if you require assistance to achieve this.

  • Once you have obtained the mSupply Client installer file, double click it to install.

The mSupply client will be installed in the folder C:\mSupply\mSupply client on your computer.

mSupply client installer also installs the following files and folders:

  • A shortcut on the Desktop called mSupply client.
  • A folder called “\4D\Network” in the Windows folder on the startup volume, which contains network component files that need to be present for 4D to communicate over a TCP (and other types of) network(s).
  • No reports are installed on 4D client. Each time 4D client connects to the Server, reports that have been added or modified on the server are automatically copied to the client.
  • Installers have been set up to overwrite existing files, so reinstalling the software will restore any potentially corrupted files to their original state. The installer will not overwrite your data files, unless you have been unwise enough to name your data file “example data” and put it in the “example data” folder ;-).

For convenience, pin the mSupply client desktop shortcut to the taskbar.

If any other Windows users will use this computer to access mSupply, it is worth copying the mSupply client desktop shortcut to the C:\Users\Public\Desktop folder. This will place the shortcut on the desktop of each user. Each user will need to pin this shortcut from their desktop to the taskbar.

The C:\Users\Public\Desktop folder is normally a hidden folder. You will likely need to make it visible).

Additionally, if this computer is primarily used for running mSupply, then it is worth copying the mSupply client desktop shortcut to the Startup folder. The actual folder name changes with Windows version :-( so here are instructions: How to Add Programs, Files, and Folders to System Startup in Windows.

Starting the mSupply Client

Once the installation is completed, double-click the “start mSupply Client” shortcut on your desktop. A window something like this should appear:

The window lists available mSupply servers on your network (there should be only one!) Click on the server you wish to connect to.

  • Once you have connected successfully, the mSupply Client 'remembers' which Server you last connected to and stores this in the Recent tab. Whenever you run the mSupply Client, it will automatically connect to that server.
  • If, mSupply Client cannot connect to the mSupply Server, this window will pop up showing the Recent tab. You can try choosing the server there.
  • If, for some reason, network settings have been changed and you cannot connect from the Recent tab, remember to look at the TCP/IP tab as well.

Clicking the “OK” button will take you to the mSupply password entry window. For new data files, the password is user1 for the first user in the list. Click on the first user, then enter the password and click OK

Forcing mSupply Client to re-sync files from the server

Occasionally the mSupply client may fail to connect with the server for un-known reasons. Errors such as the “This database has not been compiled for 64-bit processors” has been encountered and can be fixed in the following manner. Please read on.

Sometimes simply forcing the mSupply client to retrieves all setup files from the server may just fix things.

To do this Double click on the mSupply Client icon and hold the “Alt” (option on MAC) key. You should see such a window open.

On the above window select the server and click the custom tab.

On the above window check the Force update of local resources checkbox and click the OK button.

This will force the mSupply client to get the resources from the server and past issue may now be resolved.

Close mSupply and restart normally without the “Alt” key and mSupply client should be able to connect to the server without errors.

mSupply Client software cannot see the mSupply Server?

Server is not visible?

  • To make it easy for you to connect, mSupply Server publishes details about available servers on a specific port. It is quite possible that products such as “Zone Alarm” and “Norton Personal Firewall” will block access to this port and stop discovery of the servers. Contact your system administrator if the list of available servers is blank.
  • Of course, it may be possible that the mSupply Server service is not running. Check Services to establish that.
  • Lastly, the Windows firewall may be blocking the Server publishing it's presence - see below.
Configuring Windows firewall on server

The Windows firewall may need to be adjusted to allow the Client to receive Server identification.

To locate an mSupply server on a network mSupply client broadcasts over the subnet on random UDP ports from 49157 and above. As such inbound UDP ports from 49157 upwards should be opened on the server firewall. If these UDP ports are not open on the server then the clients cannot automatically find the server. However clients can still be manually directed to the server IP address by holding alt when client is opening, and entering the IP address in the network address field of the custom tab.

The default ports for client/server communication in mSupply server are TCP 19812, 19813 & 19814. The server firewall will require inbound TCP ports 19812, 19813 and 19814 to be opened (however these ports can be changed in mSupply server if required).

The firewall on the Client machines could also block access to the server machine. Testing with the firewalls on the server / client machines temporarily turned off in various combinations will help to establish whether firewalls are blocking communications.

Manually configuring the mSupply client

Due to firewall or if you connect to mSupply server via a router, then you may need to enter in the IP address on the mSupply Client custom setting window.

The data base name is always : mSupply

If mSupply server is serving via the default port (19813) then simply enter in the IP address. Otherwise, see more details on the Custom Tab.

As part of the installation, a batch file with the name Reset client temp folder is installed on the desktop. This is for use if the client begins to behave incorrectly in the future, as described on the 28.01. How to re-set the mSupply client page. It is not for use during installation so you can safely ignore it until it is needed in the future. It is safe to move the batch file to somewhere other than the desktop if needed.

Forcing mSupply client to connect to a specific mSupply Server

Within an organisation it is possible to have multiple mSupply server running like in the image shown below.

Now you as a administrator may require a particular mSupply client to connect to one of the server and to ignore the others. To reduce confusion to the user you may require the user to connect to a particular mSupply client.

It is possible to direct a mSupply client application to look out for a particular mSupply server only. Let us assume that you want a certain computer to access the mSupply server with a IP address of : 192.168.3.200

  • Install the mSupply Client.
  • Navigate to `C:\mSupply client\Database`
  • You will see the `EnginedServer.4DLink` file, use Notepad to open it.
  • For the server path `server_path=“:19813”` Enter a valid msupply server IP like `server_path=“192.168.3.200:19813”`
  • save the `EnginedServer.4DLink` file
  • Now when you start the mSupply client, it will know where the mSupply server is and will look for the IP : 192.168.3.200

mSupply Server configuration
Register mSupply

The procedure is described earlier in “Preferences” chapter of the mSupply manual. See The Register button

You will either have to phone or email the information to Sustainable Solutions to obtain a registration code.

The registration code is keyed to your Organisation name and the MAC address of the server. Changing either of these will require a new code, which we shall willingly provide. So, take care when setting the Organisation Name!

Configure mSupply preferences

Once registered, you may want to systematically to go through the mSupply Preferences and choose appropriate settings, and particularly setting up the Secondary backups! Start here: Preferences > General

Turn off web dashboard

If the web dashboard has been set up on the Primary Server, then the dashboard preferences will be copied to the Satellite site datafile. In most cases, the web dashboard is not being used on the Satellite site and it is an unnecessary interaction with the scheduler, so may as well be turned off:

Before v4.04:

  1. File > Preferences… > Dashboard
  2. Untick the 'We use the web dashboard'
  3. Click OK

After v4.04, the dashboard is managed through the Admin page of the navigator:

  1. Admin > Dashboard > Export Settings
  2. Clear the Postgres Server entries
  3. Click OK

Configure secondary backups

You should have already configured the primary backup. We recommend setting up a secondary backup which will send a backup off-site using a service such as Dropbox. The frequency of this depends largely on what bandwidth your site can afford. Each backup can easily get to GB sizes…:

  • File > Preferences… > Backup 2
    • Configure secondary backups
Turn on Synchronisation

When you are finally ready to turn on synchronisation:

  • File > Preferences… > Synchronise > Click to un-lock, enter code to edit.
    • Set the Sync time interval to 1
    • Click OK

Your installation of mSupply may have customisations made specifically for your work scenario. Please contact our support staff on support@msupply.org.nz to manage these customisations.

Configure label printer

If you are dispensing, you will need to set up label printer preferences

Graceful shutdown in the event of a power failure

Your mSupply server should be attached to a UPS. The UPS should be fitted with a control cable (serial, USB or network cable) that allows control software to detect a low power situation and shut down the server.

In the UPS control software set the shutdown to start at least two minutes before the power will fail.

Set it to run a batch file at that point. The file should contain the single line “net stop Service name” where the service name is the name displayed in the properties when you double-click the service name in the services window. In the example below the service name is “4DS mSupply.4DC” (not to be confused with the display name)

You may wish to test your typing skills by opening a command prompt:

Accessing mSupply client on a cloud server

If the mSupply client software is running on a PC, there are a range of applications that can be used for accessing the cloud hosted mSupply server including Microsoft's own Remote Desktop Connection software that comes included with Microsoft Windows.

We recommend TS-Plus, which allows users to access client on the server via their web browser.

Troubleshooting

Permission for backup setting file

Since v17 of 4D (the database engine underlying mSupply), when running mSupply as a Service, logging on as the Local System Account (LSA, as described below), mSupply MAY no longer have sufficient permissions to access the folder: C:\Program Files\mSupply\mSupply Server\Server Database\Preferences\Backup

If this is the case, it will result in the following error:

If this happens, it needs to be fixed. The Solution is to edit permission of Users to allow Full control/Modify/Write to the Backup.XML file as shown here:



Previous: 25.02. mSupply client / server installation part 2 | | Next: 25.04. Schedules and periods

25.20. Server troubleshooting

Service not running

If the client is unable to connect to the server, it is quite possible that the mSupply Server Service is not running.

You can check by going into Control Panel>Administrative Tools>Services

Look for the service named 4D. The status should be “running” or “started” and it should be set to automatic.

If it is not running or started you can click the play button above the list of services while you have 4D highlighted. The status should now read “running” or “Started”. If it doesn't please contact mSupply Support for help. support@msupply.org.nz

mSupply Client software can not see the mSupply Server?

Refer mSupply Client software can not see the mSupply Server?

Sync not working

If, on a sync satellite client, the number of sync records stays static, or continues to grow over a significant period (hours), then sync between the (Sync Satellite server to the sync Primary server) has stalled.

Sync stalled...

A probable reason for this is that the Sync Satellite server can not connect to the sync Primary server. You can check this by checking the logs (Special > View log…):

Unable to access server...

There are a number of possible reasons for this:

  • The Sync Primary server hardware is down. Check that the Sync Primary server hardware is up.
  • The Sync Primary service (software) is down. Check that the Sync Primary service (software) on the Sync Primary server hardware is up.
  • The IP address of the Sync Primary server hardware is incorrect. The IP address of the Sync Primary server should be a domain name, e.g. orgname.msupply.org. However, this domain name will be mapped to an IP address that should be static. If the ip address of the Sync Primary is different to what the domain name server maps it to, then sync will fail. To confirm this:
    • Find the IP address of the Sync Primary server hardware, at the Command Prompt on the Sync Primary server, enter ipconfig.
    • Find the IP address that the domain name server thinks is associated with the domain name, at the Command Prompt on the Sync Satellite server, enter nslookup orgname.msupply.org. Compare the reported ip addresses.
  • Access to the Sync Primary server hardware may be blocked by a firewall or proxy server on the Sync Satellite server network. A simple diagnostic test for this is to open a browser and enter the following in to the address field: https://myserver.msupply.org/sync/.
    • If the web page responds with an error message from the Primary Server, then the Primary Server is reachable: Primary server sync error message
    • If the web page responds with a firewall or proxy error message, then the firewall / proxy server needs to be configured to allow access from the Primary secondary server to https://myserver.msupply.org/sync/:



Previous: 25.19. The system log | | Next: 25.21. Help menu

25.16. Show connected users

Note: Not applicable when running mSupply in single user mode

To display a list of users currently logged on to mSupply, select Special > Show connected users (Ctrl + Shift + U). The window below is displayed.

Messaging other users

By highlighting one or more users (use control on Windows/ command on Mac to highlight multiple users), a message typed into the Message box will immediately appear on the selected user(s) mSupply window when you click on the Send button.

Such messages are not stored on the system.



Previous: 25.15. Managing users | | Next: 25.17. License management

25.22. Field descriptions



For descriptions of individual mSupply fields please refer to section 24. Data Tables and Fields

Previous: 25.21. Help menu | | Next: 26. Other Topics

25.19. The system log

The log contains records of who did what and when in the system. It's a useful place to look to find out what happened to certain records and when certain things were done. Some events (lots!) are always logged by mSupply but some are optional and are chosen in the Log tab of the General preferences page.

To view the log, choose View log… from the Special menu. You will be shown all today's log entries when the window loads:

The columns contain this information:

  • Date: the date when the log entry was made.
  • Time: the time the log entry was made.
  • User: the name of the user who did the operation giving rise to the log entry.
  • Type: the type of log entry. Can be used for filtering or just telling you which part of the system generated the log entry.
  • Event: a description of the event that occurred.
  • Source table: the name of the table that contains the affected record (if there is one).
  • Record ID: if there was one, the ID of the record in the database that was affected by the event.
  • Extra information: detailed information about what happened in the event in JSON format. Not always provided.
  • Store name: the name of the store that the event occurred in.

Buttons in the window:

  • Export Export the log to a tab delimited text file. You can then import this into other applications (such as a spreadsheet application) for editing and printing.
  • Print Prints the displayed list of log entries on your printer.
  • Order by Sort the log by something than the default date/time order.
  • Find Search for particular records in the log.
  • OK Close the window.

Double-clicking a log entry in the list will bring up a read-only window showing the full log details:

  • Date: The date the log entry was created
  • Time: The time the log entry was created
  • User: The name of the user whoi did the action that resulted in the log entry
  • Log ID: The ID of thelog entry in the database
  • Record ID: The ID of the record the log entry relates to e.g. the transaction that was edited
  • Copy ID to Clipboard button: On click, copies the Record ID value to the Clipboard so you can poaste it somewhere else
  • Event type: The type of the event that occurred. Used for filtering
  • Event: Description of the event that occurred
  • View Data button: On click, if the log entry has additional JSON information, it is displayed in the large panel below the button.
Dates

If you want to see log records that were generated over a different period then manually edit the dates in the From and To boxes as required or choose one of the many quick-select options in the drop down list to automatically set them (Today is selected by default):

log_ddl_1.jpg

Event types

Additionally, you can choose to show only certain types of event which occurred in the period you have selected. To do that, select one of the entries in the final drop down list on the right hand side (All is selected by default):

log_ddl_2.jpg

Custom query

If you are looking for log records that are not in the list of common event types described above, you will need to create a custom query. For example, to find a report of all the finalized POs this year:

  1. Set the date / time period
  2. Click on Find
  3. Click on the small right arrow to the right of the first field box
  4. Select the data type that you are looking for. In this case, we are looking for the event_type
  5. Type in the particular event type that we are looking for. In this case, we are looking for the finalized_po
  6. Click on Query
  7. Once you are happy with the included results, click on Print (or Export to produce a text file that can be imported to Excel and manipulated)



Previous: 25.18. Label printer hardware setup | | Next: 25.20. Server troubleshooting

25.21. Help menu

Help > About mSupply

Choosing this item displays information about your mSupply installation.

Authorisation

The Authorisation button is provided largely for our support team to assist with resolving any issues. You can safely ignore it.

Show table records

Clicking this button will result in a list of the number of records in each of the data 'tables' in your mSupply system. This is only generally of technical interest. You can safely ignore it.

On a large mSupply system, it can take some time to generate this list.

Show sync records

Clicking this button will result in a list of the number of outstanding 'sync-out' records, broken down by sync site. These are records of data that have been queued up for the site, but have not yet been sent for any number of reasons (no internet connection, site device is powered down, site credentials are not correct, etc.). This list is not dynamic, in that you will not see the numbers count down as the records are synced out. The numbers are generated each time the button is clicked, and remain static.

The existence of a significant number of sync out records indicates that the site has not synced with the central server for some time. If the site has been in normal operation during this time, then there will also likely be a significant number of records waiting to be synced back from the site. In these cases, once a sync connection is reestablished, it could take hours for all the sync records to be transferred.

Updating mSupply

For single user versions of mSupply, you can see if you have the latest version by choosing Special > Check for updates

Choosing this item from the Special menu will connect to the mSupply web site and compare your current mSupply version with the version you are now using.

If an update is available, you will be shown a window where you can click to download the latest version.



Previous: 25.20. Server troubleshooting | | Next: 25.22. Field descriptions

25.08. Changing users and passwords

Changing the current user

From the menus choose File > Change User… (Keyboard shortcut Ctrl+1)

This logs out the current user and re-opens the login window so that the new user can login, without having to close and reopen mSupply:

If more than one user is sharing your computer, choose this item before you leave the computer so that the next user will have to log in with their user name & password before gaining access.

If you find yourself on this page accidentally and if you do not have sufficient permissions to change to another store or user then you will have to close and restart mSupply by clicking Quit or the red X at the top right of the screen and launching the program again.

Switching stores

From the menus choose File > Switch… (Shortcut Ctrl+2)

This menu item lets a user (whose permissions allow) switch stores without the need to re-enter their password. Note that this screen does not allow a change of user; clicking on the Cancel button reverts to the current store, so caution in using this feature should be exercised, and this screen should not be displayed when the computer is left unattended (the user is not logged out).

Change password or language

From the menus choose File > Change Password or language….

This allows you to change your password or the language of the interface and will show you this window:

To change your password
  1. In Enter old password enter your current password.
  2. In Enter new password enter your new password. Make it long enough (at least 6 characters) and not easily guessed by people who know you.
  3. In Enter new password again enter your new password again to make sure you have typed it correctly.
  • Passwords are case sensitive; make sure you don't have Caps Lock on.
  • If you forget your password you must ask another user who has permission to Edit users to change your password for you - see Changing the current user for details.
To change your language

You can also change the language used in the mSupply interface on this screen - simply choose the language you wish mSupply to use for you from the Language drop down list.

You do not need to change your password at the same time!

If you change your language, mSupply will prompt you to switch stores (see above - you can switch to the same store you are currently logged in to) to see the change of language.

Edit other users

See the 25.15. Managing users page for details on this.



Previous: 25.07. Updating mSupply | | Next: 25.09. Diagnostics

25.05. Web browser access via TSPlus

Accessing mSupply

If TSPlus has been set up on your mSupply Server, then client sessions can connect to it using a web browser.

Open a web browser, then:

  1. Enter the name or IP address of the server in the URL / search bar. It should start with https:…. but in exceptional circumstances, may start with http:
  2. Remember to append the IP address the correct port number if you have been given one. You may not need to enter it, and it might not be 2048 in your instance.

Login by:

  1. Type in the TSPlus Web credentials Username (normally the same as the Windows account Username)
  2. Type in the TSPlus Web credentials Password (normally the same as the Windows account Password)
  3. Click Log on

Once the browser has successfully connected to the server and logged you in, mSupply and a small selection of applications should be available on a floating panel on the left side of the browser window.

There are two tips to give you more space:

  • Make sure your web browser window is full screen (F11). Toggle out of full screen mode by pressing F11 again.
  • Maximise the mSupply window once it opens.

Transferring files from the server to the local machine

You will often want to transfer files, and particularly reports, to your local machine. By default, your mSupply session on the server will save files to your Windows account's Documents folder. To transfer files from there to your local machine's Downloads folder:

  1. Click on the small 'down arrow' symbol at the top centre of the web page
  2. Click on the 'file download' symbol on the panel that then appears

  1. Select the file to download
  2. Click Open

  1. If it isn't already selected, select the Save File radio button
  2. Click OK

Transferring files from the local machine to the server

After clicking on the TSPlus File upload icon

  1. Select the file to upload
  2. Click Open. This should transfer the file to your Desktop on the Server

Increasing screen area

Sometimes, depending on a number of factors, but particularly the screen resolution of your local PC, you will find that the screen area is too cramped to use mSupply properly - see here:

Cramped working area

This can be improved by

  • Maximising the size of the mSupply window within the browser window

  • Making the browser session 'Full screen':

You can reverse this by repeating this process.



Previous: 25.04. Schedules and periods | | Next: 25.06. Backup

26.04. Budgets

To show the budgets window, choose Special > Show budgets

Two kinds of budgets

mSupply supports two different types of budgets.

  • The budget module described here allows you to track spending and/or sales of items against your targets, which are entered as budgets. Items are grouped together by their account code.
  • The customer budget module allows you assign a budget for each supply point (customer), and both report on how much they have been supplied, and limit supply of that item. Information on the customer budget module is available here.
Activating the budget module

To use this feature, you must check Activate budget module on the Invoices 1 tab of the mSupply Preferences window: But please note, before you do this you must enter a budget period - see the Adding a budget section below.

Overview

Firstly, you define budget periods which can be any length you choose - months, quarters, years or whatever.

Once budget periods are set up, you must allocate each transaction that issues stock (customer invoice, inventory adjustment - reduce stock or supplier credit) to a budget period (see the Including transactions in your budget section below for details). The items on that transaction will have been assigned accounts (See here for how to add item account codes, and you can then view budget reports based on expenditure or sales broken down by the accounts you have assigned to items.

At the end of a budget period, that budget period may be locked so that no further entries may be made.

To use the budget feature, these are the steps to be taken:

Viewing budget details

Choosing Special > Show budgets presents you with the Budget period list window as shown (note that the latest entry appears at the top of the list and the oldest entry at the bottom):

Adding a budget

Click on the New button in the Budget period list window to add a new budget. This window is displayed:

In the Description field, enter the name of the budget period - for example FY 2008.

The Start date is non enterable; the first time you use this feature, the field is set to 00/00/00, on subsequent occasions the it will show the date one day later than the End date entered on the previous occasion.

You should enter the End date, the date the budget period ends.

In the Account Description column, a list of account names and code(s) will be displayed. To set budget figures for these accounts, select the Account to which the budget applies by clicking on the line. Once selected, click on the figure in the Budget column of that line, and enter the budget figure.

Deleting a budget

Select a budget from the list in the budget list window shown above and click on the Delete button to delete a budget. You will be asked to confirm the deletion. Note, you can only delete budgets in order, starting from the most recent and you cannot delete a budget that has been used in any transactions (customer invoices) or has accounts with a budget amount of more than zero.

Editing budgets

Should you wish to edit a figure allocated to an account, double click on the appropriate line on the Budget period list and this brings up the Budget edit window; Click on the Account description, End date and various budget value fields and change them as required. Note that a budget can only be deleted when all of its accounts are allocated zero budget amount.

Budget reports

To find out information like expenditure against budgeted amount for a particular budget (and a whole lot more!) then you need to open the budget first by double-clicking on it in the Budget period list mentioned above. This opens the Edit Budget period window:

The Show budget against income and Show budget against expense buttons change the table to display the selected information for each account for that budget period. The Show budgets button changes it back to show the budget account information for the period.

The Print button prints out the table which is displayed at the time it is clicked.

The Show related button will display all the purchase orders, goods received notes, customer invoices, supplier invoices, supplier payments, customer payments or inventory adjustments which are related to the budget period. You simply click the button and choose which you want to see.

Including transactions in your budget

When the budget module is activated, a new Period field appears at the top of transactions that issue stock. Here it is on a customer invoice:

It is set to “Unconfirmed or none” by default and you must select a period before the invoice can be saved or closed. If you don't, mSupply will give you a warning message when you click on the OK or OK & Next buttons.

Note: you don't have to select a period if you're viewing or editing a customer invoice (or other stock issuing transaction) that was created or confirmed before the first budget period starts.

Once the transaction has been saved with a budget period, when it is confirmed the goods on it will automatically be accounted for in your budget and will affect any budget reports you run.



Previous: 26.03. Transaction Status & Type Codes | | Next: 26.05. Edit menu

26.08. Bulk Store Preferences Editor

The Bulk Store Preferences Editor allows changing preferences and other properties for many (or all) stores at once. This will be particularly useful in any system where you have many stores in a single datafile.

For a user to be able ot use this function, they must have the Edit store details permission turned on (see the Managing users section for details).

Open the editor by choosing the Special > Bulk edit store preferences… menu item. This window will open:

The editor allows editing of basic Preferences, Custom Data (Not yet implemented but coming soon!) and Tags (Not yet implemented but coming soon!). Preferences are selected by default when the window opens but click one of the others in the top panel if you want to work with another type of store setting:

The Preferences table in the left hand panel shows all the available settings of the type specified above. The Stores list in the right hand panel shows all the stores in your datafile that you can edit the settings for (normal stores, dispensaries and report type stores).

When you select a Preference, the Stores list shows the current settings for each of the stores in the Current column - this column is read only and can't be changed.

To change a selected preference, click on the checkbox in the New column to switch the preference on or off.

You can apply a setting to all displayed stores with the All/None checkbox on the far right panel. If you want to undo what the All/None button did then click on the Reset button.

Once you're done making changes for this preference, click the Save Changes button to write your preference settings to the database. The Current column will be updated with the new settings to reflect the saved changes.

Please note: You must save changes before switching to another setting, or your changes will be lost. mSupply won't stop you moving to another preference before saving changes but it will tell you if you lose unsaved changes.

Filtering stores

If you only wish to make changes to a subset of stores, you can filter the Stores list with the Filter stores bar in the top panel:

When you click the text entry field, you will be presented with a simple query editor:

Submitting this query will update the list of Stores to match the query you created. Restore the full list of Stores with the Reset Filter button.

Previous: 26.07. Virtual stores | | Next: 26.09. Custom data

26.10. Currencies

Choosing Currencies from the Special menu opens a window with a list of currently entered currencies. The home (default) currency always has a rate of 1, and the entry in the rate column of additional currencies is the number of units of the default currency equivalent to 1 unit of the other currency. In the screenshot below, the home currency is the Australian dollar (AUD) and the Rate of the Euro is 1.3317, so, at the time of writing, 1.3317 Australian dollars (the default currency) was equivalent to 1 Euro, 0.7485 Australian dollars was equivalent to 1 New Zealand dollar, etc.

Buttons in the Currency list window

New: To add a new currency (you can select from the ISO4217 list of currencies).

Get internet rates: Providing you have an internet connection, clicking this button will update the rate of exchange from the Yahoo website.

Update mSupply rate: The refreshed rates will only become active when you click this button.

OK: Click OK to close the Currencies window when you have finished editing currencies.

Editing a currency entry

Double click a currency to edit it manually. Note that your “home” currency should be entered with a value of “1”, and all other currencies should be entered with a rate relative to your home currency. A window with the currency code and the current rate will appear.

You can edit the rate. Note that doing so will automatically update quotes that use that currency.

To change your default currency
  1. Double-click on your default currency in the list
  2. Click the padlock icon
  3. Choose a different home currency.

Note that all other currencies will have to have their rate entered relative to the new default currency

Buttons in the Edit currency window

Delete: Click to delete the currency. If the field is dimmed, the currency is in use by quotations, and cannot be deleted.

Cancel: Click to exit the window without saving changes.

OK: Click this button when you are finished editing currencies.

Using Foreign currencies in transactions

We discuss this very important topic right here

Previous: 26.09. Custom data | | Next: 26.11. Using foreign currencies in transactions

26.09. Custom data

Custom data allows you to add data to mSupply that doesn't naturally fit into one of the existing fields.

  • Choose Special > Show custom data… to show the list of custom data sets.

Setup fields
  • Click New
  • This window is shown:

  • For our example, we're going to record population in several regions each year, so we need
    • A real number field to store the population number
    • A text field to store the region name
    • A date field to store the year
  • We've labelled the data set RegionalPopulations
  • To change the field names, click once on the name, and then wait a second or two and click again- now it is editable:

Adding data
  • Click the data tab then click New

Using data in reports
  • You can extract data by using the following method in a pagepro report
  • custom_value_get(“data_set”;“field_to_query”;“search_value”;“field_to_return”;→“variable_to_return”)
    • “data_set” is the name of the data set. e.g. "RegionalPopulations"
    • field_to_query is the internal name of the field “text_1” , “Text_2”, “real_2”, “date_7”
    • “search_value” is the value you're looking for in “field_to_query”
    • “field_to_return” is the field name of the value to return
    • “variable_to_return” is a pointer to the variable that will contain the data returned.
  • Sound too complicated? We usually build these reports for clients, but this documentation is for the technically minded who want to build their own.



Previous: 26.08. Bulk Store Preferences Editor | | Next: 26.10. Currencies

26.20. Document registry

The document registry is for storing settings for various forms that are used in Open mSupply.

View the current stored documents

To see a list of the currently stored documents, choose Special>Show document registry… from the menus. This window will open:

This shows a list of all the documents currently stored. If the list is long and you want to find a particular document then type something in the Type here to search field and the list will show only those documents with what you typed in their Document type.

The number in the bottom left of the window is in the format x/y where x is the number of documents displayed in the table and y is how many documents are stored altogether (i.e. displayed when nothing is entered in the Type here to search field.

Deleting a document

Select a document in the list by clicking on it and click on the Delete button. After confirmation the document will be deleted and will no longer be available for use.

Adding a document

Click on the New button and this window will open:

  • Document type: This is a free text field. Enter something meaningful so you will know later what this document is for.
  • Category: When you click on this field you will be shown another window with a selection of categories to choose from like this:

Highlight one by clicking on it and click the OK button to select it.

  • Context: This field may be filled in for you automatically and become read only when you select the Category (meaning this categroy does not need ny further context information or clicking on this field will open another window to allow you to select the master list which is the context for the form like this:

Highlight one in the list by clicking on it and click on the OK button to select it.

  • Name: This is a free text field. Enter the name of the form as it will appear in Open mSupply.
  • Data schema: Click on the Upload button to select the JSON schema file that defines the contents of the form.
  • UI schema: Click on the Upload button to select the JSON file that defines the appearance of the form.
  • Config: Click on the Upload button to select the JSON file that defines the confguration of the form.
  • Data field: When you click on one of the 3 file fields, this field will show the contents of the files for checking.

Click on the OK button to save your changes or the Cancel button to discard them.

Editing a document

Double-click on the document you want to edit in the table and the same window for adding a new document will open but populated with the selected document's details. Edit any of the details as required then click on the OK button to save your changes. Click on the Cancel button to discard your changes.



Previous: 26.19. Migrating to Open mSupply | | Next: 27. Help

26.05. Edit menu

The commands in the Edit Menu can be used when you are entering text, just the same as in a word processor.

Undo: The previous contents can be retrieved if the document has not been saved.

Cut: Deletes the currently selected text and places it on the clipboard

Copy: Copies the currently selected text and places it on the clipboard

Paste: Replaces the selected text (if there is any) with the contents of the clipboard. If there is no selected text, the clipboard contents are inserted at the insertion point (the blinking cursor)

Clear: Clears the text in the particular field.

If the Cut/Copy/Paste items are dimmed out, it is because you are not currently in a text entry field.



Previous: 26.04. Budgets | | Next: 26.06. Transaction categories

26.11. Using foreign currencies in transactions

The foreign currency feature enables you to receive stock from suppliers in the suppliers own foreign currency and also distribute goods to customers in their own currency.

Set up foreign currencies for customers and/or suppliers

You must have Foreign Currencies configured in mSupply if you are using this feature. You set them up using Currencies. Once this is done, follow the steps below.

Set the Store to use foreign currency

- From the Navigator click drop down menu Special> Show Stores… double click to select the store in which you want foreign currencies to be used and in the window that appears hit tab Preferences. - Check Store mode: Able to issue in foreign currency. - Click OK and return to the mSupply Navigator.

Set the currency of the Customer or Supplier

- From the Navigator choose Customers > Show Customers. - Locate the Customer and double-click it. In the window that appears click the General tab and in Currency drop-down list (top-right) select the appropriate currency for that Customer. - Click OK to return to the Navigator and do the same for the Supplier if required.

Using foreign currencies

Purchase orders

Instructions in these section to be update

Supplier invoices

In this example, our store operates with Australian dollars (AUD) as the local currency, and is making a purchase from a European supplier which uses the Euro (EUR)

  1. From the Navigator choose Suppliers > New Supplier Invoice
  2. In the Supplier Invoice window that appears select your supplier and view its details by double-clicking.
  3. Click the Price tab and change the currency (as highlighted in box 1 below) to the currency in which the supplier provides the items to you.
  4. Return to the General tab and click button New line to add a new item line.
  5. In the window that appears type the details of the item you are receiving and hit button OK & Next to add further items.
  6. Once all items are added, again click the Price tab and review the item prices as highlighted in box 2 below:

    The columns headed Price FC and Extension FC in box 2 above show the cost price of goods to you in Euros - i.e. the Foreign currency which the supplier uses, while the figures in the columns on the right show the prices in Australian dollars - i.e. your local currency.

  7. Click OK to save the Supplier invoice and introduce the items to stock.
  • If you change the supplier on an invoice that has item lines, the following message will appear. Check the currency is correct for the new customer and adjust it if necessary.
Customer invoices

In our example, the supplier uses Australian dollars (AUD), and is creating an invoice for Highland Health Centre which uses Solomon Islands dollars (SBD).

  1. Ensure Foreign Currencies are active as per the instructions at the top of this page.
  2. From the Navigator choose Customers > New Customer Invoice.
  3. In the Customer Invoice window that appears select your Customer in field Name and note the currently set currency and its rate as highlighted in box 1 below.
  4. Now click the New Line button to add a new item line.
  5. In the window that appears type the details of the item you are issuing and hit the OK button. Repeat as needed.
    • Box 1 shows the customer's currency, SBD, the Currency Rate, which shows the value of 1 Solomon Island dollar in the supplier's currency, Australian dollars, and the invoice value in the customer's currency.
    • Observe the item's foreign currency values (SBD) in the columns Price fc and Price fc ext on the Customer Invoice in box 2 below:
  6. Click OK to save the Customer invoice.
  • If you change the customer on an invoice that has item lines, the following message will appear. Check the currency is correct for the new customer and adjust it if necessary.
Supplier credit

In our example, the supplier, International Dispensary, uses Euros (EUR), while we use Australian dollars (AUD).

  1. Ensure Foreign currencies are active as per the instructions at the top of this page.
  2. From the Navigator click drop down menu Supplier> New Supplier Credit.
  3. In the Supplier Credit window that appears select your Supplier in field Name and note the currently set currency and its rate as highlighted in box 1 below.
  4. Now click button New Line to add a new item line.
  5. In the window that appears type the details of the item you are receiving and hit OK. Repeat as needed.
  6. As this is a credit note, the value is shown as a negative amount
  7. Box 1 shows the supplier's currency, EUR, the Currency Rate, which shows the value of 1 Euro in our currency, Australian dollars, and the credit note value in the supplier's currency.
  8. Note the item's foreign currency values (SBD) in the columns Price fc and Price fc ext on the Supplier Credit in box 2 below:
  9. Click OK to save the Supplier credit.
  • If you change the supplier on an invoice that has item lines, the following message will appear. Check the currency is correct for the new customer and adjust it if necessary.
Customer credit

In our example, the supplier uses Australian dollars (AUD), and is creating a credit note for Highland Health Centre which uses Solomon Islands dollars (SBD).

  1. Ensure Foreign currencies are active as per the instructions at the top of this page.
  2. From the Navigator click drop down menu Customer> New credit…
  3. In the Customer Credit window that appears select your Customer in field Name and note the currently set currency and its rate as highlighted in box 1 below.
  4. Now click button New Line to add a new item line.
  5. In the window that appears type the details of the item you are crediting and hit button OK.
  6. Boxes 1 and 2 show details exactly the same as explained in the previous two examples
  7. Click OK to save the Customer credit.
  • If you change the customer on an invoice that has item lines, the following message will appear. Check the currency is correct for the new customer and adjust it if necessary.



Previous: 26.10. Currencies | | Next: 26.12. Product (drug) registration

26.14. Authorisation

Sometimes it is important that certain critical processes are not carried out until they have been authorised. mSupply allows authorisation to be set according to local needs for:

Response Requisitions can be authorised using the remote authurisation app. See the 26.15. Remote authorisation page for details about that.

Configuring mSupply for authorisation

Turning on authorisation

Authorisation must be set up for each store independently. For each store, you can decide which transaction types require authorisation.

To do this, choose Special > Show stores from the menus, double-click on the store you are logged into and click on the Preferences tab. Now turn on the authorisation preferences for the transactions you want to be authorised. See the 26.08. Virtual stores page for details on which preferences do what. lick the Special tab, then click Stores.

Setting up authorisers

Certain users must be designated as authorisers for each store by giving them permissions to authorise different transaction types.

To do this, File > Edit users from the menus and double-click on the user (or change the Show drop down list to Group and double-click on the group of users) you want to designate as an authoriser and give them the Authorise purchase orders, Authorise goods received, Authorise customer invoices or Authorise supplier invoices permissions in the appropriate stores.

See the 25.15. Managing users page for details on where to find these permissions.

Supplier invoice authorisation

When the Supplier invoices must be authorised store preference is set, new supplier invoices will show an Authorised checkbox:

An authoriser must check the Authorised checkbox before the supplier invoice can be confirmed (it will be disabled for users who do not have the Authorise supplier invoices permission).

If the OK button is clicked while the Authorised box is unchecked, a warning message will appear telling you that unauthorised invoices cannot be confirmed and nothing will happen.

If you have permission to authorise a supplier invoice, you can also unauthorise it:

  • If the invoice has a new (nw) status then it has not been entered into stock. If you unauthorise it, users can edit it and and you will still control the process of authorisation before the goods are entered into stock.
  • If the invoice is confirmed (cn), the goods have already been entered into stock. If you unauthorise it, users will be able to edit it again and any changes users make will affect stock levels immediately. It is good practice, therefore, to only unauthorise a confirmed invoice to make changes immediately and the reauthorise it straightaway.

When supplier invoices have to be authorised, they cannot be confirmed until they are authorised. Until then:

  • Unauthorised invoices are held at suggested (sg) status.
  • The official invoice cannot be printed.
  • Goods are not received into stock.

Customer invoice authorisation

When the Customer invoices must be authorised store preference is set, new customer invoices will show an Authorised checkbox:

An authoriser must check the Authorised checkbox before the customer invoice can be confirmed. The Authorised checkbox will be disabled for users without permission to authorise.

If the OK button is clicked while the Authorised checkbox is unchecked, a warning message will appear stating that unauthorised invoices cannot be confirmed and nothing will happen.

When customer invoices have to be authorised, they cannot be confirmed until they are authorised. Until then:

  • Unauthorised invoices are held at suggested (sg) status.
  • The official invoice cannot be printed.
  • Goods are not removed from stock.

Goods receipt authorisation

When the Goods received lines must be authorised store preference is set, a new Authorised column will be displayed and will contain a checkbox for each goods receipt line. It looks like this:

Users who have the Authorise goods received permission turned on can check the Authorised checkbox for each line that is authorised. When the goods received note is finalised, only lines that are authorised will be added to the supplier invoice to be received into stock. The unauthorised lines will remain on the finalised goods received note as a permanent record of what was actually received but not authorised.

Any unauthorised goods received note lines do not count towards stock received against purchase orders or on goods received notes so they can be received again at a later date if they are resent by your supplier.

Users who have the Authorise goods received permission turned on may also leave a comment in the Authorisation comment field to record anything that needs to be noted.

Invoices can be edited after authorisation but goods receipt lines cannot be unauthorised to fix mistakes! Any authorising errors can only be fixed using stock adjustments.

Purchase order authorisation

When the Purchase orders must be authorised store preference is set, new purchase orders will show an Authorised checkbox:

  • An unauthorised purchase order can still be confirmed and have goods receipted against it so it is not as restrictive as authorisation on customer or supplier invoices.
  • However, an unauthorised purchase order will print with an Unauthorised watermark across it. An authorised purchase order will print without the watermark.

Monitoring authorisations

Printing unauthorised invoices

When an invoice is not authorised, it will print with a clear Unauthorised watermark. Authorised invoices will print without the watermark.

Viewing authorisation logs

mSupply records the authorisation and unauthorisation of invoices and creates a record every time the authorisation status of an invoice changes.

To view the records, click the Log tab of an invoice.

Advanced users can also view all logs by going to Special > View log...



Previous: 26.13. Using the mSupply remote client | | Next: 26.15. Remote authorisation

26.17. Keyboard shortcuts

These are the keyboard shortcuts you can use in mSupply. They can really speed up your work because using them is much quicker than using a mouse once you get used to them. Try it and see!

The Windows operating system uses the Control key and the Mac operating system uses the Command key to activate keyboard shortcuts. For clarity's sake we've used the control key in the table below. If you're using a Mac just substitute Command for Control.

Shortcut What it does
General useful computer shortcuts / Navigation keys - work in most applications
Ctrl + A Select All text in a field / cell
Control + X Cut
Control + C Copy
Control + V Paste
Control + Z Undo
Control + Shift + Z Redo
Control + Q Quit the application
Tab moves focus to next field / cell. Also used after typing in a selection textbox (e.g. item name) to bring up a window showing selections which match what was typed. But this isn't technically a shortcut, just the way the fields work!
Shift Tab moves focus to previous field / cell
Spacebar toggles between two options (with a checkbox or radio button), e.g. Male / Female in Patient details entry window
Almost Everywhere in mSupply
Enter Activates the default button (which is highlighted) on the active window. Default button is usually OK.
Control + . (full stop) Cancel/Delete
Control + Shift + N OK & Next
Control + Shift + P OK & Previous
Navigator
Control + F Show customer invoices
Control + I Show items
Control + N New customer invoice
Control + R Show prescriptions
Control + D New prescription
Control + J Show supplier invoices
Control + H New supplier invoice
Control + 1 Show log in window
Control + 2 Show switch stores window (same as log-in but no need to enter user/pass)
Control + 0 (zero) Show purchase orders
Control + Y Show customers
Control + U Show suppliers
Invoice entry
Control + N Add a new line to the invoice
Control + Shift + N OK & Next to save, print (if printing checked) and open a new prescription entry window
Invoice line entry
Control + K Same as clicking OK (Enter key is the default OK & Next button)
Stocktake list
Control + N Add a new stocktake
Control + Shift + N Add a new blank stocktake
Stocktake entry
Control + N Add a new line to the stocktake



Previous: 26.16. Misc labels | | Next: 26.18. Troubleshooting

26.19. Migrating to Open mSupply

We will be adding information on what's involved in migrating from existing mSupply to Open mSupply as time goes on.

Things to note

  • All nw or sg status repacks in mSupply will be deleted and the reserved stock made available for distribution again when a store is migrated to Open mSupply.



Previous: 26.18. Troubleshooting | | Next: 26.20. Document registry

26.16. Misc labels

This function allows you to create and save labels that you can print at any time from a label printer. Before you can print labels using this function, you must setup the printer must be set up and configured in mSupply - see the 25.18. Label printer hardware setup and 10.08. Label printing preferences sections of this user guide for information about this.

The labels list

To open this list, choose the Special > Misc labels menu item. This window will open displaying a list of all the currently saved labels:

Double-click a label in the list to edit/print that label. If there is a long list and it is hard to find the one you want, you can type something in the Search labels field and the list will be restricted to labels that have a description that contains what you have typed.

Click the New button to add a new label.

The window for editing or adding a label look the same, the only difference is that the existing label will be populated with the current settings saved for that label.

The labels are designed to print to plain 90mm x 40mm (w x h) labels from a Zebra label printer. Please contact us if you require support of other printers and other label formats.

Normal tab

This is for normal layout of printing. This will occur once per label. You can use the quantity to print field to specify how many time to print this same label.

Label name
This field will not print on the label, this name is shown in the list of available labels when the Special > Misc labels menu item is chosen.

Label details
These fields will print on the label in roughly the position that they are on the screen.
Note that if you enter a very long left and right footer they may overlap in the middle of the label.
Print a single test label to check first.

Line spacing
The spacing you want between each line of text.

Size
The font size you wish to use for each part of the label.

Quantity to print
Specify how many copies of this label you wish to print.
Note that the quantity to print is not saved - it is reset to 1 each time you open the label.

Print button
Clicking this button will print to your default mSupply label printer. It will print then number of labels specified in the Quantity to print field.

Cancel button
Clicking Cancel will close the window without saving any changes you have made.

OK Button
Clicking OK will save any changes you have made and close the window.


Multiple tab

This allows you to print the same thing multiple times on the same label.

Layout:
Select “2” for the same thing printed twice on the label, side by side.
Select “4” for the same thing to be printed 4 times on the label in a 2×2 grid layout.

Body
The text you want printed on the label. This label will have no headers and footers.
















Previous: 26.15. Remote authorisation | | Next: 26.17. Keyboard shortcuts

26.01. Miscellaneous topics

This page is a collection of miscellaneous topics that may be useful but don't easily sit anywhere else in our online documentation. They are included here so that they can be found when you search this wiki for the relevant key words.

Inactive logout

You can set mSupply to log an inactive client out after a customisable length of time. See the 15.01. General preferences page for details.

End of month tasks

We are presuming that you will finalise and export your invoice data once a month. If you choose a different frequency, you should still follow the same procedure.

Tasks to perform:

  • Check your invoices are correct. Once you have finalised an invoice, it can not be edited.
  • Finalize and export supplier invoices. See the file menu chapter.
  • Finalize and export customer invoices. See the file menu chapter.
  • Record the stock on hand value (this is only necessary if your accounting system requires the information). See the special menu chapter.

Hints:

  • Each month, take your finalised invoices and file them. We suggest you file invoices in order of their invoice number (a separate file for supplier and customer invoices).
  • Keep a file with the summary printout from each month produced when you finalize invoices.

End of year tasks

It is usual to run according to a financial year. mSupply does not require you to delete records or perform special operations for the end of the financial year. If you want to, you can just carry on using mSupply as usual.

However, there are certain procedures that will improve operation, and make an audit of your operation easier.

  1. Perform a stocktake.
    1. Finalize all outstanding invoices. Use the Finalize Customer invoices … and Finalize Supplier invoices… commands to do this. (Note that any customer invoices with a status of “sg” (“suggested”) must be confirmed before they can be finalised or exported.)
    2. Create stocktake sheets to record differences easily between actual stock and stock according to mSupply. See the stocktake sheets section of the “Report menu” chapter.
    3. Use inventory adjustment transactions to correct errors. See the Inventory adjustment- add stock and the Inventory adjustment- reduce stock sections of the “Item menu” chapter.
    4. Finalize inventory adjustments. Use the Finalize inventory adjustments command to do this.
  2. Make a backup copy of mSupply as it stands at year-end. It is a good idea to keep this backup in a secure place for long term storage.
  3. Print a ledger for each item. Choose “print item ledger” from the “report” menu. You can use your backup copy of mSupply to print this ledger at a later date.
  4. Choose “set start of year stock” from the “special” menu. This simply records the date and next transaction number, and records the total opening stock quantity for each item to allow a ledger calculation for the coming year.
  5. You are now ready to begin entering transactions for the next year.

Maintenance and repair

If you are using your data file regularly, it is a good idea occasionally to check that no problems have developed. Problems can develop due, for example, to faulty hardware and other reasons outside our control.

For technically competent users or professional IT staff

In the case of a serious hardware failure, the first option should always be to revert to the last known good backup of your data.

If for some reason you must repair a damaged data file, please contact Sustainable Solutions for advice.

To check your data, download a product called 4D Tools . (4D Tools and a manual is included on the CD) from ftp://ftp.4d.com.

4D Tools can simply check your data file for errors, or repair your file. Please contact Sustainable Solutions if you believe your data file has a problem, before repairing it.

Always use 4D Tools on a backup copy of your data first.

If 4D Tools is unable to repair your data, Sustainable Solutions is able to use specialist tools to examine your data, and even export your data and re-import into a new data file. We have not had to do this for a customer yet, but the option is available as a near-last resort.

How do I move a window whose title bar has been hidden?

On Windows:

  • Method 1: Press Ctrl and both mouse buttons, and drag the window to the new location.
  • Method 2: Press Alt-Ctrl-right mouse button, while dragging the window to the new location.

On Mac OS

  • Press Control-Command-mouse button, and drag the window to the new location

Security of your data

If you maintain the mSupply password system carefully, your data is quite secure.

Note, however, that if a person has access to the original copy of mSupply, they will easily be able to open the data file, as the “user 1” password is clearly shown in the password entry screen until it is overwritten the first time you click “OK”. It is your responsibility to keep copies of your mSupply software and data in a safe place.

As of version 1.4, passwords stored in the data file are encrypted with strong (512 bit) RSA encryption, so there is little danger of someone finding your password.

Supervisor mode - all stores

mSupply was initially designed to maintain data relating to a single store in each data file, and for many users, this is how mSupply continues to be used.

Since version 2 users have been able to operate with multiple stores. Normally you will log into a particular store when starting mSupply, and only see stock and transactions relating to that store. However, users can be given the permission to login as Supervisor - All stores. In this mode, users may now access data relating to more than one store - either selectively or cumulatively.

Any user in 'Supervisor - All stores' mode will have access to all data in all stores, not just those that they are allowed to log into. So you should only really give this permission to … a suitably authorised Supervisor ;-).

Reporting

In this mode, nearly all of the report filter windows will display an additional panel to allow you to select which stores' data will be included in the report. Here is an example from the expiring items report:

All the currently active stores in your datafile appear in the Include records form these stores list. The stores to be included in the report should be selected in the normal way by clicking with the mouse; to select more than one store, hold down Ctrl (Windows) or Cmd (Mac) while clicking on the desired store(s). Ctrl/Cmd + A also works for selecting all stores.

Note also that when you search for items, the filter window has the same store selection:

The item search filters will be applied to items visible in the stores selected only. If there are a lot of stores in the datafile you can click on the Bigger List button (or Magnifier button on some windows) to select the required store(s) in a separate window.

Filtering of stores by Tags and / or Custom data

Some mSupply datafiles can contain hundreds of stores. It cna become problematic to them select the exact stores to include in a particular report. To help with this, on some reports, there is an additional magnifying glass button near the top of the store list. See this example on the Current stock report window:

When you click on the button, this window opens and it allows you to select the stores to include based on store tag and custom data values:

  • Match tags: enter the tags that a store must have to be included in the selection. You can enter multiple tags separated by commas; if there are multiple tags then a store which has any one of them will be included in the search (the store does not have to have all of them to be included). Tags are ignored if this field is left empty. See the 25.08 Virtual stores page for details on setting store tags.
  • Custom data: enter the name of the custom data values that a store must have to be included in the search in the format field name:value where field name is the custom field name and value is the value the field must have for the store to be included. You can enter multiple field name:value pairs separated by commas; any store that has any of the custom fields with that value will be included in the search (a store does not have to have all of the field name:value pairs to be included. If the Custom data field is left blank then custom data values are ignored. See the 25.08 Virtual stores page for details on setting store cusatom data fields.
  • and/or drop down list: determines whether the Tags filter results and the Custom data field searches are ANDed or ORed together i.e. whether a store must have a matching tag AND a matching custom data field to be included or whether it can have either a matching tag OR a matching custom data field to be incuded.
  • Find button: when you click this, only the stores which match the tag and custom data filters will be shown in the store list.
  • Show all: removes all filtering and show all stores in the store list.
  • X/Y Stores shown text: X is the number of stores shown in the list, Y is the total number of stores in the datafile.

When the stores list shows the list of stores you want to include in the report, click on the Select button. This will close this filter window and highlight all the stores shown in this list in the stores list on the report filter window.

Click on the Cancel button if you want to return to the report filter page without selecting any stores.

Ordering stock

In Supervisor - All stores mode you can also create Purchase Orders that will be based on data for all stores, and can specify delivery destinations for different lines within the order. See the 6.05. Multi-store Purchase Orders page for details.

Changing item codes in bulk

If you have need to change item codes in bulk, refer to Import new item codes

Changing name codes in bulk

If you have need to change name codes in bulk, refer to Import new name codes

Updating On Price List in bulk

If you have need to change the On Price List for items in bulk, refer to Update On Price List in bulk



Previous: 26. Other Topics | | Next: 26.02. Reminders

26.12. Product (drug) registration

Introduction

The process by which a governing authority controls which products can be supplied in a country is called registration. The process involves keeping a register of the products that are allowed to be supplied by particular suppliers. Each supplier must:

  • Obtain a supplier registration number and
  • Obtain a registration for each product they wish to supply. This registration will usually be per brand and dose form, will be time-bound and therefore will need renewal.

A critical part of the process is supplying documents to verify product quality. The Product (drug) registration functionality in mSupply is all about recording and tracking the status of suppliers' registrations and storing the documentation for easy retrieval.

Getting started with the Registration module

Activate the Registration module

Before using the Registration module you will need to activate it in the Drug registration tab of the General Preferences.

Making the Registration module visible

mSupply treats the Registration module like a store (see Virtual stores). A user won't be able to log in to a virtual store on the login window unless they have permission to do so (see Managing users. You will need to allow the users who are going to do the registration work to see the Registration Module 'store'.

Making things visible in the Registration module 'store'

When a new store is created, no existing items or names (suppliers, manufacturers, customers, etc.) are visible in it. This clearly needs to be fixed if you are going to register existing items, suppliers, or manufacturers!

Any items, suppliers and manufacturers created after the Registration module 'store' has been created will be automatically made visible in the Registration module 'store'.

Make existing suppliers and manufacturers visible

To make existing suppliers and manufacturers visible, you need to make them visible in the Registration module 'store' - refer Names: Using, adding and editing, the Store tab.

Make existing items visible

To make existing suppliers and manufacturers visible, you need to make them visible in the Registration module 'store' - refer Items, the Stores tab. This must be done while logged in to another store.

Using the Registration module

The Registration module has its own Navigator. If mSupply doesn't start in Registration mode when you log in you may switch to it by choosing File > Switch… and selecting Registration:

You will then be presented with the Navigator for Registration:

Show (list) registrations

To see a list of registrations click on the List button:

This will open the filter window to allow you to refine your search. The filters all work in the normal way so, if you want to list all registrations, do not enter anything in the filters:

Clicking the Find button will display a list of all the registrations that match your search criteria:

New

This will allow you to enter new registrations. See the section New Registration.

Delete

You may remove registrations by highlighting an item on this list and clicking the delete button.

Find

This allows you to refine your search without having to go back to the previous window.

View / edit registration

To view and edit the details of a registration, double click it in the list and it will bring up a window where you can view and edit the details:

New registration

To enter a new drug registration record, click on

This will open the following window where data can be entered in fields as described below:

Supplier
  • To get a list of suppliers starting with a particular letter, enter the letter and press Tab. This will let you select the supplier from a list.
  • If you enter a letter and there is only one supplier beginning with that letter it will automatically be entered into the Supplier field.
  • If the supplier is not listed you may need to create a new supplier record by clicking on the New Supplier button.
  • If you want to list all suppliers you can enter @ and click Find.
  • For more details see the New Suppler section below.
  • Once you have chosen a supplier you will be able to edit the supplier details by clicking on the Edit Supplier button.
Item name

Enter the first letter of the item, press Tab, and select the item from the list that displays.

Manufacturer

As above enter the first letter of the manufacturer, press Tab, and select from the displayed list. If the manufacturer is not displayed a new record for the manufacturer will need to be created by clicking on the New Manufacturer button.

Trade name

As trade names for drugs vary widely this is a field to fill out manually.

Currently registered

If this item has been approved for registration then tick this box. The approval date will change to today's date once the window has been closed.

Status

You can assign a drug registration a status you have previously defined in the Drug Registration status window

Documents

You may attach documents to the registration record by clicking the plus button. This will open a window to allow you to navigate to and choose a locally stored document. To view documents stored in this way simply double click the document listed below.

Logs

The log tab allows you to see a list of events such as when this item was approved.

Show (list) suppliers

See Show Suppliers

New supplier

See Names: using, adding and editing

Show / new manufacturers

The process for viewing or adding a new manufacturer is the same as the process for viewing/adding a supplier - refer to the instructions above.

Reports

Clicking on Registrations will open a report listing all of your registration records.

Registration categories

Item categories are a great way of grouping your items. This enables you, for example, to report on specific groups of products by filtering by category. This can be extremely helpful.

To create a new category click on the Cat. This will open this window:

View registrations in category
  • To view a list of registrations assigned to each category double click on the category in the list.
New
  • Click the New button to add a new category.
Delete
  • Click the Delete button to remove a category.

If there are registrations assigned to a category, then mSupply will not let you delete the category until you have removed the category from the drug registration records. mSupply will open the category so that you can see the Registration records that are assigned to this category.

Drug registration status window

In this window you can define for yourself the different states or phases of a Drug Registration (for example, In Process, Refused, Waiting for documents, etc). This means that the status of a registration can be seen at a glance.

To show, create or delete a status click on the above button in the Navigator.

Edit a status

To edit a status, double-click on it. You can change its name or identifying color. The drug registrations that have been assigned this status will be affected by the change.

Add a new status

* Click the New button to add a new status.

Delete a status

* Click the Delete button to remove a status.

If this status has been assigned to registrations, then mSupply will not let you delete the status until you have removed the status from the drug registration records. mSupply will tell you how many drug registrations have been assigned this status.



Previous: 26.11. Using foreign currencies in transactions | | Next: 26.13. Using the mSupply remote client

26.02. Reminders

Updated: version 3.1

From the Special menu, choose Reminders; this feature of mSupply allows you to create notes of tasks that users may need to be reminded about. In the Reminders window of the Preferences , you can check the box which will, if the particular user has been issued with one or more Reminders, display them whenever the user logs in.

The Reminders command shows reminders for tasks that are not yet completed.

The window defaults to reminders which are Incomplete and Assigned to me, but other options are available:

To add a new reminder, click the New reminder button.

To edit a reminder, double-click it in the list.

To delete a reminder, click on the reminder to delete, then click the Delete button.

You can sort the list by clicking on the column headers. Click a second time to sort in the opposite direction.

Filtering the list

You can change the reminders displayed according to the status and whether the reminder is for you to complete or was created by you.

To show only complete or in-complete reminders, choose from the status drop-down list.

Reminder details window

Date: The due date of the task

Assigned to: By default you create reminders for yourself, but you can also create them for other users. If you're the micro-managing type, you could put everyone else's work plans in for each day or week!

Message: The text of the reminder message. Reminders may be shown in any one of eight colours, according to the colour selected when you click on the box in the upper right corner of the New Reminder or Edit Reminder window

Completed: Check this box if the reminder is completed (but note that it won't usually show in the list once is is checked)

Repeats automatically: Once this box is checked, you will be shown options for the reminder to repeat daily, weekly or monthly.

Options for repeating reminders:

  • Start date: the first date after which the reminder will repeat. For example, if you want an event to repeat every Wednesday, you'd set this date to the first Wednesday you want the reminder to repeat on
  • Every X days/weeks/months: For example, if you want a reminder to be created every three months to do a stocktake, you'd enter 3 and choose months
  • Preview button: clicking this button shows a window with a list of dates that the reminder will recur on.

Colour: Use the Drop-down list of colours to set a reminder colour. This colour will be used to colour the reminder in the list. For example, you might want to choose Red for all tasks you intend to do today.



Previous: 26.01. Miscellaneous topics | | Next: 26.03. Transaction Status & Type Codes

26.15. Remote authorisation

Function added in version 4.01, overhauled to current form in version 5.05

mSupply has features to allow various types of transactions to be authorised within the application before they affect stock so that supervisors can make sure the transactions are correct (see the 26.14. Authorisation page for details).

Remote authorisation allows supervisors to authorise Response requisitions via a web app, so that they can participate in the authorisation process without having to login to mSupply. The process described below uses a supplier and customer store in the same mSupply installation but it can work with stores in different mSupply installations using mSupply Link.

Only response requisitions (those made in response to request requisitions, called internal orders - see the 6.04. Ordering from one store to another page for details, can be remotely authorised). Other requisition types or response requisitions made manually can not be remotely authorised.

When an authorisation request is made, authorisers receive an email containing a link to the web app. When the authoriser logs in, they are shown all pending authorisations which they can then do any of:

  • Approve
  • Edit and approve
  • Deny

Authorisation by masterlist/vertical program

In the remote authorisation module authorisers can only authorise the requisition lines which belong to items on the master list they are able to authorise for.

A masterlist can be used to represent a vertical program so this method can also be thought of as authorisation by vertical program.

Authorisers can also be set up with auto-authorisation, where transactions will automatically be authorised if the user has not approved or denied the transaction before the set auto-authorise period has elapsed.

Setup

Turn on remote authorisation
For the store receiving requisitions that must be authorised

Remote authorisation must be turned on for each store separately. This means that, in the same datafile, some stores can use it while others do not. You turn it on for a store in the store's preferences:

1. Choose Special > Show stores from the menus.

2. Double click the store to edit.

3. Click on the Preferences tab.

4. Check the Use remote authorisation for response requisitions checkbox to turn remote authorisation on for that store.

5. Click the OK button to save the changes.

For the store placing a requisition that must be authorised

1. Choose Special > Show stores from the menus.

2. Double click the store to edit.

3. Click on the Preferences tab.

4. Check the Include requisitions from this store in suppliers' remote authorisation processes checkbox to turn remote authorisation on for that store.

5. Click the OK button to save the changes.

From now on, response requisitions produced from internal orders from this store must be authorised before being confirmed.

Set up authorisers
Set up the user accounts and details

All authorisers must have an account in mSupply. See the 25.15. Managing users page for details about adding and editing users.

To allow a user to login to the remote authorisation web app as an authoriser you must check their Use web authorisation system checkbox on the General tab of their details window:

You must also enter their email address on the Details tab of their details window:

This will enable them to receive emails when a requisition is awaiting their approval.

Assign the users as authorisers

After the user accounts have been setup, you can assign them as authorisers. To do this choose Special > Show authorisers from the menus. This window will open:

The window shows a list of the users who are currently setup as authorisers in the system; if none have been set up then the list will be empty.

Delete button: Select an authoriser in the list and click the Delete button to remove the user as an authoriser. This does not remove or disable their user account or prevent the user from logging into the authorisation web app, it only removes their ability to act as an authoriser.

New button: Click on the New button to assign a user as an authoriser. This window will open:

  • Authoriser: Enter the name of the user here. Type the first few characters of their username and press the Tab key on the keyboard to select the user from a list of users with usernames that start with what you have typed.
  • Master list: Enter the name of the master list containing the items that the user can authorise. The user will only be able to authorise lines on requisitions for items that appear on the list you select here.
  • Uses auto-authorisation: If this is checked then, after the number of days set in the Auto-authorisation period (days) field, any requisition lines that are waiting for authorisation by this user will be automatically authorised.
    • Auto-authorisation period (days): The number of days after which any requisition lines waiting for authorisation by this user will be automatically authorised by the system.
  • Active: This is checked by default. If this is checked then the user's assignment is active and they can act as an authoriser. If it is not checked then the user cannot act as an authoriser. This is useful when an authoriser is to be removed as an authoriser for a period of time and then added back in again e.g. when they go away on holiday.

Click on the OK button to save the new assignment or the Cancel button to cancel it.

Editing an authoriser assignment: Double-clicking one of the users in the list will allow you to edit the assignment; the 'Add assignment' window shown above will open, populated with the current settings for the user. Edit the settings to be what you wish and click on the OK button to save your changes..

Enable emailing of authorisers

When a requisition is created that requires one or more lines to be authorised, the appropriate authorisers are emailed to tell them that a requisition requires their attention in the authorisation web app.

To set up the emailing:

  • Set up the email server in the preferences. This is done on the Email tab of File > Preferences. See the 15.01. General preferences page for details on that.
  • Tell mSupply what the URL of the remote authorisation web app is. You do that on the Server tab of File > Preferences. See the 15.01. General preferences page for details.

The email address to send the emails to is taken from that given in the Details tab of the user's details page (see the Setup the user accounts and details section above).

Using the remote authorisation system

Requesting authorisation

You do not need to request the authoristion of a requisition. When the remote authorisation system is turned on as described above, when a requisition that requires authorisation is confirmed, an authorisation request is automatically emailed to all active authorisers who are assigned to authorise a master list containing any of the items on the requisition.

The only types of requisition that can be authorised using remote authorisation are response requisitions created automatically in the supplying store in response to an internal order (internal orders are also called request requisitions). See the 6.04. Ordering from one store to another page for details on internal orders.

To action an authorisation request they have received by email, an authoriser logs into the remote authorisation web app.

The authorisation statuses of requisitions

When the remote authorisation system is turned on, the list of customer requisitions, displayed by choosing Customer > Show requisitions from the menus, has an extra Authorisation status column and some additional filter options:

If you open a response requisition when the remote authorisation system is turned on, you will see the requisition's authorisation status and two additional columns:

  • Approved quantity: the quantity that was approved by the authoriser. The authoriser can change the quantity allowed on the requisition so the approved quantity might be different from the requested or calculated quantites.
  • Authoriser comment: any comment that the authoriser added to the requisition line.

This screenshot shows where you can find them:

There is also an additinal Authorisation tab on these requisitions, which shows the authorisation history of the requisition:

This particular screenshot shows that two authorisers have been requested to authorise lines on this requisition.

The authorisation status can have a few different values:

  • None: the requisition does not need authorisation and is not subject to the remote authorisation system. This is true for all manually created response requisitions and any requisitions of other types (customer stock history, imprest or request). All requisitions with this status can be edited normally and customer invoices can be created from them as normal.
  • Pending: the requisition is awaiting authorisation of one or more of its lines. A requisition with this status cannot be edited and you cannot create customer invoices from it.
  • Authorised: all lines that were waiting for authorisation have been authorised (with or without adjustments). The comments and quantity to supply can be edited and customer invoices can be created from requisitions that are authorised.
  • Denied: the authoriser has reviewed the requisition and the lines have all been denied. Like the Pending status, a requisition with this status cannot be edited and you cannot create customer invoices from it.
Authorising using the web app

When an internal order is finalised and contains items in master lists that are assigned to users for authorisation then an email is sent to all the users who are set as authorisers for those items. The email looks like this:

The link in the email is to the web app they need to log in to action the authorisation request. The URL is in the format server:port/authorisation; for example, https://demo.msupply.org:2048/authorisation.

When they click on the link (or paste it into their browser), authorisers are shown the login page where they login using their mSupply username and password:

Once logged in, the authoriser can see all pending (and previous) authorisation requests.

Note that only requisitions with a staus of Pending are editable in the web app. Any other status means that the requisition has already been processed, either by you, another authoriser or automatically by the system if the auto-authorise period for an authoriser has passed, and it is no longer editable.

To finish the authorising session and logout, click on the Logout button. This will log the user out and return them to the login window.

To view a requisition, click on it in the list. The requisition details window will open:

This is a simplified view to make reviewing easier. To see all the details of the requisition, click on the down arrow highlighted in red and more details will be shown like this:

  1. Click on this arrow to go back to the list of requisitions.
  2. Enter any authorisation comment for the whole transaction. When saved, this comment will appear in the Comment column of the Authorisation tab on the requisition in mSupply.
  3. Click on the Enter quantity in units/packs slider to choose whether you enter the Authorised Quantity column values in units or default pack size packs. The For vaccine lines only show/enter units/doses slider only shows if a vaccine item is on the requistion for approval. The position of this slider affects all vaccine item lines on the requisition ONLY. The units/packs side of the slider will show what is selected in the Enter quantity in slider. If the slider is in the doses position then all vaccine lines will show quantities in doses in the Supplier SOH, Customer SOH, Suggested quantity, Customer AMC, Default pack size, Customer requested and Authoriser quantity columns. If it is in the units/packs position then it will show units or packs in those columns, just the same as the non-vaccine lines.
  4. Edit the quantities for each line that you are able to authorise in these cells. Note that not all lines of the requisition are displayed in this window. Only the lines that the user can authorise are shown (i.e. those that are for items that appear in the master list the user can authorise for). The quantities you enter in this column will be taken as units, packs or doses, depending on the positions of the sliders in 3.
  5. Click on this icon to view, add or edit the line authorisation comment. When you click on it, this window will open: If there is a comment for the line already, it will be populated for you. You can edit the comment (or add one) and click on the Save comment button to save your changes. Click on the Cancel button to close this small window without saving any changes. Any comment that is saved here will appear in the Authoriser comment column on the requisition details window in mSupply.
  6. Click on this button to deny approval of all the requisition lines shown. This will deny the whole requisition and will mean that it cannot be processed in mSupply. This and the Approve with changes button will be disabled when the changes have been saved.
  7. Click on this button to quickly set all the Authoriser quantity column values to what was requested i.e. the Customer Requested column values. A handy shortcut to speed up the authorisation process if all or most of the lines are to be approved with what was requested.
  8. Click on this button to approve all the requisition lines shown. This will save any changes you have made to the approved quantities. This and the Deny button will be disabled when the changes have been saved.

If a requisition is open in mSupply, it is locked and changes cannot be saved. If you click on the Approve with changes or Deny buttons and the buttons do not become disabled then the changes were NOT saved. You will need to wait until the requisitions have been closed in mSupply before you can save your changes.

When a requisition has been approved or denied by an authoriser, its details and authorisation status will be updated in mSupply. If all the lines awaiting authorisation have been authorised then the requisitions's status will be updated to Authorised and the requisition will be able to be processed as normal.

Previous: 26.14. Authorisation | | Next: 26.16. Misc labels

26.18. Troubleshooting

Entering dates

Expiry dates

Sometimes users will have issues with previewing PDFs before they print. Our experience is that this is often due to some incompatibility between mSupply and certain XPS viewers. We recommend use of the excellent, free Sumatra PDF reader to view XPS files, which is one of the reasons why we include it as a recommended install with mSupply Client software! Installing Sumatra PDF and making it the default XPF viewer will normally fix any print preview issue.

Using Sumatra as XPS Viewer
How to set Sumatra as default XPS viewer on Windows
  1. Open Settings > Apps > Default apps.
  2. Click the Choose default apps by file type link.
  3. Scroll down to find .xps (XPS File), and click the button on the right side to select a different program as default.
  4. Select 'Sumatra PDF' from the list to set it and click the option 'Switch anyway'.
Change the default XPS viewer on Windows

You might also need to do the following.

  1. Follow the menu path Start > Devices and Printers
  2. Right click on the Microsoft XPS Document Writer
  3. Select Printing Preferences
  4. On the tab XPS Documents uncheck the checkbox that says: Automatically open XPS document using the XPS viewer

Prescription printing error

You may encounter Error when executing the method “print_label_multiple_lines” at line number 83

This has been known to occur when the margin settings for the label printer are incorrectly set. Try adjusting the print margins in Label printing preferences.



Previous: 26.17. Keyboard shortcuts | | Next: 26.19. Migrating to Open mSupply

26.06. Transaction categories

Categorising transactions allows you to group transactions together when reviewing or reporting them. Each type of transaction can have its own list of categories. For example customer invoices might have a category “normal” and “urgent”. Inventory adjustements might have categories “expired”, “damaged”, “stocktake”, “annual stockatake” or “monthly stocktake” etc.

From the Special menu, choose Transaction categories… to see this window:

First of all, select the transaction type the categories you create will belong to in the Transaction type drop down list. Customer (which refers to customer invoices) is selected by default so the table will contain all the previously created customer invoice categories.

Click on “New” button to create a new category and this window appears:

Here you enter the details of the category:

  • Master category: select the master category that this one will belong to. Master categories are a way of grouping other transaction categories together, even categories of different types, to make reporting easier (see section 11.03. Transaction reports, Transaction category filter for details of how master transaction categories can be used in reporting). Master transaction categories are fixed in the system and cannot be edited. Those available are:
    • Damaged
    • Expired
    • Found
    • Lost
    • Stocktake
    • Stolen
    • Other
  • Category code: the code of the transaction category. Not displayed in mSupply but you can filter categories by this so it provides another way to select relevant categories when reporting.
  • Category Description: the name of the category, visible throughout mSupply. Also filterable when reporting.

Once you have created transaction categories they will be selectable in a drop down list when you create a new invoice or transaction.

For systems using Remote Synchronisation, Transaction Categories are 'System' data and can only be edited on the Primary Server. Any edits then synchronise to all relevant satellites.

There is a 'server' preference to Require category entry on customer invoices. This would apply to all customer invoices issued for all stores Active on the server.

See the 28.08. How to report by invoice category section for details on how to use the transaction categories in reporting.



Previous: 26.05. Edit menu | | Next: 26.07. Virtual stores

26.03. Transaction Status & Type Codes

Transaction type codes

mSupply uses a series of two letter codes to denote the different types of transactions it can handle.

Code Meaning
ci customer invoice (goods supplied to a customer)
cc customer credit (goods returned by a customer)
si supplier invoice (goods received from a supplier)
sc supplier credit (goods returned by you to a supplier)
sr repack (changing the pack size of a stock line)
bu build (manufacturing (building) items from other items in stock)
rc receipt (cash receipt) from a customer (a customer pays for invoices issued)
ps payment (cash payment) to a supplier

Inventory adjustments have a type of “si” if stock is being increased and “sc” if stock is being reduced. They have a reserved name whose name[type] field has a value of “invad”

Transaction status codes

Transaction (and requisition) status

mSupply uses a set of two letter codes to keep track of the status of each transaction:

Code Meaning
nw new invoice
sg Suggested
cn Confirmed
fn Finalised
wp The order has been received over the internet (a “web” order), and it is currently being processed
wf The order has been received over the internet (a “web” order), and it is finalised
Purchase Orders
Code Meaning
sg The order has been created, but the “stock on order” value for each item has not yet been updated. If another order for the same item is processed, mSupply will not take account of suggested orders. Suggested orders can be deleted.
cn The “stock on order value” for each item has been updated. Confirmed orders can also be “unconfirmed” if you cancel an order. Items & quantities can still be edited.
fn The order has been received, Goods Receipts and Supplier Invoices have been created for all stock received.
The order is now completed and all stock not delivered is no longer considered “on order”.
No more stock can be received.
Supplier invoices
Code Meaning
nw The “new supplier invoice” menu item has been chosen, but the OK button on the invoice has not yet been pressed, or confirming the invoice has been postponed. (This option is only available if “confirm supplier invoices automatically” is unchecked in the Preferences). Note: quitting mSupply by choosing the “quit” command from the file menu or click the application close box (Windows only) while you are entering a new supplier invoice will result in the invoice being saved with status “nw”. To confirm the invoice, open it then click the OK button
sg This status is not used for supplier invoices- invoices of status “nw” become status “cn” when the OK button on the form is pressed
cn The invoice has been entered, but can still be edited.
fn The invoice has been finalised , and can no longer be edited.
Customer invoices
Code Meaning
nw The “customer new invoice…” menu item has been chosen, but the OK or “confirm” button has not yet been pressed.
sg The invoice has been created. An order from a customer has been received, and the items put against the invoice are still in your store, but are no longer “available” to issue to other customers. (i.e., the “available” amount for each item line has been reduced, but the “quantity” amount has not). Note that if “one step confirm” is checked in the Preferences, then customer invoices move straight from being status “nw” to status “cn”
cn The invoice has been confirmed by clicking the “confirm” button, which is done when the stock leaves the store. Lines that couldn't be supplied are added to the “backorder” file. The invoice can still be edited.
fn The invoice has been finalised, and can no longer be edited. If the Customer invoice is to another store in your system, then finalisation of the Customer Invoice also triggers generation in the receiving store of the Supplier Invoice or Goods Receipt (if the Customer Invoice is the result of a Purchase Order / Requisition from the receiving store)
Builds
Code Meaning
nw The build is being entered for the first time.
sg Suggested - the raw materials are taken out of stock, but the finished product (the item to build) is not yet entered into stock.“
cn Confirmed - the raw materials are taken out of stock and the finished product is entered into stock
fn Finalised - the build can no longer be edited



Previous: 26.02. Reminders | | Next: 26.04. Budgets

26.13. Using the mSupply remote client

As well as using an mSupply client connecting to a local mSupply server, or using a standalone version of mSupply, it is possible to access a copy of mSupply running on a remotely hosted server. In this case, we use remote access software called TSplus (http://www.tsplus.net).

Connecting to mSupply

The first time you run the remote access client, you'll have to enter your TSplus username and password. These correspond to a Windows account on the remote server and are completely separate from your mSupply username and password.

We recommend that you select the “Allow me to save credentials” box so that you don't have to remember it in future.

After clicking Connect, you may get a warning Window similar to this one:

If so, then select the “Don't ask me again for conections to this computer” box to avoid seeing it again in future.

You should then see the normal mSupply login screen - simply login as usual to get to the mSupply navigator, which looks exactly the same as normal except that it is enclosed in a session window:

When you're finished, exit mSupply by using the File → Exit mSupply menu item. If you just use the X button at the top right of the session window, it will close the window but mSupply will continue to run on the server, and use a license which may be needed by someone else.

After exiting mSupply, right-click on the empty desktop and click on the Logout button to close your session.

Printing from mSupply

Because mSupply is running on a remote server, printing forms and reports is slightly different as there is an extra step involved to download them to your local computer. There are several ways to do this, depending on which print option you choose e.g. printing a customer invoice:

Universal Printer

TSplus comes with a “Universal Printer” driver, and if you select the Printer option and then choose this as your printer, the print job should get downloaded to your local computer and then prompt you to choose one of the printer drivers on your local computer to receive the print job.

PDF printer

Foxit or some other virtual PDF printer driver will have been installed on the remote server. You can either:

  • select the Printer option and choose the virtual PDF printer driver as your printer - this will prompt you for a location to save the PDF file and then open it in the default PDF viewer (you may be prompted to choose either Foxit or Sumatra - the screen shots below use Foxit, but Sumatra is similar)
  • select the Preview option - this will generate a PDF file in the default location (C:\mSupply client\Documents\temp) and then open it in the default PDF viewer
  • select the PDF file on disk option - this will generate a PDF file in the default location and open that folder, and then you can double-click on the file to open it in the default PDF viewer

Regardless of which of these you choose, you can use File → Save As to save the PDF file to a folder on your local computer:

Click on Browse to choose where to save it - This PC includes all of your local drives as well as the ones on the remote server:

Exporting to Excel

MS Office won't normally have been installed on the remote server, but Open Office will have been. The first time you try to export to Excel, you'll have to choose the location of “Excel” - in this case, it will be something like C:\Program Files(x86)\Open Office 4\program\scalc.exe.

Select the Export to Excel option to open the report/form in Open Office:

In the same way as for PDFs, you can select a local drive from the File → Save As menu (either as an Open Office .ods document, or an Excel .xls document):

Transferring data

Dropbox will have been installed on the remote server, and can be used to transfer saved reports or other data between the server and any other computer which has access to the Dropbox account.



Previous: 26.12. Product (drug) registration | | Next: 26.14. Authorisation

26.07. Virtual stores

From the Special menu, choose Show stores

What is a virtual store?

In mSupply a virtual store is a way of segregating particular stock so that some users only see that stock and the transactions associated with it. When a user logs into mSupply, they choose a particular store to login to - this we call the current store. mSupply then operates as if:

  1. The stock in that store is the only stock available.
  2. Only stock from the current store will be available for issuing,
  3. Reports will relate to stock in that store
  4. Issues from and receipts to that store only use the stock in that store
  5. Only suppliers and customers sets as “visible” for that store will be able to be chosen for receiving and issuing goods
  6. Only items set as “visible” in that store will be usable (So for example if you have a store that handles only vaccines you can make vaccines visible in that store (and invisible in all stores that don't handle vaccines)

Many users of mSupply will only have a single store, and so will have no need of this functionality.

The following examples illustrate situations where you might want to run more than one store.

  • A hospital pharmacy where you have two dispensing locations: an inpatient pharmacy and an outpatient pharmacy.
  • A pharmaceutical warehouse where stock from a particular donor is received, issued and accounted for separately to stock in the rest of the warehouse.
  • A hospital pharmacy where the pharmacy store stock is treated separately to the dispensary stock. You would set up mSupply with a store called “Pharmacy store” and a store called “Dispensary”. You would use the function covered in section 8.05. Transferring goods to another store to move stock from the pharmacy store to the dispensary.
  • A pharmaceutical warehouse where you have 2 or more actual warehouses. These may be adjacent or several hundred kilometres apart. (Of course you need network connectivity between sites to run mSupply at each site).
  • You're using mSupply mobile- each mobile site will synchronise data with a virtual store on the mSupply server.

Note: In the above examples, when you log on, you would select the appropriate mode - see table:

Examples Stores Log on mode
Hospital Pharmacy In-patient Dispensary Dispensary
Out-patient Dispensary Dispensary
Hospital Pharmacy Pharmacy store Store
Dispensary Dispensary
Warehouse Adjacent Store Store
Remote store Store
Viewing available stores

From the Special drop down menu click Show stores… The Stores list window (shown below) appears and displays a list of all the stores which currently exist including their sync type:

You can customise the columns that show on this window. Click on the Customise button and this window will show:

The columns in the Chosen list are displayed in the table, the columns in the Available List can be shosen to be displayed. Select a column you want to show in the Available list and click on the » button to move it to the Chosen list. Similarly, click on one in the Chosen list and click on the « button to move it to the Available list and remove it from the display. You can also drag items in the Chosen list up and down to change the order they appear; top of the left is the leftmost column, bottom of the list is the rightmost column.

Editing a store

Double-click on any store in the list in the View stores window described above to view or edit its details. You will see the same window as in the Creating new stores section below but the various fields will be filled in with the store's current settings. You can click into the fields and edit them as desired. Note that in the top left of the window, the name of the store you are editing is always displayed, regardless of which tab you are on, so that you always have a reminder of which store you are editing!

If you're working within a syncing system, stores and their settings/preferences can only be created and edited on the central server, and all stores exist on the central server. A mirror sync setup is slightly more complex - stores themselves and any settings related to name visibility are only editable on the central server (or the primary server in versions of mSupply older than v7.13), but master lists and item visibility settings are only editable on the primary server. In this case, all stores exist on both the central server and the primary server.

Creating new stores

This new store will inherit the same user and group permissions (but not login permissions!) as the store which you are logged in to when you execute it. It is therefore worth logging in to a store that has similar user and group permissions to those that you want to have in the new store. Often the supplying store will be a suitable store for this purpose.

As noted above, in a syncing system you must be logged into the central server to create a new store - it will be synced to any site where it is visible to any stores active on that site (which will also include the supplying store). When a store is created, it is made active on the central server by default - see sync sites if you want to move it to (make it active on) another site.

After creating the new store, you will not be able to immediately log in to it. To be able to log in to the new store, you will need to give yourself access to the new store as shown in section 25.15. Managing users. Any other users who need to access the store will also need their permission altered accordingly.

To create a new store click the New store button in the Store list window shown above. This will display the Store details window shown below, which allows you to enter the details of the new store:

If you want to create the store for an existing customer, don't follow the rest of the instructions here. Refer to Transition a customer to a virtual store.

Name

The name used to identify the store throughout mSupply. It must be unique and mSupply will tell you if another store has the same name; you will need to change it before you can save. Any non-printable characters entered before or after the name will be removed. Any entered in the name will be replaced with an underscore (_).

Store code

The code used to identify the store. If you have a lot of stores it would be helpful if you decide on a good pattern to use for the codes. The code must be unique too; mSupply will tell you if the code is already in use and you will need to change it before you can save it. Any non-printable characters entered before or after the code will be removed. Any entered in the code (and spaces) will be replaced with an underscore (_).

Store type

Set in the drop down list to the right of the Store code field. Can be one of:

  • Store: a normal store used for managing inventory and issuing to customers
  • Dispensary: a store used for managing inventory and dispensing to patients
Organisation name

The name of the organisation running the store. Defaults to the organisation name entered in File > Preferences.

Address details

Enter the address and contact details for the store in here if there are any. These details can be used in reports. Note that these fields will be copied to the Main/Billing Address fields in the store's name record (see the 5.01. Names: using, adding and editing page for details) if they are updated.

Turn an existing customer into a store

Only visible if you are creating a new store, not if you are editing an existing one. If this is checked then the Name field becomes a search field for the customer: enter the first few characters of the customer's name and press the Tab key on the keyboard to select the name from all those that begin with what you entered (or mSupply will select it for you if only one customer matches). When the OK or OK & Next buttons are clicked, the existing customer record will become this new store.

Down arrow button

Only visible if editing an existing store, not when creating a new one. Clicking this button will open the store's name record (see the 5.01. Names: using, adding and editing page for information on names) where you can view and edit things like categories.

Disable this store

Check the Disable this store checkbox to stop the store from being used. You might want to use this feature if the store is not ready for use yet or is no longer to be used and can't be deleted. You will be asked to confirm the disabling after clicking on the OK button on this window.

Responsible officer

Select the officer responsible for the store in this drop down list. A helpful reminder for others and can be used in reports.

Store credentials

These are used when the store needs to be identified securely over electronic communications. An example of this is when using the cold chain app for monitoring temperature in cold storage and freezers.

To tell mSupply to use the credentials, check the Use store credentials checkbox (unchecking it deletes the store's credentials so please be careful before doing so).

This will enable the Username and Password text fields and you can enter the appropriate details.

  • The Username will be set to the first three letters of the store's code by default.
  • The Password must be at least 4 symbols but not more than 30 symbols, and can contain letters and numbers.

If you need to view the password you have entered to check it is correct, click on the button.

Tags

Tags are used in several ways:

  • for determining which programs a store can use.
  • for controlling some customisation features.
  • for reporting to group stores together.

This area shows the tags that the store currently has. To add a tag, simply click into the area and type the tag's name. When you have finished typing the tag's name then press the Tab or Space keys on the keyboard (not Enter or return, that will close the window!). You know when you have done it right because the tag will appear in its own little box with an 'x'. If you want to remove any tag from the store, simply click on that 'x'. In this way you can add or delete as many tags from a store as you like.

When you click on the OK, OK & Next or OK & Previous buttons, any new tags you have created here will be added to the list of name tags in your system. See the 5.05. Name tags page for details.

After having created a new store, the Stores list window will display the new list of all stores and you may double-click an entry to edit that store's details. A number of things that will need to be attended to are:

To do a number of the following steps, you will need to log in to the new store. To do this, you will need to give yourself access to the new store as shown in section 25.15. Managing users. Any other users who need to access the store will also need their permission altered accordingly. After giving yourself permission to log in to the new store, log in to it and carry out these steps.

  • Set the preferences for the store.
  • Set the store's logo so that it can appear in print-outs and reports.
  • Set the visibility of names and items in the store. All items in the system will be set to invisible in the new store when it is created. You will need to modify visibility of items in order to be able to handle stock of those items.
  • Setup any custom store data (used for reporting).
  • Set the master lists used by the store (a convenient method for controlling item visibility). See 4.04. Item master lists
Preferences tab
  • The preferences described here are set 'per store' and can be different for each store in an mSupply datafile.
  • In a synced system the store preferences will be synced along with the store to any sites where the store is visible.
  • Other preferences (accessed through File > Preferences…) apply to all stores in an mSupply datafile.
  • If you have to set the same preferences for lots of stores you might like to try the 26.08. Bulk Store Preferences Editor. It just might save you some time and your sanity :-)

This tab contains the preferences that can be set for a store. Each store has its own settings for these preferences: this is different for the settings in File > Preferences which apply to all stores in an mSupply datafile.

This is what the tab looks like:

The Search store preferences search bar at the top is used to find a particular preference. If you type something in here, preferences which contain the text you have typed only are displayed, all others are hidden. There are a lot of preferences so this should help if you just can't find the one you want!

This is what each preference does:

Sort available batches by VVM status rather than Expiry When issuing stock, this will sort the list of available batches by vaccine status first, then by expiry date rather than by expiry date first (e.g. 8.01. Issuing goods to a customer (customer invoices)).
Patients created in other stores not visible in this store If this is checked, patients that are created in other stores across all sites will not be visible in this store. If it is off, all patients from all stores from all sites will be visible to this store. It is set to true by default when a store is created. USE CAUTION: Turning this OFF for many stores does not scale well and can overload the sync system. See the 10.03. Patients page for more details.
Names created in other stores not visible in this store If this is checked, names (customers, suppliers, manufacturers, donors etc.) created in other stores in the same site will not be visible in this store. It is set to true by default when a store is created.
Allow users to enter total quantities to distribute to appropriate packs On a customer invoice an additional Total field is displayed so that users can enter the total quantity of units that they wish to distribute or the number of packs.
Round up the distributed quantity The value for distributed quantities will be rounded upwards.
Able to pack items into multiple boxes Checking this enables the functionality for packaging goods into boxes on the Transport tab of a customer invoice. See 8.06. Box management for details.
Store: Able to issue in foreign currency Foreign currencies can be used on supplier invoices for overseas suppliers.
Allow editing selling price on customer invoice lines Individual selling prices can be edited on customer invoice lines. Please note that the Price editable when issuing checkbox on the General tab of an item's details page must also be checked for each item that the price is to be editable for.
Purchase order must be authorised Turns on purchase order authorisation. See Ordering Items From Suppliers.
Finalise customer invoice automatically Automatically finalise customer invoices with confirmed status, which is normally when the goods are dispatched.
Customer invoices must be authorised Turns on customer invoice authorisation (i.e. goods can only be sent to a customer after the action has been authorised). See 26.14. Authorisation for details.
Authorisation needed only if over budget This additional option is enabled when customer invoice authorisation is turned on.
Confirm customer invoices automatically Set a New Customer Invoice status to confirmed when the OK button is clicked. This means that it is not possible to print a picking slip for the issued goods.
Supplier invoices must be authorised Turns on supplier invoice authorisation (i.e. goods can only be brought into stock when the action has been authorised). See 26.14. Authorisation for details.
Confirm supplier invoices without asking Sets a new Supplier Invoice status to confirmed automatically when it is saved (i.e. when the OK button is clicked), with no request for confirmation. The goods are made available in stock without informing the user.
Disallow adding expired stock to supplier invoices If checked then a user will not be allowed to add stock which is already expired to a supplier invoice. If a user does this, they will be shown an alert message saying that the line is expired and they will not be allowed to save it. The same check is also performed when adding lines to a goods received note, an inventory adjustment - add or a customer credit.
Goods received lines must be authorised: Turns on goods receipt authorisation (i.e. only authorised goods receipts can be processed for the goods to be made available in stock). See 26.14. Authorisation for details.
Locations must be entered for goods received A shelf location must be entered on the goods receipt item line form when receiving goods into stock.
Able to specify manufacturer when receiving, ordering or quoting for items Gives users the option to record the manufacturer of goods when making purchase orders, goods receipts or entering a quotation from a supplier.
Show item unit column when issuing If checked, when goods are issued on a customer invoice or prescription, an Item unit column is included in the window used for selecting items to add.
Log transaction edit
Set pack to one for all visible items in this store
Use remote authorisation for response requisitions Turns on remote authorisation for response requisitions. See 26.15. Remote authorisation for details.
Include requisitions from this store in suppliers' remote authorisation processes If checked then requisitions from this store will appear in the requisition approval processes of the suppying store. See 26.15. Remote authorisation for details.
Can manually link requisition to supplier invoice When receiving stock, users can match the supplier invoice to the initial requisition. They can then add items from the linked requisition, speeding up the process of creating the supplier invoice. This is useful for stores requesting and receiving stock from suppliers that do not use mSupply. See the 7.01. Supplier invoices page for details.
Automatically populate supply quantities with requested quantities On requisitions, automatically populate supply quantities with requested quantities, instead of 0. Supply quantities can still be edited.
Show extra fields on requisitions When a line is selected on a response requisition, an extra box is displayed under the table of requisition lines to show the calculations behind the suggested quantity. The extra field is currently only populated for Côte d'Ivoire users.
Keep requisition lines with zero requested quantity on finalise If this is checked, lines on requisitions that have zero requested quantity are kept when the requisition is finalised. Otherwise they are deleted (normal behaviour).
Show comment field when entering supplier invoice lines Allows users to type a comment for individual items received on a supplier invoice.
Use EDD placeholder lines in supplier invoices from this store If turned on, any placeholder lines on a customer invoice that is a stock transfer are duplicated on the supplier invoice in the receiving store when the customer invoice is finalised. The placeholder lines in the supplier invoice appear on an Unsupplied items tab (see the 7.01. Supplier invoices page for details). Note: the placeholder lines are not duplicated on the supplier invoice if the receiving store is an mSupply mobile store (placeholder lines are not used in mobile stores).
Consolidate batches Items with the same batch, expiry date, pack size, location, donor, cost and sell price will automatically consolidate when bringing goods into stock from a supplier invoice or doing a stocktake.
Edit prescribed quantity on prescriptions When checked an additional Prescribed quantity field is available when entering a prescription line. See 10.02. Prescription entry for details.
Allow users to choose diagnosis on prescriptions When checked an additional Diagnosis drop down list is available on a prescription. See 10.07. Diagnoses for details.
Use consumption and stock from customers for internal orders If checked, when calculating the current stock and consumption figures (to calculate the suggested order quantity), the stock issued to all customers and the total stock of all customers will be used instead of the current stock and consumption of the current store. Note that customer stores are all those stores that have this store set as their supplying store. See the 6.04. Ordering from one store to another page for details about internal orders.
Items received on a purchase order must be within a minimum expiry date When turned on, stock cannot be received if it has an expiry date that is before a date set on a purchase order. See mSupply mobile setup for details.
Store credentials are controlled on the central server In a syncing system, if this preference is checked, then the Store credentials preferences (see the Store credentials section above for details) can only be edited on the central server, rather than on the site where the store is active (where they are usually edited).
mobile: Alert if a patient is dispensed the same vaccine multiple times in a week This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Enforce lookback period This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Uses vaccine module This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup and also 20.01. Vaccine Vial Monitoring (VVM) for details.
mobile: Uses dispensary module This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Uses dashboard module This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Uses cash register module This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Uses payment module This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Uses patient types This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
mobile: Uses Hide Shapshot column This preference only has an effect if this is an mSupply mobile store. See mSupply mobile setup for details.
Pickface replenishments must be authorised If checked, pickface replenishments in this store must be authorised by a user who has permission to authorise them before they can be finalised. See the 4.21. Pickfaces and Replenishments setup and 4.22. Pickfaces and Replenishments pages for details.
Able to specify VVM status when receiving items If checked then a new VVM status field will be available on a supplier invoice for the user to select the current VVM status of the batch when it is received on a supplier invoice or inventory adjustment. See the 7.01. Supplier invoices and 4.18. Inventory adjustments pages for details. Also, if checked then an additional Doses column is displayed on a customer invoice. See the 8.01. Issuing goods to a customer (customer invoices) page for details.
Notification preferences

These are used by the notification/alert functionality described on the 14.01. Notifications (Alerts) page. The notifications inform users of situations that need their attention. The thresholds that give rise to some of the notifications can be set here.

Threshold for overstock

The minimum months of stock an item must have to be considered as overstocked. i.e. in danger of expiring on the shelf before it is used. An alert is triggered for an item if the total quantity in stock (including all batches) divided by the average monthly consumption of the item (calculated using the last 12 months' usage in the current store) is greater than or equal to this threshold number. The default is 6 months.

This value should be set no lower than the maximum amount of stock that you would expect to regularly have in stock. Based on the formula developed in Calculating the required stock quantity, this would be Ordering cycle + (months of) buffer stock. The default value of 6 is suitable for a store with a 2-monthly order cycle. For a central store with an annual order cycle, then this figure should be set to 36

Threshold for understock

Also called Buffer stock, this is the number of months of stock that an item must have less of, to be considered understocked i.e. in danger of not having enough to meet demand. An alert is triggered for an item is the total quantity in stock(including all batches) divided by the average monthly consumption of the item (calculated using the last 12 months' usage in the current store) is less than or equal to this threshold number. The default is 3 months.

This alert should only be triggered when your stock levels fall below your buffer stock levels. Based on the formula developed in Calculating the required stock quantity, Buffer stock (months) = 2 x Ordering cycle. The default value of 3 is suitable for a store with a 6-weekly order cycle. For a central store with an annual order cycle, then this figure should be set to 24. That is a lot of space for a national store with several thousand items :-/

Expiring items period

An alert will be triggered for an item if a batch is due to expire in less than this number of months. The default is 3 months.

This alert should be triggered if there is a reasonable risk that your store, or your store's customers will need to dispose of stock due to expiry. However, this is only a real concern if there are significant quantities of the item with short expiry. So, in isolation, Expiring items period is a bit arbitrary. As a rule of thumb, the Expiring items period can be set to equal the ordering cycle. On that basis, the default value of 3 is suitable for a store with a 3-monthly order cycle. For a central store with an annual order cycle, then this figure should be set to 12

Custom data

This section is for store specific custom data fields that must always be present. User definable custom fields are handled on the Custom fields tab (see the Custom fields tab section below for details).

Monthly consumption lookback period: The number of months of consumption information to use when calculating average monthly consumption for this store. Currently only used when the Côte d'Ivoire customisation is enabled.

Months lead time: The number of months before ordered goods normally arrive. Used to calculate how much stock to order for the suggested quantity in requisitions, for example. Currently only used when the Côte d'Ivoire customisation is enabled.

Suggested packing in boxes

These preferences affect the suggested pack functionality described on the 8.06. Box management page.

  • Prefix for generated boxes: Defaults ot no prefix. Each box created in a suggested pack has a number which starts at 1 and increments by 1 for each new box created. Whatever you enter in this text field will be added before these numbers to give you the box names. For example, if you enter “Box-” then the boxes will be created with names “Box-1”, “Box-2”, “Box-3” etc.
  • Percentage space to leave empty: Defaults to 0. Boxes will be packed as close to 100% of their volume minus the value entered in here. This is helpful to account for situations where the size, shape and possible orientation of packs make it hard to pack them all into the actual volume expected.
When finalising a goods receipt

There are three options:

  • Don't receive goods into stock until supplier invoice is taken off hold - for goods to enter stock you must finalise the goods receipt and then take the automatically generated supplier invoice off hold
  • Receive goods into stock, and leave supplier invoice confirmed - goods enter stock as soon as the goods receipt is finalised. The automatically generated supplier invoice is created with confirmed status.
  • Receive goods into stock, and finalise supplier invoice immediately - goods enter stock as soon as the goods receipt is finalised. The automatically generated supplier invoice is created with finalised status.

How you set this preference is determined by how separate your goods receiving and finance sections are. If they are not in the same building, you might want to use the “Receive into stock and leave confirmed” option, as this will allow you to proceed with issuing goods without waiting for the finance department's approval.

For stock transfers, the supplier invoice in the receiving store should be...

This option applies to all stores that this store transfers stock to.

This option is used to determine whether stock transferred from one store to another is received to a destination store and automatically introduced to stock or not. The On hold option prevents stock from being introduced, while the Finalised option automatically makes the stock available for use in the destination store - without the receiving store having the opportunity to amend the Goods Receipt.

  • Choose Finalised if there is no need to check / alter the quantity received compared to what was sent.
  • Choose On hold if the store is being used by mSupply mobile, and the goods receipt needs to be confirmed before receiving.
Location code pattern

This is used with phased stocktakes (see the 4.18. Phased stocktakes page for details) to tell msupply which parts of your shelf location codes (see the 4.06. Stock locations and location types page for details) represent the aisle, level and position of the location.

An aisle is a whole row of racking like this:

A level is a horizontal level of the racking like this:

And a position is a vertical column of the racking like this:

Use the letters A, L and P to represent the aisle, level and position parts of the location code.

Let's use an example to show how it works. Let's say that the shelf location codes are in the format B01.C.01 where B01 represents the aisle, C represents the position and 01 represents the level. Then in the Location code pattern text box you would enter the text AAA.P.LL

It doesn't matter what characters you use as separators, mSupply only looks for the positions of the letters A, P and L. If more than one character is used to define any of the three parts of the location then they must appear together in the location code pattern.

Logo tab

Here you can set the store logo by pasting in a logo you have copied to the clipboard - you must copy the contents of a file to the clipboard, not the file itself. The file can be in .jpg, .png, .bmp, .gif, or .tiff format. This logo will be displayed at the bottom right of the mSupply navigator screen when you login to this store only.

This store logo will override the logo saved in the Settings > Preferences > Logo tab.

To print this store logo on standard customer and supplier invoices etc. you will need to go to the Settings > Preferences > Logo tab in mSupply and tick the Display logo on invoice checkbox. When a store logo is set it will print the store logo instead of the logo set on that preferences tab.

Note that after saving the store logo you must login to mSupply again or use the switch function to reload this store to see it.

Custom fields tab

This tab shows the custom fields that have been set up for stores (see the Custom fields section for details). You can also add or edit custom fields directly from this screen.

Adding a custom field

To add a new field, click on the New line button; a new line with default values of “Field label” and “Field value” in the two columns is added to the table and highlighted. Click on the value in each column and type the real label and value for the piece of information.

Editing an existing custom field

To edit the label or value of any custom field, simply click on the cell in the table and edit the entry.

Deleting a custom field

To delete any custom field simply select its row in the table and click on the Delete line(s) button. You can use Shift+click, Control+click, Control A (or Cmd instead of Ctrl if you're using a Mac!) to select multiple lines and delete them all at once if you like.

Master lists tab and Visibility tab (controlling item visibility)

Controlling the visibility of items in different stores is important because you can only order, distribute, receive goods for, and report on items that are visible in your store. It's also important that stores don't have items visible that they don't use so that they don't accidentally order them etc.

In a syncing system, item visibility and master lists can only be edited on the primary server ⇒ if it's a mirror sync system, then you'll need to create the store first on the central server and wait for it to sync to the primary.

If you have lots of stores in your data file, managing item visibility can turn into a difficult task. Thankfully, mSupply has some helpful tools to make it simple! There are 2 ways to manage item visibility and you use one or the other, not both:

  1. automatically using the Master lists tab or
  2. manually using the Visibility tab

Each are useful in different situations and are described below.

Master lists tab

If you have a lot of stores in mSupply, and especially in a syncing system, we recommend that you use master lists to control item visibility, because it means that the visibility of newly created items will be automatically handled correctly. The visibility of items in a store whose visibility is controlled by master lists is immediately updated if any changes are made to any of the master lists. For instance, if a new item is added to a master list controlling visibility then that new item is made visible in all stores that use the master list. And any items deleted from the master list are made invisible in any store using that list.

The first thing to do is to turn on the preference to make master lists control item visibility in stores. Do that in File > Preferences… on the Item tab - see General preferences, the item tab for details.

The next thing to do is to create the master list(s) that will control item visibility. See Item master lists for details on how to do that. Giving your master lists helpful names will help you remember what they're for e.g. “Store xxx visibility list”.

Now edit the store to tell mSupply which master list(s) will be used to define which items are visible in the store:

  1. Click on Special > Show stores… (or click on the Stores icon on the Special tab of the navigator)
  2. Double-click the store who's visibility you would like to manage:
  3. Click on the Master lists tab:
  4. Select which master list(s) you would like to control the visibility of items in your chosen store by checking their checkbox in the Use master list column: In this example, the All items: General warehouse master list has been selected to control the visibility of the General warehouse store. Please note: If there are a lot of master lists, you can type in the Search master lists field and the list will show only those master lists which contain what you type.
  5. Click the OK button to finish. As soon as you do that the items on the selected master list(s) are made visible in the store and any items not on the selected master list(s) are made invisible. Any new items added to the selected master list(s) will be made visible in the store and any items removed form the master list(s) will be made invisible in the store.

NOTE: Assigning master lists to stores can also be done on a master list's details window. See the 4.04. Item master lists page for details.

Visibility tab

In a syncing system, the item visibility icons and fields will be disabled unless you're on the primary server; the name visibility icons and fields will be disabled unless you're on the central server.

You will only be able to use this tab if you have permission to login to the store you have selected and you have permission to edit visibility in that store.
To log into a store you may need to first give yourself permission to do so under File > Edit Users > Double-click your user name > the Log in rights tab. Phew!

The Visibility tab contains tools for manually setting the visibility of items and names in a store.

The item visibility tools are good to use if you do not have many stores in mSupply and only need to make occasional changes to visibility for a number of items. If you want to make a change to a single item's visibility in a single store then you can do that by going to the item's details window and using the store tab (see Item basics, the stores tab).

If you have turned on the preference to control item visibility by master list then you will not be able to use the visibility tab or the visibility settings on the store tab of an individual item's details window.

Here's what the tab looks like:

The buttons provide you with different ways to hide and show items and names in the store (Note: be careful showing names in databases that have a lot of names records. For example if you have 20 virtual stores and 200,000 names in your database, showing all names in all stores will create 4 million (20×200,000) records to map the visibility of each name in each store):

  • The Show stats button shows how many items and names are currently hidden and visible
  • The Set item visibility to match master lists for this store button matches the item visibility to the master lists that are selected on the Master lists tab. (Note: this is a one-off operation, no changes will be made to item visibility if the master lists are changed after you click this button. See the section above if you want that to happen!) If there are some items that can't be set to invisible (because they have stock, for example) a temporary master list will be created containing the items which could not have their visibility removed. Use the list to decide what to do with each item.
  • The Make all items in this store visible and Make all items in this store invisible both do just as they say.
  • The Set pack to one for all visible items in this store will check the Allow pack to 1 conversion and Convert pack to 1 when receiving checkboxes for all items in the store so that all stock received into the store will automatically be received in packs of 1. This is useful in a dispensary store, for example.
  • The Set to match button requires you to choose a master list. Clicking the button makes the items that are on the master list selected in the drop down list next to it visible in the current store. Note that it does not hide items that are already visible but not on the master list.
  • The Make all names in this store visible button does exactly what it says and makes all names in the datafile visible in the current store.
  • The Make all names in this store invisible button does the opposite and makes all names in the datafile invisible in this store. Be careful using this - you won't be able to receive or distribute stock from/to anyone until you make some names visible in the store!
  • The Query names button enables you to search for names (customers, suppliers, manufacturers, donors etc.) in the datafile. Every search you run creates a selection which is then operated on by the Make found names visible in this store button.
  • The Make found names visible in this store will make all names in the last selection made with the Query names button visible in this store. Ask Sustainable Solutions for help if you're not sure about getting the right selection of names, as the consequences of making a mistake can be time consuming to fix!
Users tab

The users tab shows which users have permission to log into this store.

The table shows a list of all the users in alphabetical order. If a user can login to this store then their corresponding Can login checkbox will be checked. If the store is the user's default store then the checkbox in the Default store column will be checked.

You can add or remove permission for a user to login to this store by checking or unchecking their Can login checkbox (only if you have permission to edit store details though).

Synchronisation tab

mSupply has a synchronisation system designed to cope with environments which have weak or intermittent internet. The system passes information between a server and remote site (or tablet running mSupply mobile) when there is an internet connection, and stores information to be sent when there is not.

See the 29.01. Introduction to Synchronisation page for more details.

This tab displays some of the synchronisation settings for this store:

The Resync patient records when store is saved checkbox forces all patient records to be re-synchrionised with the server when the OK button is clicked. This is useful if there appears to be something wrong with one or more patient records.

Names tab

This tab shows a list of all the customers, suppliers and stores (collectively called “names”) in the datafile and which are visible in this store. If you're on the central server (and you have edit visibility permissions for the store), you are also able to edit the visibility of names:

The table shows whether the name is a customer or supplier (or both). The checkboxes in the Visible in this store column are editable. If checked then the name is visible in this store, if unchecked then the name is not visible in this store. Click on one of the checkboxes to change its state.

  • Store checkbox: If checked then names that are stores are shown in the table
  • Customer checkbox: If checked then names that are customers are shown in the table
  • Supplier checkbox: If checked then names that are suppliers are shown in the table
  • Search names field: If you type in here then only names that contain what you type will be displayed in the list. Useful if you want to find a particular name or group of names in a long list.
  • All off button: Clicking this will uncheck all the checkboxes in the Visible in this store column (so making all names invisible in this store) and the button will change to All on. Clicking it then will check all the checkboxes in the column (and therefore make all names visible in this store).
  • Copy button: Copies the current state of all the checkboxes in the Visible in this store column.
  • Paste button: Pastes the states of checkboxes saved using the Copy button to the names in the table. Doesn't do anything if you haven't previously clicked the Copy button.

Clicking on the OK, OK & Next or OK & Previous buttons will save any changes you make on this tab.

Deleting a store

To delete a store, click on the Delete button in the View stores window. Note: deletion of a store is a serious thing to do and is only possible when that store contains zero stock and there have been no transactions recorded. mSupply will check and tell you that deletion is not possible if these criteria are not met. If you can't meet these criteria and you still want to stop people using the store then you can disable it - see above.

If the store is Active on another site, then this process will not delete the site.

Transition a customer to a virtual store

You may have a customer that is about to start using mSupply. That customer needs to become a store in mSupply. There are two ways to do this.

Whichever method is used, this is difficult to reverse. Only do this once you are sure. You have been warned!

Create new store and then merge with the existing customer name

Until version v5.02 (see below), the procedure was:

  1. Create the new store with a similar name
  2. Use mSupply's Merge names functionality to merge the two names into one
  • You must choose the newly created store's Name as the “Name to keep” and the older Customer's name as the “Name to delete”. However, doing this means that you will lose the original name properties. Therefore you should also take a note or a screenshot of name properties that you want to keep (e.g. address, categories etc.) and then re-apply them to the new store name.
  • mSupply may prevent the merge due to unfinalised CIs from other stores in the system. You will need to finalise these CIs on the corresponding stores before the merge is successful.
  • These can be hard to find on a multi-store system where the transactions could have come from a number of places. Suggested approach: Use Supervisor mode, view CIs, and customise the list view to show Store name.
  • If these transactions are on a number of stores on remote sites with dodgy internet connections, it can take days to log in to the remote sites, finalise the CIs, and sync the finalised CIs back to the central server. Meanwhile, there is a danger that new transactions will be created! :-\
  • These inconveniences are why the Turn an existing customer into a store feature was developed ;-).
Turn an existing customer into a store

Due to the limitations of the method described above, from mSupply v5.02 onwards, you can choose to convert an existing customer into a store, and thereby retain all of its properties.

If the name is not visible to the store that you are logged in to, this method will not work! First make the name visible, then start this process…

  1. Log into a store that will have the same or similar user and group permissions as the new store.
  2. Customer > Show customers… to find the customer that you want to convert into a store and copy the Name. This will ensure that you are converting the correct name into a store - see warning below!
  3. Special > Show stores… > New Store You will see an alert like that shown below. If you are logged in to a suitable store (see Alert above), then you can continue:
    \\

    User store login permissions are NOT copied to the new store. These will need to be manually configured.

  1. Click on the Turn an existing customer into a store checkbox
  2. Enter the existing customer name into the Name field. You can search for existing customers by typing the first few letters of the customer's name, and then press Tab. To ensure that you are converting the correct name into a store, paste the Name that you copied in step 2 above. This should result in at least the store code field getting populated. If this does not happen, then the existing customer has not been recognised - try again.
  3. Populate the Responsible officer, Store credentials and Tags fields if required.
  4. Click OK



Previous: 26.06. Transaction categories | | Next: 26.08. Bulk Store Preferences Editor

27.03. Help > About mSupply

You can get a lot of useful information about your current installation in the Help>About mSupply menu item. When you choose this from the menus, this window opens:

  • mSupply version: This sectio, at the top, shows tyou wnat version of mSupply you are running and when it was released (date and time).
  • Paths: This section shows you some of the paths to the datafile and the log file in case you need to track them down.
  • Show table records button: If you click on this button the table below it will be populated with the names of the tables in the mSupply database in the Table column and the number of records each holds in the Records column.
  • Show sync records button: If you click on this button the table below it will be populated with the names of the synchronisation sites set up in the datafile in the Site column and the number of sync records waiting for each site in the Records column. If there are a lot of sites, you can type something in the Filter site field and the list will display only those sites that contain what you have typed.
  • Authorisation button: A very special button, which opens a password entry window. If you enter the correct password, you enter a world of wonder and spectacular beauty. You also get access to lots of special functions that only The mSupply Foundation staff have access to :-).



Previous: 27.02. mSupply Support Web Portal | | Next: 28. Frequently Asked Questions

27.01. Support and mSupply Up-to-Date program

This page explains what is covered by our support and mSupply Up-to-Date program charges. Please note that both charges are optional

Support

Support covers all the ways we help you use mSupply well and keep it running. This includes communication via:

We also offer

What we provide

  • Help with “How do I ….. ?” questions.
  • Help if you think things aren't working correctly.
  • Installation of updates
  • Backups of your data to our cloud storage
  • We aim to give a first response to all support requests within 4 working hours, using working hours in Nepal (10am-6pm Nepal time). In reality we have much longer working hours, and are therefore able to respond outside Nepal working hours, because of our offices in New Zealand and staff in the UK.

mSupply Up-to-Date program

Our Up-to-Date program provides you with the latest versions of mSupply for a fixed yearly fee.
New versions include:

  • Updates to the underlying database system that provide compatibility with new versions of Windows and MacOS as they are released.
  • Updates to the underlying database system that provide performance improvements or new capabilities. (For example in 2018 we installed 64 bit versions of mSupply that made many operations such as long reports ten times faster than before).
  • New features in mSupply - our version history is here: https://www.msupply.org.nz/history
  • Bug fixes

Members of our mSupply Up-to-Date program have their feature requests treated with priority. If these features are applicable to a wide user base they are often included for no extra charge.



Previous: 27. Help | | Next: 27.02. mSupply Support Web Portal

27.02. mSupply Support Web Portal

We all like it when things run smoothly but every so often things go wrong. The mSupply Support Portal is where you go to get technical support for mSupply.

Log a one-off support ticket

To log a support ticket with our support team, go to https://support.msupply.org.nz/ and enter the details of the issue and click the “send message” button.

Register

If you are a regular support user, it makes sense for you to register with us so you can keep track of your support tickets.

To register, click the green sign in button on the right then click on the link “Don't have an account? Create one for free.”.

Enter your email address and click the “Send Confirmation Email” button.

This will send an email with a code to your selected email address. Enter this code and your name and password into the next screen and click the “Register” button.

Once registered and signed in, you will be able to lodge support tickets, access ticket history and administer your account. Under my account, you can also use the “Sharing/Collaboration” link to the left of the window to share tickets with others in your organisation.



Previous: 27.01. Support and mSupply Up-to-Date program | | Next: 28. Frequently Asked Questions

28.11. Benefits of a multi-store system

Introduction

When you have mSupply installed in a multi-store system, and the store operators have been faithfully recording stock transactions (receiving, issuing) and doing stock takes and finalising the inventory adjustments, then mSupply can do all the hard work of getting them to work together.

Quantification and ordering

  1. Generate a Suggested order quantities report to get a sense of what is needed. Review it to make sure that it makes sense, then,
  2. If you are ordering to a supplier outside of your mSupply system, Create a new (calculated) purchase order
  3. If you are ordering to another store in our mSupply system, generate an Internal Order

    Internal orders do not include pack sizes; all items are ordered in 'single' units.

Receiving the order

In the supplying store:

  1. Process the order from the customer This is the opportunity for the store manager to review any orders and adjust quantities to be issued (for example, because of a need to ration scarce stock).
  2. Create the customer invoice including, if possible, using the Grinder button to automatically select stock based on FEFO

    While requisitions do not include pack sizes; this is taken in to account when stock lines are selected. mSupply does allow decimal quantities. You may wish to review and amend any decimal quantities prior to printing the picking list, but this is not actually necessary because your stock pickers can make necessary changes… see below

Filling the order

  1. Generate the picking slip

When the picker comes across a line with a decimal quantity, the should take the initiative to round up or down the quantity picked to a whole number and record that on the picking slip accordingly.

Receiving the stock

In the receiving store, when the stock has arrived:

  1. Receive the goods



Previous: 28.10. Tips and tricks | | Next to: 28.12. How to access Temp folder

28.12. How to access Temp folder

Introduction

mSupply uses the operating system to store generated reports and printouts like excel and PDF documents. There may be instances where viewing the temp folder is required. There are various way to navigate to the temp folder.

Using mSupply

View any customer or supplier invoice. Pretend you want to print the invoice. As shown below choose to view the PDF file on disk.

Once the report or print out is generated you will be shown the option to view the file. Choose Show me as shown below. You will be shown the file inside the temp folder location.

The Smart Geek Way

If you are using Windows, then you can show off to your friends using this technique. On your computer keyboard, hold down the “Window Key” and click the “R” key. A window such as below will be displayed. This is known as the Run window.

We want to open the Temp folder, so type %temp% as shown and click OK to run.

The Temp folder will be displayed in an File Explorer window as shown below.

The folder mSupply should contain all the files that mSupply has generated.



Previous: 28.11. Benefits of a multi-store system | | Return to: 28.13. Fixing incorrectly received stock

28.07. How to correct wrong pack sizes

Introduction

In a warehouse or dispensary, stock may be received in 'bulk' (larger pack sizes) which then need to be physically and logically broken down in to smaller, 'issue size', packs before the stock is issued. It often makes sense to keep last-expiring stock in bulk quantities until closer to the time it will be issued:

  • It makes for easier stock-taking; just counting the number of cartons, rather than working out how many inner packs are in the cartons, and then multiplying that by the number of cartons.
  • If you will be splitting a stock line to move a carton(s) to a more accessible location for issue, then keeping the 'carton' pack size makes it easier to identify how much stock needs to be to split off.

In any case, whenever it is done, you will need to change the pack size of your stock.

It is important that changing pack size does NOT change the total amount of stock that you have. mSupply is carefully designed to ensure this.

However, if you have accidentally told mSupply that you have issued more stock than you actually have, then mSupply does allow for these to be corrected through the process described in Changing pack size for stock already issued, below.

Changing pack size for stock on hand

The pack size for Stock on hand is changed through either of two methods:

Changing pack size for stock already issued

If your staff have forgotten to tell mSupply about the new pack size through a Repack or Split, then stock may be issued without noticing the large pack sizes. This will result in mSupply being told that much more stock has been issued than actually has been.

In an pharmacy environment, the same could also be true if the 'Pack to one' preference has not been set. Most users tend to rely on the stock being introduced to the system in the correct pack sizes (suitable for patient consumption) and when this is not done, the dispenser doesn't pay attention to the pack sizes and accidentally tells mSupply that they are issuing stock with large pack sizes.

In both cases the customer or patient receives drug quantities that are generally much less than what mSupply has been told.

It is much better to take measures to ensure that these errors do not occur frequently, but if you find that you haven't, mSupply does have the facility to correct the pack size for stock that has already been issued. As you can imagine, this is a powerful and potentially harmful feature and so there is a special user permission to allow this. Only high level users should have the user permissions to carry out the task below.

User permissions

Firstly to correct pack sizes you need to have the following user permission :

  • Can update pack size, cost and sell price

Do the following :

  • View File > Edit Users…
  • Double click on the user that requires the right to correct pack size mistakes.
  • View the “Permissions” tab
  • Make sure the permission “Can update pack size, cost and sell price” is ticked (see image below)

Locating the item

For this tutorial let's assume that we are inside a pharmacy where Amoxicillin 250mg tab/cap should have been introduced as single tablets rather than boxes of 100 tablets. The pharmacy never has to dispense the whole bottle (100 tablets) to one patient.

View the item where the pack size needs to be adjusted :

  • Item > Show items… from the mSupply menu. Use the search filter
  • Navigate to the item in the list and double click.
  • Go to the “stock” section. View the image below:

The image above shows that a batch of Amoxicillin 250mg tab/cap has been received in packs of “100”.

Double click on this stock line and view the ledger associated with this batch: The image above shows that two patients (John Smith and Jennie Parker) were issued in total 500 and 200 tablets when the correct amount should have been 5 and 2 tablets. Let's assume that the pack size on all should in fact be “1”

Now close the item stock line details window and view the item again.

Getting to the source

To correct the pack size from “100” to “1”, we now need to locate the invoice that initially introduced this batch (b39399) of Amoxicillin 250mg tab/cap to our stock.

Do the following :

  • Get back to the item detail window showing the batch lines.
  • Select the batch line.
  • Then click on the “Show related invoices” icon
  • You will now be presented with a list of invoices connected to this particular batch of stock.

Locating the stock introducing invoice

From the list of invoices we now need to view the invoice that initially introduced the stock.

The image below contains customer and patient invoices (“ci” type), an inventory adjustment (“sc” type) and a supplier invoice (“si” type). The supplier invoice has been highlighted.

Double click on the line for the supplier invoice to open it.

Viewing the invoice

View the invoice and you will see one or more lines showing items that have been introduced to stock. Among them will be one containing the item you're interested in - make sure you identify the right one because there could be more than one batch of that particular item. For this example the invoice only contains one line. This invoice line was responsible for introducing an unsuitable pack size for dispensing purposes.

Double click on the line to open up the supplier invoice line:

Correcting pack size

You should now see a window similar to the image below :

For this example lets assume that the total quantities are correct. Here we did indeed receive 20,000 tablets. So we are going to make the following adjustments.

The step below is only possible if you have the user permission “Can update pack size, cost and sell price” set as described above. If this permission is not set, the pack size is disabled but still viewable.

Starting with mSupply v4.12.06 the pack size field is only enabled if there are no pending repacks connected to the stock. If suggested repacks are encountered, they either need to be deleted or finalised.

Below we have changed the packsize to “1” and pushed the quantity to 20,000

So, as before, the total tablets we have received is : 20,000 X 1 = 20,000

Click “OK” to save the changes.

We are done. Close the invoice.

Review of the changes

Now, to see the result of the pack size adjustment, view the item and its ledger associated with batch “b39399”:

From the image above we see that the available and total stock figures have changed.

We can also see that pack sizes on past ledgers have been converted from “100” to “1”.



Previous: 28.06. Why is my stock on hold? | | Next: 28.08. How to report by invoice category

28.01. How to re-set the mSupply client

Over time, the mSupply client may not function as expected. There are a variety of reason for this. Bad network connection to the server may have corrupted critical files during transfer. Unstable hardware may have shutdown un-gracefully or crashed damaging files. There may have been a virus issue.

Below is an image of one of many symptoms that the user may notice.

msupply_client_strange_icon.jpg

Corrupted client configuration files

As part of the installation, a batch file with the name Reset client temp folder is installed on the desktop. This file can do all the resetting described below. So, if it is still on the desktop, or you know where it was moved to, we recommend you double-click on that file to run it. You will be asked to confirm you want to continue; you should press Y on the keyboard if the client application is closed down - if it isn't closed down, close it and then press Y. The file will then carry out all the steps described below and reset the client for you.

mSupply client generates and stores it's configuration in files and folders. Theses files are safe to delete as they will be re-created by the mSupply client when it is started.

So let's assume that one of the files have been corrupted and that we need to delete them.

Procedure

  1. Make sure the mSupply Client is not running. If it is running, quit out of it.
  2. On windows : Navigate to c:\Users\SomeUser\AppData\Local, Then delete the “mSupply” folder. Note: SomeUser will be the Windows account name. In the example here, the Windows account name is Sussol.
  3. Please note that the “AppData” folder may be hidden, so enable your file explorer to view hidden files / folders.
  4. Navigate to the “Roaming” section in : c:\Users\SomeUser\AppData\Roaming and delete the following folders :
    • 4D
    • mSupply
  5. Finally Restart the mSupply Client.



Previous: 28. Frequently Asked Questions | | Next: 28.02. Remote support - installing TeamViewer

28.04. How to remove stock lines that have ‘0’ available

Occasionally users will come across stock lines in mSupply that cannot be removed easily. It almost like you have stock but you cannot carry our stock take or inventory adjustment to reduce the stock level to zero.

Below are two examples :

Above we have Paracetamol 500mg where for the highlighted batch ( red square ) we have a total of 100 but available is 0. This means that 100 in stock but all of this has be reserved for a customer.

Below is another example :

For Amoxycillin 250mg we have 92 in total and 42 available. This means that we have 92 - 42 = 50 reserved for customers.

Handling reserved stock

Customer invoices that are of status “nw” or “sg” will end up reserving stock. This theoretically means that you have the stock but it cannot be used as it has been reserved by the invoices.

You as a manager will be required to view the “nw” and “sg” invoices and decide if they are still valid or not. If the invoices are valid then you should “confirm” them if not they can be deleted.

So search for customer or prescription that are of “nw” status. Follow the image below. Do customer > Show invoices… or patient > Show Prescriptions…

Search for “Status” equal to “nw” as above. If the “nw” invoices exist, then you will be shown a list. Double click to review. Delete if the invoice is not valid otherwise “Confirm”.

“nw” invoices will exist in the database if you have suffered un-expected hardware or network communication failure.

Now repeat similar for “sg” type invoices :

“sg” invoices are part of the warehouse functions. You may have simply forgotten about these invoice or the customer lost interest in the order.

Your search for “nw” or “sg” invoice may result is the list below.

Note the highlighted “Status” column

Your job is now to review each invoice and to either “confirm” them or to delete them. Theses invoices may no longer be valid, you have to decide on this.

Confirming an invoice

To confirm a customer invoice, open it and click on the Confirm button:

Note the status detail. This will show cn when the invoice is confirmed, not nw or sg. The Confirm button will not be shown if the invoice is already confirmed.

For prescriptions, you won't see the Confirm button because they are automatically confirmed when you close them by clicking on the OK button.

The result

Once all the “sg” and “nw” invoices are processed, then your stock figures will update and they shouldn't be any stock that has been held as reserve.

Below the images should speak for themselves - the Total packs matches the Available packs. Please compare the image below with the ones above at the start of this topic.

Paracetamol 500mg:

Amoxycillin 250mg:



Previous: 28.03. Why is my stock balance report showing negative? | | Next: 28.05. What do I need to set up mSupply Mobile?

28.08. How to report by invoice category

Within mSupply if you have categorised invoices (or transactions) in a particular manner then you will be able to run reports based on this category. In dispensary mode Prescriptions can also be categorised. For example you may be required to tag your customer invoices as “Government” or “Private” facilities.

Follow these steps to generate a report by invoice category :-

  • Make sure there is at least one transaction category available in your data file. If not, then follow the instructions at 26.06. Transaction categories to create a transaction category.

For this example the image above shows the addition of two categories for customer invoices.

  • On your Invoices window, all of your categories will be displayed under the “Category” drop-down list.

invoice_choosing_category.jpg

  • Choose the category from the list and click on the OK button. For reporting purposes, the invoice will need to be confirmed.
  • For reporting, from mSupply menu or Navigator , View Report → Transactions.

report_by_transaction_filter.jpg

  • On the right hand side of that window, you will see the section “Transaction filter”. Here we have chosen to search for “Code” contains “govern”, which produces the same results as searching for “Code” equals “Government”.
  • Click on the OK button and you will now have the opportunity to view items issued to government facilities.

report_by_transaction_category_preview.jpg



Previous: 28.07. How to correct wrong pack sizes | | Next: 28.09. Imprest work flow

28.09. Imprest work flow

Version : v3.11 or v3.12 or later

The imprest module allows a pharmacy or warehouse to decide on quantities of drugs its receiver facilities (customers or Virtual stores) should receive. Periodically a stock take is carried out at the customer's site and drugs are replenished to meet the predefined (imprest) level.

The tutorial below suggest how an imprest should now be carried out.

We will assume that the facility or customer has been assigned with a suitable imprest list. If this is not the case then please do the following:

Create an imprest

Click on ‘Requisitions’ in the ‘Customer’ (or Patients) tab.. Click on the New customer imprest icon in he window which appears.

Type the first few few characters of the customer name in the Name field and press tab. A List of matching customers is displayed (unless only one customer name matches what you entered). Choose the intended customer and click the Use button.

At this point the master list of items associated with the customer is displayed in its default sort order.

The image below shows an example of what you now see: a list of items with their required imprest quantities. The next task is to print the list and carry out a physical stock take at the customer site.

First of all, make sure the list is in the correct order. If it is, fine. If not, re-order it as appropriate (by clicking on the column headers or dragging items up or down the list) and click on the Save Sort Order button.

Now print the list by clicking on the Print button and selecting the “Customer stock takes” option.

The print dialogue opens. Here you can add header and footer information for your printouts. Press OK when ready and print the list.

Please note that after printing the list you should not re-order it - it will be confusing later when you come to enter the counted quantities for each item.

Now, using the printout, carry out the actual stock take.

Updating the stock quantities

After carrying out actual stock take at the customer's site it's time to enter the actual stock quantities. In the window displayed below, edit the value in the Customer current stock on hand column with the stock take quantities you've written on the print out for each item.

mSupply automatically completes other two columns (Our suggested quantity and Actual quantity given).

Imprest formula:

  • Our suggested quantity = Maximum of
    • 0, and
    • Imprest quantity - Customer current stock on hand

Assigning stock

Once the updating of stock quantities is done and you are satisfied, you can click the Create customer invoice button to assign stock to the customer. Clicking the button will open the following window:

All the entries appear in red - they are placeholder lines which have the correct quantity but have no batch chosen (notice 'none' in the batch column for each line). You have to double-click each line in turn and select which batches you wish to assign to the customer.

As an example, you will see the window below when you double click an item line:

Normally you would click on the Re-distribute all button to have mSupply make the appropriate selection for you (it chooses batches with shortest expiry first). Having done that, the window now appears like this:

Clicking on OK & Next displays the next item on the invoice. When the final item has been processed, clicking on OK or OK & Next will display the complete invoice (all red lines replaced with black lines with the chosen batch displayed). The image below shows the invoice part way through this process:

When you've selected batches for every line, make sure the Hold checkbox is not checked then confirm the invoice to assign the stock to the customer. Now all you have to do is print off the pick list, physically pick the stock off the shelves and send it to the customer. Congratulations - job done!



Previous: 28.08. How to report by invoice category | | Next: 28.10. Tips and tricks

28.13. Fixing incorrectly received stock

The problem

Sometimes goods receiving officers will accidentally receive stock incorrectly in any of a number of ways including:

  • Too little stock was recorded as received
  • Too much stock was recorded as received
  • Stock of an incorrect item was recorded as received
  • The stock was recorded as received from the incorrect supplier
  • The stock was recorded as received from the correct supplier, but with the incorrect price. This can include receiving the stock from the correct supplier, but off the wrong PO.

These can all be corrected.

The methods described here will clearly identify the original error. If these methods are not followed, then a stocktake will correct the stock count, but will not help to identify the source of the original error.

Any user activity affecting stock needs to have records that management or an auditor can inspect. As with paper records, it is not appropriate to edit historic records. Instead, additional records are entered to correct historic mistakes. Management and auditors will then be able to see records of the original mistake and the corrective actions. To assist with this, clear details of what is happening should be recorded in the Comments field of the 'correcting' transactions.

GR+SI receipts
  • Stock received on the basis of a purchase order should come in to stock through a Goods Receipt which will be processed into a Supplier Invoice. For the remainder of this discussion, these transactions will be referred to as 'GR+SI receipts'.
SI only receipts
  • Stock that is not being received on the basis of a purchase order will not have a Goods Receipt and should have come in to stock through a Supplier Invoice directly. For the remainder of this discussion, these transactions will be referred to as 'SI only receipts'.

Too little stock was recorded as received

If too little stock was recorded as having been received, this can be corrected by receiving more of the same stock.

GR+SI receipts
  1. Create a new Goods Receipt for the additional stock. Enter necessary details in the Comment field, e.g. Receipt of additional stock not recorded as received on GR #### where #### is the number of the GR which had the incorrect record.
  2. Process the resulting Supplier Invoice. Again, enter necessary details in the Comment field, e.g. Receipt of additional stock not recorded as received on SI #### where #### is the number of the SI which had the incorrect record.
SI only receipts
  1. Create a new Supplier Invoice. Enter necessary details in the Comment field, e.g. Receipt of additional stock not recorded as received on SI #### where #### is the number of the SI which had the incorrect record.

Too much stock was recorded as received

If too much stock was recorded as having been received, this can be corrected by creating a Supplier credit to return the goods to the supplier. While your store never actually received this stock, this transaction will correct your stock count and the Comment field will explain why this transaction has been created.

GR+SI receipts
  1. Create a new Supplier credit for the excess stock. Enter necessary details in the Comment field, e.g. Return of additional stock recorded as received on GR #### and SI ++++ where #### and ++++ are the numbers of the GR and SI which had the incorrect record.
SI only receipts
  1. Create a new Supplier credit for the excess stock. Enter necessary details in the Comment field, e.g. Return of additional stock recorded as received on SI #### where #### is the number of the SI which had the incorrect record.

Stock of an incorrect item was recorded as received

If stock of an incorrect item was recorded as received, then we have two carry out both of the following actions. It doesn't actually matter which order you do these in:

  1. Return the incorrectly received stock by following the actions to be taken if Too much stock was recorded as received
  2. Receive the stock that was actually delivered by following the actions to be taken if Too little stock was recorded as received

The stock was recorded as received from the incorrect supplier

If the stock was incorrectly recorded as coming from the incorrect supplier, then you will need to return all of the stock to the incorrect supplier, and then receive it all from the correct supplier. It doesn't actually matter which order you do these in:

  1. Return the incorrectly received stock by following the actions to be taken if Too much stock was recorded as received. In this situation, it is highly recommended to Create a supplier credit from a finalised supplier invoice, including all of the stock on all of the stock lines.
  2. Receive the stock that was actually delivered by following the actions to be taken if Too little stock was recorded as received

The stock was recorded as received with the incorrect price

Stock can be received from the correct supplier, but with the incorrect price. Possible reasons for this include:

  • The price in the original PO is 'wrong'
  • There is more than one PO containing the item for the supplier, and the wrong PO (with a different price) was selected when receiving the goods.

If stock of an item was recorded as received, but with the incorrect price, do the following:

GR+SI receipts

When a purchase order (PO) is used in the procurement process, then the price is set by the PO. If the PO price was 'wrong', then the corrective actions should be governed by organisational policies and procedures. If your organisation and the supplier have agreed that the price was wrong, and needs to be changed, then there are two approaches, an auditor recommended approach and a method that is not recommended by auditors.

Be sure that whatever method is used complies with your organisations procurement policies

The Auditor recommended method: Cancel those lines on the PO and create a new PO

  1. Return the affected items on the current SI (refer to Too much stock was recorded as received above)
  2. Create a new PO for the affected items with the correct price
  3. Receive the corrected stock as normal.

There is another method that is not normally acceptable to auditors as it involves amending historic transactions rather than creating new transactions to correct the mistakes in historic transactions. It is included here only because some mSupply using customers choose this method and request assistance with it. This method involves amending the historic PO and SI:

  1. Amend the prices on the historic PO - refer Editing purchase order lines
  2. Amend the prices on the SI - refer Editing lines on a supplier invoice
SI only receipts

Even if a purchase order (PO) was not used in the procurement process and the price on the original paper supplier invoice turns out to be 'wrong', then the corrective actions should be governed by organisational policies and procedures. If your organisation and the supplier have agreed that the price was wrong, and needs to be changed, then, as above, there are two approaches, an auditor recommended approach and a method that is not recommended by auditors.

The Auditor recommended method: Return the incorrectly priced lines on the SI and create a new SI

  1. Return the affected items on the current SI (refer to Too much stock was recorded as received above)
  2. Receive the corrected stock on a new SI as normal.

There is another method that is not normally acceptable to auditors as it involves amending historic transactions rather than creating new transactions to correct the mistakes in historic transactions. It is included here only because some mSupply using customers choose this method and request assistance with it. It involves amending the historic SI:

  1. Amend the prices on the SI - refer Editing lines on a supplier invoice



Previous: 28.12. How to access Temp folder | | Next: 29. Synchronisation

28.02. Remote support - installing TeamViewer

Over the years we have used a number of applications for providing remote support to clients. As of writing this (January 2020) TeamViewer is the software that we use.

Please use the download link below, this is customised for interaction with Sustainable Solutions to allow us to best provide you with remote mSupply support.

Installing the TeamViewer Host customised for mSupply

1. Uninstall - if TeamViewer is already installed on the machine, it is safest to uninstall it.

2. Change the Computer Name to something meaningful before installing TeamViewer. Using a name that reflects the site and / or user would be helpful. e.g. Auckland - Grafton Pharmacy - this is what the machine will show up as on our international directory.

The TeamViewer Host module appears to only use the first 15 characters of the name. If you are connecting several computers, make sure that the first 15 characters are unique for each computer.

3. To change the computer name in Windows go to: Control Panel > System and Security > System > Advanced system settings > Computer Name > Change…

4. Note that the Computer description is NOT the Computer Name

5. Download and save the zip file at the following link https://www.msupply.org.nz/files/Teamviewer/TeamViewer%20Deployment%20September%202024.zip

6. Extract the files from the Teamviewer Deployment March 2024.zip file onto the host computer.

7. Open the folder you extracted

8. Run as administrator - right click on the file Install TeamViewer.bat and select Run as administrator. The script will check to see if it is running as an Administrator, if it isn't running as an Administrator, the installation will stop.
The Teamviewer Customised Host window should appear on your screen:

If the above window does not appear, the full installation has not completed. It definitely helps to run the batch (Install TeamViewer.bat) file with a reasonable internet connection. If the internet connection is not good enough, then some or all of the actions in the batch file will not be complete. If that happens, please uninstall TeamViewer and re-run the batch file (as Admin) when the internet connection is better.

9. Notify mSupply Support When you see this TeamViewer Host window, send us a message or email (on support@msupply.org.nz) and give us the computer name that you gave the machine in step 4 above. Otherwise, the TeamViewer ID should also work (a screenshot is fine). We will then be able to confirm for you that the remote access is operational and ready for us to provide you remote support.

It is recommended to use Google Chrome as browser if you use teamviewer on web. It supports “WebClient” connection more than other browser

The problem

Cursor on mSupply changed from arrow to window and user can't click anything resulting in inactive windows/form.

Active window

  • They may have active window that has been pushed behind the current shown window.
  • They may have minimised the active window unknowingly.

There may be an alert window that has been pushed back by the user clicking the inactive window.

Fixes

  • Drag the Top most window to the side and check if there is another active window or an alert behind it.

OR

  • Hit the “Enter” key and mSupply should bring the active window to the front.

28.10. Tips and tricks

mSupply Client: Connecting to a different server

It is unusual, but you may be in a situation where your mSupply client application needs to switch between more than one mSupply Server.

Launch the mSupply client application by double-clicking on the mSupply client icon, then immediately hold down the Alt key until the mSupply Server connection dialog box appears:

If you tick the Display this dialog at next startup tick-box, this dialog box will automatically be displayed on startup of the mSupply client application, and you will not need to do the double-click, Alt routine described above.

There are three ways of selecting the mSupply server to connect to. These are accessed via the tabs: Recent, Available and Custom:

Recent tab

The Recent tab retains a list of all mSupply servers recently used. The list is sorted by alphabetical order. To connect to a server from this list, double-click on its name or select it and click the OK button.

Available tab

The mSupply Server includes a built-in TCP/IP broadcasting system that publishes by default the name of the mSupply Server databases available over the network. These names are listed on the Available tab of the connection dialog box.

This list is sorted by order of appearance and is updated dynamically. To connect to a server from this list, double-click on its name or select it and click the OK button.

Computer networks can be configured to stop dynamic publication of the database name on the network. In this case, you will need to manually configure the the connection on the Custom tab.

Custom tab

The Custom tab allows assigning a published server on the network using its IP address and database name.

Database name: allows defining the name of the mSupply Server database.

Network address: allows entering the IP address of the machine where the mSupply Server was launched. If two servers are operating simultaneously on the same machine, the IP address must be followed a colon and port number, for example: 192.168.92.104:19814.

By default, the publishing port of a mSupply Server is 19813. This number can be modified in the Database Settings… under Client-server tab of mSupply server.

If a database was selected in the Recent or Available tabs when you clicked on the Custom tab, these two fields display the corresponding information from that tab.

Once the server details have been entered, clicking the OK button will connect you to the server.

If you tick the Force the update of the local resources tick-box, it allows you systematic updating of the local resources on the client machine when it connects. As a rule, updating of the local resources is automatic on the remote machine each time it connects, when the structure of the database has been modified between two connections. Most of the time, this option is unnecessary. Nevertheless, in certain specific cases, it may be necessary to force the update.

Emptying out a store and starting again...

Sometimes, the actual stock situation in a store becomes so out of step with mSupply's records that you want to start again from scratch with a brand new stocktake.

Be warned: Following the procedure below will result in the stock lines losing all Cost price data. Cost price data can be added back to the stock lines, but that is ordinarily a slow process that will not necessarily get back the correct Cost prices. But, you are only doing this because the mSupply record is so desperately inaccurate anyway… :-/

To do this, you will need to:

  1. Confirm or delete all customer invoices with status = nw (New) or sg (Suggested). This should remove from stock all lines that have been made unavailable, but are still showing as in stock - see figure below.
    1. Click on Customer
    2. Click on Show Customer Invoices
    3. Click on By Status
    4. Click on All new and suggested
    5. Double-click on the first displayed invoice
    6. Click on Confirm (or, if you want to delete the CI, delete each of the lines, and then Click on Delete)
    7. Click on OK & Next
    8. Repeat steps f & g until all invoices are confirmed (or deleted).Confirming all invoices with status nw and cn
  2. Empty the mSupply store of all stock by means of an Inventory Adjustment based on an mSupply stocktake of all stock in the store
    1. Create the stocktake - see figure below.
      1. Click on Item
      2. Click on Stocktakes
      3. Click on New stocktake
      4. Click OK (accept default filter values which includes all stock)Create new stocktake of all stock
    2. Set all actual quantities to zero (0) - see figure below.
      1. Click once on the first stock line. The whole line will become highlighted.
      2. Click once on the value in the 'Enter Quantity' column. The Enter Quantity value will become highlighted
      3. Type 0, then press Tab Tab. Repeat this for each line of the whole stocktake. You should be able to be faster than 2 stock lines per second, maybe a lot faster. At 2 stock lines per second, you can get through 1000 stock lines in less than 10 minutes…
    3. Click on Create Inventory adjustments If you've got a lot of stock lines, this could take a while…Setting all quantities to zero (0)
  3. Import new stock as described in Importing items & stock

Creating customers that are not visible to all the stores

In a multi-store system, you will often be wanting to create new customers that are visible in only one store. By default, when new customers are created, they will be made visible to all stores in the system. If you actually want these new customers to be visible to only one store, you will need to edit the store visibility for that customer, and un-tick the visibility for all the other stores - a tedious exercise in a system with scores or hundreds of stores!

For this reason, there is a solution: There is a store preference called Names created in this store not visible in other stores. To use it:

  1. Edit the store preferences for the store that needs to be able to see the new customers and turn on the Names created in this store not visible in other stores store preference.
  2. Make sure that you have user permission to create customers in this store.
  3. Log in to the store
  4. Create the new customers

    … or import the customers - refer Importing Names

Changing an item's name and pack size

There may come a time when you decide that you need to change the name and pack size of an item.

For example, Malaria RDTs (Rapid Diagnostic Tests) are commonly packed in packets with 25 tests in each pack. The packs can not really be broken down further in the supply chain, and it will only be opened at the last mile service delivery point. Therefore you made a decision to define this item as:

Rapid Diagnostic Test (RDT) for Malaria, Pack/25 with a default pack size of 1.

This works fine until your Malaria Programme team have advised you that they prefer to count the individual test in such a way that it matches the number of patients that need to be tested. If they need enough tests for 750 people, they want to order 750 of this item, not 30 (750/25). Therefore, you decide that you need to change the name and pack size of this item to:

Rapid Diagnostic Test (RDT) for Malaria with a default pack size of 25.

  • Changing the Item name and pack size is the easy bit. The challenge is that all existing stocks need to be recounted with resulting inventory adjustments.
  • If your system is of any substantial size, you will want to consult with stakeholders to plan a smooth transition.
  • After a change such as this, all historic issuance / AMC records will be 'incorrect'. In the case above, they will be 25 time less than future issuance AMC records
Changing the item

If the item is currently described as:

… with a pack size of 1.

In this example, the Item code = 732401. The code is often an easier way to select the item.

Edit the item (you will need user permissions to do this) to:

On the Storage tab, replace the Preferred pack size of 1 with 25

Click OK

Carry out stock takes and inventory adjustments

Create a New stock take for Item code starts with 732401:

This reveals that there are 58 packs in the store with pack size = 1:

To correct this, we need to:

  1. Add a New line
  2. 732401 <Tab>
  3. Select the line of the existing stock line (see that the Stock on hand = 58)
  4. Click on the button to use details of this existing stock line
  5. Set stock take qty = 58
  6. Set Pack size = 25
  7. Set Stock stock location to the same as the existing stock line
  8. Click Add new

With the resulting stock take:

  1. We give the stock take a useful title
  2. We update the Enter Quantity details of the the original stock line to 0
  3. Carry out a stock count to ensure that the stock on the shelves matches the newly added line and make any necessary adjustments in the Enter Quantity column.
  4. Click the Create Inventory adjustments button to finalise the stock take.



Previous: 28.09. Imprest work flow | | Next: 28.11. Benefits of a multi-store system

28.15. Wastage Prediction due to expiry when ordering

The problem

Prior to mSupply v7.12, when ordering or reporting on suggested ordering, you could simply tell mSupply to ignore stock that was going to expiry in three or four months time. mSupply would then lower it's stock level and order according to usages.

So previously if you asked mSupply to ignore stock that is likely to expire within the next six months while ordering or reporting, then mSupply would simply reduce the Stock on hand of the items by taking out the six months expiring stock as un-usable and then created a order based on the reduce stock. This is highly inaccurate as mSupply just removes the six months expiring stock instead of trying to workout if the stock can be dispensed in a timely manner.

Due to popular demand with mSupply v7.12 we have tried to do a better job of predicting stock wastage due to expiry. Using the consumption data that we have, we have travelled into the future and worked out the likely wastage stock. This page describes the workflow.

Suggested Order reports

Lets look at a report in mSupply v7.12 or later.

From mSupply activate the menu :

  • Report > Purchasing > Suggested Order quantities…

The Suggested ordering report now has a new/updated expiry filter checkbox : Exclude stock that will expire within 3 months of projected consumption date

This checkbox accurately takes into account the likelihood of current stock expiring in the future based on the monthly calculated consumption for an item while determining the suggested order quantities. Previously you could tell mSupply to ignore stock that was close to expiry by say 3 or 6 months when calculating quantities, however this is approximate.

With mSupply version v7.12, mSupply has the option to accurately analyse the stock quantities that can’t be distributed due the consumption rate and the expiry date of the stock. This results in a more accurate estimate of the suggested order quantities.

The workflow :

Imagine we have the following batches for an item.

Item Batch Stock Expiry
Amoxycillin/ Clavulanic acid 30mgb12-202350012/2023
Amoxycillin/ Clavulanic acid 30mgb06-202455006/2024
Amoxycillin/ Clavulanic acid 30mgb06-202510006/2025
  • Imagine the current date is 1/1/2024
  • Imagine the AMC is 50
  • Imagine you need stock for 12 months.
  • When running the report this is checked : Exclude stock that will expire within 3 months of projected consumption date

When the above report is run, mSupply will immediately ignore the batch `b12-2023` as it has already expired as the current date is `1/1/2024`.

For batch `b06-2024` : mSupply works out that you can only dispense this batch till the end of March 2024, due to the set 3 months cutt-off date for expiry. So the months that this stock can be dispensed are :

  • January 2024
  • February 2024
  • March 2024

So the stock that can be used from batch `b06-2024` is : 3 * 50 = 150. ( In the reports that you will see in the future, this is known as effective stock) So the wasted quantity for batch `b06-2024` is : 550 - 150 = 400 (This is expiring stock, 400 will need to be thrown away. In the reports that you will see in the future, this is shown as Expiring stock )

For batch `b06-2025` : So from April 2024, mSupply will need to start using this batch for distribution. So this is 9 months remaining from April 2024 - to December 2024. However with a stock of just `100` this item will be used up during the following two months :

  • April 2024
  • May 2024

So for batch `b06-2025` all the stock will be used up and they will be no wastage.

However we now have 7 months starting from June 2024 till the end of December 2024 where we don’t have any stock, so mSupply will suggest a immediate order of : 7 * 50 =350 to cope with the 12 months starting from `1/1/2024`

mSupply has effectively time travelled into the future to work out the Effective Stock on hand (SOH) and the order will be carried out based on this and not the current stock on hand.

New Columns on Suggested order reports and changes

Now the suggested ordering reports will have two new column :

  • Effective SOH (Stock on Hand) : From above this is the stock quantities that can be used before they expire.
  • Expiring stock : This is the stock quantity that can’t be used due to predicted expiry and cut-off date.

The `Effective Month of Stock` is now calculated from the `Effective SOH` and not from the `Stock on Hand`. The `Suggested order` is now calculated from the `Effective SOH` and the `Effective Month of Stock`.

Generating a Purchase order and Tender

The same logic is now applied when generating a purchase order or a tender. Like with the reports, we can ask mSupply to calculate potential stock wastage and order an appropriate quantity.

28.05. What do I need to set up mSupply Mobile?

Information required

  • The new mSupply Mobile store needs to be set up in mSupply desktop. The Sustainable Solutions team can help you with this, but some information is needed:
    • Store Name e.g. Mobile Clinic HC
    • Store Code e.g. mobilehc
    • Sync Site Name This is a Sync Site associated with the Store Name, and is usually the same as the Store Name, e.g. Mobile Clinic HC
    • Item Master list for items to be visible in the mobile store, e.g. TB Clinic Items
    • A list of Stores and Customers to be visible in the new mobile store.
    • A list of Stores where the new mobile Store will be visible.
    • A list of 'transfer' Stores. These are stores that current mobile store can order/send stock. This should be the same list as the list of Stores where the new mobile Store will be visible.
  • A few things that can be done by a user:
    • Create the User Name (and Password) in mSupply desktop for the Responsible Officer that will log in into the new mSupply mobile store on the tablet - refer Managing users.

The Sync Site Name, User Name and Password will need to be entered when logging in to mSupply Mobile on the tablet. It's advised to consider making them easy enough to enter via touchscreen keyboard (short, no caps, limited 'funny' characters… ;-) )!

Configuration in mSupply

To enable the additional options in mobile such as Dispensary, Cash Register and Dashboard ( bottom right of main page, below ) you will need to enable some options in mSupply admin.

Dispensary

This is controlled by the store mode, which is found on the first page when editing a Store:

Cash Register & Dashboard

For these, click on the Preferences tab when editing a store. Enable the options mobile: Uses Dashboard Module and mobile: Uses Cash Register Module as highlighted below:

Installation of mSupply Mobile APK and initiation

  • Download the mSupply Mobile .APK file to your tablet from the link provided by Sustainable Solutions. Check with Sustainable Solutions for the download link. Depending on your mSupply server version, you may require specific version of mSupply Mobile.
  • Once the download is completed and the app starts, it will ask for:
    • Primary Server URL, which will look something like https://msupply.demo.org:2048. This will be advised to you by Sustainable Solutions.
    • Sync Site Name, e.g. Mobile Clinic HC (as provided above) .
    • Sync Site Password. This will be provided by the Sustainable Solutions team once the store has been configured in mSupply).

  • Now the initial sync will start.

The initial sync could take quite some time. Please ensure that the internet connection is stable, and be patient. If the initial sync has been interrupted, you will need to restart the app and re-enter the above information.

User login

After the initial sync is complete, another page will open asking you to login as a user:

  • User Name, as created in mSupply desktop, above
  • Password

  • An existing store can be be turned into an mSupply mobile store
  • An existing customer (that is NOT a store in mSupply) can also be turned in to an mSupply mobile store. However, this requires that all Customer Invoices for the customer are finalised.
  • To help Sustainable Solutions set up multiple stores at once, please use the attached excel template, filling out ALL information.

msupply_mobile_setup_template.xlsx



Previous: 28.04. How to remove stock lines that have ‘0’ available | | Next: 28.06. Why is my stock on hold?

28.03. Why is my stock balance report showing negative?

Occasionally mSupply will show negative stock balances when running reports to view stock levels at a past date. This may look to be wrong but in many cases this is mathematically correct.

The two primary reasons for the cause in negative stock values are :

  • You may have entered backdated customer invoices using the current available stock. Here you would have created a customer invoice, but modified the confirmed invoice date to reflect past transaction.
  • You issued backdated placeholder lines on confirmed invoices using the current available stock. Initially when you created a customer invoice, you had no stock but had to resort to placeholder lines. After receiving stock, you re-open the old confirmed customer invoice to issue the placeholder lines with recently available stock.

In both the cases if you were to report on stock level at a certain point ( the date before you receive supplies), then you may get negative stock values. mSupply to calculate stock level at a certain date needs to work back from current stock level. So if your data shows that you have issued stock that you haven't technically received due to the order of the confirmed date, then you are likely to see Negative stock balance.

The image below shows a ledger for a single batch that was received in 16/2/2016, but between 04/09/2015 to 27/10/2015, the stock has been issued inside three backdated invoices.



Previous: 28.02. Remote support - installing TeamViewer | | Next: 28.04. How to remove stock lines that have ‘0’ available

28.06. Why is my stock on hold?

There are a number of reasons why stock can be On hold. This stock will be included in any stocktakes, but cannot be issued by mSupply. Depending on the reason, there will be different actions required to issue the stock:



Previous: 28.05. What do I need to set up mSupply Mobile? | | Next: 28.07. How to correct wrong pack sizes
1) , 3)
Remote support - almost 24/7. We aim to provide a first response within 2 hrs
2) , 4)
Gives you access to the latest software updates, including assistance with upgrading if needed.
5)
only applicable for mSupply products that have a license fee
6)
Essential Drug List
7)
First Expiry, First Out
8)
Vaccine vial monitor
9)
International Classification of Diseases
10)
If you don't want to allow this, then simply turn the user preference off
11)
also known as “Cancel invoice” or “Cancel a transaction” or “Cancel an invoice”
  • Last modified: 2019/10/18 04:57
  • by lou