misc:test:start

This is an old revision of the document!

test - Section One 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
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:58
  • by lou