Differences

This shows you the differences between two versions of the page.

--- integration:nhlmis [2024/09/06 10:04] – [Other setup] Gary Willetts
+++ integration:nhlmis [2025/02/06 16:21] (current) – [Customer invoices] Gary Willetts
@@ Line 1: / Line 1: @@
 {{indexmenu_n>60}}
-====== 23.06. NHLMIS integration ======
+====== 23.07. NHLMIS integration ======
 <WRAP important center round 90%>
 Before you turn on the NHLMIS integration two important setup steps must be taken:
@@ Line 73: / Line 73: @@
   - all the batches in stock (i.e. where available stock is more than 0) that have a program and donor assigned (any other stocklines are ignored) are sent to NHLMIS by calling the ''/batches'' endpoint. If all successful then proceed to the next step. If not all are successful then record error and stop.
   - all current stock lines (i.e. where available stock is more than 0 and program and donor have been set) are sent to NHLMIS by calling the ''/stock-counts'' endpoint.
+    - Some items have an NHLMISChild property with values in the format "//code//,pack_XXX" where //code// is the item's code and XXX is the pack size. If the item of any stock line has an NHLMISChild property AND the line is not using the item's default pack size then the code of the item sent to NHLMIS for this line is replaced with the item code in the NHLMISChild property that has the matching pack size value (XXX in the example above). If there is no matching pack size value then no item code replacement is made.
   - The success or failure of each send for each store is logged.
-==== Fetching requisitions ====
+==== Fetching orders (requisitions) ====
-All the outstanding orders (which become requisitions in mSupply) for this mSupply installation which have become outstanding since the last "since marker" are automatically fetched from NHLMIS on a schedule defined by the **No. of minutes between fetches** field.
+All the outstanding orders (which become requisitions in mSupply) for this mSupply installation which have become outstanding since the last "since marker" are automatically fetched from NHLMIS on a schedule defined by the **No. of minutes between fetches** field. This is done by making a GET call to the ''/orders'' endpoint.
+These calls are all made using ''genericParent=True'' which means that all items in the NHLMIS response will be replaced with their generic parent items (by NHLMIS). The quantities requested for each item in the order are multiplied by their default pack size to get the number of units for the requisition line.
 If there are more than 50 outstanding orders then mSupply will automatically ask NHLMIS to send the next 50 until all outstanding orders have been retrieved.
@@ Line 83: / Line 86: @@
 Each time orders are successfully retrieved, the "since" marker that mSupply uses for the request is updated with the value returned by NHLMIS. And if the "since" marker is for a different day to the last since marker stored, it is added to the  **Set "since" marker" to** drop down list (only the 5 most recent markers are stored in this drop down list - if there are already 5 then the oldest is replaced with the new one).
-Each order received from NHLMIS is saved as a requisition in the appropriate store in mSupply. The NHLMIs order ID is stored in the **Their ref** field of each requisition.
+Each order received from NHLMIS is saved as a requisition in the appropriate store in mSupply. The NHLMIS order ID is stored in the **Their ref** field of each requisition.
 Any orders that have already been received from NHLMIS and saved in mSupply are not saved again, they are ignored.
+=== Fetching a single order (requisition) ===
+This occurs when the **Fetch now** button shown above is clicked. This makes a GET call to the ''/orders/{suborderId}'' endpoint, where ''{suborderId}'' is the ID of the NHLMIS order to retrieve. As with the scheduled fetching of orders described above:
+  * These calls are all made using ''genericParent=True'' which means that all items in the NHLMIS response will be replaced with their generic parent items (by NHLMIS).
+  * The quantities requested for each item in the order are multiplied by their default pack size to get the number of units for the requisition line.
@@ Line 110: / Line 118: @@
 ===== Errors =====
 If errors are encountered during any of the processes then information about the error is saved in the log (see the [[admin:the_log]] page for details) and an email giving details of the error is sent to the email address stored in the **Error email** field.
+===== Visible changes in mSupply =====
+==== Requisitions ====
+When an NHLMIS order is received it is turned into a requisition in mSupply. The requisition has its donor set to the donor in mSupply that matches the value after ''funder:'' in the NHLMIS order. The donor is show in the requisition in a **Donor** drop down list (which is only shown if the **Fetch requisitions from NHLMIS** checkbox is checked on the //File// > //Preferences// > //NHLMIS// tab), shown here:
+{{ :integration:pasted:20250205-162053.png?650 |}}
+The drop down list is active so the user can edit it if required.
+==== Supplier invoices ====
+Supplier invoices have a new **Program** drop down list, displayed ony when the **Fetch requisitions from NHLMIS** checkbox is checked on the //File// > //Preferences// > //NHLMIS// tab. It is shown here:
+{{ :integration:pasted:20250205-163711.png?550 }}
+It is populated with the names of all the master lists with a tag of ''NHLMISProgram:XXX'' where XXX is the name of an NHLMIS program. The user can set the appropriate program for the stock on the supplier invoice.
+==== Customer invoices ====
+Read only **Program** and **Donor** fields are displayed on a customer invoice if the **Fetch requisitions from NHLMIS** checkbox is checked on the //File// > //Preferences// > //NHLMIS// tab. These fields display the NHLMIS progam and funder (mSupply donor) the customer invoice belongs to and are shown below:
+{{ :integration:pasted:20250205-163437.png?650 }}
+The **Program** field is populated with the name of the master list which matches the NHLMIS program. It will be empty if there isn't a requisition linked ot the customer invoice.
+The **Donor** field is populated with the name of the donor matching the NHLMIS funder (mSupply donor) associated with the requisition the customer invoice came from. It will be empty if there isn't a linked requisition.
+The action of the //Issue stock for all placeholder lines// option on the grinder icon below the table on the left hand is modified if the **Fetch requisitions from NHLMIS** checkbox is checked on the //File// > //Preferences// > //NHLMIS// tab: it still applies stock in FEFO order but it only uses stock which has a donor and program matching the customer invoice's. If the customer invoice does not have a donor then donor matching is not carried out, if it has no program then program matching is not carried out. If it has neither then the functionality is exactly the same as normal and no additional filtering is carried out.
+==== Stock lines ====
+A **Program** drop down list is displayed on the stock line edit window (opened by choosing //Item// > //Show items with stock// from the menus and double-clicking a stock line on that window). The drop down list will be set to the NHLMIS program associated with the stock and looks like this:
+{{ :integration:pasted:20250205-163531.png?550 }}
+If the **Fetch requisitions from NHLMIS** checkbox is checked on the //File// > //Preferences// > //NHLMIS// tab, the Program is also offered as a column selectable for display on the stock line edit window (opened by choosing //Item// > //Show items with stock// from the menus). If you click on the Customise button on that window, you will see the Program field in the available columns as shown here:
+{{ :integration:pasted:20250205-163500.png?650 }}
 \\