Design
Note: much of the information on this page is out of date and needs updating.
We use react native for all of our UI, following the patterns they prescribe in terms of object composition leading to a hierarchy (or dom) of components rendered on screen.
The aim is to keep the business logic out of the files containing rendered components. We instead keep it in other modules. Most of the rules around what happens given certain modifications to data are controlled by code within the classes wrapping database objects. For example, finalising an invoice involves the UI layer calling transaction.finalise(), and the specific instance of a Transaction database object is responsible for carrying out the cascading effects like locking the invoice for editing and making changes to inventory. Other business logic sits in the relevant module, most notably authentication and synchronisation.
We have a module for each distinct, encapsulated part of the app. Each has an index.js, containing exports for any of the classes or functions within the module that should be shared publicly outside of the module. This is a convention that Javascript sets out, and allows those classes/functions exported to be accessed simply by referring to the module name (directory name), e.g. import { formatStatus } from './utilities';
The index.js of each module is also the place to put contain named constants that are used throughout the app.
We don't have any checks to assert that things deep within a module are not accessed, so we as developers need to enforce that only classes/functions/constants that are publicly exposed through the index.js are used outside of the module.
Within each component (this includes pages), we have set up a convention that there is access to two different sets of styles, localStyles and globalStyles. We have been fairly loose (not a good thing) in how we have used the two, but a basic description of what we put in each follows.
Local styles is a stylesheet at the bottom of a particular javascript file which specifies styles for the component in the same file. We use this stylesheet to hold on to styles that are needed by that component whether it is in the mSupply Mobile app or another app, though it may refer to globalStyles to be more specific.
Global styles is a module (globalStyles) that contains exports for all the styling that is specific to the mSupply app as opposed to any other app. This includes colours, fonts, sizes, and specific layouts that may not be used by other apps.
The module is broken down into subfiles representing distinct parts of the app, e.g. buttonStyles, navigationStyles, etc. Anything that needs to be available to components should be exported in the index.js of the module.
This section describes the functional design of the interface. Some of the logical complexities are covered only briefly here, for more detail see the section above
Other than the root menu, each page in the app extends the generic page in the react-native-generic-table-page npm package (which is maintained by Sussol). Each page defines
- Its columns
- A function to return the data, given filtering and sorting details
- The data types that it should respond to changes for (e.g. if displaying a list of customer invoices and a new CI syncs in, the page should refresh to reflect the change and so respond to data of type 'Transaction')
- Optional functions to render particular components
- Modals, which open in response to certain buttons being pressed (e.g. edit comment)
- Page Info, which will be displayed at the top left of the page, above the data table
- The cells, if some cells need to render anything other than just the value as static text, extracted from the row's data using that column's key (e.g. are editable, checkable, etc.)
- Optionally, the render function for the page as a whole, if the layout diverges from the generic layout (e.g. has modals)
This is presented every time the app is opened from a closed state, or when a user presses logout. See user authentication for the business rules.
The menu is like the 'home page' of the app, with buttons to each of the main sections.
Interface Features
- Links to subpages are grouped in three columns, representing things related to Customers, to Suppliers, and to Stock.
- Pressing any of the buttons will take you to the relevant page
- There is a 'Logout' button on the bottom left corner - pressing this will log the current user out and bring up the login screen
Shows a list of customer invoices.
Columns
- Customer - The name of the customer the stock is being/was issued to
- Invoice Number - The unique serial number of each invoice (unique within the store only, not across all of an mSupply system)
- Status - Whether the customer invoice is 'Finalised' or 'In Progress' (any status other than finalised)
- Entered Date - Self explanatory
- Comment - Optional comment entered against the customer invoice
- Delete - Tap to select a given invoice for deletion. Can tap more than one to delete multiple invoices at one time. Disabled when the invoice is finalised. If one or more invoices are selected for deletion, a confirmation modal will appear at the bottom of the screen, with the option to confirm or cancel
Other Interface Features
- New Invoice Button - Pressing will bring up a dialog to search for and select a customer, see below
- Search Bar - Typing in here will filter the list of customer invoices on the name
- Tapping anywhere on a row (other than the delete column) will open the page for that customer invoice
Presents a list of customers to create the invoice for
Interface Features
- Can start typing in the search bar to filter the list of customers
- The cursor is automatically active in the search bar when the window opens
- Tapping on one of the customers in the list will create a new customer invoice with them as the recipient (at present, you actually need to tap twice: once anywhere to get the focus out of the search bar, and again on the customer's name to actually select them.)
Show details and allows editing of a customer invoice (unless it is finalised, when editing is disabled)
Columns
- Item Code - The code of the item
- Item Name - The name of the item
- Available Stock - The stock on hand that is available for issue, i.e. not already accounted for in other customer invoices. This is essentially the maximum quantity of each item that could be issued in this customer invoice.
- Quantity - The amount of stock being issued. Quantities in mSupply mobile are in individual items
- Remove - Tap to select a given item for deletion. Can tap more than one to delete multiple items at one time. If one or more items are selected for deletion, a confirmation modal will appear at the bottom of the screen, with the option to confirm or cancel
Other Interface Features
- Entry Date - Date the invoice was created
- Confirm Date - Generally the same as the entry date; for invoices created within mSupply mobile, we confirm them immediately so that they have an effect on inventory, making it easy to ensure that across all customer invoices, no more stock is issued than is available
- Entered By - The user logged in at the time the customer invoice was created
- Customer - The customer's name
- Their Ref - An editable text field that maps onto the their_ref field in mSupply. Usually used for entering the reference the customer might use on a physical record or similar. Tapping the field or 'edit pencil' next to it brings up a modal allowing the text to be changed
- Comment - An editable text field used for any purpose. Tapping the field or 'edit pencil' next to it brings up a modal allowing the text to be changed
- New Item Button - Brings up a modal allowing the user to select an item to add to the invoice, see add item. If the item selected is already in the invoice, it does nothing.
- Add Master List Items - Adds all items on the master lists attached to the customer this invoice is for. If any are in the invoice already, it doesn't add them again. It also does not delete any non-master list items already in the list
- Search Bar - Filters the list of items on the customer invoice by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t')
- Finalise - Pressing will bring up the finalise modal
Notes
- When a Customer Invoice is opened, we ensure it is either confirmed or finalised - if not we confirm it. This will only occur in rare cases when a new or suggested invoice syncs down from the central server. By confirming on opening, we enforce our policy to avoid over-issuing stock
Shows a list of all names that are visible in the mobile store and are customers
Columns
- Code - The name's code (generally unique)
- Name - The name's name
- Invoices - The number of customer invoices that have been or are intended to be issued to that customer
Other Interface Features
- Search Bar - Filters customer list on name
- Tapping any row will open the page for that customer
Details about the customer with a list of all their customer invoices
Columns
- ID - The unique serial number of the customer invoice (unique within the mobile store, not across a full mSupply installation)
- Status - Whether the customer invoice is 'Finalised' or 'In Progress' (any status other than finalised)
- Entered Date - The date the customer invoice was created
- Items - The number of item lines on the customer invoice
- Comment - An optional comment on the customer invoice
Other Interface Features
- Address - Address of the customer, if it has been entered
- Code - Code of the customer, generally unique
- New Invoice Button - Creates a new customer invoice for this customer, and takes you to the edit page
Shows a list of supplier invoices received by this store
Columns
- Invoice Number - The unique serial number of the supplier invoice (unique within the mobile store, not across a full mSupply installation)
- Status - Whether the supplier invoice is 'Finalised' or 'In Progress' (any status other than finalised)
- Entered Date - The date the supplier invoice was created
- Comment - An optional comment on the supplier invoice
Other Interface Features
- Search Bar - Filters the list of supplier invoices on the invoice number
Notes
- All supplier invoices currently come from a single supplying store set on the sync server, so we don't bother with a 'Supplier' column
- Entering supplier invoices manually is currently unsupported
Shows details and allows review and modification of a supplier invoice
Columns
- Item Code - The code of the item on that line
- Item Name - The name of the item on that line
- Number Sent - The quantity (in individual items) of the item that was recorded as being sent out on the supplier's end. Generally comes from the customer invoice made by the central supplying store, which automatically generates a supplier invoice when it is a stock transfer
- Number Received - The quantity of the item that arrived at the store. This is where the mSupply Mobile user is responsible for reviewing the stock that was delivered, and ensuring it matches the number in the sent column. If it doesn't, they can edit the number received so that their inventory is increased by the appropriate amount
Other Interface Features
- Entry Date - Date the invoice was created
- Confirm Date - Date the invoice is confirmed, which generally doesn't happen until the user presses 'finalise' (supplier invoices from stock transfers are created as 'suggested')
- Their Ref - A text field mapping on to transact.their_ref in mSupply. Most of the time will contain information about the customer invoice that is at the other end of the stock transfer that created this supplier invoice
- Comment - A text field with an optional comment. Generally says 'Stock transfer'
- Search Bar - Filters the list of items on the supplier invoice by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t')
- Finalise - Brings up the finalise window
Notes
- When a Supplier Invoice is opened, we ensure it is either new, suggested, or finalised - if it is 'confirmed', we finalise it. This will only occur in rare cases when a confirmed invoice syncs down from the central server. By finalising on opening, we enforce our policy to avoid 'confirmed' supplier invoices - if someone were to reduce the amount of stock on a confirmed supplier invoice, but it had already been issued in a customer invoice, we would have to deal with a tricky situation.
Shows a list of requisitions placed/to be placed by this store against the supplying store (as defined on the mSupply server)
Columns
- Requisition Number - The unique serial number of the requisition (unique within the mobile store, not across a full mSupply installation)
- Entered Date - The date the requisition was created
- Items - The number of item lines currently on the requisition
- Status - Whether the requisition is 'Finalised' or 'In Progress' (any status other than finalised)
- Delete - Tap to select a given requisition for deletion. Can tap more than one to delete multiple requisitions at one time. Disabled for any requisition that is finalised. If one or more requisitions are selected for deletion, a confirmation modal will appear at the bottom of the screen, with the option to confirm or cancel
Other Interface Features
- Search Bar - Filters the list on the requisition number
- New Requisition - Creates a new requisition and opens the edit page
Shows details and allows editing of a requisition (unless it is finalised, when editing is disabled)
Columns
- Code - The code of the item on that line
- Item Name - The name of the item on that line
- Current Stock - The stock on hand for that item, in individual items
- Monthly Use - The average monthly consumption of that item over the last three months, as determined by the dailyUsage multiplied by 30. Details described in the section on Item.dailyUsage logic
- Suggested Qty - The number of individual items mSupply Mobile thinks should be ordered in order to maintain stock availability for at least the period in the 'Months Stock' section. For details on how the suggested quantity is calculated, see the logic section
- Requested Qty - The amount of stock actually requested for that item
- Remove - Tap to select a given item for deletion. Can tap more than one to delete multiple items at one time. If one or more items are selected for deletion, a confirmation modal will appear at the bottom of the screen, with the option to confirm or cancel
Other Interface Features
- Entry Date - The date this requisition was created
- Entered By - The user who was logged in when the requisition was created
- Months Stock - Number of months of cover required in stock, used to calculate suggested quantities. Tapping on the number or drop down arrow will open a selector allowing the user to change the months stock to a number between 1 and 6
- Comment - Optional comment. Tapping on the underlined section or 'edit pencil' brings up a modal allowing the user to change the text
- Search Bar - Filters the list of items on the requisition by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t')
- Create Automatic Order - Generates an order with all items that would run out of stock in the period the requisition covers, with suggested quantities automatically in the requested column. More details in the logic section
- Use Suggested Quantities - Copies all of the values in the suggested quantity column to the requested quantity column
- New Item - Opens the new item modal to allow adding an item to the requisition
- Add Master List Items - Adds all items in this store's master lists to the requisition
- Finalise - Opens the finalise modal for this requisition
Shows a list of stock, with details about inventory levels etc
Columns
- Item Code - The code of the item
- Item Name - The name of the item
- Stock On Hand - The quantity of stock currently available in the store's inventory. This automatically updates whenever a stocktake is done, stock is received into the store (supplier invoice is finalised), or stock is issued (a customer invoice is created/edited). Note that it does not include stock that may be physically in the store room, but is either a) on a supplier invoice that has not yet been finalised, or b) on a customer invoice and so allocated to be issued
Other Interface Features
- Search Bar - Filters the list of items on the requisition by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t')
- Tapping any row will expand the row to reveal extra details about the item
- Category - The lowest level (most fine grained) category the item belongs to, if any
- Department - The lowest level (most fine grained) department the item belongs to, if any
- Number of batches - The number of batches of this item are currently in stock
- Earliest expiry - The date the batch with the earliest expiry date should be used by (note, it may be in the past if there is expired stock in the store)
Shows a list of all stocktakes that are being done/have been done in this store
Columns
- Name - The name given to the stocktake
- Created Date - The date the stocktake was created in mSupply Mobile
- Status - Whether the stocktake is 'Finalised' or 'In Progress' (any status other than finalised)
- Delete - Tap to select a given stocktake for deletion. Can tap more than one to delete multiple stocktakes at one time. Disabled for any stocktake that is finalised. If one or more stocktakes are selected for deletion, a confirmation modal will appear at the bottom of the screen, with the option to confirm or cancel
Other Interface Features
- Current/Past Toggle - Selecting Current shows all 'In Progress' stocktakes in the table and filters out all that are 'Finalised', while selecting 'Past' does the opposite
- New Stocktake - Opens the new stocktake page (does not actually create a new stocktake at this point)
Used to edit the items in and title of a stocktake, either in the process of creating it or as a management tool during the stocktake
Columns
- Item Code - The code of the item
- Item Name - The name of the item
- Selected - Tapping will fill the checkbox in this column, and mark the item to be added to/retained in the stocktake. Tapping again will unfill the checkbox, and mark the item to be either not added or removed from the stocktake (depending on whether it is already in there). If one or more items are selected, a confirm modal will appear at the bottom of the page - see 'Other Interface Features' below
Other Interface Features
- Search Bar - Filters the list of items in the table by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t')
- Hide Stockouts - A toggle button. When toggled on, filters out any items that are currently out of stock from the list. If they were selected before the button was toggled on, they will remain selected. However, if All Items Selected is pressed when stockouts are hidden, they won't be selected
- All Items Selected - A toggle button that will select/deselect all the items currently visible in the table.
- If there is nothing typed in the search bar and 'Hide Stockouts' is off
- If there is one or more line that is not yet selected, it will appear 'off' (no colour fill), and tapping it will select all items in the store
- If all items are selected, it will appear 'on' (background filled with orange), and tapping it will deselect all items in the store
- If there is something typed in the search bar and/or 'Hide Stockouts' is on, i.e. the table is showing a subset of items in the store
- If there is one or more item in the subset that is not yet selected, it will appear 'off' (no colour fill), and tapping it will select all items in the subset, without affecting items that are not yet selected but filtered out of view
- If all items in the subset are selected, it will appear 'on' (background filled with orange), and tapping it will deselect all items in the subset, without affecting items that are selected but filtered out of view
- If there is nothing typed in the search bar and 'Hide Stockouts' is off
- Confirm Modal - A small modal will appear at the bottom of the page whenever at least one item is selected.
- It has an editable text field to edit the title of the Stocktake
- It has a button reading either 'Create' or 'Confirm', depending on whether or not the stocktake is brand new
- On a brand new stocktake, if the user does not enter any text in the title text field before pressing 'Create', it will be created with the title 'Stocktake [current date and time]'
- A brand new stocktake is only created at the point the user presses 'Create'. If a user navigates back out of the page before that, the stocktake will not exist
- Similarly, if the user navigates back out of the manage page of an existing stocktake without pressing 'Confirm', any changes will not be applied
- It will disappear if no items are selected, so you cannot have a stocktake with no items
Shows details and allows editing of a stocktake (unless it is finalised, when editing is disabled)
Columns
- Item Code - The code of the item
- Item Name - The name of the item
- Snapshot Quantity - The stock on hand of the item at the time the item was added to the stocktake (often at the point the stocktake was created). We take a snapshot on the basis that no stock is issued or received between the time the item is added to the stocktake and the time it is counted, but stock may be issued/received between the time it is counted and the time it is entered into mSupply Mobile. By taking a snapshot, we can use the difference between the snapshot and counted quantities and apply that to the current stock levels as an inventory adjustment
- Actual Quantity - The amount of stock counted actually counted in the store, in individual items
- Difference - Shows the positive or negative difference between the snapshot and actual quantities, indicating the inventory adjustment that will be made when the stocktake is finalised. This was added to clear up confusion for users about whether to enter the total quantity or the difference in the 'Actual Quantity' column
Other Interface Features
- Search Bar - Filters the list of items on the stocktake by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t')
- Manage Stocktake - Opens the stocktake manager for this stocktake, allowing the user to add or remove items from the stocktake, and edit the title
- Finalise - Opens the finalise modal for this requisition
Allows the user to search for and select an item to add to the invoice or requisition.
Columns
- Item Name - The full name of each item
- Stock on Hand - The amount of stock of each item that is currently in stock
Other Interface Features
- Search Bar - Filters the list of items in the list by item name or code (so typing 'ace' would include an item with the name 'Acetazolamide' and code 'dia250t' and an item with the name 'Diamox' and code 'ace250t'). The cursor is in the search bar by default when the modal opens.
- Close X - Tapping will close the selector without adding any items
- Tapping any row will add the item to the invoice or requisition. Note that if the cursor is in the search bar, the user will need to tap twice, once to unfocus from the search bar, and again to actually select the item
Notes
- Only one item can be added at a time through this selector - it might be nice to have a multiple item selection interface
A modal that controls finalising invoices/stocktakes/requisitions. Will start by checking if the record is ready to be finalised, and if not, show an error message with information on how to correct the problem. Otherwise it shows a message about the effects of finalising.
Interface Features
- If there is an error, i.e. the record is not ready to be finalised (for the logic, see 'Notes' below)
- Error Message - a custom message depending on the issue, with information to help the user fix it
- 'Got It' Button - pressing will dismiss the modal but not affect the record
- If there is no error, i.e. the record is ready to be finalised
- Message - a custom message with information on the effects of finalising that type of record
- Cancel Button - pressing will dismiss the modal but not affect the record
- Confirm Button - pressing will finalise the record, locking it for future editing. A loading spinner will appear while this is happening, and then the modal will be dismissed, revealing the locked record behind it
- Close X - Appears whether or not there is an error. Pressing will dismiss the modal but not affect the record
Notes
- Each type of record has different criteria to be ready for finalisation
- All Types - Need at least one item line
- Customer Invoices - Needs at least one item line with a number greater than 0 in the quantity to issue column
- Supplier Invoices - No criteria! As there isn't much a mobile user can do, they are created centrally
- Requisitions - Needs at least one item line with a number greater than 0 in the required quantity column
- Stocktakes - Needs to have at least one item line with a number in the counted quantity column, and for no item to be reduced by more than is in stock at the time of finalising (we don't want to send stock negative, this situation doesn't make sense!)
This is only displayed in admin mode and provides a way to look at the raw data stored in the realm database.
- Typing the name of a data type, e.g. 'Transaction', in the search bar will show all the data of that type in the table
- The table is dynamically built using the data returned to determine the columns. This means it won't always look nice as it may be overfilled with columns
- Any field that is a list will simply show the number of children, e.g. the Transaction.items column will show the number of items in each transaction, rather than any details about the actual items
- It does not provide editing abilities, i.e. you cannot change the data in the database through Realm Explorer
The first time the user opens the app (or any time the locally stored data is wiped, see changing sync details).
Interface Features
- Primary Server URL - An editable text field to enter the URL of the mSupply server that this tablet will sync with. This should include the https:// and the :port (unless the port is the standard HTTPS 443). Obviously all syncing should be done over HTTPS
- Sync Site Name - An editable text field to enter the name of the sync site that this app represents, as set up on the server in mSupply's 'Synchronise' preferences
- Sync Site Password - An editable text field to enter the password of the sync site that this app represents, as set up on the server in mSupply's 'Synchronise' preferences
- Sync Indicator - Shows the status of sync: during sync it is darkly coloured, if there is an error it becomes lighter grey
- Connect Button
- Is disabled until some text has been entered in all three fields
- Tapping begins the app's initialisation sync, getting all data required for that site
- Once sync is underway the connect button and all fields are disabled
- While syncing, the number of records remaining will be displayed inside the button as a progress indicator
- If there is an error (did not authenticate, server stopped responding, bad sync record, etc.), the error message will display in the 'Connect' button, ending with 'Tap to retry.' Tapping this button will resume the sync from the point it got to before the error occurred, so if it had already synced 1500 out of 2000 records, it won't have to sync them all again - just the 500 still to go.
Settings are kept in the realm database along with the rest of the data. However, they have a different interface to the database, so that a.) settings are easier to add, retrieve, and edit, and b.) we could swap out where they are kept but keep the interface if we wanted (encapsulation!) The repo (and npm package) that sussol maintains, react-native-database, provides this settings interface.
In the settings module's index.js, we keep all of the settings key constants in a javascript object. This is so you can import { SETTINGS_KEYS } from './settings'; and then access the specific key you need - basically provides a centralised point to maintain a consistent, unique set of settings keys that can be changed in one place and have the changes reflected everywhere. It's good practice to use named constants rather than repeating the string literal version of a key throughout a codebase.
We extend the react-native-database Settings class to connect it to our localization module. Whenever an interface consumer (user of the Settings class) sets the CURRENT_LANGUAGE, it will ensure the localization module updates the current language. It also ensures the localization module is informed of the current language when the app first starts.
Localization works by providing the strings that will be rendered throughout the app as they are needed, in the language currently set by the user. Currently the only options are English (default) and Tetum. We use the external npm package react-native-localization to deal with actually selecting the right strings, given a set to choose from and having set a current language key.
Adding support for a new language is easy, just add it to languageKeys in the localization index.js, and a matching entry in each of the other files in the module (as well as adding the option to the LanguageModal).
The widgets module is a collection of odds and sods, all of them UI components that are self contained, not specific to a particular page, and can be reused. A few examples: PageButton, SyncState, ToggleBar, and the various Modals (ConfirmModal, FinaliseModal, etc.)
If any are needed for other projects, they can easily have their last dependencies (usually on globalStyles) broken, and be pulled out into their own repo with an associated npm package.
Here is a list of things that people may expect to work in mSupply Mobile, but at this stage are unsupported:
If one mobile site makes a customer invoice for another mobile site, the stock will not be automatically transferred. Instead, the stock will go out of the supplying site, but no supplier invoice will be generated for the receiving site. For this reason, anyone setting up mobile must be careful not to make names that are attached to stores visible in a mobile site - this makes it too easy for them to create a customer invoice without the appropriate supplier invoice showing up on the other side. A good solution to this problem would be to have the sync server respond centrally, by detecting customer invoices created by mobile that have a store as the recipient, and generating a supplier invoice at that point.
Requisitions created in the mSupply Mobile app are all directed to the supplying store, as set up in the preferences on the sync server. Mobile users cannot make requisitions for any other store.
Even if a requisition is made against a mobile store using a desktop computer, it could not be accessed in mobile. We have no UI or process for a mobile site taking the role of a supplying store, and receiving and responding to requisitions.
Supplier invoices show up in mobile as if by magic. They are all generated centrally by the server or someone on a desktop, and almost always as the result of a stock transfer to that store. Mobile users cannot enter supplier invoices manually - the workaround is to create a new stocktake and add the appropriate amount of incoming items to the current stock count.
Every quantity visible to an mSupply mobile user is in individual items, meaning individual tablets, vials, and some exceptional cases like boxes of gloves. If you must think of pack sizes, consider that every batch has a pack size of 1.
We made a conscious decision not to clutter or confuse things with batch numbers and expiries in the mobile app. It does maintain knowledge of the batch details under the hood, but no information about this is ever exposed to an mSupply Mobile user. The way batches are dealt with internally is by assuming the store follows FEFO (first expiry, first out) principles.
- Whenever a customer invoice is created, the stock issued from it will be taken from the batch(es) with the nearest expiry date.
- Supplier invoices sync down with batch information already recorded in mSupply Desktop/Server, however if the mobile user disputes how much was sent, and edits the amount being received, this will be treated pessimistically: if there is more than expected, it will be added to the batch with the shortest shelf life, if there is less, it will come off the batch(es) with the longest shelf life.
- Stocktakes will also take this pessimistic view. If a stocktake decreases stock, it will be taken from the batch(es) with the longest shelf life. If it increases stock, it will be added to the batch with the shortest shelf life, unless there are no batches of the given item, in which case a batch will be created with no batch number or expiry date. These no-expiry batches are considered to have the shortest shelf life when making the above decisions (this way they will be issued first in customer invoices, and be cleared out of the system as quickly as possible)
Patients (or other 'names' that might be issued stock from a mobile store) must be added centrally. There is no interface for adding them from within the mobile app. When added centrally, and made 'visible' in a given mobile store, they will sync down and become available within the app.
Even if a name added centrally is a patient, with details like gender, age, etc., those details cannot be viewed in mobile. Mobile doesn't make any distinction between patients and other 'names' that can have stock issued to them.
Invoices created within mSupply mobile are confirmed from the outset so that they have an effect on inventory, making it easy to ensure that across all customer invoices, no more stock is issued than is available. We don't allow for stock that is not available to be issued (i.e. no placeholder lines), and we avoid the situation where stock that is available will be issued across more than one customer invoice. There is a loophole in the logic that could create this situation: if a customer invoice is created as 'new' or 'suggested' centrally and syncs down, it could have more stock issued than is available. However, we assume that mobile stores are only ever active on a mobile app sync site, so this should never happen.
The first time the app is opened, the user is presented with the first use page. Once this initial sync has successfully completed, the Sync Server URL, Sync Site Name, and Sync Site Password are locked in, and can't be changed. This is partially what is easy, but also a considered decision: adding the ability to change sync details after the initial sync opens up the possibility of having a tablet with the data of one site/store, and then getting mucked up by changing to get the data of another site/store or even from another sync server. The safe way is therefore to wipe all data and sync the initial dump in fresh. We don't have to provide an additional interface to do this, as you can wipe all data through the app manager within Android settings, and the next time you open mSupply Mobile it will be at the first use page. Having to go through this route rather than make it part of our standard interface also prevents any user from accidentally wiping everything.
That's it! Absolutely everything else is supported. I joke, please edit and add features here that people might expect but are missing.
We have a special admin mode that allows access to
- The Realm Explorer page, for viewing the contents of the app database
- Manually syncing To get into admin mode, press and hold the mSupply logo in the middle of the navigation bar for at least 5 seconds. Do the same again to get out of it (please don't forget!)