From 94724563065821000d123415b2a3263254059872 Mon Sep 17 00:00:00 2001 From: Juhi Date: Tue, 24 Mar 2026 13:41:15 +0530 Subject: [PATCH 1/3] restructure user guide to 01-18 sequence and apply premium Poppins UI refresh --- docs/developer/01_purpose.md | 11 - docs/developer/02_intro.md | 47 - docs/developer/03_getting-started.md | 35 - .../04_Architecture/data-dictionary.md | 12 - docs/developer/04_Architecture/intro.md | 40 - .../04_Architecture/system-hierarchy.md | 20 - docs/developer/04_Architecture/tech-stack.md | 1 + .../05_Database/consumption-forecast.md | 16 - .../05_Database/dataset-masterdata.md | 16 - docs/developer/05_Database/intro.md | 37 - .../05_Database/qat-db-application-masters.md | 16 - .../qat-db-inventory-shipment-consumption.md | 16 - .../qat-db-product-related-tables.md | 16 - .../05_Database/qat-db-realm-masters.md | 16 - .../05_Database/qat-db-user-roles-acl.md | 16 - docs/developer/05_Database/tree-forecast.md | 16 - docs/developer/05_Database/tree-template.md | 16 - .../06_Integrations/erp-shipment-linking.md | 131 +- docs/developer/06_Integrations/intro.md | 41 - .../06_Integrations/qat-catalog-updates.md | 136 -- .../06_Integrations/qat-interfaces.md | 91 - .../qat-supply-plan-sharing.md | 14 - docs/developer/07_Installation/01_overview.md | 20 - docs/developer/07_Installation/02_fasp-api.md | 233 -- .../07_Installation/03_fasp-core-ui.md | 62 - .../04_standard-installation.md | 125 -- .../07_Installation/05_server-setup.md | 248 --- .../07_Installation/06_rollback-procedure.md | 22 +- .../08_Guides/automated-test-backend.bkp | 169 -- .../08_Guides/automated-test-frontend.bkp | 275 --- .../developer/08_Guides/country-dashboards.md | 14 - docs/developer/08_Guides/flyway.bkp | 87 - docs/developer/08_Guides/intro.md | 10 - docs/developer/08_Guides/r-reports.md | 41 - docs/user/00-introduction.md | 1173 ---------- docs/user/01-introduction.md | 14 + docs/user/01-overview.md | 473 ---- docs/user/02-getting-started.md | 836 ------- docs/user/02-version-history.md | 20 + .../user/03-managing-programs-and-versions.md | 425 ---- docs/user/03-table-of-contents.md | 64 + docs/user/04-overview.md | 102 + .../04-supply-planning-module-program-data.md | 1258 ----------- docs/user/05-getting-started.md | 464 ++++ ...-supply-planning-module-supply-planning.md | 471 ---- .../user/06-managing-programs-and-versions.md | 162 ++ .../user/06-supply-planning-module-reports.md | 598 ----- .../07-forecasting-module-program-data.md | 147 -- .../07-supply-planning-module-program-data.md | 430 ++++ .../user/08-forecasting-module-forecasting.md | 1975 ----------------- ...-supply-planning-module-supply-planning.md | 127 ++ ...-forecasting-module-reports-and-outputs.md | 210 -- .../user/09-supply-planning-module-reports.md | 141 ++ ...-application-realm-administrator-manual.md | 1384 ------------ .../10-forecasting-module-program-data.md | 84 + docs/user/11-annex-2-business-rules.md | 1174 ---------- .../user/11-forecasting-module-forecasting.md | 164 ++ docs/user/12-annex-3-user-role-matrix.md | 1723 -------------- ...-forecasting-module-reports-and-outputs.md | 69 + ...-application-realm-administrator-manual.md | 100 + docs/user/13-annex-4-business-functions.md | 151 -- docs/user/14-annex-2-business-rules.md | 102 + .../14-annex-5-pipeline-program-import.md | 108 - docs/user/15-acronyms.md | 41 - docs/user/15-annex-3-user-role-matrix.md | 83 + docs/user/16-annex-4-business-functions.md | 69 + .../17-annex-5-pipeline-program-import.md | 55 + docs/user/18-acronyms.md | 59 + src/css/custom.css | 104 +- src/pages/index.js | 141 +- src/pages/index.module.css | 123 +- 71 files changed, 2603 insertions(+), 14287 deletions(-) delete mode 100644 docs/developer/01_purpose.md delete mode 100644 docs/developer/02_intro.md delete mode 100644 docs/developer/03_getting-started.md delete mode 100644 docs/developer/04_Architecture/data-dictionary.md delete mode 100644 docs/developer/04_Architecture/intro.md delete mode 100644 docs/developer/04_Architecture/system-hierarchy.md delete mode 100644 docs/developer/05_Database/consumption-forecast.md delete mode 100644 docs/developer/05_Database/dataset-masterdata.md delete mode 100644 docs/developer/05_Database/intro.md delete mode 100644 docs/developer/05_Database/qat-db-application-masters.md delete mode 100644 docs/developer/05_Database/qat-db-inventory-shipment-consumption.md delete mode 100644 docs/developer/05_Database/qat-db-product-related-tables.md delete mode 100644 docs/developer/05_Database/qat-db-realm-masters.md delete mode 100644 docs/developer/05_Database/qat-db-user-roles-acl.md delete mode 100644 docs/developer/05_Database/tree-forecast.md delete mode 100644 docs/developer/05_Database/tree-template.md delete mode 100644 docs/developer/06_Integrations/intro.md delete mode 100644 docs/developer/06_Integrations/qat-catalog-updates.md delete mode 100644 docs/developer/06_Integrations/qat-interfaces.md delete mode 100644 docs/developer/06_Integrations/qat-supply-plan-sharing.md delete mode 100644 docs/developer/07_Installation/01_overview.md delete mode 100644 docs/developer/07_Installation/02_fasp-api.md delete mode 100644 docs/developer/07_Installation/03_fasp-core-ui.md delete mode 100644 docs/developer/07_Installation/04_standard-installation.md delete mode 100644 docs/developer/07_Installation/05_server-setup.md delete mode 100644 docs/developer/08_Guides/automated-test-backend.bkp delete mode 100644 docs/developer/08_Guides/automated-test-frontend.bkp delete mode 100644 docs/developer/08_Guides/country-dashboards.md delete mode 100644 docs/developer/08_Guides/flyway.bkp delete mode 100644 docs/developer/08_Guides/intro.md delete mode 100644 docs/developer/08_Guides/r-reports.md delete mode 100644 docs/user/00-introduction.md create mode 100644 docs/user/01-introduction.md delete mode 100644 docs/user/01-overview.md delete mode 100644 docs/user/02-getting-started.md create mode 100644 docs/user/02-version-history.md delete mode 100644 docs/user/03-managing-programs-and-versions.md create mode 100644 docs/user/03-table-of-contents.md create mode 100644 docs/user/04-overview.md delete mode 100644 docs/user/04-supply-planning-module-program-data.md create mode 100644 docs/user/05-getting-started.md delete mode 100644 docs/user/05-supply-planning-module-supply-planning.md create mode 100644 docs/user/06-managing-programs-and-versions.md delete mode 100644 docs/user/06-supply-planning-module-reports.md delete mode 100644 docs/user/07-forecasting-module-program-data.md create mode 100644 docs/user/07-supply-planning-module-program-data.md delete mode 100644 docs/user/08-forecasting-module-forecasting.md create mode 100644 docs/user/08-supply-planning-module-supply-planning.md delete mode 100644 docs/user/09-forecasting-module-reports-and-outputs.md create mode 100644 docs/user/09-supply-planning-module-reports.md delete mode 100644 docs/user/10-annex-1-application-realm-administrator-manual.md create mode 100644 docs/user/10-forecasting-module-program-data.md delete mode 100644 docs/user/11-annex-2-business-rules.md create mode 100644 docs/user/11-forecasting-module-forecasting.md delete mode 100644 docs/user/12-annex-3-user-role-matrix.md create mode 100644 docs/user/12-forecasting-module-reports-and-outputs.md create mode 100644 docs/user/13-annex-1-application-realm-administrator-manual.md delete mode 100644 docs/user/13-annex-4-business-functions.md create mode 100644 docs/user/14-annex-2-business-rules.md delete mode 100644 docs/user/14-annex-5-pipeline-program-import.md delete mode 100644 docs/user/15-acronyms.md create mode 100644 docs/user/15-annex-3-user-role-matrix.md create mode 100644 docs/user/16-annex-4-business-functions.md create mode 100644 docs/user/17-annex-5-pipeline-program-import.md create mode 100644 docs/user/18-acronyms.md diff --git a/docs/developer/01_purpose.md b/docs/developer/01_purpose.md deleted file mode 100644 index 1ebb0f6..0000000 --- a/docs/developer/01_purpose.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -id: 01_purpose -title: Purpose of Document -sidebar_label: Purpose of Document -sidebar_position: 1 ---- - -# Purpose of Document - -This document seeks to provide technical overview details of the Quantification Analytics Tool (QAT) Server and provide a guide to any IT professionals wishing to further understand the back end of QAT, including the software tools used, high-level design architecture, data interfaces/integration, and server-side details on configuration and management. For example, developers who are expected to take over and do code maintenance on the system over its life span. This does not include the application and realm admin functions that are available on the front end of the software, as those are covered in the QAT user guide. - diff --git a/docs/developer/02_intro.md b/docs/developer/02_intro.md deleted file mode 100644 index 5eb9db8..0000000 --- a/docs/developer/02_intro.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -id: 02_intro -title: Introduction to QAT -sidebar_label: Introduction to QAT -sidebar_position: 2 ---- - -# Introduction to QAT - -The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages new technologies to enhance and modernize the functionality offered by the incumbent PipeLine (supply planning) and Quantimed (forecasting) tools by providing advanced visualizations, master data management, and updated planning logic on a cloud-based solution with offline functionality. - -QAT is being built in two modules – the supply planning module (launched December 2020) and the forecasting module (launched June 2022). For more on the Functional Requirements used to build QAT, please see [Business & Technical Requirements](./architecture/requirements). - -## Version -| Version (date) | Author/Editor | Notes & Major Changes | -| :---- | :---- | :---- | -| 1 (Mar 15, 2021\) | GHSC-PSM FASP, Altius & FHI 360 | First draft | -| 2 (Sept 14, 2022\) | Kyle Duarte | Updated to include Forecasting Module | -| 3 (Aug 01, 2024\) | Akil Mahimwala | Updated to include reference to Integration documentation. | -| 4 (Jan 28, 2025\) | Dolly Chabria | Added information for ERP Shipment linking | -| 5 (Mar 07, 2026\) | Akil Mahimwala | Combined the Documenatition from different locations into one | - - -## Contents -- [Getting Started](./getting-started) -- [Architecture](./architecture/overview) -- [Database](./database/overview) -- [Integrations](./integrations/overview) -- [Installation](./installation/overview) -- [Guides](./guides/overview) - - -## Acronyms & Definitions - -| ARTMIS | Automated Requisition Tracking Management Information System | -| :---- | :---- | -| CDN | Content Delivery Network | -| ERP | Enterprise Resource planning | -| FASP | Forecasting and Supply Planning | -| GFPVAN | Global Family Planning Visibility & Analytics Network | -| GHSC-PSM | Global Health Supply Chain \- Procurement and Supply Management program | -| IAM | Identity and Access Management | -| JWT | JSON Web Tokens | -| QAT | Quantification Analytics Tool | -| RDS | Relational Database Service | -| VPC | Virtual Private Cloud | -| USAID | United States Agency for International Development | \ No newline at end of file diff --git a/docs/developer/03_getting-started.md b/docs/developer/03_getting-started.md deleted file mode 100644 index 6591973..0000000 --- a/docs/developer/03_getting-started.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -id: getting-started -title: Getting Started -sidebar_label: Getting Started -sidebar_position: 3 ---- - -# Getting Started - -This guide will help you set up both the frontend and backend components of the QAT application. The system consists of a React-based frontend and a Java Spring Boot backend with MySQL database. - -## Installation - -### Frontend - -See [Frontend Setup](./installation/fasp-core-ui) for detailed instructions on how to set up `fasp-core-ui`. - -### Backend - -See [Backend Setup](./installation/fasp-api) for detailed instructions on how to set up `fasp-api`. - -## Reference Documentation - -* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html) -* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/2.2.1.RELEASE/maven-plugin/) -* [Spring Web](https://docs.spring.io/spring-boot/docs/2.2.1.RELEASE/reference/htmlsingle/#boot-features-developing-web-applications) -* [Spring Boot DevTools](https://docs.spring.io/spring-boot/docs/2.2.1.RELEASE/reference/htmlsingle/#using-boot-devtools) - - -### Guides -The following guides illustrate how to use some features concretely: - -* [Building a RESTful Web Service](https://spring.io/guides/gs/rest-service/) -* [Serving Web Content with Spring MVC](https://spring.io/guides/gs/serving-web-content/) -* [Building REST services with Spring](https://spring.io/guides/tutorials/bookmarks/) diff --git a/docs/developer/04_Architecture/data-dictionary.md b/docs/developer/04_Architecture/data-dictionary.md deleted file mode 100644 index fdd4479..0000000 --- a/docs/developer/04_Architecture/data-dictionary.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -id: data-dictionary -title: Data Dictionary -sidebar_label: Data Dictionary -sidebar_position: 4 ---- - -# Data Dictionary - -Please see the corresponding excel file in the zipped folder for the [Data Dictionary v2.9](https://github.com/FASP-QAT/fasp-api/raw/master/docs/Data%20dictionary%20QAT%20SP%20v2.9.xlsx). - -**Note:** while this data dictionary has been created for the supply plan output that's sent to the GFPVAN & ARTMIS \- the fields cover all data fields in the broader database structure. \ No newline at end of file diff --git a/docs/developer/04_Architecture/intro.md b/docs/developer/04_Architecture/intro.md deleted file mode 100644 index a81f6a3..0000000 --- a/docs/developer/04_Architecture/intro.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -id: overview -title: High-level Architecture -sidebar_label: High-level Architecture -sidebar_position: 1 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -# High-level Architecture - -QAT is built on Java spring boot backend and React front end. The high-level architecture is below. - -![QAT High-level Architecture](/diagrams/high-level-architecture.png) - -Figure:QAT High-level Architecture - - -For a more detailed explaination of the above, please refer to the [Tech Stack documentation](/docs/developer/architecture/tech-stack). - -## Front End \- React based PWA - -The React based application is hosted on a NodeJS server. It is built as a Progressive Web App (PWA) and can work even if the User is offline. To initialize the application the User will have to login to the application once while he is online. The Username and Password that the user has entered is sent to the backend and once authorized a Token is returned. The Local application then does all subsequent calls to the API using the Token to identify and authenticate the request. - -At the first login the application Syncs all the Master data with the Server side pulling in any updates to the Master data. Since Master data is only edited on the live server. Server side always takes precedence during the Sync process and updates from Server will overwrite Client side Master data. - -Once a User has logged in the application stores his credentials and access rights locally and he can then continue to Login and access the application even if he is Offline. Authentication of the Username and Password is done locally. - -To begin editing a Program the user will need to Load the Program from the Server. Once a program has been loaded the user can then begin editing the Supply Plan by making changes to the Consumption, Inventory and Shipments. All of the changes that the user has made are stored locally on the IndexedDb. Once the user is ready to commit his changes to the Server he then selects the Commit version option. - -Please refer to [Process Flows](process-flow.md) for additional information on process flows. - -## Back End \- Java Spring Boot Application - -The Back end is a Java Spring Boot application. The Front end connects to the Server side through a REST API interface. - -### API - -Please refer to [API Documentation](/docs/api) for more details on the API. - diff --git a/docs/developer/04_Architecture/system-hierarchy.md b/docs/developer/04_Architecture/system-hierarchy.md deleted file mode 100644 index 131c9a1..0000000 --- a/docs/developer/04_Architecture/system-hierarchy.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: system-hierarchy -title: System Hierarchy -sidebar_label: System Hierarchy -sidebar_position: 6 ---- -import DiagramEditor from '@site/src/components/DiagramEditor'; - -# System Hierarchy - -This diagram shows the system hierarchy of the application, illustrating the relationship between the different components - Realm, Country, Health Area, Organisation, Region and Program - with an example. - -![System Hierachy](/diagrams/system-hierarchy.drawio.png) - - - diff --git a/docs/developer/04_Architecture/tech-stack.md b/docs/developer/04_Architecture/tech-stack.md index 0e60b25..343e988 100644 --- a/docs/developer/04_Architecture/tech-stack.md +++ b/docs/developer/04_Architecture/tech-stack.md @@ -100,6 +100,7 @@ Details on the end points and the parameters that you need to pass and that you As an example, to generate the JWT authorization token you need to call the `https://www.quantificationanalytics.org/authenticate` endpoint. The Username and Password should be passed to the end point as part of the Body as a JSON object. Sample JSON + ```json { "username": "sombody@somedomain.com", diff --git a/docs/developer/05_Database/consumption-forecast.md b/docs/developer/05_Database/consumption-forecast.md deleted file mode 100644 index 5a6f838..0000000 --- a/docs/developer/05_Database/consumption-forecast.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: consumption-forecast -title: Consumption Forecast ERD -sidebar_label: ERD Consumption Forecast -sidebar_position: 3 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Consumption Forecast ERD](/database/consumption-forecast.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/dataset-masterdata.md b/docs/developer/05_Database/dataset-masterdata.md deleted file mode 100644 index a893698..0000000 --- a/docs/developer/05_Database/dataset-masterdata.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: dataset-masterdata -title: Master Data ERD -sidebar_label: ERD Master data -sidebar_position: 2 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Dataset Masterdata ERD](/database/dataset-masterdata.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/intro.md b/docs/developer/05_Database/intro.md deleted file mode 100644 index 729aa46..0000000 --- a/docs/developer/05_Database/intro.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -id: overview -title: Database Design -sidebar_label: Overview -sidebar_position: 1 ---- - -# Database Design - -The application has two databases: - -1. The main database, MySQL, which is the source of truth for all data in the application. -2. The indexDB, which is a subset of the main database that allows the application to work offline. - -**MySQL**: -The `fasp-api` project uses a MySQL database. This database is stored on the server. - -**IndexDB**: -The `fasp-ui` project uses an IndexedDB database, which is a subset of the main database, and is saved on each user's computer. - -All masters data is loaded by default (restricted by access rights), and users select specific program-versions to load. - -See an overview of the QAT Data Model from 2020 in [this PowerPoint presentation](https://github.com/FASP-QAT/fasp-api/blob/master/docs/Database%20ER%20Diagrams/QAT%20Data%20Model%20Overview.pptx). - -## Entity-Relationship Diagrams (ERDs) - -Entity-Relationship Diagrams (ERDs) for the QAT Application DB: - -* [Dataset Masterdata](dataset-masterdata) -* [Consumption Forecast](consumption-forecast) -* [Tree Template](tree-template) -* [Tree Forecast](tree-forecast) -* [Application masters](application-masters) -* [Inventory, Shipment and Consumption](inventory-shipment-consumption) -* [Product related tables](product-related-tables) -* [Realm masters](realm-masters) -* [User, Roles & ACL](user-roles-acl) \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-application-masters.md b/docs/developer/05_Database/qat-db-application-masters.md deleted file mode 100644 index 970a074..0000000 --- a/docs/developer/05_Database/qat-db-application-masters.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: application-masters -title: Application Masters ERD -sidebar_label: ERD Application Masters -sidebar_position: 6 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Application Masters ERD](/database/qat-db-application-masters.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-inventory-shipment-consumption.md b/docs/developer/05_Database/qat-db-inventory-shipment-consumption.md deleted file mode 100644 index 85e5443..0000000 --- a/docs/developer/05_Database/qat-db-inventory-shipment-consumption.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: inventory-shipment-consumption -title: Inventory, Shipment and Consumption ERD -sidebar_label: ERD Inventory, Shipment and Consumption -sidebar_position: 7 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Inventory, Shipment and Consumption ERD](/database/qat-db-inventory-shipment-and-consumption.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-product-related-tables.md b/docs/developer/05_Database/qat-db-product-related-tables.md deleted file mode 100644 index 1537921..0000000 --- a/docs/developer/05_Database/qat-db-product-related-tables.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: product-related-tables -title: Product Related Tables ERD -sidebar_label: ERD Product Related Tables -sidebar_position: 8 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Product Related Tables ERD](/database/qat-db-product-related-tables.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-realm-masters.md b/docs/developer/05_Database/qat-db-realm-masters.md deleted file mode 100644 index 882ed2f..0000000 --- a/docs/developer/05_Database/qat-db-realm-masters.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: realm-masters -title: Realm Masters ERD -sidebar_label: ERD Realm Masters -sidebar_position: 9 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Realm Masters ERD](/database/qat-db-realm-masters.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-user-roles-acl.md b/docs/developer/05_Database/qat-db-user-roles-acl.md deleted file mode 100644 index b2eafd5..0000000 --- a/docs/developer/05_Database/qat-db-user-roles-acl.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: user-roles-acl -title: User, Roles & ACL ERD -sidebar_label: ERD User, Roles & ACL -sidebar_position: 10 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![User, Roles & ACL ERD](/database/qat-db-user-roles-acl.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/tree-forecast.md b/docs/developer/05_Database/tree-forecast.md deleted file mode 100644 index 1d4b022..0000000 --- a/docs/developer/05_Database/tree-forecast.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: tree-forecast -title: Tree Forecast ERD -sidebar_label: ERD Tree Forecast -sidebar_position: 5 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Tree Forecast ERD](/database/tree-forecast.png) - - \ No newline at end of file diff --git a/docs/developer/05_Database/tree-template.md b/docs/developer/05_Database/tree-template.md deleted file mode 100644 index 941ee8c..0000000 --- a/docs/developer/05_Database/tree-template.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: tree-template -title: Tree Template ERD -sidebar_label: ERD Tree Template -sidebar_position: 4 ---- - -import DiagramEditor from '@site/src/components/DiagramEditor'; - -![Tree Template ERD](/database/tree-template.png) - - \ No newline at end of file diff --git a/docs/developer/06_Integrations/erp-shipment-linking.md b/docs/developer/06_Integrations/erp-shipment-linking.md index 74eb3c8..074ea01 100644 --- a/docs/developer/06_Integrations/erp-shipment-linking.md +++ b/docs/developer/06_Integrations/erp-shipment-linking.md @@ -6,88 +6,75 @@ sidebar_position: 5 --- # ERP Shipment linking -This section outlines the workflow and rules for linking and managing QAT and ERP shipments within the system. The ARTMIS team is sending incremental order and shipment files daily. This information is updated in QAT, and for locally loaded programs, the data is synced automatically to the user's machine. -## 1. QAT Shipments - Not Linked (QAT-Initiated Linking) -These are QAT shipments that are currently not linked to any ERP shipment. +This section outlines the workflow and rules for linking and managing QAT and ERP shipments within the system. The ARTMIS team is sending incremental order and shipment files daily. This information is updated in QAT, and for locally loaded programs, the data is synced automatically to the user's machine. -### User Action: - * Select one or more QAT shipments (the first selected is treated as the Parent Shipment). - * Select one or more ERP shipments to link with. +## 1. QAT Shipments - Not Linked (QAT-Initiated Linking) -### System Behavior: - * The selected QAT shipments are updated: - - ERP flag = true - - Active = false - * Child Shipments are created for: - - RO No - - RO Prime Line No - - Order No - - Prime Line No - - KN Shipment No - * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. - * The non-parent QAT shipments will have the Parent Linked Shipment ID set to the Parent Shipment's ID. +These are QAT shipments that are currently not linked to any ERP shipment. - +### User Action: -## 2. QAT Shipments - Linked -This state reflects QAT shipments that are already linked. From here, users can either de-link or update ARU and Notes. - * If Shipment is Committed: - - Parent Shipment: - + Active = false - - Child Shipments: - + Active = true - + ERP flag = false - * If Shipment is Not Committed: - - Parent Shipment: - + Active = true - - Child Shipments: - + Active = false - + ERP flag = false - + * Select one or more QAT shipments (the first selected is treated as the Parent Shipment). + * Select one or more ERP shipments to link with. +### System Behavior: -## 3. ERP Shipments - Not Linked (ERP-Initiated Linking) - * These are ERP shipments that are not currently linked to any QAT shipment. - * User Action: - - Select one or more ERP shipments. - - Either: - + Link them to existing QAT shipments (first selected QAT shipment becomes the Parent Shipment), or - + Choose to create new QAT shipments directly. - * System Behavior: - - The associated QAT shipments are updated: - + ERP flag = true - + Active = false - - Child Shipments are created using: - + RO No - + RO Prime Line No - + Order No - + Prime Line No - + KN Shipment No - * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. - * The QAT shipments that are not the Parent will have the Parent Linked Shipment ID set accordingly. + * The selected QAT shipments are updated: + - ERP flag = true + - Active = false + * Child Shipments are created for: + - RO No + - RO Prime Line No + - Order No + - Prime Line No + - KN Shipment No + * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. + * The non-parent QAT shipments will have the Parent Linked Shipment ID set to the Parent Shipment's ID. - +## 2. QAT Shipments - Linked -## 4. Status Mapping -| **ARTMIS External Status Stage** | **QAT Shipment Status** | -| :---- | :---- | -| Cancelled | Cancelled | -| Delivered | Received | -| Order on Hold \- Pending Clarification Stage | On-hold | -| Order on Hold \- Pending Release | On-hold | -| Order on Hold \- Sourcing / Fulfillment Processing | On-hold | -| Partially Delivered | Shipped | -| Pending Clarification | Submitted | -| Pending PSM Source Final Approval | Submitted | -| Pending PSM Source Initial Approval | Submitted | -| Pending Recipient Approval | Submitted | -| Pending Release | Approved | -| Pending Shipment | Approved | -| Pending USAID Approval | Submitted | -| Shipped | Shipped | -| Sourcing / Fulfillment Processing | Submitted | +This state reflects QAT shipments that are already linked. From here, users can either de-link or update ARU and Notes. +_ If Shipment is Committed: - Parent Shipment: + Active = false - Child Shipments: + Active = true + ERP flag = false +_ If Shipment is Not Committed: - Parent Shipment: + Active = true - Child Shipments: + Active = false + ERP flag = false +## 3. ERP Shipments - Not Linked (ERP-Initiated Linking) + * These are ERP shipments that are not currently linked to any QAT shipment. + * User Action: + - Select one or more ERP shipments. + - Either: + + Link them to existing QAT shipments (first selected QAT shipment becomes the Parent Shipment), or + + Choose to create new QAT shipments directly. + * System Behavior: + - The associated QAT shipments are updated: + + ERP flag = true + + Active = false + - Child Shipments are created using: + + RO No + + RO Prime Line No + + Order No + + Prime Line No + + KN Shipment No + * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. + * The QAT shipments that are not the Parent will have the Parent Linked Shipment ID set accordingly. +## 4. Status Mapping +| **ARTMIS External Status Stage** | **QAT Shipment Status** | +| :------------------------------------------------- | :---------------------- | +| Cancelled | Cancelled | +| Delivered | Received | +| Order on Hold \- Pending Clarification Stage | On-hold | +| Order on Hold \- Pending Release | On-hold | +| Order on Hold \- Sourcing / Fulfillment Processing | On-hold | +| Partially Delivered | Shipped | +| Pending Clarification | Submitted | +| Pending PSM Source Final Approval | Submitted | +| Pending PSM Source Initial Approval | Submitted | +| Pending Recipient Approval | Submitted | +| Pending Release | Approved | +| Pending Shipment | Approved | +| Pending USAID Approval | Submitted | +| Shipped | Shipped | +| Sourcing / Fulfillment Processing | Submitted | diff --git a/docs/developer/06_Integrations/intro.md b/docs/developer/06_Integrations/intro.md deleted file mode 100644 index 3dbb896..0000000 --- a/docs/developer/06_Integrations/intro.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: overview -title: QAT-ERP Integrations -sidebar_label: Overview -sidebar_position: 1 ---- - -# QAT-ERP Integrations - -QAT has several data integrations with Enterprise Resource Planning (ERP) systems, as shown in the below diagram. - -There are 3 main types of interfaces between QAT and external systems - -1. **Supply plan sharing.** QAT sends supply plans to external systems. Currently QAT shares supply plans with the GHSC-PSM order management system ARTMIS, and to the GFPVAN. -1. **Catalog Updates.** QAT receives the ARTMIS product catalog, which updates the QAT planning unit details -1. **ERP Shipment linking** Currently the only active ERP shipment linking interface is with ARTMIS for GHSC-PSM orders. - -To summarise: - -- QAT receives ARTMIS Orders and Shipments -- QAT sends QAT shipments to ARTMIS -- QAT sends QAT Supply Plans to ARTMIS and GFPVAN -- Country Dashboards. A recent addition has been made to QAT where countries can pull updated Supply plans directly from QAT via an API and build their own Dashboards for reporting. To get more information on how this works please refer to [Country Dashboard](/docs/developer/Guides/country-dashboards) -To get more information on - - -![QAT data interfaces with ERP systems](/diagrams/QAT-ERP-Integrations.png) - -Figure 1 QAT data interfaces with ERP systems - -## QAT Supply Plan Sharing - -Refer to the [QAT Supply Plan Sharing](/docs/developer/integrations/qat-supply-plan-sharing) page for more information. - -## QAT Catalog Updates - -Refer to the [QAT Catalog Updates](/docs/developer/integrations/qat-catalog-updates) page for more information. - -## ERP Shipment Linking - -Refer to the [ERP Shipment Linking](/docs/developer/integrations/erp-shipment-linking) page for more information. diff --git a/docs/developer/06_Integrations/qat-catalog-updates.md b/docs/developer/06_Integrations/qat-catalog-updates.md deleted file mode 100644 index b5ea735..0000000 --- a/docs/developer/06_Integrations/qat-catalog-updates.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -id: qat-catalog-updates -title: QAT Catalog Updates -sidebar_label: QAT Catalog Updates -sidebar_position: 4 ---- - -# QAT Catalog Updates - -The QAT Catalog is created using the ARTMIS data. The Forecasting Unit, Planning Unit and Procurement Unit are all taken from ARTMIS database. If user changes any one of these data and ARTMIS pushes a new feed, then the former will be replaced by the `feed`. The non-ARTMIS data can be updated by the user on QAT. All Alternate Reporting Units are managed directly on QAT. - -### Unit -**Unit** is the unit of measure. QAT checks whether a unit already exists based on the unit name and unit code. If the unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Dimension | Eaches | -| Unit Name | product_base_unit/item_uom/item_weight_uom/item_sizemeasure | -| Unit Code | product_base_unit/item_uom/item_weight_uom/item_sizemeasure | - - -### Tracer Category -**Tracer Category** are a second tier, less broad grouping of product types specific to a Realm. QAT checks whether a tracer category already exists based on the tracer category name. If the tracer category exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Realm | Global Health | -| Tracer Category Name | product_tracer_cat | -| Technical Area | Null | - - -### Product Category -**Product Category** is a broad category group used to group planning units. QAT checks whether a product Category already exists based on the product category name. If the product category exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Realm | Global Health | -| Product Category Name | commodity_subcat_long_desc | -| Parent Product Category | commodity_council_long_desc | -| Sort Order | Auto generated by QAT | - - -### Planning Unit -**Planning Unit** is the product to be planned for in QAT. It is a product with full description up to the primary packaging (e.g. bottle of 30 tablets, 10x10 blister pack, etc.). QAT checks whether a Planning Unit already exists based on the SKU Code. If the Planning Unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Forecasting Unit | product_name_no_pack | -| Planning Unit Name | product_name | -| SKU Code | product_id | -| Unit | item_uom | -| Conversion Factor | product_base_unit_mult | - - -### Procurement Agent Planning Unit -**Procurement Agent Planning Unit** is the Mapping between Procurement Agent and Planning Unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Procurement Agent | GHSC-PSM | -| Planning Unit | product_name | -| Catalog Price | wcs_catalog_price | -| MOQ | planning_unit_moq | -| Units per pallet Euro 1 | planning_unit_per_pallet | -| Units per pallet Euro 2 | planning_unit_per_pallet | -| Units per container | planning_unit_per_container | -| Volume | planning_unit_volume_m3 | -| Weight | planning_unit_weight_kg | - - -### Forecasting Unit -**Forecasting Unit** is the base unit that will be used for a specified forecasting period. e.g. one tablet, one condom, one milliliter. QAT checks whether a Forecasting Unit already exists based on the SKU Code. If the Forecasting Unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Realm | Global Health | -| Product Category | Based on commodity_council_long_desc and commodity_subcat_long_desc | -| Tracer Category | product_tracer_cat | -| Generic Name | product_international_nonproprietary_name | -| Forecasting Unit Name | product_name_no_pack | -| Unit | product_base_unit | -| SKU Code | product_id_no_pack | - - -### Procurement Unit -**Procurement Unit** is the product at item level. In other words, it is a higher-level description of the planning unit including supplier-specific attributes. This information will not be visible/selectable by QAT users but will be sent automatically from procurement management systems. QAT checks whether a Procurement Unit already exists based on the SKU Code. If the Procurement Unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Planning Unit | product_name | -| Procurement Unit Name | item_name | -| Unit | item_uom | -| Conversion Factor | 1 | -| Manufacturer | item_supplier_name | -| Width Qty | item_width | -| Height Qty | item_height | -| Length Unit | item_sizemeasure | -| Length Qty | item_length | -| Weight Unit | item_weight_uom | -| Weight Qty | item_weight | -| Volume Unit | Null | -| Volumn Qty | Null | -| Units per case | item_units_per_case | -| Units per pallet Euro 1 | item_num_of_units_pallet | -| Units per pallet Euro 2 | Null | -| Units Per container | units_per_container | -| Labeling | item_label_languages | - - -### Procurement Agent Procurement Unit -**Procurement Agent Procurement Unit** is the mapping between procurement agent and procurement Unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Procurement Unit | item_name | -| Procurement Agent | GHSC-PSM | -| SKU Code | item_id | -| Vendor Price | wcs_catalog_price | -| Approved to shipped lead time | 3 | -| Gtin | item_manufacturer_gtin_upc | - - -### Manufacturer -**Manufacturer**, QAT checks whether a manufacturer already exists based on the Manufacturer Name. If the Manufacturer exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. - -| QAT Field | ARTMIS Field | -| :---- | :---- | -| Realm | Global Health | -| Manufacturer Name | item_supplier_name | - -:::warning FIXME ARTMIS Sample files -We need to put the correct files in the location -::: -:::tip ARTMIS Sample files -[ARTMIS Sample files](https://github.com/FASP-QAT/fasp-api/tree/master/docs/Sample%20ARTMIS%20Feeds) -::: \ No newline at end of file diff --git a/docs/developer/06_Integrations/qat-interfaces.md b/docs/developer/06_Integrations/qat-interfaces.md deleted file mode 100644 index f64319d..0000000 --- a/docs/developer/06_Integrations/qat-interfaces.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -id: qat-interfaces -title: QAT Interfaces -sidebar_label: QAT Interfaces -sidebar_position: 2 ---- - -# QAT Interfaces - -This section describes the data exchange interfaces between QAT and ARTMIS and GFPVAN. - -## File formats - -The following file formats are used for data exchange: - -* Files shared with ARTMIS are done via SFTP (xml formats). The formats of the files were provided by ARTMIS and used by QAT as is. -* Files imported from Pipeline and Quantimed are via xml- (formats dictated by each software). -* Files shared with GFPVAN are JSON. - -Only if the scripts below fail will QAT send an automated notification of this failure. -* Script files on Sharepoint [here](https://chemonics.sharepoint.com/sites/FASP-FHI360_Suncontract/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FFASP%2DFHI360%5FSuncontract%2FShared%20Documents%2FGeneral%2FDocumentation%2FBatch%20job%20scripts&viewid=5438e9ce%2D8d16%2D4183%2D8b68%2Daf909e3acd8e) -* ARTMIS Sample file details [here](https://github.com/FASP-QAT/fasp-api/tree/master/docs/Sample%20ARTMIS%20Feeds) - - -## QAT Server Scripts - -The following scripts are used to transfer data between QAT and external systems: - -| Script name | Description of the script | Script Path | Source folder | Source folder after completing script | Destination folder | Log Path | Schedule Time (EST) | -| :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | -| [task1.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task1.sh) | To pull Catalog files from ARTMIS to QAT and then import them into the QAT db | /home/ubuntu/QAT/script/task1.sh | Remote server \-\> /FASP/ARTMIS | Remote server \-\> /FASP/processed | Local server \-\> /home/ubuntu/QAT/ARTMIS | /home/ubuntu/QAT/logs/ARTMIS/task1-yyyy-mm-dd.txt | 23:00 | -| [task2.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task2.sh) | To first generate the Order and Program files and then push the files from QAT to ARTMIS | /home/ubuntu/QAT/script/task2.sh | Local server \-\> /home/ubuntu/QAT/supplyPlan | Local server \-\> /home/ubuntu/QAT/supplyPlan/processed | Remote server \-\> /FASP/supplyPlan | /home/ubuntu/QAT/logs/ARTMIS/task2-yyyy-mm-dd.txt | 23:00 | -| [task3.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task3.sh) | To push Supply Plan files from QAT to ARTMIS | /home/ubuntu/QAT/script/task3.sh | Local server \-\> /home/ubuntu/QAT/supplyPlan/Artmis | Local server \-\> /home/ubuntu/QAT/supplyPlan/Artmis/processed | Remote server \-\> /FASP/supplyPlan and Sharepoint | /home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt | Every 15 min | -| [task6.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task6.sh) | To push GFPVAN files from QAT to GFPVAN SFTP Server | /home/ubuntu/QAT/script/task6.sh | Local server \-\> /home/ubuntu/QAT/supplyPlan/GFPVAN | Local server \-\>/home/ubuntu/QAT/supplyPlan/GFPVAN/processed | Remote server \-\> /e2open/b2b/scpusers2/e2net/E2NETSTG/e2c0000e9a-2ed8866a49-0/in | /home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt | Every 15 min | - -Table 1 QAT Server Scripts - -Note there is no task 4 and task 5. task 4 and task 5 used to exist but are no longer in use and therefore have been removed form the documentation. - -### Task1.sh - -`importProductCatalog.sh` - -1. We have a Local Directory on QAT Server `/home/ubuntu/QAT/ARTMIS` in which we will download the data from SFTP server from the `/FASP/ARTMIS`. -1. After Downloaded we will move data in processed folder on SFTP Server `/FASP/processed`. -1. Import the files into QAT, once they are imported they are moved to the `/home/ubuntu/QAT/ARTMIS/processed` folder -1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task1-yyy-ymm-dd.txt` - -Script Location `/home/ubuntu/QAT/script/task1.sh` (QAT Server) - -### Task2.sh - -`exportProgramAndOrder.sh` - -1. Generate the Program and Order csv files in `/home/ubuntu/QAT/supplyPlan` folder -1. We have Local path in QAT server `/home/ubuntu/QAT/supplyPlan` in which we need to transfer the csv file on SFTP server in `/FASP/supplyPlan` directory. -1. After transferring all the files on SFTP Server all the files will move in local folder `/home/ubuntu/QAT/supplyPlan/processed`. -1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task2-yyyy-mm-dd.txt` - -### Task3.sh - -1. We have Local path in QAT server `/home/ubuntu/QAT/supplyPlan/Artmis` in which we need to transfer the json file on SFTP server in `/FASP/supplyPlan` directory. -1. Copy of same files will be copied to sharepoint (Only Production Server) -1. After transferring all the files on SFTP Server all the files will move in local folder `/home/ubuntu/QAT/supplyPlan/Artmis/processed` -1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt` - -Script Location `/home/ubuntu/QAT/script/` (QAT Server) - -### Task6.sh - -1. We have Local path in QAT server /home/ubuntu/QAT/supplyPlan/GFPVAN in which we need to transfer the text file on GFPVAN SFTP server in `/e2open/b2b/scpusers2/e2net/E2NETSTG/e2c0000e9a-2ed8866a49-0/in directory.` -1. After transferring all the files on SFTP Server all the files will move in local folder `/home/ubuntu/QAT/supplyPlan/GFPVAN/` processed. -1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt` - -Script Location `/home/ubuntu/QAT/script/` - -:::tip ARTMIS Sample files -[ARTMIS Sample files](https://github.com/FASP-QAT/fasp-api/tree/master/docs/Sample%20ARTMIS%20Feeds) -::: - -**TO CONNECT SFTP SERVER** - -sh QAT/script/sftp.sh -``` -Prodcution Server SFTP: \ -UAT Server SFTP: \ -SHAREPOINT: \ -GFPVAN SFTP for UAT :bastion3.e2open.net -GFPVAN SFTP for PROD :bastion7.e2open.net -``` - diff --git a/docs/developer/06_Integrations/qat-supply-plan-sharing.md b/docs/developer/06_Integrations/qat-supply-plan-sharing.md deleted file mode 100644 index d3e20de..0000000 --- a/docs/developer/06_Integrations/qat-supply-plan-sharing.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -id: qat-supply-plan-sharing -title: QAT Supply Plan Sharing -sidebar_label: QAT Supply Plan Sharing -sidebar_position: 3 ---- - -# QAT Supply Plan Sharing - -Below are diagrams of which supply plans are shared by QAT to external systems. - -![QAT Supply Plan Sharing](/diagrams/QAT-supply-plan-flow.png) - -Figure 2 QAT Supply Plan Sharing \ No newline at end of file diff --git a/docs/developer/07_Installation/01_overview.md b/docs/developer/07_Installation/01_overview.md deleted file mode 100644 index 433d6fa..0000000 --- a/docs/developer/07_Installation/01_overview.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: overview -title: Overview -sidebar_label: Overview -sidebar_position: 1 ---- - -Below is the current QAT service side application set up, which is the recommended set up for future implementation on other servers. - - -## Source Code - -To get started with the source code, please look at the [Getting Started](/docs/developer/getting-started) guide. - -These are the main repositories for the QAT project: -1. [fasp-api](https://github.com/FASP-QAT/fasp-api) (Server-side project for QAT that runs the API's) -2. [fasp-core-ui](https://github.com/HSS-FASP-Team/fasp-core-ui/) (Client-side project for QAT) -3. [globalTables](https://github.com/HSS-FASP-Team/globalTables) (Tools to import the programs from Global Tables) -4. [ConvertPipelineToJson](https://github.com/FASP-QAT/ConvertPipelineToJson) (Tool to convert Pipeline to JSON) -5. [altiusUtilsMaven](https://github.com/FASP-QAT/AltiusUtilsMaven) (General purpose tools used across the fasp-api project) \ No newline at end of file diff --git a/docs/developer/07_Installation/02_fasp-api.md b/docs/developer/07_Installation/02_fasp-api.md deleted file mode 100644 index c46c81d..0000000 --- a/docs/developer/07_Installation/02_fasp-api.md +++ /dev/null @@ -1,233 +0,0 @@ ---- -id: fasp-api -title: Backend -sidebar_label: Backend -sidebar_position: 2 ---- - -# Backend Setup - -## Prerequisites -Before proceeding, ensure you have the following installed: -- MySQL 8 -- Git -- Java 17 -- jenv (Optional: for managing multiple Java versions) - -## Installation Steps - -1. **Clone the Repository** - ```bash - git clone git@github.com:FASP-QAT/fasp-api.git - cd fasp-api - ``` - - Please make sure that you have: - - An SSH key generated on your local machine - - The SSH key added to your GitHub account - - An SSH agent running on your local machine - -2. **Set up Application Directory Structure** - - Set temporary variables to specify the location of your code and application home folder: - - ```bash - QAT_CODE="$HOME/Code/QAT" - QAT_HOME="$HOME/Code/QAT/home" - ``` - - Note: these variables are temporary and are only used to set up the application - so it's not necessary to export them. - - Create application home folder: - ```bash - mkdir -p $QAT_HOME - ``` - - Extract the required folder structure: - ```bash - 7zz x docs/QATFolders.7z -o"$QAT_HOME" - ``` - - Configure application home path: - Edit `src/main/resources/application.properties` and set `qat.homeFolder` to the path of your application home folder (i.e. `QAT_HOME`). - - -3. **Setup MySQL Database** - - You can either use Docker to run MySQL 8, or run MySQL 8 as a service on your local machine. - - Depending on your choice, follow the instructions under 3a or 3b below. - - ***3a) Using Docker*** - - **Create a Docker network** - ```bash - docker network create qat-network - ``` - - **Start MySQL container** - ```bash - docker run --name qat-mysql \ - --network qat-network \ - -e MYSQL_ROOT_PASSWORD=root \ - -e MYSQL_DATABASE=fasp \ - -p 3306:3306 \ - -d mysql:8 - ``` - - **Create database and user** (__Optional__) - ```bash - docker exec -it qat-mysql mysql -uroot -proot - ``` - Then create the database and user: - ```sql - CREATE DATABASE IF NOT EXISTS `fasp` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin; - CREATE USER 'faspUser'@'%' IDENTIFIED BY 'faspP@ssw0rd'; - GRANT ALL PRIVILEGES ON fasp.* TO 'faspUser'@'%'; - GRANT CREATE VIEW, CREATE ROUTINE ON fasp.* TO 'faspUser'@'%'; - ``` - - :::info Note: - Run this command to set MySQL config to allow group by without an alias: - ```bash - docker exec -i qat-mysql mysql -uroot -proot fasp -e "SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));" - ``` - Note: This command will need to be run every time the container is restarted.The config should be added to the MySQL config file, but the default MySQL container does not have a config file. Once we are using docker compose we should be able to add this to the startup script, so it's not needed to be run manually. - ::: - - **Import database dumps** - ```bash - cd src/main/resources - 7zz x fasp-db.7z -o"$QAT_CODE" - docker exec -i qat-mysql mysql -uroot -proot fasp < "$QAT_CODE/fasp-db.sql" - ``` - - ***3b) Locally*** - - Navigate to the project's resource directory and extract the database dump: - ```bash - cd src/main/resources - 7zz x fasp-db.7z -o"$QAT_CODE" - ``` - - Set up the database and user: - ```bash - mysql -u root -p - ``` - Then run the following SQL commands: - ```sql - CREATE DATABASE IF NOT EXISTS `fasp` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin; - CREATE USER 'faspUser'@'%' IDENTIFIED BY 'faspP@ssw0rd'; - GRANT ALL PRIVILEGES ON fasp.* TO 'faspUser'@'%'; - GRANT CREATE VIEW, CREATE ROUTINE ON fasp.* TO 'faspUser'@'%'; - ``` - - Then import the database dumps: - ```bash - # Import main database structure - mysql -u root -p fasp < "$QAT_CODE/fasp-db.sql" - ``` - - Then add this line to my.conf, to allow group by without an alias, and restart MySQL: - ``` - sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION - ``` - - -:::info -Add a user to the application by running the following SQL script: -```sql -INSERT INTO fasp.us_user (REALM_ID, USERNAME, PASSWORD, EMAIL_ID, ORG_AND_COUNTRY, LANGUAGE_ID, ACTIVE, FAILED_ATTEMPTS, EXPIRES_ON, SYNC_EXPIRES_ON, LAST_LOGIN_DATE, CREATED_BY, CREATED_DATE, LAST_MODIFIED_BY, LAST_MODIFIED_DATE, AGREEMENT_ACCEPTED, DEFAULT_MODULE_ID, DEFAULT_THEME_ID, SHOW_DECIMALS) VALUES ('1', 'Test User', "$2a$10$wk103RbWjloLY4iuWATn0.0ifqnXfAKGpKM/NaeoWgGMwh8CeaCia", 'testuser@qat.com', 'Altius', '1', '1', '0', NOW(), '2024-11-26 11:15:22', '2024-11-26 11:15:22', '1', '2020-02-12 12:00:00', '1', '2024-11-20 08:44:46', '1', '2', '1', '0'); -SET @user_id=last_insert_id(); -INSERT INTO us_user_role VALUES(null,@user_id,'ROLE_INTERNAL_USER',1,NOW(),1,NOW()); -INSERT INTO us_user_acl VALUES(null,@user_id,'ROLE_INTERNAL_USER',null,null,null,null,1,NOW(),1,NOW()); -``` - -Login will be `testuser@qat.com` with password `pass`. -::: - -4. **Update the QAT properties** - Edit `qat.properties` and add the database connection properties: - - ```bash - vi $QAT_HOME/QAT/properties/qat.properties - ``` - - ```properties - spring.datasource.url=jdbc:mysql://localhost:3306/fasp?allowPublicKeyRetrieval=true&useSSL=false - spring.datasource.username=root - spring.datasource.password=root - ``` - - -5. **Configure Java Version (Optional)** - If you're using jenv to manage Java versions: - ```bash - jenv add - jenv local 17 - ``` - -6. **Build and Run the Application** - ```bash - ./mvnw clean spring-boot:run - ``` - - :::info Logs - To monitor the application logs: - ```bash - tail -f "$QAT_HOME/QAT/logs/qat/faspLogger.log" - ``` - ::: - -## Verify the API is running - -1. Open the following URLs in your browser: - - http://localhost:8084/actuator/health - - You should see a response similar to the following: - - ```json - { - "status": "UP" - } - ``` - -## Swagger / OpenAPI - -Access the Swagger UI at: - -* http://localhost:8084/swagger-ui/index.html - -Access the OpenAPI spec at: - -* http://localhost:8084/v3/api-docs (JSON) -* http://localhost:8084/v3/api-docs.yaml - -### Authenticate - -To use the API, you need to authenticate. To do so, follow these steps: - -To get an access token: - -1. Scroll to `jwt-authentication-rest-controller` -2. Open the `Post` `/authenticate` endpoint -3. Click "Try it out" -4. Enter your login details -5. Click "Execute" - -To use the token to authenticate your requests: - -6. Scroll to the top, click "Authorize" button -7. Enter token -8. Click "Authorise" - -Now you can use the Swagger API endpoints - -# Troubleshooting - -If you encounter any issues during the setup process, please check the following: -- Ensure all prerequisites are correctly installed -- Verify that the ports 3306 (MySQL) are not already in use -- Check the application logs for detailed error messages \ No newline at end of file diff --git a/docs/developer/07_Installation/03_fasp-core-ui.md b/docs/developer/07_Installation/03_fasp-core-ui.md deleted file mode 100644 index 0606d41..0000000 --- a/docs/developer/07_Installation/03_fasp-core-ui.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -id: fasp-core-ui -title: Frontend -sidebar_label: Frontend -sidebar_position: 3 ---- - -# Frontend Setup - -## Prerequisites - -Before you begin, ensure you have the following installed: -- Git -- Node.js 16 -- npm (Node Package Manager) -- nvm (Optional: for managing multiple Node.js versions) - -## Installation Steps - -1. **Clone the Repository** - ```bash - git clone git@github.com:FASP-QAT/fasp-core-ui.git - cd fasp-core-ui - ``` - - Please make sure that you have: - - An SSH key generated on your local machine - - The SSH key added to your GitHub account - - An SSH agent running on your local machine - -2. **Configure Node Version (Optional)** - If you're using nvm to manage Node.js versions: - ```bash - nvm install 16 - nvm use 16 - ``` - -3. **Install Dependencies** - ```bash - npm install --legacy-peer-deps - ``` - -4. **Start the Development Server** - ```bash - npm run dev - ``` - -5. **Configuration (Optional)** - To connect to a different backend server, modify the `API_URL` in `Constants.js`. The application is set up to connect to the live backend server by default. - -:::tip Login -To login to the application, you will need to create a new user in the backend. - -The instructions for creating a user are available in the [fasp-api](/docs/developer/installation/developer/fasp-api) installation guide, if you are running your own backend server. - -If you are connecting to the demo QAT server, you, you will need to request a new user account from the FASP team. -::: - -## Verify the application is running - -The application will be available at: -http://localhost:4202/ diff --git a/docs/developer/07_Installation/04_standard-installation.md b/docs/developer/07_Installation/04_standard-installation.md deleted file mode 100644 index c4de83f..0000000 --- a/docs/developer/07_Installation/04_standard-installation.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -id: standard-installation -title: Standard Installation -sidebar_label: Standard Installation -sidebar_position: 4 ---- - -# QAT Application Installation Guide - -## Prerequisites -- Java Runtime Environment -- Node.js server with npm -- MySQL database server -- Git -- PM2 (Node.js process manager) -- Access to FASP-QAT repositories - -## Pre-Installation Preparation - -### 1. Record Current Git Commit Hash -Before pulling the latest code, record the current commit hash for both the API and UI repositories. This will allow you to revert to the previous state if needed. - -1. Navigate to the API repository: - ```bash - cd /home/ubuntu/GitRepo/fasp-api - git rev-parse HEAD > /backup/fasp/api_last_commit_$(date +%Y%m%d_%H%M%S).txt - ``` - -2. Navigate to the UI repository: - ```bash - cd /home/ubuntu/GitRepo/fasp-core-ui - git rev-parse HEAD > /backup/fasp/ui_last_commit_$(date +%Y%m%d_%H%M%S).txt - ``` - -### 2. Backup Current Database -1. Connect to your MySQL database server -2. Back up your existing database: - ```bash - mysqldump -u [username] -p fasp > backup_$(date +%Y%m%d_%H%M%S).sql - ``` - -## Installation Steps - -### 1. Database Preparation -1. Connect to your MySQL database server -2. Execute all provided SQL scripts in sequential order: - ```bash - mysql -u [username] -p fasp < [script_name].sql - ``` - - -### 2. UI Installation -1. Navigate to the UI deployment directory: - ```bash - cd /home/ubuntu/GitRepo/fasp-core-ui - ``` - -2. Stop the existing UI service: - ```bash - pm2 stop QAT-React - ``` - -3. Get the latest code: - ```bash - git checkout master - git pull - ``` - -4. Install dependencies: - ```bash - npm install - ``` - -5. Start the UI service: - ```bash - pm2 start QAT-React - ``` - -6. Verify the service status: - ```bash - pm2 status - ``` - -7. Check logs if needed: - ```bash - pm2 log - ``` - -### 3. API Installation -1. Navigate to the API directory: - ```bash - cd /home/ubuntu/GitRepo/fasp-api - ``` - -2. Build and deploy the API: - ```bash - run sh buildAndDeploy.sh - ``` - -3. Check the API logs: - ```bash - tail -f /home/ubuntu/QAT/logs/qat/faspLogger.log - ``` - -### 4. Post-Installation Verification -1. Verify API endpoints are accessible -2. Verify UI is accessible through the browser -3. Perform basic functionality testing: - - User login - - Basic navigation - - Core features -4. Monitor logs for any errors: - - UI logs: `pm2 log` - - API logs: `tail -f faspLogger.log` - -## Troubleshooting -- If services fail to start, check the log files for specific error messages -- Ensure database connectivity is established -- Confirm all required ports are open and accessible -- Verify file permissions are set correctly -- If build fails: - - Check Git branch is correct - - Verify all dependencies are installed - - Check disk space availability - - Review build logs for specific errors \ No newline at end of file diff --git a/docs/developer/07_Installation/05_server-setup.md b/docs/developer/07_Installation/05_server-setup.md deleted file mode 100644 index 6768091..0000000 --- a/docs/developer/07_Installation/05_server-setup.md +++ /dev/null @@ -1,248 +0,0 @@ ---- -id: server-setup -title: Server Setup -sidebar_label: "Server Setup" -sidebar_position: 4 ---- - -# Server Setup - -## Suggested Server Setup - -The below diagram explains the setup that is the suggested setup for the QAT application. The current set up is with Amazon Web Services (AWS) . For access to the login for this, please contact [Support@quantificationanalytics.org](mailto:Support@quantificationanalytics.org). - -![Server Setup](/diagrams/server-setup.png) - -Figure 2: Relational Database Service (RDS) and Virtual Private Cloud (VPC) - -This is the suggested setup the user can choose to downgrade this as per requirements. On a minimum level ,the following components are required - -a. Load balancer or WebServer -b. Application Server -c. Database Server - -:::warning FIXME -This section needs to be updated as the versions are outdated. - -You can refer to the installation guides for [fasp-api](/docs/developer/installation/developer/fasp-api) and [fasp-core-ui](/docs/developer/installation/developer/fasp-core-ui) for more information on up to date versions for some of the dependencies. -::: - -## Operating system requirements - -**Application Server**: -The Application server requires a Linux based server preferably Ubuntu with at least ver 18.04LTS or higher. - -**Database Server**: -The Database server needs MySql v 5.7 - -## Other Software - -**Application Server**: - -1. Java JDK ver 11 - `sudo apt-get install openjdk-11-jdk-headless` - -2. Apache WebServer - `sudo apt-get install apache2` - -3. Node JS version 8.10 - `sudo apt-get install nodejs` - -4. PM2 - A production process manager for Node.js applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime and to facilitate common system admin tasks. - - `sudo npm install -g pm2` - -## Setup process - -### Application Server - -#### Apache server - -To setup Apache server use the following commands -`sudo apt-get install apache2` - -Copy the SSL Certificates into a folder called `/etc/apache2/ssl/` - -Create a file called `www.quantificationanalytics.org.conf` in the following folder `/etc/apache2/sites-available/` with the following contents: - -``` - - ServerName quantificationanalytics.org - ServerAlias www.quantificationanalytics.org - ServerAdmin info@altius.cc - ErrorLog /var/log/apache2/qat_error.log - - # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. - LogLevel warn - CustomLog /var/log/apache2/qat_access.log combined - - RewriteEngine On - RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} - - - - ServerName quantificationanalytics.org - ServerAlias www.quantificationanalytics.org - ServerAdmin info@altius.cc - - ErrorLog /var/log/apache2/qat_error.log - - # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. - LogLevel warn - CustomLog /var/log/apache2/qat_access.log combined - - ProxyRequests Off - ProxyPreserveHost On - ProxyPass / http://localhost:4202/ - - SSLEngine On - SSLCertificateFile /etc/apache2/ssl/WWW.QUANTIFICATIONANALYTICS.ORG.crt - SSLCertificateKeyFile /etc/apache2/ssl/www.quantificationanalytics.org.txt - SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown - - Header always set Strict-Transport-Security "max-age=63072000;" - Header always unset X-Frame-Options - Header set X-Frame-Options "SAMEORIGIN" - Header always set X-Content-Type-Options nosniff - Header set Feature-Policy: "fullscreen 'self'" - Header set Referrer-Policy: "no-referrer" - -``` - -Create a file called `api.quantificationanalytics.org.conf` in the following folder `/etc/apache2/sites-available/` with the following contents - -``` - - ServerAlias api.quantificationanalytics.org - ServerAdmin info@altius.cc - - ErrorLog /var/log/apache2/qatapi_error.log - - # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. - LogLevel warn - CustomLog /var/log/apache2/qatapi_access.log combined - - RewriteEngine On - RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} - - - - ServerAlias api.quantificationanalytics.org - ServerAdmin info@altius.cc - - ErrorLog /var/log/apache2/qatapi_error.log - - # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. - LogLevel warn - CustomLog /var/log/apache2/qatapi_access.log combined - - ProxyRequests Off - ProxyPreserveHost On - ProxyPass / ajp://localhost:8109/ - - SSLEngine On - SSLCertificateFile /etc/apache2/ssl/API.QUANTIFICATIONANALYTICS.ORG.crt - SSLCertificateKeyFile /etc/apache2/ssl/api.quantificationanalytics.org.txt - SSLCertificateChainFile /etc/apache2/ssl/DV_USERTrustRSACertificationAuthority.crt - - SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown - -``` - -To enable the modules required for Apache to work execute the following: -```bash -sudo a2enmod proxy proxy_ajp proxy_http rewrite ssl -``` - -To enable the sites you need to run the following command: -```bash -sudo a2ensite www.quantificationanalytics.org.conf -sudo a2ensite api.quantificationanalytics.org.conf -``` - -To restart the apache2 service and activate your new settings run the following command: -```bash -sudo systemctl restart apache2.service -``` - -### Node JS - -Run the following command to install Node JS: -```bash -curl \-sL https://deb.nodesource.com/setup\_12.x | sudo \-E bash \- -``` - -Run the following command to install Node JS: -```bash -sudo apt-get install \-y nodejs -``` - -Run the following command to update npm to the latest version: -```bash -sudo npm install npm@latest \-g -``` - -### PM2 - -:::warning FIXME -Add instructions for installing PM2 -::: - -### API Application - -To Install the application and run it on the Server download the compiled `QAT.war` file on to the Server `/home/ubuntu/qatApi` folder - -Make sure the `QAT.war` file is executable - -Create a service file in the `/etc/systemd/system/QATAPI.service` with the following content: - -``` -[Unit] -Description=QAT API - -[Service] -User=nobody -# The configuration file application.properties should be here: -WorkingDirectory=/home/ubuntu/qatApi -ExecStart=/usr/bin/java -Xmx256m -jar QATAPI.jar -SuccessExitStatus=143 -# TimeoutStopSec=10 -# Restart=on-failure -# RestartSec=5 - -[Install] -WantedBy=multi-user.target -``` - -Make sure that service file has 755 rights -```bash -sudo chmod 755 /etc/systemd/system/QATAPI.service -``` - -Reload the daemon services -```bash -sudo systemctl daemon-reload -``` - -You can now use the following commands to start, stop or restart the application - -To start the application -```bash -sudo systemctl start QATAPI.service -``` - -To stop the application -```bash -sudo systemctl stop QATAPI.service -``` - -To check the status of the application -```bash -sudo systemctl status QATAPI.service -``` - -To restart the application -```bash -sudo systemctl restart QATAPI.service -``` \ No newline at end of file diff --git a/docs/developer/07_Installation/06_rollback-procedure.md b/docs/developer/07_Installation/06_rollback-procedure.md index f2c05d7..deaba95 100644 --- a/docs/developer/07_Installation/06_rollback-procedure.md +++ b/docs/developer/07_Installation/06_rollback-procedure.md @@ -8,7 +8,9 @@ sidebar_position: 6 # QAT Application Rollback Procedure ## Prerequisites + Before starting rollback, ensure you have: + - Previous commit hashes (saved during installation) - Database backup (taken before installation) - Access to both API and UI repositories @@ -16,6 +18,7 @@ Before starting rollback, ensure you have: ## Rollback Steps ### 1. Database Rollback + 1. Connect to your MySQL database server 2. Restore the previous database backup: ```bash @@ -23,28 +26,34 @@ Before starting rollback, ensure you have: ``` ### 2. UI Rollback + 1. Navigate to the UI directory: + ```bash cd /home/ubuntu/GitRepo/fasp-core-ui ``` 2. Stop the UI service: + ```bash pm2 stop QAT-React ``` 3. Revert to previous commit: + ```bash git checkout $(cat /backup/fasp/ui_last_commit_$(date +%Y%m%d_%H%M%S).txt) ``` 4. Clean and reinstall dependencies: + ```bash rm -rf node_modules npm install ``` 5. Start the UI service: + ```bash pm2 start QAT-React ``` @@ -55,22 +64,27 @@ Before starting rollback, ensure you have: ``` ### 3. API Rollback + 1. Navigate to the API directory: + ```bash cd /home/ubuntu/GitRepo/fasp-api ``` 2. Stop the API service: + ```bash pm2 stop fasp-api ``` 3. Revert to previous commit: + ```bash git checkout $(cat /backup/fasp/api_last_commit_$(date +%Y%m%d_%H%M%S).txt) ``` 4. Rebuild and redeploy: + ```bash run sh buildAndDeploy.sh ``` @@ -81,7 +95,9 @@ Before starting rollback, ensure you have: ``` ### 4. Post-Rollback Verification + 1. Check service status: + ```bash pm2 status ``` @@ -93,15 +109,17 @@ Before starting rollback, ensure you have: - Basic navigation - Core features 5. Monitor logs for any errors: + ```bash # UI logs pm2 log QAT-React - + # API logs tail -f /home/ubuntu/QAT/logs/qat/faspLogger.log ``` ## Troubleshooting + - If services fail to start: - Check logs for specific error messages - Verify all dependencies are installed @@ -117,4 +135,4 @@ Before starting rollback, ensure you have: - If Git checkout fails: - Verify commit hash exists - Check for uncommitted changes - - Ensure proper repository access \ No newline at end of file + - Ensure proper repository access diff --git a/docs/developer/08_Guides/automated-test-backend.bkp b/docs/developer/08_Guides/automated-test-backend.bkp deleted file mode 100644 index 5f9f0c4..0000000 --- a/docs/developer/08_Guides/automated-test-backend.bkp +++ /dev/null @@ -1,169 +0,0 @@ -# Automated Testing - Backend - -This document serves as a guide for setting up, writing, and running automated tests for our project. It explains the frameworks, tools, and conventions used to ensure consistency and efficiency. - -## Table of Contents - -1. [Introduction](#introduction) -2. [Test Frameworks and Tools](#test-frameworks-and-tools) -3. [Test Structure and Conventions](#test-structure-and-conventions) -4. [Running Tests](#running-tests) -5. [Writing New Tests](#writing-new-tests) -6. [Code Coverage](#code-coverage) -7. [Continuous Integration (CI) Integration](#continuous-integration-ci-integration) -8. [Troubleshooting](#troubleshooting) -9. [References](#references) - -## Introduction - -Automated tests are a crucial part of our development workflow to ensure code quality and stability. We use a combination of unit tests, integration tests, and end-to-end (E2E) tests to cover all aspects of the application. - -### Test Categories - -- **Unit Tests**: Validate individual methods and classes. -- **Integration Tests**: Test how different components interact. - -## Test Frameworks and Tools - -### Backend - -- **JUnit**: Unit testing framework for Java. -- **Testcontainers**: Manages containerized dependencies (e.g., databases) for integration tests. -- **JaCoCo**: Tracks code coverage. - -### Utilities - -- **Maven Surefire Plugin**: Runs unit and integration tests. -- **JaCoCo Maven Plugin**: Measures test coverage. - -## Test Structure and Conventions - -The tests are organized into different categories based on their scope: - -```plaintext -src/ - main/ - java/ # Application code - test/ - java/ - cc/ - altius/ - FASP # Unit and integration tests - -``` -# Naming Conventions - -- **Test Classes**: Test classes should end with `Test` (e.g., `UserServiceTest`). -- **Test Methods**: Test methods should be descriptive (e.g., `shouldReturnUserById`). - -## Annotations (JUnit) - -- `@Test`: Marks a method as a test. -- `@BeforeAll` / `@BeforeEach`: Setup methods that run before tests. -- `@AfterAll` / `@AfterEach`: Cleanup methods that run after tests. - ---- - -# Running Tests - -## Backend - -- **Run all tests**: - ```bash - mvn clean test - ``` - -- **Run specific test class**: - ```bash - mvn -Dtest=UserServiceTest test - ``` -- **Run integration tests**: - ```bash - mvn verify - ``` - -## Writing New Tests - -### Backend (JUnit) -1. Create a test class in `src/test/java`. -2. Use mocks (e.g., with Mockito) to isolate components. - -#### Example: -```java -@Test -public void shouldReturnUserById() { - when(userRepository.findById(1)).thenReturn(Optional.of(new User(1, "John Doe"))); - User result = userService.getUserById(1); - assertEquals("John Doe", result.getName()); -} -``` -### Integration Tests (Using `AbstractIntegrationTest`) -`AbstractIntegrationTest` serves as a base class for integration tests in the application. It provides a common setup and teardown logic for integration tests, ensuring consistency across tests that require database interactions and HTTP request simulations. - -### Integrated Testing Utilities and Frameworks -This class integrates several testing utilities and frameworks: -- **Spring Boot Test Framework**: Utilizes `@SpringBootTest` for testing. -- **Testcontainers**: Manages a MySQL container for database operations during testing. -- **MockMvc**: Simulates HTTP requests and responses in the context of integration tests. -- **Dynamic Property Source**: Dynamically configures the database connection properties. - -### Inherited Functionality -By extending this class, tests automatically inherit the following: -- A preconfigured `MockMvc` instance for simulating HTTP requests. -- The necessary setup for a Testcontainers-managed MySQL container. -- Common utility methods like converting objects to JSON. -- Stops the MySQL container after all tests are completed. - - - -## Code Coverage -We aim for a low minimum threshold for existing code but at least 80% coverage for new classes. Ensure your tests cover: -- Edge cases -- Error handling -- Key workflows - -### To enforce coverage thresholds: -Configure JaCoCo in `pom.xml`: -```xml - - - CLASS - - - LINE - COVEREDRATIO - 0.80 - - - - -``` -## Continuous Integration (CI) Integration -Our CI pipeline (Jenkins/GitHub Actions) automatically runs tests on every push/PR. - -### Steps: -1. Run tests: Backend and frontend tests. -2. Generate coverage reports: Both JaCoCo and frontend reports. -3. Fail build on low coverage. - -## Troubleshooting - -### Common Issues -- **Testcontainers not starting**: Verify Docker is running and accessible. - -### Debugging Tips -- Use `mvn -X` for verbose logs. -- For flaky tests, isolate and re-run: - ```bash - mvn -Dtest=FlakyTest test - ``` - -## References -- [JUnit 5 Documentation](https://junit.org/junit5/docs/current/user-guide/) -- [Testcontainers](https://www.testcontainers.org/) -- [JaCoCo Maven Plugin](https://www.jacoco.org/) - -Feel free to extend this documentation as our testing strategy evolves! - - - diff --git a/docs/developer/08_Guides/automated-test-frontend.bkp b/docs/developer/08_Guides/automated-test-frontend.bkp deleted file mode 100644 index acab19a..0000000 --- a/docs/developer/08_Guides/automated-test-frontend.bkp +++ /dev/null @@ -1,275 +0,0 @@ -# Automated Testing - Frontend - -This document serves as a guide for setting up, writing, and running automated tests for our frontend project. It explains the frameworks, tools, and conventions used to ensure consistency and efficiency. - -## Overview -Automated tests are crucial for ensuring our React application's reliability and maintainability. We implement three levels of testing. - -- **Unit Tests**: Vitest for component and unit testing -- **E2E Tests**: Cypress for integration and end-to-end testing -- **CI Pipeline**: GitHub Actions for automated testing - -## Test Structure - -### Directory Layout -``` -├── src/ -│ ├── __tests__/ # Unit tests -│ │ ├── components/ # Component tests -│ │ └── unit/ # Utility function tests -├── cypress/ -│ ├── e2e/ # Integration tests -│ ├── fixtures/ # Test data -│ └── support/ # Custom commands & utilities -``` - -## Writing Tests - -### Unit Tests (Vitest) - -#### Component Test Example -```jsx -import { render, screen, fireEvent } from '@testing-library/react' -import { describe, it, expect, vi } from 'vitest' -import LoginForm from '../components/LoginForm' - -describe('LoginForm', () => { - it('should handle successful login', async () => { - const onSubmit = vi.fn() - render() - - // Fill form - await fireEvent.change(screen.getByLabelText('Username'), { - target: { value: 'testuser' } - }) - await fireEvent.change(screen.getByLabelText('Password'), { - target: { value: 'password123' } - }) - - // Submit form - await fireEvent.click(screen.getByRole('button', { name: /login/i })) - - // Assertions - expect(onSubmit).toHaveBeenCalledWith({ - username: 'testuser', - password: 'password123' - }) - }) - - it('should show validation errors', async () => { - render() - - // Submit empty form - await fireEvent.click(screen.getByRole('button', { name: /login/i })) - - // Check error messages - expect(screen.getByText('Username is required')).toBeInTheDocument() - }) -}) -``` - -#### Utility Test Example -```javascript -describe('RealmService', () => { - let service; - - beforeEach(() => { - service = new RealmService(); - }); - - test('should construct URL correctly', () => { - expect(service.getUrl()).toBe(`${API_URL}/api/realm`); - }); -}); -``` - -### E2E Tests (Cypress) - -#### Login Flow Example -```javascript -describe('Login Flow', () => { - beforeEach(() => { - cy.mockRealApiCalls(); - }) - - it('should login successfully', () => { - cy.login('correctuser@qat.info', 'password'); - cy.url().should('include', '/#/ApplicationDashboard'); - }) - - it('should handle login errors', () => { - cy.intercept('POST', `${API_URL}/authenticate`, { - statusCode: 401, - body: { messageCode: 'static.message.login.invalidCredentials' } - }).as('loginRequest'); - - cy.login('wrong@email.com', 'wrongpass'); - cy.contains('Incorrect login or password').should('be.visible'); - cy.url().should('include', '/#/login'); - }) -}) -``` - -## Testing Standards - -### Unit Tests -1. **Naming Convention** - - Test files: `*.test.{js,jsx}` - - Test suites: Describe the component/function - - Test cases: Start with "should" and describe expected behavior - -2. **Component Testing** - - Test user interactions - - Test rendering logic - - Test prop changes - - Test error states - - Use React Testing Library queries in this order: - 1. getByRole - 2. getByLabelText - 3. getByText - 4. getByTestId (last resort) - -3. **Mocking** - - Mock external dependencies - - Use `vi.mock()` for module mocks - - Use `vi.fn()` for function mocks - - Reset mocks between tests - - Keep mocks minimal: - - If your test requires more than 2-3 mocks, this is often a code smell - - Consider either: - - Refactoring the component to reduce dependencies - - Writing an integration test instead of a unit test - - Breaking down the component into smaller, more focused pieces - -### E2E Tests -1. **Structure** - - Group related tests in a single spec file - - Use descriptive test names - - Setup test data in `beforeEach` - - Clean up after tests - -2. **Best Practices** - - Mock API responses for consistent tests - - Use custom commands for common operations - - Add data-testid for stable selectors - - Test the happy path first, then edge cases - -3. **Custom Commands** - ```javascript - // cypress/support/commands.js - Cypress.Commands.add('login', (email = 'test@example.com', password = 'password123') => { - cy.visit('/#/login', { - onBeforeLoad: (win) => { - win.WebSocket = undefined; - } - }); - cy.window().then((win) => { - win.localStorage.setItem('loginOnline', 'true'); - win.localStorage.setItem('sessionTimedOut', '0'); - win.localStorage.setItem('sessionChanged', '0'); - win.localStorage.setItem('lastLoggedInUsersLanguageChanged', 'false'); - }); - // Fill in the login form and submit - cy.get('#emailId').should('be.visible').type(email); - cy.get('#password').should('be.visible').type(password); - cy.get('button[type="submit"]').should('be.visible').click(); - }); - ``` - -## Running Tests - -### Unit Tests -```bash -npm test # Run tests in watch mode -npm run test:coverage # Run tests with coverage -npm run test:ui # Run tests with UI -``` - -### E2E Tests -```bash -npm run cypress:open # Open Cypress UI -npm run cypress:run # Run Cypress headless -npm run test:e2e # Start dev server and run Cypress -``` - -### All Tests -```bash -npm run test:all # Run both unit and E2E tests -``` - -## CI/CD Pipeline -- Runs on every push (excluding documentation changes) -- Sequential execution: unit tests → E2E tests → coverage reporting -- Artifacts: test videos and screenshots available on failure -- Coverage reports sent to Code Climate - -### Coverage Requirements -- Minimum overall coverage: 80% -- Minimum function coverage: 80% -- Minimum branch coverage: 75% - -## Debugging Tests - -### Unit Tests -- Use `test.only()` to run specific tests -- Use `console.log()` or `debug()` from Testing Library -- Check test coverage with `npm run test:coverage` - -### E2E Tests -- Use `cy.pause()` to pause test execution -- Use `.debug()` to inspect elements -- Check screenshots and videos in `cypress/screenshots` and `cypress/videos` -- Use Cypress UI for step-by-step debugging - -## Common Issues & Solutions - -### Unit Tests -1. **Async Updates** - ```javascript - // Wrong - fireEvent.click(button) - expect(result).toBe('updated') - - // Correct - await fireEvent.click(button) - await waitFor(() => { - expect(result).toBe('updated') - }) - ``` - -2. **Component Re-renders** - ```javascript - // Wrong - const { rerender } = render() - rerender() - - // Correct - const { rerender } = render() - rerender() - ``` - -### E2E Tests -1. **Race Conditions** - ```javascript - // Wrong - cy.get('.loading').should('not.exist') - cy.get('.content') - - // Correct - cy.get('.loading', { timeout: 10000 }).should('not.exist') - cy.get('.content').should('be.visible') - ``` - -## Contributing -1. Write tests for new features -2. Update tests for modified features -3. Ensure all tests pass locally before pushing -4. Follow the testing standards outlined above -5. Include updated test coverage reports - -## References -- [Vitest Documentation](https://vitest.dev/) -- [Testing Library](https://testing-library.com/docs/react-testing-library/intro/) -- [Cypress](https://docs.cypress.io/app/get-started/why-cypress) - -Feel free to extend this documentation as our testing strategy evolves! diff --git a/docs/developer/08_Guides/country-dashboards.md b/docs/developer/08_Guides/country-dashboards.md deleted file mode 100644 index fae4329..0000000 --- a/docs/developer/08_Guides/country-dashboards.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -id: country-dashboards -title: Country Dashboards -sidebar_label: Country Dashboards -sidebar_position: 3 ---- - -# Country Dashboards - -Integration with Country Dashboard - -A new functionality that allows Countries to pull completed Supply Plans for one Program at a time has just been introduced. - -The full documentation for this Integration is available in the following [file](https://github.com/FASP-QAT/fasp-api/blob/a271980e12637d6a31f4d87560df85a88789ee6e/docs/API%20Documentation%20for%20Dashboard%20integration%20v1.31.pdf) \ No newline at end of file diff --git a/docs/developer/08_Guides/flyway.bkp b/docs/developer/08_Guides/flyway.bkp deleted file mode 100644 index e79c28f..0000000 --- a/docs/developer/08_Guides/flyway.bkp +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Flyway Database Migration ---- - -# Flyway Database Migration - -Flyway is a database migration tool that helps manage database schema changes in a version-controlled, reliable way. - -## Why We Use It -- Version control for database schemas -- Consistent database state across all environments -- Automated, repeatable migrations -- Tracks migration history - -## How It Works -Flyway looks for migration files in the `db/migration` directory and executes them in version order. - -### Migration File Naming -``` -V1__Description_of_change.sql -│ │ └─ Descriptive text of the change -│ └─── Double underscore separator -└───── Version number (must be a number and must be unique) -``` - -### Repeatable Migrations -Repeatable migrations are used to apply changes to the database schema that do not require a version number. - -``` -R__Description_of_change.sql -│ │ └─ Descriptive text of the change -│ └─── Double underscore separator -└───── Repeatable migration name -``` - -These migrations are executed in the database every time their checksum changes. - -They are useful for applying changes to the database schema that do not require a version number. - -For example, views, stored procedures, etc. - -### Common Commands -- `migrate`: Apply pending migrations -- `clean`: Remove all objects from the schema -- `info`: Show migration status/history -- `validate`: Verify migrations and checksums -- `repair`: Fix migration history table -- `baseline`: Baseline an existing database -- `undo`: Revert most recent migration (Pro edition) - -Commands can be executed using Maven: -```bash -mvn flyway:migrate -mvn flyway:clean -mvn flyway:info -mvn flyway:validate -mvn flyway:repair -mvn flyway:baseline -``` - -Add the database credentials to the above commands. - -E.g. -``` -./mvnw flyway:info -Dflyway.url=jdbc:mysql://localhost:3306/fasp -Dflyway.user=root -Dflyway.password=root -``` - -### Best Practices -1. Never modify an existing migration file -2. Always test migrations before applying to production -3. Use descriptive names for migration files -4. Keep migrations idempotent when possible -5. Add new migration files to the end of the list -6. Do not delete migration files - -### Troubleshooting -Common issues and solutions: -- **Checksum mismatch**: Use `flyway:repair` if you're sure the change is intended -- **Failed migration**: Fix the issue in a new migration, don't modify the failed one -- **Out of order**: Enable `outOfOrder` property if you need to apply an older version -- **Connection issues**: Verify database credentials and network connectivity - - -### Further Reading -- [Flyway Documentation](https://documentation.red-gate.com/fd) -- [Flyway Concepts](https://documentation.red-gate.com/fd/flyway-concepts-271583830.html) -- [Flyway Best Practices](https://documentation.red-gate.com/fd/recommended-practices-150700352.html) diff --git a/docs/developer/08_Guides/intro.md b/docs/developer/08_Guides/intro.md deleted file mode 100644 index c2ec926..0000000 --- a/docs/developer/08_Guides/intro.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -id: overview -title: Guides -sidebar_label: Overview -sidebar_position: 1 ---- - -# Guides - -This section provides guides for developers working on the QAT project. Please refer to the individual pages for more information, using the sidebar on the left. diff --git a/docs/developer/08_Guides/r-reports.md b/docs/developer/08_Guides/r-reports.md deleted file mode 100644 index 3d81abb..0000000 --- a/docs/developer/08_Guides/r-reports.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: r-reports -title: R Reports -sidebar_label: R Reports -sidebar_position: 2 ---- - -# Running R based reports - -Please follow the below steps to install R application required for running ARIMA based reports. - -```bash -$ sudo apt update -$ sudo apt install libsodium-dev -$ sudo apt-get install libcurl4-openssl-dev -$ sudo apt install r-base -``` - -After installing R application type R in command prompt to launch the console of R application as given below. - -```bash -$ R -``` - -Once you enter the console of R application you need to install Plumber and forecast packages. Given below are the steps. - -```bash -install.packages("plumber") -install.packages("forecast") -``` - -You can run the R application with below command. - -```bash -plumber::plumb(file='/root/Documents/GitRepo/Rprojects/api_arima.r')$run(host="0.0.0.0", port=8000) -``` - -After running R application go to Postman application and enter below line in post column and enter the details. - -[http://server-ipaddress:8000/tes](http://server-ipaddress:8000/tes) - diff --git a/docs/user/00-introduction.md b/docs/user/00-introduction.md deleted file mode 100644 index b3f2b94..0000000 --- a/docs/user/00-introduction.md +++ /dev/null @@ -1,1173 +0,0 @@ ---- -id: introduction -title: "Introduction" -sidebar_label: "Introduction" -sidebar_position: 0 ---- - -Welcome to the User Documentation for the QAT. This section is aimed at users of the QAT. Both end-users and more technical users will find useful information here. - -**Document details:** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-

- Version (date) -

-

- Author/Editor -

- 		- Notes & Major Changes -
-

0 (Jan 27, 2021)

-

Altius & FHI 360

- 		Initial draft
-

1 (Mar 15, 2021)

-

GHSC-PSM FASP

- 		- Restructured document so all realm & app admin functions are moved - to annex, formatting changes, editing for clarity -
-

2 (Apr 26, 2021)

-

GHSC-PSM FASP

- 		-
    -
  • -

    Updated to reflect software changes:

    -
    • -
-
    -
  • -

    Section 2.E – updated to include password expiry rules

    -
    • -
  • -

    - Section 5.A – updated screenshots and language for actual vs. - projected inventory differentiation -

    -
    • -
  • -

    - Section 6.A – QAT Problem List - added summary table, updated - logic, and problem category column -

    -
    • -
-
-

3 (June 10, 2021)

-

GHSC-PSM FASP

- 		-
    -
  • -

    Improved formatting (section numbering and footer)

    -
    • -
  • -

    - Added reminders for master data sync and offline/online throughout - manual -

    -
    • -
  • -

    Updated to reflect software changes:

    -
    • -
-
    -
  • -

    - Section 4.B.3 – updated language for auto pop-up of batch info -

    -
    • -
  • -

    - Section 4.B.4 – added ERP Linking instructions & screenshots -

    -
    • -
  • -

    - Section 4.A.3 – alternate reporting unit added (moved up from - Annex 1) -

    -
    • -
  • -

    - Section 5.C.1 & 5.C.2 – updated logic for suggested shipments - and added recalculate button for supply planning -

    -
    • -
  • -

    Section 5.D – added final inventory batch information pop-up

    -
    • -
  • -

    Section 5.E – added batch ledger

    -
    • -
-
4 (Oct 15, 2021) GHSC-PSM FASP -
    -
  • -

    Updated to reflect software changes:

    -
      -
    • -
      -

      - Section 4.A.1 – updated language for multi-selecting - technical areas -

      -
      -
      • -
    • -
      -

      - Annex 1 Section H – updated user requirement to include - “organization & country” descriptor -

      -
      -
      • -
    • -
      -

      - Annex 1 Section G – added language and instructions on - Organization Type for realm-level master data -

      -
      -
      • -
    -
    • -
-
-

5 (Feb 13, 2023)

-

GHSC-PSM FASP

- 		-
    -
  • -

    Updated to include the Forecasting Module throughout manual

    -
    • -
  • -

    Updated to reflect software changes:

    -
      -
    • -
      -

      - Section 2.E – included online/offline button functionality -

      -
      -
      • -
    • -
      -

      - Section 2.H.3 – added troubleshooting for network errors -

      -
      -
      • -
    • -
      -

      - Section 2.I – updated information on managing HelpDesk - tickets in Jira -

      -
      -
      • -
    • -
      -

      - Section 3.D & 6.A.1 – added Manual Problem description -

      -
      -
      • -
    • -
      -

      - Section 3.E – updated to include unencrypted/encrypted JSON - explanation for exports -

      -
      -
      • -
    • -
      -

      - Section 4.A.2, 5.A, 6.A.3, 6.C.2, & 6.C.3 – updated to - include explanation and functions of the minimum quantity - parameter -

      -
      -
      • -
    • -
      -

      - Section 4.B.3 – included explanation on strategic calculator - & emergency shipments -

      -
      -
      • -
    • -
      -

      - Section 4.B.4 – added instructions and screenshots for the - new ERP Linking functionality -

      -
      -
      • -
    • -
      -

      Section 4.C.3 – added QAT Forecast Import functionality

      -
      -
      • -
    • -
      -

      - Section 5.F – updated to include Replan Supply Plan scenario -

      -
      -
      • -
    • -
      -

      - Section 6.E.1 & 6.E.2 – included explanation on - Procurement Agent-specific dropdowns & Procurement Agent - Type groupings -

      -
      -
      • -
    • -
      -

      - Section 6.E.3 – added editing functionality to Shipment - Details Report -

      -
      -
      • -
    • -
      -

      - Annex 2 – added Business Rules relevant to the Forecasting - Module -

      -
      -
      • -
    -
    • -
-
- 6 (Feb 16, 2023) -
- GHSC-PSM FASP - 		-
    -
  • -

    Updated PMI logo

    -
    • -
-
-

7 (Nov 09, 2023)

-

GHSC-PSM

- 		-
    -
  • -

    Updated to reflect software changes:

    -
      -
    • -
      -

      - Replaced Commit/Load language with Upload/Download - throughout the manual -

      -
      -
      • -
    • -
      -

      - Section 3.B – Added clarification to the redownload pop-up - notification -

      -
      -
      • -
    • -
      -

      - Section 3.C – Updated functionality on merging forecast - during upload process -

      -
      -
      • -
    • -
      -

      - Section 3.D – Replaced ‘Rejected’ language with ‘Needs - Revision’ -

      -
      -
      • -
    • -
      -

      - Section 4.A.1 – Added Road transport as a shipping modality; - updated the ability for Program Admins to add/remove/edit - Procurement Agents to their program -

      -
      -
      • -
    • -
      -

      - Section 4.A.4 – Added Road transport as a shipping modality -

      -
      -
      • -
    • -
      -

      - Section 4.A.6 – Updated to include tagging multiple programs - to a single budget -

      -
      -
      • -
    • -
      -

      - Section 4.B.1 – Updated to include multi-select PUs to enter - consumption data -

      -
      -
      • -
    • -
      -

      - Section 4.B.2 - Updated to include the ability to enter - multi-select PUs to enter inventory/adjustment data & - other new functionalities -

      -
      -
      • -
    • -
      -

      - Section 4.B.3 – Updated to include various changes (i.e. - multi-select PUs, road transport, blank freight cost, etc.) - to the shipment data entry functionality -

      -
      -
      • -
    • -
      -

      - Section 4.C.3 – Added new functionality of rounding - residuals when importing forecasted consumption to the - supply planning module -

      -
      -
      • -
    • -
      -

      - Section 5.A – Updated to include the combined shipment rows, - the ability to view actual consumption in graph, & AMC - calculation to have decimals -

      -
      -
      • -
    • -
      -

      - Section 5.C, 5.C.1, & 5.C.2 – Updated to include the - combined shipment rows & streamlined shipment pop-up -

      -
      -
      • -
    • -
      -

      - Section 5.E – Updated expiry logic to ‘best case scenario’ -

      -
      -
      • -
    • -
      -

      - Section 5.G – Updated to include various changes to the - Supply Plan Report (i.e. including order no., multi-select - PUs, forecasted consumption in graph, etc.) -

      -
      -
      • -
    • -
      -

      - Section 6.D.1 & 6.D.3 – Includes new Forecast Error - Report & functionalities -

      -
      -
      • -
    • -
      -

      Section 6.E.6 – Includes updates to Budget Report

      -
      -
      • -
    • -
      -

      - Section 6.F.1 – Added details on the ‘Total Cost of Expiry’ - in Expiry Report -

      -
      -
      • -
    • -
      -

      - Section 6.F.3 – Includes new Inventory Turns Report & - functionalities -

      -
      -
      • -
    • -
      -

      - Section 8.A.3 – Added clarification on r-squared calculation -

      -
      -
      • -
    • -
      -

      - Section 8.B.1, 8.B.1.a, 8.B.1.b – Includes changes to - forecasting trees, such as: duplicate across trees, - expand/collapse tree, branch templates, discrete/continuous - icons, auto-calculate button, PU validation flag -

      -
      -
      • -
    • -
      -

      - Section 8.B.1.e – Remove multi-month dispensing - functionality -

      -
      -
      • -
    • -
      -

      - Section 8.B.2 – Includes annual forecasting quantities to - modeling validation -

      -
      -
      • -
    • -
      -

      - Section 8.B.4.a & 8.B.4.b – Added branch template - functionality & various updates to tree templates -

      -
      -
      • -
    • -
      -

      - Annex 1 – Added information on variable settings & data - restrictions, and updated user/access roles functionality -

      -
      -
      • -
    • -
      -

      - Annex 2 – Updated business rules and calculations for unmet - demand, expiry logic, total cost of expiry, & inventory - turns -

      -
      -
      • -
    • -
      -

      - Annex 3 & 4 – Updated the ability for Program Admins to - add/remove/edit Procurement Agents to their program -

      -
      -
      • -
    -
    • -
-
8 (Dec. 31, 2024) GHSC-PSM -
    -
  • -

    Updated to reflect software changes:

    -
      -
    • -
      -

      - Section 1.E & 1.E.2 – Updated definitions to align with - new enhancements -

      -
      -
      • -
    • -
      -

      - Section 2.C – Includes ability to assign different roles to - a single user -

      -
      -
      • -
    • -
      -

      - Section 2.E – Updated to include the new HelpDesk icon on - the login page -

      -
      -
      • -
    • -
      -

      - Section 2.G – Clarified language on version releases and QAT - software updates -

      -
      -
      • -
    • -
      -

      - Section 2.H.2 – Includes new images of the enhanced supply - planning dashboard -

      -
      -
      • -
    • -
      -

      - Section 2.I.1, 2.I.3, 2.J, & 2.K – Includes new images - of the enhanced supply planning dashboard, new HelpDesk - icons on the login and homepage, and updated menu items -

      -
      -
      • -
    • -
      -

      - Section 2.L – New section added to explain the enhanced QAT - supply planning dashboard and it’s components -

      -
      -
      • -
    • -
      -

      - Section 3.B & 3.E – Includes the new functionality of - downloaded programs with a subset of data to reduce program - file size -

      -
      -
      • -
    • -
      -

      - Section 3.D & 6.C.1 – Updated to include version notes - and the new supply plan status: No Review Needed -

      -
      -
      • -
    • -
      -

      - Section 3.F – Clarified the import process with a two-step - progress bar -

      -
      -
      • -
    • -
      -

      - Section 4.A.1 – Updated to include the ability for Program - Admins to add/remove funding sources -

      -
      -
      • -
    • -
      -

      - Section 4.A.2 & 7.D – Updated the screen to include - aesthetic changes and an additional column for FU:PU - conversion factor -

      -
      -
      • -
    • -
      -

      - Section 4.A.3 & 4.A.5 – Added screen for PA-specific - freight % and lead times -

      -
      -
      • -
    • -
      -

      - Section 4.A.4 – Updated to include the ability to either - multiply or divide by a conversion factor for PU:ARU to - account for rounding issues -

      -
      -
      • -
    • -
      -

      - Section 4.B.2 – Added ability to tag batches to inventory - counts -

      -
      -
      • -
    • -
      -

      - Section 4.B.3, 5.C, 5.C.1, & 5.C.2 – Updated screenshots - and information on program-specific PAs and Funding Sources, - improved over-budget pop-up message, new feature for - auto-calculating or manually overriding freight cost, and - various tooltips -

      -
      -
      • -
    • -
      -

      - Section 4.B.4 – Updated screenshots to indicate missing - fields in ERP Linking -

      -
      -
      • -
    • -
      -

      - Section 4.C.3 – Included auto-fill “do not import” ability - in QAT Import screen -

      -
      -
      • -
    • -
      -

      - Section 5.A – Updated screenshots with ability to view in - ARU, new version notes field, and new SOH legend -

      -
      -
      • -
    • -
      -

      - Section 5.D & 5.E – Added ability to tag batches to - inventory counts and the new calculation for - auto-adjustments -

      -
      -
      • -
    • -
      -

      - Section 5.F – Updated with new scenario: phase-in/out and - remove all planned shipments -

      -
      -
      • -
    • -
      -

      - Section 5.G – Included new “views” available in the SP - Report: single program, multi-program, or EU -

      -
      -
      • -
    • -
      -

      - Section 6.C.1, 6.D.3, & 6.D.4 – Includes new PU-specific - forecast error threshold percentage -

      -
      -
      • -
    • -
      -

      - Section 6.E.2 – Updated screenshots and explanation on - Funder Type, as well as added percentages to pie chart -

      -
      -
      • -
    • -
      -

      - Section 6.E.5 – Added CSV export for Shipment Cost Overview - report -

      -
      -
      • -
    • -
      -

      - Section 8.A.1 – Added ability to import multiple supply - plans into single forecast, import with different regions, - and auto-fill “do not import” ability -

      -
      -
      • -
    • -
      -

      - Section 8.A.3 – Updated with bulk extrapolation feature and - optimized parameters for ARIMA/TES -

      -
      -
      • -
    • -
      -

      - Section 8.B.1 – Updated screenshot to include ‘Last Updated - By’ column -

      -
      -
      • -
    • -
      -

      - Section 8.B.1.a, b, c, d, & f – Updated to include - copy/move feature, tree table, reordering branches, - inactivating scenarios, seasonality in % nodes, hourglass - node, calculating discrete differently, and aesthetic - updates to PU node -

      -
      -
      • -
    • -
      -

      - Section 9.A – Updated to include aesthetic changes to - Compare and Select screen, as well as ability to choose - multiple tree forecasts and view annual data -

      -
      -
      • -
    • -
      -

      - Annex 1.B – Updated with new enhanced supply planning - dashboard features -

      -
      -
      • -
    • -
      -

      - Annex 1.C.2 – Added realm-level ability to view programs - using specific FU/PUs -

      -
      -
      • -
    • -
      -

      - Annex 1.D – Updated with program-specific funding sources - & PAs -

      -
      -
      • -
    • -
      -

      - Annex 1.E – Added new realm-level functionality of resetting - the QPL regardless of approval status -

      -
      -
      • -
    • -
      -

      - Annex 2 – Updated business rules and calculations for - auto-adjustments, importing multiple supply plans into - single forecast, and aggregating multiple tree forecasts -

      -
      -
      • -
    • -
      -

      - Annex 3 & 4 – Updated the ability for Program Admins to - add/remove/edit Funding Sources their program, ability for - users to have multiple roles in QAT, and new access for - Forecast Viewers -

      -
      -
      • -
    -
    • -
-
- -\*\* -\*\* - -**Table of Contents** - -[Acronyms 9](15-acronyms.md#) - -[Section 1. Overview 10](01-overview.md#overview) - -[A. Introduction 10](01-overview.md#introduction) - -[B. Forecasting vs. Supply Planning 10](01-overview.md#forecasting-vs-supply-planning) - -[C. What is QAT and What Can It Do for You? 10](01-overview.md#what-is-qat-and-what-can-it-do-for-you) - -[D. Who Should Use QAT? 11](01-overview.md#who-should-use-qat) - -[E. Important QAT Concepts and Terms 12](01-overview.md#important-qat-concepts-and-terms) - -[E1. Cross-cutting terms 12](01-overview.md#cross-cutting-terms) - -[E2. Supply Planning Terms 12](01-overview.md#supply-planning-terms) - -[E3. Forecasting Terms 15](01-overview.md#forecasting-terms) - -[Section 2. Getting Started 16](02-getting-started.md#getting-started) - -[A. System Requirements 16](02-getting-started.md#system-requirements) - -[B. Levels of Hierarchy in QAT 16](02-getting-started.md#levels-of-hierarchy-in-qat) - -[C. User Roles and Permissions 17](02-getting-started.md#user-roles-and-permissions) - -[D. How to Log into QAT and Install the Progressive Web Application (PWA) 17](02-getting-started.md#how-to-log-into-qat-and-install-the-progressive-web-application-pwa) - -[E. How to Log into QAT for Existing Users 19](02-getting-started.md#how-to-log-into-qat-for-existing-users) - -[F. Working Offline 21](02-getting-started.md#working-offline) - -[G. QAT Release Updates 22](02-getting-started.md#qat-release-updates) - -[H. Troubleshooting 23](02-getting-started.md#troubleshooting) - -[H1. When and How to Conduct an Application Refresh 23](02-getting-started.md#when-and-how-to-conduct-an-application-refresh) - -[H2. When and How to Conduct a Full Master Data Sync (MDS) 24](02-getting-started.md#when-and-how-to-conduct-a-full-master-data-sync-mds) - -[H3. When and How to Clear Site Data 24](02-getting-started.md#when-and-how-to-clear-site-data) - -[H4. Troubleshooting Network Errors 25](02-getting-started.md#troubleshooting-network-errors) - -[I. QAT Helpdesk and Tickets 26](02-getting-started.md#qat-helpdesk-and-tickets) - -[I1. Tickets for Adding/Updating Users and Master Data 26](02-getting-started.md#tickets-for-addingupdating-users-and-master-data) - -[I2. Requesting a Change 28](02-getting-started.md#requesting-a-change) - -[I3. Reporting a Bug 29](02-getting-started.md#reporting-a-bug) - -[I4. Managing Tickets 30](02-getting-started.md#managing-tickets) - -[J. Navigation and Menu Bar 31](02-getting-started.md#navigation-and-menu-bar) - -[K. Changing Language 36](02-getting-started.md#changing-language) - -[L. QAT Dashboard 37](02-getting-started.md#qat-dashboard) - -[Section 3. Managing Programs and Versions 43](03-managing-programs-and-versions.md#managing-programs-and-versions) - -[A. Working with Program Data 43](03-managing-programs-and-versions.md#working-with-program-data) - -[B. Download/Delete 43](03-managing-programs-and-versions.md#downloaddelete) - -[C. Upload 46](03-managing-programs-and-versions.md#upload) - -[D. Supply Plan Version and Review (Supply Plan Module Only) 52](03-managing-programs-and-versions.md#supply-plan-version-and-review-supply-plan-module-only) - -[E. Export 55](03-managing-programs-and-versions.md#export) - -[F. Import 56](03-managing-programs-and-versions.md#import) - -[G. Version Comparison 57](03-managing-programs-and-versions.md#version-comparison) - -[Section 4. Supply Planning Module: Program Data 59](04-supply-planning-module-program-data.md#supply-planning-module-program-data) - -[A. Background Data 59](04-supply-planning-module-program-data.md#background-data) - -[A1. Program Information 59](04-supply-planning-module-program-data.md#program-information) - -[A2. Planning Units 61](04-supply-planning-module-program-data.md#planning-units) - -[A3. Program/Procurement Agent-specific Information 63](04-supply-planning-module-program-data.md#programprocurement-agent-specific-information) - -[A4. Alternate Reporting Units 65](04-supply-planning-module-program-data.md#alternate-reporting-units) - -[A5. Default Lead Times 66](04-supply-planning-module-program-data.md#default-lead-times) - -[A6. Budgets 68](04-supply-planning-module-program-data.md#budgets) - -[B. Transactional Supply Plan Data 69](04-supply-planning-module-program-data.md#transactional-supply-plan-data) - -[B1. Consumption Data 70](04-supply-planning-module-program-data.md#consumption-data) - -[B2. Inventory Data 72](04-supply-planning-module-program-data.md#inventory-data) - -[B3. Shipment Data 74](04-supply-planning-module-program-data.md#shipment-data) - -[B4. ERP Shipment Linking 77](04-supply-planning-module-program-data.md#erp-shipment-linking) - -[C. Importing Data for Supply Planning 84](04-supply-planning-module-program-data.md#supply-plan-data-excel-import-templates) - -[C1. Supply Plan Data Excel Import Templates 84](04-supply-planning-module-program-data.md#supply-plan-data-excel-import-templates) - -[C2. Quantimed Forecast Import 86](04-supply-planning-module-program-data.md#quantimed-forecast-import) - -[C3. QAT Forecast Import 88](04-supply-planning-module-program-data.md#qat-forecast-import) - -[Section 5. Supply Planning Module: Supply Planning 92](05-supply-planning-module-supply-planning.md#supply-planning-module-supply-planning) - -[A. Supply Planning: An Overview 92](05-supply-planning-module-supply-planning.md#supply-planning-an-overview) - -[B. Supply Planning: Consumption 97](05-supply-planning-module-supply-planning.md#supply-planning-consumption) - -[C. Supply Planning: Shipments 98](05-supply-planning-module-supply-planning.md#supply-planning-shipments) - -[C1. Updating an Existing Shipment 99](05-supply-planning-module-supply-planning.md#updating-an-existing-shipment) - -[C2. Creating a New Shipment 101](05-supply-planning-module-supply-planning.md#creating-a-new-shipment) - -[D. Supply Planning: Inventory/Adjustments 104](05-supply-planning-module-supply-planning.md#supply-planning-inventoryadjustments) - -[E. Supply Planning: Project Expired Stock and Batch Information 108](05-supply-planning-module-supply-planning.md#supply-planning-project-expired-stock-and-batch-information) - -[F. Scenario Planning 109](05-supply-planning-module-supply-planning.md#scenario-planning) - -[G. Supply Plan Report 110](05-supply-planning-module-supply-planning.md#supply-plan-report) - -[Section 6. Supply Planning Module: Reports 114](06-supply-planning-module-reports.md#supply-planning-module-reports) - -[A. QAT Problem List 114](06-supply-planning-module-reports.md#qat-problem-list) - -[A1. QAT Problem List Basics 115](06-supply-planning-module-reports.md#qat-problem-list-basics) - -[A2. Closing and Addressing Problems 116](06-supply-planning-module-reports.md#closing-and-addressing-problems) - -[A3. QAT Problem List: Explanation of Problems 117](06-supply-planning-module-reports.md#qat-problem-list-explanation-of-problems) - -[B. Program Catalog 120](06-supply-planning-module-reports.md#program-catalog) - -[C. Stock Status Reports 121](06-supply-planning-module-reports.md#stock-status-reports) - -[C1. Stock Status Over Time 121](06-supply-planning-module-reports.md#stock-status-over-time) - -[C2. Stock Status Matrix 121](06-supply-planning-module-reports.md#stock-status-matrix) - -[C3. Stock Status Snapshot 122](06-supply-planning-module-reports.md#stock-status-snapshot) - -[C4. Stock Status Snapshot (Global) 123](06-supply-planning-module-reports.md#stock-status-snapshot-global) - -[D. Consumption Reports 124](06-supply-planning-module-reports.md#consumption-reports) - -[D1. Consumption (Global) 124](06-supply-planning-module-reports.md#consumption-global) - -[D2. Forecast Error (Monthly) 125](06-supply-planning-module-reports.md#forecast-error-monthly) - -[D3. Forecast Error (by Planning Unit) 127](06-supply-planning-module-reports.md#forecast-error-by-planning-unit) - -[E. Shipment Reports 128](06-supply-planning-module-reports.md#shipment-reports) - -[E1. Shipment (Global) 128](06-supply-planning-module-reports.md#shipment-global) - -[E2. Shipment Overview 129](06-supply-planning-module-reports.md#shipment-overview) - -[E3. Shipment Details 130](06-supply-planning-module-reports.md#shipment-details) - -[E4. Shipment Cost Details 131](06-supply-planning-module-reports.md#shipment-cost-details) - -[E5. Shipment Cost Overview 131](06-supply-planning-module-reports.md#shipment-cost-overview) - -[E6. Budget 132](06-supply-planning-module-reports.md#budget) - -[E7. Procurement Agent Lead Time 133](06-supply-planning-module-reports.md#procurement-agent-lead-time) - -[F. Inventory Reports 134](06-supply-planning-module-reports.md#inventory-reports) - -[F1. Expiries 134](06-supply-planning-module-reports.md#expiries) - -[F2. Cost of Inventory 134](06-supply-planning-module-reports.md#cost-of-inventory) - -[F3. Inventory Turns 135](06-supply-planning-module-reports.md#inventory-turns) - -[F4. Stock Adjustment 136](06-supply-planning-module-reports.md#stock-adjustment) - -[F5. Warehouse Capacity (by Program) 137](06-supply-planning-module-reports.md#warehouse-capacity-by-program) - -[F6. Warehouse Capacity (by Country) 137](06-supply-planning-module-reports.md#warehouse-capacity-by-country) - -[Section 7. Forecasting Module: Program Data 139](07-forecasting-module-program-data.md#forecasting-module-program-data) - -[A. Introduction 139](07-forecasting-module-program-data.md#introduction) - -[B. Program Information 139](07-forecasting-module-program-data.md#program-information) - -[C. Version Settings 140](07-forecasting-module-program-data.md#version-settings) - -[D. Planning Units 141](07-forecasting-module-program-data.md#planning-units) - -[E. Equivalency Units 141](07-forecasting-module-program-data.md#equivalency-units) - -[Section 8. Forecasting Module: Forecasting 143](08-forecasting-module-forecasting.md#forecasting-module-forecasting) - -[A. Consumption Forecasts 143](08-forecasting-module-forecasting.md#consumption-forecasts) - -[A1. Import/Inputting Actuals 144](08-forecasting-module-forecasting.md#importinputting-actuals) - -[A2. Adjustments 147](08-forecasting-module-forecasting.md#adjustments) - -[A3. Extrapolation 148](08-forecasting-module-forecasting.md#extrapolation) - -[B. Tree Forecasts 153](08-forecasting-module-forecasting.md#tree-forecasts) - -[B1. Building a Tree 154](08-forecasting-module-forecasting.md#building-a-tree) - -[B2. Modeling Validations 171](08-forecasting-module-forecasting.md#modeling-validations) - -[B3. Product Validations 173](08-forecasting-module-forecasting.md#product-validations) - -[B4. Using Templates 174](08-forecasting-module-forecasting.md#using-templates) - -[Section 9. Forecasting Module: Reports and Outputs 179](09-forecasting-module-reports-and-outputs.md#forecasting-module-reports-and-outputs) - -[A. Compare and Select 179](09-forecasting-module-reports-and-outputs.md#compare-and-select) - -[B. Monthly Forecast 180](09-forecasting-module-reports-and-outputs.md#monthly-forecast) - -[C. Forecast Summary 182](09-forecasting-module-reports-and-outputs.md#forecast-summary) - -[C1. Regional View 182](09-forecasting-module-reports-and-outputs.md#regional-view) - -[C2. National View 183](09-forecasting-module-reports-and-outputs.md#national-view) - -[Section 10. **Annex 1: Application & Realm Administrator Manual** 185](10-annex-1-application-realm-administrator-manual.md#annex-1-application-realm-administrator-manual) - -[A. Introduction 185](10-annex-1-application-realm-administrator-manual.md#introduction) - -[B. Application Dashboard 185](10-annex-1-application-realm-administrator-manual.md#application-dashboard) - -[C. Managing Master Data 187](10-annex-1-application-realm-administrator-manual.md#managing-master-data) - -[C1. Application Masters 188](10-annex-1-application-realm-administrator-manual.md#application-masters) - -[C2. Realm Masters 199](10-annex-1-application-realm-administrator-manual.md#realm-masters) - -[D. Setting Up a New Program 221](10-annex-1-application-realm-administrator-manual.md#setting-up-a-new-program) - -[E. Resetting the QAT Problem List 223](10-annex-1-application-realm-administrator-manual.md#resetting-the-qat-problem-list) - -[Section 11. **Annex 2: Business Rules** 225](11-annex-2-business-rules.md#annex-2-business-rules) - -[A. Introduction 225](11-annex-2-business-rules.md#introduction) - -[B. Supply Planning Module: Supply Planning 225](11-annex-2-business-rules.md#supply-planning-module-supply-planning) - -[C. Supply Planning Module: QAT Problem List 232](11-annex-2-business-rules.md#supply-planning-module-qat-problem-list) - -[C1. Data Quality 232](11-annex-2-business-rules.md#data-quality) - -[C2. Procurement Schedule 232](11-annex-2-business-rules.md#procurement-schedule) - -[C3. Supply Planning 233](11-annex-2-business-rules.md#supply-planning) - -[C4. Other (Manual Problems) 234](11-annex-2-business-rules.md#other-manual-problems) - -[D. Supply Planning Module: Other QAT Reports 234](11-annex-2-business-rules.md#supply-planning-module-other-qat-reports) - -[E. Forecasting Module: Tree Forecasts 237](11-annex-2-business-rules.md#forecasting-module-tree-forecasts) - -[F. Forecasting Module: Consumption Forecast 239](11-annex-2-business-rules.md#forecasting-module-consumption-forecast) - -[G. Forecasting Module: Reports & Outputs 242](11-annex-2-business-rules.md#forecasting-module-reports-outputs) - -[G1. Compare & Select 242](11-annex-2-business-rules.md#compare-select) - -[G2. Forecast Summary 242](11-annex-2-business-rules.md#forecast-summary) - -[H. Supply Planning and Forecasting Module: Uploading Versions 243](11-annex-2-business-rules.md#supply-planning-and-forecasting-module-uploading-versions) - -[Section 12. **Annex 3: User Role Matrix** 248](12-annex-3-user-role-matrix.md#annex-3-user-role-matrix) - -[Section 13. **Annex 4: Business Functions** 255](13-annex-4-business-functions.md#annex-4-business-functions) - -[Section 14. **Annex 5: PipeLine Program Import** 259](14-annex-5-pipeline-program-import.md#annex-5-pipeline-program-import) - -Acronyms - -| | | -| ------------ | ------------------------------------------------------------------------------------------------------- | -| **AMC** | Average Monthly Consumption (see [Important QAT Concepts and Terms](01-overview.md#important-qat-concepts-and-terms)) | -| **ARIMA** | Auto Regressive Integrated Moving Average | -| **ARTMIS** | Automated Requisition Tracking Management Information System | -| **ARU** | Alternate Reporting Unit (see [Important QAT Concepts and Terms](01-overview.md#important-qat-concepts-and-terms)) | -| **ERP** | Enterprise Resource Planning | -| **EU** | Equivalency Unit | -| **FASP** | Forecasting and Supply Planning | -| **FEFO** | First Expiry, First Out | -| **FP/RH** | Family Planning and Reproductive health | -| **GFPVAN** | Global Family Planning Visibility and Analytics Network | -| **GHSC-PSM** | Global Health Supply Chain – Procurement and Supply Management program | -| **GLN** | Global Location Number | -| **GTIN** | Global Trade Item Number | -| **MSE** | Mean Squared Error | -| **MAPE** | Mean Absolute Percentage Error | -| **MNCH** | Maternal, Newborn and Child Health | -| **MOH** | Ministry of Health | -| **MOQ** | Minimum Order Quantity (see [Important QAT Concepts and Terms](01-overview.md#important-qat-concepts-and-terms)) | -| **MOS** | Months of Stock (see [Important QAT Concepts and Terms](01-overview.md#important-qat-concepts-and-terms)) | -| **PEPFAR** | President's Emergency Plan for AIDS Relief | -| **PMI** | U.S. President's Malaria Initiative | -| **PWA** | Progressive Web Application | -| **QAT** | Quantification Analytics Tool | -| **RMSE** | Root Mean Squared Error | -| **RO** | Requisition Order | -| **SKU** | Stock Keeping Unit | -| **SOH** | Stock on Hand | -| **STG** | Standard Treatment Guidelines | -| **TES** | Triple Exponential Smoothing (Holt-Winters) | -| **USAID** | United States Agency for International Development | -| **WAPE** | Weighted Absolute Percentage Error | diff --git a/docs/user/01-introduction.md b/docs/user/01-introduction.md new file mode 100644 index 0000000..e2c7e50 --- /dev/null +++ b/docs/user/01-introduction.md @@ -0,0 +1,14 @@ +--- +id: introduction +title: "Introduction" +sidebar_label: "Introduction" +sidebar_position: 1 +--- + +# Introduction + +Welcome to the User Documentation for the Quantification Analytics Tool (QAT). This guide is designed for both end-users and technical administrators, providing comprehensive information on system functionality, workflows, and best practices. + +The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages advanced technologies to enhance the functionality of legacy tools like PipeLine and Quantimed. + +For a high-level overview of the document structure, please refer to the [Table of Contents](03-table-of-contents.md). diff --git a/docs/user/01-overview.md b/docs/user/01-overview.md deleted file mode 100644 index 1baf9db..0000000 --- a/docs/user/01-overview.md +++ /dev/null @@ -1,473 +0,0 @@ ---- -id: overview -title: "Overview" -sidebar_label: "Overview" -sidebar_position: 1 ---- - -# Overview - -## Introduction - -The Global Health Supply Chain – Procurement and Supply Management (GHSC-PSM) program is an official project of the United States Agency for International Development (USAID), implemented by Chemonics International and its consortium members. The purpose of GHSC-PSM is to ensure uninterrupted supplies of health commodities in support of US Government-funded public health initiatives around the world. - -The Forecasting and Supply Planning (FASP) tool modernization initiative was supported with funding from the U.S. President’s Emergency Plan for AIDS Relief (PEPFAR), the U.S. President’s Malaria Initiative (PMI), USAID’s family planning and reproductive health (FP/RH) program, and USAID’s maternal and child health (MCH) program, which share the cost of the project. - -Previous USAID-funded projects, including the Supply Chain Management Systems (SCMS) and DELIVER developed and implemented the previous suite of FASP tools used in the global health domain. These tools performed their specific functions well and achieved their main objectives. The tools, however, were designed separately, were inconsistent in terms of the user interfaces, and required manual manipulation for data exchange. - -The primary objectives of this initiative were to build the next generation FASP tools on a scalable and modular platform that is operating-system agnostic; a tool that is web-based with significant offline capabilities; designed to allow for seamless data exchange and sharing across key stakeholders and public health systems, as well as have a user-centric interface for overall usability and automates supply chain functions for end-to-end data visibility and evidence-based decision-making that extends across global and national supply chains and encourages coordination with all stakeholders. - -## Forecasting vs. Supply Planning - -A forecast is an estimate/prediction of the quantities of products to be consumed/utilized by clients or consumers over a future period of time. Supply planning is the component of supply chain management involved with determining how to best fulfill the requirements created from the demand plan. The objective is to balance supply and demand in a manner that achieves the service delivery and financial objectives of the health program. - -## What is QAT and What Can It Do for You? - -The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages new technologies to enhance and modernize the functionality offered by the incumbent PipeLine and Quantimed tools by providing flexible forecasting tree structures, advanced extrapolation methodologies, scenario planning and updated planning logic. It also streamlines forecasting supply planning activities. Furthermore, the QAT enables offline functioning that helps users log their data even when there is no network coverage. QAT is changing the paradigm of legacy forecasting and planning solutions by leveraging master data management to drive standardization and increase visibility across all programs. - -This new tool seeks to enable users to do multi-method forecasting, compare outputs, quickly transfer the forecast to the supply plan module to optimize commodity procurement and delivery schedules, monitor the stock status of products and share data with external platforms and key stakeholders. - -QAT supports forecasting, monitoring, and procurement planning functions, as explained below: - -**QAT forecasting functions include:** - -- Forecasts based on multiple types of data. - -- Advanced extrapolation methodologies, including moving averages, semi averages, linear regression, Holt-Winters, and Auto Regressive Integrated Moving Averages (ARIMA). - -- Forecasting tree development that allows flexibility for multiple applications. - -- Visual comparison of multiple forecast outputs to drive stakeholder consensus and selection of final output. - -**QAT monitoring functions include:** - -- Monitoring stock balances, in terms of quantities and months of stocks on hand in the entire program. - -- Comparing stock balances to maximum and minimum stock parameters and identifying stock outs, balances below minimum or above maximum. - -- Automating the identification of problems such as additional procurements needed. - -**Procurement planning functions include:** - -- Calculation of shortfalls/surpluses and quantities needed to maintain the program’s optimum stock levels. - -- Automated calculation and tracking of pending actions, based on lead times such as shipments to plan, order, ship, and receive. - -- Calculation of estimated shipment and freight costs. - -- Tracking estimated budget expenditures. - -- Comparison of alternative procurement scenarios and analysis. - -## Who Should Use QAT? - -It is increasingly necessary that local program managers be empowered to do their own forecasting, monitoring, and procurement planning; they must also take charge of coordinating the activities of donors and local suppliers, as well as those of their own logistics management staff. While program managers and decision makers will be the primary users of QAT, the system can provide information to host country policy makers, country directors, procurers, and donors. - -| | | -| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Who** | **Purpose** | -| **Supply Planners / Program Managers** | Managing procurements from multiple funding sources (with different budgets), multiple procurement agents (with different catalogs, and lead times) and consumption and inventory data coming from different levels of the supply chain. QAT will help decrease the risk of stock imbalances by providing increased visibility into procurement planning, and stock status monitoring in the near- and long-term. | -| **Forecast/Demand Planners** | Estimating the demand with different methodologies (consumption, demographic, morbidity, services) using flexible and easy-to-use templates, advanced extrapolation methods, and built-in validations. Guide conversations, build assumptions, compare methodologies, and select final commodity forecasts using QAT's built-in visualizations to | -| **Host-country policy makers / country directors** | Use QAT to visually compare available forecasts, as well as highlight any stock imbalances and the implications of different decisions, such as new program targets, budgetary constraints, and procurement policies. | -| **Procurers and donors** | QAT highlights the current supply status and future procurement requirements | - -Table 1: Recommended QAT users and purpose - -## Important QAT Concepts and Terms - -### Cross-cutting terms - -| | | -| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Terms** | **Definitions** | -| **Forecasting Unit** | The base unit that will be used for a specified forecasting period (e.g. one tablet, one condom, one milliliter). | -| **Master Data (Sync)** | Master data is a cleaned/standardized set of data that is shared and used across a system. Many data points in QAT are standardized – for example, in the Global Health Realm, product lists, shipment statuses, data sources, etc are shared. Users can request updates and additions to this master data though a ticketing mechanism. QAT will sync master when a user logs in online or if the user chooses to manually sync. Note that for the full forecast or supply plan data, users must download the data to their local computer and upload it to the server when done. See Section 3 Managing Programs and Versions for more. | -| **Planning Unit** | The product to be planned for in QAT. It is a product with a full description up to the primary packaging (e.g. bottle of 30 tablets, 10x10 blister pack, etc.) | -| **Programs** | A program arises similar in structure to a PipeLine “supply plans database” in the supply planning module, or a Quantimed dataset in the forecasting module. Each program consists of only one country, one or more technical area(s), one region (national level, central level, etc.), and one organization (MOH, PEPFAR-only, PMI-only). | -| **Realm** | QAT is subdivided into realms, each one governed by their own master data (inclusive of product catalog, funder names, procurement agent names, etc.). QAT has started with the Global Health Realm, but future realms could be set up for other fields such as education supply chains, agriculture supply chains, etc. | -| **Region** | QAT users can capture data at sub-national levels by structuring their programs with regions. The regions are defined at the program level. If a program administrator does not have subnational-level data or prefers to enter aggregated values, the user may keep the region as “national” or “central.” To define sub-national levels, both forecast/actual consumption and inventory/adjustments must be entered at each level, which the application would then aggregate to a national total. | -| **Technical Area** | In QAT, technical area is synonymous with commodity groups (i.e. ARV, Family Planning, Malaria, etc.) and are used to build a QAT program. | -| **Tickets** | When a program user notices an issue with QAT (i.e. bug, system error) or would like to update/add master data, user role/access, or a program, they may submit a ticket. This ticket will be resolved by a realm or application administrator and changes made accordingly. | -| **User Roles** | These are dedicated assignments to users that allow for different levels of access to data and functional areas within QAT. | - -### Supply Planning Terms - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Terms - - Definitions -
- Alternate Reporting Unit (ARU) - - The product and the unit that the country's data (consumption or stock) is reported in. This could be the same as the planning unit or may be different. QAT users can define an alternate reporting unit and a conversion factor (multiplier) to the planning unit. (E.g., The planning unit is one bottle of 30 tablets; inventory reported in a box of 20 bottles (alternate reporting unit) = 100; multiplier is 20. Therefore, inventory reported is converted to planning units = 20 x 100 = 2,000 bottles of 30 tablets.) See - Section 4.A3 - Alternate Reporting Unit for more. -
- Average Monthly Consumption (AMC) - -

- A dynamic value (could be different month to month) that determines the average quantity a product is used over a selected period of time. For QAT, the default AMC will be an average of the past three (3) months of consumption, the current month, and two (2) months into the future. If there is missing monthly consumption data within the calculated time period, it will be treated as “null,” not as zero. QAT program administrators have the ability to change the AMC time period to a maximum of 12 months into the past and 12 months into the future. -

-

- P461C6T5#yIS1 -

-
- Data Source - - A data source is the location where data that is being entered into QAT originates from. Data sources should be applied for transactional records (Consumption, Inventory, Adjustments and Shipments) by QAT users. The selection of data sources for each transactional record will depend on which Data Source Type that record is for. -
- Enterprise resource planning (ERP) - - The software is designed to interface with different procurement management (ie Enterprise Resource Planning) systems from the various procurement agents. Initially, QAT will have an interface with ARTMIS that will enable import of USAID product information along with shipment data directly into QAT, reducing workload on planners to update shipment delivery dates, quantities, and statuses. In the future, PSM will work to engage other procurement agents to interface with their systems, thus enabling importation of shipment data from them. -
- Funding Source - - Funding Source is any financial institution or other entity providing funding or facilities for the program. Every shipment should be assigned a funding source. -
- Lead Times - -

- Lead times for QAT shipments have been mapped to the supply planning statuses and are inputted per product, procurement agent, or program by the QAT program administrator. There are six different lead time calculations: -

-
    -
  • -
    -

    - Planned to Submitted: time from when a shipment is planned (need identified) until it is entered into the procurement agent’s system. -

    -
    -
    • -
  • -
    -

    - Submitted to Approved: time from when the shipment is entered into the procurement agent’s system until it is approved for procurement. -

    -
    -
    • -
  • -
    -

    - Approved to Shipped: time from when the shipment is officially approved for procurement until it is shipped by the supplier. -

    -
    -
    • -
  • -
    -

    - Shipped to Arrived (sea) and Shipped to Arrived (air): time from when the shipment has left the supplier’s location until it arrives at the port of entry. -

    -
    -
    • -
  • -
    -

    - Arrived to Received: time from when the shipment arrives at port of entry and is in the customs clearance process until it arrives at the final destination and is ready to distribute. -

    -
    -
    • -
-
- Minimum & Maximum Stock Levels - -

- The minimum stock level (in months) is determined per planning unit and is set at the program level. QAT program administrators can adjust as desired. -

-

- P484C16T5#yIS1 -

-

- The maximum stock levels (in months) are dynamically calculated based on the minimum stock level plus the reorder interval. -

-

- P488C16T5#yIS1 -

-
- Minimum Order Quantity (MOQ) - - Minimum number of units a product must be ordered in. -
- Months of Stock - -

- This measure is conceptually the same as in PipeLine. However, due to the new AMC calculation methodology, results may vary from those seen in PipeLine. -

-

- P496C20T5#yIS1 -

-
- Plan by MOS - -

- For products that are consumed in high quantities, planning by Months of Stock (MOS) is more appropriate. For these products, we expect: -

-
    -
  • -

    - Minimal expiries -

    -
    • -
  • -

    - Shipments mostly replacing consumption rather than expired product -

    -
    • -
  • -

    - Minimum and maximum months of Stock (MOS) rather than a minimum or maximum quantity to be the appropriate method to plan for the product. -

    -
    • -
-

- Therefore, QAT offers the option to “Plan by MOS” See Section 4.A2 - Planning Units for how to update this parameter and Section 5.A Supply - Planning: An Overview for more information on the supply planning - implications. -

-
- Plan by Quantity - -

- Some products are consumed in low quantities, for emergency purposes - with high expiries, such as calcium gluconate for pre-eclampsia, - severe malaria treatment in the malaria elimination context, - anti-venom treatment for rare bites or fire extinguishers. For these - high expiry, low consumption products, we expect: -

-
    -
  • -

    high inventory compared to consumption

    -
    • -
  • -

    high amount of expiries

    -
    • -
  • -

    - shipments replacing both consumption (small percentage) and - expired product (large percentage) -

    -
    • -
  • -

    - A minimum quantity of stock (e.g. e.g. 2 units per facility * - 2,000 facilities = 4,000 min) rather than a minimum months of - stock -

    -
    • -
-

- Therefore, QAT offers the option to “Plan by Quantity” See Section - 4.A2 Planning Units for how to update this parameter and Section 5.A - Supply Planning: An Overview for more information on the supply - planning implications. -

-
- Reorder Interval - -

- A user-input number of months between shipments. QAT program administrators can adjust (default = 1 month) as desired. The reorder interval is used to calculate the maximum stock parameter. -

-
    -
  • -

    - For Plan by MOS, Min MOS + Reorder Interval = Max MOS. -

    -
    • -
  • -

    - For Plan by Quantity, Min Quantity + Reorder Interval * AMC = Max Quantity. -

    -
    • -
-

See Section 4.A2 Planning Units for how to update this parameter.

-
- Shipment Statuses - -

- Within QAT, there are a total of nine supply planning statuses that have been identified through the shipment’s lifecycle. These nine statuses are: -

-

- Suggested: shipments “suggested” by QAT as an early warning to avoid going below minimum stock levels. These are not actual shipments and as such, do not affect stock projections. Only when a suggested shipment is accepted and the status change to planned, will it be counted towards your stock projections. -

-
    -
  • -
    -

    - Planned: could be manually entered or suggested shipments accepted by the QAT user and are included in stock projections. Must have an assigned procurement agent and funding source (which could be TBD). -

    -
    -
    • -
  • -
    -

    - Submitted: shipments that have been placed in a procurement management system (i.e. ARTMIS, WAMBO) and have a designated order number (i.e. RO number). -

    -
    -
    • -
  • -
    -

    - Approved: shipments that have been approved by the procurement agent/funder. -

    -
    -
    • -
  • -
    -

    - Shipped: orders that have been shipped by the supplier. -

    -
    -
    • -
  • -
    -

    - Arrived: shipments that have arrived at the port of entry and are in the customs clearance process. -

    -
    -
    • -
  • -
    -

    - Received: shipments that have been received at destination and ready to distribute. -

    -
    -
    • -
  • -
    -

    - Cancelled: shipment was placed in a procurement management system, but later cancelled due to various reasons. These do not count towards projected inventory balances. -

    -
    -
    • -
  • -
    -

    - On-hold: shipment in QAT that has been placed in the procurement management system but is waiting for decision-maker action. These do count towards projected inventory balances. -

    -
    -
    • -
-
- Unmet Demand - -

- QAT only allows stock on hand (SOH) to be equal to or greater than zero, thus avoiding negative stock balances. Unmet demand is used by QAT to estimate quantities of product that would have been consumed if sufficient stock was available: -

-
    -
  1. -

    - When the forecast consumption is greater than the projected available beginning stock on hand for that month. -

    -
    2. -
  2. -

    - When the actual consumption also includes periods of stock out, QAT estimates what the consumption would have been during those days without stock (even when the ending balance is greater than zero). -

    -
    3. -
  3. -

    - When a negative manual adjustment is larger than the projected ending balance. -

    -
    4. -
-

- QAT places the unmet demand in a separate row. -

-
- Volumetrics - - In QAT, programs users will be able to define volumes, and thus be able to estimate the volumetrics of orders. -
- -### Forecasting Terms - -| | | -| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Terms** | **Definitions** | -| **Consumption-based forecast** | **A prediction of future demand based on historical actual consumption data, using linear and non-linear extrapolation methodologies. (Section 8.A** Consumption Forecasts **for more)** | -| **Tree Forecast** | **Flexible forecasting structures used to convert different types of data (demographics, morbidity, services) into commodities for the purpose of extrapolating or interpolating into the future in the forecasting module. (Section 8.B** Tree Forecasts **for more)** | -| **Tree Template** | **Pre-defined forecasting trees that can be downloaded and customized to each user’s context in the forecasting module. (Section 8.B4.a** Tree Templates **for more)** | -| **Usage Template** | **Pre-defined rates of use of specific products that can be applied across trees and programs in the forecasting module. (Section 8.B4.c** Usage Templates **for more)** | -| **Continuous and Discrete usage** | **When defining a product’s usage rate on a forecasting tree, the user can choose whether it is continuous use (i.e., unending) or discrete use. If discrete, the user must specify the period of time the product is used for, or can also specify if the product is for single use, thus no period is required.** | diff --git a/docs/user/02-getting-started.md b/docs/user/02-getting-started.md deleted file mode 100644 index 6cefbf2..0000000 --- a/docs/user/02-getting-started.md +++ /dev/null @@ -1,836 +0,0 @@ ---- -id: getting-started -title: "Getting Started" -sidebar_label: "Getting Started" -sidebar_position: 2 ---- - -# Getting Started - -## System Requirements - -The QAT is primarily expected to be accessed via laptops and desktops with standard operating systems such as MS Windows, Linux/Ubuntu, and iOS. The recommended web browser is Google Chrome, but Chromium, Edge, Mozilla Firefox or Safari may be utilized. - -It is also suggested that each user of QAT have enough space on their C:drive to allow for storing browser cache data successfully. The amount of space needed depends on the size of the QAT program that is being downloaded and how many apps are currently running and utilizing browser data. Temporary storage is shared among all web apps running in the browser. This shared pool can be up to 1/3 of the of available disk space. Each app can then have up to 20% of the shared pool. For example, if the total available C:drive space is 60 GB, the shared pool is 20 GB; thus, QAT can potentially utilize up to 4 GB. This is calculated from 20% (up to 4 GB) of 1/3 (up to 20 GB) of the available C:drive space (60 GB). - -## Levels of Hierarchy in QAT - -The QAT system has **three levels of hierarchy** for conducting operations. The hierarchy levels are as follows: - -- **Application** Masters is the top-most data hierarchy level in QAT. Application master data applies to all the Realms and Programs within QAT. Most of it is only accessible to Application Admins, though a few of the Application functions are available to Realm Admins such as adding and updating users and assigning roles to users. Application Admins can select the specific application-wide master data they want to add or update. - -- **Realm** Level Masters covers all the master data for that Realm which apply to its forecasting and supply planning programs. The Realm Admin will be able to view, create and edit this master data. Programs, Technical Areas, Planning Units, Procurement Agents, and Tree Templates are a few examples of realm master data that the Realm Admin can add and maintain. A lot of the realm level masters are accessible for viewing to Program Admins; however, they do not have the ability to add/update this data. - -- **Program** Level Masters is the third level of hierarchy in QAT. While program admins cannot add programs, they can update the program information (e.g., lead times, freight costs, etc.) within their assigned program(s). Program Admin and Program Users can also add and update the program’s data, such as consumption adjustments, extrapolation, and managing trees (in forecasting); and consumption, inventory, shipments (in supply planning). - -For more on functionality for Application- and Realm-level administrators, please see [Annex 1: Application & Realm Administrator Manual.](10-annex-1-application-realm-administrator-manual.md#annex-1-application-realm-administrator-manual) - -**Programs** are a combination of Country, Technical Area (1 or more), Organization and Region. For example, **FASPonia**–ARV-MOH-National, is a supply planning program under the Global Health Realm for the management and planning of **antiretrovirals** for the ministry of health of the fictional country FASPonia, and the consumption and inventory data is captured at a national level (region). - -## User Roles and Permissions - -Users can be assigned one of many roles available in QAT that define what level of data users have access to and how they interact with that data, according to the following hierarchy: - -Users will have access to one or more levels of data as per the roles and permissions assigned to them. Roles are defined centrally at the Application or Realm Level. A role can have multiple permissions assigned to it. These permissions define what actions a user is entitled to. A user can be assigned multiple roles and can vary the role based on program access. For example, a user could be a supply plan program admin for program A and a supply plan reports viewer for program B. (NOTE: Roles can be assigned to only those users that are registered in QAT). - -The vast majority of QAT users – in-country health program managers and officers - will interact with the application at the **program level**; thus, this manual will focus mainly on tasks and functions that apply to this group. The Program Admin and Program User roles are usually configured to have access to one or multiple program(s) within a geographic jurisdiction i.e., a Program Admin can only manage assigned program(s) in their country, but not a realm. - -A **Realm** Admin manages master data and can have access to all programs within that realm. - -At the **Application** level, there is an Application Administrator role. This role has exclusive access to create application-wide data structures, including adding languages, roles, creating realms, updating static and dynamic labels, among other business functions. - -Please refer to [Annex 4: Business Functions](13-annex-4-business-functions.md#annex-4-business-functions) for a table with the full list of QAT business functions available per user role. - -## How to Log into QAT and Install the Progressive Web Application (PWA) - -**How to log in to QAT** **for the first time** (**online**) - -1. > If you do not have a user profile, please contact the realm administrator to create a new user account and corresponding role on your behalf. - -2. > Once the account is created, the new user receives an email to “Reset Password”. - -3. > The “Reset Password” link will redirect the user to the QAT website to create the new password. Once complete, click “Submit”. - 1. > **Note**: the “Reset Password” link will be valid for 24 hours and can be used only once. If needed, the user can generate the link again to reset the password by clicking “Forgot Password” on the login screen. - -4. > Afterwards, the user will be redirected to the sign in screen. Using the User ID email and the created password, log in to QAT. - -**Note:** The password must: be at least six characters long, start with a letter, not be the same as your username or your last password, and must include at least one special character, one number, and one uppercase letter. - -**Installing the QAT Progressive Web Application** - -Progressive web applications (PWA) are standalone browsers that bring an app-like look and feel and are installed on the Desktop. Users can only install the QAT PWA through Google Chrome and Edge. The PWA can be used in online or offline mode. - -1. > Go to [Quantification Analytics website](https://www.quantificationanalytics.org/). - -2. > Click on the add button in the address bar. - -3. > Click “install” when the small pop-up appears. - -![P602#yIS1](/img/media/image10.png) - -Figure 1: Installing QAT PWA - -4. > An icon will appear on your Desktop as a standalone application. Users can directly open from the desktop or type **chrome://apps/** in the browser. - -> ![P605#yIS1](/img/media/image11.png) - -Figure 2: QAT PWA Icons - -**Note:** Users can utilize the PWA and browser versions concurrently; however, when making changes in one, a refresh is needed in the other so changes are made effective (see [When and How to Conduct an Application Refresh](#when-and-how-to-conduct-an-application-refresh)). - -**Steps to Install PWA When the Install Button is Not Available** - -1. > In your Chrome browser, navigate to [https://www.quantificationanalytics.org/](https://www.quantificationanalytics.org/) - -2. > Click on the three vertical dots on the top righthand corner of the browser - -3. > Select “Cast, Save, and Share” - -4. > Click on “Create Shortcut” - -5. > A QAT icon will be displayed on your desktop. - -6. > Click on the “QAT” icon to open PWA of QAT application. - -![A screenshot of a computer Description automatically generated](/img/media/image12.png) - -Figure 3: Install PWA alternate method - -## How to Log into QAT for Existing Users - -**Login** - -1. To log in, type the URL [https://www.quantificationanalytics.org/](https://www.quantificationanalytics.org/) in the browser bar and press enter, or open the PWA from your desktop. - -2. A login screen will be displayed. - -![A screenshot of a computer Description automatically generated](/img/media/image13.png) - -Figure 4: Log-in Screen - -1. > Type the username and password in the required fields. - -2. > Click on the “Login” button. - 1. > Note: A user can choose to login “online” or “offline” using the checkbox above the “Login” button. For more information on working in QAT offline, see Section F. [Working Offline](#working-offline). - - 2. > When logging in using “online” mode – QAT will undergo master data sync. If you see a message about a “more recent server version” – see Figure 36 in Section 3.B for more information. - -**Logging out** - -1. > Go to the top right corner of the screen. - -2. > Click on the logout button icon to the right of the profile icon. - -![A screenshot of a computer Description automatically generated](/img/media/image14.png) - -Figure 5: Logout Icon - -3. > A pop up will appear asking “Are you sure you want to log out?” – click “yes” to log out - -**Change Password** - -1. Within QAT, click the Profile icon on the top right corner of the screen. - -2. Click “Change Password”. - -![A screenshot of a login screen Description automatically generated](/img/media/image15.png) - -Figure 6: Profile Icon - -3. Once on the ‘Change Password’ screen, enter your old password followed by the desired new password. - -4. The new password must meet the following criteria: - - Password must be at least 6 characters - - - Password should not contain the word ‘password’ - - - Password must contain at least 1 special character - - - Password must contain at least 1 number - - - Password must contain at least 1 uppercase letter - - - Password must start with a letter - - - New Password should not be the same as your username - - - New password should not be the same as your last password - -5. Confirm the new password by typing it again. - -6. Click “Submit”. - -**If user forgets their password** - -1. A user that has forgotten their password, can click on the “Forgot Password?” link to reset it. - -2. Type the email address the user is registered in QAT with and click “Submit”. - -![P662#yIS1](/img/media/image16.png) - -Figure 7: Forgot Password Screen - -3. The user will get a link via email to reset their password. - -![P666#yIS1](/img/media/image17.png) - -Figure 8: Reset Password Email - -4. The “Reset Password” link will redirect you to QAT, where you will input your new password. Once complete, click “Submit”. - -5. After clicking “Submit” the user will be redirected to the login screen. Using the User ID email and the newly created password, log in to QAT. - -**_Note: A QAT user password will be valid for up to one year from the date it is created/updated._** - -## Working Offline - -QAT is a hybrid tool and can be operated in both the online and offline mode. There are two ways to force the offline mode of QAT: on the login page before logging into QAT or under the profile settings after logging into QAT. It may be useful to switch to the offline mode of QAT when internet bandwidth is low. - -![A screenshot of a login page Description automatically generated](/img/media/image18.png) ![A screenshot of a login page Description automatically generated](/img/media/image19.png) - -> Figure 9: Offline Button on Profile Page Figure 10: Offline Button on Login Page - -The Profile icon on the top right corner shows a green-colored circle when working in online mode. When the user switches to offline mode the color changes to red, as shown on the screenshot below. - -![P677#yIS1](/img/media/image20.png) - -Figure 11: Offline vs. Online Icons - -The below table details _some_ of the key functionalities that can be done in QAT offline as well as _some_ of the functionalities that must be done online: - -| What can a user do Offline?\* | What must a user do Online? | -| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -| Import/Export supply plans/forecasts | Reset password | -| View master data | Sync master data | -| Build Trees/Scenarios | Update program info, planning units, version settings, or budgets | -| Enter/update supply plan transactional data, and manually enter/adjust consumption data | Import forecast data to/from the Supply Planning Module to/from the Forecasting Module | -| Extrapolate using moving averages or semi-averages | Extrapolate using linear regression, triple-exponential smoothing (TES), or ARIMA methods | -| Supply/Scenario plan | Create tickets | -| View QAT Problem List | Download/Upload supply plans/forecasts | -| View program reports & forecast outputs | View global reports | - -\*Note: Even when online, functions in the “offline” column require that that a program is downloaded- see Section 3 for more information - -Table 2: Online vs. Offline Capabilities - -## QAT Release Updates - -To maintain the QAT application, regular version releases are pushed automatically to the QAT application and all realm users. These version releases could occur due to the following: - -- Regularly scheduled maintenance for bug fixes and application optimization - -- Unplanned emergency maintenance for high priority/urgent bug fixes - -- Periodic updates related to enhancements or new features - -![A screenshot of a computer Description automatically generated](/img/media/image21.png) - -Figure 12: QAT Version Releases - -Most version releases will not require significant action from the user, except to refresh the QAT application prior to logging-in. QAT will prompt user that there is a new version of QAT on the login page: - -![P721#yIS1](/img/media/image22.png) - -Figure 13: New QAT Version Released Prompt for Users - -If there is a major change to the structure of the QAT backend architecture, users may be required to upload their latest version to the server (see the [Upload](03-managing-programs-and-versions.md#upload) section for more information) to avoid losing data once the new version of QAT is released. The QAT Support Team ([support@quantificationanalytics.org](mailto:support@quantificationanalytics.org)) will inform users well in advance if a program upload is required. -## Troubleshooting - -When a user comes across a potential system issue with QAT, they should attempt to troubleshoot the issue by trying the solutions outlined in this section, in the order they are described (i.e. try H1 first, and if that does not work, then attempt H2, and then H3). If none of these steps resolve the issue, the user should submit a helpdesk ticket to report the bug (see section on ‘[Reporting a Bug](#reporting-a-bug)’). - -### When and How to Conduct an Application Refresh - -The QAT development team deploys incremental software releases to address the bugs and changes needed for the application. QAT prompt users to do so on the log-in screen after each release (see Figure 12). To conduct an application refresh, users should press “Ctrl” + “Shift” + “R” at the same time on their keyboard. - -![P721#yIS1](/img/media/image22.png) ![P721#yIS2](/img/media/image23.png) - -Figure 14: Hold Ctrl + Shift + R (all 3 keys) to conduct an Application Refresh - -The application refresh can also be used to help troubleshoot any issues experienced while using QAT. After holding all 3 keys, the software should reload automatically. Note that the application refresh is different than simply refreshing the browser (“Ctrl” + “R”). - -### When and How to Conduct a Full Master Data Sync (MDS) - -If an application refresh (“Ctrl” + “Shift” + “R”) does not solve your software issue, you can try conducting a “Full Master Data Sync.” To do so, please ensure you have a stable internet connection, and then click on the “Full Master Data Sync” link at the bottom of the application (see Figure 13). This solution is likely to work if you are experiencing master data issues that may be the result of unstable internet that disturbed the regular Master Data Sync (MDS) described in Section 2.J Navigation and Menu Bar. - -- In a **regular MDS,** only incremental changes are synced between the server and your local computer based on the last time a MDS was completed. - -- In a **full MDS**, the entire master data is loaded irrespective of the last time QAT was synced, as if this is the first time you are loading master data. Therefore, this will take longer than a normal MDS. - -![A screenshot of a computer Description automatically generated](/img/media/image24.png) - -Figure 15: Click “Full Master Data Sync” - -### When and How to Clear Site Data - -If refreshing QAT (Ctrl + Shift + R) and a Full Master Data Sync do not resolve the issue, the user should attempt to clear site data in order to troubleshoot the issue. Follow the below steps in order to clear site data on your QAT: - -**\*Warning**: Clearing site data on QAT clears all local data on the PWA and Web Browser, including any changes that you have made since you last uploaded. Ensure you have uploaded any unsaved programs before clearing site data.\* - -1. > Click on “Ctrl”+”Shift”+”I” keys at the same time on your keyboard. - -> ![P739#yIS1](/img/media/image25.png) -> -> Figure 16: Ctrl + Shift + I - -2. > Go to “Application”. - -3. > On the left-hand side of the screen, click where it says “Storage”. - -4. > Once on the “Storage” screen, select “Clear site data.” This will clear any data that was not uploaded. - -5. > Log in again to QAT and re-download any programs you need. (Clearing site data erases all programs from your local machine so you will need to re-download those programs.) - -![P746#yIS1](/img/media/image26.png) - -Figure 17: Clear Site Data - -### Troubleshooting Network Errors - -Users may see the following error message when logging in or while using QAT: - -| | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| “Network error. Please check your internet connection or contact your organizational IT department to ensure [api.quantificationanalytics.org/\#](https://nam02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fapi.quantificationanalytics.org%2F%23&data=05%7C01%7Clgu%40ghsc-psm.org%7C9490a6cee80d4de5c62608dabd019412%7C7c1f24a67d39452c82370726e3b19a73%7C0%7C0%7C638030111727715513%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=4heIFYQR9sA%2FqkifKvp2y9V00BIPmMKX35Wi5Am4jXk%3D&reserved=0) and [www.quantificationanalytics.org/\#](https://nam02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.quantificationanalytics.org%2F%23&data=05%7C01%7Clgu%40ghsc-psm.org%7C9490a6cee80d4de5c62608dabd019412%7C7c1f24a67d39452c82370726e3b19a73%7C0%7C0%7C638030111727715513%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=cW0d%2B1AnhHVpuclTsFqM6KwhliqBT1y82X5OD5ZUrmc%3D&reserved=0) are whitelisted for firewall access.” | - -This message appears for two reasons: 1) Unstable internet, or 2) Restricted internet. - -**Unstable Internet**: Use another internet with a stable or faster connection, or try again later. - -**Restricted Internet**: QAT can be accessed by most private internet connections, but sometimes organizational IT systems have stricter security control, and thus they are flagging QAT as a potential threat. In this case, users have two options: - -1. Use another internet connection without restrictions, or - -2. Enable firewall access by whitelisting the below two site URLs. User may need to contact their organizational IT staff for assistance - -> •         [api.quantificationanalytics.org/\#](https://nam02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fapi.quantificationanalytics.org%2F%23&data=05%7C01%7Clgu%40ghsc-psm.org%7C9490a6cee80d4de5c62608dabd019412%7C7c1f24a67d39452c82370726e3b19a73%7C0%7C0%7C638030111727715513%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=4heIFYQR9sA%2FqkifKvp2y9V00BIPmMKX35Wi5Am4jXk%3D&reserved=0) -> -> •         [www.quantificationanalytics.org/\#](https://nam02.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.quantificationanalytics.org%2F%23&data=05%7C01%7Clgu%40ghsc-psm.org%7C9490a6cee80d4de5c62608dabd019412%7C7c1f24a67d39452c82370726e3b19a73%7C0%7C0%7C638030111727715513%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=cW0d%2B1AnhHVpuclTsFqM6KwhliqBT1y82X5OD5ZUrmc%3D&reserved=0) - -## QAT Helpdesk and Tickets - -### Tickets for Adding/Updating Users and Master Data - -When a user needs to either add or update a user or master data for any reason, they may do so by taking out a helpdesk ticket. Before requesting any additions or changes to the master data in QAT, the user should first check the realm-level master data (Realm Level Masters \>\> Product) and the Program Catalog Report to make sure the information does not already exist. For more information on how to access and use master data, please see [Program Management](03-managing-programs-and-versions.md#working-with-program-data) and [Realm Masters](10-annex-1-application-realm-administrator-manual.md#realm-masters). For information on how to access the Program Catalog, please see [Program Catalog](10-annex-1-application-realm-administrator-manual.md#product). To access the QAT Helpdesk: - -1. > Users can access the QAT Helpdesk from two different locations in QAT: - 1. > On the login page, and - - 2. > from the top right ribbon in QAT - -![A screenshot of a login screen Description automatically generated](/img/media/image27.png) - -![A red line with numbers and circles Description automatically generated](/img/media/image28.png) - -Figure 18: Three location to access the QAT Helpdesk - -2. > Four options will appear for taking out a ticket: Add/Update User, Add/Update Master Data, Change Request, and Report a Bug. See below sections on [Change Requests](#requesting-a-change) and [Report a Bug](#reporting-a-bug). - -![P772#yIS1](/img/media/image29.png) - -Figure 19: QAT Helpdesk Menu - -3. > Choose to Add/Update User or Add/Update Master data. Either option will take you to different screens for more information. - -4. > Enter the information required in the form and click “Submit.” - -![P778#yIS1](/img/media/image30.png) - -Figure 20: Add/Update User Screen - -![A screenshot of a computer Description automatically generated](/img/media/image31.png) ![P781#yIS2](/img/media/image32.png) - -Figure 21: Add Master Data Screen Figure 22: Add Procurement Agent Master Data Screen - -After submitting a ticket, the user will be assigned a Ticket Code number (ex: QAT-570). The user will also receive an email notification and the number of “Open Tickets” on the top ribbon in red will increase. This ticket number corresponds to the ticket number stored in the JIRA software management tool. For more information on managing tickets and the JIRA software management tool, please see [Managing Tickets](#managing-tickets). - -### Requesting a Change - -When a user has an idea for a new feature, functionality, or design element that would make QAT a better application for all users, such as a new report, removing an unnecessary column, etc., they may request a change through the QAT Helpdesk. All change request tickets will require a detailed description and screenshots. Once the technical team receives a user’s change request ticket, it will be reviewed for feasibility and usefulness to all QAT users. If the change request is accepted, it will not be made available in QAT immediately, but will placed in a queue based on realm business priority, criticality, and LOE requirements. To request a change in QAT: - -1. > Click on the QAT Helpdesk icon. - -![A red line with numbers and circles Description automatically generated](/img/media/image28.png) - -Figure 23: QAT Helpdesk Icon - -2. > Click on “Request a Change” from the QAT Helpdesk menu options. - -3. > Complete the form by filling out the required information and click “Submit,” - -![A screenshot of a computer Description automatically generated](/img/media/image33.png) - -Figure 24: Change Request Ticket - -4. > After submitting a ticket, the user will be assigned a Ticket Code number (ex: QAT-570). The user will also receive an email notification and the number of “Open Tickets” on the top ribbon in red will increase. This ticket number corresponds to the ticket number stored in the JIRA software management tool. For more information on managing tickets and the JIRA software management tool, please see [Managing Tickets](#managing-tickets). - -### Reporting a Bug - -When a user comes across a potential system issue with QAT, they should attempt to troubleshoot it through an [application refresh](#when-and-how-to-conduct-an-application-refresh) and/or [clearing site data](#when-and-how-to-clear-site-data). If neither of these steps resolve the issue, the user should submit a helpdesk ticket to report the bug. - -The bug ticket will be addressed by the development team per the business priority, criticality and available ‘capacity’ via the incremental releases. The steps to raise a ticket in QAT is shown below: - -1. Open the QAT Helpdesk screen and click on “Report a bug”. - -2. Enter a summary of the bug as well as a description of the bug. Please be descriptive and provide as much detail as possible (_e.g., what program/version/functionality you were working on, steps you took to obtain the bug, etc_). - -3. Upload a screenshot of the bug by clicking the “Browse” button and pulling a saved screenshot file from your computer. - 1. It is also helpful to provide the program export, if possible (see [Program Exports](03-managing-programs-and-versions.md#export) on how to export a local program) - - 2. **\*Note**: If you want to upload multiple files, place the multiple screenshots in a folder on your computer and zip it before browsing in QAT. Then, upload the zipped folder.\* - -4. Choose a priority (Highest, High, Medium, or Low) for the bug based on the urgency and how it affects daily work in QAT - 1. Response and resolution times for bugs will be based on priority level - -5. Click on the “Submit” button to raise the ticket. - -![A screenshot of a computer Description automatically generated](/img/media/image34.png) - -Figure 25: Report a Bug - -### Managing Tickets - -For enhanced visibility, QAT will give users the option to manage and check the status of their tickets, whether they are adding/editing a user or master data, requesting a change, or reporting a bug. When a user submits a ticket, they will be assigned a Ticket Code number (ex: QAT-570). The user will also receive an email notification and the number of “Open Tickets” on the top ribbon in red will increase. This ticket number corresponds to the ticket number stored in the JIRA software management tool. - -![P815#yIS1](/img/media/image35.png) ![A red line with numbers and circles Description automatically generated](/img/media/image28.png) - -Figure 26: Helpdesk Ticket Code Number Figure 27: Number of Tickets on Top Ribbon - -From the email notification, users may click on “View Requests” to see the status of their ticket. Users may also add additional comments and screenshots to their request, if desired. **Users will always receive an email notification once the ticket has been completed.** - -**Note**: In order to fully access the ticket via the JIRA software management tool, users must create an account with a username and password in JIRA. Creating an account in JIRA is **optional**. JIRA is an outside software management tool that can be accessed through the link provided in the email, **by clicking on the HelpDesk icon and then choosing “Manage my tickets” in the top right corner of the pop-up**, or directly through [https://qathelpdesk.atlassian.net/servicedesk/customer/portals](https://qathelpdesk.atlassian.net/servicedesk/customer/portals). - -![P821#yIS1](/img/media/image36.png) - -Figure 28: Email Notification for QAT Ticket - -![A screenshot of a computer Description automatically generated](/img/media/image37.png) - -Figure 29: Option to Navigate to JIRA - -![P823#yIS1](/img/media/image38.png) - -Figure 30: JIRA Ticket Management - -## Navigation and Menu Bar - -**Basic Navigation** - -Once logged into QAT, the below screen will appear: - -![A screenshot of a computer Description automatically generated](/img/media/image39.png) - -Figure 31: Supply Planning Module Home Screen - -![P830#yIS1](/img/media/image40.png) - -Figure 32: Forecasting Module Home Screen - -In the main area of the home page will be an application dashboard. The Supply Planning Module has an enhanced dashboard with visualizations and analytics regarding downloaded and server-based programs a user has access to. For specific information on the Supply Planning Module dashboard, see [QAT Dashboard](#qat-dashboard). For the Forecasting Module, the number of tiles, and types of tiles will depend on the access according to the role assigned to the user. Users will see one tile for program they’ve downloaded (i.e. When in the forecasting module, users will see one tile for every forecasting program they’ve loaded.). By clicking on the down arrow on the Forecasting program tile, a user can 1) Delete the program from your local computer, 2) Proceed to the Version Settings for the program, 3) Proceed to the list of Forecasting Trees, or 4) Proceed to the Consumption Data Entry & Adjustment screen. - -![P838C3T9#yIS1](/img/media/image41.png) - -Figure 33: Forecasting Module Program Tile - -In addition to the application dashboard, the screen consists of the top ribbon and a menu sidebar on the left-hand side. All the functions available in the ribbon and sidebar will be accessible to the user throughout the tool no matter which screen they are viewing. - -To return to the Dashboard screen, the user can either click the home icon in the top ribbon or the QAT logo in the top left corner of the screen. - -![P860#yIS1](/img/media/image42.png) Or ![P860#yIS2](/img/media/image43.png) - -**Top Ribbon for Supply Planning Module** - -![](/img/media/image44.png) - -**Top Ribbon for Forecasting Module** - -![](/img/media/image45.png) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ScreenshotFunction
- P873C3T10#yIS1 - - Logs user out of QAT. -
- P876C5T10#yIS1 - -

- The profile icon is green when working online and red while working offline. When the user click on the icon, they are able to: -

-
    -
  • -

    - View the username and associated role(s) assigned to them -

    -
    • -
  • -

    - Change their preferred language -

    -
    • -
  • -

    - Change their password -

    -
    • -
  • -

    - Go offline/online -

    -
    • -
-
- P883C7T10#yIS1 - - Returns user to the dashboard/home screen. -
- P886C9T10#yIS1 - - Downloads the QAT user manual to the user’s computer. The file can be found in the Downloads folder on the user’s computer. -
- P889C11T10#yIS1 - - Refreshes the current page a user is working on. -
- - - Informs the user when a program stored on the local server has non-uploaded changes and should upload that program to the server. If the icon is blue, there are no programs non-uploaded. If the icon is red, there are program(s) that should be uploaded to the server. The number in the red box indicates the number of programs that should be uploaded. -
- P895C15T10#yIS1 - - Informs the user when there is a newer version on the server for of one of their locally downloaded programs. If the icon is blue, the user has the most up to date version of all downloaded programs. If the icon is red, there are program(s) that are outdated compared to the server. The number in the red box indicates the number of programs that have outdated versions. -
- - - Opens up the QAT Helpdesk where users can create tickets to add/update master data, propose change requests and report a bug. The number in the red box indicates thet number of open tickets a user has. For more information on the helpdesk, refer to QAT Helpdesk and Tickets. -
- P901C19T10#yIS1 - - Directs the user to the ERP Shipment Notification page. This page will inform users if there are any important updates that need to be reviewed for a linked ERP shipment. For more information on these notifications and which will be flagged, refer to ERP Shipment Linking. Note: this icon is only available in the QAT Supply Planning Module. -
- P904C21T10#yIS1 - - Opens a Show Guidance webpage on an Introduction to QAT Forecasting. This document provides a high-level overview on the QAT forecasting process flow. Note: This icon is only available in the QAT Forecasting Module. -
- -Additionally, users can utilize the profile icon to check their current user roles, as well as: - -- Change their password, - -- Go [offline/online,](#working-offline) - ![A close up of words Description automatically generated](/img/media/image55.png) - -- [Change the preferred language,](#changing-language) - -- Chage to dark/light theme mode, and - ![A black and white text Description automatically generated](/img/media/image56.png) - -- Show decimals in the supply planning screens - ![A black text on a white background Description automatically generated](/img/media/image57.png) - -**Sidebar Menu:** - -The sidebar menu is where the user can navigate to the different screens within QAT. The options available in the sidebar will vary based on the access according to the role assigned to the user. Within the sidebar there are menu items. Clicking into one of those items will expand to show a list of sub menu items. As the user selects different items from the menu, the respective data will be displayed in QAT. - -Within the sidebar menu, you will find the following menu items: - -- **Supply Planning Module** - - **Master Data Sync** - Clicking on this button will sync the updated master data to your local version. This function is done automatically when logging into QAT, but this button provides the user to do so without logging out and logging back in. - - - **Application Masters** (only available to Application and Realm Admins) – view/add/edit application-level data. - - - **Realm Level Masters** – view/add/edit realm level data. - - - **Program Management** – view/add/edit program level data. Download/Upload/Delete/Import/Export programs. Conduct supply plan reviews. - - - **Supply Plan Data** – Add/Edit supply plan data. - - - **Supply Planning** – View/edit supply plan. Scenario Plan. - - - **Reports** – View Reports. Edit QAT Problem List. - -- **Forecasting Module** - - **Master Data Sync** - Clicking on this button will sync the updated master data to your local version. This function is done automatically when logging into QAT, but this button provides the user to do so without logging out and logging back in. - - - **Application Masters** (only available to Application and Realm Admins) – view/add/edit application-level data. - - - **Realm Level Masters** – view/add/edit realm level data. - - - **Program Management** – view/add/edit program level data. Download/Upload/Delete/Import/Export programs. - - - **Consumption-Based Forecasts – **Import/add/adjust and extrapolate consumption data. - - - **Tree Forecasts –** Build and manage forecast tree. View modeling and product validations. - - - **Forecast Analysis Outputs –** Compare & select final forecasts. View other output reports. - -| Screenshot | Function | -| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| ![P934C3T11#yIS1](/img/media/image58.png) | Completely collapses the sidebar menu to create more space on the screen. Clicking the icon once will make the menu disappear. Clicking it again will make it re-appear. | -| ![P937C5T11#yIS1](/img/media/image59.png) | Minimizes the sidebar menu while not making it completely disappear. Creates some more space on the screen. | -| ![P940C7T11#yIS1](/img/media/image60.png) | Shown when sidebar menu is minimized. Click to expand and show the full sidebar menu. Also used to expand and show sub menu items under menu items. | -| ![P943C9T11#yIS1](/img/media/image61.png) | Shown when sub menu items are displayed. Click to collapse sub menu items. | -| ![P946C11T11#yIS1](/img/media/image62.png) | Buttons that allow users to toggle between the Forecasting and Supply Planning Module in QAT, if their user access allows. | - -Table 4: Sidebar Menu Icons - -**Buttons Found Throughout QAT** - -The following buttons are frequently found on the different QAT screens: - -| | | -| ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | -| **Buttons** | **Action** | -| ![P956C3T12#yIS1](/img/media/image63.png) | Submits and makes changes. | -| ![P959C5T12#yIS1](/img/media/image64.png) | Cancels the unsubmitted changes. | -| ![P962C7T12#yIS1](/img/media/image65.png) | Reverts unsubmitted data back to previous format. | -| ![P965C9T12#yIS1](/img/media/image66.png) | Adds a new record to the database. | -| ![P968C11T12#yIS1](/img/media/image67.png) | Updates records. | -| ![P971C13T12#yIS1](/img/media/image68.png) | Helps users to search the desired information. Searches all fields in the table displayed. | -| ![P974C15T12#yIS1](/img/media/image69.png) | Allows a user to clear search fields. | -| ![P977C17T12#yIS1](/img/media/image70.png) | Indicates mandatory data entry fields. | -| ![P980C19T12#yIS1](/img/media/image71.png) | Displays explanations/definitions and formulas on commonly used terms in the specified window/report. | -| ![P984C21T12#yIS1](/img/media/image72.png) | Provides high-level guidance on how to best use the current page. | -| ![P987C23T12#yIS1](/img/media/image73.png)![P987C23T12#yIS2](/img/media/image74.png) | Exports report PDF, CSV or Word (options depend on the screen). | - -Table 5: Commonly Used Buttons - -## Changing Language - -To ensure that QAT is adaptable to users around the world, the application displays text in four different languages: English, French, Portuguese, and Spanish. Users are encouraged to submit tickets if they would like to see a particular label translation improved. (_Note: Translations for application labels can be edited only by **application admins**. Instructions on how to do so can be found in the [translation section](10-annex-1-application-realm-administrator-manual.md#database-translation)._) - -There are two ways to change the language displayed for the user: - -1. **Login Screen:** - -On the top right corner of the login screen, there is a drop-down menu from which users can select their preferred language ahead of logging in. This will not only change the text once you are logged in to QAT but it will also change the text displayed on the login screen. - -![P1001#yIS1](/img/media/image75.png) - -Figure 34: Login Screen Language Change - -2. **Within QAT:** - -Once logged into QAT, the user may change the display language by clicking on the user profile icon on the top right corner of the screen, selecting the preferred language and then the tool will automatically update it’s text/labels. - -![](/img/media/image76.png) - -Figure 35: In Tool Language Change - -## QAT Dashboard - -The supply planning dashboard provides a comprehensive interface with enhanced visualizations and analytics. It is structured into three main sections: Ticker, Overview, Program Spotlight. - -![No alt text provided for this image](/img/media/image77.jpeg) - -Figure 36: Dashboard - -1. **Ticker –** This section displays key information through three automatically scrolling tiles. To manually navigate the tiles, click the dots at the bottom of the tiles. Each tile links to relevant screens. Click on the tile name to be directed to that screen (if you lack access, an appropriate message will display). For example, clicking on the ‘ERP linking’ tile will take you to the ERP Linking screen. - 1. **Realm:** Provides global metrics, such as the number of countries, users, supply planning programs, and forecasting programs. - - 2. **My Access:** Highlights the supply plans you have access to, including downloaded supply plans. - - 3. **ERP Linking:** Displays number of linked shipments by realm and downloaded programs. - -![](/img/media/image78.png) - -Figure 37: Dashboard Ticker - -2. **Overview –** This table offers a high-level summary of one or more programs based on your access. - -![A screenshot of a computer Description automatically generated](/img/media/image79.png) - -Figure 38: Overview Section - -> **Selecting Programs:** - -- Programs can be server-based or downloaded but cannot be mixed - -- Can select 1 to ‘all’ programs. Multi-select. - -- Offline mode limits selection to downloaded programs only, with the checkbox for server programs greyed out. - -- For server programs, some columns/features (e.g., Action column and QPL links) are not displayed, but all other details remain consistent. - -> **Features of the Overview Table** -> -> Each column is designed to present actionable data: - -- **Tooltips:** Hover over tool tip icon in each column for further details - -- **Sorting:** Programs are sorted alphabetically, with an asterisk indicating final and approved versions. - -- **Links and Icons:** - - The ‘Action’ column allows users to delete out a local program as well as click on the cloud icons to be re-directed to the upload or download screens. The cloud icon will appear in red if that downloaded version is outdated. The ‘Action’ column does not appear on the overview table for server programs. - - - Clicking on the number in the ‘Open QAT Problems’ column will direct the user to the QAT Problem List (QPL) for that program. This does not appear for server programs. - - - Clicking on the status in the ‘Review Status’ column will direct the user to the Supply Plan Version & Review screen while clicking on the notebook icon in the same cell will open up the notes history for that program. - -![](/img/media/image80.png) - -Figure 40: Version Notes - -3. **Program Spotlight –** This section provides detailed insights into a single program’s key metrics. Make sure to utilize tooltips and embedded links for efficient navigation and data exploration. All 5 sections have a tool tip next to the header and each header is linked to a QAT screen that you can access by clicking on the header. - -> **Selecting a program:** - -- Supports server or downloaded programs (single select only) - -- Server programs default to the latest version (draft or final) - -- Offline mode limits selection to downloaded programs. - -> **Report Period:** - -- **Server programs:** Defaults to 6 moths past and 18 months future (editable) - -- ![](/img/media/image81.png)**Downloaded programs:** Defaults to 6 months past and 18 months future (non-editable on the dashboard). Admins can set custom defaults by program via the Update Program Info screen. - -> **Spotlight Metrics** -> -> **Stock Status:** - -- Bar graph displays the percentage of months in the report period by stock category. Can hover over graph for detailed breakdowns. - -- Visual customization: Can hide legend elements or copy/paste graph. - -- The accompanying table shows stockout details per planning unit (PU). - -![A screen shot of a chart Description automatically generated](/img/media/image82.png) - -Figure 42: Stock Status Section - -**Forecast Error (Server Versions Only):** - -- Average percentage error calculated for the report period. - -- Errors above a set threshold (default 50%) are highlighted in red. Admins can adjust thresholds per PU and program in the ‘Update Planning Units’ screen. - -- Missing data displays a caution icon with an explanatory note. - -![A screenshot of a computer screen Description automatically generated](/img/media/image83.png) - -Figure 43: Forecast Error Section - -> **Shipments:** - -- Pie chart of shipments by funding source, procurement agent, or status using the dropdown to designate which one. - -- Hover over pie chart for cost breakdowns. The cost breakdown is using the total value of shipments in that report period as the denominator. - -- The accompanying table shows the \# of shipments with funding TBD in the report period. - -![A screenshot of a computer Description automatically generated](/img/media/image84.png) - -Figure 44: Shipment Section - -> **Data Quality:** - -- Reflects QAT problem List metrics, independent of the report period. This is the only section of the 5 sections on the program spotlight that does not use the report period displayed on the dashboard. - -- Updates dynamically with changes made in QPL if user has refreshed the QPL. Otherwise, user can click the refresh icon next to the Data Quality header to refresh the data displayed. - -- Dials for: - - Forecasted consumption: Counts the number of PUs that have at least one month of missing forecasted consumption in the next 18 months. - - - Actual Inventory: Counts the number of PUs that have no recent actual inventory data in the last 3 months. - - - Actual Consumption: Counts the number of PUs that either have no actual consumption data in the last 3 months or a gap in actual consumption data in the last 6 months. - - - Shipments: Counts the number of PUs that have shipments with receive dates in the past, or shipments that should have been “submitted” based on program lead times. - -![](/img/media/image85.png) - -**Expiries:** - -- Displays expiries within the report period, including quantity and total cost - -- Total expiry value across all planning units for the selected program appear at the top right of the section. - -![](/img/media/image86.png) diff --git a/docs/user/02-version-history.md b/docs/user/02-version-history.md new file mode 100644 index 0000000..98c66bc --- /dev/null +++ b/docs/user/02-version-history.md @@ -0,0 +1,20 @@ +--- +id: version-history +title: "Version History" +sidebar_label: "Version History" +sidebar_position: 2 +--- + +# Version History + +| Version | Date | Author/Editor | Notes & Major Changes | +| :--- | :--- | :--- | :--- | +| 0 | Jan 27, 2021 | Altius & FHI 360 | Initial draft. | +| 1 | Mar 15, 2021 | GHSC-PSM FASP | Restructured document; moved realm and application administrator functions to Annex; applied formatting changes and clarity edits. | +| 2 | Apr 26, 2021 | GHSC-PSM FASP | **Software Enhancements:**
- Section 2.E: Included password expiry rules.
- Section 5.A: Updated screenshots and terminology for actual vs. projected inventory.
- Section 6.A: Enhanced QAT Problem List with summary tables, updated logic, and problem categories. | +| 3 | June 10, 2021 | GHSC-PSM FASP | **General Updates:**
- Improved section numbering and footer formatting.
- Added reminders for master data synchronization and offline/online modes.
**Software Enhancements:**
- Section 4.B.3: Updated batch information pop-ups.
- Section 4.B.4: Added ERP Linking instructions and screenshots.
- Section 4.A.3: Integrated alternate reporting units.
- Section 5.C.1 & 5.C.2: Updated suggested shipment logic and added recalculation features.
- Section 5.D: Added final inventory batch pop-ups.
- Section 5.E: Introduced the batch ledger. | +| 4 | Oct 15, 2021 | GHSC-PSM FASP | **Software Enhancements:**
- Section 4.A.1: Updated multi-select functionality for technical areas.
- Annex 1 Section H: Added "organization & country" descriptor to user requirements.
- Annex 1 Section G: Added Organization Type instructions for realm-level master data. | +| 5 | Feb 13, 2023 | GHSC-PSM FASP | **Core Updates:**
- Integrated the Forecasting Module throughout the manual.
**Software Enhancements:**
- Section 2.E: Added online/offline functionality.
- Section 2.H.3: Included network error troubleshooting.
- Section 2.I: Updated Jira HelpDesk ticket management.
- Section 3.D & 6.A.1: Added manual problem descriptions.
- Section 3.E: Explained unencrypted/encrypted JSON exports.
- Section 4.A.2, 5.A, 6.A.3, 6.C.2, & 6.C.3: Explained minimum quantity parameters.
- Section 4.B.3: Added strategic calculator and emergency shipment details.
- Section 4.B.4: Updated ERP Linking functionality.
- Section 4.C.3: Launched QAT Forecast Import.
- Section 5.F: Added "Replan Supply Plan" scenario.
- Section 6.E.1 & 6.E.2: Added Procurement Agent-specific dropdowns.
- Section 6.E.3: Added editing capability to Shipment Details Report.
- Annex 2: Added Business Rules for the Forecasting Module. | +| 6 | Feb 16, 2023 | GHSC-PSM FASP | Updated PMI branding and logo. | +| 7 | Nov 09, 2023 | GHSC-PSM | **Terminology & Core Changes:**
- Standardized "Upload/Download" language throughout.
- Section 3.B: Clarified redownload notifications.
- Section 3.C: Optimized merging forecasts during upload.
- Section 3.D: Renamed 'Rejected' status to 'Needs Revision'.
- Section 4.A.1, 4.A.4 & Annex 3/4: Added Road transport and enhanced Program Admin permissions.
- Section 4.A.6: Multi-program tagging for budgets.
- Section 4.B.1 & 4.B.2: Multi-select PU support for data entry.
- Section 5.A, 5.C, & 5.G: Streamlined shipment handling and improved visualization.
- Section 6.D, 6.F, & 8.B: New reports (Forecast Error, Inventory Turns) and tree forecast enhancements. | +| 8 | Dec 31, 2024 | GHSC-PSM | **Major Platform Enhancements:**
- Section 2.L: Introduced the enhanced Supply Planning Dashboard.
- Section 3.B: Subset data downloads for optimized file size.
- Section 4.A.3: Added PA-specific freight and lead time defaults.
- Section 8.A.3: Bulk extrapolation and optimized ARIMA/TES parameters.
- Section 8.B.1: Enhanced tree reordering, branch templates, and aesthetic updates.
- Annex 1/2: Updated business rules for inventory tagging, auto-adjustments, and realm-level tools. | diff --git a/docs/user/03-managing-programs-and-versions.md b/docs/user/03-managing-programs-and-versions.md deleted file mode 100644 index b20f01e..0000000 --- a/docs/user/03-managing-programs-and-versions.md +++ /dev/null @@ -1,425 +0,0 @@ ---- -id: managing-programs-and-versions -title: "Managing Programs and Versions" -sidebar_label: "Managing Programs and Versions" -sidebar_position: 3 ---- - -# Managing Programs and Versions - -## ![](/img/media/image87.png)Working with Program Data - -| | | | -| ---------------- | ---------- | ----------- | -| | **Online** | **Offline** | -| Data from others | Download | Import | -| Data from users | Upload | Export | - -Table 6 - Working with Program Data - -Program data can be downloaded, uploaded, imported, and exported in QAT. - -- > Note that forecasting programs are entirely different from supply planning programs. Ensure you are in the correct module before downloading, uploading, importing or exporting. - -- > Users must **Download** program data to begin supply planning or forecasting and need to **Upload** their data back to the server to share their work with others. - -- > Uploading can be as “draft” or as “final”. Uploading a supply plan program as “final” initiates the supply plan review process. The status of supply plan versions can be viewed in the **Supply Plan Version & Review** screen – this is the only function described in this section that is available to report viewers. Uploading a forecast program as “final” allows users to import that forecast directly into the supply plan module. See [QAT Forecast Import](04-supply-planning-module-program-data.md#qat-forecast-import) for further instructions on how to import a forecast into a supply plan. - -- > When no internet is available, the **Export** feature allows users to share their data with other users via external devices such as a pen drive/flash drive, who can then use the **Import** data function to open that file on their computer. - -- > These functions can be accessed from the left menu bar under **Program Management.** - -- > Additionally, Download & Upload can be accessed from the top menu bar (see Figure 32) - -![A blue circle with a arrow Description automatically generated](/img/media/image88.png) - -Figure 47 Menu Bar - -## Download/Delete - -- Who? This function is available for **Realm/Program -Admins, Program Users and Supply Plan Reviewers. Not available or needed for Report -Viewers** - -- When? The user must be online to download a program. - -- Why? Users should download a program if they -want to enter or update data, or actively forecast or supply plan (instead of -just viewing reports). Users may download a program when they notice that -their local version is not the latest (i.e. when download icon is red -![P1040\#yIS1](/img/media/image89.png) instead of the usual blue -![P1040\#yIS2](/img/media/image90.png)). Downloading programs enable the -user to work offline. However, note that programs must be downloaded to complete the following functions, even if the user is online: - - Supply Planning: - - Enter/update data (consumption, inventory/adjustments, shipments). For example, if the user is working on “Consumption Details”, he/she must select a program from the given list. The list will show data only for those “Programs” which have been downloaded in the local index database. - - - Supply/scenario plan - - - View QAT Problem List - - - In reports, viewing the data on the local computer (as opposed to on the server) - - - Forecasting: - - Enter/update data (enter/import actual consumption, add/edit forecast trees, extrapolate, etc) - - - In validation or forecast analysis reports, viewing the data on the local computer (as opposed to on the server) - -- What happens when a user downloads a program? -When the user downloads a Program, it gets stored in the local index database -in the JSON format. - -- How to download a Program: - - - -1. > Determine whether you would like to download from the forecasting or the supply planning module, and navigate to the correct module (See [Section 2.J Navigation and Menu Bar](02-getting-started.md#navigation-and-menu-bar)). If you only have access to one module, you can ignore this step. - -2. > Go to “Program Management” \> “Download/Delete Program.” (Alternatively, access this screen by clicking the ![P1055#yIS1](/img/media/image89.png) icon in the top right bar in QAT). The screen will display the Program Data as shown in the below figure. - - > Red text indicates that the program downloaded is not the latest version. Green text indicates that the program downloaded is the latest version. Black text indicates the program is not downloaded. - -![A screenshot of a computer Description automatically generated](/img/media/image91.png) - -Figure 48: Load Program Screen - -3. > To Download - 1. > Select the checkbox next to the program you want to download. By default, QAT will download the latest version of the selected program. - - 2. > _(optional)_ Click on the triangle button next to the program to see all version of the program. The five latest versions will be displayed. Click “see more” to view older versions. Use the checkbox to select which specific version(s) you would like to download. - -![P1063#yIS1](/img/media/image92.png) - -Figure 49: Version Tree – how to expand - -3. > Click on the “**Download**” button to download the program to your system. - - - -4. > To Delete or Clean up: - 1. > Click on the triangle button next to the program to see all version of the program. - - 2. > Select the trashcan icon ![P1068#yIS1](/img/media/image93.png)next to the version of the program you want to delete. If you have multiple versions, you also have the option of clicking the clean-up icon ![P1068#yIS2](/img/media/image94.png)to delete all versions except the latest local version. - -> ![P1069#yIS1](/img/media/image95.png) - -Figure 50: Download Screen Version Tree –clean up and delete icons - -5. > _(optional)_ In the supply planning module, users can download subset of their supply plans as their programs start to have more historical data. - - - -- > **To do this, the user clicks on “Download specific range of supply plan data” and selects the starting month/year for the data they will download.** - -- > If “**Download specific range of supply plan data**” is checked, the version of the program selected will only show data starting from the desired date (minimum 18 months in the past). - -![A screenshot of a computer Description automatically generated](/img/media/image96.png) - -Figure 51 Download specific range of data - -- > **The date range selection would apply to ALL programs selected for download. If the user wants to download one full program (program A) and one truncated program (program B), the user must complete the download process twice – one for the full program and another for the truncated program.** - -- > **Older data not downloaded always exists on the server and cannot be deleted or overwritten.** - -- > **When user downloads truncated program (v1), updates it, and uploads a new version (v2), the server version will include the entirety of the data, while the new local version will remain truncated with previously selected start date. User may delete that version and download the full v2 from the server, or v2 with a different range of data, as needed** - -Note: If you download an older version, or if another user uploads a later version on the server after you download, you will see a message like the below in Figure 36 any time master data sync happens (upon logging in, upon downloading new program, or if manually requested by user). - -- > If you select “OK”, the latest server version will be downloaded and your local version will be permanently deleted. Please only select “OK” if you are okay with discarding your changes or if you have not made any changes. - -- > If you select “cancel”, no action will be taken and you will remain with your local version. - -![P1074#yIS1](/img/media/image97.png) - -Figure 52: “More recent server” warning on user login - -## Upload - -- Who? - - **Supply Planning: Application/Realm/Program Admins, and Program Users. Not available or needed for Report Viewers** - - - **Forecasting: Application/Realm/Program Admins and Program Users. Not available or needed for Forecast Viewers** - -- Why? - - > **Uploading as draft:** - - **Supply Plans/Forecasts:** Share the local version of program data with the server and other users (uploading as draft) - - - > **Uploading as final:** - - **Supply Planning:** Indicate to all users that the supply plan has been fully updated, and also to initiate the supply plan review process - - - **Forecasting:** Allow final forecasts to be importable into the supply plan - -- What happens when a user uploads a program? -When the user uploads a Program, it becomes the latest version on the server -and is available for all other users to download or view - - Note that if a truncated version of the supply plan program was downloaded (e.g. v10), when the user uploads their local version (becoming v11), the new version on the server will contain all the data, not just the subset the user worked with. - -- When? The user must be online to upload a program - -**Supply Plan Module -** How to Upload a Program: - -1. Ensure you are in the Supply Plan Module - 1. Go to “Program Management” \> “Upload Version.” - - 2. Or, Click the ![P1097#yIS1](/img/media/image98.png) icon in the top right bar in QAT - -2. ![](/img/media/image99.png)Use **Program** dropdown to select the appropriate program, if it is not already selected (only downloaded programs will be visible) - -3. Select a **Version Type** using the dropdown: - 1. **Draft Version**: Indicates the supply plan is a work in progress. Use this to share a supply plan with others, but not ready to be submitted into the supply plan review process. - - 2. **Final Version**: Indicates that the supply plan has reached a final status, and is being submitted to the supply plan review process. Note that QAT will not allow the user to upload as final with any “Open” issues in the QAT Problem List. Please use the QAT problem list (see [Closing and Addressing Problems](06-supply-planning-module-reports.md#closing-and-addressing-problems)) to mark any open issue as “Addressed” with an explanatory note, or move issue to “in compliance” via data entry first. - -4. In **Notes**, type any overall notes about this version, such as summarizing the major changes made the supply plan and the reasoning behind those changes. - -5. In the 4 tabs – Consumption, Inventory, Shipment, QAT Problem list – QAT will display a detailed comparison of supply plan details between the “Local version” and the “Server version.” Review each tab for any highlighted records. Yellow records require your action before you can upload the supply plan - -> **Legend Explanation**: - -- > Green: represents changes that have been made in the local version; by uploading your program, these changes will save to the online server as a new version. - -- > Light blue: represents changes made by another user that has already been uploaded to the live/online version – because this is a data point that you did not edit, the server version will persist for this/these records. - -- > Yellow: represents a conflict in data between the local version and the server version for the same data cell. You must resolve all yellow conflicts before the Upload button appears. To resolve a conflict, right click on the relevant row, and select “Resolve Conflict.” In the pop-up screen, choose whether to keep the local version of the data or the server version of the data. (see Figure 32) - -![P1109#yIS1](/img/media/image100.png) - -Figure 55 Resolving Conflict while uploading supply plan - -6. After reviewing all updates and resolving all conflicts, click the “Upload” button. QAT will provide a confirmation message. - -7. **(For final)** Supply planners and supply plan reviewers will receive an email notification confirmation that their supply plan has been uploaded as final. - -8. **(For final)** Supply planners, program admins and supply plan reviewers, realm admins, program users, data viewers and supply plan viewers will receive an email notification when their supply plan is rejected. They can also check the status of their supply plan review in the [Supply Plan Version and Review](#supply-plan-version-and-review-supply-plan-module-only) Report. - -**Forecasting Module –** How to Upload a Program: - -1. Ensure you are in the Forecasting Module - 1. Go to “Program Management” \> “Upload Version.” - - 2. ![](/img/media/image101.png)Or, Click the ![P1119#yIS1](/img/media/image102.png) or ![P1119#yIS2](/img/media/image103.png) icon in the top right bar in QAT - -2. Use **Program** dropdown to select the appropriate program, if it is not already selected (only downloaded programs will be visible) - -3. Select a **Version Type** using the dropdown: - 1. **Draft Version**: Indicates the forecast is a work in progress. Use this to share a forecast with others. - - 2. **Final Version**: Indicates that the forecast has reached a final status and can be imported into the supply plan. Note that QAT will not allow the user to upload as final if no there are no changes between the latest server version and the version being uploaded. - -4. In **Notes**, type any overall notes about this version, such as summarizing the major changes made in the forecast and the reasoning behind those changes. - - - -9. In the 5 tabs – Version Settings, Planning Unit, Consumption, Tree, Selected Forecast – QAT will display a detailed comparison of details between the “Local version” and the “Server version.” Review each tab for any highlighted records. Yellow records require your action before you can upload your version - -> **Legend Explanation**: - -- > Green: represents changes that have been made in the local version; by uploading your program, these changes will save to the online server as a new version. - -- > Light blue: represents changes made by another user that has already been uploaded to the live/online version – because this is a data point that you did not edit, the server version will persist for this/these records. - -- > Yellow: represents a conflict in data between the local version and the server version for the same data cell. You must resolve all yellow conflicts before the Upload button appears. To resolve a conflict, right click on the relevant row, and select “Resolve Conflict.” In the pop-up screen, choose whether to keep the local version of the data or the server version of the data. (see Figure 42 Resolving Conflict while uploading forecast) - -![P1131#yIS1](/img/media/image104.png) - -Figure 58 Resolving Conflict while uploading forecast - -5. After reviewing the table and confirming the selected forecasts, click the ‘Upload’ button. This will open up a separate pop-up window (“Forecast Validation”). The **Forecast Validation** screen provides users the ability to double check their work and anything they might have missed when creating and selecting the forecast(s). The user has the option to view the different validations for only the selected forecasts for each planning unit, or to view the validations for all forecasts in the program. To change this setting, check/uncheck the box in the top of the screen. For ease of access, the validations that are in blue font are linked to the page in QAT where the validation is being flagged. For example, if a forecast is not selected for one of the planning units, clicking on the planning unit in the validation page will direct you to the Compare and Select screen where you can select a forecast. - 1. **Section 1** flags any active planning units that do not have a selected forecast. - - 2. **Section 2** looks at all active planning units that use consumption-based forecasting. 2a will flag if any of the consumption forecasts are missing actual consumption values (gap). 2b will flag any planning units that do not have at least 24 months of consumption data. If the checkbox at the top is selected, then only the planning units with a selected consumption forecast will be flagged. Planning units with a selected tree forecast will not be flagged in this section. - - 3. **Section 3** looks at all active planning units that use tree forecasting. Planning units with a selected consumption forecast will not be flagged in this section. 3a flags any planning units that do not appear on any tree. 3b flags any tree branches that are missing a planning unit. 3c flags any tree nodes where the parent’s child nodes don’t add up to exactly 100%. In section 3c, clicking on the + icon will expand a table with details on which nodes and % are being flagged. - - 4. **Section 4** compiles all of the notes across the different screens in the forecasting module. 4a will display notes from the Data Entry & Adjustment screen. 4b will display notes from the ‘Manage Tree’ screen. These notes include both tree specific notes and scenario specific notes. 4c will display notes from the ‘Manage Tree’ screen, specifically the notes in each node. - -![P1139#yIS1](/img/media/image105.png) - -Figure 59: Forecast Validation - -6. After reviewing all validations and resolving ay issues, click the “Okay” button to upload. QAT will provide a confirmation message. - -## Supply Plan Version and Review (Supply Plan Module Only) - -- Who? This function is available for **Application/Realm/Program -Admins, Program Users, Supply Plan Reviewers, and Supply Plan Viewers** - -- When? The user must be online. Supply Plan Reviewers -will receive an email from QAT whenever a supply plan is uploaded as final (i.e. -ready for review). - -- Why? This function allows users to **review the -supply plan review status of supply plans.** - - **Supply planners** (program admins & users) can check on the status of their review - - - **Supply plan reviewers** can view the review queue - - - **Supply Plan viewers** can check on the status of supply plan reviews - -- How? - - - -1. > Go to “Program Management” \> “Supply Plan Version and Review” and the below screen will be displayed. Select the Report Period, Country, Program, Version Type, and Status. In this table, users can see the status of all supply plans and any version comments. Users can also use the search, filter and sort options (see [Navigation and Menu Bar](02-getting-started.md#navigation-and-menu-bar)) to find specific programs. - -![A screenshot of a computer Description automatically generated](/img/media/image106.png) - -Figure 60: Supply Plan Versions and Review - -2. > Click any row in the table to open the details for that supply plan. - -> **_For Supply Plan Reviewers_** **ONLY** – - -1. Use the first tab “Supply Planning” to review the stock status and data elements of any given planning unit - -2. Use the second tab “QAT Problem List” to review any issues within the supply plan. - 1. Use the “**Reviewed**” column and check the checkbox in each row as you review them. All issues other than “in compliance” or “resolved” must be checked as “reviewed” in order for you to approve or reject the plan. - - 2. Use the “**Enter Reviewer Notes**” column to note any feedback for the supply planner. - - 3. Update the “**Problem Status**” as needed – Leave issues as “**Addressed**” if you want the supply planner to review them again in the next review cycle (the issue will become “open” in the next version). Mark issues as “**Resolved**” if they don’t need to be reviewed again even in future review cycles. Mark issues as “**Open**” if you want to communicate to the reviewer that they need to update their comments. - - 4. If there is a problem that should be addressed by the supply planner, but is not automatically flagged by the QAT Problem List, the reviewer can add a manual problem by clicking the “+” symbol in the top right of the screen. - 1. Manual problems must have an associated planning unit, criticality, description, and suggestion. These problems will be added as a separate row in the QAT Problem List for supply planners to address. - -3. After reviewing, change the status of the Supply Plan to **Approved** or Needs Revision, provide notes (mandatory), and click “Update” - 1. Utilize the Version Notes History to view overall notes on the supply plan through time. - -![A screenshot of a computer Description automatically generated](/img/media/image107.png) - -Figure 61: View Notes History Button - -> ![A screenshot of a computer Description automatically generated](/img/media/image108.png) - -Figure 62: Version Notes History Example - -2. **\*Note:** There is an additional status for “No Review Needed” that can be used when a duplicate supply plan is uploaded or a supply plan is uploaded outside of the submission period window.\* - -![A screenshot of a computer Description automatically generated](/img/media/image109.png) - -Figure 63: Supply Plan Version and Review (second screen) - -3. > The user that submitted the supply plan for review will be notified by email when their submission is either Approved, Needs Revision, No Review Needed. Rules for supply plan review email notifications are as follows: - 1. Notification of **Uploaded** final supply plan - 1. Sent to: All supply plan reviewers with access to that program. - - 2. Cc’d: User who uploaded the version - - 3. Bcc’d: All program admins with access to that program. - - 2. Notification of **Needs Revision** supply plan: - 1. Sent to: The user who uploaded the supply plan. - - 2. Cc’d: Reviewer who requested revisions to the version - - 3. Bcc’d: All reviewers with access to that program as well as admins with access to that program. - - 3. Notification of **Approved** supply plan: - 1. Sent to: The user who uploaded the plan. - - 2. Cc'd: All users who have access to that program except for app admins and reports viewer. - - 4. Notification of **No Review Needed** supply plan: - 1. Sent to: The user who uploaded the plan - - 2. Cc'd: The supply plan reviewer - -## Export - -- Who? This function is available for **Application/Realm/Program -Admins, Program Users and Supply Plan Reviewers. This function is not available -or needed for Report Viewers.** - -- Why? The “Export Program” function is used when -the user wants to export the program to his/her local machine. By using the Export -function, Program data can be shared with others offline. For example, user A can -export a program and save that file on a USB drive to share with user B, who is -offline. - -- What? The program data file will be exported in -the zip format. The zip file contains all the data for that version of the program. -Users can choose to export in encrypted or unencrypted format. This file can subsequently -be shared with others to import into QAT, or, if unencrypted, analyzed outside -of QAT. - - - -- **Note:** if the user downloaded a version with a selected range of data, the export will also be for that selected range of data) - -![P1190#yIS1](/img/media/image110.png) - -Figure 64: Export Program Screen - -- How to export a program: - - - -1. > Determine whether you would like to export from the forecasting or the supply planning module, and navigate to the correct module (See [Section 2.J Navigation and Menu Bar](02-getting-started.md#navigation-and-menu-bar)). If you only have access to one module, you can ignore this step. - -2. > Go to “Program Management” \> “Export Program” - -3. > Select the program to be exported using the dropdown. Programs must be first downloaded before exporting is available. (See [Section 3.B Download/Delete Program](#downloaddelete)). - - If the program was downloaded with a subset of data, the export will also be limited to that same subset. - -4. > Determine whether or not you need an unencrypted version. - - For importing back into QAT, leave the “Do you want to encrypt” checkbox checked - - - For analyzing data outside of QAT, uncheck the “Do you want to encrypt” checkbox - -5. > Click on the “Submit” button to save the changes. - -6. > A browse window will pop up. Select the folder you want to save the exported file in. Then click “Save.” - -7. > The .zip file will now be saved in the selected folder. - -8. > Share the .zip file with others as needed. - -## Import - -- Who? This function is available for **Application/Realm/Program -Admins, Program Users and Supply Plan Reviewers. Not available or needed for Report -Viewers** - -- Why? The “Import Program” function is used when -the user is working on the program in offline mode and wants to open a program -that has been exported into a .zip file - - **Note**: The program data file must be saved in the zip format). For example, user B can (while offline) import a program that user A exported and saved to an external device - - - **Note**: If the user exported a version with a selected range of data, the import will also be for that selected range of data. - -- When? This function can be used when offline or -online. - -![](/img/media/image111.png) - -Figure 65: Import Program Screen - -- How to import a program: - - - -1. > Determine whether you would like to export from the forecasting or the supply planning module, and navigate to the correct module (See [Section 2.J Navigation and Menu Bar](02-getting-started.md#navigation-and-menu-bar)). If you only have access to one module, you can ignore this step. - -2. > Go to “Program Management” \> “Import Program” - -3. > Click “Browse”. Choose the required file that needs to be imported. The selected file must be in the zip format. The zip file may have multiple programs. - -4. > Click “Next” - -5. > Select the required program to import. (if only one program is in the file, it will be auto selected) - -6. > Click on the “Import” button to import the program into the local machine. - -## Version Comparison - -**Purpose:** Enable users to view and compare 2 different versions of the same forecast program. In this screen, users will select a forecast program to view and from there select 2 versions of that program to compare. The user can select both local and server versions as well as draft and final versions. If the version has a \* next to it, this indicates that the version is final. Once the user has selected all of the dropdowns, a table will appear comparing the two forecast versions. For each planning unit and region combination, the table will display the selected forecast, forecast quantity, and notes for each of the 2 forecast versions. This screen is only for viewing purposes and no changes can be made to the selected forecasts in this screen. - -![P1227#yIS1](/img/media/image112.png) - -Figure 66: Version Comparison - -**Using this screen:** - -1. **First, select from the output filters from the dropdowns. This screen only compares 1 program at a time, but allows the user to compare multiple versions of that program. The user has the ability to compare any combination of final and draft versions as well as local and server versions. If** the version has a \* next to it, this indicates that the version is final. The version notes and forecast period will appear greyed out as these are non-editable fields. To update these fields, go to ‘Update Version Settings’. - -2. Once all dropdowns are selected, a table will appear with data across for both forecast versions that were selected. For each planning unit and region combination, the table will show the selected forecast, total forecast quantity for the forecast period, and any forecast notes for that selected forecast. Each side of the table represents 1 of the 2 forecast versions selected. The top row of the table shows which version the side is showing data for. - -3. This screen can be exported in both PDF and CSV format by clicking the icons in the top right of the page. diff --git a/docs/user/03-table-of-contents.md b/docs/user/03-table-of-contents.md new file mode 100644 index 0000000..45a011a --- /dev/null +++ b/docs/user/03-table-of-contents.md @@ -0,0 +1,64 @@ +--- +id: table-of-contents +title: "Table of Contents" +sidebar_label: "Table of Contents" +sidebar_position: 3 +--- + +# Table of Contents + +Below is the full breakdown of the QAT user documentation. Click on any section to navigate to the detailed guide. + +- [Acronyms](18-acronyms.md) +- [Section 1: Overview](04-overview.md#overview) +- [Section 2: Getting Started](05-getting-started.md#getting-started) +- [Section 3: Managing Programs and Versions](06-managing-programs-and-versions.md#managing-programs-and-versions) +- [Section 4: Supply Planning Module - Program Data](07-supply-planning-module-program-data.md#supply-planning-module-program-data) +- [Section 5: Supply Planning Module - Supply Planning](08-supply-planning-module-supply-planning.md#supply-planning-module-supply-planning) +- [Section 6: Supply Planning Module - Reports](09-supply-planning-module-reports.md#supply-planning-module-reports) +- [Section 7: Forecasting Module - Program Data](10-forecasting-module-program-data.md#forecasting-module-program-data) +- [Section 8: Forecasting Module - Forecasting](11-forecasting-module-forecasting.md#forecasting-module-forecasting) +- [Section 9: Forecasting Module - Reports and Outputs](12-forecasting-module-reports-and-outputs.md#forecasting-module-reports-and-outputs) +- [Annex 1: Application & Realm Administrator Manual](13-annex-1-application-realm-administrator-manual.md#annex-1-application-realm-administrator-manual) +- [Annex 2: Business Rules](14-annex-2-business-rules.md#annex-2-business-rules) +- [Annex 3: User Role Matrix](15-annex-3-user-role-matrix.md#annex-3-user-role-matrix) +- [Annex 4: Business Functions](16-annex-4-business-functions.md#annex-4-business-functions) +- [Annex 5: PipeLine Program Import](17-annex-5-pipeline-program-import.md#annex-5-pipeline-program-import) + +--- + +## Acronyms + +| Acronym | Definition | +| :--- | :--- | +| **AMC** | Average Monthly Consumption | +| **ARIMA** | Auto Regressive Integrated Moving Average | +| **ARTMIS** | Automated Requisition Tracking Management Information System | +| **ARU** | Alternate Reporting Unit | +| **ERP** | Enterprise Resource Planning | +| **EU** | Equivalency Unit | +| **FASP** | Forecasting and Supply Planning | +| **FEFO** | First Expiry, First Out | +| **FP/RH** | Family Planning and Reproductive Health | +| **GFPVAN** | Global Family Planning Visibility and Analytics Network | +| **GHSC-PSM** | Global Health Supply Chain – Procurement and Supply Management | +| **GLN** | Global Location Number | +| **GTIN** | Global Trade Item Number | +| **MSE** | Mean Squared Error | +| **MAPE** | Mean Absolute Percentage Error | +| **MNCH** | Maternal, Newborn and Child Health | +| **MOH** | Ministry of Health | +| **MOQ** | Minimum Order Quantity | +| **MOS** | Months of Stock | +| **PEPFAR** | President's Emergency Plan for AIDS Relief | +| **PMI** | U.S. President's Malaria Initiative | +| **PWA** | Progressive Web Application | +| **QAT** | Quantification Analytics Tool | +| **RMSE** | Root Mean Squared Error | +| **RO** | Requisition Order | +| **SKU** | Stock Keeping Unit | +| **SOH** | Stock on Hand | +| **STG** | Standard Treatment Guidelines | +| **TES** | Triple Exponential Smoothing (Holt-Winters) | +| **USAID** | United States Agency for International Development | +| **WAPE** | Weighted Absolute Percentage Error | diff --git a/docs/user/04-overview.md b/docs/user/04-overview.md new file mode 100644 index 0000000..93300b9 --- /dev/null +++ b/docs/user/04-overview.md @@ -0,0 +1,102 @@ +--- +id: overview +title: "Overview" +sidebar_label: "Overview" +sidebar_position: 4 +--- + +# Overview + +# Overview + +## Introduction + +The Global Health Supply Chain – Procurement and Supply Management (GHSC-PSM) program is an official United States Agency for International Development (USAID) project. Implemented by Chemonics International and its consortium members, GHSC-PSM ensures the uninterrupted supply of health commodities to support U.S. Government-funded public health initiatives worldwide. + +The Forecasting and Supply Planning (FASP) tool modernization initiative was supported by the U.S. President’s Emergency Plan for AIDS Relief (PEPFAR), the U.S. President’s Malaria Initiative (PMI), USAID’s Family Planning and Reproductive Health (FP/RH) program, and USAID’s Maternal and Child Health (MCH) program. + +### Background and Objectives +Previous USAID-funded projects, such as Supply Chain Management Systems (SCMS) and DELIVER, successfully implemented a suite of FASP tools. However, these tools were often siloed, had inconsistent user interfaces, and required manual data exchange. + +The primary objective of this initiative was to build a next-generation FASP platform that is: +- **Scalable and Modular**: Built on a modern, operating-system-agnostic architecture. +- **Web-Based with Offline Capabilities**: Ensuring accessibility even in low-connectivity environments. +- **Interoperable**: Designed for seamless data sharing across stakeholders and public health systems. +- **User-Centric**: Focused on usability and automation to drive end-to-end data visibility and evidence-based decision-making. + +## Forecasting vs. Supply Planning + +- **Forecasting**: An estimate or prediction of the quantities of products to be consumed by clients or consumers over a future period. +- **Supply Planning**: The component of supply chain management focused on fulfilling demand plan requirements. The goal is to balance supply and demand to meet the financial and service delivery objectives of the health program. + +## What is QAT and What Can It Do for You? + +The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages advanced technologies to enhance the functionality of legacy tools like PipeLine and Quantimed by providing: +- **Flexible Forecasting**: Customizable tree structures and advanced extrapolation methodologies (ARIMA, Holt-Winters, etc.). +- **Scenario Planning**: Robust tools to model and compare different supply chain scenarios. +- **Offline Functionality**: Reliable data entry and management without a constant network connection. +- **Standardization**: Master data management to drive consistency across all programs. + +### Core Functions +- **Forecasting**: Multi-method forecasts, visual output comparison, and stakeholder consensus tools. +- **Monitoring**: Real-time tracking of stock balances, minimum/maximum stock parameters, and automated problem identification (e.g., pending shortfalls). +- **Procurement Planning**: Shortfall calculations, lead-time-based action tracking, and estimated shipment/freight cost modeling. + +## Who Should Use QAT? + +QAT empowers local program managers to take charge of their own forecasting and procurement planning. While program managers are the primary users, the system provides vital insights for policymakers, country directors, procurers, and donors. + +| User Group | Purpose | +| :--- | :--- | +| **Supply Planners / Program Managers** | Manage procurements across multiple funding sources and procurement agents. QAT provides visibility into long-term stock status and decreases the risk of stock imbalances. | +| **Forecast / Demand Planners** | Estimate demand using flexible templates and built-in validations. Compare methodologies and select final commodity forecasts using integrated visualizations. | +| **Policy Makers / Directors** | Visually compare forecasts and analyze the implications of budgetary constraints or new program targets. | +| **Procurers and Donors** | Gain clear visibility into current supply status and future procurement requirements. | + +*Table 1: Recommended QAT users and purpose* + +## Important QAT Concepts and Terms + +### Cross-cutting Terms + +| Term | Definition | +| :--- | :--- | +| **Forecasting Unit** | The base unit used for a specified forecasting period (e.g., one tablet, one milliliter). | +| **Master Data (Sync)** | A standardized set of data (e.g., product lists, funder names) shared across the system. Users can request updates via a ticketing mechanism. QAT syncs master data during login or manual triggers. Note that full forecast or supply plan datasets must be downloaded for local use. | +| **Planning Unit** | The product planned for in QAT, described up to the primary packaging level (e.g., a bottle of 30 tablets). | +| **Programs** | Similar to a "supply plan database" in legacy tools. Each program consists of one country, specific technical areas, a region (e.g., national level), and an organization (e.g., MOH). | +| **Realm** | A high-level subdivision in QAT (e.g., Global Health) governed by its own master data. | +| **Region** | Sub-national levels used to structure program data. To define a region, both consumption and inventory data must be entered at that level for national aggregation. | +| **Technical Area** | Synonymous with commodity groups (e.g., ARV, Malaria, Family Planning) used to categorize programs. | +| **Tickets** | The mechanism for reporting bugs or requesting master data updates. Tickets are resolved by system administrators. | +| **User Roles** | Dedicated assignments that define data access and functional permissions within the application. | + +### Supply Planning Terms + +| Term | Definition | +| :--- | :--- | +| **Alternate Reporting Unit (ARU)** | The product and unit in which a country's data (consumption or stock) is reported. This may differ from the planning unit. QAT allows users to define an ARU and a conversion factor (multiplier) to the planning unit. For example, if the planning unit is a bottle of 30 tablets and inventory is reported in boxes of 20 bottles, the multiplier is 20. See Section 4.A3 (Alternate Reporting Unit) for details. | +| **Average Monthly Consumption (AMC)** | A dynamic value calculated month-to-month based on average product usage over a specific period. By default, QAT calculates AMC using the past three months, the current month, and the next two months. Missing monthly data is treated as "null" rather than zero. Administrators can adjust the calculation window up to 12 months into the past and future.
![AMC Formula](/img/media/image6.png) | +| **Data Source** | The origin of data entered into QAT. Data sources must be applied to all transactional records (Consumption, Inventory, Adjustments, and Shipments). Selection depends on the specific Data Source Type of the record. | +| **Enterprise Resource Planning (ERP)** | QAT is designed to interface with various procurement management systems (ERPs). Currently, an interface with ARTMIS enables the direct import of USAID product and shipment data which reduces manual planning efforts by auto-updating delivery dates and statuses. | +| **Funding Source** | Any financial institution or entity providing facilities or funding for the program. Every shipment must be assigned a funding source. | +| **Lead Times** | Mapped to supply planning statuses, lead times are input per product, procurement agent, or program. Calculations include:
- **Planned to Submitted**: Time from identifying a need to entry in the procurement system.
- **Submitted to Approved**: Time from entry to procurement approval.
- **Approved to Shipped**: Time from approval to supplier dispatch.
- **Shipped to Arrived (Sea/Air)**: Transit time to the port of entry.
- **Arrived to Received**: Time for customs clearance and delivery to the final destination. | +| **Min & Max Stock Levels** | **Minimum stock level** (in months) is determined per planning unit at the program level.
![Min Stock Formula](/img/media/image7.png)
**Maximum stock level** is dynamically calculated as the minimum stock level plus the reorder interval.
![Max Stock Formula](/img/media/image8.png) | +| **Minimum Order Quantity (MOQ)** | The minimum number of units a product must be ordered in. | +| **Months of Stock (MOS)** | A measure of inventory levels relative to consumption, conceptually similar to PipeLine but using the updated QAT AMC methodology.
![MOS Formula](/img/media/image9.png) | +| **Plan by MOS** | Best suited for high-consumption products with minimal expiries where shipments primarily replace consumed stock. Planning focuses on maintaining month-based stock parameters. See Section 4.A2 for configuration. | +| **Plan by Quantity** | Best suited for low-consumption products with high expiry rates (e.g., emergency medicines). Planning focuses on maintaining a fixed quantity of stock (e.g., 2 units per facility) rather than months of stock. See Section 4.A2 for configuration. | +| **Reorder Interval** | The user-defined number of months between shipments (default is 1 month). This value is used to calculate maximum stock levels for both MOS and Quantity-based planning. | +| **Shipment Statuses** | Tracking a shipment through its lifecycle via nine statuses: Suggested (automated warning), Planned (confirmed for projection), Submitted (ordered), Approved, Shipped, Arrived (at port), Received (at destination), Cancelled, and On-Hold. | +| **Unmet Demand** | Quantities that would have been consumed if stock were available. QAT tracks unmet demand separately when:
a) Forecasted consumption exceeds available stock.
b) Actual consumption includes stock-out periods.
c) A negative adjustment exceeds the projected ending balance. | +| **Volumetrics** | Feature allowing users to define product volumes to estimate the total physical size and logistics requirements of orders. | + +### Forecasting Terms + +| Term | Definition | +| :--- | :--- | +| **Consumption-based Forecast** | A prediction of future demand based on historical actual consumption data using linear and non-linear extrapolation methodologies. | +| **Tree Forecast** | Flexible forecasting structures used to convert diverse data types (demographics, morbidity, services) into commodity requirements by modeling service pathways. | +| **Tree Template** | Pre-defined forecasting trees that can be downloaded and customized to a specific user's context. | +| **Usage Template** | Pre-defined rates of use for specific products that can be applied consistently across different trees and programs. | +| **Continuous and Discrete Usage** | When defining usage rates, users can choose between **Continuous** (ongoing) or **Discrete** (specific period or single-use) applications. | diff --git a/docs/user/04-supply-planning-module-program-data.md b/docs/user/04-supply-planning-module-program-data.md deleted file mode 100644 index c7b8808..0000000 --- a/docs/user/04-supply-planning-module-program-data.md +++ /dev/null @@ -1,1258 +0,0 @@ ---- -id: supply-planning-module-program-data -title: "Supply Planning Module: Program Data" -sidebar_label: "Supply Planning Module: Program Data" -sidebar_position: 4 ---- - -# Supply Planning Module: Program Data - -As previously defined on [Important QAT Concepts and Terms](01-overview.md#important-qat-concepts-and-terms), a program is similar in structure to a PipeLine supply plan database. Each program consists of only one country, one or more technical area(s), one region (national level, central level, etc.), and one organization (MOH, PEPFAR-only, PMI-only). Every program within a realm is governed by the same standardized master data, such as product catalog, procurement agents, funding sources, data sources, etc. - -Program data management sits on the third tier of the QAT system hierarchy and is generally done by users with the roles **program admin and program user** (for more information on the user roles, please see [Annex 3: User Role Matrix](12-annex-3-user-role-matrix.md#annex-3-user-role-matrix)). Program-level master data managed by these users include budgets and alternate reporting units. - -A user can “Download” or “Delete” programs from their local machine. Programs can also be “Imported” to the local machine or “Exported” from the local machine to share with other users if there are connectivity issues. - -Program admins and users can manipulate two big categories of data within their programs: Program data and Transactional data (the “big 3” – consumption, inventory, shipments). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Data Category - - Details -
Background Data - Program Info - Program Manager, Freight %, Lead Times
- Product Info - Planning units – min, reorder interval, alternate reporting units
- Budget - Funding source, amounts, beginning and ending dates, etc. 
-

Transactional Data

-

(“Big 3”)

-

for each product

- 		- Consumption - -

Forecasted consumption

-

And actual consumption, as it becomes available

-
- Stock - Inventory counts & Adjustments
- Shipments - -

- Quantities, receive date, status, procurement agent, funder & - associated budget -

-

(if available) batch #s & expiry dates

-
- -Table 7: Program level data - -## Background Data - -Note: All background data must be updated while a user is online. It is recommended that users click “master data sync” after making any background data updates so it is reflected throughout the tool. - -### Program Information - -Program managers in QAT can define their general program parameters, by selecting from a list of dropdowns that contain realm-level master data for each the fields**.** These general parameters for the supply planning module include program name, program manager, default freight percentages for air, sea, & road freight, lead times by shipment status, and notes. General parameters for the forecasting module include program name, program manager, and notes. **Program users** will be able to list/view all the programs they have access to, while only **Program Admins** are able to update any of the program’s general parameters. - -**Update program information:** - -1. Click on “Program Management” and then select “Update Program Info” - -2. Click on the program that needs to be updated - 1. Program Admins can add/remove procurement agents and funding sources that already exist in QAT to their program. This will in turn, add/remove the procurement agents to the dropdown fields in the [Shipment Data entry](#shipment-data) screens. If a user would like to add a procurement agent to their program that does not exist in QAT, they can take out a ticket with the [QAT HelpDesk](02-getting-started.md#tickets-for-addingupdating-users-and-master-data) system. - -![](/img/media/image113.png) - -Figure 67: Update Program Info – Supply Planning Module - -![A screenshot of a computer Description automatically generated](/img/media/image114.png) - -Figure 68: Update Program Info – Forecasting Module - -3. Update fields as desired, and click “Submit” - -**\*Note:** QAT only allows Realm-level Admin or App-level Admins to update the fields which are in gray in the Update Program Info screen. If a user requires these fields to be updated, they can take out a ticket with the [QAT HelpDesk](02-getting-started.md#tickets-for-addingupdating-users-and-master-data) system.\* - -### Planning Units - -The planning unit is the product used in QAT as the basis for planning procurements, and displaying consumption, shipments, inventory, and adjustments. A planning unit name is usually inclusive of a full description up to the primary packaging; thus, its nomenclature closely follows the pack size in which dispensing happens, i.e., one bottle of 30 tablets, blister of 10x10 capsules, etc. - -The QAT planning unit catalog is considered realm-level master data, meaning any additions / edits / subtractions from that catalog are managed at the realm-level and apply to all programs within that realm. Every program must have at least one planning unit that **Program Admins** can select from the realm-level catalog to **add to their programs or deactivate** from their programs. Program Admins can also update any parameter related to a particular planning unit, including the reorder frequency, minimum months of stock, average monthly consumption calculation, local procurement agent lead time, shelf life, and price. Planning units can be deactivated from the program if no longer in use, allowing the program admins to keep all the legacy data. If the planning unit does not exist in the QAT catalog, please raise a ticket through the QAT Helpdesk so that it can be created for the entire realm. See more on ticketing in section [QAT Helpdesk and Tickets](02-getting-started.md#qat-helpdesk-and-tickets). - -![](/img/media/image115.png) - -Figure 69: Parameters to update per planning unit. - -**Planning Unit Parameters:** - -- > **Conversion Factor (FU:PU):** A non-editable field providing information on the conversion factor between the chosen PU and its associated FU - -- > **Plan By: choose between “MOS” for those planning units that are consumed in large quantities or “Quantity” for those planning units that are** consumed in low quantities, or for emergency purposes with high expiries - -- > **Reorder Interval (in months): the** number of months between shipments**. Reorder interval + Min MOS = Max MOS** - -- > **Min Months of Stock (MOS): the minimum amount of inventory, in months, that should be available on-hand to meet demand and avoid stockouts** - -- > **Min Quantity: the minimum quantity of inventory that is determined to be needed on-hand** - -- > **Average Monthly Consumption (AMC) calculation, which is the average quantity a product is used over a selected period of time, will take an average of the program admin-eneter values for “Months in future (including current month)” and “Months in past”** - - - -- **Local Procurement Lead Time: the ent**ire lead time (‘planned to received’), in months, for locally procured planning units. Ideally in local procurement, the lead time would be much shorter than that for international. - - > **Distribution Lead Time: Number of months between shipment receipt and the product to be distributed down to the lowest level. Used for suggested shipments ahead of understock.** - - - > **Shelf Life: number of months from shipment receipt (status = received) until expiry. This is an average number of months for the planning unit – for entering exact batch data, including expiry dates see [Supply Planning: Project Expired Stock and Batch Information](05-supply-planning-module-supply-planning.md#supply-planning-project-expired-stock-and-batch-information)** - - - > **Forecast Error Threshold (%): a value used in the Forecast Error (Monthly) and Forecast Error (by PU) consumption reports as a demarcation of whether a forecast error is deemed too high** - - - > **Catalog Price: average price of a single planning unit, which will be used in calculating shipment costs. Price per program and procurement agent can be more granularly updated in [Program/Procurement Agent-specific Information](#programprocurement-agent-specific-information) or specific shipment prices can updated in the [Shipment data entry](#shipment-data) screen.** - - - > **Notes: a free text field to add relevant planning unit information (i.e. phasing-in/out timelines, if the planning unit is central/national-level data, etc.). These notes are available for viewing the in the Supply Plan report, Supply Plan Version & Review Supply Planning screen, Supply Planning screen, & Scenario Planning screen.** - -**Update planning units within a program:** - -1. Ensure that you are working in ‘online’ mode. Select “Program Management” and then “Update Planning Units” - -2. Select the program to display the planning units currently managed - 1. If intending to update or reactivate a deactivated planning unit, choose “Inactive” from the planning unit Status dropdown - -3. Double-click on the cell (parameter) that needs updating - -4. Click “Submit” to save the changes - -**Add planning units to a program:** - -1. Ensure that you are working in ‘online’ mode. Select “Program Management” and then “Update Planning Units”. - -2. Select the program to display the planning units currently managed - -3. Click on the blue “Add Row” button on the bottom right of the screen and a new row will appear at the top of the table. - 1. Alternatively, right-click on any row in the table and select “Insert new row before” or “Insert new row after”. - -4. Begin by typing the first three letters of the desired planning unit to be added - -5. Complete all the cells (parameters) in that row - -6. Click “Submit” to save the changes - -> **Note:** If a required planning unit is not available in the dropdown, and thus on the QAT catalog, please raise a ticket through the QAT Helpdesk so that it can be created for the entire realm. See more on ticketing in section [QAT Helpdesk and Tickets](02-getting-started.md#qat-helpdesk-and-tickets). - -### Program/Procurement Agent-specific Information - -QAT users can manage specific details (freight costs, lead times, unit costs) for procurement agents and planning units within a supply plan. Program procurement agent-specific prices can be set for each planning unit in their programs, in addition to the program’s default (catalog) prices or realm-level procurement agent catalog prices. For example, a user may want to enter the UNDP price for malaria rapid diagnostic tests (mRDT) in the program FASPonia-Malaria, if UNDP’s catalog is not available at the realm level. Users also have the ability to designate freight percentages, lead times (including local lead times), and unit prices for specific planning units, procurement agents, or a combination of the two. - -**Features and Rules:** - -- **Program + Procurement Agent Combination:** If creating a program and procurement agent combination, the price column will become non-editable if the planning unit is set to ‘All’ since the price already exists in a different screen. - -- **Freight Costs, Lead Times, and Unit Prices:** At least one of these columns must have a numeric value when adding or editing rows. - -- **Mandatory Fields:** Only the first three columns (Program, Planning Unit, and Procurement Agent) are required to add a row. - -- **Constraints:** - - Only one row is allowed per program/planning unit/procurement agent combination. - - - If a procurement agent row includes 'All' planning units, the unit price column will be non-editable. - -**Usage in Supply Planning Module:** - -These program/procurement agent/planning unit-specific details will impact the supply planning module as follows: - -- **Freight Percentages:** Prioritized by program/procurement agent/planning unit settings and then program settings. - -- **Lead Times:** Prioritized by program/procurement agent/planning unit settings, then program settings, and finally realm-level procurement agent settings. - -- **Unit Prices:** Prioritized by program/procurement agent/planning unit settings, then realm-level procurement agent settings, and finally program settings. - -**Steps to Add or Edit Program/Procurement Agent-specific info** - -1. Select “Program Management” and then “Update Planning Units”. - -2. Select the program to display the planning units currently managed. - -3. Right-click on the row of the planning unit to add the procurement agent price for and click on “Add Program/Procurement Agent Prices” to show a new screen. - -![P1341#yIS1](/img/media/image116.png) - -Figure 70. Accessing the Program/Procurement Agent Prices screen - -4. OR select “Program/Procurement Agent Info” from -the lefthand menu to go directly to the screen. - -5. Select the program(s) and planning unit(s) to enter information for. - -6. Fill in the required fields and any additional fields. A few reminders from above: - 1. If creating a program and procurement agent combination, the price column will become non-editable if the planning unit is set to ‘All’ since the price already exists in a different screen. - - 2. At least one of these columns must have a numeric value when adding or editing rows. - - 3. Only the first three columns (Program, Planning Unit, and Procurement Agent) are required to add a row. - - 4. Only one row is allowed per program/planning unit/procurement agent combination. - -![](/img/media/image117.png) - -Figure 71. Adding Program/Procurement Agent Info for a planning unit - -7. Click “Submit” to save the changes. - -8. Click on Master Data Sync after making changes (applies to any item under Program Management). - -### Alternate Reporting Units - -An alternate reporting unit (ARU) is the product and unit that the country’s data (consumption, inventory & adjustments) is reported in and it could have the same description as the planning unit, forecasting unit, procurement unit, or in an altogether different packaging description. The ARU is defined within a particular country and requires entering a conversion factor from the ARU to the planning unit it is associated with (could be 1). Of all the product masters, the ARU is the only one program admins manage, because they are country specific. **Application, Realm, and Program Admins** can add/edit ARU for a country and program. Alternate reporting units are useful when: - -1. > Data sources report data in different units (e.g. pieces vs packs) - -2. > There’s another common name in country (e.g. brand name) - -**To see the list of all alternate reporting units in one country:** - -1. Select “Program Management” and then “Alternate Reporting Unit”. - -2. Select the program from the dropdown. - -**To add alternate reporting units to a country:** - -1. Select “Program Management” and then “Alternate Reporting Unit”. - -2. Select the program from the dropdown. - -3. Click on the “Add Row” button at the bottom right corner of the screen, or right-click on any row to add another. - -4. Enter the details in the newly created row and click on “Submit”. - 1. Note: the conversion factor can be ‘divide’ or ‘multiply’. - -![](/img/media/image118.png) - -Figure 72: ARUs - -\*Note that for each planning unit added to a program, QAT will automatically create an Alternate Reporting Unit with a 1:1 conversion factor. QAT will use the Planning Unit description as the Alternate Reporting Unit description. - -### Default Lead Times - -QAT uses six shipment statuses to track the progression of a shipment from planning to product receipt. Each of those steps in the order lifecycle has an associated lead time that is used to estimate when the next action should happen at each step. Lead times are expressed in months and can be partial months or even zero. The priority order for lead times settings is as follows: **Program/Procurement Agent Info** settings take the highest priority, followed by **Program-level** settings, and then R**ealm-level** settings. - -Figure 73: QAT shipment statuses - -There is different lead time logic depending on whether procurement is tagged as international or local. - -- **For international procurement:** - - **Program Admins** manage lead times that are program/country-specific (e.g., planning time, shipment times, custom clearance times, quarantine periods, etc.) - - - **Realm Admins** manage lead times specific to each procurement agent (more on this in the table below). - - - **Can also set specific lead time configurations for programs and/or procurement agents on a per-planning unit (PU) basis.** - -- **For local procurement:** - - The entire lead time (‘planned to received’) is determined by what's entered at the program level, per planning unit. All steps in local procurement are typically shorter than those in international procurement. - -| | | | -| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| **Lead time (from – to)** | **Definition** | **Configuration** | -| Planned to submitted | Number of months from identifying procurement need to placing an order with a procurement agent | Always set at the program level by Program Admins | -| Submitted to approved | Number of months between order placement and approval of order. This lead time can be defined for each procurement agent. | Default set at the program level by Program Admins. However, overwritten by realm-level procurement agent setting, if procurement agent is assigned to a shipment. | -| Approved to shipped | Number of months between order approval and dispatch from the procurement agent/supplier. This lead time can be defined for each procurement agent. | Default set at the program level by Program Admins. However, overwritten by realm-level procurement agent setting, if procurement agent is assigned to a shipment. | -| Shipped to arrived by air | Transit time via air between order dispatch until arrival at port of entry -in number of months. | Always set at the program level by Program Admins | -| Shipped to arrived by sea | Transit time via ocean between order dispatch via air until arrival at port of entry -in number of months. | Always set at the program level by Program Admins | -| Shipped to arrived by road | Transit time via road between order dispatch via road until arrival at requested point of delivery –in number of months | Always set at the program level by Program Admins | -| Arrived to received | Number of months from arrival at port of entry until reception into the warehouse. | Always set at the program level by Program Admins | - -Table 8: Lead times by shipment stage - definitions - -**Priority Order for Lead Time Settings** - -The priority order for lead time configurations is as follows: - -1. **Program/Procurement Agent Info:** These settings take the highest priority. If lead times are defined at this level, they will override other settings. These can be updated in the ‘Program/Procurement Agent Info’ screen. - -2. **Program-level:** If no lead time is defined at the program/procurement agent level, the program level defaults will be used. These can be updated in the ‘Update Program Info’ and ‘Update Planning Units’ screens. - -3. **Realm-level:** Realm-level lead times will apply if no specific lead time is set at the program level. - -**Enter/update the default lead times at the program level:** - -1. > Go to “Program Management” and then click on “Update Program Info” (see [Updating Program Information](#program-information)). - -2. > Scroll down to the second half of the page where all the lead time fields are. - -3. > Enter the default program lead times per step. - -4. > Click “Update” to save the changes. - -_Refer to [Program/Procurement Agent Info](#programprocurement-agent-specific-information) for instructions on how to add/edit settings at a program/procurement agent level._ - -**Enter/update the default local procurement agent lead times:** - -1. > Go to “Program Management” and then click on “Update Planning Units” (see [Updating Planning Units](#planning-units)) - -2. > Select the program from the dropdown on the top left. - -3. > Enter the default program lead time for local procurement. - -4. > Click “Submit” to save the changes. - -![P1428#yIS1](/img/media/image119.png) - -Figure 74: Entering local procurement agent lead times - -### ![](/img/media/image120.png)Budgets - -A budget represents an amount (estimated or actual) of capital for a set period that is to be spent on buying commodities for the program. - -Go to “Program Management” and then “Budget” to view a list of all budgets for your program(s). - -A budget can be tagged to one program or multiple programs. For example, if FSP-Lab-A has budget x, FSP-Lab-B can also link its program to budget x. If a program is delinked from a budget, the user will be forced to un-tag all shipments from that budget before uploading the version to the server. Any program admin that has access to a program can edit a budget that is associated with the program; however, he/she will only be able to add/remove programs that they have access to. - -To add or remove programs from a budget, click into the budget and then select or de-select from the first dropdown. - -![P1438#yIS1](/img/media/image121.png) - -Figure 75: Multiple Program ® - -If a budget is highlighted in red, it indicates that the budget has either passed the ‘End Date’ and/or the ‘Used Amount’ has exceeded the ‘Budget Amount’. - -**Add a Budget** - -1. In the “Budget” screen, go to the top right corner and click on the blue “+” icon. ![P1444L58#yIS1](/img/media/image122.png) - -2. A new screen titled “Add Budget” will appear. - -3. Enter the required details. - -4. Click the “Submit” button. - 1. **\*Note:** A Program cannot have multiple budgets with the same Funding Source and Budget Display Name. An error message will pop up if this is the case.\* - -**Update a Budget** - -1. Go to the Budget screen. - -2. Left click on the budget that you want to update. - -3. A new screen will appear titled “Update Budget - -4. Update the details of the selected budget as appropriate. - -5. Click “Submit” to save the changes. - -![P1456#yIS1](/img/media/image123.png) - -Figure 76: Budget Screen - -![P1458#yIS1](/img/media/image124.png) - -Figure 77: Update Budget - -## **Transactional Supply Plan Data** - -There are 3 main data requirements when creating or updating a supply plan: consumption, inventory, and shipments. The section below will define each of the data elements and how to add/update those elements in QAT. - -1. > **Consumption**: Stock dispensed by the program to clients. - 1. > **Actual Consumption**: The reported quantity of a product dispensed to clients in a given time period for a specific program at a specific supply chain level or combination of levels. - - 2. > **Forecasted Consumption**: The quantity predicted to be consumed by clients in a given time period which has been agreed upon by the program. - -2. > **Inventory**: The quantity on hand of usable product at a specific supply chain level or combination of levels, on a specific date, for a specific product. - 1. > **Stock** **count**: A check of how much stock a program has at a particular time in a specific supply chain level or combination of levels. - - 2. > **Stock adjustments**: Positive or negative modifications to usable inventory quantities for a specific date, categorized by reason for the adjustment, if possible (e.g. damage, expiry, quarantine, transfer to another implementing partner, etc.). Rebalancing transfers between locations in the same supply chain are excluded. - -3. > **Shipments**: The quantity of funded or planned quantities that will ship in current or future month or has shipped in a previous month or that has been received. Expressed in individual shipments, with a shipment number, and expected receipt date. - -### Consumption Data - -**Add Consumption Data:** - -1. From the menu sidebar, go to “Supply Plan Data” and click “Consumption Data”. - -2. Once the “Consumption Data” screen appears, select the desired filters using the drop-down menus at the top. - -3. The screen will display all current data for the selected period, planning unit(s), and other filters selected in step 2. - -4. To add a new consumption record, right click on any cell and select “Add new consumption” OR select the blue “+ Add row” at the bottom. JAJALC - -5. Enter the required information and click “Submit”. - 1. Any cell that is greyed out (e.g. Quantity (PU) indicates that it is a QAT generated cell and cannot be manually entered/edited. - 1. Reminder that [Alternate Reporting Unit](#alternate-reporting-units) (ARU) is the product and the unit that the country’s data is reported in. This could be the same as the planning unit or may be different. QAT users can define an alternate reporting unit and a conversion factor (multiply or divide) to the planning unit. - - 2. Any cell that is highlighted yellow indicates that it is a required field and has not yet been entered by the user. - -![](/img/media/image125.png) - -Figure 78: Add Consumption Data - -**Update consumption data:** - -1. From the menu sidebar, go to “Supply Plan Data” and click “Consumption Data”. - -2. Once the “Consumption Data” screen appears, select the desired filters using the drop-down menus at the top. - -3. The screen will display all current data for the report period, planning unit(s) and other filters selected in step 2. - -4. To update existing consumption data, the user must double-click on the cell(s). A user can update as many cells for as many rows as they need to before saving as long as it is for the same dropdown filters selected in step 2. - 1. **Note:** Users may not edit forecasted consumption more than nine (9) months in the past and may not edit actual consumption more than nine (9) months in the past. The non-editable data is identified by greyed out rows. - -5. Once a consumption record has been saved in QAT, it cannot be deleted. Therefore, if a user wants to remove that record from the supply plan, he/she must de-activate it by checking the blue check box in the far-right column or it can be repurposed for a different month’s data. - -6. Once the update(s) have been made, click “Submit”. - -**Add/update batch details:** - -Adding batch information to consumption records can only be applied to actual consumption. - -1. Right click on the “Actual Consumption” row and click “Show Batch Information”. - -2. A pop-up screen of the batch details for that actual consumption record will appear. - -3. The user can edit the existing batch number and/or quantity by double clicking on the cell. - -4. The user can also add a new batch(es) by right-clicking and selecting “Add New Batch” or by clicking on the “+Add Row” button”. - -5. The total quantity of the batches must equal the quantity of that actual consumption record. - 1. If the batch quantity/batch quantities are less than the actual consumption quantity, QAT will create a batch, using FEFO to calculate the difference. - - 2. If the batch quantity/batch quantities are greater than the actual consumption quantity, QAT will have a validation error and not let the user submit. - -6. Click “Submit”. - -![P1507#yIS1](/img/media/image126.png) - -Figure 79: Batch Details - -### Inventory Data - -**Add Inventory/Adjustment Data:** - -1. From the menu sidebar, go to “Supply Plan Data” and click “Inventory Data”. - -2. Once the “Inventory Data” screen appears, select the desired filters using the drop-down menus at the top. - 1. If the user is entering inventory data, select “Inventory” in the Inventory Type drop-down. If the user is entering adjustment data, select “Adjustment”. - -3. The screen will display all current data for the selected period, planning unit(s) and other filters selected in step 2. - -4. To add a new inventory/adjustment record, right click on any cell and select “Add New Inventory Count”/ “Add new adjustments” OR select the blue - “+ Add row” at the bottom. - -5. Enter the required information. - 1. Any cell that is greyed out (e.g., Conversion Factor) indicates that it is a QAT generated cell and cannot be manually entered/edited. - - 2. Any cell that is highlighted yellow indicates that it is a required field and has not yet been entered by the user. - - 3. If entering an adjustment, a note in the “Notes” field is required. Notes for inventory records are optional. - -6. Click “Submit”. - -![P1523#yIS1](/img/media/image127.png) - -Figure 80: Add Inventory - -**Update Inventory/Adjustment Data:** - -1. From the menu sidebar, go to “Supply Plan Data” and click “Inventory Data”. - -2. Once the “Inventory Data” screen appears, select the desired filters using the drop-down menus at the top. - 1. If the user is updating inventory data, select “Inventory” in the Inventory Type drop-down. If the user is updating adjustment data, select “Adjustment”. - -3. The screen will display all current data for the report period, planning unit(s) and other filters selected in step 2. - -4. To update existing inventory/adjustment data, the user must double click on the cell(s). A user can update as many cells for as many rows as they need to before saving as long as it is for the same dropdown filters selected in step 2. A user also cannot update adjustment and inventory data at the same time without first saving. - 1. **Note:** Users may not edit adjustment or inventory records more than nine (9) months in the past. The non-editable data is identified by greyed out rows. - - - -7. Once an inventory record has been saved in QAT, it cannot be deleted. Therefore, if a user wants to remove that record from the supply plan, he/she must de-activate it by checking the blue check box in the far-right column or it can be repurposed for a different month’s data. - - - -5. Once the update(s) have been made, click “Submit”. - -**Add/Update Batch Details – Adjustments** - -(for more information on QAT batch calculations, please see [Annex 2: Business Rules](11-annex-2-business-rules.md#annex-2-business-rules) or Section 5.E). - -1. Right click on the Adjustment row and click “Show Batch Information”. - -2. A pop-up screen of the batch details for that record will appear - -3. The user can edit the existing batch number and/or quantity by double clicking on the cell. - -4. The user can also add a new batch(es) by right-clicking and selecting “Add New Batch” or by clicking on the “+Add Row” button” to select - -5. The total quantity of the batches must equal the quantity of that adjustment record. - 1. If the batch quantity/batch quantities are less than the adjustment quantity, QAT will create a batch, using Best Case Scenario logic to calculate the difference - - 2. If the batch quantity/batch quantities are greater than the adjustment quantity, QAT will have a validation error and not let the user submit. - - 3. _Note: there is no user override for auto-adjustments, only manual adjustments._ - -6. Click “Submit” - -![](/img/media/image128.png) - -![](/img/media/image129.png) - -Figure 81: Batch Details - -**Add/Update Batch Details – Inventory** - -1. Right click on the Inventory row and click “Show Batch Information”. - -2. A pop-up screen of the batch details for that record will appear in the supply planning screen. See Section 5.E for details on how to update. - -### Shipment Data - -**Add Shipment Data:** - -1. From the menu sidebar, go to “Supply Plan Data” and click “Shipment Data”. - -2. Once the “Shipment Data” screen appears, select the desired filters using the drop-down menus at the top. - -3. The screen will display all current data for the report period, planning unit(s) and other filters selected in step 2. - -4. To add a new shipment record, right click on any cell and select “Add new shipment” OR select the blue “+ Add row” at the bottom. - -5. Enter the required information. - 1. Any cell that is greyed out (e.g. Planning Unit Cost) indicates that it is a QAT generated cell and cannot be manually entered/edited. - - 2. Any cell that is highlighted yellow indicates that it is a required field and has not yet been entered by the user. - - 3. Certain cells will not be available to enter data into until other cells have been filled in. For example, “Budget” cannot be selected until the user has selected a “Funding Source”. - - 4. “QAT Shipment ID” will display as blank or ‘0’ until the program is uploaded. - - 5. Shipments cannot be marked as ‘Received’ if the Receive Date is in the future. - - 6. In the shipment data screen, the user may select the desired currency from a drop-down list by clicking in the appropriate cell in the currency column. Based on the currency selected, the user will get the catalog price. - 1. That price can be changed during data entry/updating. - - 2. Freight cost is based on shipment mode and procurement agent but can also be modified manually. - - 7. If a shipment row is in red text, this means that the shipment is identified as an “Emergency Shipment”. QAT will automatically mark the shipment as an emergency shipment if the receive date falls inside the predefined lead time, meaning the shipment will most likely need to be expedited. _Note: QAT will only auto-flag the emergency shipment when the shipment is first created, but QAT will stop auto-flagging after first time the shipment row is submitted._ - - 8. If a shipment is highlighted in grey, this means that the shipment is not included in the ending balance of the supply plan. Shipments can be excluded by either changing the status of the shipment to “Cancelled” OR by de-activating the shipment using the blue check box on the far left. - -6. Click “Submit”. - -**Update Shipment Data:** - -1. From the menu sidebar, go to “Supply Plan Data” and click “Shipment Data”. - -2. Once the “Shipment Data” screen appears, select the desired filters using the drop-down menus at the top. - -3. The screen will display all current data for the report period, planning unit(s) and other filters selected in step 2. - -4. To update existing shipment data, the user must double click on the cell(s). A user can update as many cells for as many rows as they need to before saving as long as it is for the same dropdown filters selected in step 2 (i.e. you cannot edit shipments for a product and then edit shipments for a different product without first saving). - -5. When any of the following elements are changed (quantity, ARU, shipment mode, procurement agent, and planning unit cost), the behavior of the freight cost field will depend on the status of the “Auto-calculated Freight Cost” checkbox: - 1. **Checked:** - 1. The freight cost will be automatically recalculated based on the program/planning unit settings. - - 2. This calculation uses the formula: Planning Unit cost \* Freight %. - - 2. **Unchecked:** - 1. The freight cost cell with have a red triangle in the right corner appear recommending the user to update the freight cost the first time the checkbox is unchecked. - - 2. To facilitate manual entry, the user can input a formula directly into the cell by typing an ‘=’ first. The formula will disappear upon saving, but the resulting value will remain. The user can also input a number directly. - -6. Unlike consumption data, a user can delete a shipment record even after it has been saved to the program, although the shipment must be in the ‘Planned’ status. To do so, right-click on the desired shipment and select ‘Delete Row’. - -7. Once the update(s) have been made, click “Submit”. - -**Add/Update Batch Details** - -Adding batch information to shipment records can be applied to shipments in any status other than “suggested shipments”. Once a shipment is created, QAT will auto-generate a batch. The user has the ability to edit that batch and/or add new batches to that shipment. - -1. Right click on the shipment row and click “Show Batch Information”. - -2. A pop-up screen of the batch details for that shipment will appear. - -3. The user can edit the existing batch number, expiry date and quantity by double clicking on the cell. - -4. The user can also add a new batch(es) by right-clicking and selecting “Add New Batch” or by clicking on the “+Add Row” button”. - -5. The total quantity of the batches must equal the quantity of that shipment. At the bottom of the pop-up screen will display the total quantity for the shipment as well as the total quantity assigned to the batch(es). This is to let the user know if the batch quantity is over, under, or the same as the shipment quantity. - -6. Click “Save Batch Information”. - -7. **Note:** When a shipment status is changed to “Received,” the batch details will automatically pop-up for users to edit or confirm the current batch information. - -The column to the far right labeled “Auto Generated” will let the user know if that batch was auto generated by QAT or manually entered by the user. If any of the 3 fields of the batch (batch number, expiry date, quantity) are changed, the checkbox for the auto generated field will become unchecked. If the expiry date and/or quantity are changed but not the batch number, the batch number automatically changes to swap out ‘QAT’ for ‘MAN’ and the cell gets highlighted with a red triangle indicating to the user that it should be changed. If the user doesn’t know the real batch number, QAT will allow the batch to still be saved without changing the number. - -![P1594#yIS1](/img/media/image130.png) - -Figure 82: Shipment Batch Details - -**Strategic Order Calculator:** - -For specific planning unit and procurement agent combinations, a **strategic order calculator** may appear for the user when entering the quantity of a shipment. The purpose of the calculator is to advise users on the appropriate order quantity for a shipment based on one or more of the following elements: a) Minimum Order Quantity (MOQ); b) Container load; c) Euro 1 pallet; d) Euro 2 Pallet. The calculator will help users plan shipments to maximize efficiency with delivery logistics (e.g. utilizing a full container instead of 20% of the container). Strategic products are defined at the realm level by an application or realm admin. For more information on how to define strategic products, see the [section on adding planning units for procurement agents](#programprocurement-agent-specific-information). - -1. To view the Quantity Calculator for a strategic product, double click on the cell under the “Order Quantity” column and the “Quantity Calculator” screen will appear. _Note: If the product is a non-strategic product, the user can directly modify the order quantity in the cell after double-clicking and there will not be a pop-up._ - -2. The original quantity of the shipment will appear in the “Manual Order Quantity” cell. - -3. If you don’t want to use the strategic calculator and want to use the original “Manual Order Quantity”, select “None” in the drop-down for “Packaging Based On” and click “Save Shipment Quantity”. - -4. If you want to use the strategic calculator: - 1. Select how you wish to use the calculator by choosing an option from the “Packaging Based On” drop-down as well as the “Rounding Option” drop-down. - - 2. Depending on your selections in step 4a, the quantity in “Final Order Quantity” cell will show you QAT’s calculated shipment quantity. The bottom table summarizes the key information around the different packaging modes. - - 3. After confirming you are happy with the Final Order Quantity, click “Save Shipment Quantity”. - -![P1608#yIS1](/img/media/image131.png) - -Figure 83: Strategic Order Calculator - -**View Shipment Dates:** - -Estimated for each status can be seen, and actual dates can be manually entered, in the Shipment screen. This will allow the user to identify if the shipment is on schedule or behind/ahead based on the lead times. The user can also use this screen to compare the actual dates with the estimated dates of that shipment and use that information to update lead times that may not be accurate. - -1. From the menu sidebar, go to “Supply Plan Data” and click “Shipment Data”. - -2. Once the “Shipment Data” screen appears, select the desired filters using the drop-down menus at the top. - -3. The screen will display all current data for the report period, planning unit and other filters selected in step 2. - -4. Right-click on the shipment you wish to view the dates for and select “Show shipment dates”. A pop-up screen labeled “Shipment Dates” will appear. - -5. The row labeled “Estimated” of the “Shipment Dates” screen will show a date for each status of the shipment based on the lead times entered for the program as well as the estimated receive date. Only the estimated receive date can be edited by the user. - 1. If a user changes the estimated receive date, the other estimated dates will also change based on the program’s lead times. - -6. The row labeled “Actual” will allow the user to enter the actual date that each status occurred for that shipment. If a cell is greyed out in this row, it means that the shipment has not yet reached that status and a date cannot be entered. - -7. If the user makes a change to the estimated receive date or one of the actual dates, click “Save shipment dates”. - -![P1623#yIS1](/img/media/image132.png) - -Figure 84: Show Shipment Dates - -### ERP Shipment Linking - -The ERP shipment linking functionality allows supply planners to link select shipments (currently GHSC-PSM) with the corresponding procurement agent’s ERP system (currently ARTMIS). Once a shipment is linked in the supply plan, all the order details (status, receive date, costs, quantity, batches, etc.) will match what is in the ERP and the user will no longer need to manually update the shipment. If the packaging of the product in the ERP does not match the packaging of the planning unit in QAT, the user will have the ability to correct this through a conversion factor attribute in QAT. The user will be able to de-link the shipment if they want to manually track instead. The shipment details for these linked shipments will appear throughout QAT (Shipment Data Entry, Supply Planning, Reports, etc.). The user will be alerted if there are any key changes made in the ERP such as an order being cancelled or a product SKU changing. Users will only be able to tag shipments that are past funding source approval in ERP. - -When managing ERP shipment linking, users will select either the ‘Link ERP Shipments’ or ‘ERP Shipment Notifications’ menu options. Within the ‘Link ERP Shipments’ screen there are 3 sub-screens: - -1. > **Not Linked (QAT) –** Use this screen to link QAT shipments with ERP orders for the first time. Users will see a list of QAT shipments, and when a user clicks on a single QAT shipment, they can choose which ERP orders that QAT shipment should be linked with. - -2. > **Linked –** Users will see a list of currently linked shipments and they can update the conversion factor or notes of already linked shipments, add ERP lines to already linked QAT shipments, or de-link ERP lines from QAT shipment. - -3. > **Not Linked (ERP) –** Use this screen to link ERP orders to QAT for the first time. Users will see a list of ERP shipments, and when a user clicks on a single ERP shipment, they can then choose which QAT shipment that ERP shipment should be linked with. For any orders that are in the ERP that are not already in QAT, you can create a new QAT shipment in this screen. - -![P1634#yIS1](/img/media/image133.png) - -Figure 85: ERP Linking Screens - -**Rules for ERP Shipment Linking** - -Below are the rules for ERP shipment linking. The details button in the top right corner of the ‘Link ERP Shipments’ screen will summarize these rules. - -1. ERP linking is only editable for downloaded local versions. The ERP linking screens will show server versions, but that data is read only. To save the linking changes, the user must upload that version. - -2. Currently, QAT shipments can only be linked if the procurement agent is GHSC-PSM. - -3. QAT shipments cannot be linked if they are in the status of planned, cancelled or suggested. - -4. Inactive QAT shipments cannot be linked. - -5. QAT shipments in the ‘received’ status can only be linked if the receive date falls within the last 6 months. - -6. ERP orders can only be linked if they are past the funding source approval status (e.g. USAID approved). - -7. ERP orders in the ‘delivered’ status can only be linked if the delivery date falls within the last 6 months. - -8. ERP receive date uses the logic: 1) Actual Delivery Date 2) Estimated Delivery Date 3) Agreed Delivery Date 4) Requested Delivery Date. Therefore, if \#1 is not available QAT will use \#2. If \#2 is not available QAT will use \#3 and if \#3 is not available QAT will use \#4. - -**Not Linked (QAT)** - -This screen is used by supply planners to link QAT shipments with ERP orders. Below are the steps on how to link a QAT shipment with one or multiple ERP orders: - -1. Select the radio button at the top labeled ‘Not Linked (QAT)’. - -2. Select the program and planning unit(s) you want to choose the QAT shipment from. Once selected, a list of QAT shipments will appear. ERP linking can only be done on local versions, however, linked shipments can be viewed on server versions. - -3. Left click on a single QAT shipment. A pop-up window will appear called ‘Search ERP-linked shipments’. This window will allow the user to choose which ERP orders that QAT shipment should be linked with. - 1. The top half of the window will show the QAT shipment details. This information is non-editable. - - 2. The middle half of the window will show 2 dropdowns that will allow the user to filter the list of ERP orders to link the QAT shipment with. - - 3. The bottom half of the window will list all ERP shipments based on the dropdowns in the middle section. This is where the user will link 1 or more orders as well as provide the Alternate Reporting Unit (ARU) and note (optional). The ARU will automatically populate the conversion factor. - 1. **To change/add a conversion factor, the user can do so in the ‘Alternate Reporting Unit’ screen.** - -4. In the middle section, the user can filter the ERP shipments by selecting the ERP planning unit, the RO/Order No. or both. QAT will pre-fill the RO/Order No. dropdown once this window appears by selecting the Proc Agent Order No. from the QAT shipment. If this field is blank, QAT will display a message underneath both dropdowns in red that displays “Fill either ERP planning unit or RO/Order No. to populate data”. - -5. To link an ERP shipment, the user will check the box in the far-left column that says ‘Link?’. Once the user does this, they will be required to enter the ARU. - 1. If a user wants to link multiple ERP lines to the same QAT shipment, he/she should check the box for multiple rows. - - 2. If a user wants to link multiple QAT shipments to 1 or multiple ERP lines, he/she should check the box at the top that says ‘Show all shipments for \_\_\_\_\_\_’ and then select each of the QAT shipments to link. - -6. The conversion factor is useful when the QAT planning unit and ERP product are different (pack of 10 chocolate bars vs. pack of 100 chocolate bars). The conversion factor is used to calculate what the converted QAT shipment quantity is. The converted QAT shipment quantity is the order quantity that will be used in your supply plan for the linked shipment. - -![P1665#yIS1](/img/media/image134.png) - -7. If there is a note in the QAT shipment, this will carry over to each of the ERP orders when you link. In this pop-up window, the user can edit or delete that note. - -8. The bottom of the window will show what the original QAT quantity order is and what the new converted QAT quantity will be. - -![P1668#yIS1](/img/media/image135.png) - -Figure 86: ERP Converted Quantity - -9. Lastly, click ‘Link Shipment’. - -**Not Linked (ERP)** - -This screen is used by supply planners to link ERP orders to QAT for the first time. For any orders that are in the ERP that are not already in QAT, you can create a new QAT shipment in this screen. Below are the steps on how to link an ERP order with a QAT shipment: - -1. Select the radio button at the top labeled ‘Not Linked (ERP)’. - -2. Select the country AND planning unit category or planning unit you want to choose the ERP order from. Once selected, a list of ERP orders will appear. - 1. **Note: This list is showing ERP data whereas the Not Linked (QAT) screen shows QAT data.** - -3. Left click on a single ERP order. A pop-up window will appear called ‘Search ERP-linked shipments’. This window will allow the user to link 1 or more ERP orders with a pre-existing or new QAT shipment. - 1. The top half of the window will show the QAT shipment details. This area will allow the user to either select a pre-existing QAT shipment or create a new one. Steps 4 and 5 will detail how to do so. - - 2. The middle half of the window will show 2 dropdowns that will allow the use to filter the list of ERP orders to link the QAT shipment with. - - 3. The bottom half of the window will list all ERP shipments based on the dropdowns in the middle section. This is where the user will link 1 or more orders as well as provide the conversion factor and note. This section is pre-populated based on the ERP order number that was selected on the previous screen. - -4. To select an existing QAT shipment, click on the ‘Select Existing Shipment’ button in the top section. - 1. Select the program that you want to search the QAT shipment(s) from. The dropdown will be filtered to show only the country that was selected in step 2. - - 2. Next, either search the list of QAT shipments by planning unit (default) or by QAT shipment ID. If you want to search by QAT shipment ID, you will need to check the box that is labeled ‘Filter by QAT shipment id?’. To go back to searching by planning unit, you will uncheck the box. - - 3. Once you find the desired QAT shipment, select the button in the far-left column labeled ‘Select shipment id’. - -5. To create a new QAT shipment, click on the ‘Create New Shipment’ button in the top section. - 1. The user will need to fill in 4 dropdowns (Program, Planning Unit, Funding Source, Budget) to provide required information for creating the shipment. The rest of the shipment details will come from the ERP order that is selected in step 7. - 1. The program dropdown is filtered to show only the country that was selected in step 2. - - 2. The budget dropdown is filtered based on the selection in the funding source dropdown. - - 3. If there is no applicable budget, the user will need to leave the screen and add a budget in master data. If the user adds a budget, he/she must master data sync before seeing that option appear in this screen. - -6. In the middle section, QAT will pre-fill the RO/Order No. dropdown once this window appears based on the selected ERP order made in step 3. - -7. To link an ERP shipment, the user will check the box in the far-left column that says ‘Link?’. Once the user does this, they will be required to enter the ARU. - 1. If a user wants to link multiple ERP lines to the same QAT shipment, he/she should check the box for multiple rows. - - 2. If a user wants to link multiple QAT shipments to 1 or multiple ERP lines, he/she should check the box at the top that says ‘Show all shipments for \_\_\_\_\_\_’ and then select each of the QAT shipments to link. - -8. The conversion factor is useful when the QAT planning unit and ERP product are different (pack of 10 chocolate bars vs. pack of 100 chocolate bars). The conversion factor is used to calculate what the converted QAT shipment quantity is. The converted QAT shipment quantity is the order quantity that will be used in your supply plan for the linked shipment. - -![P1699#yIS1](/img/media/image134.png) - -9. The user can add a note to the shipment by editing the far-right column labeled ‘Notes’. - -10. The bottom of the window will show what the original QAT quantity order is and what the new converted QAT quantity will be. - -11. Lastly, click ‘Link Shipment’. - -![P1703#yIS1](/img/media/image136.png) - -Figure 87: Create New Shipment - -**Linked Screen** - -This screen is used by supply planners to view the list of currently linked ERP shipments and update the Alternate Report Unit (ARU) or notes, add ERP orders to already linked QAT shipments, or de-link ERP lines from the QAT shipment. - -1. Select the radio button at the top labeled ‘Linked’. - -2. Select the program and planning unit(s) you want to see the list of linked shipments for. Once selected, a list of shipments will appear. The information in these shipments is being pulled in from the ERP. - -3. To make any of the updates listed in step 2, left click on a single shipment. - 1. To edit ARU and/or notes, double-click on the cell and type or select from dropdown. - - 2. To de-link an ERP order, uncheck the box in the ‘Link?’ column. - - 3. To add an ERP order, check the box for that order under ‘Link?’ column. The user can clear the search dropdowns in the middle section to look up a differe planning unit or order number and the originally linked orders will remain linked. - -4. Users will have the ability to also view order history details from the ERP. To do so, from the original ‘Linked’ screen, right-click on a single shipment and click ‘View ERP Order History’. A pop-up window will appear labeled ‘ERP Order History’. This screen will show any details that have changed over time in the ERP order. Each row indicates that one or more of the columns has changed. The furthest column on the right labeled ‘Data Received On’ is when the record was received by QAT. - 1. To view batch details, click on the![](/img/media/image137.png) icon. - - 2. **Note:** Certain fields from the ERP are not captured on this screen so there may be some instances where 1 or more rows have the same details. This means that a column in the backend was changed. - -> **Once you have linked QAT shipments with ERP orders, the data will reflect in your supply plan without having to master data sync.** The newly linked ERP data will reflect in the local reports, supply planning screen as well as the shipment data entry screen. The user **does** need to upload a version to the server in order for other users to see these changes. -> -> To view the ERP-linked shipments in the shipment data entry screen, the user must select ‘ERP-linked shipments’ from the Shipment Type dropdown. The user can either display only this option or combine it with the manual shipments to show all shipments. The ERP-linked shipments will be greyed out to indicate that they are non-editable. - -![P1723#yIS1](/img/media/image138.png) - -Figure 88: View ERP Shipments in Data Entry - -In the supply planning screen, ERP-linked shipments will have a link icon in the top left of the cell. The user can click into a specific shipment to view the details but those cells will also be greyed out to indicate that they are non-editable. The user can still right click on the shipment details,however, to view the shipment dates and batch information. - -![P1727#yIS1](/img/media/image139.png) - -Figure 89: View ERP Shipments in Supply Plan - -**ERP Shipment Notifications** - -The purpose of the ‘ERP Shipment Notifications’ screen is to alert supply planners of any key changes made to ERP linked shipments, such as an order being cancelled or a product SKU changing. Supply planners will be encouraged to ‘address’ each of the notifications to confirm that they are aware of the change and the implications made on the supply plan. For product changes, the user will re-confirm the conversion factor, whether it changes or not. - -![](/img/media/image140.png) - -At the top of the screen, there is a icon. This icon will display a red number indicating how many non-addressed notifications are in the ERP shipment notifications screen. If there is no red number, that means there are none. - -To get to the ‘ERP Shipment Notifications’ screen, either click on the truck icon at the top of QAT or select ‘ERP Shipment Notifications’ under ‘Supply Plan Data’ in the left sidebar menu. - -To view the notifications, the user will need to select from the 3 dropdowns (Program, Planning Unit, Addressed). The user also has the option to select directly from the table above the dropdowns. When a user left clicks on a row in the table, the 3 dropdowns will atomically populate based on the program that user selected. The planning unit dropdown will populate to all planning units and the addressed dropdown will select ‘Not Addressed’. - -![P1739#yIS1](/img/media/image141.png) - -Figure 90: ERP Shipment Notifications Filtering - -To address a notification, the user must check the box in the ‘Addressed?’ column and then hit the ‘Submit’ button. If the user is addressing an ERP Product Change notification, he/she must first enter the conversion factor. The conversion factor field is not editable until the addressed box is checked. - -Just like in the ‘Linked’ screen, the user can view ERP order history. To do so, right-click on the notification row and click ‘View ERP Order History’. Refer to the Linked Screen section for more information. - -## Importing Data for Supply Planning - -### Supply Plan Data Excel Import Templates - -Consumption, Inventory and Shipment data can be entered through QAT’s data entry screens, through the Supply Planning screen or through Quantimed Import (forecasted consumption only). QAT also provides users with the ability to input this data directly from Microsoft Excel. This method of data entry is intended for bulk entries that have a lot of data. The steps below will show how to input data from Excel into QAT: - -1. From the menu sidebar, go to “Supply Plan Data” and click the type of data you want to enter (e.g. “Consumption Data”). ![P1748L76#yIS1](/img/media/image142.png) - -2. ![](/img/media/image143.png)Once on the data entry screen, go to the top right corner and click “Download Template”. - -3. A Microsoft Excel file will be downloaded directly to your computer’s ‘**Downloads’** folder. - -4. Proceed to your computer’s Downloads folder and open the Excel file. The name format should be **ConsumptionDataEntryTemplate.xlsx** with the first portion dependent on the type of data you are entering. - 1. _Each of the four data types (Inventory, Adjustment, Consumption and Shipment) have their own Excel template so it is important that you click on “Download Template” from the proper screen. For inventory and adjustment, make sure the drop-down menu has selected the type of data you want the template for._ - -5. Once in the Excel template, click “Enable Editing” at the top if it prompts you to. - -![P1755#yIS1](/img/media/image144.png) - -Figure 91: Enable Editing - -6. Enter data for all of the required fields. - 1. Any cell highlighted in grey (e.g. Conversion Factor) is non-editable and does not need to be filled in. - - 2. Certain fields (e.g. Data Source) will have drop down menus pre-populated from QAT. Therefore, it is important to download a new template if it has been a while since the last time the user used the template. - - 3. Certain fields have built in data validations (e.g. letters cannot be entered in cost cells). If the validation is not met, a pop-up error message will appear. - -![P1762#yIS1](/img/media/image145.png) - -Figure 92: Excel Template - -7. Once all the data is entered in the Excel template, re-open QAT window. - -8. Go to the Data Entry screen (Consumption, Inventory, Adjustment, Shipment). - -9. Click the blue “+Add Row” button at the bottom. - 1. **Note:** You only need to add 1 row in QAT regardless of how many rows there are in the Excel template. - -10. In the Excel template, select all data and press Ctrl + C on your keyboard to copy the data. - -11. Go to the added row in QAT, left click on the far most left cell in that row and press Ctrl + V on your keyboard to paste the data. - -12. QAT will automatically create new rows for the data being imported from Excel. - -13. Click “Submit”. - -### Quantimed Forecast Import - -![](/img/media/image146.png)Quantimed is a software designed to facilitate the process of determining the quantities of medicines and medical supplies required for a health program. The output of Quantimed is a health programs’ forecasted consumption data. That forecasted consumption data can be a key input into QAT user’s supply plans. QAT allows users to import Quantimed forecasts into QAT to include in their supply plan. - -**Step 1: Import Quantimed Data into QAT** - -1. Go to “Supply Plan Data” on the sidebar menu - -2. Selected “Quantimed Import” - -3. **Import Quantimed Data File** - 1. Choose the Quantimed .xml forecast file from your local computer system. - - 2. Select the QAT program that you want the Quantimed data to import into. - - 3. Click on “Import”. - -![P1783#yIS1](/img/media/image147.png) - -Figure 93: Quantimed File Import - -**Step 2: Map Planning Units** - -1. > To map a Quantimed product to a QAT planning unit, select the QAT planning unit using the drop-down menu. - -2. > If you do not want to import a specific Quantimed product, select the “Do Not Import” option for that row. - -3. > If there is not a QAT planning unit associated with the Quantimed product, the dropdown will show “Planning Unit Not Found”. You will either need to manually select a planning unit from the dropdown or go back to the program and add a planning unit for that Quantimed product before proceeding. You cannot click “Next” one or more of the cells says “Planning Unit Not Found”. - 1. > **Note**: to minimize instances where a planning unit is not found, it is recommended that Quantimed users select products from the GHSC-PSM product catalog .xml file. - -4. > Once very row has a planning unit selected or says “Do not import”, click “Next” at the bottom of the screen. - -![P1794#yIS1](/img/media/image148.png) - -Figure 94: Map Planning Units - -**Step 3: Region** - -1. > In this step select the region that you want to import the forecasted consumption data into. If there is only one region, you must select that region to proceed. - -2. > Then, input the percentage of that consumption data that you want to import into QAT. This percentage must range from 0-100% and will apply to all the planning units previously selected. - -3. > Click “Next”. - -**Step 4: Consumption Month** - -1. > Select the date range for the Quantimed data that you want to import into QAT. - 1. > The period you select is the period of data that you will be able to import and will apply to all planning units previously selected. - -2. > Click “Next”. - -![P1806#yIS1](/img/media/image149.png) - -Figure 95: Consumption Month Screen - -**Step 5: Import Data** - -1. > The final step is to confirm the data that will be imported from Quantimed into QAT based on what was entered in steps 1-4. - 1. > “Quantimed Forecasted Consumption” is the amount that is being pulled in from Quantimed for the associated product and month-year. - - 2. > “Converted Quantimed Forecasted Consumption” is the amount that will be pulled into QAT for the associated product and month-year after applying the import percentage and conversion factor. - - 3. > “Current QAT Forecasted Consumption” is the forecasted consumption amount currently in QAT for that planning unit and month-year. Once you import the Quantimed data, this amount will be overwritten by the “Converted Quantimed Forecasted Consumption” amount. - -2. > This screen will show all the data that will be imported into QAT. If you do not want to import certain records, click on the checkbox in the ‘Import?’ column on the far right. This will prevent QAT from importing the Quantimed data and will keep the current QAT forecasted consumption for that planning unit and month-year. - -3. > Click “Submit” to import the data. - -![P1816#yIS1](/img/media/image150.png) - -Figure 96: Confirm Data Import Screen - -### QAT Forecast Import - -**Purpose:** Enable users to import QAT-created forecasts into supply plan programs. Forecasts are only available for importing if 1) they are uploaded as a final version and 2) there is a forecast selected for each planning unit. - -**Using this screen**: - -**(Step 1)** - -- Select which forecast program to import from (only final forecasts are available) - -- Select which supply plan program to import to. Only local supply plan versions can be used. To download a program, go to the ‘Download/Delete Program’ screen under ‘Program Management’. - - Select the date range of forecast data to import, which must be within the forecast period. - -- In the table that appears, select and map planning units. - - For every Forecasting Planning Unit, QAT requires a corresponding Supply Plan Planning Unit and conversion factor. QAT automatically maps exact planning unit matches, but users can override both the planning unit mapping and conversion factor. - - - Not all forecast planning units need to be imported, however, all forecast planning units must have a selection in the mapping table. You could manually select “Do not import” for each Forecasting PUs you don’t want to import or you could click on the check box “Do not import all unmapped PUs” which will allow a bulk selection of Do not import for all unmapped PUs. - - - > If for a PU No forecast was selected, it will appear greyed with “static.importintoSP.forecastBlank” - - - If a planning unit does not appear in the dropdown, you will need to add this to the supply plan program in the ‘Update Planning Units’ screen. - -![P1833#yIS1](/img/media/image151.png) - -Figure 97: Forecast Import Screen - -**(Step 2)** - -For each Forecast region, input how much (%) of that region’s forecast you will import and which region the forecasted consumption will be imported into. Below are some use cases: - -- National forecast to national supply plan - -| **Forecast Region (s)** | **% of Forecast** | **Supply Plan Region** | -| ----------------------- | ----------------- | ---------------------- | -| National | 100 | National | - -- Multi-region forecast to multi-region supply plan - -| **Forecast Region (s)** | **% of Forecast** | **Supply Plan Region** | -| ----------------------- | ----------------- | ---------------------- | -| North | 100 | North | -| East | 100 | East | -| South | 100 | South | - -- Multi-region forecast to national supply plan – - -| **Forecast Region (s)** | **% of Forecast** | **Supply Plan Region** | -| ----------------------- | ----------------- | ---------------------- | -| North | 100 | National | -| East | 100 | National | -| South | 100 | National | - -- National forecast to multi-region supply plan – note that the import process needs to be repeated for each supply plan region. - -| **Forecast Region (s)** | **% of Forecast** | **Supply Plan Region** | -| ----------------------- | ----------------- | ---------------------- | -| National | 20 | North | - -| **Forecast Region (s)** | **% of Forecast** | **Supply Plan Region** | -| ----------------------- | ----------------- | ---------------------- | -| National | 45 | South | - -| **Forecast Region (s)** | **% of Forecast** | **Supply Plan Region** | -| ----------------------- | ----------------- | ---------------------- | -| National | 35 | East | - -**(Step 3)** - -QAT will list each forecast record to be imported (one row for each planning unit, region and month combination). - -- QAT calculates the Forecasted Consumption to be imported as follows: - - - - - - - - - - - - - -
- Forecasted Consumption (Forecast Module) - - x - - % of Forecast - - x - -

- Conversion Factor -

-

- (Forecast to Supply Plan) -

- 		- = - - Rounded* Converted Forecasted Consumption -
- -> For example: - -- A national forecast that will be split into two regions of 50% each - -- The Forecast Planning Unit is in packs of 3, and the Supply Plan Planning Unit is in packs of 1 (Conversion factor = 3) - -- The national forecast for Month N was 100 (packs of 3) - -- Forecast of 100 x 50% x 3 = 150.00 rounded (packs of 1) will be imported into each region for Month N - - - -- **\*Rounding Method:** Because QAT Supply Planning requires whole numbers without decimals, QAT converts forecasted consumption into whole numbers by rounding down and summing the “residuals” over time. Each month, QAT adds last month's residuals total and this month's forecast, before rounding down, and any residual not rounded down is added to a running residual total, called the Cumulative Total. In this way, quantities are not lost through the rounding process. - - > Formulas: - - **Cumulative Total for Month N** = (Residual for Month N - 1) + Converted Forecast for Month N - - - **Residual for Month N** = How much was lost in the rounding = (Cumulative Total for Month N) – (Rounded Converted Forecast for Month N) - - - **Rounded Converted Forecast for Month N** = Cumulative Total for Month N, rounded down to the nearest whole number - - - > For example, a national forecast is projected to consume 0.25 packs of the Forecast Planning Unit per month, for 12 months. The Forecast Planning Unit and the Supply Plan Planning Unit are the same (Conversion factor = 1) - - In January, the Converted Consumption is 0.25, and since it’s the first month, the 0.25 is also the January Cumulative Total. 0.25 is rounded down to a whole number is 0, and the rounded number of 0 is imported into the supply planning module. The January Residual from the rounding is 0.25 – 0 = 0.25. - - - In February, the Converted Consumption is 0.25, added to the January Residual of 0.25 makes the February Cumulative Total 0.25 + 0.25 = 0.5. Then, 0.5 is rounded down to a whole number of 0, which is imported into the supply planning module. The February Residual from the rounding is 0.5 – 0 = 0.5. - - - In March, the Converted Consumption is 0.25, added to the February Residual of 0.5 makes the March Cumulative Total 0.25 + 0.5 = 0.75. Then, 0.75 is rounded down to a whole number of 0, which is imported into the supply planning module. The March Residual from the rounding is 0.75 – 0 = 0.75. - - - In April, the Converted Consumption is 0.25, added to the March Residual of 0.75 makes the April Cumulative Total 0.25 + 0.75 = 1.00. Then, 1.00 is rounded down to a whole number of 1.00, which is imported into the supply planning module. The April Residual from the rounding is 1.00 – 1.00 = 0. - - - From May onwards, the cycle repeats itself. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
JanFebMarAprMayJunJulAugSepOctNovDec
-

Converted Forecast

-

- (After conversion factor is applied) -

- 		0.250.250.250.250.250.250.250.250.250.250.250.25
- Cumulative Total - - 0.25 - - 0.5 - - 0.75 - - 1 - - 0.25 - - 0.5 - - 0.75 - - 1 - - 0.25 - - 0.5 - - 0.75 - - 1 -
- Residual - - 0.25 - - 0.5 - - 0.75 - - 0 - - 0.25 - - 0.5 - - 0.75 - - 0 - - 0.25 - - 0.5 - - 0.75 - - 0 -
-

Rounded Converted Forecast

-

- (To be imported into Supply Planning Module) -

- 		000100010001
- -- If there is an existing forecasted consumption in the supply plan, the ‘Current Forecasted Consumption’ cell will be highlighted yellow. - -- If there is an existing forecasted consumption in the supply plan and the forecasted consumption data the user is trying to import is older than 4 months, the ‘Current Forecasted Consumption’ cell will be highlighted gray, and will NOT be imported. - -- Use the “Import?” column to de-select any forecasts that you do NOT want to import into the supply plan. If checked, the Converted Forecasted Consumption will override the Supply Plan forecast. If unchecked, the current Supply Plan forecast will remain. - -![P2015#yIS1](/img/media/image152.png) - -Figure 98:QAT Forecast Import Screen diff --git a/docs/user/05-getting-started.md b/docs/user/05-getting-started.md new file mode 100644 index 0000000..41439f4 --- /dev/null +++ b/docs/user/05-getting-started.md @@ -0,0 +1,464 @@ +--- +id: getting-started +title: "Getting Started" +sidebar_label: "Getting Started" +sidebar_position: 5 +--- + +# Getting Started + +## System Requirements + +The QAT is a web-based application accessible via laptops and desktops running **Windows, Linux/Ubuntu, or macOS**. + +- **Recommended Browser:** Google Chrome. +- **Supported Browsers:** Chromium, Microsoft Edge, Mozilla Firefox, and Safari. + +### Disk Space and Cache +We recommend having sufficient free space on your primary drive (e.g., C: drive) for browser cache data. Chrome and other browsers share a storage pool among all web apps, which can be up to 1/3 of available disk space. QAT can utilize up to 20% of this shared pool. For example, with 60 GB of free space, the shared pool is 20 GB, allowing QAT to store up to 4 GB of local data. + +## Data Hierarchy in QAT + +The QAT system is organized into three hierarchical levels: + +1. **Application Level:** The highest level, covering global master data that applies to all Realms and Programs. Restricted to Application Admins. +2. **Realm Level:** Covers master data specific to a Realm (e.g., Country, Technical Areas, Planning Units). Managed by Realm Admins. +3. **Program Level:** The third level, where users manage specific forecasting or supply planning data (e.g., consumption, inventory, shipments). + +For detailed administrative functions, see [Annex 1: Application & Realm Administrator Manual](13-annex-1-application-realm-administrator-manual.md#annex-1-application-realm-administrator-manual). + +> **Note:** A **Program** is a combination of a Country, Technical Area, Organization, and Region (e.g., *FASPonia–ARV-MOH-National*). + +## User Roles and Permissions + +Access to QAT is governed by roles and permissions defined at the Application or Realm level. A user can be assigned multiple roles, which may vary by program. + +- **Program Level:** Most users (managers and officers) interact at this level as **Program Admins** or **Program Users**. +- **Realm Level:** **Realm Admins** manage master data and have access to all programs within their realm. +- **Application Level:** **Application Admins** have exclusive access to global structures, roles, and system settings. + +For a full list of roles and business functions, refer to [Annex 4: Business Functions](16-annex-4-business-functions.md#annex-4-business-functions). + +## Logging In and PWA Installation + +### Initial Login (Online) +If you do not have a user profile, contact your Realm Administrator to create an account. Once created, you will receive an email to reset your password. + +1. Click the **Reset Password** link in the email (valid for 24 hours, single-use). +2. Create your new password and click **Submit**. +3. Log in using your email address and the new password. + +> **Password Requirements:** +> - Minimum 6 characters, starting with a letter. +> - Must include at least one uppercase letter, one number, and one special character. +> - Cannot be the same as your username or previous password. + +### Installing the QAT Progressive Web Application (PWA) +The PWA provides a standalone, app-like experience on your desktop and supports offline mode. It is compatible with **Google Chrome** and **Microsoft Edge**. + +#### Standard Installation +1. Navigate to the [Quantification Analytics website](https://www.quantificationanalytics.org/). +2. Click the **Install** icon (plus sign) in the browser's address bar. +3. Select **Install** in the confirmation pop-up. + +![Installing QAT PWA](/img/media/image10.png) +*Figure 1: PWA Installation* + +#### Alternate Installation (If the button is missing) +1. In Chrome, click the **three vertical dots** (top-right). +2. Select **Cast, Save, and Share** > **Create Shortcut**. +3. A QAT icon will appear on your desktop. + +![PWA Alternate Method](/img/media/image12.png) +*Figure 2: Alternate PWA Installation* + +## Accessing QAT for Existing Users + +1. Navigate to [https://www.quantificationanalytics.org/](https://www.quantificationanalytics.org/) or open the PWA from your desktop. +2. Enter your credentials on the login screen. +3. (Optional) Check the **Offline** box to work without an internet connection. + +![Login Screen](/img/media/image13.png) +*Figure 3: Login Screen* + +### Security and Maintenance +- **Logging Out:** Click the logout icon in the top-right ribbon. +- **Changing Passwords:** Within QAT, go to your **Profile** > **Change Password**. +- **Forgot Password:** Click the **Forgot Password?** link on the login screen to receive a reset link via email. + +> **Note:** QAT passwords expire one year after they are created or updated. + +## Working Offline + +QAT is a hybrid tool that operates in both online and offline modes. You can manually switch to offline mode via the login page or within your profile settings. This is particularly useful in environments with low internet bandwidth. + +![Offline Toggle (Profile)](/img/media/image18.png) ![Offline Toggle (Login)](/img/media/image19.png) + +*Figure 9: Offline Toggle in Profile Settings & Figure 10: Offline Toggle on Login Page* + +The Profile icon in the top-right corner indicates your connection status: a **green circle** for online and a **red circle** for offline. + +![Status Icons](/img/media/image20.png) + +*Figure 11: Online (Green) vs. Offline (Red) Status Icons* + +### Online vs. Offline Capabilities + +| Feature | Offline | Online | +| :--- | :---: | :---: | +| Import/Export supply plans & forecasts | [x] | [x] | +| View master data | [x] | [x] | +| Build Trees and Scenarios | [x] | [x] | +| Enter transactional & consumption data | [x] | [x] | +| Extrapolate (Moving Average / Semi-Average) | [x] | [x] | +| View program-level reports & outputs | [x] | [x] | +| Reset password | [ ] | [x] | +| Sync master data | [ ] | [x] | +| Update program info / budgets | [ ] | [x] | +| Import data between modules | [ ] | [x] | +| Extrapolate (Linear Regression / TES / ARIMA) | [ ] | [x] | +| Create helpdesk tickets | [ ] | [x] | +| Download/Upload programs | [ ] | [x] | +| View global-level reports | [ ] | [x] | + +*\*Note: Most offline functions require that the specific program has been previously downloaded to your local device. See Section 3 for details.* + +## Troubleshooting and Software Updates + +### Regular Software Releases +QAT receives regular version updates for bug fixes, performance optimization, and new features. When a new version is available, you will be prompted on the login screen to refresh the application. + +![New QAT Version Prompt](/img/media/image22.png) +*Figure 4: Software Update Notification* + +> [!IMPORTANT] +> To avoid data loss during major structural updates, ensure all local programs are uploaded to the server prior to the release. The QAT Support Team will notify you in advance if an upload is required. + +### Solving Common Issues +If you encounter technical difficulties, follow these troubleshooting steps in order: + +#### 1. Application Refresh +Address most minor glitches by performing a hard refresh. Press **Ctrl + Shift + R** simultaneously. This reloads the software and clears temporary glitches, unlike a standard browser refresh (**Ctrl + R**). + +#### 2. Full Master Data Sync +If a refresh doesn't work, try a **Full Master Data Sync**. While a regular MDS only fetches incremental changes, a Full MDS reloads all master data from scratch. +- *Location:* Click the link at the bottom of the application. +- *Requirement:* A stable internet connection is required. + +![Full Master Data Sync](/img/media/image24.png) +*Figure 5: Full Master Data Sync Link* + +#### 3. Clear Site Data +As a final troubleshooting step, you can clear all locally stored data. + +> [!WARNING] +> This will erase all local changes and downloaded programs. Ensure you have **uploaded all data** to the server before proceeding. + +1. Press **Ctrl + Shift + I** to open the browser's Developer Tools. +2. Navigate to the **Application** tab. +3. Select **Storage** on the left and click **Clear site data**. +4. Log back in and re-download your programs. + +![Clear Site Data](/img/media/image26.png) +*Figure 6: Clearing Site Data* + +### Troubleshooting Network Errors +If you see a "Network error" message, it is usually due to: +- **Unstable Internet:** Try a faster connection or wait for better signal. +- **Firewall Restrictions:** Your organization's IT policy may block QAT. Request that your IT department whitelist the following URLs: + - `api.quantificationanalytics.org` + - `www.quantificationanalytics.org` + +## QAT Helpdesk and Tickets + +### Tickets for Adding/Updating Users and Master Data + +When a user needs to either add or update a user or master data for any reason, they may do so by taking out a helpdesk ticket. Before requesting any additions or changes to the master data in QAT, the user should first check the realm-level master data (Realm Level Masters \>\> Product) and the Program Catalog Report to make sure the information does not already exist. For more information on how to access and use master data, please see [Program Management](06-managing-programs-and-versions.md#working-with-program-data) and [Realm Masters](13-annex-1-application-realm-administrator-manual.md#realm-masters). For information on how to access the Program Catalog, please see [Program Catalog](13-annex-1-application-realm-administrator-manual.md#product). To access the QAT Helpdesk: + +1. > Users can access the QAT Helpdesk from two different locations in QAT: + 1. > On the login page, and + + 2. > from the top right ribbon in QAT + +![A screenshot of a login screen Description automatically generated](/img/media/image27.png) + +![A red line with numbers and circles Description automatically generated](/img/media/image28.png) + +Figure 18: Three location to access the QAT Helpdesk + +2. > Four options will appear for taking out a ticket: Add/Update User, Add/Update Master Data, Change Request, and Report a Bug. See below sections on [Change Requests](#requesting-a-change) and [Report a Bug](#reporting-a-bug). + +![P772#yIS1](/img/media/image29.png) + +Figure 19: QAT Helpdesk Menu + +3. > Choose to Add/Update User or Add/Update Master data. Either option will take you to different screens for more information. + +4. > Enter the information required in the form and click “Submit.” + +![P778#yIS1](/img/media/image30.png) + +Figure 20: Add/Update User Screen + +![A screenshot of a computer Description automatically generated](/img/media/image31.png) ![P781#yIS2](/img/media/image32.png) + +Figure 21: Add Master Data Screen Figure 22: Add Procurement Agent Master Data Screen + +After submitting a ticket, the user will be assigned a Ticket Code number (ex: QAT-570). The user will also receive an email notification and the number of “Open Tickets” on the top ribbon in red will increase. This ticket number corresponds to the ticket number stored in the JIRA software management tool. For more information on managing tickets and the JIRA software management tool, please see [Managing Tickets](#managing-tickets). + +### Requesting a Change + +When a user has an idea for a new feature, functionality, or design element that would make QAT a better application for all users, such as a new report, removing an unnecessary column, etc., they may request a change through the QAT Helpdesk. All change request tickets will require a detailed description and screenshots. Once the technical team receives a user’s change request ticket, it will be reviewed for feasibility and usefulness to all QAT users. If the change request is accepted, it will not be made available in QAT immediately, but will placed in a queue based on realm business priority, criticality, and LOE requirements. To request a change in QAT: + +1. > Click on the QAT Helpdesk icon. + +![A red line with numbers and circles Description automatically generated](/img/media/image28.png) + +Figure 23: QAT Helpdesk Icon + +2. > Click on “Request a Change” from the QAT Helpdesk menu options. + +3. > Complete the form by filling out the required information and click “Submit,” + +![A screenshot of a computer Description automatically generated](/img/media/image33.png) + +Figure 24: Change Request Ticket + +4. > After submitting a ticket, the user will be assigned a Ticket Code number (ex: QAT-570). The user will also receive an email notification and the number of “Open Tickets” on the top ribbon in red will increase. This ticket number corresponds to the ticket number stored in the JIRA software management tool. For more information on managing tickets and the JIRA software management tool, please see [Managing Tickets](#managing-tickets). + +### Reporting a Bug + +When a user comes across a potential system issue with QAT, they should attempt to troubleshoot it through an [application refresh](#1-application-refresh) and/or [clearing site data](#3-clear-site-data). If neither of these steps resolve the issue, the user should submit a helpdesk ticket to report the bug. + +The bug ticket will be addressed by the development team per the business priority, criticality and available ‘capacity’ via the incremental releases. The steps to raise a ticket in QAT is shown below: + +1. Open the QAT Helpdesk screen and click on “Report a bug”. + +2. Enter a summary of the bug as well as a description of the bug. Please be descriptive and provide as much detail as possible (_e.g., what program/version/functionality you were working on, steps you took to obtain the bug, etc_). + +3. Upload a screenshot of the bug by clicking the “Browse” button and pulling a saved screenshot file from your computer. + 1. It is also helpful to provide the program export, if possible (see [Program Exports](06-managing-programs-and-versions.md#export) on how to export a local program) + + 2. **\*Note**: If you want to upload multiple files, place the multiple screenshots in a folder on your computer and zip it before browsing in QAT. Then, upload the zipped folder.\* + +4. Choose a priority (Highest, High, Medium, or Low) for the bug based on the urgency and how it affects daily work in QAT + 1. Response and resolution times for bugs will be based on priority level + +5. Click on the “Submit” button to raise the ticket. + +![A screenshot of a computer Description automatically generated](/img/media/image34.png) + +Figure 25: Report a Bug + +### Managing Tickets + +For enhanced visibility, QAT will give users the option to manage and check the status of their tickets, whether they are adding/editing a user or master data, requesting a change, or reporting a bug. When a user submits a ticket, they will be assigned a Ticket Code number (ex: QAT-570). The user will also receive an email notification and the number of “Open Tickets” on the top ribbon in red will increase. This ticket number corresponds to the ticket number stored in the JIRA software management tool. + +![P815#yIS1](/img/media/image35.png) ![A red line with numbers and circles Description automatically generated](/img/media/image28.png) + +Figure 26: Helpdesk Ticket Code Number Figure 27: Number of Tickets on Top Ribbon + +From the email notification, users may click on “View Requests” to see the status of their ticket. Users may also add additional comments and screenshots to their request, if desired. **Users will always receive an email notification once the ticket has been completed.** + +**Note**: In order to fully access the ticket via the JIRA software management tool, users must create an account with a username and password in JIRA. Creating an account in JIRA is **optional**. JIRA is an outside software management tool that can be accessed through the link provided in the email, **by clicking on the HelpDesk icon and then choosing “Manage my tickets” in the top right corner of the pop-up**, or directly through [https://qathelpdesk.atlassian.net/servicedesk/customer/portals](https://qathelpdesk.atlassian.net/servicedesk/customer/portals). + +![P821#yIS1](/img/media/image36.png) + +Figure 28: Email Notification for QAT Ticket + +![A screenshot of a computer Description automatically generated](/img/media/image37.png) + +Figure 29: Option to Navigate to JIRA + +![P823#yIS1](/img/media/image38.png) + +Figure 30: JIRA Ticket Management + +## Navigation and Menu Bar + +**Basic Navigation** + +## QAT Helpdesk and Tickets + +The QAT Helpdesk is your primary point of contact for technical support, user management, and feature requests. + +### Submitting a Ticket +You can access the Helpdesk from the **Login Page** or the **Top Ribbon** within the application. + +1. Click the **QAT Helpdesk** icon. +2. Select one of the following options: + - **Add/Update User:** Request new accounts or role changes. + - **Add/Update Master Data:** Request additions to products, procurement agents, etc. + - **Request a Change:** Propose new features or design improvements. + - **Report a Bug:** Report technical issues (please include screenshots and steps to reproduce). +3. Complete the required fields and click **Submit**. + +![QAT Helpdesk Menu](/img/media/image29.png) +*Figure 7: Helpdesk Ticket Options* + +### Managing Your Tickets +After submission, you will receive a **Ticket Code** (e.g., QAT-570) and an email notification. +- **Tracking:** Click **View Requests** in the notification email to check status or add comments. +- **JIRA Integration:** QAT uses JIRA for ticket management. While optional, you can create a JIRA account to track all your requests in one place. + +## Navigation and Interface + +### Homepage and Dashboard +Upon logging in, you will see the main Dashboard. +- **Supply Planning Module:** Features enhanced visualizations and analytics. +- **Forecasting Module:** Displays tiles for each downloaded program. Click a tile's arrow to manage versions, trees, or data entry. + +To return to the Dashboard at any time, click the **Home** icon in the top ribbon or the **QAT Logo** in the top-left corner. + +![Supply Planning Dashboard](/img/media/image39.png) +*Figure 8: Supply Planning Home Screen* + +### Interface Layout +The interface consists of three primary areas: +1. **Top Ribbon:** Quick access to global functions (Profile, Helpdesk, Sync). +2. **Sidebar Menu:** Navigation to module-specific screens (Master Data, Reports, etc.). +3. **Main Content Area:** Where data entry and analysis occur. + +**Top Ribbon for Supply Planning vs. Forecasting:** +![Supply Planning Ribbon](/img/media/image44.png) +![Forecasting Ribbon](/img/media/image45.png) + +### Top Ribbon Functions + +| Icon | Function | +| :--- | :--- | +| ![Logout](/img/media/image46.png) | **Logout:** Logs you out of the QAT application. | +| ![Profile](/img/media/image47.png) | **User Profile:** Green when online, red when offline. Click to view username/roles, change language, reset password, or toggle online/offline mode. | +| ![Home](/img/media/image42.png) | **Dashboard:** Returns you to the main home screen. | +| ![Download Manual](/img/media/image48.png) | **User Manual:** Downloads the QAT manual to your local device. | +| ![Refresh](/img/media/image49.png) | **Refresh Page:** Reloads the current screen. | +| ![Upload Alert](/img/media/image50.png) | **Upload Status:** Blue indicates no changes pending. Red indicates local changes are ready for upload; the number shows affected programs. | +| ![Version Alert](/img/media/image51.png) | **Version Sync:** Red indicates a newer version is available on the server; click to synchronize your local program. | +| ![Helpdesk](/img/media/image52.png) | **QAT Helpdesk:** Opens the ticketing portal for support, data updates, or bug reports. The number tracks your open tickets. | +| ![ERP Notification](/img/media/image53.png) | **ERP Updates:** (Supply Planning only) Alerts you to updates from linked ERP systems (e.g., ARTMIS). | +| ![Guidance](/img/media/image54.png) | **Workflow Guidance:** (Forecasting only) Displays a high-level guide to the forecasting process. | + +Additionally, users can utilize the profile icon to check their current user roles, as well as: + +- Change their password, + +- Go [offline/online,](#working-offline) + ![A close up of words Description automatically generated](/img/media/image55.png) + +- [Change the preferred language,](#changing-language) + +- Chage to dark/light theme mode, and + ![A black and white text Description automatically generated](/img/media/image56.png) + +- Show decimals in the supply planning screens + ![A black text on a white background Description automatically generated](/img/media/image57.png) + +### Sidebar Menu + +The sidebar menu allows you to navigate through QAT's various screens. Available options depend on your assigned role and permissions. + +#### Key Modules + +- **Supply Planning Module:** Manage supply plan data, conduct reviews, and view supply planning reports. +- **Forecasting Module:** Build forecast trees, import consumption data, and analyze forecast outputs. +- **Master Data Sync:** Manually synchronize updated master data without logging out. +- **Application & Realm Masters:** (Admins only) Manage high-level data structures and realm-specific settings. + +#### Sidebar Navigation Icons + +| Icon | Action | +| :---: | :--- | +| ![Collapse](/img/media/image58.png) | **Full Collapse:** Hides the sidebar menu entirely for more screen space. | +| ![Minimize](/img/media/image59.png) | **Minimize:** Reduces the sidebar to icons only. | +| ![Expand](/img/media/image60.png) | **Expand:** Restores the full sidebar or expands a sub-menu. | +| ![Collapse Sub-menu](/img/media/image61.png) | **Collapse Sub-menu:** Hides nested menu items. | +| ![Module Toggle](/img/media/image62.png) | **Module Toggle:** Switches between the Forecasting and Supply Planning modules. | + +*Table 4: Sidebar Menu Icons* + +### Common Action Buttons + +| Button | Action | +| :--- | :--- | +| ![Submit](/img/media/image63.png) | **Submit:** Saves changes and updates the database. | +| ![Cancel](/img/media/image64.png) | **Cancel:** Discards unsubmitted changes. | +| ![Revert](/img/media/image65.png) | **Revert:** Returns unsubmitted data to its previous state. | +| ![Add](/img/media/image66.png) | **Add:** Creates a new record. | +| ![Update](/img/media/image67.png) | **Update:** Modifies an existing record. | +| ![Search](/img/media/image68.png) | **Search:** Filters the current table for specific keywords. | +| ![Clear](/img/media/image69.png) | **Clear:** Resets all active filters and search fields. | +| ![Mandatory](/img/media/image70.png) | **Required Field:** Indicates that data entry is mandatory. | +| ![Help](/img/media/image71.png) | **Tooltips:** Displays definitions, formulas, or context for specific terms. | +| ![Guidance](/img/media/image72.png) | **Page Guidance:** Provides high-level instructions for the current screen. | +| ![Export Logs](/img/media/image73.png) ![Export Reports](/img/media/image74.png) | **Export:** Downloads data/reports as PDF, CSV, or Word files. | + +## Changing Language + +To ensure that QAT is adaptable to users around the world, the application displays text in four different languages: English, French, Portuguese, and Spanish. Users are encouraged to submit tickets if they would like to see a particular label translation improved. (_Note: Translations for application labels can be edited only by **application admins**. Instructions on how to do so can be found in the [translation section](13-annex-1-application-realm-administrator-manual.md#database-translation)._) + +There are two ways to change the language displayed for the user: + +1. **Login Screen:** + +On the top right corner of the login screen, there is a drop-down menu from which users can select their preferred language ahead of logging in. This will not only change the text once you are logged in to QAT but it will also change the text displayed on the login screen. + +![P1001#yIS1](/img/media/image75.png) + +Figure 34: Login Screen Language Change + +2. **Within QAT:** + +Once logged into QAT, the user may change the display language by clicking on the user profile icon on the top right corner of the screen, selecting the preferred language and then the tool will automatically update it’s text/labels. + +![](/img/media/image76.png) + +Figure 35: In Tool Language Change + +## QAT Dashboard + +The Supply Planning dashboard provides a comprehensive interface for visual analytics. It is divided into three main sections: **Ticker**, **Overview**, and **Program Spotlight**. + +![QAT Dashboard](/img/media/image77.jpeg) + +*Figure 36: QAT Supply Planning Dashboard* + +### 1. Ticker +The Ticker displays high-level metrics via three auto-scrolling tiles: +- **Realm:** Shows global counts of countries, users, and programs. +- **My Access:** Lists supply plans available to you. +- **ERP Linking:** Shows the count of linked shipments across your programs. + +![Dashboard Ticker](/img/media/image78.png) + +*Figure 37: Dashboard Ticker Tiles* + +### 2. Overview +The Overview table summarizes multiple programs based on your access level. + +![Dashboard Overview Section](/img/media/image79.png) + +*Figure 38: Dashboard Overview Table* + +- **Program Selection:** Choose between server-based or local (downloaded) programs. Multi-select is supported. +- **Action Column:** (Local programs only) Provides quick links for deleting, uploading, or downloading programs. +- **Problem List (QPL):** (Local programs only) Click the number in this column to jump to the QAT Problem List for that program. +- **Notes & Status:** Review the current status and historical notes for each supply plan. + +![Version Notes](/img/media/image80.png) + +*Figure 39: Program Version Notes* + +### 3. Program Spotlight +This section provides deep-dive metrics for a single selected program. + +- **Stock Status:** A bar graph showing the percentage of months by stock category (e.g., Stocked, Overstocked, Stockout). +- **Forecast Error:** (Server programs only) Highlights planning units with high error rates (default >50%). +- **Shipments:** A pie chart showing funding sources and procurement status for upcoming shipments. +- **Data Quality:** Displays real-time metrics from the QAT Problem List (QPL), such as missing consumption data or overdue shipments. +- **Expiries:** Summarizes the quantity and total cost of products expiring within the report period. + +![Stock Status](/img/media/image82.png) ![Shipment Status](/img/media/image84.png) +*Figure 40: Stock Status & Figure 41: Shipment Analytics* + +![Data Quality Dials](/img/media/image85.png) ![Expiries Table](/img/media/image86.png) +*Figure 42: Data Quality & Figure 43: Product Expiries* diff --git a/docs/user/05-supply-planning-module-supply-planning.md b/docs/user/05-supply-planning-module-supply-planning.md deleted file mode 100644 index a8ab30f..0000000 --- a/docs/user/05-supply-planning-module-supply-planning.md +++ /dev/null @@ -1,471 +0,0 @@ ---- -id: supply-planning-module-supply-planning -title: "Supply Planning Module: Supply Planning" -sidebar_label: "Supply Planning Module: Supply Planning" -sidebar_position: 5 ---- - -# Supply Planning Module: Supply Planning - -## Supply Planning: An Overview - -![](/img/media/image153.png) - -Figure 99: Supply Planning Screen – Plan by MOS - -![](/img/media/image154.png) - -Figure 100: Supply Planning Screen – Plan by Quantity - -- What? All major data points (consumption, -shipments, inventory) come together on the supply planning screen, and this is -where most QAT users will spend the majority of their time. Users can click on -many of the cells in the table to directly edit their data. It is recommended -to use this screen for active supply planning (including data updates and -planning new shipments), but to use the data entry screen when significant -data entry is required. Note that some sections vary **based on whether the -planning unit is planned by MOS or planned by Quantity (as selected in -[Updating Planning Units](04-supply-planning-module-program-data.md#planning-units)) – differences are noted below.** - - This screen can also be viewed by the alternate reporting unit (ARU) associated with the planning unit. This means that users can view their supply plans in terms of the product names and units of measure they enter the data in, with values on the table and graph changing according to the ARU/PU conversion factor that is established by the user (see Alternate Reporting Units). The user selects to view by ARU clicking on the radio button and then selecting the desired ARU to display. - -![A screenshot of a calendar Description automatically generated](/img/media/image155.png) - -Figure 101: Supply Planning Table –by Planning Unit vs by Alternate Reporting Unit - -- Who? **Realm Admins, Program Admins**, **Supply -Plan Reviewers,** and **Program Users** can add data/edit data in the supply plan. -Certain “view only” roles can view the supply plan. - -- When? At any time. The user does not have to be -online. However, they must have downloaded a program onto their local computer -while online before beginning. - -- How? - -> **Note:** other than step 1 being required, the remaining steps are not sequential, but an explanation of the features available in the supply planning screen. - -1. > On the left menu bar, go to Supply Planning \> “Supply Planning” - 1. Select the desired **Program**. The drop-down list in the supply plan screen will show all the programs that have been downloaded by the user. Refer to [Download Program](03-managing-programs-and-versions.md#downloaddelete) for details on how to download a program. - - 2. Select the desired **QAT Planning Unit or Alternate Reporting Unit (ARU)**. - -![](/img/media/image156.png) - -2. > The screen displays two Supply Plan tabs: **Local Supply Plan** and **Server** **Supply Plan - VX.** The “Local Supply Plan” tab is the local version that was selected under “program” and is available to be edited. The “Server Supply Plan” is the latest version available on the server and is only available for viewing (not editable). - -![P2040#yIS1](/img/media/image157.png) - -3. > By default, the past 3 months and 15 future months from the current date are shown. Use **Scroll to Left/Right** to show data for 3 months in the past/future - -![P2044#yIS1](/img/media/image158.png) - -> Click “Show Formulae” at the top right of the screen for explanations on calculations on this screen. - -![](/img/media/image159.png) - -4. > Click on the PDF & CSV icons to export this report, and will include all planning units in the program. In PDF, only the graph for the selected product will be included, but there will be tables for each planning unit. - -![P2050#yIS1](/img/media/image160.png) - -5. > Understanding the stock balance calculations on the top half of the table: - -![](/img/media/image161.png) - -Figure 102: Ending Stock Balance Calculation - -- > **Opening Balance** represents the quantity of stock at the beginning of the month. It is equal to the ending balance of the previous month, except the very first month of the program, where the opening balance is zero. It can be an inventory count from the previous month (**bolded**), or a projected value (unbolded). - -- > **Ending Balance** represents the quantity of stock at the end of the month. It can be an inventory count (**bolded**), or a projected value (unbolded). - -- > Follow the +/- signs besides each row to understand how the math works from opening balance to ending balance. - - - -6. > The bottom half of the table contains more detail to help the user interpret the stock status. - -![](/img/media/image162.png) - -Figure 103 Differences in the Supply Planning Table - Plan by MOS vs Plan by Quantity - -- > **Average monthly consumption (AMC)** is an average of the consumption over the months indicated by the AMC parameters, which are displayed above the table. **To edit these parameters, see [Updating Planning Units](04-supply-planning-module-program-data.md#planning-units).** - -![](/img/media/image163.png) - -Figure 104 Differences in the Supply Planning Legend- Plan by MOS vs Plan by Quantity - -- > **Unmet demand.** Estimated quantities of product that would have been consumed if sufficient stock was available: - - > When the forecast consumption is greater than the projected available beginning stock on hand. - - - > **When the actual consumption includes days of stock out** - - - > **When a negative manual adjustment is larger than the projected ending balance** - - - > The QAT unmet demand functionality is what captures what would have been negative stock in legacy software PipeLine. - -- > **The second row from the bottom** - - > **Planned by MOS: Months of Stock** is calculated as the ending balance of the month divided by the AMC. - - - > **Planned by Quantity: Max Quantity is calculated as the Minimum Qty + Reorder Frequency x AMC.** - -- > Stock Status Color-coding - - > **Planned by MOS: The “Months of Stock” row** is color-coded based on the stock status using the color coding displayed in the legend. Stock status is determined by comparing the MOS with the MIN MOS and MAX MOS. - - - > **Planned by Quantity: The “Ending Balance” row is color-coded based on the stock status** using the color coding displayed in the legend. Stock status is determined by comparing the quantity of the “ending balance” with the min quantity (provided by user) and max quantity (calculated). - - - -7. > **Reading the stock status graph.** The dates on this graph follow the table. By default, all graph elements are displayed. Click on any data element in the legend to hide a data element. The Stock Status graph has two vertical (Y) axes: - - - -- > The **primary (left) axis is in units**, and depicts shipments, consumption, stock, and expiries. For Plan by Quantity, there minimum and maximum quantities use the primary axis. - -![](/img/media/image164.png) - -Figure 105 Supply Planning Graph - Primary Axis (Plan by MOS) - -![](/img/media/image165.png) - -Figure 106 Supply Planning Graph - Primary Axis (Plan by Quantity) - -- > For plan by MOS, there is a **secondary (right) axis in months**, and depicts the stock parameters (minimum, maximum) and the calculated months of stock. - -![](/img/media/image166.png) - -Figure 107 Supply Planning Graph - Secondary Axis (Plan by MOS) - -## Supply Planning: Consumption - -In the supply planning table, only one number will show per month for the whole program in the consumption row. As noted in the legend, **_forecasted consumption_** is indicated by purple italic text, while **actual consumption** is indicated by black non-italicized text. - -![P2093#yIS1](/img/media/image167.png) - -> ![P2094#yIS1](/img/media/image168.png) - -![](/img/media/image169.png)**To add or edit consumption records** - -1. Click on the month and cell on the Consumption row in the supply planning screen. A new window called Consumption Details will pop up. In the table that appears, each row represents a region. Single-region programs will only have one row, while multi-region programs would have multiple rows. The total shows the aggregated consumption for all regions. - -2. Click on the consumption record of any month and region to display further details*.* Any records for that month and region will display below. - -3. To create a new record, right click on the details row and select “Add new consumption” or click the “+ Add Row” button. - -4. To edit a record, click on any cell and edit consumption details (consumption type, data source, quantity, etc.) Double click to activate any dropdowns. See [Consumption Data](04-supply-planning-module-program-data.md#consumption-data) for additional guidance on consumption data entry. - -5. Click “Submit” to save the changes and return to the main supply planning screen, where your changes will be reflected. ![A screenshot of a computer Description automatically generated](/img/media/image170.png) - -## Supply Planning: Shipments - -By default, shipments are only shown as one row in the supply planning screen – this is the aggregate quantity of all shipments (excluding suggested shipments). To show more details, click on the + icon to the left of the “+ Shipments” row to expand and display the sub-rows. You will see five rows split up by order status (top row for suggested shipments which are automatically calculated). - -**To see a detailed breakdown of all shipments in a month, click on the cell in the corresponding month in the ‘+Shipments row’. To see the detailed breakdown of all shipments by status, click on the cell in the corresponding month in the individual status row.** - -**ERP (enterprise resource planning)**: data linked to ERP from procurement agents are non-editable (see [ERP Shipment Linking](04-supply-planning-module-program-data.md#erp-shipment-linking)) - -For all shipment rows, the colors indicate the procurement agent. If a month has multiple shipments with different procurement agents, the cell will be green. Red triangles on the top right of the cell indicate that a shipment is an emergency. If the shipment is a local procurement, there will be an L icon in the bottom left of the cell. If the shipment is ERP linked, there will be a link icon in the top left of the cell. Shipments can have multiple icons such as a local ERP linked emergency order. The legend appears at the top of the screen. - -![](/img/media/image171.png) - -![](/img/media/image172.png) - -Figure 108 Shipments in Supply Planning - -The following sections will cover how to update existing shipments and create new shipments within the supply planning screen. See **Shipment Data** for more tips on the shipment data fields, which apply across the Shipment Data Entry screen and the supply planning screen. - -### Updating an Existing Shipment - -1. Click on the cell representing the month and shipment to be edited. Clicking on the ‘+Shipments’ row will open up a tab with all shipments for that month regardless of status. Clicking on one of the status rows will open up a tab showing only shipments for that month with that status. - -![A screenshot of a computer Description automatically generated](/img/media/image173.png) - -2. The Shipment Details pop-up will appear. Make all desired changes. To update batch or date information, right click on the shipment row. The top of the pop-up allows users to navigate to a different month to make changes to those shipments as well. - -![](/img/media/image174.png) - -3. Click “Submit” to save the changes and return to the main supply planning screen, where changes will be reflected (**Note:** The Submit button will not appear if all required fields are not filled.) - -![A screenshot of a computer screen Description automatically generated](/img/media/image175.png) - -**Note:** Planned shipment was edited to shipped, showing the 130,000 has now been moved from “Planned” row to the “Shipped & Arrived” row. - -![](/img/media/image176.png) - -**Reminder:** Tool tips are provided to help guide where to update specific parameters. These provide clarity into what users need to update. - -**Updating Shipment Quantity with Recalculate Button** - -For planned shipments in the future, QAT will suggest a revised shipment quantity as an early warning to avoid going below minimum stock levels. Just like suggested shipments (see [Creating a new Shipment](#creating-a-new-shipment)), QAT will only provide the recalculate button if the shipment falls in a month that is below min followed by at least two months that also below minimum stock level. The quantity recommended by the recalculate button will follow the same logic as the QAT suggested shipments (see **Rules for Suggested Shipments** below). - -Below are the steps to use the recalculate button in the Supply Planning screen: - -Go to a planned shipment in the future where the current month and at least following 2 months are below minimum stock level. - -Left click on the shipment. - -Find the ‘Order Quantity’ column and right click. - -Click ‘Recalculate’. A pop-up message will appear telling you how much quantity QAT is suggesting to add and how much quantity the revised shipment will be. - -![P2155#yIS1](/img/media/image177.png) - -Figure 109: Recalculate Button - -Click ‘Ok’. The pop-up will go away, and the revised order quantity will appear in the ‘Order Quantity’ column. Click ‘Submit’ if you wish to proceed with the revised order quantity. At any point, the user can override the quantity by double clicking into the cell and typing in a new quantity. - -The revised quantity will now reflect in the supply plan. - -### Creating a New Shipment - -There are two ways to create new shipments – 1) converting a QAT suggested shipment into a planned shipment or 2) manually adding a shipment. - -To **Convert a** **Suggested Shipment** into a planned shipment: - -1. Click on the row for Suggested Shipment under the desired month. - -2. The Shipment Details pop-up will appear. Change the status to the desired status, fill out the required fields, indicated by an asterisk. Double click to activate any dropdowns. Scroll to the right to see all fields. Hover over tool tips if any clarification is needed (shown in picture below). The order quantity will be pre-filled by the suggested order quantity. - -![](/img/media/image178.png) - -![A screenshot of a computer Description automatically generated](/img/media/image179.png) - -3. Click “Submit” to save the changes and return to the main supply planning screen, where changes will be reflected (**Note**: The Submit button will not appear if all required fields are not filled) - -**Rules for Suggested Shipments:** - -> For Plan by MOS: - -1. Is the planning unit understocked (MOS\Min, the suggested shipment will bring the current month’s stock level to **minimum.** - -3. If AMC = 0 or N/A, there will not be a suggested shipment for that month. - -> For Plan by Quantity: -> -> Where Month N is the month QAT is calculating for, and X = Distribution Lead Time - -1. > If AMC = 0 or N/A for Month N, no suggested shipment - -2. > If Month N is stocked out (Ending balance = 0), QAT will always suggest a shipment - - - -1. > If both of next 2 months (N+1, N+2) are \< min qty, suggested shipment is the quantity that would bring month N to **maximum qty.** - -2. > If one or both of the next 2 months (N+1 or N+2) is \> min qty, suggested shipment is the quantity that would bring month N to **minimum qty.** - - - -3. > Is product understocked (ending balance \< Min qty) for 3 straight months (Month N, N+1, N+2)? - - - -1. > If yes, suggested shipment is the quantity that would bring Month N to **maximum qty.** - -2. > If no, no suggested shipment - -_QAT puts the suggested quantity in Month N-X. In other words, X months before Month N, where X is the distribution lead time._ - -**To Manually Create a New Shipment:** - -1. Click on the cell representing the month the shipment should be added to. Clicking on the ‘+Shipments’ row will open up a tab with all shipments for that month regardless of status. Clicking on one of the status rows will open up a tab showing only shipments for that month with that status. Either option will work for adding a new shipment. - -2. The Shipment Details pop-up will appear. To add a new row, click on the ‘+ Add Row’ button or right click on any row and select ‘Add new shipment’ Double click to activate any dropdowns. Change to the desired status, quantity, and complete the required fields indicated by an asterisk. Scroll to the right to see all fields. - -3. To create multiple new shipments, right click on any row and select “Add new shipment” or click the “+ Add Row” button. - 1. Be mindful of tool tip icons to help guide which specific parameters need to be updated. - -> ![A close up of a white background Description automatically generated](/img/media/image180.png) - -![P2201#yIS1](/img/media/image181.png) - -4. Click “Submit” to save the changes and return to the main supply planning screen, where changes will be reflected (**Note:** The Submit button will not appear if all required fields are not filled.) - -## Supply Planning: Inventory/Adjustments - -In the supply planning table, one number will show per month for the whole program in the **manual** **adjustments** row, regardless of how many manual adjustments are made. Similarly, the **ending balance** will always be one row, regardless of whether the ending balance is projected by QAT or provided by the user as an inventory count. - -![](/img/media/image182.png) - -1. ![](/img/media/image169.png) To add or edit adjustment or inventory records, click on the month and cell on the adjustments or ending balance rows in the supply planning screen. - 1. A new window called **Adjustments and Inventory Details** will pop up. In the table that appears, each row represents a region. Single-region programs will only have one row, while multi-region programs would have multiple rows. - - 2. The total shows the aggregated adjustments and inventory for all regions. - - 3. Click on the record of any month and region to display further details - -![P2222#yIS1](/img/media/image183.png) - -2. Any records for that month and region will display below. - - To add an adjustment or inventory record, click on add row, or right-click on the bottom table and select “Add new adjustment” or “Add new inventory”. Enter the required details. For adjustments, users can enter both positive and negative adjustments, in the past and in the future, and notes are required - -![P2227#yIS1](/img/media/image184.png) - -- To edit a record, click on any cell to edit. - - - -3. **Note:** A user can review which batch is affecting their ending balance for a particular month, by clicking on “Final Inventory” in the “Adjustment and Inventory Details” screen pop-up. - -![P2232#yIS1](/img/media/image185.png) - -Figure 111: Batches included in Final Inventory Pop-up - -4. For months with an inventory record, the user can click edit the batch quantities. - - Note: redistributing batch quantities should be the last resort. It’s always better to update the information upstream (shipment, consumption, adjustment) instead of updating the inventory batch information. - - - How to do it? - 1. Ensure there is an actual/manual inventory count for the month - - 2. Click on “final inventory” to pull up the batches - - 3. Type over the actual quantity – use the dropdowns if you want to change batches - - 4. Remember, the total of the batches must match the total inventory total for the month. - - - Right click on any batch to view the batch ledger (learn more in [Supply Planning: Project Expired Stock and Batch Information](#supply-planning-project-expired-stock-and-batch-information).) - -> ![](/img/media/image186.png) - -Figure 112: Batches Affecting Final Inventory Pop-up - -## Supply Planning: Project Expired Stock and Batch Information - -![](/img/media/image187.png)Users can view the projected expired stock, if any, for each month in their supply plan in the P**rojected Expired Stock** row. Clicking on the cell will bring a pop-up window with the expiry details. - -![](/img/media/image188.png) - -From the pop-up – users can do 2 functions: - -1. **Edit the batch that contributed to the expiry**: Click on the Batch Number. QAT will automatically redirect the user to the shipment from which the batch was generated. From the shipment screen, a user can edit the Batch Name, Expiry Date, and Shipment Quantity. - -![P2240#yIS1](/img/media/image189.png) - -> **Note:** Users can also edit this information in the Shipment Data entry screen (see [Shipment Data](04-supply-planning-module-program-data.md#shipment-data)). - -2. **View the batch ledger:** Click on the Expired Quantity cell. QAT will automatically open a pop-up screen below with the batch ledger, which shows the life of a batch month-by-month from shipment receipt to expiry. - -![P2247#yIS1](/img/media/image190.png) - -> **Note:** unless the user tags a batch to specific actual consumption or adjustment entries (see “Add/Update Batch Details” in [Consumption Data](04-supply-planning-module-program-data.md#consumption-data) and [Inventory Data](04-supply-planning-module-program-data.md#inventory-data)), QAT will default to monthly batch quantities being placed in the “Auto-Allocated” column in the Batch Ledger. - -## Scenario Planning - -QAT provides users with predefined scenarios for supply planning. This functionality will allow users to make changes to- and visualize their data in different ways, without necessarily affecting their current supply plan. Users can apply one or more scenarios to their data to see how those changes affect stock projections. The selected scenario(s) can then be applied to a current supply plan, creating a new version. - -There are currently six predefined scenarios available to users; more can be programed into QAT depending on the need and use cases. QAT users can request new scenarios through raising a ticket. The need for new scenarios will be managed centrally by the Realm Admin. - -Available scenarios: - -- > **Increase forecasted consumption**: for a user-defined percentage and period. This will apply a percent increase to forecast values for each month of the selected period. - -- > **Decrease forecasted consumption**: for a user-defined percentage and period. This will apply a percent decrease to forecast values for each month of the selected period. - -- > **Forecast phase in/out product:** for a user-defined period and start and end forecast consumption values. QAT will draw a straight line by interpolating between the start and ending values, and will replace the current forecast consumption values. - -- > **Remove unfunded shipments**: all shipments without an assigned funding source (i.e., funding source = TBD) will be removed from the supply plan and stock projections. - -- > **Remove all Planned shipments**: all shipments with status “planned” will be removed the supply plan and from stock projections. User can check a box to only remove the “planned shipments” that do not comply with the established lead times (i.e. expected receipt date is sooner than what would be feasible given lead times). - -- > **Remove all Submitted shipments not within the lead time**: all shipments with status “submitted” that do not comply with the established lead times will be removed from the supply plan and stock projections. - -- > **Remove all On Hold Shipments not within the lead time**: all shipments with status “on hold” that do not comply with the established lead times will be removed from the supply plan and stock projections. - -- > **Re-plan supply plan:** for a user-defined time period, QAT removes planned shipments that are not correctly maintaining stock between MIN/MAX parameters and creates new planned shipments to comply with stock parameters, using suggested shipment logic described in Section 5.C2 Creating a New Shipment. - -To access these scenarios: - -1. Go to Supply Planning and click on “Scenario Planning”. - -2. Select a predefined scenario from the dropdown menu and edit the required fields - -3. Click Add to view the changes. - -![P2270#yIS1](/img/media/image191.png) - -Figure 113 Scenario Planning Screen - -4. The scenario will be shown in the “Scenario List”. - -![P2274#yIS1](/img/media/image192.png) - -Figure 114: Scenario Planning Scenario List - -5. If the user wishes to apply the scenario to their supply plan, they can click on the “Submit” button. The new supply plan will get stored in the computer of that user, and the user can upload this to the server as a new version via the Upload functionality. - -6. If the user does not wish to apply the scenario to their current supply plan, they can click on the “Cancel” button or the “Reset” button, and the changes will not take effect. - -## Supply Plan Report - -The purpose of the supply plan report is to allow the user to quickly assess the stock status of one or more selected programs and/or planning units, by graphically comparing the stock projections to dynamic minimum and maximum inventory levels and to be able to see all consumption (both actual and forecast), inventory, and shipping details in one place. The report provides a graphical representation of the supply plan, as well as a tabular view. The report can be exported in PDF and/or CSV format. - -- **Accessible to:** Realm Admins, Program Admins, Program Users, and Reports Viewer - -- **Navigation:** Supply Planning  Supply Plan Report - -**Users can utilize the various dropdown parameters at the top of the screen to generate different views of the Supply Plan Report. Each view of report generated, will have both a graphical representation and tabular equivalent of the data. There are three main views of the Supply Plan Report:** - -1. **Single Program View** - 1. **Single program** - - 2. **Single Planning Unit (PU) or single Alternate Reporting Unit (ARU)** - - 3. **Shipments disaggregated by status (i.e. planning, shipped, received, etc.)** - -![A graph with blue and red lines Description automatically generated](/img/media/image193.png) - -Figure 115: Supply Plan Report: Single Program View, Graph - -![A screenshot of a computer Description automatically generated](/img/media/image194.png) - -Figure 116: Supply Plan Report: Single Program View, Tabular Data - -2. **Multi-Program View** - 1. **Multiple programs** - - 2. **Single PU or ARU** - - 3. **Shipments disaggregated by program (i.e. FASPonia Malaria MOH & FASPonia Malaria Social Marketing)** - - 4. **Notes: QAT is able to aggregate the supply planning data across multiple programs if they share the same PU/ARU. This could be useful if a country has multiple parallel programs monitoring the same products and would like to see an aggregated or national view of the stock status over time.** - -![A graph with blue and red lines Description automatically generated](/img/media/image195.png) - -Figure 117: Supply Plan Report: Multi-program View - -![A screenshot of a computer Description automatically generated](/img/media/image196.png) - -Figure 118: Supply Plan Report: Multi-program/EU View, Tabular Data - -3. **Equivalency Unit (EU) View** - 1. **Single or multiple programs** - - 2. **Multiple PUs _(ARUs cannot be used with EUs)_** - - 3. **Shipments disaggregated by program, PU, or program-PU** - - 4. **Notes: QAT is able to aggregate across PUs that are different (different pack sizes, usage rates, etc.), but related by utilizing an EU (see [Equivalency Units](07-forecasting-module-program-data.md#equivalency-units) for more information) and a corresponding conversion factor. This could be useful for countries or global viewers that would like to see concepts such as, Malaria Treatments, Couples Year Protection (CYP), ARV Patient Months, etc. as an aggregate.** - -![A graph with colorful lines and numbers Description automatically generated with medium confidence](/img/media/image197.png) - -Figure 119: Supply Plan Report: Equivalency Unit View - -**Note:** - -1. > **The report utilizes the Planning Unit settings set by the Program Admin for AMC, shelf life, MIN, reorder interval, and MAX** - -2. > The Shipment Quantity column is the sum of all shipments that have a receive date in the same month for that planning unit - -3. > The “Shipment Quantity | Funding Source | Shipment Status | Procurement Agent | RO – Prime lie No | Order No – Prime line No” column allows the user to see the disaggregated shipments that have receive date in the same month, including details of quantity, procurement agent, status, funding source, and order number assigned to that order - -4. > The “Consensus Consumption” column only appears if a user chooses multiple programs for aggregation - -5. > The PDF and CSV exports have multiple options, similar to the report dropdowns, allowing for exports of aggregated programs, multiple single product supply plans, or aggregated products (via EUs) - -# diff --git a/docs/user/06-managing-programs-and-versions.md b/docs/user/06-managing-programs-and-versions.md new file mode 100644 index 0000000..65f5d7d --- /dev/null +++ b/docs/user/06-managing-programs-and-versions.md @@ -0,0 +1,162 @@ +--- +id: managing-programs-and-versions +title: "Managing Programs and Versions" +sidebar_label: "Managing Programs and Versions" +sidebar_position: 6 +--- + +# Managing Programs and Versions + +## Working with Program Data + +QAT allows you to manage program data through four primary actions: downloading, uploading, importing, and exporting. + +| Action | Mode | Description | +| :--- | :---: | :--- | +| **Download** | Online | Retrieve program data from the server to your local device. | +| **Upload** | Online | Save your local changes back to the server. | +| **Export** | Offline | Save local data to a compressed file (`.zip`) for sharing. | +| **Import** | Offline | Load data from an exported `.zip` file into QAT. | + +> [!NOTE] +> Forecasting and Supply Planning programs are separate modules. Ensure you are in the correct module before performing any data operations. + +### Workflow Summary +- **Download:** Necessary to begin work on any program. +- **Upload:** Share your work with the team. Uploading as "Final" in Supply Planning starts the review process; in Forecasting, it makes the data available for import into Supply Planning. +- **Export/Import:** Primarily used for sharing data in offline environments (e.g., via USB drive). + +## Download and Delete Programs + +### Overview +- **Who:** Admins, Program Users, and Reviewers. +- **When:** Required for online downloads. Necessary even when working online to enable data entry and scenario planning. +- **Status Indicators:** + - ![Red Icon](/img/media/image89.png) **Red:** Your local version is outdated. + - ![Blue Icon](/img/media/image90.png) **Blue:** You have the latest version or no version downloaded. + +### How to Download a Program +1. Navigate to **Program Management** > **Download/Delete Program** (or click the download icon in the top right). +2. The screen displays programs with color-coded text: + - **Green:** Latest version downloaded. + - **Red:** Outdated version downloaded. + - **Black:** Not yet downloaded. +3. Select the checkbox for the target program. QAT defaults to the latest version. +4. (Optional) Expand the triangle next to a program to select a specific historical version. +5. Click **Download**. + +![Load Program Screen](/img/media/image91.png) +*Figure 1: Download Program Interface* + +### Downloading a Subset of Data (Supply Planning Only) +To improve performance for large programs, you can download a truncated version of a supply plan. +- Check **Download specific range of supply plan data**. +- Select a start date (minimum 18 months in the past). +- **Note:** Older data remains safely on the server and is merged during future uploads. + +### Deleting and Cleaning Up +- **Delete:** Click the trashcan icon next to a specific version. +- **Clean Up:** Click the broom icon to delete all local versions except the latest one. + +> [!WARNING] +> If you see a "More recent server version" warning during synchronization, clicking **OK** will overwrite your local changes with the server's data. Click **Cancel** to keep your local edits. + +![More recent server warning](/img/media/image97.png) +*Figure 2: Server Version Conflict Warning* +## Uploading Program Data + +### Purpose of Uploading +- **Draft Version:** Save your work-in-progress to the server and share it with other users. +- **Final Version (Supply Planning):** Marks the supply plan as complete and initiates the review process. +- **Final Version (Forecasting):** Makes the forecast available for import into the Supply Planning module. + +### How to Upload (Supply Planning) +1. Go to **Program Management** > **Upload Version** (or click the upload icon in the top right). +2. Select your program and the **Version Type** (Draft or Final). +3. Add **Notes** describing the changes made. +4. Review the comparison tabs (**Consumption, Inventory, Shipment, QPL**). +5. Resolve any conflicts (highlighted in **Yellow**) by right-clicking the row and selecting **Resolve Conflict**. +6. Click **Upload**. + +> [!IMPORTANT] +> You cannot upload a "Final" version if there are any "Open" issues in the QAT Problem List. You must first address them or mark them as "In Compliance." + +### How to Upload (Forecasting) +1. Navigate to **Program Management** > **Upload Version**. +2. Select the program and version type. +3. Review changes across the tabs (**Version Settings, Planning Unit, Consumption, Tree, Selected Forecast**). +4. Resolve conflicts and click **Upload**. +5. Complete the **Forecast Validation** checklist to ensure data integrity and click **Okay** to finalize the upload. + +![Forecast Validation](/img/media/image105.png) +*Figure 3: Forecast Validation Screen* + +## Supply Plan Version and Review (Supply Plan Module Only) + +- Who? This function is available for **Application/Realm/Program +## Supply Plan Version and Review (Supply Planning Only) + +### Overview +- **Who:** Admins, Program Users, Reviewers, and Viewers. +- **When:** Used online to track the submission and approval status of supply plans. +- **Why:** + - **Planners:** Monitor approval status and feedback. + - **Reviewers:** Manage the review queue and approve/reject submissions. + +### How to Review a Supply Plan +1. Navigate to **Program Management** > **Supply Plan Version and Review**. +2. Select filters (Period, Country, version type) to find the target plan. +3. Click a row to view details. + +#### For Reviewers: +- **Supply Planning Tab:** Review stock status and data for each planning unit. +- **QAT Problem List Tab:** Review all flagged issues. +- **Action:** Check the **Reviewed** box for each issue. You can add **Reviewer Notes** or update the **Problem Status** (e.g., mark as "Resolved"). +- **Manual Problems:** Click the **+** icon to add issues not caught by automatic validation. +- **Approval:** Set status to **Approved** or **Needs Revision**, add mandatory notes, and click **Update**. + +![Supply Plan Review Interface](/img/media/image106.png) +*Figure 4: Supply Plan Versions and Review Screen* + +### Email Notifications +QAT automatically notifies relevant users when a plan is: +- **Uploaded (Final):** Reviewers notified. +- **Needs Revision:** Planner notified. +- **Approved:** Planner and team notified. + +## Exporting and Importing Data + +### Exporting Programs +Use Export to save program data to your machine for offline sharing (e.g., via USB). +1. Go to **Program Management** > **Export Program**. +2. Select the downloaded program from the dropdown. +3. Choose encryption: + - **Encrypted (default):** Secure; required for importing back into QAT. + - **Unencrypted:** For external data analysis (e.g., Excel). +4. Click **Submit** and select a save location. + +![Export Program Screen](/img/media/image110.png) +*Figure 5: Export Interface* + +### Importing Programs +Use Import to load a `.zip` file into your local QAT instance. +1. Go to **Program Management** > **Import Program**. +2. Click **Browse** and select the `.zip` file. +3. Click **Next**, select the program(s) from the file, and click **Import**. + +![Import Program Screen](/img/media/image111.png) +*Figure 6: Import Interface* + +## Version Comparison (Forecasting Only) + +Use the **Version Comparison** screen to view differences between two versions of the same forecast program. + +1. Navigate to **Program Management** > **Version Comparison**. +2. Select the program and the two versions you wish to compare. + - **Note:** Final versions are marked with an asterisk (`*`). + - You can compare local vs. server and draft vs. final versions. +3. Review the comparison table, which summarizes the selected forecast, forecast quantity, and notes for each planning unit/region combination. +4. (Optional) Click the icons in the top right to export the comparison as a **PDF** or **CSV**. + +![Version Comparison Interface](/img/media/image112.png) +*Figure 7: Forecast Version Comparison* diff --git a/docs/user/06-supply-planning-module-reports.md b/docs/user/06-supply-planning-module-reports.md deleted file mode 100644 index eb39292..0000000 --- a/docs/user/06-supply-planning-module-reports.md +++ /dev/null @@ -1,598 +0,0 @@ ---- -id: supply-planning-module-reports -title: "Supply Planning Module: Reports" -sidebar_label: "Supply Planning Module: Reports" -sidebar_position: 6 ---- - -# Supply Planning Module: Reports - -QAT reports allow the user to extract and view their supply planning data in graphs, tables, and other visual formats. The user will also be able to navigate, sort, filter, and view the data for specific needs. QAT reports produce visualizations and display data in a way that can support decision making. - -The reports are divided into **Global Reports** and **Program-specific Reports**. Program-specific Reports are shown offline, as well as online. However, the Global Reports are shown only in online mode and are only available to Global Users, such as the Realm Administrator and the Application Administrator. - -**Note:** All QAT reports have the ability to be exported into an Excel CSV file as well as PDF format. Additionally, all graphs allow for the user to hover over a visual for a tool tip with more information. - -## QAT Problem List - -**Purpose:** A Supply Plan Review integrated within QAT that allows for a quality check to easily identify problematic data/issues and correct these before uploading a supply plan to the server as a “Draft” or “Final” version. - -- **Accessible to:** Realm Admins, Program Admins, and Program Users - -- **Navigation:** Reports  QAT Problem List - -![P2309#yIS1](/img/media/image198.png) - -Figure 120: QAT Problem List - -**Note:** Only the Problem associated with the programs that have been downloaded by the user in their local machine will appear in the QAT Problem List. For details on how to download specific programs and versions, refer to the [Download Program](03-managing-programs-and-versions.md#downloaddelete) section of the User Manual. - -### QAT Problem List Basics - -Each Problem that is flagged in the QAT Problem List will have a separate line. This will have the associated planning unit, a description of the problem, a suggestion on how to fix the problem, the problem status, user notes, a checkbox for identifying if the problem has been reviewed, the latest reviewer notes (as applicable), the date it was last reviewed and the criticality. - -![P2315#yIS1](/img/media/image199.png) - -Figure 121: Aspects QAT Problem List - -QAT Problems can be subdivided into four main categories: Data Quality, Procurement Schedule, Supply Planning, and Other. They are also assigned to different levels of criticality: Low (yellow), Medium (orange), and High (red). The criticality informs users the extent to which a problem affects the quality of the supply plan. However, regardless of criticality, all problems must be “In-compliance” or “Addressed” in the QAT Problem List to be uploaded as a Final Version. There are five main statuses associated with the individual problems in the QAT Problem List: - -1. **In-Compliance** – Issue has been closed through data entry by the user. Status will be automatically changed, and notes are not required. - -> _Example – A planning unit is missing actual consumption in the last 3 months. A user enters actual consumption data for the last 3 months. QAT automatically marks this as ‘in-compliance’._ - -2. **Resolved** – Issue has been manually marked by reviewer as ‘resolved’. The reviewer uses this status if this issue will unlikely be corrected via data entry and also does not require further notes in the future. Only a reviewer can mark an issue as ‘resolved’. - -> _Example – A planning unit gets flagged for not following dynamic forecasting. The user enters a note that this planning unit does not follow dynamic forecasting as it is not a seasonal product. The reviewer marks this as resolved because the explanation will most likely not change in the future._ - -3. **Addressed** – Issue has been manually marked by either reviewer or user as ‘addressed’. The user applies this status when they cannot resolve the issue through data entry. This status must be accompanied by a note. The reviewer uses this status if this issue cannot be resolved in this review period, but will be resolved in the future, most likely in a few periods, rather than before the next review. - -> _Example – A planning unit being phased out only has 8 months of forecasted consumption in the future instead of 18. This is acceptable as it is a phasing out planning unit, but the user will still need to de-activate the planning unit once it is fully phased out, which is why the issue is marked as ‘addressed’ instead of ‘resolved’._ - -4. **Open** – This problem has been automatically flagged by QAT, or the problem has been manually marked by the reviewer as ‘Open’. The reviewer could use this status when rejecting a supply plan to indicate that the notes are not accepted. - -> _Example – A user has a planning unit that is missing actual consumption data in the last 3 months. QAT will automatically flag this as 'Open'. If the problem has been 'Addressed' when uploaded and approved, the problem will revert back to the 'Open' status for the next submission._ - -5. **Reviewed -** The issue has been reviewed by the supply plan reviewer. This field is only editable by the supply plan reviewer. - -### Closing and Addressing Problems - -1. > **Closing a problem via data entry**: to change an ‘Open’ problem to one that is ‘In-compliance,’ the user will need to complete the suggestion provided in the “Suggestion” column for the specific problem. For example, the suggestion may be to “provide actual consumption” for specific months. Thus, the user will need to: - -![P2340#yIS1](/img/media/image200.png) - -Figure 122: Closing a Problem Example - -1. Navigate to the Consumption Data Entry screen by either clicking directly on the Problem (which will open a new QAT window) or by clicking on Supply Plan Data  Consumption Data. - -2. From the consumption data entry screen, the user will add actual consumption for the requested months. For instructions on how to add consumption, please refer to [Consumption Data](04-supply-planning-module-program-data.md#consumption-data). - -3. Navigate back to the QAT Problem List and click Recalculate to refresh the QAT Problem List to include the most recent addition of actual consumption data. The previously flagged problem should now be “In-compliance” and no longer be flagged by the QAT Problem List. - -![P2346#yIS1](/img/media/image201.png) - -Figure 123: QAT Problem List Recalculate/Refresh - -1. **Addressing a problem with a comment**: If a problem that has been flagged in the QAT Problem List cannot be fixed and made ‘In-compliance’ through data entry as recommended in the “Suggestion” column, a user can provide a comment and manually change the status to ‘Addressed.’ For example, a planning unit may be overstock/understocked and the suggestion to “re-evaluate supply plan to meet the min/max parameters” is presented. If a user is unable to fix this problem via data entry, they will need to address the problem: - 1. Double-click on the Problem Status dropdown for that problem and choose “Addressed.” Users must provide an explanatory note in the Notes column for all problems marked as “Addressed.” - -![P2354#yIS1](/img/media/image202.png) - -Figure 124: Addressing a Problem & Adding a Note - -> **Note:** the user can also see in the “Problem Transaction Details” screen by right clicking on the Problem. This area will show the user past notes, reviewers, dates reviewed, etc. - -![P2358#yIS1](/img/media/image203.png) - -Figure 125: Problem Transaction Right Click - -![P2360#yIS1](/img/media/image204.png) - -Figure 126: Problem Transaction Details - -2. Click “Update.” The QAT Problem List will now include the most recent addition of explanatory notes and the status. - -### QAT Problem List: Explanation of Problems - -- **Missing recent actual consumption inputs (within the last 3 months)** - -> If a planning unit is missing recent actual consumption data inputs within the last three months, it will be flagged in the QAT Problem List. If the inputs are filled in for any of these last three months, whether it is one month or all three months, the problem will not be flagged by the system. - -- **Any gaps in the last 6 months (actual consumption)** - -> QAT checks if a planning unit is missing a month or multiple months of recent actual consumption inputs between two actual consumption entries in the specified 6-month range. This problem is looking for accidental gaps in actual consumption inputs. If there is any gap in actual consumption data in the past 6 months, the QAT Problem List will flag this as an issue. For example, a user inputs actual consumption for September 2022, December 2022, and January 2023. This will be flagged by the QAT Problem list because there is a gap of missing actual consumption inputs for October 2022 and November 2022. - -- **Missing recent inventory inputs (within the last 3 months)** - -> If a planning unit is missing recent actual inventory data inputs within the last three months, it will be flagged in the QAT Problem List. If the inputs are filled in for any of these last three months, whether it is one month or all three months, the problem will not be flagged by the system. - -- **Supply Plan lacks forecasted consumption within the next 18 months** - -> If a planning unit is missing the forecasted consumption inputs for one or more months for a period of 18 months from the current month, QAT will flag it as a problem. QAT will check for gaps to ensure that all of the future 18 months have forecasted consumption values. -> -> **\*Note:** If there is a planning unit that is phasing out, it is recommended that the user puts zero as the forecasted consumption, until it is fully phased out, at which point the planning unit will need to be deactivated.\* - -- **Shipments with received dates in the past** - -> QAT will check the receive dates of all shipments to see if any are in the past based on the current date. If the receive date for a shipment is in the past, it will be flagged in the QAT Problem List. For example, there is a planning unit with a receive date of December 31st, 2022. As this date is in the past, QAT will flag it, and the user will need to either change the shipment status to “Received” or change the receive date to one that is in the future. -> -> **\*Note:** there is a fourteen-day buffer time for QAT to recognize that the shipment receive date is in the past and for the problem to be flagged.\* - -- **Shipments that should have been submitted by the target date** - -> QAT will check the estimated shipment dates, which are calculated based on the Program’s pre-defined lead times, to see if there are any shipments with an estimated “Submitted” date in the past. If the estimated shipment submitted date is in the past, it will be flagged in the QAT Problem List. For example, there is a planning unit with a target submitted date of January 15th, 2023. As this date is in the past, QAT will flag it, and the user will need to either change the shipment status to “Submitted” or change the receive date to one that is further in the future. Changing the receive date to one further in the future, will cause QAT to automatically recalculate the target shipment dates. If it is not possible to change the status or receive date, a user many ‘Address’ the problem (see [Closing and Addressing Problems](#closing-and-addressing-problems)). -> -> **\*Note:** There is a fourteen-day buffer time for QAT to recognize that the shipment submitted date is in the past and for the problem to be flagged.\* - -- **Dynamic forecasting is not used (for commodity groups Malaria, ARV, VMMC)** - -> For any products that belong to the following tracer categories: Malaria, ARV, or VMMC, QAT will check for dynamic forecasting. GHSC-PSM encourages forecasting with dynamic monthly values, in order to show that factors, such as seasonality, program scale-up, or campaigns have been taken into account. If a planning unit from one of these three commodity groups has four consecutive months with static consumption, it will be flagged in the QAT Problem List. - -- **Supply Plan does not follow minimum/maximum parameters** - -> If a planning unit is overstocked, understocked or stocked out at any point during the next 18 months, it will be flagged in the QAT Problem List. QAT will count the number of months the planning unit is **overstocked and understocked**, by subdividing it in two different time windows: those months within lead time (1-6 months) and those within the planning window (7-18 months). The QAT Problem List will also denote the number of shipments being received in the next 1-6 months and the next 7-18 months. **Stock-outs** will be flagged as a separate problem in the QAT Problem List. QAT will directly state which months are stocked out in the subdivided time periods of 1-6 months and 7-18 months. The QAT Problem List will also denote the number of shipments being received in the next 1-6 months and the next 7-18 months. -> -> **_Plan by MOS:_** Overstocked is defined by MOS \> Maximum MOS. Understocked is defined by MOS \< Minimum MOS. _See_ below for an example of a problem and the accompanying supply plan graph: - -![P2396#yIS1](/img/media/image205.png) - -Figure 127: Supply Plan does not follow min/max MOS parameter example - -> **\*Note:** If the MOS value for a given month is “N/A”, then all such instances are excluded while calculating the overstocked, understocked or stocked out problems.\* -> -> **Plan by Quantity Example**: Overstocked is defined by Ending Balance Quantity \> Maximum Quantity. Understocked is defined by Ending Balance Quantity \< Minimum Quantity. Note that QAT will only flag the overstock if this overstock occurs more than distribution lead time in a row (e.g. if lead time is 2 months, then QAT flags if there is an overstock more than 2 months in a row - but won’t flag the problem if the overstock every other month). _See_ below for an example of a problem and the accompanying supply plan graph: - -![P2403#yIS1](/img/media/image206.png) - -Figure 128: Supply Plan does not follow min/max quantity parameter example - -- **Other – Manual** - -> These are specific questions or clarifications manually entered by the supply plan reviewer that are not automatically flagged by QAT. These problems could be items that supply plan reviewer wants addressed that quarter before finalizing or a reminder for the next quarterly submission. The problem description, suggestion, and the criticality are determined by the supply plan reviewer. - -## Program Catalog - -**Purpose**: to view a standardized list of all the planning units and forecasting units in a QAT program and their corresponding attributes. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Program Catalog - -- **Notes:** A user may select all Planning Unit Categories and Tracer Categories, or they may choose a specific category for viewing. If a user would like to add a planning unit that does not appear in the Program Catalog Report, please refer to [Tickets for Adding/Updating Users and Master Data](02-getting-started.md#tickets-for-addingupdating-users-and-master-data). - -![P2414#yIS1](/img/media/image207.png) - -Figure 129: Program Catalog Report - -## Stock Status Reports - -### Stock Status Over Time - -**Purpose:** to compare one or more products and their inventory-levels across a period time - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Stock Status  Stock Status Over Time - -- **Notes:** The Planning Unit can be single, multi-select, or select all. The “Select All '' option may not be advantageous if the program has many planning units, as the graph will not be able to decern the individual lines on the graph. We suggest choosing less than ten products at once. Specifically, this report can be useful to compare categories. - -![A graph of a graph Description automatically generated with medium confidence](/img/media/image208.png) - -Figure 130: Stock Status Over Time Report - -### Stock Status Matrix - -**Purpose:** to provide a quick snapshot of the months of stock across time in an easy-to-read table format. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers and Program Users - -- **Navigation:** Reports  Stock Status  Stock Status Matrix - -- **Notes:** - - One row is shown for every planning unit & year combination, based on what’s selected in the top filters. - - - QAT will display the MOS or quantity for each planning unit based on whether the product is planned by quantity or MOS, as selected in the Update Planning Units screen (see Section 4.A2). - - - Colors corresponds to the stock levels during that particular month: - - Red – Stocked Out - - - Orange – Under Stocked - - - Green – Stocked to Plan - - - Yellow – Over Stocked - - - Grey – N/A (QAT is unable to calculate the value due to missing data) - - - Although the CSVs does not export the conditionally formatted colors, the PDF contains the colors and users may copy and paste the table to keep all the colors and formatting. - -![P2442#yIS1](/img/media/image209.png) - -Figure 131: Stock Status Snapshot Report - -### Stock Status Snapshot - -**Purpose:** to give a high-level view of a program’s stock status across planning units at a single point in time (one month). - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Stock Status  Stock Status Snapshot - -- **Notes:** - - The various color corresponds to the stock levels during that particular month: - - Red – Stocked Out - - - Orange – Under Stocked - - - Green – Stocked to Plan - - - Yellow – Over Stocked - - - Grey – N/A (QAT is unable to calculate the value due to missing data) - - - Although the PDF and CSV do not export the conditionally formatted colors, users may copy and paste the table to keep all the colors and formatting. - -![P2459#yIS1](/img/media/image210.png) - -Figure 132: Stock Status Snapshot Report - -### Stock Status Snapshot (Global) - -**Purpose:** to give a high-level view of a program’s stock status across planning units at a single point in time (one month) for multiple programs. - -- **Accessible to:** Realm Admins, Program Admins, Program Users, and Report Viewers - -- **Navigation:** Reports  Stock Status  Stock Status Snapshot (Global) - -- **Notes:** - - The various color corresponds to the stock levels during that particular month: - - Red – Stocked Out - - - Orange – Under Stocked - - - Green – Stocked to Plan - - - Yellow – Over Stocked - - - Although the PDF and CSV do not export the conditionally formatted colors, users may copy and paste the table to keep all the colors and formatting. - -![P2475#yIS1](/img/media/image211.png) - -Figure 133: Stock Status Snapshot (Global) Report - -## Consumption Reports - -### Consumption (Global) - -**Purpose:** to visually show the consumption of a planning unit or multiple planning units across countries. - -- **Accessible to:** Realm Admins, Program Admins, Program Users, and Report Viewers - -- **Navigation:** Reports  Consumption Reports  Consumption (Global) - -- **Notes:** - - The various colors stacked in the horizontal bars represent different countries. Users can determine which country by referencing the graph legend. - - - The x-axis corresponds to the consumption quantity (in millions) for each country. - -![P2487#yIS1](/img/media/image212.png) - -Figure 134: Consumption (Global) Report - -### Forecast Error (Monthly) - -**Purpose:** to visually show forecast accuracy using the weighted average percent error (WAPE) method, over time, while viewing the forecasted consumption against the actual consumption. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Consumption Reports  Forecast Error (Monthly) - -![A graph with red and blue bars Description automatically generated](/img/media/image213.png) - -> Figure 135: Forecast Error (Monthly) Report - -- **Notes:** - - In the graph, the red vertical bars represent the actual consumption, the blue vertical bars represents the forecasted consumption, the green line (which uses the right axis), represents the forecast error, and the turquoise dotted line represents the forecast error threshold (see Figure 115: Forecast Error (Monthly) Report). - - - The forecast error threshold (%) per planning unit is set by the Program Admin in the Update Planning Units screen. If a forecast error is above the set forecast error threshold (%), it will appear in red text in the data table. - - - The Report View can be viewed in multiple ways: - - **Forecasting unit.** A user may want to choose forecasting unit when comparing in base units, such as with medicines that have different bottle sizes (planning units) sharing the same forecasting unit (e.g. the antiretroviral TLD30 vs TLD90 - See Figure 116.) - - - **Equivalency Unit:** A user may want to choose forecasting unit when comparing products with different forecasting units, but some programmatic link (e.g. malaria treatments AL 6x1 vs 6x2 – see Figure 117.) - - - **“Show consumption adjusted for stock out?”:** If this checkbox is checked, QAT uses the adjusted actual consumption instead of the actual consumption. QAT calculates the total days in the month based on the calendar. - - - Missing Data: - - - > If data is missing for either forecasted or actual consumption, there will be a missing segment of the line or a missing bar in the graph - - - - > If there is missing data for actual or forecasted consumption, it will not be possible to calculate the forecast error and the user may see a gap in the line graph - - - - **Formula:** Forecast Error uses the Weighted Average Percent Error (WAPE) formula. The example below uses the time windows of 6 months. - - **Time Window:** For non-seasonal products with predictable consumption pattern, use a short time window, but consider using a longer time window for those products with a more variable consumption or those with seasonality (use a time window at least long enough to consider the entire season). - - - For more details on the logic QAT uses to calculate this report, see the “Show Formulae” in the tool. - -![P2508#yIS1](/img/media/image214.png) - -Figure 136: WAPE Formula with 6-month time window as example - -![A graph with red and blue bars Description automatically generated](/img/media/image215.png) - -> Figure 137: Forecast Error (Monthly) Report – displayed by forecasting unit - -![A screenshot of a graph Description automatically generated](/img/media/image216.png) - -> Figure 138: Forecast Error (Monthly) Report – displayed by equivalency unit - -### Forecast Error (by Planning Unit) - -**Purpose: **to assess forecast accuracy for selected products during a specific month across countries and programs. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Consumption Reports  Forecast Error (by Planning Unit) - -- **Notes:** - - For the time window, non-seasonal products with predictable consumption pattern can have a short time window, but those that have a more variable consumption/those with seasons should have a long-time window, or at least long enough to consider the entire season - - - In the table, the forecast error percentages that are above the forecast error threshold (%), set by a Program Admin in the Update Planning Units screen, will be highlighted red - - - If there is missing data for actual or forecasted consumption, it will not be possible to calculate the forecast error and the user will see an error message in the table. - - - Forecast Error uses the Weighted Average Percent Error (WAPE) formula: - -![P2529#yIS1](/img/media/image217.png) - -Figure 139: WAPE Formula - -![P2531#yIS1](/img/media/image218.png) - -Figure 140: Forecast Error (by Planning Unit) Report - -## Shipment Reports - -### Shipment (Global) - -**Purpose:** to aggregate procurement quantities by funding source, procurement agent, and procurement agent type across all countries and programs. - -- **Accessible to:** Realm Admins, Program Admins, Program Users, and Report Viewers - -- **Navigation:** Reports  Shipment Reports  Shipments (Global) - -- **Notes:** - - The two graphs that appear first in the Shipments (Global) Report depict the aggregated quantity of shipments per country and cost of the shipments (in USD) per funding source for a single planning unit. For a tabular view of the data, the user may find details in the bottom two tables. - - - If a country does not procure the selected planning unit, it will not appear in the graph of the tables in the report. - -![P2543#yIS1](/img/media/image219.png) - -Figure 141: Shipment (Global) Report - -### Shipment Overview - -**Purpose:** to aggregate procurement quantities by funding source or by procurement agent type across all countries and programs. - -- **Accessible to:** Realm Admins, Program Admins/Users, and Report Viewers - -- **Navigation:** Reports  Shipment Reports  Shipment Overview - -- **Notes:** - - Once navigating to the Shipment Overview screen, Users will see dropdowns in which they must fill out to show specific data. Once selecting certain dropdowns or all, users are shown a graph and a pie chart. The graph that appears first in the Shipments Overview Report depicts the aggregated quantity of shipments across countries and cost (in USD) of the shipments per funding source across planning units. The pie chat shows percentages of Funding Source depending on user selections while also being able to hover over to see the total amount (in USD). Users may also choose to group the data by Procurement Agent Type or Funding Source Type. For a tabular view of the data, the user may find details in the bottom table. - -![A screenshot of a computer Description automatically generated](/img/media/image220.png) - -Figure 142: Shipment Overview Report - -### Shipment Details - -**Purpose:** to provide a comprehensive view of all shipments for a program. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Shipment Reports  Shipment Details - -- **Notes:** - - The top graphs shows total USD per month by shipment status - - - There are two tables below the graph: the first one provides a summary and the second one provides detailed information on shipments. - - The summary table shows the total number of shipments, and total costs per funding source, for the selected time period. - - - The detailed table contains the shipments disaggregated by planning unit, etc. - -![](/img/media/image221.png) - -Figure 143: Shipment Details Report - -### Shipment Cost Details - -**Purpose:** to provide a simple view of all shipments for a program and their total costs. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Shipment Reports  Shipment Cost Details - -- **Notes:** - - Can be displayed by funding source, procurement agent, or planning unit. - -![P2574#yIS1](/img/media/image222.png) - -Figure 144: Shipment Cost Details Report - -### Shipment Cost Overview - -**Purpose:** to provide a general view of the total shipment costs per calendar year for a program and planning unit, by funding source. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Shipment Reports  Shipment Cost Overview - -- **Notes:** - - This report can be viewed in PDF or Excel (CSV) format - - - This report can be based on either the shipment receive date, or the shipment submitted date - -![A screenshot of a computer Description automatically generated](/img/media/image223.png) - -Figure 145: Shipment Cost Overview Report - -### Budget - -**Purpose:** to show the different budgets assigned to a program(s), the amounts allocated to shipments, the amount overspent (if applicable), and estimated amounts remaining. This program dropdown in this report is multi-select since multiple programs can share the same budget. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Shipment Reports  Budget - -- **Notes:** - - The graph shows every predefined Budget in a program and whether it is allocated to shipments (planned or ordered) and the remaining amount. - - - The tabular view of the graph also provides information on the funding source for each budget, start and end date, and other detailed information. - -![P2596#yIS1](/img/media/image224.png) - -Figure 146: Budget Report - -### Procurement Agent Lead Time - -**Purpose:** to show the detailed lead times (in months) for all planning units, by procurement agent. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Shipment Reports  Procurement Agent Lead Time - -![P2604#yIS1](/img/media/image225.png) - -Figure 147: Procurement Agent Lead Time Report - -## Inventory Reports - -### Expiries - -**Purpose:** to provide planners with estimated quantities of planning units expiring in the future based on batch/shelf life - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Inventory Reports  Expiries - -- **Notes:** - - This report pulls from data previously entered by including batch information on shipments, inventory, and actual consumption, and shelf life per planning unit. It displays the batch numbers, the receive date of the batch, shelf life of that batch (or planning unit), expiry date, and cost of the expired product. - - - The report can include quantities in planned shipments expected to arrive and expiry during the selected timeframe. - - - It will calculate (based on shelf life, stock projections, and forecast consumption) how much of a particular batch is expected to expire and when. - - For the expiry calculation, refer to [Annex 2: Business Rules](11-annex-2-business-rules.md#annex-2-business-rules) - - - The report will calculate a cost of expired product, based on the quantity expired and the planning unit default price set by the user in the Update Planning Units screen - - - The table is interactive. When the user clicks on the expired quantity, QAT will open a pop up with the batch ledger. - -![P2620#yIS1](/img/media/image226.png) - -Figure 148: Expiries Report - -### Cost of Inventory - -**Purpose**: for a selected month, provides an estimated cost of inventory based on actual or projected stock on hand and the planning unit catalog price. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Inventory Reports  Cost of Inventory - -- **Notes:** - - The report can include quantities in planned shipments expected to arrive during the selected timeframe - - - The stock column could be based on an actual inventory or projected ending balance - - - This report uses the following formula: - -![P2632#yIS1](/img/media/image227.png) - -Figure 149: Cost of Inventory Formula - -![P2635#yIS1](/img/media/image228.png) - -Figure 150: Cost of Inventory Report - -### Inventory Turns - -**Purpose:** to show the number of inventory turns per planning unit, program, country, or planning unit category at a particular point in time. Inventory turns are a way to measure the velocity of the supply plans. Inventory turnover is a key performance metric often used to signal supply chain management effectiveness. It is usually a backward looking metric, but because QAT uses forecast data to estimate stock projections into the future, the report can also be used to view estimated inventory turns based on the plans. Generally, higher turns mean a healthier supply chain – products are moving downstream and being replaced by fresh products more frequently. Low turnover implies low consumption, possibly excess inventory – it could point for instance to program targets being too ambitious. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Inventory Reports  Inventory Turns - -- **Notes:** - - This reports calculates inventory turns at various levels: at the individual planning unit level, at an aggregate level for an entire program (multiple planning units), and at an aggregate level for an entire country (multiple programs), or commodity category. - - - Planned Inventory turns: are the possible months of stock for each month over 12 months if the inventory rules worked perfectly considering the Planning Unit’s MIN and Reorder Interval. - - At the planning unit level, the report utilizes the MIN and Reorder Interval from Planning Unit Settings to calculate the “Planned” inventory turns. - - - At the program level (multiple planning units) QAT utilizes the mode of all planned inventory turns of all Planning units under a specific program. - - - At the country and/or Planning Unit Category level QAT utilizes the mode of all planned inventory turns of all Planning units under a specific country / PU Category - - - Actual inventory turns: - - At the planning unite level, QAT uses the following formula for each planning unit to calculate the actual inventory turns: - -![P2651#yIS1](/img/media/image229.png) - -Figure 151: Inventory Turns Formula at the planning unit level - -- For each planning unit, the report compares the actual and planned turns, and calculates the MAPE and MSE. - -- To calculate the actual inventory turns at the program level, QAT will look for the mode across all planning units in that program. If no mode can be found, QAT will use the average from all planning units as that program’s actual inventory turns. - -- To calculate the actual inventory turns at the country (or commodity category) level, QAT will look for the mode across all programs. If no mode can be found, QAT will use the average. - -![P2656#yIS1](/img/media/image230.png) - -Figure 152: Inventory Turns Report - -### Stock Adjustment - -**Purpose:** to show a list of all the manually entered stock adjustments in a program. Note: automatically calculated adjustments will not display on this report. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Inventory Reports  Stock Adjustment - -- **Notes:** - - Automatically calculated adjustments (as a result of a difference between projected ending balance and an inventory count) do not appear in this report. - -![P2666#yIS1](/img/media/image231.png) - -Figure 153: Stock Adjustment Report - -### Warehouse Capacity (by Program) - -**Purpose:** displays the volume (in cubic meters) of all regions within a country (if a user enters such information upon setting up a program. - -- **Accessible to:** Realm Admins, Program Admins, Report Viewers, and Program Users - -- **Navigation:** Reports  Inventory Reports  Warehouse Capacity (by Program) - -- **Notes:** - - This report is most useful for those countries with multiple regions. - -![P2676#yIS1](/img/media/image232.png) - -Figure 154: Warehouse Capacity (by Program) - -### Warehouse Capacity (by Country) - -**Purpose:** displays the volume (in cubic meters) of all countries and regions within a country (realm-level access required). - -- **Accessible to:** Realm Admins and Report Viewers - -- **Navigation:** Reports à Inventory Reports à Warehouse Capacity (by Country) - -- **Notes:** - - This report is most useful for those countries with multiple regions. - -![P2686#yIS1](/img/media/image233.png) - -Figure 155: Warehouse Capacity (by Country) diff --git a/docs/user/07-forecasting-module-program-data.md b/docs/user/07-forecasting-module-program-data.md deleted file mode 100644 index 5b356c4..0000000 --- a/docs/user/07-forecasting-module-program-data.md +++ /dev/null @@ -1,147 +0,0 @@ ---- -id: forecasting-module-program-data -title: "Forecasting Module: Program Data" -sidebar_label: "Forecasting Module: Program Data" -sidebar_position: 7 ---- - -# Forecasting Module: Program Data - -## Introduction - -![](/img/media/image234.png)A forecast is an estimate/prediction of the quantities of products to be consumed/utilized by clients or consumers over a future period of time. In QAT, the forecast process is generally conducted in a specific order (see _Figure to the right_). - -First, set up a program using Update Program Info or select a previous program using Download or Delete Program. After downloading the program, add information on the forecast period, threshold (%), products, and other program settings in the Update Version Settings and Updating Planning Unit screens. In QAT, users can either create forecasts by designing forecasting trees (tree-based forecast) or by leveraging historical consumption (consumption-based forecast) to reach a final forecast. For each product, choose consumption or tree methodology, or both\! - -**Consumption-based forecasts** are most useful in mature, stable programs that have a full supply of products and reliable data. This method can be the most reliable predictor of future consumption if future use is predicted to be very similar to the past. Ideally, 24+ months of monthly actual consumption data is available. If the necessary data for a consumption-based forecast is not available or not helpful in predicting future consumption, conduct a **tree-based forecast**, which flexibly accommodates all other forecast methods, such as morbidity, services, and demographic methods. Users can specify changes over time in a tree, either by directly specifying the rate of change or extrapolating from past data. - -Once the various forecasts have been created, users can navigate to the Forecast Analysis and Outputs section to view and compare forecasts, and select the final forecast. - -## Program Information - -**Purpose:** Enables users to update their basic program information after initial creation. - -**Using this screen:** - -_Program Admins_ can use the main screen to: - -- Update Forecast Program Name, Program Manager, and the Notes field. Program Admins can also choose to disable or activate a program in this screen. For changes relating to the technical area, organization, or program display name, Program Admins must request the change from a Realm Admin through the [QAT Helpdesk System.](02-getting-started.md#qat-helpdesk-and-tickets) - -_Realm Admins_ can use the main screen to: - -- Update the Technical Area, Organization, Forecast Program Name, Program Display Name, Program Manager, and the Notes field. Realm Admins can also choose to disable or activate a program in this screen. - -## Version Settings - -![P2710#yIS1](/img/media/image235.png) - -**\*Purpose**: Enables users to update their program settings and view details about previous versions. For viewing forecast results, use the screens in the [Forecast Analysis Output](09-forecasting-module-reports-and-outputs.md#forecasting-module-reports-and-outputs) section.\* - -**\*Using this screen**:\* - -_Note: A forecast program must be downloaded to update version settings. All past versions of each forecast program will be in a read-only format; only the local version is available for updating and editing._ - -On this screen, users can: - -1. Update the following program settings for the downloaded, local program: - 1. **Version Notes** – a free form editable text field that allows users a place to provide general notes about a particular forecast version. It is also visible and editable when uploading a program. - - 2. **Date Uploaded/Uploaded by User** – denotes the user that uploaded each version of the forecast to the server and on what date. Useful for understanding the lifecycle of each program. - - 3. **Forecast Start, Forecast Period (Months), and Forecast End** – based on the start & end date, QAT will automatically calculate the forecast period in months. Alternatively, users can choose to enter a forecast start date and number of months in the forecast period, and QAT will automatically calculate the forecast end date. - - 4. **\# Of Days in Month** – used in consumption-based forecasts for adjusting actual consumption against the number of days stocked out. A user can choose anywhere from 15 to 31 days; however, QAT will default to “calendar days.” This field could be useful if a facility only wants to use business days (\~20 days) to calculate the stockout rate. - -> ![P2723#yIS1](/img/media/image236.png) - -5. **Freight percentage** – used in forecasting output screens and reports for estimating total procurement costs. This field is not mandatory and can be updated at any time. - - - -1. **Forecast Threshold** – this metric is used in the Compare and Select screen. QAT compares available Consumption Forecasts and Tree Forecasts. For any Tree Forecasts, QAT will flag the percentage above the highest or below the lowest Consumption Forecast. The comparison will be highlighted in red text if it is outside of the threshold percentages set by the user in this screen. Assuming reliable actual consumption data, this comparison helps users determine if their Tree Forecasts are realistic. These two fields, high and low, are not mandatory and can be updated at any time. - - - -2. See a historical lifecycle of each program through all its versions. - 1. View all version settings above - - 2. (Right click) View the [Forecast Validation](03-managing-programs-and-versions.md#upload) screen (same screen as viewed during the Upload process) – which lists missing forecasts, missing data and all notes. This serves as an easy for users to understand previous forecasts without downloading them. Use the [Monthly Forecast](09-forecasting-module-reports-and-outputs.md#monthly-forecast), [Forecast Summary](09-forecasting-module-reports-and-outputs.md#forecast-summary) or [Version Comparison](03-managing-programs-and-versions.md#version-comparison) screens to view the forecast outputs from other versions. - -## Planning Units - -**\*Purpose**: Enables users to add and update planning units and the associated planning unit settings that will be used in their forecasts and for calculation in the forecast output screens.\* - -**Using this screen**: - -_Note: A forecast program must be downloaded to add or update planning units and their settings._ - -1. **\*Add Planning Units** – Users will need to add any planning units in this screen that they would like to forecast. Planning Units can be added manually or copied and pasted from the Supply Planning module ‘Update Planning Unit’ screen, if the planning unit have already been added to a user’s supply plan.\* - -2. **\*Update Planning Unit Settings** – Users can also use this screen to update any planning units and their associated settings. Users should always Master Data Sync after updating any setting in order to see the changes take place in other forecasting module screens. Planning Unit settings and brief explanations is as follows:\* - -| Column Name | Description | Used Where? | -| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | -| **Conversion Factor (FU:PU)** | A non-editable field providing information on the conversion factor between the chosen PU and it’s associated FU. | Select screens (Data Entry & Adjustment, Compare & Select, Monthly Forecast) allow data entry/viewing in PU or FU | -| **Consumption Forecast?** | For each PU, users can choose one or both methods. If the forecast type is checked for the PU, it will appear in the Consumption and Tree screens. | Building your forecasts and then analyzing in the Compare & Select screen | -| **Tree Forecast?** | | | -| **Stock on Hand** _(start of forecast period)_ | The actual or projected stock (quantity) at the beginning of your forecast period. Users can utilize the supply planning module to determine the SOH, if desired. | Forecast Summary to calculate the procurement gap | -| **Existing Shipments** _(forecast period)_ | Total existing shipment quantity during the forecast period. Users can utilize the supply planning module to determine the existing shipment quantity (_it is recommended to not include planned shipment quantities unless there is a high likelihood of ordering)_. | | -| **Desired Months of Stock** _(end of forecast period)_ | The MOS you wish to have at the end of your forecast. | | -| **Price Type** | Choose a specific procurement agent or “Custom.” | Forecast Summary to calculate the cost of the procurement gap | -| **Unit Price** | Auto-filled based on procurement agent or manually entered by a user. | | - -Table 9: Forecasting Module Planning Unit Settings - -## Equivalency Units - -**Purpose**: Enable users manage Equivalency Units. Equivalency Units (EUs) allow users to aggregate data across products that are different, but related. They allow users to group multiple forecasting units for aggregation in the [Reports and Outputs](09-forecasting-module-reports-and-outputs.md#forecasting-module-reports-and-outputs). - -**Using this screen:** - -**Mapping equivalency units to forecasting units** - -Use the main screen to manage mappings between equivalency units and forecasting units. Realm-level mappings are available to all users and are indicated by Program "Realm Level." However, program admins can create program-specific mappings (by adding a row and tagging it to a specific EU). If there are any conflicts, program-specific mappings will take precedence and be used instead of realm-level mappings. - -For example, a user is forecasting medicines to treat QATitis, a condition where people cannot stop using QAT. The user may forecast by different treatments (different forecasting units) but want to see how they are aggregated together. For the example below, a patient would need 14 tablets of FASPicillin, or 1 tube of FASPasone (cream), or 0.5 vials of FASPicaine, or 2 bars of chocolate to treat QATitis. Thus, if different patients are undergoing different treatments, a user can aggregate these different treatments by creating/using an Equivalency Unit (EU). - -| **Equivalency Unit** | **Forecasting Unit** | **Conversion to EU** | **Average Treatment required to cure QATitis** | -| ----------------------- | ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| 1 Treatment for QATitis | 1 tablet of FASPicillin | 14 | 1 tablet a day for 2 weeks | -| 1 Treatment for QATitis | 5mL tube of FASPasone (cream) | 1 | 0.5mL/day applied on the forehead over 10 days (1 tube total) | -| 1 Treatment for QATitis | 2mL vial of FASPicaine (injection) | 0.5 | One injection of 1mL (Two people can share one vial) | -| 1 Treatment for QATitis | 1 bar of white chocolate | 2 | 2 bars of chocolate. The type of chocolate does not matter, as all chocolate contains the natural form of FASPicillin. | -| 1 Treatment for QATitis | 1 bar of dark chocolate | 2 | | -| 1 Treatment for QATitis | 1 bar of milk chocolate | 2 | | - -Table 10: EU Example - Treatment for QATitis - -**Steps to creating and managing equivalency units** - -1. A user should first check to see if the EU exists already in the QAT Master Data by navigating to “Realm Masters” à “Equivalency Units.” - -2. If the EU does not exist, click on “Manage Equivalency Unit” then “Add Row” and users can input the EU they would like to utilize for their specific program throughout QAT. This EU will be program-specific and will not be available to other programs. If there is an EU that would benefit the QAT community, users can request it via the [QAT Ticketing Helpdesk System](02-getting-started.md#tickets-for-addingupdating-users-and-master-data). - -> ![P2819#yIS1](/img/media/image237.png) - -3. If the EU exists and a user would like to map forecasting units to the existing EU, they can click “Add Row” on the main screen and map the forecasting unit to the program-level EU. If a user would like to map the forecasting unit to an existing _realm-level_ EU and thinks it would benefit the QAT community, users can request it via the [QAT Ticketing Helpdesk System](02-getting-started.md#tickets-for-addingupdating-users-and-master-data). - -> ![P2821#yIS1](/img/media/image238.png) - -4. Users can also edit program-specific EUs on the main screen as well. - -5. User must click “Submit” when they have finished editing and Master Data Sync, in order to see the EU available from the dropdowns in the Reports and Outputs screens. - -**Where are equivalency units used?** - -- In the Forecasting Module ‘Compare and Select’ screen, the user can display their forecasts in EUs. Using the example above, a user that forecasts 10,000 bars of dark chocolate per month, could elect to display their forecast in the EU of “Treatments for QATitis” and display their forecast as 5,000 “Treatments for QATitis” per month instead. - -- In the Forecasting Module ‘Monthly Forecast’ screen, the user can display their selected forecasts by individual planning units, or aggregate across planning units if they are connected by EUs. For example, if a user forecasted 10,000 bars of dark chocolate, and 10,000 bars of white chocolate and 14,000 per month, QAT would display 7,000 “Treatments for QATitis”. - -- In the Supply Planning Module ‘Forecast Error (Monthly) Report’ screen, users can also view the actual and forecasted consumption in Equivalency Units. - -| **Forecast** | **Equivalent in “Treatments for QATitis”** | -| ------------------------------ | ------------------------------------------ | -| 10,000 bars of dark chocolate | 5,000 | -| 10,000 bars of white chocolate | 5,000 | -| 14,000 tablets of FASPicillin | 1,000 | -| **Total** | **7,000** | diff --git a/docs/user/07-supply-planning-module-program-data.md b/docs/user/07-supply-planning-module-program-data.md new file mode 100644 index 0000000..50d228e --- /dev/null +++ b/docs/user/07-supply-planning-module-program-data.md @@ -0,0 +1,430 @@ +--- +id: supply-planning-module-program-data +title: "Supply Planning Module: Program Data" +sidebar_label: "Supply Planning Module: Program Data" +sidebar_position: 7 +--- + +# Supply Planning Module: Program Data + +In QAT, a **Program** is the primary unit of supply planning, typically corresponding to a country's technical area (e.g., Malaria, HIV). Programs are governed by realm-level master data, ensuring consistency across the system. + +Data management at the program level is primarily handled by **Program Admins** and **Program Users**. For more details on roles, see [Annex 3: User Role Matrix](15-annex-3-user-role-matrix.md). + +### Data Categories + +| Category | Data Type | Examples | +| :--- | :--- | :--- | +| **Background Data** | Program Info | Lead times, freight %, program managers. | +| | Product Info | Planning units, reorder intervals, min/max stock. | +| | Budget | Funding sources, budget amounts, valid dates. | +| **Transactional Data**| Consumption | Actual and forecasted consumption. | +| | Inventory | Stock counts and adjustments (damages, expiries). | +| | Shipments | Quantities, delivery dates, procurement agents. | + +*Table 1: Program Data Hierarchy* + +## Background Data + +> [!TIP] +> Background data must be updated while online. Perform a **Master Data Sync** after updates to ensure changes are reflected across the application. + +### Program Information +Program Admins can define general parameters such as program managers, lead times, and default freight percentages. + +**To update program info:** +1. Navigate to **Program Management** > **Update Program Info**. +2. Select the target program. +3. Modify fields as needed and click **Submit**. +4. (Optional) Add/remove procurement agents and funding sources from the program-specific lists. + +![Update Program Info Interface](/img/media/image113.png) +*Figure 1: Program Information Management* + +### Planning Units +Planning units are the specific products used for procurement and inventory tracking. While the master catalog is managed at the realm level, Program Admins manage which units are active within their specific programs. + +**Key Parameters:** +- **Plan By:** Choose "MOS" (Months of Stock) for high-volume items or "Quantity" for low-volume/emergency items. +- **Reorder Interval:** Frequency of shipments (in months). +- **Min Months of Stock (MOS):** The safety stock level required to prevent stockouts. +- **Shelf Life:** Average months from receipt until expiry. +- **Forecast Error Threshold:** Used to flag high discrepancies in consumption reports. + +**To manage planning units:** +1. Go to **Program Management** > **Update Planning Units**. +2. Select your program. +3. **To Edit:** Double-click any cell (e.g., Min MOS, Shelf Life) and click **Submit**. +4. **To Add:** Click **Add Row**, search for the planning unit by name, fill in the parameters, and click **Submit**. + +> [!NOTE] +> If a planning unit is missing from the catalog, submit a ticket via the [QAT Helpdesk](05-getting-started.md#qat-helpdesk-and-tickets). + +### Program/Procurement Agent-specific Information +Users can override default lead times, freight costs, and unit prices for specific procurement agents and planning units. + +**Key Roles and Rules:** +- **Prioritization:** Specific agent/unit settings override program settings, which override realm-level defaults. +- **Constraints:** Only one row is allowed per program/unit/agent combination. +- **Mandatory Fields:** Program, Planning Unit, and Procurement Agent are required to add a row. + +**To add or edit specific info:** +1. Navigate to **Program Management** > **Program/Procurement Agent Info**. +2. Select the program and planning unit. +3. Fill in the specific Lead Times, Freight %, or Unit Prices. +4. Click **Submit** and perform a **Master Data Sync**. + +![Procurement Agent Info Interface](/img/media/image117.png) +*Figure 2: Specific Procurement Agent Settings* + +### Alternate Reporting Units (ARU) +An ARU allows data entry in units different from the standard planning unit (e.g., pieces vs. packs). + +**Rules:** +- **Conversion Factor:** Must be defined to convert ARU to Planning Unit (e.g., multiply by 10). +- **Automation:** QAT automatically creates a 1:1 ARU for every planning unit added. + +**To manage ARUs:** +1. Go to **Program Management** > **Alternate Reporting Unit**. +2. Select the program. +3. Click **Add Row** to create a new ARU, define the conversion factor, and click **Submit**. + +![ARU Interface](/img/media/image118.png) +*Figure 3: Alternate Reporting Units* + +### Lead Times +Lead times track shipment progression across six statuses. The system prioritizes lead times as follows: **Program/Agent Specific** > **Program Defaults** > **Realm Defaults**. + +#### Lead Time Definitions + +| Stage | Definition | Configuration Level | +| :--- | :--- | :--- | +| **Planned to Submitted** | Identifying need to placing order. | Program | +| **Submitted to Approved** | Order placement to approval. | Program (Default) / Realm (Agent) | +| **Approved to Shipped** | Approval to dispatch. | Program (Default) / Realm (Agent) | +| **Shipped to Arrived** | Transit time (Air, Sea, or Road). | Program | +| **Arrived to Received** | Arrival at port to warehouse receipt. | Program | + +**To update lead times:** +1. Navigate to **Program Management** > **Update Program Info**. +2. Scroll to the lead time fields and enter values in months. +3. Click **Update**. + +For local procurement, the entire lead time (Planned to Received) is managed per planning unit in **Update Planning Units**. + +![Shipment Status Flow](/img/media/image120.png) +*Figure 4: Shipment Lead Time Lifecycle* + +### Budgets +Budgets track capital allocation for purchasing commodities. A budget can be linked to one or multiple programs. + +- **Status Alert:** Budgets highlighted in **Red** indicate that the end date has passed or the used amount exceeds the budget. +- **Rules:** Shipments tagged to a budget must be un-tagged before delinking the program from that budget. + +**To add a budget:** +1. Navigate to **Program Management** > **Budget**. +2. Click the **+** (Add) icon. +3. Enter the Funding Source, Budget Name, and amounts. +4. Click **Submit**. + +**To update a budget:** +1. Select the budget from the list. +2. Modify details in the **Update Budget** screen and click **Submit**. + +![Budget Management Screen](/img/media/image123.png) +*Figure 5: Budget Overview* + +## Transactional Supply Plan Data +Transactional data includes the "Big 3": **Consumption**, **Inventory**, and **Shipments**. + +### Consumption Data +Consumption refers to stock dispensed to clients. +- **Actual Consumption:** Reported quantity dispensed. +- **Forecasted Consumption:** Predicted quantity agreed upon by the program. + +**To add/update consumption:** +1. Navigate to **Supply Plan Data** > **Consumption Data**. +2. Select the report period and planning unit. +3. **Add:** Click **+ Add row** or right-click a cell and select **Add new consumption**. +4. **Update:** Double-click a cell to edit. + +> [!WARNING] +> Historical data (more than 9 months in the past) is read-only and cannot be edited. + +**Batch Details (Actual Consumption Only):** +1. Right-click an "Actual Consumption" row and select **Show Batch Information**. +2. Edit batch numbers or quantities. The total batch quantity must exactly match the total consumption quantity. + +![Consumption Data Entry](/img/media/image125.png) +*Figure 6: Consumption Management* + +### Inventory Data +Inventory data includes **Stock Counts** and **Adjustments** (e.g., damages, transfers). + +- **Stock Count:** Physical inventory on a specific date. +- **Adjustments:** Modifications to usable inventory (notes are required for all adjustments). + +**To add/update inventory:** +1. Navigate to **Supply Plan Data** > **Inventory Data**. +2. Select the **Inventory Type** (Inventory or Adjustment). +3. **Add:** Click **+ Add row** and enter details. +4. **Update:** Double-click cells to edit. + +> [!IMPORTANT] +> Like consumption, inventory and adjustment records more than 9 months in the past cannot be edited. + +**Batch Details:** +- **Adjustments:** Right-click a row and select **Show Batch Information**. QAT uses "Best Case Scenario" logic to handle batch quantities if not explicitly provided. +- **Inventory:** Batch details are managed within the Supply Planning screen (see [Section 5.E](08-supply-planning-module-supply-planning.md#supply-planning-project-expired-stock-and-batch-information)). + +![Inventory Data Entry](/img/media/image127.png) +*Figure 7: Inventory Management* + +### Shipment Data +Shipments are tracked from planning to receipt. + +**To add/update shipments:** +1. Navigate to **Supply Plan Data** > **Shipment Data**. +2. Select filters and click **+ Add row**. +3. Fill in required fields (highlighted in **Yellow**). +4. **Strategic Order Calculator:** For strategic products, double-click the **Order Quantity** cell to use the calculator for MOQ or pallet-based rounding. +5. **Batch Details:** Right-click a shipment and select **Show Batch Information** to manage expiry dates and quantities. + +**Key Shipment Rules:** +- **Emergency Shipments:** Rows in **Red** indicate the receive date is within the lead time. +- **Freight Cost:** Automatically calculated based on `Cost * Freight %` unless manually overridden. +- **Shipment Dates:** Right-click a shipment and select **Show shipment dates** to compare Estimated vs. Actual milestones. + +![Shipment Management](/img/media/image131.png) +*Figure 8: Strategic Order Calculator* + +### ERP Shipment Linking +ERP linking allows planners to sync QAT shipments with a procurement agent's ERP system (e.g., GHSC-PSM's ARTMIS). This automates updates for status, costs, and dates. + +**Rules for Linking:** +- **Status:** QAT shipments must not be "Planned," "Cancelled," or "Suggested." +- **Recency:** "Received" shipments must be from within the last 6 months. +- **Agent:** Currently supported only for **GHSC-PSM**. +- **Mode:** Only editable in downloaded local versions. + +#### Linking Screens +1. **Not Linked (QAT):** Link existing QAT shipments to ERP orders. Select a shipment, search for the ERP order, and define the conversion factor. +2. **Not Linked (ERP):** Link ERP orders to QAT. You can select an existing QAT shipment or create a new one directly from this screen. +3. **Linked:** View all currently synced shipments, update conversion factors, or de-link orders. + +**To link an ERP shipment:** +1. Navigate to **Supply Plan Data** > **Link ERP Shipments**. +2. Select the **Not Linked (QAT)** or **Not Linked (ERP)** tab. +3. Choose the program/planning unit. +4. Click a row to open the search/link window. +5. Provide the **Alternate Reporting Unit (ARU)** to set the conversion factor. +6. Click **Link Shipment**. + +![ERP Linking Screens](/img/media/image133.png) +*Figure 9: ERP Linking Overview* + +#### ERP Notifications +Planners will receive alerts in the **ERP Shipment Notifications** screen if there are discrepancies between QAT and the ERP system (e.g., cancelled orders, quantity changes, or SKU updates). + +1. Select the radio button at the top labeled ‘Linked’. + +2. Select the program and planning unit(s) you want to see the list of linked shipments for. Once selected, a list of shipments will appear. The information in these shipments is being pulled in from the ERP. + +3. To make any of the updates listed in step 2, left click on a single shipment. + 1. To edit ARU and/or notes, double-click on the cell and type or select from dropdown. + + 2. To de-link an ERP order, uncheck the box in the ‘Link?’ column. + + 3. To add an ERP order, check the box for that order under ‘Link?’ column. The user can clear the search dropdowns in the middle section to look up a differe planning unit or order number and the originally linked orders will remain linked. + +4. Users will have the ability to also view order history details from the ERP. To do so, from the original ‘Linked’ screen, right-click on a single shipment and click ‘View ERP Order History’. A pop-up window will appear labeled ‘ERP Order History’. This screen will show any details that have changed over time in the ERP order. Each row indicates that one or more of the columns has changed. The furthest column on the right labeled ‘Data Received On’ is when the record was received by QAT. + 1. To view batch details, click on the![](/img/media/image137.png) icon. + + 2. **Note:** Certain fields from the ERP are not captured on this screen so there may be some instances where 1 or more rows have the same details. This means that a column in the backend was changed. + +> **Once you have linked QAT shipments with ERP orders, the data will reflect in your supply plan without having to master data sync.** The newly linked ERP data will reflect in the local reports, supply planning screen as well as the shipment data entry screen. The user **does** need to upload a version to the server in order for other users to see these changes. +> +> To view the ERP-linked shipments in the shipment data entry screen, the user must select ‘ERP-linked shipments’ from the Shipment Type dropdown. The user can either display only this option or combine it with the manual shipments to show all shipments. The ERP-linked shipments will be greyed out to indicate that they are non-editable. + +![P1723#yIS1](/img/media/image138.png) + +Figure 88: View ERP Shipments in Data Entry + +In the supply planning screen, ERP-linked shipments will have a link icon in the top left of the cell. The user can click into a specific shipment to view the details but those cells will also be greyed out to indicate that they are non-editable. The user can still right click on the shipment details,however, to view the shipment dates and batch information. + +![P1727#yIS1](/img/media/image139.png) + +Figure 89: View ERP Shipments in Supply Plan + +**ERP Shipment Notifications** + +The purpose of the ‘ERP Shipment Notifications’ screen is to alert supply planners of any key changes made to ERP linked shipments, such as an order being cancelled or a product SKU changing. Supply planners will be encouraged to ‘address’ each of the notifications to confirm that they are aware of the change and the implications made on the supply plan. For product changes, the user will re-confirm the conversion factor, whether it changes or not. + +![](/img/media/image140.png) + +At the top of the screen, there is a icon. This icon will display a red number indicating how many non-addressed notifications are in the ERP shipment notifications screen. If there is no red number, that means there are none. + +To get to the ‘ERP Shipment Notifications’ screen, either click on the truck icon at the top of QAT or select ‘ERP Shipment Notifications’ under ‘Supply Plan Data’ in the left sidebar menu. + +To view the notifications, the user will need to select from the 3 dropdowns (Program, Planning Unit, Addressed). The user also has the option to select directly from the table above the dropdowns. When a user left clicks on a row in the table, the 3 dropdowns will atomically populate based on the program that user selected. The planning unit dropdown will populate to all planning units and the addressed dropdown will select ‘Not Addressed’. + +![P1739#yIS1](/img/media/image141.png) + +Figure 90: ERP Shipment Notifications Filtering + +To address a notification, the user must check the box in the ‘Addressed?’ column and then hit the ‘Submit’ button. If the user is addressing an ERP Product Change notification, he/she must first enter the conversion factor. The conversion factor field is not editable until the addressed box is checked. + +Just like in the ‘Linked’ screen, the user can view ERP order history. To do so, right-click on the notification row and click ‘View ERP Order History’. Refer to the Linked Screen section for more information. + +## Importing Data for Supply Planning + +### Supply Plan Data Excel Import Templates + +Consumption, Inventory and Shipment data can be entered through QAT’s data entry screens, through the Supply Planning screen or through Quantimed Import (forecasted consumption only). QAT also provides users with the ability to input this data directly from Microsoft Excel. This method of data entry is intended for bulk entries that have a lot of data. The steps below will show how to input data from Excel into QAT: + +1. From the menu sidebar, go to “Supply Plan Data” and click the type of data you want to enter (e.g. “Consumption Data”). ![P1748L76#yIS1](/img/media/image142.png) + +2. ![](/img/media/image143.png)Once on the data entry screen, go to the top right corner and click “Download Template”. + +3. A Microsoft Excel file will be downloaded directly to your computer’s ‘**Downloads’** folder. + +4. Proceed to your computer’s Downloads folder and open the Excel file. The name format should be **ConsumptionDataEntryTemplate.xlsx** with the first portion dependent on the type of data you are entering. + 1. _Each of the four data types (Inventory, Adjustment, Consumption and Shipment) have their own Excel template so it is important that you click on “Download Template” from the proper screen. For inventory and adjustment, make sure the drop-down menu has selected the type of data you want the template for._ + +5. Once in the Excel template, click “Enable Editing” at the top if it prompts you to. + +![P1755#yIS1](/img/media/image144.png) + +Figure 91: Enable Editing + +6. Enter data for all of the required fields. + 1. Any cell highlighted in grey (e.g. Conversion Factor) is non-editable and does not need to be filled in. + + 2. Certain fields (e.g. Data Source) will have drop down menus pre-populated from QAT. Therefore, it is important to download a new template if it has been a while since the last time the user used the template. + + 3. Certain fields have built in data validations (e.g. letters cannot be entered in cost cells). If the validation is not met, a pop-up error message will appear. + +![P1762#yIS1](/img/media/image145.png) + +Figure 92: Excel Template + +7. Once all the data is entered in the Excel template, re-open QAT window. + +8. Go to the Data Entry screen (Consumption, Inventory, Adjustment, Shipment). + +9. Click the blue “+Add Row” button at the bottom. + 1. **Note:** You only need to add 1 row in QAT regardless of how many rows there are in the Excel template. + +10. In the Excel template, select all data and press Ctrl + C on your keyboard to copy the data. + +11. Go to the added row in QAT, left click on the far most left cell in that row and press Ctrl + V on your keyboard to paste the data. + +12. QAT will automatically create new rows for the data being imported from Excel. + +13. Click “Submit”. + +### Quantimed Forecast Import + +![](/img/media/image146.png)Quantimed is a software designed to facilitate the process of determining the quantities of medicines and medical supplies required for a health program. The output of Quantimed is a health programs’ forecasted consumption data. That forecasted consumption data can be a key input into QAT user’s supply plans. QAT allows users to import Quantimed forecasts into QAT to include in their supply plan. + +**Step 1: Import Quantimed Data into QAT** + +1. Go to “Supply Plan Data” on the sidebar menu + +2. Selected “Quantimed Import” + +3. **Import Quantimed Data File** + 1. Choose the Quantimed .xml forecast file from your local computer system. + + 2. Select the QAT program that you want the Quantimed data to import into. + + 3. Click on “Import”. + +![P1783#yIS1](/img/media/image147.png) + +Figure 93: Quantimed File Import + +**Step 2: Map Planning Units** + +1. > To map a Quantimed product to a QAT planning unit, select the QAT planning unit using the drop-down menu. + +2. > If you do not want to import a specific Quantimed product, select the “Do Not Import” option for that row. + +3. > If there is not a QAT planning unit associated with the Quantimed product, the dropdown will show “Planning Unit Not Found”. You will either need to manually select a planning unit from the dropdown or go back to the program and add a planning unit for that Quantimed product before proceeding. You cannot click “Next” one or more of the cells says “Planning Unit Not Found”. + 1. > **Note**: to minimize instances where a planning unit is not found, it is recommended that Quantimed users select products from the GHSC-PSM product catalog .xml file. + +4. > Once very row has a planning unit selected or says “Do not import”, click “Next” at the bottom of the screen. + +![P1794#yIS1](/img/media/image148.png) + +Figure 94: Map Planning Units + +**Step 3: Region** + +1. > In this step select the region that you want to import the forecasted consumption data into. If there is only one region, you must select that region to proceed. + +2. > Then, input the percentage of that consumption data that you want to import into QAT. This percentage must range from 0-100% and will apply to all the planning units previously selected. + +3. > Click “Next”. + +**Step 4: Consumption Month** + +1. > Select the date range for the Quantimed data that you want to import into QAT. + 1. > The period you select is the period of data that you will be able to import and will apply to all planning units previously selected. + +2. > Click “Next”. + +![P1806#yIS1](/img/media/image149.png) + +Figure 95: Consumption Month Screen + +**Step 5: Import Data** + +1. > The final step is to confirm the data that will be imported from Quantimed into QAT based on what was entered in steps 1-4. + 1. > “Quantimed Forecasted Consumption” is the amount that is being pulled in from Quantimed for the associated product and month-year. + + 2. > “Converted Quantimed Forecasted Consumption” is the amount that will be pulled into QAT for the associated product and month-year after applying the import percentage and conversion factor. + + 3. > “Current QAT Forecasted Consumption” is the forecasted consumption amount currently in QAT for that planning unit and month-year. Once you import the Quantimed data, this amount will be overwritten by the “Converted Quantimed Forecasted Consumption” amount. + +2. > This screen will show all the data that will be imported into QAT. If you do not want to import certain records, click on the checkbox in the ‘Import?’ column on the far right. This will prevent QAT from importing the Quantimed data and will keep the current QAT forecasted consumption for that planning unit and month-year. + +3. > Click “Submit” to import the data. + +![P1816#yIS1](/img/media/image150.png) + +Figure 96: Confirm Data Import Screen + +### QAT Forecast Import + +### Importing Forecasts into Supply Plans +Planners can import QAT-created forecasts into their supply plan programs to drive procurement needs. + +**Prerequisites:** +- The forecast must be uploaded as a **Final** version. +- A forecast must be selected for each planning unit. + +**To import a forecast:** +1. Navigate to **Supply Plan Data** > **Import Forecast into Supply Plan**. +2. Select the **Source Forecast Program** and **Target Supply Plan Program** (local versions only). +3. Select the date range for import. +4. **Map Planning Units:** Map forecasting planning units to supply plan units. Set a conversion factor if packaging differs. Use "Do not import" for units you wish to exclude. +5. **Map Regions:** Define the percentage of the forecast to allocate to each supply plan region (e.g., 100% National to National, or split 50/50 between two regions). + +![Forecast Import Screen](/img/media/image151.png) +*Figure 10: Mapping Forecast Data to Supply Plans* + +#### Rounding and Residuals +Since supply planning requires whole numbers, QAT rounds forecasted consumption down to the nearest whole number. To prevent data loss, "residuals" (remainders) are carried over and summed across months. Once the cumulative residual reaches 1.0, it is added to the current month's imported quantity. + +**Example:** +| Month | Converted Forecast | Cumulative Total | Rounded Import | Residual | +| :--- | :---: | :---: | :---: | :---: | +| Jan | 0.25 | 0.25 | 0 | 0.25 | +| Feb | 0.25 | 0.50 | 0 | 0.50 | +| Mar | 0.25 | 0.75 | 0 | 0.75 | +| Apr | 0.25 | 1.00 | 1 | 0.00 | + +*Table 2: Demonstration of the Residual Rounding Logic* + +6. Review the final conversion list and click **Import** to finalize. diff --git a/docs/user/08-forecasting-module-forecasting.md b/docs/user/08-forecasting-module-forecasting.md deleted file mode 100644 index 4cc384d..0000000 --- a/docs/user/08-forecasting-module-forecasting.md +++ /dev/null @@ -1,1975 +0,0 @@ ---- -id: forecasting-module-forecasting -title: "Forecasting Module: Forecasting" -sidebar_label: "Forecasting Module: Forecasting" -sidebar_position: 8 ---- - -# Forecasting Module: Forecasting - -## Consumption Forecasts - -Consumption-based forecasts, which are based on historical consumption data are most useful in mature, stable programs that have a full supply of planning units and reliable data. This method can be the most reliable predictor of future consumption if the future use is predicted to be very similar to the past. Thus, a user must be able to extrapolate historical data (ideally, 24+ months of monthly actual consumption data is available) and the data must be a series of data over time (i.e. actual adjusted monthly consumption). - -There are four basic components for a consumption forecast: - -𝐹𝑜𝑟𝑒𝑐𝑎𝑠𝑡 ≅ 𝐵𝑎𝑠𝑒 + 𝑇𝑟𝑒𝑛𝑑 + 𝑆𝑒𝑎𝑠𝑜𝑛 + 𝑅𝑎𝑛𝑑𝑜𝑚 - -Different extrapolation models will utilize different statistical methods to estimate these different components and produce a forecast. In QAT, users will follow three steps to produce a consumption-based forecast: - -1. > [**Import/input**](#importinputting-actuals) actual consumption data. This can be done by importing data from the QAT Supply Planning module or inputting data manually. - -2. > [**Adjust**](#adjustments) actual consumption data by adding reporting rate and stockouts, and/or interpolating missing data. - -3. > [**Extrapolate**](#extrapolation) actual consumption data to produce a forecast. QAT has five different extrapolation methods to choose from: Moving Averages, Semi-Averages, Linear Regression, Triple Exponential Smoothing (TES, Holt-Winters), and Auto-Regressive Integrated Moving Average (ARIMA). - -### Import/Inputting Actuals - -There are two ways a user can add actual consumption data to their program: - -1. Importing actual consumption data from an existing program in the QAT Supply Planning module, or - -2. Manually input data in the “Data Entry and Adjustments” screen in the QAT Forecasting module - -**Steps for Importing Data from the QAT Supply Planning module:** - -1. > Navigate to the “Consumption-Based Forecast” à “Import from QAT Supply Plan” screen - -2. > Choose the Forecast Program, Range of Actual Consumption data to import, the Supply Plan program and then the Supply Plan version. _Note: only forecast programs that have been **downloaded** to the user’s local computer will be available in the dropdown for “Forecast Program.” See [Download/Delete Program](03-managing-programs-and-versions.md#downloaddelete) for how to download a program to the local computer._ - -3. > Users will then map the Supply Plan Planning Unit to the Forecasting Planning Unit. _Note: only planning units that have been added to the Forecast Program in the “Update Planning Units” screen and for which we have checked the checkbox for consumption forecast will be available in the dropdown for “Forecast Planning Unit.” See Forecasting Module [Planning Units](07-forecasting-module-program-data.md#planning-units) for how to add planning units to a forecast program._ - -4. > _Choose “Do not import” in the drop down for any PUs that do not automatically match. In case you have a lot of PUs and you want to select “Do not import” for all the unmapped one you can check the box ‘Do not import all unmapped planning units”_ - -> ![A screenshot of a computer Description automatically generated](/img/media/image239.png) - -Figure 157: Step 1 for Importing Actual Consumption Data from the Supply Planning Module - -5. > Users choose which region should be imported into the forecast program and also provide information on the % of the actual consumption that should be imported into the forecast program - > ![A screenshot of a computer Description automatically generated](/img/media/image240.png) - -Figure 158: Step 2 for Importing Actual Consumption Data from the Supply Planning Module - -6. > The last step will allow users to double-check the supply plan actual consumption data to make sure they are importing the correct unit of measure and months of data. If the data already exists in the forecast program, it will be highlighted yellow. If a user imports data that is highlighted yellow, this new import will override the data that already exists in the forecast program. Users can manually uncheck the months of data not to import, if desired. - > ![P2868#yIS1](/img/media/image241.png) - -Figure 159: Step 3 for Importing Actual Consumption Data from the Supply Planning Module - -7. > Click “Import.” - -**Steps for Inputting Actual Consumption Data Manually** - -1. Navigate to the “Consumption-Based Forecast” à “Data Entry and Adjustments” screen. - -2. Select the forecast program and the desired review period. By default, QAT pre-selects a date range of 36 months prior to the start of the forecasting period. A non-editable table and all products related to this forecast program are displayed, along with their adjusted consumption data if you have previously entered that data; otherwise, you will see yellow cells indicating that no consumption data has been entered. By default, the products and consumption are shown in planning units. The user can also expand each row of the table to display the consumption by region, if managing a multi-region program. - -> ![P2876#yIS1](/img/media/image242.png) - -Figure 160: Top Table in Data Entry & Adjustments Screen - -3. On the top table, click on a planning unit to display the detailed data table below for that planning unit. The detailed data table will have a section for each region in your program. - -4. The detailed data table allows users to add, edit, adjust, or delete historical consumption records. - 1. If you would like to enter data manually, enter the historical consumption for each region and month in the ‘Actual Consumption’ row. - - 2. If you have imported data from QAT, you will see your imported historical consumption in the ‘Actual Consumption’ row. - -![P2882#yIS1](/img/media/image243.png) - -Figure 161: Manual Data Entry Table for Actual Consumption - -3. By default, data is assumed to be entered in the Planning Unit. However, the user can specify the appropriate unit for the detailed data by clicking on the “change” link under the Planning Unit name and in the subsequent pop-up, choosing to enter data using the planning unit, the forecasting unit quantities (applying a realm-managed conversion factor) or another user-entered unit (and conversion factor). - -![P2885#yIS1](/img/media/image244.png) - -Figure 162: Button for Changing How Data is Manually Entered for Actual Consumption - -![P2887#yIS1](/img/media/image245.png) - -Figure 163: Pop-up for Choosing How Data is Entered - -5. Once a user enters data in the “Actual Consumption” row in the bottom data table, click “Submit” in order to save the entries and visualize them in the graph. - 1. Users can also copy & paste data from an excel or other tabular formats into the “Actual Consumption” row. - -![P2891#yIS1](/img/media/image246.png) - -Figure 164: Graphical Display of Manually Entered Actual Consumption Data - -### Adjustments - -**Purpose:** Enable users to prepare historical consumption data before moving on to the ‘Extrapolation’ screen. Historical actual consumption can be quantities sold, quantities dispensed to user, or quantities issued by storage facilities. On this screen, users can adjust historical consumption data that has been either manually entered on this screen or that has been imported from a QAT supply plan program (if you desire to import, please proceed first to the ‘Import from QAT Supply Plan’ screen). - -**Using this screen:** - -1. There are three ways to adjust the data: - 1. **Adjust for under-reporting**: The default value is 100% reporting every month. The user can change this to the correct value. QAT will calculate the adjusted consumption due to underreporting. The calculation assumes that facilities that did not report any consumption had the same consumption rate as the ones that did. - - 2. **Adjust for stockouts**: For imported data, the number of stockout days is pulled in from the QAT supply plan program, if data is collected. The default value for stock out days is zero days (product assumed always in stock). The user can change this to the correct value and QAT will calculated the adjusted consumption due to stockouts. The calculation assumes that the days the product was stocked out would have had the same consumption rate as the rest of the time the product was in stock. The default value for number of days in a month are based on the calendar days, but users can adjust the number of days used for the stock out calculation in ‘Update Version Settings’. - -> **\*Stock Out Rate** = Stocked Out (days)/ (\# of Days in Month).\* -> -> **\*Adjusted Consumption** = Actual Consumption / Reporting Rate / (1 – Stock Out Rate)\* -> -> For example, for a given month, a product had a consumption of 1,000 units, was out-of-stock for 5 out of 31 days in the month and the reporting rate was 98%: -> -> **\*Stock Out Rate** = 5 days stocked out / 31 days in a month = 16.1%.\* -> -> **\*Adjusted Consumption** = 1,000 units / 98% Reporting / (1 – 16.1%) = 1,217 units.\* - -3. **Adjust for missing values**: Click the green ‘Interpolate’ button in the middle right of the screen to search for periods where the consumption value is blank and replace them with an interpolated value. QAT interpolates by finding the nearest values on either side (before or after the blank), calculates the straight line in between them and uses that straight-line formula to calculate the value for the blank(s). Note that QAT will not interpolate for months where actual consumption is zero. QAT will only interpolate if there is at least one data point before and one data point after the blank value(s). Mathematically: - - - -- Where x’s represent months, and y’s represent actual consumption, - -- Where known data values are (x0 , y0) and (x1 , y1) - -- Where any unknown data values are (x, y) - -- The formula for the interpolated line is - -![P2914#yIS1](/img/media/image247.png) - -![P2915#yIS1](/img/media/image248.png) - -2. Use Detailed Data table to review the adjusted consumption - -3. Click ‘Submit’ to save any entered/adjusted data. Once the adjustments are saved, the Graph will update (note that it is required to click Submit for this to happen) - -4. Repeat steps 1-3 for each planning unit that needs to be adjusted. - -### Extrapolation - -**Purpose:** Enable users to create a forecast by identifying trends and seasons from historical time series data entered by the user in the ‘Data Entry and Adjustment’ screen. Several statistical extrapolation options are available and will be described below. Extrapolations from consumption data are made on a planning unit-by-planning unit basis. - -**Using this screen:** - -1. **Getting started on extrapolation:** - - - -- Before you use this screen, please ensure you have completed the ‘Data Entry and Adjustment’ screen for each planning unit and region you would like to extrapolate - -- Use the filters at the top of this screen to select the planning unit, region to extrapolate, and date range for historical data to utilize. - -- The user may select one -or several of the extrapolation methods available in QAT, as appropriate to the general consumption pattern and available data, as will be discussed below. See sections 2-4 below for an explanation of the extrapolation methods and how to best choose methods for your forecast. - -- Note that changes in this screen are optional – QAT automatically applies the default extrapolation parameters to all planning units after the Adjustments screen has been completed. The user then makes the final forecast selection in the ‘Compare and select’ screen. - - - -2. **Extrapolation methods available in QAT** - -> Forecast methods in QAT are organized from simple to sophisticated. - -1. > **Moving Average:** Moving average is an average that moves along time, dropping older data as it incorporates newer data. For QAT to calculate the moving average, enter the number months in the past that you would like to use in the calculation of the average. The user may select any positive integer for this field. Entering 5 for example would mean that the projection for the next month in the series would be the average of the preceding five months’ consumption. This method is most useful for short-term forecasts and is sensitive to trends. It is not appropriate for seasonal data - -2. > **Semi-Averages:** Semi-average estimates trends based on two halves of a series. QAT divides the actual data into two equal parts (halves) and the arithmetic mean of the values of each part (half) is calculated as the ‘y’ values of two points on a line. The slope of the trend line is determined by the difference between these ‘y’ values over time as defined by the difference of the midpoints of the two halves of the series, or ‘x’ values, of the points. This method is sensitive to trends and useful for short- and medium-term forecasts but is not appropriate for seasonal data. - -3. > **Linear Regression:** Linear regression models the relationship between two variables by fitting a linear equation to observed data. Confidence interval: between 0% and 100% (exclusive) e.g., 90% confidence level indicates 90% of possible future points are to fall within this radius from prediction represented by the regression line. This method is not appropriate for seasonal data. - -4. > **Triple Exponential Smoothing (Holt-Winters)**: In statistics, different types of smoothing are used to filter out the noise so that we can see patterns in a time series dataset more clearly. Exponential smoothing uses older data at exponentially decreasing weights over time. Smoothing parameters in exponential smoothing are set between 0 and 1, with values close to 1 favoring recent values and values close to 0 favoring older values. Users utilizing triple exponential smoothing can choose four parameters: - - - -- **alpha**, applies to the level or baseline of the dataset. Higher alpha values give more weight to the more recent data. The QAT default parameter for alpha is 0.2 - -- **beta,** determines how strongly recent trends should be valued as compared to older trends. The QAT default parameter for beta is 0.2. - -- **gamma,** reflects the seasonal component of the forecast. Seasonal generally refers to repeating patterns _within a year_. The higher the gamma, the more weight will be applied to the most recent seasonal component of the data. The QAT default parameter for gamma is 0.2. - -- **Confidence interval:** between 0% and 100% (exclusive) e.g. 90% confidence level indicates 90% of future points are to fall within this radius from prediction. The QAT default confidence interval is 85%. - -> QAT will only calculate TES forecasts for datasets with 24 or more months of data. - -1. > **ARIMA:** ARIMA or autoregressive integrated moving average enables two statistical models designed for stationary time series to be integrated and applied to non-stationary time series, that is, time series that have trends or seasons. It is often applied to short term forecasts. “Auto-regressive” means each point in the regression is influenced by its previous values and "moving average" implies that each point is an average, a linear combination of one or more adjacent points. Both the auto-regression and the moving average are "integrated" together to fit a best model for the series through differencing, or literally using the difference between points on a time series for the analysis instead of the raw values. ARIMA models have three parameters: - - - -- p or AR (lag order): the number of lag observations in the model. The QAT default parameter for p is 0. - -- d or I (degree of differencing): the number of times that the raw observations are differenced. This value is normally 1 (if there is a trend) or 0 (no trend). Other higher values are possible but not expected. The QAT default parameter for d is 1. - -- q or MA (order of the moving average): the size of the moving average window or the number of differenced observations to be averaged. The QAT default parameter for q is 1. - -- Confidence interval: between 0% and 100% (exclusive) e.g. 90% confidence level indicates 90% of future points are to fall within this radius from prediction. The QAT default confidence interval is 85%. - -> The ARIMA calculation may be either seasonal or non-seasonal, based on the user’s choice and understanding of their data and expectations of whether or not consumption of a particular product is subject to seasonal influences. QAT’s default selection is for seasonal ARIMA. QAT will only calculate ARIMA forecasts for datasets with 13 or more months of data. - -3. **Which extrapolation method should I use?** - -> Below are some considerations for selecting a forecast method. Forecast methods in QAT are organized from simple to sophisticated. In general, - -- More sophisticated models are more sensitive to problems in the data - -- If you have poorer data (missing data points, variable reporting rates, \<12 months of data), simpler forecast methods like moving averages are likely more useful. - -> The choice of extrapolation method depends on the expected pattern in the data. Some typical patterns include: - -- Stationary, where the range of observed values over time hover around an average. Models applied to such datasets may include - - Moving Average - - - ARIMA (non-seasonal) - -- Trending with no seasonal component, where the observed values have an increasing or decreasing trend. Models applied to such datasets may include - - Semi-averages - - - Linear Regression - -- Trending and Seasonal, where the observed values in a dataset have both trend and seasonal components. Models applied to such datasets may include - - ARIMA (seasonal) - - - Triple Exponential Smoothing (Holt-Winters) - -- Seasonal without trend, where the observed values have a seasonal component but no trend. Models applied to such datasets may include - - Triple Exponential Smoothing (Holt-Winters) - -> The models suggested here are neither exhaustive nor exclusive. QAT enables the user to apply a variety of extrapolation methods and then to compare them using best fit or forecast error metrics. -> -> The second step is to consider whether the forecast values are expected to reflect closely the historical patterns in your data and so whether you will use the error metrics to inform your selection. When choosing an output, (whether by disregarding the error metric or not) it will be important to document your rationale for doing so to inform discussions or reviews of your forecast and to help future forecasters to support their decisions. - -4. **How do I interpret errors?**0F\[1\] - -> QAT automatically calculates forecast error metrics using several methods. These include: - -- MAPE (Mean Absolute Percentage Error): can be interpreted as the average percentage difference between predictions and their intended targets in the dataset. For example, if MAPE is 15% then your predictions are on average 15% away from the actual values. - - _MAPE = \[(1/No. of Observations) \* ∑ (|(actual – forecast)|/actual)\] x 100_ - -- WAPE (Weighted Absolute Percentage Error): WAPE is an appropriate metric for when the dataset used has low or intermittent values. A WAPE percentage of 5 means that the forecast was off by 5% over the entire dataset for a certain evaluation period. Depending on the use case, it is recommended to choose a model that gives the least WAPE value. - - _WAPE = \[ (∑n | (actual – forecast) | / ∑ n (actuals)\] x 100_ - -- RMSE (Root Mean Squared Error): RMSE can be interpreted as the average error that the model’s predictions have in comparison with the actual, with extra weight added to larger prediction errors. Generally, the closer RMSE is to zero, the more accurate the model. - - _RMSE = sqrt \[∑n (actual – forecast)2\] / No. of observations_ - -- MSE (Mean Squared Error): MSE is the aggregated mean of the squared difference between the actuals and predictions. Large errors are highlighted due to this squaring. MSE is useful when working on models where occasional large errors must be minimized. Generally, the closer it is to 0, the more accurate the model. - - _MSE = ∑ n \[(actual – forecast)2\] / No. of Observations)_ - -- _R2 (the squared correlation between the dependent variable and the fitted values):_ - -> _R2 = 1 – \[sum squared regression (SSR) / total sum of squares (SST)\], where the sum squared of the residuals for the regression (SSR) is the sum of its residuals squared, and the total sum of squares (SST) is the sum of the distance the data is away from the mean, all squared. The R2 value is always a number between 0 and 1. R2 is a measure the fit of a regression line to a series of historical observations with values closer to 1 indicating a stronger correspondence between the actual and predicted (regression model) values. It is not a measure of error and should not be used by itself to assess the fitness of a prediction, but in combination with other error metrics and the user’s knowledge of the program._ - -- _R2 = 1 – \[sum squared regression (SSR) / total sum of squares (SST)\]_ - -> Apart from R2 the lower the score, the more closely the forecast method result fits the historical data. In models where historical patterns in a data set are expected to be reflected in the future values, a low error value could be used to help select a preferred extrapolation method, and QAT will highlight these best fits in a table. However, if substantial changes which do not fit the historical data are anticipated, the best fit extrapolation may not be the most appropriate forecast to select. -> -> To make the best selection between extrapolation methods for your purpose, before reviewing error metrics, the most important thing is first understanding which method of extrapolation is most appropriate for the expected pattern in the data. - -5. **Optimization of TES and ARIMA forecast parameters** - -![A screenshot of a computer Description automatically generated](/img/media/image249.png) - -Figure 165: Optimize TES & ARIMA Link - -> **As described in [Section A3. Extrapolation](#extrapolation), QAT offers the users multiple extrapolation options including TES and seasonal and non-seasonal ARIMA. Users are free to use the QAT defaults or to enter alternative forecasting parameters with the intention of reducing the error metrics thereby increasing the correspondence between the forecast method outputs the real datapoints in the historical data period. If the user is working online, QAT can optimize the TES and ARIMA parameters by iterating, calculating the RMSE of each iteration, and selecting the parameters that produce the lowest RMSE.** - -![A screenshot of a computer Description automatically generated](/img/media/image250.png) - -Figure 166: Optimizing TES & ARIMA Pop-up - -> **For TES, QAT calculates 125 iterations of the forecast, testing each of the alpha, beta and gamma parameters in combination with the following values: 0, 0.2, 0.4, 0.8 and 1. Whichever of the 125 combinations for a given product produces the result with the lowest RMSE will be displayed in the extrapolation screen.** -> -> **For ARIMA or seasonal ARIMA, QAT calculates 24 iterations of the forecast, testing each of the p, d and q parameters in combination, using the following values:** - -- **p: 0 or 1** - -- **d: 0, 1 or 2** - -- **q: 0, 1, 2 or 3** - -> **Whichever of the 24 combinations for a given product produces the ARIMA result with the lowest RMSE will be displayed in the extrapolation screen.** -> -> **Note: Statistics are not magic. The underlying assumption for all these methods of extrapolation are that trends and patterns in the historical data will continue into the future. Therefore, low error metrics do not necessarily guarantee a better forecast.** - -6. **Bulk Extrapolation** - -![A screenshot of a computer Description automatically generated](/img/media/image251.png) - -Figure 167: Bulk Extrapolation Link - -> **In the QAT extrapolation screen, the user can compare the outputs of the various extrapolation methods both graphically and in an output table, product by product. This allows the user to de-select extrapolation methods that they feel do not apply to a given product to limit the options in the Compare and Select screen to only those the user chooses to display.** - -![A screenshot of a computer Description automatically generated](/img/media/image252.png) - -Figure 168: Bulk Extrapolation Pop-up - -> **If the user would prefer to send all of the outputs of the available extrapolation methods for more than one product directly to the Compare and Select screen, the user can select bulk extrapolation. From the Bulk Extrapolation pop-up window, the user may then select an historical date range from which to extrapolate the forecast (only one date range per bulk extrapolation), whether to apply seasonality to their ARIMA calculation, which planning units and regions (if regional data are used) to include in the bulk extrapolation and whether or not to optimize ARIMA and TES parameters for the extrapolation.** -> -> **After running the bulk extrapolation, all results can be viewed in the Extrapolation Screen, the Compare and Select Screen and the Forecast Summary (regional) Screen dropdown box. The user may select their preferred extrapolation method from either the Compare and Select Screen or the Forecast Summary (regional) Screen.** -> -> **Bulk extrapolation in QAT is particularly useful when working with a large set of products for which timely, complete and accurate consumption data is available for 12 or more months.** - -## Tree Forecasts - -Users can conduct a tree-based forecast if the necessary data for a consumption-based forecast is not available or not helpful in predicting future consumption. Tree forecasts flexibly accommodate all other forecast methods, such as **morbidity, services, and demographic methods**. Users can specify changes over time in a tree, either by directly specifying the rate of change or extrapolating from past data. - -### Building a Tree - -![A screenshot of a computer Description automatically generated](/img/media/image253.png) Figure 169: Manage Tree – Tree List (Right click to access actions) - -**Purpose:** Enable users to: - -1. View a list of their existing trees - -2. Edit an existing tree by clicking any row - -3. Right click on a row to - - > **Duplicate existing trees:** Users may also duplicate an existing tree to another program. Users must have access to both programs and have both downloaded to their local computer to duplicate across. - - - > **Delete existing trees:** There will be a confirmation screen, but this action is thereafter irreversible. However, if you accidentally delete a tree, you can re-download a program if the deleted tree has been backed up to the server. - - - > **Tree Table:** This allows user to edit the selected tree in the [Tree Table](#advanced-techniques) screen - -4. Add a new tree to a downloaded program by clicking on the ‘Create or Select’ dropdown in the top right corner of the screen. New trees can be built: - - - -- manually - select ‘+ Draw Your Own Tree’ - -- from a tree template - select the name of the desired template. If a user would like to see a tree template added to QAT that does not exists and it would benefit the QAT community, they can submit a change request to the [QAT Ticketing Helpdesk System](02-getting-started.md#qat-helpdesk-and-tickets). - -**\*Note**: [Forecast Viewers](12-annex-3-user-role-matrix.md#annex-3-user-role-matrix) can view any tree that has been uploaded to the server and they have access to; however, only Forecast Users/Admins will be able to create and edit/update trees.\* - -**Using this screen:** - -- A forecast program must first be downloaded to build or edit a tree - -- Before building and editing a tree, first add the forecast program’s planning units in the ‘Update Planning Units’ screen. - -- **Building a tree similar to an existing tree?** - - Same structure, different numbers: Build only -one tree, and use the [scenario](#scenarios) feature. - - - Slightly different structure: Duplicate an -existing tree by right clicking on a row and selecting “Duplicate Tree.” -Note: If you want to duplicate an existing tree from another program, you -must have both programs downloaded, then you can duplicate from one program -to another program. - -- **Want to start from a template instead?** See [Tree Template](#tree-templates) section - -- Users can also delete trees by right clicking on a row and selecting “Delete Tree.” - -#### Node Types & Functions - -**Building the Tree:** The forecast tree is built from the top down, using different types of “nodes”. See the Node Types and Node Actions below. Each forecast tree must start with either an Aggregation node or a Number node, and include one or more Planning Unit nodes, which form the forecast output. - -**Node Actions:** - -- ![P3021L144#yIS1](/img/media/image254.png) Delete: Deletes the selected node and all its children. - -- ![](/img/media/image255.png) Copy/Move: Copies or moves the selected node and all children under the node. The user can select the destination. - -- ![P3023#yIS1](/img/media/image256.png) Add Branch Template: Adds a tree template as a branch below the chosen node. - -- ![](/img/media/image257.png) Add: Adds a child to the selected node. - -- ![P3025#yIS1](/img/media/image258.png)/![P3025#yIS2](/img/media/image259.png) Collapse/Expand: Collapse/Expands the current node and all its children. Users can also hover over the dot to choose which node to expand and click once to expand that node and all it’s children. Additionally, there is a “Collapse Tree” checkbox at the top of the Build Trees screen that will collapse every node except for the top node. - -> ![](/img/media/image260.png) - -Figure 170: Example of a Collapsed Forecasting Tree - -**Node Types:** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Node Type - - Value - - Potential Children - - Advanced Functionality -
- Aggregation ∑ - Sum of children nodes. - ∑ or Number - -
- Number # - Defined at this node - % or - P3041C11T27#yIS1 - - ⇅, - P3042C12T27#yIS1 - , - P3042C12T27#yIS2 - , - -
- Percentage % - Percentage of the parent. - % or - P3046C15T27#yIS1 - - ⇅, - P3047C16T27#yIS1 - , - -
- Funnel - - - Sum of linked source nodes ( - - ) - - % or - P3046C15T27#yIS1 - -
- Forecasting Unit - P3049C17T27#yIS1 - -

- Percentage of the parent and forecasting unit parameters. Can be two - different use types: -

-
    -
  • -
    -

    - : Continuous -

    -
    -
    • -
  • -
    -

    - P3052C18T27#yIS1 - : Discrete -

    -
    -
    • -
- 		- P3053C19T27#yIS1 - - ⇅, - P3054C20T27#yIS1 -
- Planning Unit - P3056C21T27#yIS1 - Percentage of the parent and planning unit parameters.- - ⇅, - P3059C24T27#yIS1 -
- -- > **∑ Aggregation node-specific attributes:** none – it is defined by the sum of its children. _For example, if there are two children nodes below the Aggregation node equal to 50 and 100, QAT would automatically add these numbers to define the Aggregation node: 50 (child) + 100 (child) = 150 (Aggregation parent)._ - -- > **\# Number node-specific attributes:** - - > Node Unit: dropdown consisting of either -patient, client, customer, people, or unit - - - > Month: choose the month/year this data was reported -from*. For example, if a user wants to define a number node as Country Population -and the data is from January 2020, the node month should be Jan. 2020.* - - - > Node Value: Define the number value for this -node. *For example, if the Country Population in January 2020 is 500,000, the -node value should be 500,000.* If this value changes over time, users can utilize -the [Modeling/Transfer](#modelingtransfers) tab to specify the change. - - > **% Percentage node-specific attributes:** - - > Node Unit: dropdown consisting of either -patient, client, customer, people, or unit - - - > Month: choose the month/year this data was -reported from*.* Typically, this will be the start month/year of the forecast. - - - > Percentage of Parent: define the percentage -of the parent node. *For example, if half of the parent number node, Country -Population, are female, the percentage of parent would be 50%.* - - - > Parent Value for Month: non-editable and -provided only as a reference. - - - > Node Value**:** auto-calculated by QAT -based on the percentage defined by the user and the parent value. This -field is non-editable. - - - > ![](/img/media/image271.png) **Forecasting Unit node-specific attributes:** - - > Month: choose the month/year this data was -reported from. Typically, this will be the start month/year of the forecast. - - - > Percentage of Parent: define the percentage -of the parent node. - - - > Parent Value for Month: non-editable and -provided only as a reference. - - - > Percentage of Parent Value for Month: non-editable -and provided only as a reference. - - - > Tracer Category: dropdown that can be used -to help narrow-down forecasting units, but will be auto-filled once the -forecasting unit is chosen. - - - > Copy from Template: advanced functionality, -in which a user can utilize a [Usage Template](#usage-templates) to assist -with building a tree efficiently. This dropdown is not required. - - - > Forecasting Unit: dropdown of all available -forecasting unit in user program. If a forecasting unit is not available -in the dropdown, user should first add it to the ‘[Update Planning Unit](07-forecasting-module-program-data.md#planning-units)’ -screen. - - - > Planning Unit: dropdown filtered based on -forecasting unit chosen. If there is only one planning unit associated -with the forecasting unit, this field will automatically be pre-filled. - - - > Type of Use: - - > ![](/img/media/image272.png) Discrete: Every \_\_\_\_\_\_\_ \[parent node unit\] requires \_\_\_\_\_\_\_\_\_ \[forecasting unit of measure\] \_\_\_\_­­­­­\_\_\_\_\_\_ times per \[day/week/month/year\] for \_\_\_\_\_\_\_\_\_\_\_\_\_ \[day/week/month/year\] - - > Calculate (All in the First Month/Month-by-Month) -: If selected “All in First Month,” QAT will frontload the total -forecasted quantity to the node's start month. If selected -“Month-by-Month,” QAT will calculate the quantity discretely -month-by-month (see [Advanced Techniques](#advanced-techniques) -for more information). - - - > Single Use (Yes/No): allows user to -determine if this forecasting unit is used over a specific period of -time. If “yes” is selected, the length of time for discrete calculations -is not needed. - - - > ![](/img/media/image268.png) Continuous: Every \_\_\_\_\_\_\_ \[parent node unit\] requires \_\_\_\_\_\_\_\_\_ \[forecasting unit of measure\] every \_\_\_\_\_\_\_ \[day/week/month/year\] - - - > Lag in months: used to detail if a forecasting -unit is delayed or has a phased-product usage. See [Advanced Techniques](#advanced-techniques) -for more information. - - - > ![](/img/media/image273.png) **Planning Unit node-specific attributes:** node automatically created when the forecasting unit is added to a tree. Most attributes in the add/edit node screen are non-editable and only for reference; however, a few can be updated based on specific circumstances: - - > Month: choose the month/year this data was -reported from. Typically, this will be the start month/year of the forecast. - - - > Calculation Override: users can choose to -use QAT's auto-calculation for number of Planning Units by clicking “Yes” -or manually input a value by clicking “No.” See [Advanced Techniques](#advanced-techniques) -for more information. - -**Changes Over Time** - -While the tree structure stays constant throughout time, node percentages and values can change over time. Use the date dropdown to view the tree at any month. The three functionalities below are available in each node and allow the user to control how nodes change over time: - -- **⇅ Modeling:** Allows user to specify the exact rate of change - -- ![P3094#yIS1](/img/media/image274.png "Link with solid fill")**Transfer**: Allows users to link two nodes together – so the decrease from the source node is linked to the increase of the destination node. Useful for transitions. - -- ![P3095#yIS1](/img/media/image275.png) **Extrapolation:** Allows users to use historical data to extrapolate future change. - -For more information and specific examples of changes over time, see [Modeling/Transfers](#modelingtransfers). - -#### Building Tree Basics - -![](/img/media/image276.png) - -Figure 171: Simple Forecasting Tree Example - -Forecasting trees are built from the top-down using different types of [nodes.](#node-types-functions) Each forecast tree must start with either an Aggregation node or a Number node, and include one or more Planning Unit nodes. Planning Unit nodes must be the child of a Forecasting Unit node. Thus, a user must have at least three levels of nodes (Aggregation/Number node, Forecasting Unit node, and Planning Unit node) to produce a forecast output. - -**Steps for Building a Manual Tree:** - -1. > Download a program - -2. > Navigate to the Forecasting Tree à Manage Tree screen - -3. > In the top-right of the screen, click the blue ‘Create or Select’ dropdown and select ‘+ Draw your own tree’ from the dropdown - -4. > Define the tree details, such as the forecasting method (demographic, morbidity, or services), tree name, and region. - 1. Once created, users can edit tree details by clicking on the ![P3108#yIS1](/img/media/image277.png)icon next to the Tree dropdown. - - 2. (optional) By clicking on the ![P3109#yIS1](/img/media/image277.png) icon next to the Scenario dropdown, users can add, edit, and delete tree scenarios. For more information, see [Scenarios](#scenarios) in the section below. - -5. > By default, QAT will begin with a number node with a value of zero on Level 0. Click on this default node to edit/update the node. - -6. > Add a new node (child) below the parent node by clicking on ![P3111#yIS1](/img/media/image278.png) and choosing the appropriate Node Type. Based on the parent, QAT will automatically filter which [child node types](#node-types-functions) are available. QAT will add the new node under the same parent and to the right of any existing nodes. Continue to add nodes based on available data until ending with a Forecasting Unit node and its associated Planning Unit node. - 1. To delete a node, simply click the ![P3112#yIS1](/img/media/image254.png) icon, but note that this will also delete the child nodes under the one being deleted - - 2. To copy or move a node, click on the ![](/img/media/image279.png)icon. In the pop-up, review or select where you want the node to be copied or moved to – the tree, the level of the parent, and the parent. - - For copying, QAT will select the same location as the original node by default - - - For moving, QAT will select the same tree as the original node by default - - - The entire branch (including all child nodes) will be moved/copied. - - - Use the checkbox to select if you want to include modeling or not. Note: Transfers are never copied/moved. - - 3. As a validation feature, QAT will flag a Planning Unit (PU) node with a red border under two circumstances: 1) if a user has added a Forecasting Unit (FU) and PU, and later changes the FU and mistakenly forgets to also change to the correct corresponding PU, or 2) if a user creates a tree from a tree template which has PUs, but the user does not have those PUs in their program. - -![](/img/media/image280.png) - -> To correct this, users can click on the PU node and choose the appropriate PU from the dropdown list. - -![P3117#yIS1](/img/media/image281.png) - -4. _Tip: users can “clean-up” their tree by clicking any of the checkboxes available (Hide Planning Unit, Hide Forecasting Unit and Planning Unit, or Hide Tree Validation) at the top of the tree._ - - - -7. > _(optional)_ Users can insert a tree template within the body of their tree by clicking the ![P3119#yIS1](/img/media/image256.png) icon to add a branch template. This branch will be added below the current node as a child. This improves the efficiency of adding multiple batches of nodes (a branch) that are the same or similar across an existing tree or a new tree by utilizing templates. For more information on branch templates, refer to [Branch Templates](#branch-templates) - -8. > _(optional)_ Click on the tree levels (dark blue rectangular boxes on the left of the tree) to: - - > Name the levels of a tree. This will make a tree easier to read and will be used in the dropdowns and axis of the [Modeling Validation](#modeling-validations) screen. - - - > Reorder branches of your tree as desired by using the up and down arrows to indicate the left-to-right position of the branches. If the list is long, use the “see children of” dropdown to filter the nodes. - -![A screenshot of a computer Description automatically generated](/img/media/image282.png) - -9. > QAT trees are **automatically saved** to the local computer (for saving a tree to the server, please see [Upload Version](03-managing-programs-and-versions.md#upload). The quantities that appear in the nodes are also automatically calculated as a tree changes; however, if QAT is running slow while editing the tree, users can uncheck the “Auto-Calculate” box to stop the backend auto-calculations. To manually see the updated calculations after each edit, users will need to click the ![P3121#yIS1](/img/media/image283.png) icon. - 1. > Users can download their trees as PDFs to share with stakeholders by clicking on the ![P3122#yIS1](/img/media/image284.png) icon. - - 2. > Users can download an outline form of their tree to double check the Sum of Children validation, node values, and their nodes by clicking on the ![P3123#yIS1](/img/media/image285.png) icon. - -10. > _(optional)_ To batch edit values in a tree, user can use the **Tree Table** screen, which is accessible via a link at the top left of the Manage Tree – Build Trees screen. - - > On the Tree Tables screen, - - - > The dropdowns at the top of the screen should be prepopulated with the same program, tree, scenario, and display date as previously selected, but users can update the dropdowns as needed before making edits. - - - > Nodes are grouped by node type on different tabs. Navigate to the node(s) you want to edit by using the tabs - - - > Made edits to any node values by editing the table cells. - - - > See the example and screenshot in Figure 157 - - - > Note that while the Tree Tables screen is helpful for editing the values of multiple nodes efficiently, the Tree Tables screen does not allow for editing for the tree structure. Please use the Manage Tree – Build Trees screen to add, delete, copy or move nodes. - - - > Upon returning to the Build Tree screen, users may need to click the ![P3121#yIS1](/img/media/image283.png) icon to see updated values. - -> ![A screenshot of a computer Description automatically generated](/img/media/image286.png) - -Figure 172 Accessing and Using Tree Table Screen - -#### Scenarios - -**Using Scenarios:** Scenarios are used to model different values for the same tree. Scenarios are useful when users would like to analyze the outcome of different changes over time (ex: national target vs. status quo, different levels of seasonality, transitioning planning units at different rates, etc.), but would like to keep the same base structure. To create a tree with different structures (e.g. different regimens, different methodologies), it is recommended to create another tree (tip: utilize the duplicate tree function\!). To add, edit, delete or inactivate a scenario, use the ![P3125#yIS1](/img/media/image277.png) icon next to the scenario dropdown. Use the scenario dropdown to select which scenario to view and edit. - - - - - - - - - - - - - - -
- Fixed for All Scenarios - - Unique to each Scenario -
-

Tree structure

-

Node Title

-

Node Type

- 		-

Node value

-

Month

-

Notes

-

Modeling/Transfer/Extrapolation

-
- -_Notes_ - -- _By default, only active_ _scenarios are shown. To view inactive scenarios, click the_ ![P3125#yIS1](/img/media/image277.png) _icon next to the scenario dropdown, followed by “Show Inactive”_ - -- _Users can choose different tree-scenario combinations for each Planning Unit in the [Compare and Select](09-forecasting-module-reports-and-outputs.md#compare-and-select) screen._ - -#### Modeling/Transfers - -**Purpose:** If a node changes over time, a user can utilize the Modeling/Transfer tab to model growth/loss within a single node or a transfer from one node to another. Note that this functionality is only available for Number (\#) Nodes and Percentage (%) Nodes (including Forecasting Units and Planning Units). User can still use the tab to view monthly data for Aggregation and Funnel nodes. - -**Using this tab:** - -Users can **manually** enter any desired changes over time (growth/loss/transfer) in the top table, or they can utilize the ![P3144#yIS1](/img/media/image287.png) **Modeling Calculator** for calculating the monthly rate of change (see ‘Modeling Calculator’ section below for more information). Each entry must be added as separate rows per change in the top table (ie. a node cannot grow and transfer in one data entry row – these must be two separate rows). - -- **Rules for Transfer Nodes:** - - Number nodes can only transfer to other number nodes and must belong to the same level. - - - Percentage nodes can only transfer to other percentage nodes and must belong to the same parent. - - - Transfers are always negative from the source node and positive to the destination node. - - - Extrapolation is not allowed on a node that also has a transfer, whether that be to/from another node. - - - -- **Modeling Types:** - -| **Modeling Type** | **\# Node Calculation** | **% Node Calculation** | -| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Linear (\#) | \+/- a static number each month | N/A | -| Linear (%) | \+/- a static percentage each month, calculated based on the starting month | N/A | -| Exponential (%) | \+/- a percentage each month, calculated on the previous month as a rolling percentage | N/A | -| Linear (% point) | N/A | \+/- a static percentage each month (e.g. if the starting month is 30% and the change is +1% each month, next month is 31%, the next is 32%, and so on) | - -- Click on “**Show Monthly Data”** to show a table & graph with the node value across time - - This feature is helpful to see how modelling and transfer inputs affect the monthly data in both a graphical and tabular form. - - - In the tabular data, users may add a manual change for a specific month or input a seasonality index percentage (only available for \# and % nodes), as needed. - - Enter a positive % for an increased value in this month or a negative value for a decreased value. For example, 20% indicates that this month's value is 20% over the non-seasonal value (or 120%), whereas -20% indicates that it is 20% under the non-seasonal value (or 80%). - - - For percentage nodes, QAT first calculates the seasonalized value of the percentage before then calculating the value of the node by multiplying the seasonalized percentage and the parent value. In Figure 159, the example show how the unseasonalized percentage of 50% becomes 60% after it’s seasonalized. - -> ![](/img/media/image288.png) -> -> Figure 173 Seasonality in a number node -> -> ![](/img/media/image289.png) -> -> Figure 174 Seasonality in a percentage node - -- If a user checks “Manual Change affects future month,” the manual amount added to the end of the month will carry over to the beginning of the next month. - -- If neither of these fields are relevant, users can uncheck “Show manual change” or “Show seasonality & manual change” to hide these columns. - -**Modeling Examples:** - -- **Simple Growth** (linear \#) - the example below shows a population growth each month by 500/month from January 2022 to December 2024. - -![P3182#yIS1](/img/media/image290.png) - -- **Simple Loss** (linear \#) - the example below shows attrition each month by 100/month from January 2022 to December 2024. QAT utilizes a negative number to denote a decrease or loss. - -![P3184#yIS1](/img/media/image291.png) - -- **Simple Growth** (linear %) – the example below shows a steady population growth each month by 2% from January 2022 to December 2024. QAT has calculated this change to be increasing the population by 108.64 each month. - -![P3186#yIS1](/img/media/image292.png) - -- **Simple Growth** (exponential %) - the example below shows a population growth each month by 1% from January 2022 to December 2024. Because the growth is exponential, the change differs each month. ![P3187#yIS1](/img/media/image293.png) - - QAT calculates this change to be 54.32 in Jan-22 month, - - - QAT calculates this change to be 54.86 in Feb-22 month, and - - - QAT calculates this change to be 55.41 in Mar-22 - -- **Multi-year Loss** – the example below shows a different rate of attrition (loss) each year. Year 1 (January 2022 to December 2022) decreases the population by 1% or 54.32 each month, Year 2 (January 2023 to December 2023) decreases the population by 2% or 95.6 each month, etc. QAT utilizes a negative number to denote a decrease or loss. - -![P3192#yIS1](/img/media/image294.png) - -- **Transfer** – the example below shows a transfer of 250 patients each month for one year, January 2022 to December 2022, from the current node (Adults 1st Line) to another node (Adults 2nd Line). This transfer will also appear on the other node (Adults 2nd Line) greyed-out to signify a non-editable change. - -![P3194#yIS1](/img/media/image295.png) - -![](/img/media/image296.png)**Modeling Calculator:** - -Click on the modeling calculator icon if you need assistance to calculate the monthly rate of change. The modeling calculator **Ending Value/Change** is available for all nodes except Aggregation Nodes, and the modeling calculator **Annual Target** is only available for Number Nodes. Begin by select a **Modeling Type** (Linear \#, Linear %, or Exponential %), and then a **Target Type** (Ending Value/Change or Annual Target): - -- **Ending Value/Change:** Use this if you have target value (non-cumulative) or total desired change over a specific period, rather than a known monthly rate of change. - - - -1. The **Start Date** and **Target Date** will be filled in based on the original inputs for Start date and End date in the modeling table, which are by default, based on the forecast period. The user can change these if desired. These two dates will flow back into the modeling table. - -2. The **Start Value** is the node value at beginning of the month for the Start Date, as calculated by QAT. In other words, the Start Value is the node value _before_ any modeling changes occur. This field is calculated and cannot be directly changed by the user. If the Start Date is the month after the “Month” on the Node Data tab, then the Start Value is equal to the "Node Value” provided by the user on the Node Data tab. - -3. **Period** is calculated as Target Date - Start Date (in months). This value is not displayed in the front-end of QAT, but is used in the formulas below. - -4. Based on the available data or assumptions, enter data in one of the following fields: **Target Ending Value**, **Target Change (%)** or **Target** **Change (\#)** - -5. After an input is provided, the other fields will be automatically populated, as well the final **‘Calculated Month-on-Month Change’**. - -6. When user clicks ‘Accept’, the **Monthly Change (% or \#)** will be populated back in the main modeling table, based on the formulas below. All negative changes will be displayed as “decrease” and positive changes displayed as “increase”, with the number shown in absolute value. - -> If user enters **Target Ending Value**: - -| | **Linear (%)** | **Linear (\#)** | **Exponential (%)** | -| ------------------------------------ | -------------------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------- | -| **Target Change (%)** | (Target Ending Value - Start Value) / Start Value | | | -| **Target Change (\#)** | \- | Target Ending Value - Start Value | \- | -| **Calculated Month-on-Month Change** | (Target Ending Value - Start Value) / Period | | | -| **Monthly Change (%)** | (((Target Ending Value - Start Value)/ Period) / Start Value) \* 100 | \- | ((Target Ending Value / Start Value) ^ (1 / Period) - 1) \* 100 | -| **Monthly Change (\#)** | \- | Change (\#) / Period | \- | - -> If user enters **Target Change (%)**: - -| | **Linear (%)** | **Linear (\#)** | **Exponential (%)** | -| ------------------------------------ | --------------------------------------------------------------------- | --------------------------------- | -------------------------------------------------------------- | -| **Target Ending Value** | Start Value + (Start Value \* Target Change (%)/100)/100 | | | -| **Target Change (\#)** | \- | Target Ending Value - Start Value | \- | -| **Calculated Month-on-Month Change** | (Start value \* Target Change (%)) / 100 / Period | | | -| **Monthly Change (%)** | (((Target Ending Value - Start Value) / Period) / Start Value) \* 100 | \- | (Target Ending Value / Start Value) ^ (1 / Period) - 1) \* 100 | -| **Monthly Change (\#)** | \- | Target Change (\#) / Period | \- | - -> If user enters **Target Change (\#)**: - -| | **Linear (\#)** | -| ------------------------------------ | ---------------------------------------------------------- | -| **Target Ending Value** | Start Value + Target Change (\#) | -| **Change (%)** | (Target Ending Value - Start Value) / (Start Value \* 100) | -| **Calculated Month-on-Month Change** | Target Change (\#)/ Period | -| **Monthly Change (\#)** | Target Change (\#) / Period | - -- **Annual Target:** Use this if you have target values (cumulative over a year). Instead of simply dividing annual targets by 12, which creates a stairstep pattern that is, the calculator will help provide a smooth forecast. - -![P3279#yIS1](/img/media/image297.png) - -1. Select the first month of your target and the number of years of targets available. - - QAT will autofill in the yearly rows in the table based on the chosen first month of target, assuming targets are for 12-month periods. - -2. In the table, enter figures for the year before the target (the actual) and each target year. - -3. After data entry, click “Calculate” (see below for calculation approach and formulas). - -4. Review the differences between the desired targets and the QAT calculated numbers. If differences are large, consider if the rate of change follows a linear or exponential pattern and change the **Modeling Type** (Linear \#, Linear %, or Exponential %) and re-calculate if needed. - -5. When user clicks “Accept,” QAT populates the calculated values in two places: - - Node Value tab - Starting Month and Starting Value - - - Modeling/Transfer tab – one row is created per 12-month period after the Starting Value. **Note that these are not the same periods as the Target Years** (see below). - -> Annual Target Calculation Approach: QAT assumes -that 1/12th of the annual actual value was achieved in the midpoint -of the actual year, and 1/12th of the annual targets will be reached -by the midpoint each target year. QAT then effectively interpolates between those -midpoints by calculating a linear or exponential monthly rate of change. This monthly -rate of change is then applied to both years - the second half of the first year -and the first half of the second year. To achieve this, QAT calculates the following -fields: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Field - - Explanation / Formula -
Annual Change (%) -

- Change from previous year. Calculated for each year after the first - year. -

-

- = (Current Year Value - Previous Year Value) / (Previous Year Value) -

-
Monthly Change (%) / Monthly Change (#)* -

Exponential Rate = (Year 2 Value/Year 1 Value)^ (1/12) -1

-

Linear Rate = Annual Change / 12

-
Node Month**= n-7, where n is the first month of the target.
Node Value** -

- Assumed to be the first value (the actual value) provided by the user - divided by 12, since this is assumed to be the midpoint of the year. -

-

= Year Value/12

-
Calculated Total - Beginning with the Node Month and Node Value, and applying the Monthly - Change (% or #), QAT calculates each monthly value, then provides sums - the values across 12-month periods. -
Difference (Target vs Calculated, #) -

- Calculated for each year after the first Actual year. This difference - will be large if the annual change varies significantly between years. -

-

= Calculated Total – Target

-
Difference (Target vs Calculated, %) -

- Calculated for each year after the first Actual year. This difference - will be large if the annual change varies significantly between years. -

-

= (Calculated Total - Target) / Target.

-
- -> \* These values don’t appear in the ‘Modeling Calculator’ section, but populate in the top modeling/transfer node table after user clicks “accept.” -> \*\* These values don’t appear in the ‘Modeling Calculator’ section, but populate into the main node fields after use clicks “accept.” - -#### Extrapolation - -**Purpose:** The extrapolation tab allows users to forecast future node values by extrapolating from past values. This functionality is only available for number nodes, and is similar to the ‘Extrapolation’ screen, but is conducted in a tree node instead. For a given node, users must choose between modeling/transfers or extrapolation, but cannot use both at the same time. More details on extrapolation methods can be found under [Extrapolation](#extrapolation). - -**Using this tab:** - -1. First, select the checkbox next to ‘Extrapolate’ in the Add/Edit Node. - -2. Select ‘Show Data’. - -3. In the table, enter any actual values and reporting rates for your past data. From this input, QAT will calculate adjusted historical values. If you need to change the period for data, change the start and end month at the top of the node under ‘Start Month for Historical Data’. - -4. If there is missing data, use the green Interpolate button to fill in missing data. Interpolate can only be used if there is data on both sides of the month missing data. - -5. (optional) Select which forecast method(s) you wish to display and update the extrapolation parameters. - -6. Click “Extrapolate.” All selected forecasts will display in the main table and the graphs. - -> _NOTE: The minimum values needed to get correct graphs and reports for the various features are below:_ -> -> _\* TES, Holt-Winters: Needs at least 24 months of actual consumption data_ -> -> _\* ARIMA: Needs at least 14 months of actual consumption data_ -> -> _\* Moving Average, Semi-Averages, and Linear Regression: Needs at least 3 months of actual consumption data_ - -7. (optional) In the table, add any manual changes (+/-). These changes are added or subtracted on top of the extrapolated values. - -8. After reviewing the main table, the error table, and the graphs, select the desired forecast method at the bottom of the screen and click “Save.” - -9. Note: If you change any inputs, you will be required to extrapolate again to update calculations, before selecting a new method. - -#### Advanced Techniques - -**Tips for specific use cases**: - -- **Delayed or phased product usage?** Sometimes, the product consumption is delayed in relation to the other higher levels of the tree. In the relevant **Forecasting Unit** node, use the **Lag** field to indicate this delay. - - For example, if the product usage will begin 2 months after the parent node dates, enter “2” in this field. - - - This field can also be used where the product switches over time – for example, if forecasting units A, B, and C are used in secession for two months at a time, you can set up your tree with Forecasting Unit A (discrete for 2 months, lag=0), Forecasting Unit B (discrete for 2 months, lag=2), Forecasting Unit C (discrete for 2 months, lag = 4). - -- **Discrete product usage over a longer period of time? (first month forecasting vs. forecasting month-by-month):** QAT has the option to calculate discrete product usage in forecasting unit nodes in two ways: - - by frontloading the discrete quantity consumed per patient in month 1 (choose "Calculate" = "All in the First Month") or - - - by disaggregating the discrete quantity consumed per patient by month (choose "Calculate" = "Month-by-Month"). - - - By default, QAT will assume "All in the First Month" (frontloading); however, users have the option to select "Month-by-Month" for the alternative method. This alternative calculation could be useful for Planning Units (PUs) that have low consumption patterns over a period of time or if applying to a newly initiated patient group. For example, if a pregnant woman is required to take a nutritional supplement once/month for the duration of the pregnancy (nine months), by default QAT would calculate nine supplements in month 1 (frontloading). Without frontloading, QAT would calculate one supplement in month 1, one supplement in month 2, one supplement in month 3, and so forth. - -Example calculation (All in the First Month vs. Month-by-Month) – **no modeling applied**: - -- All in the First Month: There are 10 patients -that require 1 bottle for treatment over the course of 6 months; thus, the \# -of Planning Units per patient = 6. When calculating “All in the First Month,” -QAT will frontload the forecasted quantity and assume that all 60 bottles (10 -patients \* 6 bottles per patient) are forecasted each month. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MonthJanFebMarAprMayJunJulAugSepOctNovDec
- # of -
- Patients - 		- 10 - - 10 - - 10 - - 10 - - 10 - - 10 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 -
60
60
60
60
60
60
0
0
0
0
0
0
- Total -
- Forecasted - 		606060606060000000
- -**Total Forecasted in 6-month Period = 360 Bottles** - -- Month-by-Month: There are 10 patients that -require 1 bottle for treatment over the course of 6 months; thus, the \# of -Planning Units per patient = 6. With “Month-by-Month,” QAT will evenly -distribute the forecasted quantity across the time period. Thus, QAT will -assume that 10 bottles are forecasted in month 1 (10 patients \* 1 bottle). In -month 2, those same 10 patients will each return for another bottle, while a -new patient group of 10 will also each need 1 bottle \[(10 patients \* 1 -bottle) + (10 patients \* 1 bottle)\] for a total of 20 bottles forecasted in -month 2, and so forth. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MonthJanFebMarAprMayJunJulAugSepOctNovDec
- # of -
- Patients - 		- 10 - - 10 - - 10 - - 10 - - 10 - - 10 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 -
101010101010
101010101010
101010101010
101010101010
101010101010
101010101010
000000
00000
0000
000
00
0
- Total -
- Forecasted - 		10203040506050403020100
- -**Total Forecasted in 6-month Period = 160 Bottles** - -**Total Forecasted in 12-month Period = 360 Bottles** - -> Example calculation (All in the First Month vs. Month-by-Month) – **modeling applied**: - -- There are 10 patients that require 1 bottle for treatment over the course of 6 months; thus, the \# of Planning Units per patient = 6. There is also an expected increase of 5 new patients per month. Using the logic above for calculating “All in the First Month” and “Month-by-Month,” QAT will calculate the following number of bottles to be dispensed over a 12-month period: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
MonthJanFebMarAprMayJunJulAugSepOctNovDec
- # of -
- Patients - 		- 10 - - 15 - - 20 - - 25 - - 30 - - 35 - - 0 - - 0 - - 0 - - 0 - - 0 - - 0 -
All in the First Month6090120150180210000000
Month-by-Month102545701001351251109065350
- -**Total Forecasted (All in the First Month) = 810 Bottles** - -**Total Forecasted (Month-by-Month) = 810 Bottles** - -- **Desire a specific value for number of Planning Units per patient?** A user can specify a specific value for number of Planning Units per unit\* (discrete) or per unit\* per month (continuous) by choosing “No” for “Use QAT's Autocalculation for \# of Planning Units?” Unless overridden by a user, QAT will utilize the auto-calculation by default. (\* In this case, unit could be patient, test, client, etc) - - **Discrete Example:** If every 1 vial of bupivacaine is supposed to be used every 5 procedures, then the number of forecasting units / procedures is 0.2 vials. With a planning unit of 5 vials, QAT calculates that 0.2/5 = 0.04 planning units are used per procedure. However, a user can toggle the radio button to “No” and choose to override this with knowledge of actual usage rates and enter 0.05 planning units. Always add a note when you override QAT’s calculation. - -> ![](/img/media/image298.png) - -- **Continuous Example:** If a patient requires 1 tablet per day indefinitely of TLD 30-tablet bottle, QAT will calculate this as 30.4167/month or 1.0139/day to account for months that have 30 days, 31 days, 28 days, etc. However, a user may choose to toggle the radio button to “No” and choose to override this to 1 planning unit/month. provide the override value of 1. Always add a note when you override QAT’s calculation. - -> ![](/img/media/image299.png) - -- **Repeating Forecasting usages?** If multiple Forecasting Unit nodes share the same settings, consider using the [Usage Template screen](#usage-templates) to save your common usages, and then using the “Copy from Template” field to populate the fields in the forecasting unit nodes. - -- **Aggregate node values for further calculation? (Funnel Nodes):** In some cases, users may want to link the value of one node to another node, or aggregate multiple nodes into one node before adding additional nodes below. \*\*Please note this feature is different than linking nodes via modeling/transfer, which is for linking changes in one node to changes in another node, rather than aggregation. This is also different from using aggregation nodes, which aggregate only upwards, and don’t allow further calculation\*\* - -> Use cases: - -- Viral Load tests are used by various populations, -but all populations will use the same mix of instruments. Start with a demographic -tree which ends in multiple populations. The different populations need to be summed -and the various instrument branches sit under the sum. - -- Malaria Patients enter the health system through -different channels (community health workers vs public health facilities), which -have different testing algorithms, but once a patient tests positive, they receive -the same “mix” of treatments. The different populations testing positive need to -summed and the various treatment regimens sit under the sum - -- Various Contraceptive Methods differ in how they are calculated, but they all derive from the same country population, which needs to be updated each quantification, and may have modeling over time. One tree can be built for implants and injectables, and another built for condoms, but the two trees are linked together at the country population node so their values remain consistent - -How to link values - -1. Indicate (on \# or % nodes) that they are "**source nodes**" ![](/img/media/image300.png) - -> Figure 175 Indicating source nodes - -2. Create new "**funnel nodes**" and select which source nodes to aggregate from. - -> Note: Funnel nodes can “sit” anywhere on the tree – that is, you can make the first node of a tree a funnel node, or build funnel nodes under any aggregation, number of percentage node. This is because the value of funnel nodes does not derive from their parent, but from the sources they are linked to. -> -> ![](/img/media/image301.png) - -Figure 176 Adding funnel nodes - -3. Add any "child" nodes under the funnel nodes - these will likely be the product nodes. - -> Funnel nodes allow for lots of flexibility as they may be used within one tree or multiple trees, can be used on any level, and - -1. User can either link **internally within one tree** - -![](/img/media/image302.png) - -2. Users can link **externally between trees** (source nodes on one tree, funnel nodes on a different tree) - -> ![](/img/media/image303.png) - -### Modeling Validations - -**Purpose:** Once a tree has been built, users can use the Modeling Validation screen to view the change over time. This is useful if the forecast has applied modeling/transfers in one or mode nodes. - -**Using this screen:** - -- Go to ‘Tree Forecast’ and select ‘Modeling Validations’. - -- Select the screen filters using the dropdowns. - - **Program**: You must be online to view program versions on the server. When offline, only downloaded local programs can be selected. - - - **Level**: - - When creating a tree, it is useful to re-name the levels. The ‘level’ dropdown in this screen will show the different level names that you have chosen. This makes it easier to identify what the data is showing, rather than using level 0,1,2,3, etc. - - - The level dropdown will automatically group Planning Unit and Forecasting Unit into it’s own levels in case these nodes are on separate levels of your tree. Therefore, if you also have a level called ‘Forecasting Unit’, selecting the ‘FU’ level and ‘Forecasting Unit’ level will populate the same results. However, if you have a forecasting unit on level 4 and another one on level 5, the ‘FU’ level will show both of those. - - - **X-Axis Display:** The data can be shown by months (default) or aggregated by calendar year or fiscal year. (See Figure 154) - - When aggregating by year, it is helpful to use the ‘Show Data’ feature to confirm which months are included in the aggregated chart, and to confirm if there is data for all the months that are expected - - - When aggregating by fiscal years - you must select the which month your fiscal year starts in. For example, if your Fiscal Year 2023 is from October 2022 to September 2023 – you can select the option that . QAT will always show the examples using the current calendar year. - - - **Y-Axis Display**: The data can be shown by number of units, as well as by percentage. (See Figure 149 versus Figure 147) - -- To view the tabular data, select the ‘**Show Data**’ blue button in the bottom right of the screen. - -- When viewing the **graph**, the user can hide elements by clicking on the legend. To unhide, re-click on that part of the legend. - -- This screen can be **exported** in both CSV and PDF format by selecting the icon(s) in the top right corner. - -![P3366#yIS1](/img/media/image304.png) - -Figure 177: Modeling Validation Screen (by number and month) - -![P3368#yIS1](/img/media/image305.png) - -Figure 178: Modeling Validation Screen (by percentage and month) - -![](/img/media/image306.png)![P3371#yIS1](/img/media/image307.png) - -Figure 179: Modeling Validation Screen (by Calendar Year vs by Fiscal Year) - -### Product Validations - -**Purpose:** Once a tree has been built, users can use the Product Validations screen to check the usage for the products in the forecast tree. This is useful for seeing multiple products at a time. - -**Using this screen:** - -- Go to ‘Tree Forecast’ and select ‘Product Validations’. - -- Select the screen filters using the dropdowns. - - Only downloaded local programs can be selected in this screen. - -- This screen can be exported in both CSV and PDF format by selecting the icon(s) in the top right corner. - -![P3382#yIS1](/img/media/image308.png) - -Figure 180: Product Validations - -### Using Templates - -#### Tree Templates - -**Purpose:** To enable users to begin designing their forecast tree from a pre-established template. _Note: tree templates are managed at the realm (global) level._ - -**Using tree templates:** - -**User can add tree templates in two different locations: ‘Manage Tree’ screen or ‘Tree Templates’ screen. Note: a program must be downloaded in order to create a tree template.** - -**Method 1:** - -1. **Navigate to ‘Tree Forecast’** à **‘Manage Trees’.** - -2. **In the top-right of the screen, click the blue ‘Create or Select’ dropdown and select the desired tree template.** - -3. **In the “Tree Details” Pop-up:** - 1. **Confirm or update the Program, Forecast Method, Tree Name, Regions, and Notes sections.** - - 2. **If there are any planning units that are in the template but are missing from the program, QAT will flag them in a bottom section of this pop-up (see** Figure 150**), wherein a table displays any missing planning units.** - 1. **If there are planning units that are missing in the program (including those inactive or unchecked for Tree Forecast) and are recommended for utilizing the chosen tree template, users can click the “Add/update selected planning units” button and QAT will automatically add the planning units to the user’s program.** - - 2. **If the user would like to create the tree without the recommended planning units, users can click the “Create tree without adding planning units” button and the planning units will not be added to the user’s program. This could be useful when a user would like to utilize a tree structure but have different planning units they would like to forecast.** - -![P3400#yIS1](/img/media/image309.png) - -Figure 181 Tree Details Pop-up with 'Missing Planning Units' - -3. **Note that all of the tree details can be updated at a later stage by clicking the gear icon** ![P3402#yIS1](/img/media/image310.png) **next to the tree dropdown and planning units can be added by navigating to the ‘Update [Planning Units](07-forecasting-module-program-data.md#planning-units)’ screen.** - - - -4. **QAT will automatically create the tree template for the user’s program and navigate to the ‘Build Tree’ screen.** - -**Method 2:** - -1. > **Navigate to ‘Tree Forecast’** à **‘Tree Templates.’** - -> ![P3407#yIS1](/img/media/image311.png) - -Figure 182: Tree Templates Screen - -2. > **Review the different tree template options, paying special attention to the Forecast Method & the Start Node type. Users can click on any row to review the tree template, its structure, and various nodes.** - 1. > **Note: those nodes that start with a Percentage node are used specifically for Branch Templates and cannot be used as a tree template. Users must first create a starting node (Number or Aggregation), before adding a Branch Template (for more information, please see [Branch Templates](#branch-templates)).** - -3. > **Once a user has reviewed the tree template, they can click “Use this template” in the top right corner of the screen.** - -4. > **Continue to follow steps 3-4 from Method 1 to finalize the tree template creation.** - -**General Recommendations on Tree Templates:** - -- **In general, tree templates contain values of “0” and “0%” at all levels except the forecasting and planning unit nodes. User can then customize the tree based on their requirements – for example:** - - **Click each node to edit the values to actual values.** - - - **Rename any node titles.** - - - **Replace any products by either:** - - **editing the forecasting unit node – but be sure to also open the child planning unit node and select the correct planning unit.** - - - **deleting the forecasting & planning unit nodes and adding new ones.** - - - **Copy any nodes or branches (user can copy multiple nodes by copying the top of a branch of nodes).** - - - **Delete any nodes or branches.** - - - **Add notes to explain any information sources.** - -- If there is a Tree Template that would benefit the QAT community, users can request it via the [QAT Ticketing Helpdesk System](02-getting-started.md#tickets-for-addingupdating-users-and-master-data). - -#### Branch Templates - -**Purpose: Branch templates enable users to add a tree template, including the structure and all the various child nodes as a branch** within **a pre-existing tree.** _Note: branch/tree templates are managed at the realm (global) level._ If there is a Tree/Branch Template that would benefit the QAT community, users can request it via the [QAT Ticketing Helpdesk System](02-getting-started.md#tickets-for-addingupdating-users-and-master-data). - -**Using Branch Templates:** - -1. > **Users should first review the different tree/branch template options, paying special attention to the Forecast Method & the Start Node type in the ‘Tree Forecast’** à **‘Tree Template’ screen.** - -2. > **Navigate to ‘Tree Forecasts’** à **‘Manage Trees,’ and select the desired tree.** - -3. > **Click on the** ![P3431#yIS1](/img/media/image312.png) **symbol. This will add the branch template as a child to the selected node.** - 1. > **Based on the parent node chosen, QAT will only display branch templates that are allowed to be added as potential children based on the Start Node in the ‘Tree Template’ screen (see [Node Types & Functions](#node-types-functions) for the potential children options for each node type).** - -![P3433#yIS1](/img/media/image313.png) - -Figure 183: Adding a Branch Template - -4. > **Once a branch template is chosen, click “Add Branch.”** - -5. > **If there are any planning units that are in the branch template, but are missing from the program, QAT will flag them in a bottom section of this pop-up (see** Figure 153**), wherein a table displays any missing planning units.** - 1. > **If there are planning units that are missing in the program (including those inactive or unchecked for Tree Forecast) and are recommended for utilizing the chosen branch template, users can click the “Add/update selected planning units” button and QAT will automatically add the planning units to the user’s program.** - - 2. > **If the user would like to add the branch without the recommended planning units, users can click the “Add branch without adding planning units” button and the planning units will not be added to the user’s program. This could be useful when a user would like to utilize a branch structure but have different planning units they would like to forecast.** - -![P3440#yIS1](/img/media/image314.png) - -Figure 184: Adding PUs from a Branch Template to a Program - -#### Usage Templates - -**Purpose:** Usage templates allow the user to fill in the details for a forecasting unit node all at once. Usage templates can be global or program specific. Note that program-specific templates are managed by forecast program admins. User must be online to manage templates, but can be offline to use them. - -**To use usage templates** - -![P3446#yIS1](/img/media/image315.png) ![P3446#yIS2](/img/media/image316.png) - -Figure 185: Using a Usage Template in a forecasting unit node - -1. **Ensure the program has the planning unit related to the usage template. Remember, usage templates are based on the forecasting unit, but each planning unit is related to a specific forecasting unit. For example, if the program has the planning unit “_Lopinavir/Ritonavir 200/50 mg Tablet, 120 Tablets_”, all usage templates with the associated forecasting unit “_Lopinavir/Ritonavir 200/50 mg Tablet_” will be available when designing the tree.** - -2. **In the Build Tree screen, create or edit an existing forecasting unit node (See Section** **B1for more). If creating a new node, be sure to first select the node type as “forecasting unit”, and double check that the ‘month’ and ‘percentage of parent’ fields are correct.** - -3. **(optional) Select a Tracer category to filter the available usage templates** - -4. **Using the “Copy From Template” dropdown, select the desired usage templates** - -5. **All subsequent fields will be populated** - -6. **Click “Update” to save changes.** - -**To manage usage templates (**forecast program admins only) - -> ![P3456#yIS1](/img/media/image317.png) - -Figure 186: Managing Usage Templates - -1. **Ensure QAT is in online mode and navigate to Tree Templates \> Usage Templates. Global templates will be greyed out and not editable.** - -2. **To create a new usage template, click “add row.” To edit an existing usage template, skip to the next step.** - -3. **Populate or edit the row for the usage template as desired** - - > **The “usage name” column is what will appear in the dropdown.** - - - > **Use the horizontal scroll bar to access all the fields in the table.** - - - > **Use the tooltips (hover mouse over “i" icons) to guide you** - - - > **Use the second to last column “Usage in words” to verify that everything is entered correctly.** - - - > **For products used more than once, there is a calculator to help you convert interval to frequency. Right click on the row you are editing to open the “Calculate Usage Frequency” screen. Enter the interval and desired frequency unit (day, month, week or year) and the calculated frequency number and unit will be populated in the table.** - -> ![P3467#yIS1](/img/media/image318.png) - -Figure 187: **“Calculate Usage Frequency” screen** - -4. **Click “Submit” when finished.** diff --git a/docs/user/08-supply-planning-module-supply-planning.md b/docs/user/08-supply-planning-module-supply-planning.md new file mode 100644 index 0000000..9a97ec2 --- /dev/null +++ b/docs/user/08-supply-planning-module-supply-planning.md @@ -0,0 +1,127 @@ +--- +id: supply-planning-module-supply-planning +title: "Supply Planning Module: Supply Planning" +sidebar_label: "Supply Planning Module: Supply Planning" +sidebar_position: 8 +--- + +# Supply Planning Module: Supply Planning + +## Supply Planning: An Overview +The Supply Planning screen is the central hub where consumption, inventory, and shipments converge to project stock levels. + +**Who:** Realm/Program Admins, Reviewers, and Program Users. +**When:** Any time (Offline support via PWA). + +**Key Interface Features:** +- **Local vs. Server Tabs:** Edit the **Local Supply Plan**; the **Server Supply Plan** is read-only for comparison. +- **Interactive Table:** Click cells to edit data directly or view detailed pop-ups. +- **Dynamic Legend:** Toggle data elements in the graph by clicking legend items. + +### Stock Balance Calculations +QAT uses a standard logic to calculate the monthly progression: + +| Component | Description | Visual Indicator | +| :--- | :--- | :--- | +| **Opening Balance** | Start-of-month stock. | **Bold** = Actual; Regular = Projected. | +| **Ending Balance** | End-of-month stock. | **Bold** = Actual; Regular = Projected. | +| **Unmet Demand** | Stock needed but unavailable. | Captures "negative" stock scenarios. | + +### Stock Status Legend +Stock status is color-coded based on the planning method: +- **Plan by MOS:** Transitions: **Stock Out (Red)** → **Understock (Yellow)** → **Ideal (Green)** → **Overstock (Blue)**. +- **Plan by Quantity (Min/Max):** Color-coded based on user-defined minimum and calculated maximum quantities. + +![Supply Planning Interface](/img/media/image153.png) +*Figure 1: Plan by Months of Stock (MOS) View* + +## Supply Planning: Consumption & Shipments +The Supply Planning table allows granular control over transactions. + +### Consumption +- **Forecasted Consumption:** Purple italic text. +- **Actual Consumption:** Black non-italicized text. + +**To edit consumption:** +1. Click the month's cell in the **Consumption** row. +2. In the pop-up, edit quantities by region. +3. Click **Submit** to update the plan. + +### Shipments +Shipments are aggregated by default. Click the **+** next to **Shipments** to expand into: +- **Suggested:** Auto-calculated by QAT to maintain stock levels. +- **Planned, Submitted, Shipped, Arrived, Received:** Tracked milestones. + +#### Visual Indicators +| Icon | Meaning | +| :--- | :--- | +| **Red Triangle** | Emergency Shipment (within lead time). | +| **Link Icon** | ERP Linked Shipment (read-only). | +| **L Icon** | Local Procurement. | +| **Green Cell** | Multiple shipments in the same month. | + +#### Suggested Shipments Logic +QAT suggests shipments to keep the plan between **Minimum** and **Maximum** levels. +- **Trigger:** If stock falls below Min for 3 consecutive months. +- **Quantity:** Calculates the amount needed to reach the **Max** level. + +**To convert a suggestion to a planned order:** +1. Click the **Suggested** row cell. +2. Update the status and click **Submit**. + +![Shipment Details Pop-up](/img/media/image174.png) +*Figure 2: Editing Shipment Details* + +## Supply Planning: Inventory & Adjustments +Inventory and adjustments can be managed directly from the supply planning table. + +**To add/edit records:** +1. Click the month's cell in the **Adjustments** or **Ending Balance** row. +2. In the pop-up, adjust quantities by region. +3. **Inventory Count:** Entering an inventory count will **bold** the ending balance and override projections. +4. **Adjustments:** Notes are required for all adjustment entries. + +### Projecting Expiries +The **Projected Expired Stock** row highlights potential losses. +- **Action:** Click a cell to see the **Expiry Details**. +- **Correction:** Click the batch number to jump to the source shipment and update the expiry date or quantity. +- **Batch Ledger:** Click the **Expired Quantity** cell to view the full month-by-month history of that batch. + +![Expiry Management Pop-up](/img/media/image189.png) +*Figure 3: Batch Expiry Details* + +## Scenario Planning +Scenario Planning allows users to simulate changes to their supply plan without altering the current version. + +**Available Scenarios:** +- **Consumption Changes:** Increase or decrease forecasted consumption by a fixed percentage. +- **Phase In/Out:** Linear interpolation between two consumption values over a defined period. +- **Shipment Cleanup:** Bulk remove unfunded, planned, or submitted shipments that violate lead times. +- **Re-plan:** Automatically generates new shipments to resolve stock level violations. + +**To use scenarios:** +1. Navigate to **Supply Planning** > **Scenario Planning**. +2. Select a scenario from the dropdown and configure parameters. +3. Click **Add** to visualize the impact. +4. If satisfied, click **Submit** to save the scenario as a new supply plan version. + +![Scenario Planning interface](/img/media/image191.png) +*Figure 4: Comparing Scenarios* + +## Supply Plan Report +The Supply Plan Report provides a comprehensive view of stock status across one or multiple programs. + +### Report Views +- **Single Program:** Detailed view of one program and planning unit. +- **Multi-Program:** Aggregates data for the same planning unit across multiple programs. +- **Equivalency Unit (EU):** Aggregates different planning units using standardized conversion factors (e.g., CYP or ARV Patient Months). + +**Navigation:** **Supply Planning** > **Supply Plan Report**. + +**Key Features:** +- **Tabular & Graphical Views:** Data is presented as both an interactive graph and a detailed data table. +- **Disaggregated Shipments:** See individual shipment details (Funding Source, Status, Procurement Agent) directly in the table. +- **Exporting:** Supports PDF and CSV exports with various aggregation options. + +![Supply Plan Report](/img/media/image193.png) +*Figure 5: Single Program Supply Plan Report* diff --git a/docs/user/09-forecasting-module-reports-and-outputs.md b/docs/user/09-forecasting-module-reports-and-outputs.md deleted file mode 100644 index d2e5f8b..0000000 --- a/docs/user/09-forecasting-module-reports-and-outputs.md +++ /dev/null @@ -1,210 +0,0 @@ ---- -id: forecasting-module-reports-and-outputs -title: "Forecasting Module: Reports and Outputs" -sidebar_label: "Forecasting Module: Reports and Outputs" -sidebar_position: 9 ---- - -# Forecasting Module: Reports and Outputs - -## Compare and Select - -**Purpose:** Enable users to compare all the available forecasts (from tree and consumption methods) and select their final forecast. In this screen, users select their forecasts one planning unit and region at a time. For selecting forecasts across multiple planning units and regions, use the Forecast Summary screen. Users should utilize all tables and graph on this screen for comparing data and choosing a final forecast. - -**Using this screen:** - -1. **Check to make sure all expected forecasts appear in the Compare & Select table. To add forecasts, navigate to the** [Manage Tree](08-forecasting-module-forecasting.md#tree-forecasts) **screen to build a tree forecast or the [Extrapolation](08-forecasting-module-forecasting.md#extrapolation)** **screen to build a consumption-based forecast.** Users may also need to double-check the [Update Planning Units](07-forecasting-module-program-data.md#planning-units) screen to make sure the Consumption Forecast or Tree Forecasts methods have been checked/unchecked for each Planning Unit. - 1. Note: Rows are highlighted gray and non-editable when there is nothing to display or select. - -2. **Review available forecasts for each planning unit using the following information on the screen:** - 1. **Forecast Error (%):** this error is calculated using the Weighted Absolute Percentage Error (WAPE) calculation in the same manner as it is calculated in the Consumption Extrapolation screen. If the forecast error is highlighted in green text, this forecast has the lowest forecast error out of the available forecasts. - -> _Note: the forecast error is not always reliable for tree forecasts – unless a tree forecast has a significant overlap with the past actual data, there may not be past forecast data available for comparison._ - -2. **Compare to Consumption Forecast:** QAT compares available Consumption Forecasts and Tree Forecasts. For any Tree Forecasts, QAT will flag the percentage above the highest or below the lowest Consumption Forecast. The comparison will be highlighted in red text if it is outside of the threshold percentages set by the user in the [Version Settings](07-forecasting-module-program-data.md#version-settings) screen. Assuming reliable actual consumption data, this comparison helps users determine if their Tree Forecasts are comparable to historical consumption. This statistic will not be available for consumption forecasts. - -3. **Graph: Visually compare the different forecasts.** The forecast selected in the top table will appear **bolded** in the graph. - -4. **Detailed Data Table: Compare the data between forecasts side-by-side by clicking the “Show Data” button below the graph. Any bolded**/**_bolded italicized purple_** **data fall within the forecast period.** - -5. **Viewing the forecasts in calendar year or fiscal year aggregations: by default, QAT shows the forecast in monthly figures, but users have the option to view an aggregation of those figures by calendar year or by fiscal year (and defining the start/end of the fiscal year that works in their context).** - 1. **When choosing to view by calendar/fiscal year, a new table appears between the graph and the detailed data table. This new table shows the aggregate forecast values by calendar or fiscal year, and denotes the number of months used in the calculation for that year.** - - - -3. **Select the final forecast in the Compare & Select table. If there is a** ![Warning with solid fill](/img/media/image319.png) **symbol next to the Planning Unit, there is no forecast selected. If there is a** ![Checkbox Checked with solid fill](/img/media/image320.png) **symbol next to the Planning Unit, there is a forecast selected.** - -4. **Repeat steps 1-3 for each Planning Unit and Region until no more** ![Warning with solid fill](/img/media/image319.png) **symbols remain. Once completed, continue forward to the** [Monthly Forecasts](#monthly-forecast) **to verify all planning units together.** - -**_Note: Users may select multiple tree forecasts as their final forecast, which will aggregate the monthly forecast quantities; however, users cannot select multiple consumption forecasts or a combination of consumption and tree forecasts._** - -**Tips on Using the Graph & Detailed Data Table:** - -- A user may view the graph in Planning Unit, Forecasting Unit, [Equivalency Unit](07-forecasting-module-program-data.md#equivalency-units), and for a specific period of time. If a user chooses to “Show only Forecast Period,” the graph will display only the period of time the user chose as the forecast period in the Version Settings screen. - -- By default, QAT will display all available forecasts by Planning Unit and any actuals entered or imported from QAT Supply Planning module in the graph; however, a user may deselect the “Display?” checkbox for any forecasts in the top table if they do not wish to view it in the graph. - -- Like the graph on the Consumption Extrapolation screen, the user may choose to display the ‘backwards’ forecast. Note that if you choose this option, that will bring back the “Actuals (adjusted) line. - -## Monthly Forecast - -**Purpose**: Enable users to view the final (_selected_) forecasts for a single program, and displays the forecast by planning unit and month. This output aggregates all regional forecasts into one total forecast. To view disaggregated regional forecasts, users can export the output as a CSV. This report is great for verifying all planning units in one place, as it has multiple report view options: - -- Planning Unit or Forecasting Unit - -- Aggregated by Equivalency Unit - -- Monthly or yearly graph & tabular data - -![P3495#yIS1](/img/media/image321.png) - -Figure 188: Monthly Forecast Displayed with Y--axis in EUs - -![P3497#yIS1](/img/media/image322.png) - -Figure 189: Monthly Forecast Tabular Data - -**Using this screen**: - -- _Only selected forecasts will be shown in this output. To select a forecast for a product, go to the ‘_[Compare and Select Forecast](#compare-and-select)’ screen. To see total forecasts across products, go to the ‘[Forecast Summary](#forecast-summary)’ screen. - -- *T*he **Report Period** will be used to determine the period of time that will display in the graphical/tabular output and must be within the forecast period. - -- Use the parameters to view the graph/tabular data either by forecasting units or planning units as well as showing the y-axis in equivalency units. - -- **Equivalency Units** (EUs) allow users to aggregate data across planning units or forecasting units that are different but have the same equivalency unit. See [Equivalency Units](07-forecasting-module-program-data.md#equivalency-units) for more information. - -- The ‘X-axis Aggregate By Year’ filter allows you to view the data aggregated by year instead of by month. - -- For the graph view, there are 3 ways you can hide which planning units that are being displayed: - 1. Use the filter at the top to select the planning unit(s). - - 2. Click on a planning unit in the legend of the graph. - - 3. Uncheck the ‘Display’ checkbox on the far left of the tabular view. - -## Forecast Summary - -**Purpose**: Enable users to see a summary of their final (selected) forecasts for the entire forecast period. To view the forecasts by month, use the ‘[Monthly Forecast](#monthly-forecast)’ screen instead. - -- **Regional View:** Use this view to see your forecast across planning units and regions. Directly update the forecast method for every region-planning unit combination and add notes in the table, if desired. Forecast selections can also be updated in the ‘[Compare and Select Forecast](#compare-and-select)’ screen. - -- **National View:** Use this view to see your forecast at a national level and evaluate your procurement surplus or gaps. - -### Regional View - -1. **Utilize the dropdowns at the top of the screen to select the Program and Version** - -2. **Ensure the “Regional View” radio button under Display.** - -3. **View a summary of all the planning units, their select forecast quantity and the notes, by region.** - -4. **(if a local version is selected), user can update the selected forecast by double clicking any of the cells under the “Selected Forecast” column as well as any notes in the “Notes” column.** - -![P3518#yIS1](/img/media/image323.png) - -Figure 190 Forecast Summary - Regional View - -### National View - -![P3521#yIS1](/img/media/image324.png) - -Figure 191 Forecast Summary - National View - -1. **Utilize the dropdowns at the top of the screen to select the Program and Version** - -2. **Ensure the “National View” radio button under Display.** - -3. **View the resulting surplus gap analysis. _Note: This is not a full supply plan, but a high-level procurement surplus/gap analysis. We recommend importing your forecast into the supply planning module for granular supply planning._** - -4. **Click the “hide calculations” checkbox to see a simplified version of the table.** - -5. For the data to display here properly, enter the following data: - 1. Under [Update Planning Unit](07-forecasting-module-program-data.md#planning-units): - 1. **Stock** – at the beginning of your forecast period - - 2. **Existing shipments** – during your forecast period - - 3. **Desired Months of stock** – at the end of your forecast period - - 4. **Price Type** and **Unit Prices** - - 2. Under [Update Version Settings](07-forecasting-module-program-data.md#version-settings): - 1. **Freight %** - Freight cost is calculated as a percentage of product cost - -**Formulas used to calculate the Procurement Surplus/Gap** - -- Project Stock at Forecast end = (Starting Stock) + (Existing Shipments) - (Forecasted Quantity) - -- Desired Stock at Forecast end = (Forecasted Quantity \* Desired Months of Stock) / (Number of Months in Forecast Period) - -- Procurement Surplus/Gap = (Projected Stock at Forecast end) - (Desired Stock at Forecast end) - -For example, a forecast from Jan 2021 to Dec 2023 (36-month forecast) - - - - - - - - - - - - - - - - - - - - - - - - -
- Total Forecasted Quantity - - Stock
(end of Dec 2020) - 		- Existing Shipments (Jan 2021 - Dec 2023) - - Stock
(end of Dec 2023) - 		- Desired Months of Stock
(end of Dec 2023) - 		- Desired Stock
(end of Dec 2023) - 		- Procurement Surplus/Gap -
360,0005,00020,000 -

5,000 + 20,000

-

- 360,000

-

= -335,000

- 		5 -

(360,000 * 5) / 36

-

= 50,000

- 		-

-335,000 -50,000

-

= -385,000

-
- -**Formulas used to calculate the Procurement Costs** - -_Note: the cost is only calculated if there is a procurement gap, not if there is a surplus_ - -- Product Cost = Procurement Gap \* Unit Cost - -- Freight Cost = Product Cost \* Freight Percentage - -- Total Cost = Product Cost + Freight Cost - -For the example above, assuming a unit cost of 0.10 USD and a freight % of 7%: - -- Product Cost = -385,000 \* 0.10 = $38,500 - -- Freight Cost = $38,500 \* 7% = $2,695 - -- Total Cost = $38,500 + $2,695 = $41,195 diff --git a/docs/user/09-supply-planning-module-reports.md b/docs/user/09-supply-planning-module-reports.md new file mode 100644 index 0000000..a294989 --- /dev/null +++ b/docs/user/09-supply-planning-module-reports.md @@ -0,0 +1,141 @@ +--- +id: supply-planning-module-reports +title: "Supply Planning Module: Reports" +sidebar_label: "Supply Planning Module: Reports" +sidebar_position: 9 +--- + +# Supply Planning Module: Reports + +QAT reports allow the user to extract and view their supply planning data in graphs, tables, and other visual formats. The user will also be able to navigate, sort, filter, and view the data for specific needs. QAT reports produce visualizations and display data in a way that can support decision making. + +The reports are divided into **Global Reports** and **Program-specific Reports**. Program-specific Reports are shown offline, as well as online. However, the Global Reports are shown only in online mode and are only available to Global Users, such as the Realm Administrator and the Application Administrator. + +**Note:** All QAT reports have the ability to be exported into an Excel CSV file as well as PDF format. Additionally, all graphs allow for the user to hover over a visual for a tool tip with more information. + +## QAT Problem List +The **QAT Problem List** is a built-in quality assurance tool. It identifies data inconsistencies and supply planning issues that must be addressed before a supply plan can be finalized and uploaded. + +**Key Features:** +- **Recalculate:** Refresh the list after making data entry changes. +- **Criticality Levels:** Items are flagged as **High (Red)**, **Medium (Orange)**, or **Low (Yellow)**. +- **Audit Trail:** Right-click a problem to view internal notes and review history. + +### Problem Statuses +| Status | Definition | Action Required | +| :--- | :--- | :--- | +| **Open** | Default state for new or auto-flagged issues. | Requires data entry or a note. | +| **In-Compliance** | Issue resolved automatically via data entry. | None (auto-closed). | +| **Addressed** | Issue acknowledged with an explanatory note. | Note is mandatory. | +| **Resolved** | Reviewer confirms the issue is permanently handled. | Reviewer-only status. | +| **Reviewed** | Reviewer has inspected the entry. | Reviewer-only status. | + +### Common Problems & Solutions +- **Missing Data:** Actual consumption or inventory counts missing in the last 3 months. *Solution: Enter missing data.* +- **Forecast Gaps:** Missing forecast values within the next 18 months. *Solution: Enter forecast or zeros if phasing out.* +- **Past Shipments:** Shipments with "Received" dates in the past that are still marked as "Ordered" or "Shipped". *Solution: Update status to "Received".* +- **Lead Time Violations:** Shipments that should have been submitted by a certain date. *Solution: Update status or push back receipt date.* +- **Stock Violations:** Plan falls below Minimum or above Maximum parameters. *Solution: Adjust shipments or consumption.* + +![QAT Problem List Interface](/img/media/image198.png) +*Figure 1: High-level view of the Problem List* + +## Program Catalog +The **Program Catalog** provides a standardized list of all Planning Units and Forecasting Units within a program, including their corresponding attributes. + +**Navigation:** **Reports** > **Program Catalog**. + +## Stock Status Reports +These reports provide different perspectives on stock health over time. + +### Stock Status Over Time +Visualizes inventory levels for one or more planning units across a defined period. +- **Tip:** Limit the selection to fewer than 10 products to maintain graph clarity. + +### Stock Status Matrix +Provides a high-level "heatmap" of stock status (MOS or Quantity) in a grid format. +- **Visual Coding:** + - **Red:** Stocked Out. + - **Orange:** Understocked. + - **Green:** Ideal. + - **Yellow:** Overstocked. + - **Grey:** N/A (Missing data). + +### Stock Status Snapshot +A point-in-time view (single month) of all planning units in a program. + +### Stock Status Snapshot (Global) +Similar to the Snapshot but allows for cross-program comparisons (Realm-level access). + +![Stock Status Matrix](/img/media/image209.png) +*Figure 2: Stock Status Matrix Heatmap* + +## Consumption Reports +These reports analyze how products are being used compared to forecasts. + +### Consumption (Global) +Visualizes consumption across multiple countries to identify regional trends. + +### Forecast Error (Monthly & by Planning Unit) +Analyzes forecast accuracy using the **Weighted Average Percent Error (WAPE)** method. + +**Key Metrics & Features:** +- **Visuals:** Red bars (Actual), Blue bars (Forecast), Green line (Error %). +- **Thresholds:** Error percentages exceeding the Program Admin's set threshold are highlighted in **Red**. +- **Adjusted Consumption:** Toggle to see consumption adjusted for stock-out days. +- **WAPE Formula:** Measures the absolute deviation of forecast from actual, weighted by total volume. + +![Forecast Error Report](/img/media/image213.png) +*Figure 3: Forecast Error (Monthly) with Threshold* + +## Shipment Reports +These reports track procurement volume, costs, and logistics. + +### Shipment (Global & Overview) +Aggregates procurement data by funding source, agent, and country. +- **Global:** Cross-country view of quantities and costs. +- **Overview:** High-level summary using pie charts for funding source distribution. + +### Shipment Details & Cost Details +Provides granular lists of shipments with status and financial breakdowns. +- **Summary Table:** Costs per funding source for the selected period. +- **Detailed Table:** Disaggregated by planning unit and shipment status. + +### Budget Report +Tracks spending against predefined program budgets. +- **Visuals:** Shows allocated vs. remaining funds. +- **Multi-Program:** Supports budgets shared across multiple programs. + +### Procurement Agent Lead Time +A reference report showing established lead times for each agent/planning unit combination. + +![Shipment Details Report](/img/media/image221.png) +*Figure 4: Detailed Shipment Tracking* + +## Inventory Reports +These reports monitor stock on hand, expiry risks, and warehouse capacity. + +### Expiries Report +Provides estimated quantities of products expiring in the future based on batch/shelf life. +- **Projection:** Calculates expiry based on stock projections and forecast consumption. +- **Interactive:** Click an expired quantity to open the **Batch Ledger**. + +### Cost of Inventory +Calculates the estimated value of stock on hand (actual or projected) based on catalog prices. + +### Inventory Turns +Measures the velocity of the supply chain (effectiveness of management). +- **Planned Turns:** Target turns based on MIN and Reorder Interval settings. +- **Actual Turns:** Calculated based on average stock and consumption. +- **Interpretation:** High turns generally indicate a healthier, more responsive supply chain. + +### Stock Adjustment Report +Lists all manually entered stock adjustments. +> [!NOTE] +> Automatically calculated adjustments (from inventory count discrepancies) are not shown here. + +### Warehouse Capacity +Displays storage volume (m³) utilization by region or country. Requires Realm-level access for the Global view. + +![Warehouse Capacity Report](/img/media/image232.png) +*Figure 5: Regional Warehouse Capacity Utilization* diff --git a/docs/user/10-annex-1-application-realm-administrator-manual.md b/docs/user/10-annex-1-application-realm-administrator-manual.md deleted file mode 100644 index dbe0959..0000000 --- a/docs/user/10-annex-1-application-realm-administrator-manual.md +++ /dev/null @@ -1,1384 +0,0 @@ ---- -id: annex-1-application-realm-administrator-manual -title: "Annex 1: Application & Realm Administrator Manual" -sidebar_label: "Annex 1: Application & Realm Administrator Manual" -sidebar_position: 10 ---- - -# Annex 1: Application & Realm Administrator Manual - -## Introduction - -While the focus of the user manual is to guide program administrators and users on how to supply plan in QAT, the objective of this annex is to provide guidance on functionalities available to application and realm administrators only. Application masters are mainly available to the App Administrator (with a few exceptions), while Realm Level Masters are available to both App and Realm Administrators. - -## Application Dashboard - -The functions available on the Forecasting Application Dashboard will be visible according to the **user’s role**. Below is an explanation of the tiles unique to App and Realm Level Admins. For an explanation of other tiles (tickets and program), please see [Navigation and Menu Bar](02-getting-started.md#navigation-and-menu-bar). See [QAT Dashboard](02-getting-started.md#qat-dashboard) for information on the enhanced supply planning dashboard. - -In the screenshot below, the role assigned is “**App Level Admin**”. - -![P3582#yIS1](/img/media/image326.png) - -Figure 192: App Level Admin Dashboard - -In the screenshot below, the role assigned is “**Realm Level Admin**”. - -![P3585#yIS1](/img/media/image327.png) - -Figure 193: Realm Level Admin Dashboard - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Which Admins? - - Screenshot - - Explanation -
App & Realm -

Program user

-

- P3593C5T35#yIS1 -

- 		- This tile displays the number of users in each role. - Clicking on the pull-down button displays two functions (“Go to User - Management” and “Add User”). Both redirect users to the “Application - Masters” > “User” (See Users for more) -
App -

Total Realms

-

- P3598C8T35#yIS1 -

- 		- This tile displays the total number of realms in the - app. Clicking on the pull-down button displays two functions (“Go to - Realm Management” and “Add Realm”). Both redirect users to the Realms - screen, which is also accessible in the left menu under - Application Masters > Realms (See - Realm for more) -
App -

Language

-

- P3603C11T35#yIS1 -

- 		- This tile displays the number of languages in the app. - Clicking on the pull-down button displays two functions (“Go to Language - Management” and “Add Language”). Both redirect users to the Language - screen, which is also accessible in the left menu under - Application Masters > Language (See - Language for more) -
Realm -

Country

-

- P3608C14T35#yIS1 -

- 		- This tile displays the number of countries in the - realm. Clicking on the pull-down button displays two functions: “Go to - Realm Country Management” brings users to a table of countries, which is - also accessible in the left menu under Realm Masters > - Country. “Add Realm Country” brings users to the Realm screen, - which is also accessible in the left menu under - Application Masters > Realm, where users can map - countries to the realm. (See Realm Country for - more) -
Realm -

Technical Area

-

- P3613C17T35#yIS1 -

- 		- This tile displays the number of technical areas in the - realm. Clicking on the pull-down button displays two functions (“Go to - Technical Area Management” and “Add Technical Area”). Both redirect - users to the Technical Area screen, which is also accessible in the left - menu under Application Masters > Technical Area - (See Technical Area for more) -
Realm -

Region

-

- P3618C20T35#yIS1 -

- 		- This tile displays the number of regions in the app. - Clicking on the pull-down button displays two functions (“Go to Region - Management” and “Add Region”). Both redirect users to the Language - screen, which is also accessible in the left menu under - Application Masters > Region. (See - Realm Country for more) -
Realm -

Organization

-

- P3623C23T35#yIS1 -

- 		- This tile displays the number of organizations in the - app. Clicking on the pull-down button displays two functions (“Go to - Organization Management” and “Add Organization”). Both redirect users to - the Language screen, which is also accessible in the left menu under - Application Masters > Organization. (See - Organization for more) -
Realm -

Total Program

-

- P3628C26T35#yIS1 -

- 		- This tile displays the number of programs in the app. - Clicking on the pull-down button displays (“Go to Program Management”, - which redirects users to the Update Program Info screen, which is also - accessible in the left menu under Program Management > - Update Program Info. (See - Program Information for more) -
Realm -

Setup Program

-

- P3633C29T35#yIS1 -

- 		- This tile allows users to click on the pull-down button to navigate to - the “Setup Program” screen, which is also accessible in the left menu - under Program Management > Setup Program. (See - Setting up a new program for - more) -
- -Table 11 : App and Realm Admin Tiles - -## Managing Master Data - -**Application Masters** is the top-most data hierarchy level in QAT. Application master data applies to all the Realms and Programs within QAT. Most of it is only accessible to Application Admins, though a few of the Application functions are available to Realm Admins such as adding and updating users and assigning roles to users. Application Admins can select the specific application-wide master data they want to add or update. - -**Realm Level Masters** covers all the master data for that Realm which apply to its programs and supply plans. The Realm Admin will be able to view, create and edit this master data. Programs, Technical Areas, Planning Units and Procurement Agents are a few examples of realm master data that the Realm Admin can add and maintain. A lot of the realm level masters are accessible for viewing to Program Admins; however, they do not have the ability to add/update this data. - -**Program Level Masters** is the third level of hierarchy in QAT. While program admins cannot add programs, they can update the program information (e.g., lead times, freight costs, etc.) within their assigned program(s). Program Admin and Program Users can also add and update the program’s data (consumption, inventory, shipments). - -### Application Masters - -#### Database Translation - -![](/img/media/image337.png)The database translation screen, which is accessible for application admins is used to translate "Dynamic labels" that are stored in QAT. The dynamic labels are included in drop-down lists throughout QAT as well as be labels that reference other labels (e.g. QAT Problem List problems that reference shipment IDs). - -For every dynamic label, there must be at least an English translation as identified by the red asterisk next to ‘English’ in the below figure. The translations for the other software languages are highly recommended but not required to save a translation. - -To edit a translation, double-click that cell and input the desired text. Then click the “Submit” button. The submitted translation(s) will not be changed on the front end in QAT until the next software release. - -![](/img/media/image338.png) - -#### Label Translation - -The Label translation screen is used to translate "static labels" that do not reference other QAT labels and are not part of drop-down lists. Table column headers are an example of a static label in QAT. - -For the static labels, there must be at least an English translation as identified by the red asterisk next to ‘English’ in the below figure. The translations for the other software languages are highly recommended but not required to save a translation. - -To edit a translation, double-click that cell and input the desired text. Then click the “Submit” button. After you click submit, the translation will immediately reflect in QAT for all users. - -![P3667#yIS1](/img/media/image339.png) - -Figure 195: Label Translation Screen - -#### Country - -QAT displays a Country table listing all default countries in the application, but new countries can be added, as needed. - -**To view a list of the current countries that are in QAT:** - -1. Go to “Application Masters” and click on “Country.” - -2. The application administrator can view and filter the countries by their status of “Active” or Disabled.” Additionally, the user can search for a specific country by using the search bar. - -![P3676#yIS1](/img/media/image340.png) - -Figure 196: List of Countries - -**To add a country:** - -1. In the top right corner of the country list, click on the “+” icon. - -2. A new screen “Add Country” will be opened as shown below. - -3. Enter the new Country, Country Display Name, Country Display Name2, and Currency and click on the “Submit” button. - 1. **Note**: Country Display Name is always the three-letter country code (e.g., Angola = AGO). Country Display Name2 is always the two-letter country code (e.g., Angola = AO). - -![P3684#yIS1](/img/media/image341.png) - -Figure 197: Add Country Screen - -**To update a country:** - -1. To update a current country, go to the Application Admin country list. - -2. Click on the country that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. This can include “disabling” a country or making one “active.” - -![P3691#yIS1](/img/media/image342.png) - -Figure 198: Update Country Screen - -#### Currency - -**To view a list of the current currencies that are in QAT:** - -1. Go to “Application Masters” and click on “Currency.” - -2. A list of currencies and their attributes, such as conversion rate will be shown as below: - -![P3698#yIS1](/img/media/image343.png) - -Figure 199: Currency List - -**To add a currency:** - -1. In the top right corner of the currency list, click on the “+” icon. - -2. A new screen “Add Currency” will be opened as shown below. - -3. Enter the new Currency, Currency Display Name, Conversion Rate to 1 USD, and whether it should Sync Online. When all information has been entered, click on the “Submit” button. - 1. **Note:** The conversion rate to 1 USD can be entered manually or it can be obtained from the integration with the public online source by selecting “Yes” on the “Sync online conversion rate”, which is the default. - -![P3706#yIS1](/img/media/image344.png) - -Figure 200: Add Currency Screen - -**To update an existing currency:** - -1. To update an existing currency, go to the Application Admin currency list. - -2. Click on the currency that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. - -#### Dimension - -Dimensions denote various measurable values, such as length, volume, weight, or height. - -**To view a list of the current dimensions that are in QAT:** - -1. Go to “Application Masters” and click on the “Dimension.” - -2. A list of dimensions will be shown as below: - -![P3719#yIS1](/img/media/image345.png) - -Figure 201: List of Dimensions - -**To add a dimension:** - -1. In the top right corner of the Dimension List, click on the “+” icon. - -2. A new screen “Add Dimension” will be opened as shown below. - -3. Enter the new dimension and click on the “Submit” button. - -![P3726#yIS1](/img/media/image346.png) - -Figure 202: Add Dimension Screen - -**To update a dimension:** - -1. To update a current dimension, go to the Application Admin dimension list. - -2. Click on the dimension that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. - -#### Language - -QAT is available in four different languages: English, French, Spanish, and Portuguese. - -**To view a list of the current languages that are in QAT:** - -1. Go to “Application Masters” and click on the “Language.” - -2. A list of languages will be shown as below: - -![P3738#yIS1](/img/media/image347.png) - -Figure 203: List of Languages - -**To add a language:** - -1. In the top right corner of the language list, click on the “+” icon. - -2. A new screen “Add Language” will be opened as shown below. - -3. Enter the new Language and the Language Display Name and click on the “Submit” button. - -4. **Note:** All QAT database and display labels must be translated in order for a new language to appear across QAT. Please see [Database Translation](#database-translation) and [Label Translation](#label-translation) in Appendix 1 for more information. - -![P3746#yIS1](/img/media/image348.png) - -Figure 204: Add Language Screen - -**To update a language:** - -1. To update a current language, go to the Application Admin language list. - -2. Click on the language that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. This can include “disabling” a language or making one “active.” - -#### Roles - -Application Administrators are able to create and edit role types for the entire application as the need arises to modify the business rules that certain roles can access. For a list of the current roles, access, and associated functions, please see [Annex 3: User Role Matrix](12-annex-3-user-role-matrix.md#annex-3-user-role-matrix). - -**To view a list of the current roles that are in QAT:** - -1. Go to “Application Masters” and click on the “Roles.” - -2. A list of roles will be shown as below: - -![P3759#yIS1](/img/media/image349.png) - -Figure 205: Current list of roles - -**To add a role:** - -1. In the top right corner of the role list, click on the “+” icon. - -2. A new screen “Add Role” will be opened as shown below. - -3. Enter the new Role, Business Function, and Can Create Role and click on the “Submit” button. - -4. For a description and more information on individual business functions, see [Annex 4: Business Functions](13-annex-4-business-functions.md#annex-4-business-functions) - -5. “Can Create Role” allows the new role to create users and assign them to specific roles and access. For example, a Realm Admin can create a user, assign them as a Program Admin, and determine which countries and programs the user will have access to. - -![P3768#yIS1](/img/media/image350.png) - -Figure 206: Add Role Screen - -**To update a role:** - -1. To update a current role, go to the Application Admin role list. - -2. Click on the role that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. - -4. For a description and more information on individual business functions, see [Annex 4: Business Functions](13-annex-4-business-functions.md#annex-4-business-functions) - -5. “Can Create Role” allows the new role to create users and assign them to specific roles and access. For example, a Realm Admin can create a user, assign them as a Program Admin, and determine which countries and programs the user will have access to. - -![P3776#yIS1](/img/media/image351.png) - -Figure 207: Edit Role Screen - -#### Realm - -QAT is subdivided into realms, each one governed by their own master data (inclusive of product catalog, funder names, procurement agent names, etc.). Future realms could be set up for other fields such as education supply chains, agriculture supply chains, etc. For information and functions that can be performed by a Realm Admin, see [Realm Level Masters](#realm-masters). - -**To view a list of the current realms that are in QAT:** - -1. Go to “Application Masters” and click on the “Realm.” - -2. A list of realms will be shown as below: - -![P3784#yIS1](/img/media/image352.png) - -Figure 208: List of Realms - -**To add a realm:** - -1. In the top right corner of the realm list, click on the “+” icon. - -2. A new screen “Add Realm” will be opened as shown below. - -3. Enter the new Realm, Realm Display Name, Min Guardrail for MIN MOS, Min Guardrail for MAX MOS, and Max Guardrail for MAX MOS. Continue to add all tolerance and restriction values for the realm and then click on the “Submit” button. - 1. When adding a user to QAT, if they are not assigned a realm, they will be automatically assigned to the realm that is considered the “default.” There can only be one default realm per QAT instance. - - 2. **Note**: the MIN/MAX guardrails are the absolute inferior and superior limits for setting program MIN/MAX parameters; they are set at the realm level. This means a program cannot have a MIN MOS that is less than the “Min guardrail for MIN MOS”, or a MAX MOS that is greater than the “Max guardrail for MAX MOS” - -![P3793#yIS1](/img/media/image353.png) - -Figure 209: Add Realm screen - -**To update a realm:** - -1. To update a current realm, go to the Application Admin realm list. - -2. Click on the realm that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. This can include “disabling” a realm or making one “active.” - -**To add a country to a realm** - -1. > To add a country an existing realm, go to the Application Admin realm list - -2. > Right click on the realm and then click on “Map countries to this realm” as shown below: - -![P3804#yIS1](/img/media/image354.png) - -Figure 210: Map Countries - -3. From this new window, the application admin can add a country by clicking the “Add Row” button at the bottom of the screen. The new country cannot already exist in the realm to be added. For more information on how to add a country see Application Masters: [Country](#country). - -4. From this new window, the application admin can also make a country “Active” as programs are on-boarded to QAT, or inactive by using the checkbox in the last column. - -5. When all updates and changes have been made, click “Submit.” - -![P3810#yIS1](/img/media/image355.png) - -Figure 211: Mapping countries to a Realm - -#### Users - -Adding and updating users and their roles/access controls is available to both application administrators and realm administrators. - -**To view a list of the current user that are in QAT:** - -1. Go to “Application Masters” and click on the “User.” - -2. A list of users will be shown, along with information, such as email, last login date, and status. - -**To add a new user:** - -1. ![](/img/media/image356.png)In the top right corner of the realm list, click on the “+” icon. - -2. A new screen “Add User” will be opened as shown below. - -3. Enter the new user’s name, email address, organization & country, role, and language and click “Submit.” - -4. For a detailed description on roles, their function, and access, see [Annex 3: User Role Matrix](12-annex-3-user-role-matrix.md#annex-3-user-role-matrix) - -**To update an existing user or manage user access controls:** - -1. Navigate to the user list. - -2. Click on the user that needs to be changed or updated. - -3. Update the information or access controls as needed and then click on the “Update” button. This can include “disabling” a user or making one “active.” - -#### Usage Period - -Usage period is used in the forecasting module for users to associate a time period with certain elements of the forecast (e.g. how often a planning unit is used). - -**To view a list of the current units that are in QAT:** - -1. Go to “Application Masters” and click on “Usage Period.” - -2. A list of usage periods and their attributes, such as whether it’s active or not will be shown as below: - -![P3836#yIS1](/img/media/image357.png) - -Figure 2136: List of Usage Periods - -**To add a usage period:** - -1. In the bottom right corner of the unit list, click on the “+ Add Row” button. - -2. A new row appear. - -3. Enter the usage period name, conversion factor, and click on the “Submit” button. - -**To update an existing usage period:** - -1. To update an existing usage period, go to the Application Admin usage period list. - -2. Double-Click on the usage period name or conversion factor that needs to be changed or updated. To de-activate or re-activate, select the checkbox. - -3. Update the information as needed and then click on the “Submit” button. This can include “disabling” a usage period or making one “active.” - -#### Unit - -Unit is a fixed quantity (in this case a value like mL, gm or even Box) used as a standard of measurement. - -**To view a list of the current units that are in QAT:** - -1. Go to “Application Masters” and click on “Unit.” - -2. A list of units and their attributes, such as dimension will be shown as below: - -![P3855#yIS1](/img/media/image358.png) - -Figure 214: List of Units - -**To add a unit:** - -1. In the top right corner of the unit list, click on the “+” icon. - -2. A new screen “Add Unit” will be opened as shown below. - -3. Enter the new Unit, Unit Display Name, and its corresponding Dimension and click on the “Submit” button. - -**To update an existing unit:** - -1. To update an existing unit, go to the Application Admin unit list. - -2. Click on the unit that needs to be changed or updated. - -3. Update the information as needed and then click on the “Update” button. This can include “disabling” a user or making one “active.” - -![P3866#yIS1](/img/media/image359.png) - -Figure 215: Updating a Unit Screen - -#### Upload User Manual - -The user manual can be uploaded at any time by an application admin. - -**To upload a new version:** - -1. Go to “Application Masters” and click on “Upload User Manual” - -2. Click on ‘Select File’ or ‘Browse’ - -3. Select the user manual you want to upload, from your computer. Note that the file must be in PDF format. - -4. Click “Submit”. - -### Realm Masters - -The QAT application is subdivided into Realms, each with their own master data (inclusive of product catalog, funder names, procurement agent names, etc.) Realm is the second level of hierarchy in the QAT system. - -A Realm covers all the programs and their supply plans. For example, “Global Health” is a Realm under which various programs are managed. Other realms could be set up for other fields such as education supply chains, agriculture supply chains, etc. - -#### Country - -**The Country menu under Realm Level Masters allows Application and Realm Admins to create/assign regions to previously created countries.** - -**A region could be “National” for single-region programs, or it could be any number of regions for multi-region programs. The** decision to add regions depends on how inventory and consumption data will be entered into QAT. Note that QAT shipments are always National and may not be attributed to Regions. - -1. Go to “Realm Level Masters”. - -2. Click on “Country” and the screen below will be shown. - -3. Right click on a specific country that needs to be updated. - -4. Click on “Map Region” to show the Realm Country Region screen. - -![P3891#yIS1](/img/media/image360.png) - -Figure 216: Mapping regions to a country within a realm - -5. Enter a Region description as well available warehouse volume and Global Location Number (GLN) of your warehouse. - -6. Select the status (“Active” or “Disabled”) as shown in the screen. - 1. **Note:** To add multiple regions, click the blue “+ Add row” button, or right-click on the form and select “Insert new row before” or “Insert new row after”. - -7. Click “Submit” to save your changes or “Cancel” to close the form without saving. - -![P3898#yIS1](/img/media/image361.png) - -Figure 217: Adding multiple regions to a country - -#### Data Source - -A data source is the location where data that is being entered into QAT originates from. Users should apply data sources to all transactional records (Consumption, Inventory, Adjustments and Shipments) in QAT. The user selects data sources as required from drop down lists. The selection of data sources for each transactional record will depend on which Data Source Type that applies to that type of transactional record. **Application and Realm Admins** can add/edit Data source(s) as follows: - -**Add a Data Source** - -Go to the top right corner in the “Data Source” screen and click on the blue “+” icon. - -1. > A new screen showing “Add Data Source” will appear. - -2. > Enter the required details and click on the “Submit” button. - -3. > Click on the “Cancel” button to not add the data source. - -![P3909#yIS1](/img/media/image362.png) - -Figure 218: Adding a data source - -**Update Data Source** - -1. > Go to the “Data Source” screen. - -2. > Click on the data source row that you want to update. - -3. > A new screen showing “Update Data Source” will appear. - -4. > Enter the updated details. - -5. > If you want to activate/de-activate that data source, select the corresponding circle. - -6. > Click on the “Submit” button. - -7. > Click on the “Cancel” button to keep the existing information. - -#### Data Source Type - -Refers to the type of data a source is providing information for. There are four data source types: actual consumption, forecast consumption, inventory, shipments. **Application and Realm Admins** can add/edit Data Source Type. - -**Add Data Source Type** - -1. > Go to “Realm Level Masters” and then on “Data Source Type” to show the below table. - -![P3924#yIS1](/img/media/image363.png) - -Figure 219: Data Source type - -2. > Click on the blue “add” button on the top right corner. A new screen showing “Add Data Source Type” will be opened. - -![P3928#yIS1](/img/media/image364.png) - -Figure 220: Add Data Source type - -3. > Enter the required details and click on the “Submit” button. - -**Update Data Source Type** - -1. > Go to the Data Source Type List. - -2. > Click on any parameter that needs to be changed or updated. - -3. > Click on the “Update” button. - -#### Funding Source - -Funding Source refers to the entity providing funding for procurement for the program. **Application and Realm Admins** can add/edit Funding Sources. - -To add a Funding Source - -1. > Go to “Realm Level Masters” and click on “Funding Source” to display the list of current funding sources. - -![P3943#yIS1](/img/media/image365.png) - -Figure 221: Realm-level funding sources - -4. > Click on the blue “+” (add) button below the profile icon. - -5. > A new screen “Add Funding Source” opens. - -6. > Enter the required details and click on the “Submit” button to save your changes or “Cancel” to close the form without saving. - -![P3949#yIS1](/img/media/image366.png) - -Figure 222: Add Funding Source - -**To update a Funding Source** - -1. > Go to the Funding Source List. - -2. > Click on the funding source that needs to be changed or updated. - -3. > Enter the required information and click on the “Update” button. - -![P3956#yIS1](/img/media/image367.png) - -Figure 223: Update Funding Source - -#### Manufacturer - -The manufacturer of a commodity is master data that is not accessible/visible to main users of QAT. However, they are part of shipment/order data that can/will be received from order management systems along with manufacturer-specific commodity attributes. - -**To add a manufacturer** - -1. > Go to “Realm Level Masters” and then click on “Manufacturer” to display the below table. - -![P3964#yIS1](/img/media/image368.png) - -Figure 224: Realm-level Manufacturers - -2. > Click on the blue “+” button to open a new “Add Manufacturer” screen. - -3. > Enter the required details. - -4. > Click “Submit” to save changes or “Cancel” to close the form without saving. - -![P3970#yIS1](/img/media/image369.png) - -Figure 225: Add Manufacturer - -**Update Manufacturer** - -1. > Go to the Manufacturer screen. - -2. > Click on the manufacturer that needs to be updated. - -3. > Enter the required information and click on the “Update” button. - -#### Organization - -An organization is a group of people with a particular purpose, which can be a private or government body. **Application, Realm Admins, Program Admin, Program User and Guest User** can list/view organizations. - -**To add an Organization** - -1. > Go to “Realm Level Masters” and then click on “Organization” to display the below table. - -![P3982#yIS1](/img/media/image370.png) - -Figure 226: Organization - -2. > Click on the blue “+” button to open a new “Add Organization” screen. - -3. > Enter the required details. - -4. > Click “Submit” to save changes or “Cancel” to close the form without saving. - -![P3988#yIS1](/img/media/image371.png) - -Figure 227: Add Organization - -**Update an Organization** - -1. > Go to the Organization screen. - -2. > Click on the record that needs to be updated. - -3. > Enter the required information and click on the “Update” button. - -![P3995#yIS1](/img/media/image372.png) - -Figure 228: Update Organization - -#### Organization Type - -Organization names can be customized per user need; however, in order to maintain standardization through master data, QAT includes an “organization type” that can be managed by a realm administrator. - -The realm administrator assigns an organization type to each organization in QAT; for example, in the Global Health Realm, country A might request their program name include the organization Ministry of Health and Wellness (MOHW), while country B requires their program name to include Ministry of Health and Social Welfare (MOHSW). This level of customization is possible in QAT, while maintaining standardization through the Organization Type masters. In the example above both MOHW and MOHSW would be assigned the organization type “Govt”, as any ministry of health would be considered a governmental entity, regardless of what that ministry of health if called in each country. - -As organization type is realm-level master data, QAT users can request new organization types if those don’t already exist, through the ticketing function. - -![P4004#yIS1](/img/media/image373.png) - -Figure 229 - Organization types in the Global Health Realm - -**Add Organization Type** - -1. Go to “Realm Level Masters” and then click on “Organization Type” to display a list of current Organization types. - -![P4009#yIS1](/img/media/image374.png) - -2. Click on the blue “+” button to open the “Add Organization Type” screen - -3. Enter the required details. - -4. Click “Submit” to save changes or “Cancel” to close the form without saving. - -![P4014#yIS1](/img/media/image375.png) - -> **Note:** QAT does not allow to put space before starting the name of organization type. Spaces are only allowed in between words if the organization type name consists of multiple words. - -**Update an Organization Type** - -1. Go to “Realm Level Masters” and then click on “Organization Type”, - -2. Click on an existing organization type to display below screen. - -![P4023#yIS1](/img/media/image376.png) - -3. Enter the required details. - -4. Click “Submit” to save changes or “Cancel” to close the form without saving. - -#### Product - -QAT supports data standardization within each realm through master data management. An essential piece of master data are products. In QAT, “Product” refers to the multiple tiers of commodities that should be configured and managed by realm: forecasting units, planning units, procurement units, and alternate reporting units. Products in QAT can be **edited/added** **by Application or Realm Admins**, except for the alternate reporting units, which are managed at the country/program level. **Country-level users** can also request new planning/forecasting units to be added to the QAT catalog by raising a ticket. - -##### Forecasting Unit - -The forecasting unit is the QAT equivalent of the product base unit. It will be used for estimating future demand, i.e., the forecast. For example: one tablet, one milliliter, one condom. These forecasting units have a one-to-many relationship with the planning unit, that is, many planning units (e.g., TLD, Bottle of 90 tablets, TLD, Bottle of 180 tablets, etc.) may relate to a single forecasting unit (e.g., 1 tablet TLD) - -**To see and export the list of all forecasting units in the realm-level catalog:** - -1. Go to “Realm Level Masters” - -2. Click on “Product” and then “Forecasting Unit”. - -3. Select the Planning Unit Category and then the Tracer Category and click on “Search” - -4. By clicking on the export to CSV Icon you could export all the selected Forecasting Units. - -![](/img/media/image377.png) - -Figure 230: List of Forecasting Units - -**To add forecasting units:** - -1. Go to “Realm Level Masters” - -2. Click on “Product” and then “Forecasting Unit”. - -3. Click the blue “add” button on to the top right corner of the Forecasting Unit screen. - -4. A new screen called “Add Forecasting Unit” will be opened. - -5. Enter the required details and click “Submit”. - -**To edit/update forecasting units:** - -1. Go to “Realm Level Masters” - -2. Click on “Product” and then “Forecasting Unit”. - -3. Click on any forecasting unit that needs to be changed or updated. - -4. Edit the required information. - -5. Click on “Update” to save the changes. - -![P4052#yIS1](/img/media/image378.png) - -Figure 231: Update Forecasting Unit - -##### Planning Unit - -By default, supply planning in QAT is managed in Planning Units. A planning unit description is usually inclusive of a full description of the product up to the primary packaging; thus, its nomenclature generally follows the pack size in which dispensing happens, i.e., one bottle of 30 tablets, one blister of 10x10 capsules, etc. Planning Units can also have volumetric data attributed to them to enable more detailed planning, but this screen is view only for Program Administrators, and its purpose is to show volumetric data for each planning unit, not to edit or add. - -**To see and export the list of all planning units in the realm-level catalog:** - -1. Go to “Realm Level Masters”. - -2. Click on “Product” and then “Planning Unit”. - -3. Select the Planning Unit category, the Tracer Category and click on “Search” - -4. By clicking on the export to CSV Icon you could export all the selected Planning Units. - -![A screenshot of a computer Description automatically generated](/img/media/image379.png) - -Figure 232: List of Planning Units - -**To add planning units:** - -1. Go to “Realm Level Masters”. - -2. Click on “Product” and then “Planning Unit”. - -3. Click the blue “add” button on to the top right corner of the Planning Unit screen. - -4. Enter the required details. - -5. Click the “Submit” button to save the changes. - -**To edit/update planning units:** - -1. Go to “Realm Level Masters”. - -2. Click on “Product” and then “Planning Unit”. - -3. Click on any forecasting unit that needs to be changed or updated. - -4. Edit the required information. - -5. Click on “Update” to save the changes. - -##### Planning Unit Volume - -As mentioned in the Planning Unit section, planning units can have volumetrics attributed to them to enable more detailed planning. However, this screen is view only for program Admins, and its purpose is to show volumetric data for each planning unit, not to edit or add. **Application** **and** **Realm admins can** add/edit planning unit volumetric data in the Planning Unit screen. - -**To add volumetric data to planning units:** - -**Application and Realm admins can** add/edit planning unit volumetric data from the Planning Unit screen. - -1. Go to “Realm Level Masters”. - -2. Click on “Product” and then “Planning Unit”. - -3. Right click on the planning unit to be edited. - -4. Click “Map Volumes” - -5. Use the blue “Add Row Button” to add a new row if needed or edit the Planning Unit details in the existing planning unit row. - -6. Click on the “Submit” button. - -![P4090#yIS1](/img/media/image380.png) - -Figure 233: Adding volumetric data to planning units - -##### Planning Unit Category - -At the realm-level, planning units should grouped in broad categories, such as HIV/AIDS pharmaceuticals, Reproductive Health Pharmaceuticals & Devices (in the Global Health Realm) in order to filter searches and reports. **Application and Realm Admins** can add/edit planning unit categories. - -**To add planning unit categories** - -1. Go to “Realm Level Masters” - -2. Click on “Product” and then “Planning Unit Category” - -3. Write the name of the new category to add, click “Add” and then “Submit”. - -![P4100#yIS1](/img/media/image381.png) - -Figure 234: Viewing/adding planning unit categories - -##### Alternate Reporting Unit - -See [Alternate Reporting Units](04-supply-planning-module-program-data.md#alternate-reporting-units) for more information. - -##### Procurement Unit - -An item-level description of the “planning unit” including supplier/manufacturer-specific attributes such as GTIN and order prices, that can be manually added/edited by **Application** **and Realm Admins** or received automatically through integration and mapping QAT planning units to a procurement agent order management system. Procurement units are specific to each procurement agent. Procurement units are not visible to/editable by country/program-level users. - -**To add procurement units to the realm-level catalog, the Application or Realm Admin must:** - -1. Go to “Realm Level Masters” and Click on “Product”. - -2. Click on “Procurement Unit” and a table of procurement units will be displayed. - -3. Click on the blue “add” button on the top right corner of the screen. - -4. Enter all the required details on the “Add Procurement Unit” screen and click “Submit”. - 1. **Note:** Required details include planning unit name, manufacturer, conversion factor, volume and weight attributes, units per pallet and per container, etc. - -**To edit/update procurement units:** - -1. Go to “Realm Level Masters” and Click on “Product”. - -2. Click on “Procurement Unit” and a table of procurement units will be displayed. - -3. Click on any procurement unit that needs to be changed or updated. - -4. Edit the required information. - 1. **Note:** Details such as planning unit name and manufacturer are not editable. - -5. Click on the “Update” button to save the changes. - -![P4122#yIS1](/img/media/image382.png) - -Figure 235: Add/Update Procurement Unit - -##### Tracer Category - -Tracer categories are a second tier, less broad grouping of product types specific to a Realm. **Application** **Admins and Realm Admins** can add/edit Tracer categories. For example, Adult antiretrovirals are a tracer category belonging to the broader grouping HIV/AIDS Pharmaceuticals (Planning Unit Category). - -![P4127#yIS1](/img/media/image383.png) - -Figure 236: List of tracer categories - -**To add tracer categories to the realm-level catalog:** - -1. Go to “Realm Level Masters” and Click on “Product”. - -2. Click on “Tracer Category” and a Tracer category table will be shown for the selected Realm. - -3. Click the blue “add” button on the top right corner of the screen. - -4. Enter all the required details on the “Add Tracer Category” screen and click “Submit”. - -**To update/edit tracer categories:** - -1. Go to “Realm Level Masters” and Click on “Product”. - -2. Click on “Tracer Category” and a Tracer category table will be shown for the selected Realm. - -3. Click on any row that needs to be changed or updated. - -4. Update the required information and click “Update” to save the changes. - -![P4141#yIS1](/img/media/image384.png) - -Figure 237: Update Tracer Category - -#### Equivalency Unit - -Equivalency Unit enables users to manage aggregate data across product that are different, but related. Equivalency Units can be used in the [compare and select forecast screen](09-forecasting-module-reports-and-outputs.md#compare-and-select), the [monthly forecast screen](09-forecasting-module-reports-and-outputs.md#monthly-forecast), the [forecast error (monthly) screen](06-supply-planning-module-reports.md#forecast-error-monthly) and the [supply plan report](05-supply-planning-module-supply-planning.md#supply-plan-report). - -**To add an Equivalency Unit Mapping:** - -1. Go to “Realm Level Masters” and Click on “Equivalency Unit”. - -2. Click on the ‘+Add Row’ button in the bottom right of the screen. You can also right click on any row and select ‘Add Row’. - -3. Enter the required details and click on the “Submit” button. - 1. Realm level mappings are available to all users and are indicated by all. These are created and managed by Realm Admins. Program specific mapping can be created and managed by program admins. If there are any conflicts, program specific mappings will take precedence and be used instead of realm level mappings. - -For example, a user is forecasting medicines to treat QATitis, a condition where people cannot stop using QAT. The user may forecast by different treatments (different forecasting units) but want to see how they are aggregated together. - -| **Equivalency Unit** | **Forecasting Unit** | **Conversion to EU** | **Average Treatment Required to cure QATitis** | -| ----------------------- | ---------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | -| 1 Treatment for QATitis | 1 tablet of FASPicillin | 14 | 1 tablet a day for 2 weeks | -| 1 Treatment for QATitis | 5mL tube of FASPasone (cream) | 1 | 0.5mL/day applied on the forehead over 10 days (1 tube total) | -| 1 Treatment for QATitis | 2mL vial of FASPicaine (injection) | 0.5 | One injection of 1mL (Two people can share one vial) | -| 1 Treatment for QATitis | 1 bar of white chocolate | 2 | 2 bars of chocolate. The type of chocolate does not matter, as all chocolate contains the natural form of FASPicillin. | -| 1 Treatment for QATitis | 1 bar of dark chocolate | 2 | | -| 1 Treatment for QATitis | 1 bar of milk chocolate | 2 | | - -**Creating and Managing Equivalency Units:** - -If you don’t see an equivalency unit that you would like to map or you would like to edit an existing equivalency unit, click on the Manage Equivalency Unit button in top right of the screen. From there, you can edit a pre-existing equivalency unit or select ‘Add Row’ and add a new one. - -#### Technical Area - -Technical Area is a key component of a QAT program and specifies the focus of that program. For example, in the Global Health Realm, the technical areas are aligned with medical conditions or health care, treatment and prevention programs such as Malaria, Family Planning and HIV/AIDs, each of which requires a variety of medicines and supplies. **Application** **Admins and Realm Admins** can add/update Technical Area(s). - -**To add a Technical Area:** - -1. Go to the top right corner in the Technical Area screen and click on the blue “+” button. A new screen showing “Add Technical Area” will open: - -![P4198#yIS1](/img/media/image385.png) - -Figure 238: Add Technical Area Screen - -![P4200#yIS1](/img/media/image386.png) - -Figure 239 Add Technical Area - -2. Enter the required details and click on the “Submit” button. - 1. If you do not wish to proceed with creating a new technical area, and you have not clicked submit, click on the “Cancel” button and QAT will close the form without saving and take you back to the Technical Area screen. - -**To update a Technical Area:** - -1. To update the technical area, go to the Technical Area Screen. - -2. Left click on the technical area that you wish to update. - -3. Enter the desired edits to the technical area and click the “Submit” button. - -4. If you want to disable or re-activate the technical area, click the circle next to that option and click the “Submit” button” - 1. By clicking on the “Reset” button, the information in the technical area will not go away, rather it will reset to what it was prior to updating it. - -![P4212#yIS1](/img/media/image387.png) - -Figure 240: Update Technical Area - -#### Procurement Agent - -A Procurement Agent selects the vendors, establishes payment terms, strategic vetting, selection, the negotiation of contracts and actual purchasing of goods that are shipped to a program. Procurement Agents are generally hired by the agency funding a particular shipment (a “Funding Source” in QAT) and identified by the Program-level user when planning a shipment. Procurement Agents are managed by **Application Level Admins** and **Realm Level Admins**. - -**To see the list of realm level procurement agents:** - -1. Go to “Realm Level Masters” from the sidebar menu. - -2. Click on “Procurement Agent”. - -**To add a Procurement Agent** - -1. On the Procurement Agent screen, go to the top right corner of the screen and click on the blue “+” button. - -2. A screen titled “Add Procurement Agent” will appear. - -3. Enter the required details. - -4. Click on the “Submit” button to save the procurement agent. - 1. Before submitting, if you wish to not proceed with that procurement agent, click the “Cancel” button. - -![P4228#yIS1](/img/media/image388.png) - -Figure 241: Add Procurement Agent - -**To update a Procurement Agent:** - -1. Go to the Procurement Agent screen. - -2. Left click on the Procurement Agent that needs to be updated. - -3. A screen labeled “Update Procurement Agent” will appear. - -4. Input the desired change(s), for example modifying the agent’s color code or Lead Times. - -5. If you want to either activate or disable the procurement agent, select the corresponding option at the bottom of the screen. - -6. Click the “Update” button to save changes or cancel to close the form without saving. - -**Planning Unit Details for Mapping to a Procurement Agent:** - -| | | -| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Planning Unit** | The planning unit is the product to be planned in QAT. It is a product with full description up to the primary packaging (e.g. bottle of 30 tablets, 10x10 blister pack, etc.). | -| **Procurement Unit** | The procurement unit is a higher-level description of the Planning Unit which includes supplier-specific attributes such as costs and GTINs. | -| **SKU Code** | Stock Keeping Unit (SKU) Code is a feature used to identify specific products and often printed on the product and case labels. The SKU code should match with what is in the procurement agent’s catalog. | -| **Catalog Price** | Price included in the procurement agent’s catalog. | -| **MOQ** | Minimum Order Quantity refers to the minimum amount that can be ordered from a procurement agent for that specific planning unit. | -| **Units per Container** | The maximum number of units for a planning unit that can fit in a container used by the procurement agent to ship the product to a program. | -| **Units per Pallet** | Units per pallet defines the number of planning units that can be packed onto a standard pallet, per pallet dimension. Units per pallet describes the individual items on a pallet into single "units" that can be moved easily with a pallet jack or forklift truck. | -| **Volume** | The volume of the planning unit. | -| **Weight** | The weight of the planning unit. | -| **GTIN** | The Global Trade Item Number is an identifier for trade items, developed by GS1. Such identifiers are used to look up product information in a database which may belong to a manufacturer. | - -Table 12: Procurement Agent Planning Unit Details - -**To add a Procurement Agent Planning Unit:** - -1. Go to the “Procurement Agent” screen. - -2. Right click on the desired procurement agent that you want to add a planning unit to. Then select “Map Planning Unit”. - -3. A screen titled “Add Procurement Agent Planning Unit” will appear. - -4. Either click on the “Add Row” button or right click and select “Insert New Row” to add a row. - -5. Enter the details for the new planning unit. Refer to the table above for definitions on any of the data elements. - -6. If you enter information for “MOQ”, “Unit Per Pallet” or “Unit Per Container”, this procurement agent/planning unit combination will be considered a *strategic product. (*Refer to Shipment Data section to learn more about strategic products). - -7. Click the “Submit” button. - -**To update a Procurement Agent Planning Unit:** - -1. Go to the “Procurement Agent” screen. - -2. Right click on the desired procurement agent that you want to update a planning unit(s) for. Then select “Map Planning Unit”. - -3. A screen titled “Add Procurement Agent Planning Unit” will appear. - -4. Enter the details for the existing planning unit by double clicking into the cells and typing in the information. Refer to the table above for definitions on any of the data elements. - -5. If you enter information for “MOQ”, “Unit Per Pallet” or “Unit Per Container”, this procurement agent/planning unit combination will be considered a *strategic product. (*Refer to Shipment Data section to learn more about strategic products). - -6. Click the “Submit” button. - -**Note:** If the procurement agent’s catalog is integrated with QAT, the planning units and associated details in QAT will automatically reflect that catalog and any change you manually make in QAT will be overridden automatically with the data from the procurement agent’s catalog at the time their data updates. - -![P4290#yIS1](/img/media/image389.png) - -Figure 242: Map Procurement Agent Planning Unit - -**To add a Procurement Agent Procurement Unit:** - -1. Go to the “Procurement Agent” screen. - -2. Right click on the desired procurement agent that you want to add a planning unit to. Then select “Map Procurement Unit”. - -3. A form titled “Add Procurement Agent Procurement Unit” will appear. - -4. Either click on the “Add Row” button or right click and select “Insert New Row” to add a row. - -5. Enter the details for the new procurement unit. Refer to the table above for definitions on any of the data elements. - -6. All the fields are required except for the GTIN field which is optional. - -7. Click the “Submit” button. - -**To update a Procurement Agent Procurement Unit:** - -1. Go to the “Procurement Agent” screen. - -2. Right click on the desired procurement agent for which you want to update a procurement unit(s). Then select “Map Procurement Unit”. - -3. A form titled “Add Procurement Agent Procurement Unit” will appear. - -4. Enter the details for the existing procurement unit by double clicking into the cells and typing in the information. Refer to the table above for definitions on any of the data elements. - -5. All the fields are required except for the GTIN field which is optional. - -6. Click the “Submit” button. - -**Note:** If the procurement agent’s catalog is integrated with QAT, the procurement units and associated details in QAT will automatically reflect that procurement agent’s catalog and any change you make manually in QAT will be overridden by the integration at the time of the next update. - -![P4311#yIS1](/img/media/image390.png) - -Figure 243: Map Procurement Agent Procurement Unit - -#### Procurement Agent Type - -Procurement agents can be customized per program need; however, in order to maintain standardization through master data, QAT includes an “procurement agent type” that can be managed by a realm administrator. - -The realm administrator assigns a procurement agent type to each procurement agent in QAT; for example, in the Global Health Realm, country A might request their program shipments include the procurement agent Joint Medical Store, while country B requires their program shipments to include National Medical Store. This level of customization is possible in QAT, while maintaining standardization through the procurement agent Type masters. In the example above both procurement agents would be assigned the procurement agent type “Government”. - -As procurement agent type is realm-level master data, QAT users can request new organization types if those don’t already exist, through the ticketing function. - -![P4320#yIS1](/img/media/image391.png) - -Figure 244 – Procurement agent types in the Global Health Realm - -**Add Procurement Agent Type** - -1. Go to “Realm Level Masters” and then click on “Procurement Agent Type” to display a list of current Organization types. - -![P4325#yIS1](/img/media/image392.png) - -2. Click on the blue “+” button to open the “Add Procurement Agent Type” screen - -3. Enter the required details. - -4. Click “Submit” to save changes or “Cancel” to close the form without saving. - -![P4330#yIS1](/img/media/image393.png) - -> **Note:** QAT does not allow to put space before starting the name of procurement agent type. Spaces are only allowed in between words if the procurement agent type name consists of multiple words. - -**Update a Procurement Agent Type** - -1. Go to “Realm Level Masters” and then click on “Procurement Agent Type”, - -2. Click on an existing Procurement Agent type to display below screen. - -![P4339#yIS1](/img/media/image394.png) - -3. Enter the required details. - -4. Click “Update” to save changes or “Cancel” to close the form without saving. - -#### Forecast Method - -This screen enables realm admins to add or edit forecast methods which can be used by users when creating forecast programs. - -**Add a Forecast Method:** - -1. Go to “Realm Level Masters” and then click on “Forecast Method” to display a list of current forecast methods. - -![P4349#yIS1](/img/media/image395.png) - -2. Click on the blue “+Add Row” button to add a blank row - -3. Enter the required details. - -4. Click “Submit” to save changes. - -## Setting Up a New Program - -A Realm or Application administrator can create a new program when required. Each program must consist of a country, technical area (can be 1 or more), region(s) and organization. Once the program is setup in QAT, program admins will have the ability to update certain program settings. Information on updating these settings can be found in the “[Program Information](07-forecasting-module-program-data.md#program-information)” section. - -**To set up a new Supply Planning Program**0F0F **follow these steps:** - -1. Go to “Program Management” from the sidebar menu. - -2. Click on “Setup Program”. - -OR - -1. Go to “Program Management” from the sidebar menu and select “Update Program Info”. - -2. Click on the blue “+” icon in the top right corner of the screen. This button will redirect the user to the “Set up Program” screen. - -![P4363#yIS1](/img/media/image396.png) - -Figure 245: Supply Planning Module Setup Program Screen - -3. Fill in the Realm section and click on “Next”. If the user only has access to one realm then this will automatically be selected for the user. - -4. Next, select the Country that the program is for and click “Next”. If the country is not listed, the Application admin will need to add or activate that specific country for the realm. - -5. Select the Technical Area(s) that the program is for and click “Next”. If the Technical Area is not listed, the Application admin will need to add or activate that Technical Area for the realm. - -> **Note:** Multiple Technical Areas can be selected using the Technical Area dropdown list. -> -> ![P4369#yIS1](/img/media/image397.png) - -Figure 246 Setting-up a program with multi-select technical areas - -6. Select the Organization that the program is for and click “Next”. If the Organization is not listed, the Application admin will need to add or activate that Organization for the realm. - -7. Select the Region(s) that the program is for and click “Next”. If a Region the user needs is not listed, the Application admin will need to add or activate that Region for the realm. This step allows for one or more selections. - -8. Step 6 is where the user will provide the Program Data. Fill in all the required details. - -![](/img/media/image398.png) - -Figure 247: Add Program Data - -9. The final step to setup the program is to add in the planning unit(s). All of the fields in this step are required in order to proceed. Any field that is left blank will be highlighted yellow until it is filled in. - -10. Click “Submit”. - -**To set up a new Forecasting Program**0F0F **follow these steps:** - -1. Go to “Program Management” from the sidebar menu and select “Update Program Info”. - -2. Click on the blue “+” icon in the top right corner of the screen. - -3. Complete the required fields for Country, Technical area, Organization, Region, Forecasting Program, Program Manager, and the Version 1 Settings (Forecast Start, Forecast Period, Forecast End). The [Version Settings](07-forecasting-module-program-data.md#version-settings) can be updated at any time by the Program Admins. - - > **Forecast Start, Forecast Period (Months), and Forecast End** – based on the start & end date, QAT will automatically calculate the forecast period in months. Alternatively, users can choose to enter a forecast start date and number of months in the forecast period, and QAT will automatically calculate the forecast end date. - -4. Click “Submit” - -![P4387#yIS1](/img/media/image399.png) - -Figure 248: Forecasting Module Setup Program Screen - -## Resetting the QAT Problem List - -Realm administrators have the ability to reset the QAT Problem List for all programs, regardless of version type or status. The programs can be reset in bulk or individually by program. Resetting the QAT Problem List for a program will revert all problems with an “addressed” status to “open.” This automatically happens when a supply plan is Final-Approved by a supply plan reviewer, but does not automatically happen for any other version types or statuses. Resetting the QAT Problem List can be useful at the end of a supply plan submission period for programs that were submitted as Final, not Approved, but all problems should be reopened for review for the next submission period. - -**To reset the QAT Problem List:** - -1. > Navigate to the Supply Plan Version and Review screen - -2. > Click on the “Reset QPL” button in the top right corner - -![A screenshot of a computer Description automatically generated](/img/media/image400.png) - -Figure 249: Reset QPL Button - -3. > Choose the Version Type, Status, and Program that should be reset - -![A screenshot of a computer Description automatically generated](/img/media/image401.png) - -Figure 250: Reset QPL Dropdowns - -4. > Click “Submit” diff --git a/docs/user/10-forecasting-module-program-data.md b/docs/user/10-forecasting-module-program-data.md new file mode 100644 index 0000000..a6d03df --- /dev/null +++ b/docs/user/10-forecasting-module-program-data.md @@ -0,0 +1,84 @@ +--- +id: forecasting-module-program-data +title: "Forecasting Module: Program Data" +sidebar_label: "Forecasting Module: Program Data" +sidebar_position: 10 +--- + +# Forecasting Module: Program Data + +## Introduction +A forecast is an estimate of product quantities required by clients over a future period. In QAT, forecasting follows a structured workflow: **Setup** → **Methodology Selection** → **Data Entry** → **Analysis & Selection**. + +### Forecasting Methodologies +QAT supports two primary methodologies, which can be used individually or combined for each product: + +| Methodology | Best For... | Requirements | +| :--- | :--- | :--- | +| **Consumption-Based** | Mature, stable programs with reliable data. | 24+ months of historical consumption data. | +| **Tree-Based** | New programs, scale-ups, or variable demand. | Morbidity, service, or demographic data; demographic trends. | + +Once forecasts are prepared, they are compared in the **Forecast Analysis** section to select the final plan. + +## Program Information +Program Admins can update basic metadata (Name, Manager, Notes) and toggle program status (Active/Disabled). +> [!NOTE] +> Changes to Technical Area, Organization, or Display Name require a [Helpdesk Ticket](05-getting-started.md#qat-helpdesk-and-tickets). + +## Version Settings +The **Version Settings** screen allows users to define the parameters of the current forecast and review previous versions. Only the **Local Version** is editable; server versions are read-only. + +### Technical Parameters +- **Forecast Period:** Define the **Start Date** and **Number of Months**. QAT auto-calculates the **End Date**. +- **Days in Month:** Set between 15–31 days (Default: Calendar days). Useful for adjusting consumption based on service days. +- **Freight Percentage:** Optional estimate for procurement cost calculations. +- **Forecast Threshold:** Used in the **Compare & Select** screen. QAT flags Tree Forecasts that deviate significantly (High/Low) from Consumption Forecasts. Out-of-threshold values are highlighted in **Red**. + +### Version History +Users can view the historical lifecycle of the program and right-click any version to view the **Forecast Validation** summary (listing missing data and validation notes) without downloading that specific version. + +![Version Settings Interface](/img/media/image235.png) +*Figure 1: Forecasting Version Set## Planning Units +The **Planning Units** screen is where you define the products to be forecasted. Products can be added manually or copied from the Supply Planning module. + +### Planning Unit Settings +Configure these settings to enable specific methodologies and financial calculations: + +| Setting | Description | Impact | +| :--- | :--- | :--- | +| **Conversion Factor** | Ratio between Planning Unit (PU) and Forecasting Unit (FU). | Standardizes data entry across units. | +| **Forecast Methodology** | Toggle **Consumption** and/or **Tree** methodology. | Determines which data entry screens are active. | +| **Stock on Hand** | Opening balance at the start of the forecast period. | Used to calculate the procurement gap. | +| **Existing Shipments** | Total committed quantities for the forecast period. | Reduces the total gap to be filled. | +| **Desired MOS** | Target inventory level (Months of Stock) at end of period. | Sets the goal for the gap calculation. | +| **Price & Type** | Catalog price or custom price per procurement agent. | Estimates the total cost of the procurement gap. | + +> [!TIP] +> Always perform a **Master Data Sync** after updating these settings to ensure they propagate to the Analysis screens. + Planning Unit Settings + +## Equivalency Units +**Equivalency Units (EUs)** allow you to aggregate data across different but related products (e.g., different pack sizes or concentrations). This enables a unified view of the forecast in the **Reports & Outputs** section. + +### Mapping & Conflicts +- **Realm Level Mappings:** Universal mappings provided by QAT. +- **Program Level Mappings:** Overrides created by Program Admins for specific needs. Program-level mappings always take precedence. + +### Examples of Equivalency +If a treatment regimen requires 14 tablets of one product OR 1 tube of another, both can be mapped to an EU called "Regimen Treatment". + +| Equivalency Unit | Forecasting Unit | Conversion Factor | +| :--- | :--- | :---: | +| Regimen Treatment | 1 tablet of Product A | 14 | +| Regimen Treatment | 1 tube of Product B | 1 | + +### Managing EUs +1. **Check Master Data:** Search for existing EUs in **Realm Masters** > **Equivalency Units**. +2. **Add Custom EU:** If not found, use **Manage Equivalency Unit** to create a program-specific unit. +3. **Map Units:** Click **Add Row** on the main screen to link your Forecasting Units to the EU. +4. **Sync:** Click **Submit** and perform a **Master Data Sync**. + +### Usage in Reports +- **Compare & Select:** Display total demand in EUs instead of individual units. +- **Monthly Forecast:** Aggregate disparate products into a single "total requirement" line. +- **Supply Planning:** View actual and forecasted consumption in EUs to identify high-level trends. diff --git a/docs/user/11-annex-2-business-rules.md b/docs/user/11-annex-2-business-rules.md deleted file mode 100644 index 6665fb1..0000000 --- a/docs/user/11-annex-2-business-rules.md +++ /dev/null @@ -1,1174 +0,0 @@ ---- -id: annex-2-business-rules -title: "Annex 2: Business Rules" -sidebar_label: "Annex 2: Business Rules" -sidebar_position: 11 ---- - -# Annex 2: Business Rules - -## Introduction - -This document outlines the key formulas and business rules that underpin the Quantification Analytics Tool (QAT) application. - -## Supply Planning Module: Supply Planning - -1. **Opening Balance:** - -> Opening balance for a month is the same as that of the Ending balance of last month and if that is the first month then the opening balance is 0. -> -> **Formula:** -> -> Opening balance of first month = 0 -> -> Opening balance for current month = Ending balance of previous month - -2. **Expired Stock:** - -> Expired stock is calculated as the sum of the Ending balance of all the batches of the previous month that are available and have the expiry date same as that of the current month. -> -> **Formula:** -> -> Expired Stock = Sum of Ending balance of batches that are expiring this month - -3. **Total Shipment:** - -> Total shipment is calculated as the sum of all the shipments with receive date (if present or expected delivery date) is the same as that of current month and the shipment status is not cancelled and if that particular shipment needs to be accounted for that is to be considered in the Ending balance. -> -> **Formula:** -> -> Total shipments = Sum of all the shipments whose receive date or expected delivery date is in the same month - -4. **Final Stock and Adjustment:** - -> Final stock is calculated as the sum of stock of all the regions and total adjustment is calculated as sum of the adjustments of all the regions based on certain conditions. - -1. If the region has reported both the actual stock and the adjustment then we only consider the actual count while doing the sum and the adjustment is ignored for that region even if someone has entered the data for adjustment. - -2. If the region has only reported the adjustment then that adjustment is considered while doing the sum. - -> For example, if Region A has reported both the stock count and the manual adjustment so in that case we only consider the stock count and ignore the adjustment. And If Region B has reported only the adjustments then we take the sum of all the adjustments for that region. And then we sum up the counts for both the regions as final stock and total adjustment. -> -> **Formula:** -> -> Final Stock = Sum of stock for all the regions -> -> Total Adjustments = Sum of adjustments of all the regions for which there is no stock qty available. - -5. **Consumption: ** - -> Consumption is calculated as the sum of consumption of all the regions based on some conditions. - -- > If all the regions have not reported the actual consumption, QAT takes the max of sum of forecasted consumption and sum of actual consumption. - -- > If all the regions have reported the actual consumption, we take the sum as the final consumption. - -> \*\* \*\* -> -> **Formula: ** -> -> Final consumption (If all the regions have not reported the actual consumption) = MAX (Sum of actual consumption for all the regions, Sum of forecasted consumption for all the regions) -> -> Final consumption (If all the regions have reported the actual consumption) = Sum of actual consumption for all the regions - -6. **Projected inventory:** - -> Projected inventory is calculated as sum of opening balance, total shipments, total adjustments and deduction of total final consumption and expired stock. -> -> **Formula:** -> -> Projected inventory = Opening balance + Total shipments +/- Total adjustments - Final consumption - Expired stock - -7. **Calculate Automatic Adjustment:** - -> Automatic adjustments is calculated based on three conditions: - -1. If all the regions have reported the actual stock count and projected inventory is not equal to final inventory - -2. If some of the regions have reported the actual stock count and final inventory is greater than sum of projected inventory and total adjustment - -3. If any of the regions have reported the actual stock count and projected inventory is less than 0 - -> And based on the above conditions if any of the conditions is satisfied then auto adjustment is calculated as difference between final inventory and projected inventory otherwise it is considered as 0. -> -> **Formula:** -> -> Automatic adjustments = Final stock - Projected inventory - -8. **AMC:** - -> Average monthly consumption (AMC) is calculated as the ratio of sum of full demand of months in past and the full demand of months in future to the total number of months for all the non-zero final consumptions and including the current month in months in future. If consumption is actual Full Demand will be equal to the sum of the unmet demand in addition to the actual consumption. If the consumption is forecasted the full demand is equal to the forecasted consumption. Both months in past and months in future are based on the mapping of program planning units. -> -> **Formula:** -> -> AMC = Sum (Full Demand in No. of months in past) + Sum (Full Demand in No. of months in future)/Total number of months - -9. **Min MOS:** - -> Min MOS is calculated as Max of Min MOS and Min MOS guardrail. Min MOS is based on the mapping of the program planning unit and Min MOS guardrail is based on the realm. -> -> Rules for Decimal places are as follows: -> -> \-Display 0 decimal places if 3+ digits (\>100, e.g. 10,000) -> -> \-Display 1 decimal places if 2 digits (e.g. 99.8) -> -> \-Display 2 decimal places if 1 digit (e.g. 1.63) -> -> \-Display 3 decimal places if under 0 (e.g 0.124) -> -> Note: AMC and MOS always show decimals, other supply plan fields will only show decimals if the rounding toggle is on. -> -> **Formula:** -> -> Min MOS = Max of (Min MOS, Min MOS guardrail) - -10. **Max MOS:** - -> Max MOS is calculated as Min of Max of sum of Min MOS and reorder frequency and the Min Max guardrail and Max Max guardrail. Reorder frequency is based on the mapping of the program planning unit and Min Max guardrail and Max Max guardrail are based on the realm. -> -> **Formula:** -> -> Max MOS = Min(Max(Min MOS + Reorder frequency, Min Max guardrail),Max Max guardrail) - -11. **Min Stock:** - -> Min stock is calculated by multiplying the AMC and Min MOS. -> -> **Formula:** -> -> Min Stock = AMC \* Min MOS - -12. **Max Stock:** - -> Max stock is calculated by multiplying the AMC and Max MOS. -> -> **Formula:** -> -> Max Stock = AMC \* Max MOS - -13. **Max Quantity:** - -> Max Quantity is calculated as sum of Min Qty and multiplication of reorder frequency and AMC -> -> **Formula** -> -> Max Qty = Min Qty + (Reorder Frequency \* AMC) - -14. **Ending Balance:** - -> Ending balance is calculated based on certain conditions: - -1. If all the regions have reported the actual stock count, then the Ending balance is equal to the final stock. - -> **Formula:** -> -> Ending balance = Final Stock - -2. If some of the regions have reported the actual stock count and if the final stock is greater than the sum of projected inventory and auto adjustment, then the Ending balance is equal to the final stock. - -> **Formula:** -> -> Ending balance = Final Stock - -3. Otherwise Ending balance is calculated as the sum of projected inventory and auto adjustment. - -> **Formula:** -> -> Ending balance = Projected inventory + Auto adjustment - -15. **Unmet demand:** - - - -- When actual consumption is available = (Actual consumption \* Days stocked out) / (Days in Month – Days Stocked out) - -- When no actual consumption is available = Projected Inventory\* (if Projected Inventory is \<0) - - - -16. **MOS:** - -> MOS is calculated as the ratio of Ending balance to that of AMC. -> -> **Formula:** -> -> MOS = Ending balance / AMC - -17. **When to suggest shipments (Plan by MOS):** - -> QAT suggests the shipment for a month when MOS for the month and following two months is less than that of the Min MOS and if the month is greater than the current month -> -> **Formula:** -> -> When to suggest shipments = If MOS for month and following two months \< Min MOS - -18. **Suggested shipment quantity (Plan by MOS):** - -> Suggested shipment quantity is calculated as the difference between Max stock and Ending balance -> -> **Formula:** -> -> Suggested shipment quantity = Max stock - Ending balance - -- If MOS for current month and following two months is less than Min MOS - -> _Suggested Order Qty = (Max Stock - Ending Balance + Unmet Demand)_ - -- If MOS is '0' and AMC is greater than \> 0 and the following two months are less than Min MOS - -> _Suggested Order Qty = (Max Stock - Ending Balance + Unmet Demand)_ - -- If MOS is '0' and AMC is greater than \> 0 and one of the following two months is greater than Min MOS - -> _Suggested Order Qty = (Min Stock - Ending Balance + Unmet Demand)_ - -19. **When to suggest shipments (Plan by Qty): ** - -> QAT suggests the shipment for a month when Ending Balance for the month + Distribution lead time and following two months is less than that of the Min Qty or when Ending Balance for month is 0 and AMC is greater than 0 and if the month is greater than the current month -> -> **Formula: ** -> -> When to suggest shipments = If Ending Balance for month + X (Distribution Lead Time) and following two months \< Min Qty or -> -> When to suggest shipments = If Ending Balance for month = 0 and AMC is not equal to 0 -> -> \*\* \*\* - -20. **Suggested shipment quantity (Plan by Qty): ** - -> Suggested shipment quantity is calculated as the difference between Max stock/Min Stock and Sum of Ending balance and Unmet Demand -> -> **Formula:** - -- If Ending Balance for current month + X months (Distribution Lead Time) and following two months is less than Min Qty - -> _Suggested Order Qty = (Max Qty for current month + X months (Distribution Lead Time) - Ending Balance + Unmet Demand)_ - -- If Ending Balance is '0' and AMC is greater than \> 0 for current month + X months (Distribution Lead Time) and the following two months are less than Min Qty - -> _Suggested Order Qty = (Max Qty for current month + X months (Distribution Lead Time) - Ending Balance + Unmet Demand)_ - -- If Ending is '0' and AMC is greater than \> 0 for current month + X months (Distribution Lead Time) and one of the following two months is greater than Min MOS - -> _Suggested Order Qty = (Min Qty - Ending Balance + Unmet Demand)_ - -21. **Batch calculations:** - -> Below are the steps for the all the batch allocations: - -1. **FEFO Calculations:** - -> We first calculate the unallocated FEFO that is we calculate the total remaining quantity of the final consumption and total adjustment which will be used in case of FEFO calculations and for which we do not have the batch information. So, the unallocated FEFO is calculated based on two different conditions - -1. If the sum of total adjustment and auto adjustment is less than 0 then unallocated FEFO is calculated as difference between final consumption and the sum of manual adjustment and automatic adjustment. - -> **Formula:** -> -> Unallocated FEFO = Final consumption - (Manual adjustment + Auto adjustment) - -2. If the sum of adjustment and national adjustment is greater than 0 then unallocated FEFO is the same as that of final consumption. - -> **Formula:** -> -> Unallocated FEFO = Final consumption -> -> We sort all the batches based on the expiry date in ascending order that is sort the batches in the order which is expiring first -> -> We then loop across all the batches for doing the FEFO calculations -> -> We calculate the opening balance for a batch which is the same as that of the Ending balance for the same batch in the previous month. And if the batch is created then the opening balance is considered as 0. -> -> **Formula:** -> -> Opening balance of newly created batch = 0 -> -> Opening balance of remaining batches = Ending balance -> -> We then calculate the Expired stock quantity which is equal to the Ending balance of the same batch from the previous month and is only calculated when the expiry date of the batch is the same as that of the current month otherwise it is 0. -> -> **Formula:** -> -> Expired Stock (If expiry date is same as that of current date) = Ending Balance -> -> Expired Stock (Otherwise) = 0 -> -> We then calculate the temp Ending Balance. Temp Ending Balance is calculated as sum of opening balance, total shipments, total adjustments and deduction of total final consumption and expired stock. -> -> **Formula:** -> -> Temp Ending Balance = Opening Balance + Shipment Qty + Adjustment Qty - Consumption Qty - Expired Stock -> -> We then calculate the Ending balance amount which is calculated based on two different conditions - -1. > If temp Ending Balance is greater than or equal to unallocated FEFO then Ending balance is equal to the difference between the temp Ending balance and unallocated FEFO also in this case we make the unallocated FEFO as 0 since we have allocated all the quantity to the batch. - -> **Formula:** -> -> Ending balance = Temp Ending Balance - unallocated FEFO -> -> Unallocated FEFO = 0 - -2. > If temp Ending Balance is less than unallocated FEFO then Ending balance is equal to 0 since we will fully consume this batch. Also we then deduct the temp CB from the unallocated FEFO since we have consumed that much of the quantity. - -> **Formula:** -> -> Ending balance = 0 -> -> Unallocated FEFO = Unallocated FEFO - Temp Ending balance -> -> We repeat this process for every batch in the order of their expiry date. - -1. > **LEFO Calculations:** - -> We first calculate the unallocated LEFO that is we calculate the total remaining quantity of the final consumption and total adjustment which will be used in case of LEFO calculations and for which we do not have the batch information. So, the unallocated LEFO is calculated based on two different conditions - -1. If the sum of manual adjustment and automatic adjustment is greater than 0 then unallocated LEFO is calculated as difference between 0 and the sum of manual adjustment and automatic adjustment. - -> **Formula:** -> -> Unallocated LEFO = 0 - (Manual adjustment + Automatic adjustment) - -2. If the sum of manual adjustment and auto adjustment is less than 0 then unallocated LEFO is 0. - -> **Formula:** -> -> Unallocated LEFO = 0 - -3. If unallocated LEFO is not equal 0 then we continue otherwise we break. - -> We sort all the batches based on the expiry date in descending order that is sort the batches in the order which is expiring first -> -> We then loop across all the batches for doing the LEFO calculations -> -> We then calculate the temp Ending Balance. Temp Ending Balance is the same as that of Ending the balance of batch after FEFO calculations. -> -> **Formula:** -> -> Temp Ending Balance = Ending balance after FEFO calculations -> -> We then calculate the Ending balance amount which is calculated based on two different conditions - -1. If temp Ending Balance is greater than or equal to unallocated LEFO then Ending balance is equal to the difference between the temp Ending balance and unallocated LEFO also in this case we make the unallocated LEFO as 0 since we have allocated all the quantity to the batch. - -> **Formula:** -> -> Ending balance = Temp Ending Balance - unallocated LEFO -> -> Unallocated LEFO = 0 - -2. If temp Ending Balance is less than unallocated LEFO then Ending balance is equal to 0 since we will fully consume this batch. Also we then deduct the temp CB from the unallocated LEFO since we have consumed that much of the quantity. - -> **Formula:** -> -> Ending balance = 0 -> -> Unallocated LEFO = Unallocated LEFO - Temp Ending balance -> -> We repeat this same process for the rest of batches till unallocated LEFO is not equal to 0. - -## Supply Planning Module: QAT Problem List - -### Data Quality - -1. > Missing recent actual consumption inputs (within the last \<%X %\> months) - - - -1. **Suggestion:** Please provide Actual consumption in \<%REGION %\> region for the month of \<%DT %\>. - -2. **Logic:** QPL will check actual consumption for the past three months and current month. If actual consumption for all of the past three month and current month is missing, then the problem is flagged. - - - -1. Missing recent inventory inputs (within the last \<%X%\> months) - 1. **Suggestion:** Please provide Stock count in \<%REGION %\> region for the month of \<%DT%\>. - - 2. **Logic:** QPL will check stock for the past three months and current month. If stock for all of the past three month and current month is missing, then the problem is flagged. - -2. Missing recent actual consumption inputs for months in gaps - 1. **Suggestion:** Please provide Actual consumption in \<%REGION %\> region for the month of \<%DT %\>. - - 2. **Logic:** - 1. QPL will check actual consumption inputs for the current month (consider as t) and for the month which will be current month minus two months (consider as t-2) i.e. t and t-2 if both the months have actual consumption and current month minus one month (consider as t-1) i.e. t-1 don't have actual consumption. Then in this case the problem is flagged. - - 2. QPL will check actual consumption inputs for the current month minus one month (consider as t-1) and for the month which will be current month minus three months (consider as t-3) i.e. t-1 and t-3 if both the months have actual consumption and current month minus two month (consider as t-2) i.e. t-2 don't have actual consumption. Then in this case the problem is flagged. - -### Procurement Schedule - -1. Shipments have receive dates more than \<%X%\> days in the past - 1. **Suggestion:** Please check to make sure shipment \<%SHIPMENT_ID %\> was received, and update either the receive date or the shipment status. - - 2. **Logic:** QPL will check the receive date for all the shipments and if the receive date is past and has also crossed the buffer time period then the problem is flagged. For example, buffer time for this problem is 14 days so if the receive date of the shipment plus the buffer days are past then the problem is flagged for each shipment. - -2. Shipment have not been submitted for over \<%X%\> days since target date - 1. **Suggestion:** Based on lead times, shipment \<%SHIPMENT_ID%\> should have been submitted by now. Please double-check to ensure that the status or receive date is accurate. - - 2. **Logic:** QPL will check the submitted date for all the shipments and if the submitted date is past and has also crossed the buffer time period then the problem is flagged. For example, the buffer time for this problem is 3 days. Hence if the submitted date of the shipment plus the buffer days have already passed, then the problem is flagged for each shipment. - -### Supply Planning - -1. No Forecasted consumption \<%X %\> months into the future - 1. **Suggestion:** Please provide Forecasted consumption in \<%REGION %\> region for the month of \<%DT %\>. - - 2. **Logic:** QPL will check forecasted consumption for future 18 months. If forecasted consumption for any one of the month is missing then the problem is flagged. The problem gets into in-compliance state if and only if all the 18 months have forecasted consumption. - -2. Dynamic forecasting is not used for commodity groups ARV - 1. **Suggestion:** Please check consumption data in region \<%REGION%\> during period \<%DT%\> as we encourage forecasting with dynamic monthly values, showing that factors such as program scale or seasonality have been taken into account. - - 2. **Logic:** QPL will check whether the planning unit of the program falls in the commodity group ARV then QPL will check forecasted consumption for future 18 months if any four consecutive months within the future 18 month span have the same forecasted consumption quantity then the problem is flagged. - -3. Dynamic forecasting is not used for commodity groups MALARIA - 1. **Suggestion:** Please check consumption data in region \<%REGION %\> during period \<%DT%\> as we encourage forecasting with dynamic monthly values, showing that factors such as program scale or seasonality have been taken into account. - - 2. **Logic:** QPL will check whether the planning unit of the program falls in the commodity group MALARIA then QPL will check forecasted consumption for future 18 months if any four consecutive months within the future 18 month span have the same forecasted consumption quantity then the problem is flagged. - -4. Dynamic forecasting is not used for commodity groups VMMC - 1. **Suggestion:** Please check consumption data in region \<%REGION%\> during period \<%DT%\> as we encourage forecasting with dynamic monthly values, showing that factors such as program scale or seasonality have been taken into account. - - 2. **Logic:** QPL will check whether the planning unit of the program falls in the commodity group VMMC then QPL will check forecasted consumption for future 18 months if any four consecutive months within the future 18 month span have the same forecasted consumption quantity then the problem is flagged. - -5. **Supply Plan does not follow minimum/maximum parameters** - 1. **Suggestion:** **Re-evaluate supply plan to meet the Min/Max parameters. If overstocked, consider delaying/canceling shipment(s), review future expiries, or donating stock. If understocked, consider planning & ordering, expediting, or increasing shipment quantity.** - - 2. **Logic: QPL will check to see if each planning unit** is overstocked or understocked at any point during the next 18 months according to the minimum and reorder parameters defined at individual program-levels. QAT will then count the number of months the planning unit is **overstocked and understocked** and subdividing it in two different time windows: those months within lead time (1-6 months) and those within the planning window (7-18 months). The QPL will also denote the number of shipments being received in the next 1-6 months and the next 7-18 months. - -6. **Stock outs in the next 1-6 months/Stock outs in the next 7-18 months** - 1. **Suggestion: Consider planning & ordering, expediting, or increasing shipment quantity. Communicate the potential stockout(s) with relevant stakeholders.** - - 2. **Logic: QPL will check to see if each planning unit** is stocked out (zero MOS) at any point during the next 18 months. QAT will then count the number of months the planning unit is stocked out and subdividing it in two different time windows: those months within lead time (1-6 months) and those within the planning window (7-18 months). The QPL will also denote the number of shipments being received in the next 1-6 months and the next 7-18 months. - -### Other (Manual Problems) - -1. > **These are specific questions or clarifications manually entered by the supply plan reviewer that are not automatically flagged by QAT. The problem description, suggestion, and the criticality are determined by the supply plan reviewer. QAT does not conduct any specific logic for this problem as it must be manually added, updated, and resolved by the supply plan reviewer.** - -## Supply Planning Module: Other QAT Reports - -1. **WAPE (Weighted Absolute Percentage Error)** - -> WAPE (Weighted Absolute Percentage Error) is being used to calculate forecast error. This calculation is used in forecast error reports which helps supply plan owners to review forecast error in order to monitor the strength for their forecast. The WAPE formula is using the previous 3-12 months of data depending on the selection in the ‘Time Window’ dropdown. -> -> WAPE is Dividing the sum of absolute differences by the sum of actual values for a particular time window. Time window can be 3,6,9 or 12 -> -> **Formula:** -> -> WAPE=((Abs(actual consumption month 1-forecasted consumption month 1)+ Abs(actual consumption month 2-forecasted consumption month 2)+ Abs(actual consumption month 3-forecasted consumption month 3)+ Abs(actual consumption month 4-forecasted consumption month 4)+ Abs(actual consumption month 5-forecasted consumption month 5)+ Abs(actual consumption month 6-forecasted consumption month 6)) / (Sum of all actual consumption in the last 6 months)) -> -> **Note:** Time window considered as 6 months - -2. **Shipment Cost** - -> It is the total cost required to received order at warehouse -> -> **Formula:** -> -> Shipment Total Cost = (Product Cost+ Freight Cost) \* conversion rate to USD - -3. **Cost of Inventory** - -> This calculation provide us cost of available product -> -> **Formula:** -> -> Cost of Inventory = ending balance\* catalog price - -4. **Average Stock** - -> **Formula:** -> -> Average stock= sum (ending balance for ‘n’ months) / n -> -> **Note:** “n” is number of months - -5. **Inventory Turns** - -> It is the ratio of consumption versus average stock. User can select to view the table in two ways: by country or by PU category. Can be multi-select for countries or PU category, highest level calculation (aggregation/average from each PU under program or from each program that contains that PU category). Then will calculate the turns for each planning unit under that program. -> -> **Formula: ** - -**Planned Inventory Turns (IT)** - -**At PU level** - -> The calculation is done by determining the possible months of stock for each month over 12 months if the inventory rules worked perfectly considering the Planning Unit’s MIN and Reorder Interval. -> -> Consumption = 1 MOS/month ; Total consumption over period = 12 MOS -> -> Average MOS is calculated based on the MIN and the Reorder Interval -> -> For example: - -1\. If the MIN is 3 and reorder is 9 and the first month is a re-order month then: - -> a. The average MOS over 12 months would be 7.25 -> -> b. The Planned inventory turn is the Total consumption 12 divided by the calculated Average months of stock over 12 month. Thus 12 /7.25 = 1.7 - -| Reorder interval | Month 1 | Month 2 | Month 3 | Month 4 | Month 5 | Month 6 | Month 7 | Month 8 | Month 9 | Month 10 | Month 11 | Month 12 | Total months | -| ---------------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- | ------- | -------- | -------- | -------- | ------------ | -| 12 | 12 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 78 | -| 11 | 1 | 11 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 67 | -| 10 | 2 | 1 | 10 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 58 | -| 9 | 3 | 2 | 1 | 9 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 51 | -| 8 | 4 | 3 | 2 | 1 | 8 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 46 | -| 7 | 5 | 4 | 3 | 2 | 1 | 7 | 6 | 5 | 4 | 3 | 2 | 1 | 43 | -| 6 | 6 | 5 | 4 | 3 | 2 | 1 | 6 | 5 | 4 | 3 | 2 | 1 | 42 | -| 5 | 2 | 1 | 5 | 4 | 3 | 2 | 1 | 5 | 4 | 3 | 2 | 1 | 33 | -| 4 | 4 | 3 | 2 | 1 | 4 | 3 | 2 | 1 | 4 | 3 | 2 | 1 | 30 | -| 3 | 3 | 2 | 1 | 3 | 2 | 1 | 3 | 2 | 1 | 3 | 2 | 1 | 24 | -| 2 | 2 | 1 | 2 | 1 | 2 | 1 | 2 | 1 | 2 | 1 | 2 | 1 | 18 | -| 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 12 | - -**At Program level:** - -> MODE (Planned inventory turns of all Planning units under a specific program) -> -> **At Country and/or PU category level**: - -MODE (Planned inventory turns of all Planning units under a specific country / PU Category) - -**Actual Inventory Turns (IT)** - -**At PU level** - -1.Total Consumption for the last 12 months / Average Stock on hand over last 12 months - -> **At Program level** - -1\. First option is to look for a mode. - -2\. If the count of MODE Value \< 3 (variable setting), QAT uses AVG, if the count of the MODE value is \> 3 (variable setting), then - -3\. The mode will be determined if the value occurs in at least 20% (variable setting), of the program's total number of planning units. (Example: program contains 100 PUs, 20 of those have turns = 1.2 and the rest all have different turns; so the turns for the program will be 1.2) - -4\. If above condition (20%) is found multiple times in the dataset, QAT to use the LOWEST inv. turns mode of the set (Example:, Program contains 100 PUs; 60 PUs have different turns; 20 PUs - -> have inv turns = 1.2, another 20 PUs have inv. turns = 2.5; QAT will display 1.2 as the inv. turns for that program) - -5\. If no definitive mode can be found based on above rules, then Program level inv turns will be the average of all PU inventory turns under that program - -**At Country and/or PU category level** - -1\. First option is to look for a mode. - -2\. If the count of MODE Value \< 3 (variable setting), QAT uses AVG, if the count of the MODE value is \> 3 (variable setting), then - -3\. The mode will be determined if the value occurs in at least 20% (variable setting) of the that country's (or PU category) total number planning units - -4\. Rule: If above condition is found multiple times in the dataset, QAT to use the LOWEST inv. turns mode of the bunch (e.g., Country contains 1000 PUs; 600 PUs have different turns; 200 PUs - -have inv turns = 1.6, another 200 PUs have inv. turns = 2.2; QAT will display 1.6 as the inv. turns for - -that Country/PU category) - -5\. Rule: If no definitive mode can be found based on above rules, then Country/PU category level inv turns will be the average of all PU inventory turns under that country/PU category - -\*\* \*\* - -**Note**: Actual consumption precedes forecasted consumption in calculation if available - -6. **Procurement Agent Total Lead Time:** - -> This is the total time required to receive a product in the warehouse since the date when order was planned. It also depends on shipment mod (sea or air). This calculation is used to calculate the expected delivery date so that user can order products before stock out -> -> **Formula:** -> -> Procurement Agent total Lead Time(by Air) = Planned to Submitted Lead Time in months +Submitted to Approved Lead Time in months+ Approved to Shipped Lead Time in months+ Shipped to Arrived Lead Time in months( by Air)+Arrived to Received Lead Time in months -> -> Procurement Agent total Lead Time(by Sea) = Planned to Submitted Lead Time in months +Submitted to Approved Lead Time in months+ Approved to Shipped Lead Time in months+ Shipped to Arrived Lead Time in months( by Sea)+Arrived to Received Lead Time in months - -7. **Expiries Report:** - -> This report calculates the expired quantity for each planning unit as well as the linked batch number to show dates of when the expiry occurred. Also included, the total cost of expiry for products that have expired. -> -> **Formula:** -> -> Total Cost of Expiry= Expiring Quantity \* Unit-price of product from shipment (if batch didn’t come from shipment, default catalog price is used) - -## Forecasting Module: Tree Forecasts - -1. **Aggregation Node** - -> Value for the aggregation node for a month is calculated as sum of the values of the children nodes for that same month -> -> **Formula:** -> -> Value of node for a month = Sum(Node values of child nodes) - -1. **Number Node** - -> Value for the number node for a month is defined at node. -> -> **Formula:** -> -> Value of node for a month = Value defined at the node -> -> There are three types of modeling/transfer that can be applied -> -> **a. Linear Number: ** -> -> If linear number modeling is applied then the value of that node is increased or decreased by a fixed, monthly quantity. -> -> If linear number transfer is applied then the value of that node is decreased from this node and the same amount is increased in the transferred node. - -- **Formula for modeling:** - -> Value for a node for a month = Value defined at the node +/- Fixed,monthly quantity - -- **Formula for transfer:** - -> Value of transfer from node for a month = Value defined at the node - fixed, monthly quantity -> -> Value of transfer to node for a month = Value defined at the node + fixed, monthly quantity - -2. > **Linear Percentage: ** - -> If linear percentage modeling is applied then a percentage of starting month is increased or decreased from each month. -> -> If linear percentage transfer is applied then a percentage of starting month is decreased from this node and the same amount is increased in the transferred node for each month. - -- **Formula for modeling:** - -> Value for a node for a month = Value defined at the node +/- Percentage of starting month value - -- **Formula for transfer:** - -> Value of transfer from node for a month = Value defined at the node - Percentage of starting month value -> -> Value of transfer to node for a month = Value defined at the node + Percentage of starting month value of transfer from node - -3. > **Exponential Percentage: ** - -> If exponential percentage modeling is applied then a percentage of preceding month value is increased or decreased from each month. -> -> If exponential percentage transfer is applied then a percentage of preceding month value is decreased from this node and the same amount is increased in the transferred node for each month. - -- **Formula for modeling:** - -> Value for a node for a month = Value defined at the node +/- Percentage of preceding month value - -- **Formula for transfer:** - -> Value of transfer from node for a month = Value defined at the node - Percentage of preceding month value -> -> Value of transfer to node for a month = Value defined at the node + Percentage of preceding month value - -1. > **Percentage Node** - -> Value for the percentage node is calculated as percentage of the parent node value -> -> **Formula:** -> -> Value of node for a month = (Value defined at the node \* Value of parent Node/100) -> -> There is only type of modeling/transfer that can be applied - -1. > **Linear (% point): ** - -> If linear (% point) modeling is applied then the value is calculated as the sum of  Percentage of the node and linear (% point) percentage value of the parent node. -> -> If linear number transfer is applied then the percentage value of that node is decreased from this node and the same amount is increased in the transferred node. - -- **Formula for modeling:** - -> Value for a node for a month = (Value defined at the node +/- Linear % point Value) \* Node value of parent / 100 - -- **Formula for transfer:** - -> Value of transfer from node for a month = (Value defined at the node - Linear % point Value) \* Node value of parent / 100 -> -> Value of transfer to node for a month = (Value defined at the node + Linear % point Value) \* Node value of parent / 100 - -1. > **Forecasting Unit Node** - -> Value for the percentage node is calculated as percentage of the parent node value based on forecasting unit parameters -> -> **Formula:** -> -> Value of node for a month = (Value defined at the node \* Value of parent Node/100) -> -> There is only type of modeling/transfer that can be applied - -1. > **Linear (% point): ** - -> If linear (% point) modeling is applied then the value is calculated as the sum of  Percentage of the node and linear (% point) percentage value of the parent node. -> -> If linear number transfer is applied then the percentage value of that node is decreased from this node and the same amount is increased in the transferred node. - -- **Formula for modeling:** - -> Value for a node for a month = (Value defined at the node +/- Linear % point Value) \* Node value of parent / 100 - -- **Formula for transfer:** - -> Value of transfer from node for a month = (Value defined at the node - Linear % point Value) \* Node value of parent / 100 -> -> Value of transfer to node for a month = (Value defined at the node + Linear % point Value) \* Node value of parent / 100 - -1. > **Planning Unit Node** - -> Value for the percentage node is calculated as percentage of the parent node value based on planning unit parameters -> -> **Formula:** -> -> Value of node for a month = (Value defined at the node \* Value of parent Node/100) -> -> There is only type of modeling/transfer that can be applied - -1. > **Linear (% point): ** - -> If linear (% point) modeling is applied then the value is calculated as the sum of Percentage of the node and linear (% point) percentage value of the parent node. -> -> If linear number transfer is applied then the percentage value of that node is decreased from this node and the same amount is increased in the transferred node. - -- **Formula for modeling:** - -> Value for a node for a month = (Value defined at the node +/- Linear % point Value) \* Node value of parent / 100 - -- **Formula for transfer:** - -> Value of transfer from node for a month = (Value defined at the node - Linear % point Value) \* Node value of parent / 100 -> -> Value of transfer to node for a month = (Value defined at the node + Linear % point Value) \* Node value of parent / 100 - -## Forecasting Module: Consumption Forecast - -1. > **Interpolate** - -> QAT interpolates by finding the nearest values on either side (before or after the blank), calculates the straight line in between them and uses that straight-line formula to calculate the value for the blank(s). Note that QAT will not interpolate for months where actual consumption is zero. QAT will only interpolate if there is at least one data point before and one data point after the blank value(s). -> -> Mathematically: - -- Where x represents months, and y represents actual consumption, - -- Where known data values are (x0 , y0) and (x1 , y1) - -- Where any unknown data values are (x, y) - -- The formula for the interpolated line is - -> **Formula:** -> -> y = y0+(x-x0)\*(y1-y0)/(x1-x0) - -2. > **Stockout Rate** - -> Stockout Rate is calculated as percentage of ratio of Stockout rate in days to that of no of days in a month -> -> **Formula:** -> -> Stockout Rate = (Stockout Rate(days)/No of days in month) \* 100 - -3. > **Adjusted Consumption** - -> Adjusted Consumption is calculated based on Actual Consumption, Reporting Rate, Stockout Rate(days), No of days in month using below formula -> -> **Formula:** -> -> If Actual Consumption is empty then, -> -> Adjusted Consumption = “” -> -> Otherwise, -> -> Adjusted Consumption= (Actual Consumption/Reporting Rate/(1-(Stockout Rate(days)/No of days in month)))\*100 - -4. > **Conversion Factor for Data entry and Adjustment Screen** - -> If the Actual Consumption is in Forecasting Unit then -> -> Conversion Factor = 1/Planning Unit Conversion Factor -> -> If the Actual Consumption is in Planning Units then -> -> Conversion Factor = 1 -> -> If the Actual Consumption is in Other Unit then -> -> Conversion Factor = 1/Conversion to FU(User Entered) - -5. > **Adjusted Consumption in terms of Planning Unit** - -> Adjusted Consumption in terms of planning unit is calculated by multiplying Adjusted Consumption with Conversion Factor -> -> **Formula:** -> -> Adjusted Consumption(Planning Unit) = Adjusted Consumption \* Conversion Factor - -6. > **Forecast Error (%)** - - - -- **WAPE** (Weighted Absolute Percentage Error) divides the sum of absolute differences by the sum of actual values for a particular time window. Time window is 6 months. - -> **Formula:** -> -> WAPE = ((Abs(actual consumption month 1-forecasted consumption month 1)+ Abs(actual consumption month 2-forecasted consumption month 2)+ Abs(actual consumption month 3-forecasted consumption month 3)+ Abs(actual consumption month 4-forecasted consumption month 4)+ Abs(actual consumption month 5-forecasted consumption month 5)+ Abs(actual consumption month 6-forecasted consumption month 6)) / (Sum of all actual consumption in the last 6 months)) - -- **RMSE (**Root mean square error) is calculated as square root of ratio of summation of square of difference between forecast - actual to number of observations. - -> **Formula:** -> -> RMSE = Square root \[ Summation(Square(Forecast – Actual)) / No. of Observations \] - -- **MAPE (**Mean absolute percentage error) is calculated as ratio of 1 is to number of observations multiplied by summation of absolute difference between actual and forecast to multiplication of absolute actual and 100 - -> **Formula:** -> -> MAPE = (1/No of Observations) \* Summation(Absolute(actual – forecast) / Absolute(actual)) \* 100 - -- **MSE** (Mean squared error) is calculated as multiplication of ratio of 1 to no of observations and summation of square of difference between actual and forecast. - -> **Formula:** -> -> MSE = (1/No of Observations) \* Summation(Square(actual – forecast)) - -- **R squared** - -> R2 = 1 – \[sum squared regression (SSR) / total sum of squares (SST)\]. The sum squared of the residuals for the regression is the sum of its residuals squared, and the total sum of squares is the sum of the distance the data is away from the mean, all squared. By “sum of squares” we mean the sum of squared deviations between **actual** values and the mean (SST), or between **predicted** values and the mean (SSR). The R2 value is always a number between 0 and 1. R2 is a measure the fit of a regression line to a series of historical observations with values closer to 1 indicating a stronger correspondence between the actual and predicted (regression model) values. It is not a measure of error and should not be used by itself to assess the fitness of a prediction, but in combination with other error metrics and the user’s knowledge of the program. -> -> **Formula:** -> -> R2= 1- \[SSR / SST\] - -7. **Import From QAT Supply Plan** - - - -- QAT allows users to import actual data from their supply plans into a consumption forecast. - - First, a user will select a Forecast Program and Date Range for the imported actual consumption. - - Note: A toggle is shown if not all unmapped planning units are to be imported. This is useful if there are many planning units, and you only import a selected few. After mapping the selected few planning units, click the toggle “Do not import all unmapped planning units”, which will then automatically select the remaining planning units to not be imported. - - - Second, a Supply Plan Program and Supply Plan Version will be selected. This is useful if a user wants a specific uploaded supply plan version and not just the latest. - - Note: A User can select more than one program to import from. - - - Third, after selecting a Supply Plan program, the Supply Plan Planning Units will be shown along side the Forecast Planning Unit dropdown. - - Note: The Forecast Planning Unit dropdown allows the user to select a specific Forecast Planning Unit or not to import that specific Supply Plan Planning Unit. - - - After selecting next, now a % of Supply Plan must be inputted. - - A tool tip is shown on the top column noting “Percentage of monthly actual consumption quantity from the Supply Plan program that will be imported into the Forecast Program. - - - This is to allow a specific percentage to be used if not all 100% is needed. - -## Forecasting Module: Reports & Outputs - -### Compare & Select - -1. **Compare to Consumption Forecast** is displayed only when there are both tree and consumption forecasts. It displays the values as - - - -- > Higher than H% than the highest consumption forecast or - -- > Lower than L% than the lowest consumption forecast - -> **Formula:** -> -> H% = (Sum(Selected tree forecast)-Sum(Consumption Forecast))/Sum(Consumption Forecast) -> -> L% = (Sum(Selected tree forecast)-Sum(Consumption Forecast))/Sum(Consumption Forecast) - -2. **Multi-Select Trees** - -> In the compare & select screen, users can select multiple tree forecasts as their final forecast, which will aggregate the monthly forecast quantities. Users cannot select multiple consumption forecasts or a combination of tree and consumption forecasts as their final forecast -> -> Note: Consumption Extrapolation Forecast Error and Compare & Select Forecast Error will match on both screens even if the historical range of data is limited. - -### Forecast Summary - -1. > **Stock or Unmet Demand** - -> Stock or Unmet demand is calculated as difference between sum of stock and existing shipments for a planning unit and total forecasted consumption -> -> **Formula:** -> -> Stock or Unmet Demand = (Stock for a planning unit + Existing Shipments for a planning unit) -(Total forecasted consumption) - -2. > **Desired Stock** - -> Desired Stock is calculated as Ratio of multiplication of months of stock for a planning unit and total forecasted consumption to No of months in forecast period - -**Formula:** - -> Desired Stock =((Months of stock for a planning unit) \*(Total Forecasted Consumption) /(No of months in forecast period)) - -3. > **Procurement Surplus/Gap** - -Procurement surplus is calculated as difference between stock and desired stock - -**Formula:** - -Procurement Surplus = Stock or Unmet Demand - desired Stock - -4. > **Procurements Needed** - -> Procurements Needed is calculated as multiplication of Procurement surplus/Gap and unit price. - -**Formula:** - -Procurements Needed = Procurement surplus \* Unit price - -5. > **Freight Cost** - -> Freight cost is calculated as multiplication of ratio of Freight percentage by 100 and sum of procurements needed - -**Formula:** - -Freight Cost = Freight Percentage /100 \* Total procurement Needed - -6. > **Total Cost** - -Total Cost is calculated as sum of sum of procurements needed and Freight cost - -**Formula:** - -Total Cost = Sum of Procurements Needed + Freight Cost - -## Supply Planning and Forecasting Module: Uploading Versions - -The below section details the different conditions that QAT looks for when identifying conflicts in a version upload (for both a supply plan program and a forecast program). - -The following example will be used throughout the explanation below: A user is trying to upload local version 8 and the latest version available on the server is version 10. Once any conflicts are resolved and the user confirms, the uploaded version will be version 11. QAT compares the 3 different versions: - -> **a. Server v8** (this is the server version that the user downloaded prior to making edits) -> -> **b. Local v8** (this is the version the user intends to upload) -> -> **c. Server v10** (this is the latest server version) - -Depending on the data type, QAT either compares actual records, or compares modified dates. Actual records cannot be compared for some data because the data is too vast and complex. - - - - - - - - - - - - - - -
Actual records are comparedModified dates are compared
-
    -
  • -

    Supply Planning Module

    -
      -
    • -

      - Actual/Forecasted consumption, Inventory, Adjustment, Shipment - records -

      -
      • -
    • -

      QAT Problem List

      -
      • -
    • -

      ERP Shipment Linking*

      -
      • -
    -
    • -
  • -

    Forecasting Module

    -
      -
    • -

      Planning Unit Settings

      -
      • -
    • -

      Version Settings

      -
      • -
    • -

      Selected Forecast

      -
      • -
    -
    • -
- 		-
    -
  • -

    Forecasting Module

    -
      -
    • -

      Actual consumption, adjustments, extrapolation

      -
      • -
    • -

      Tree

      -
      • -
    -
    • -
-
- -> \* For ERP linking, before the below logic, QAT first checks if the ERP shipment is already linked to another program. If it is linked, then QAT highlights in red and does not allow upload. - -Using the logic outlined below (testing each condition in sequential order), QAT determines if data is - -- > **Newly added on the local version (Local v8)** ß Condition 1 - -- > **Newly added on the server version (Server v10)** ß Condition 2 - -- > **Unchanged since the previous server version (Server v8)** ß Condition 3a - -- > **Updated on the local version (Local v8) with no conflicts ß** Condition 3b - -- > **Updated on the server version (Server v10) with no conflicts** ßCondition 3c - -- > **Or, a conflict between the local and server versions.** ß Condition 3d - -#### Condition 1: Newly added data in local version  - -First, QAT checks each data point in the local version (Local v8) to confirm if it is newly added data. If so, data is shown as **green** in the upload screen. - -**a. Server v8 - Record does not exist** - -**b. Local v8 - Record exists** - -**c. Server v10- Record does not exist** - -Below are some examples for this condition: - -1. > **Consumption (Supply Planning):** For example, there is an actual consumption record in local v8 for May 2023, planning unit A, alternate reporting unit B, region X. QAT checks server v10 and server v8 to see if an actual consumption record in May 2023, planning unit A, alternate reporting unit B, region X exists. If not, local v8 is the latest. - -2. > **Inventory (Supply Planning):** For example, there is an inventory record in local v8 for May 2023, planning unit A, alternate reporting unit B, region X, Data Source Y. QAT checks server v10 and server v8 to see if an inventory record in May 2023, planning unit A, alternate reporting unit B, region X, Data Source Y exists. If not, local v8 is the latest. - - - -2. > **Adjustments, Shipments, QPL (Supply Planning):** Since IDs are only assigned after the supply plan is uploaded, QAT checks the IDs for each record in local v8 to see if they are “0”. Records with the ID “0” were newly created in this local version, so for these records, local v8 is the latest. QAT does not check server versions. - -3. > **Trees (Forecasting):** Since IDs are only assigned after the forecast is uploaded, QAT checks the IDs for each tree in local v8 to see if they are “0”. Trees with the ID “0” were newly created in this local version, so for these, local v8 is the latest. QAT does not check server versions. - -4. > **Planning Unit Settings (Forecasting):** QAT checks if that planning unit ID is present in the Sever v8 and Server v10. If the planning unit ID does not exist in either, local v8 is the latest. - -5. > **Consumption Data and Extrapolation (Forecasting):** QAT checks if the data for this planning unit and region is present in Server v10 based on the presence of the modified date. If the planning unit and region data is not present in Server v10, local v8 is the latest. - -6. > **Selected Forecast (Forecasting):** QAT checks if a selected forecast exists for this planning unit and region in Server v10. If no selection is present in Server v10, local v8 is the latest. - -#### Condition 2: Newly added data in server version  - -If Condition 1 fails, QAT checks the latest server version (Server v10) to see if that data was newly added by comparing it with local version (Local v8). QAT does not check previous server version (server v8). If the data is not present on the local version, that means the data was newly added on the latest server version, and there is no conflict with the local version. This data will be added to the newly uploaded version (Server v11) and data is shown as **blue** in the upload screen. - -**a. Server v8 - Record does not exist** - -**b. Local v8 - Record does not exist** - -**c. Server v10 - Record exists** - -Below are some examples for this condition: - -1. > **Consumption Inventory, Adjustment, Shipment, QPL (Supply Planning): For example, there is an actual consumption record with unique ID \#A in server v10. QAT checks if the unique ID\#A is also present in local version v8. If the unique ID is not present in local version, server v10 is the latest. ** - -2. > **Trees: For example, there is tree with unique ID \#B in server v10. QAT checks if the unique ID\#B is also present in local version v8. If the unique ID is not present in local version, server v10 is the latest. ** - -3. > **Planning Unit Settings (Forecasting):** **For example, there is planning unit with planning unit ID \#C in server v10. QAT checks if the planning unit \#C is also present in local version v8. If the Planning Unit ID is not present in local version, server v10 is the latest. ** - - - -7. > **Consumption Data and Extrapolation (Forecasting): After QAT finds data for a** planning unit and region server v10, QAT looks at the same planning unit and region in local v8 looks for a modified date. If the modified date does not exist in the local v8, **server v10 is the latest. ** - -8. > **Selected Forecast (Forecasting):** **After QAT finds data for a selected forecasts for a particular planning unit and region in server v10, QAT looks for** the same planning unit and region in local v8 looks for a selected forecast. If the selected forecast does not exist in the local v8, **server v10 is the latest. ** - -#### Condition 3a: Local and latest server are the same  - -If the conditions above fail, QAT checks each data point in the local version (Local v8) to see if they are same as the latest (v10) server version. If same, the data is shown un-highlighted in the upload screen. - -**a. v8 server – Record is X** - -**b. v8 local – Record is X** - -**c. v10 latest server – Record is X** - -Below are some examples for this condition: - -1. > **Consumption, Inventory, Adjustment, Shipments, QPL, version settings, planning unit settings and selected forecasts:** QAT compares each record in local version (v8) with the latest server versions (v10). For example, for actual consumption record for the month June 22, QAT checks each field (ARU, data source, quantity, days of stock out, etc) to see if the local (v8) and the latest server version (v10) are the same. If they are the same, then no changes have been made since server v8, or they were updated to be the same value. - -2. > **Consumption (Forecasting) and Trees: QAT compares the last modified date for each record in local version (v8) with the last modified date of the latest server version (v10). If they are the same, then no changes have been made since server v8.** - -#### Condition 3b: Changes only in local version  - -If the conditions above fail, then QAT compares to see if the previous server version (Server v8) and the latest server version (server v10) are the same. If so, QAT infers that the local version (local v8) was changed and data is shown as **green** in the upload screen. - -Below are some examples for this condition: - -1. **Consumption, Inventory, Adjustment, Shipments, QPL, version settings, planning unit settings and selected forecasts:** For example, an actual consumption record for June 22 has “Warehouse Reports” as the data source in v8 local. If the data source field for the previous (v8) and latest (v10) server versions are both “LMIS Reports”, this indicates that the data was modified in local version, so local v8 is the latest. - -> **a. v8 server – data source is LMIS Reports ** -> -> **b. v8 local –** **data source is Warehouse Reports ** -> -> **c. v10 latest server - data source is LMIS Reports  ** - -2. **Consumption (Forecasting) and Trees:** If the last modified dates of the previous (v8) and latest (v10) server versions are the same, this indicates that the data was modified in local version, so local v8 is the latest. - -> **a. v8 server - last modified date is 15 Sep 2023, 12:00:00** -> -> **b. v8 local - last modified date is 20 Sep 2023, 15:15:00** -> -> **c. v10 latest server - last modified date is 15 Sep 2023, 12:00:00** - -#### Condition 3c: Changes only in latest server version  - -If the conditions above fail, then QAT compares to see if the previous server version (Server v8) and the local version (local v8) are the same. If so, QAT infers that the latest server version (server v10) was changed and the data is shown as **blue** in the upload screen. - -Below are some examples for this condition: - -1. **Consumption, Inventory, Adjustment, Shipments, QPL, version settings, planning unit settings and selected forecasts: For example, an actual consumption record for June 22. If the data source value in** v8 server and v8 local are the same, this indicates that the data was modified in latest server version (v10), so **server v10 is the latest. ** - -> **a. v8 server - data source is LMIS Reports ** -> -> **b. v8 local - data source is LMIS Reports ** -> -> **c. v10 latest server - data source is Warehouse Reports ** - -2. **Consumption (Forecasting) and Trees:** If the last modified dates of the previous server version (v8) and the local version (v8) are the same, this indicates that the data was modified in latest server version (v10), so **server v10 is the latest. ** - -> **a. v8 server - last modified date is 15 Sep 2023, 12:00:00 ** -> -> **b. v8 local - last modified date is 15 Sep 2023, 12:00:00 ** -> -> **c. v10 latest server - last modified date is 20 Sep 2023, 15:30:00** - -#### Condition 3d: Changes in both local and latest server version (same parameter) - -If the conditions above fail, this means that the 3 versions are not matching and there is a conflict. If so, data is highlighted **yellow** in the upload screen. - -Below are some examples for this condition: - -1. **Consumption, Inventory, Adjustment, Shipments, QPL, version settings, planning unit settings and selected forecasts:** For an actual consumption record for the month of June 22**, i**f the data source value does not match for any of the versions, this indicates that the data is modified in both local (v8) and latest server (v10) versions, so QAT highlights the row in yellow to indicate a conflict for the user to resolve. - -> a. v8 server - data source is LMIS Reports -> -> **b. v8 local - data source is SDP Reports** -> -> **c. v10 latest server - data source is Warehouse Reports** - -2. **Consumption (Forecasting) and Trees**: If the last modified date does not match for any of the versions, this indicates that the data is modified in both local (v8) and latest server (v10) versions, so QAT highlights the row in yellow to indicate a conflict for the user to resolve. - -> **a. v8 server - last modified date is 15 Sep 2023, 12:00:00** -> -> **b. v8 local - last modified date is 16 Sep 2023, 13:00:00** -> -> **c. v10 latest server - last modified date is 20 Sep 2023, 15:30:00** -> -> **a. v8 server - last modified date is 28 A Sep 2023, 12:00:00** -> -> **b. v8 local - last modified date is 16 Sep 2023, 13:00:00** -> -> **c. v10 latest server – tree is missing ** - -#### Condition 4: Changes in both local and latest server version (different parameters)  - -After checking all the conditions, QAT checks to see if any records that have a combination of 3b and 3c, but for different fields. If so, data is highlighted **yellow** in the upload screen. - -1. **Consumption, Inventory, Adjustment, Shipments, QPL, version settings, planning unit settings and selected forecasts:** For an actual consumption record for the month of June 22**,** the data source is updated in the local version (Condition 3b) and quantity is changed in server version (condition 3c). In this case, QAT does not know which version to use, so QAT highlights the row in yellow to indicate a conflict for the user to resolve. - -| **Version** | **Data Source** (Condition 3b) | **Quantity** (Condition 3c) | -| --------------------- | ------------------------------ | --------------------------- | -| v8 server | LMIS Reports | 50 | -| **v8 local** | **Warehouse Reports** | 50 | -| **v10 latest server** | LMIS Reports | 55 | - -2. **Consumption (Forecasting) and Trees:** This does not apply to since only the modified date is compared for these two data types - -# diff --git a/docs/user/11-forecasting-module-forecasting.md b/docs/user/11-forecasting-module-forecasting.md new file mode 100644 index 0000000..1e68595 --- /dev/null +++ b/docs/user/11-forecasting-module-forecasting.md @@ -0,0 +1,164 @@ +--- +id: forecasting-module-forecasting +title: "Forecasting Module: Forecasting" +sidebar_label: "Forecasting Module: Forecasting" +sidebar_position: 11 +--- + +# Forecasting Module: Forecasting + +## Consumption Forecasts +Consumption-based forecasts use historical data to project future demand. This method is ideal for stable programs with at least 24 months of reliable monthly consumption data. + +**The Workflow:** +1. **Import/Input:** Bring in historical actuals from the Supply Planning module or enter them manually. +2. **Adjust:** Account for under-reporting, stockouts, and missing data points. +3. **Extrapolate:** Apply statistical models to project the "Adjusted Consumption" into the future. + +### Data Entry & Import +You can populate historical actuals via two methods: + +#### Method 1: Import from Supply Plan +**Navigation:** **Consumption-Based Forecast** > **Import from QAT Supply Plan**. +- **Mapping:** Link Supply Plan units to Forecast units. You can use the "Do not import all unmapped" toggle for large datasets. +- **Regional Split:** Select which regions to import and the percentage of consumption to attribute to the forecast. +- **Conflict Handling:** Data already present is highlighted in **Yellow**. Importing will override existing records. + +#### Method 2: Manual Data Entry +**Navigation:** **Consumption-Based Forecast** > **Data Entry and Adjustments**. +- **Interface:** Select the program and review period (default: trailing 36 months). +- **Expansion:** Expand rows to drill down into regional data. +- **Unit Conversion:** Use the "change" link to toggle entry between Planning Units (PU) or Forecasting Units (FU). + +![Data Entry Interface](/img/media/image242.png) +*Figure 1: Historical Consumption Data Entry Table* + +### Statistical Adjustments +Raw data must be cleaned to create a reliable "Adjusted Consumption" series. QAT handles three types of adjustments: + +#### 1. Under-Reporting +If reporting is less than 100%, QAT inflates consumption proportionally, assuming non-reporting facilities consume at the same rate as reporting ones. + +#### 2. Stockouts +QAT adjusts consumption for days spent out of stock to estimate true demand. +- **Stock Out Rate** = `Stocked Out (Days)` / `Days in Month` +- **Adjusted Consumption** = `Actual Consumption` / `Reporting Rate` / (1 - `Stock Out Rate`) + +#### 3. Missing Values (Interpolation) +The **Interpolate** button fills gaps in your data using a straight-line formula between the nearest known values. +> [!NOTE] +> QAT will not interpolate months where actual consumption is zero (as this may be a valid data point). It only fills blank "missing" cells. + +### Extrapolation Concepts +QAT offers several statistical models to project future demand. Choose a model based on your data availability and consumption patterns: + +- **Simple Models (3+ months data):** + - **Moving Average:** Best for stable data without strong trends or seasonality. + - **Semi-Averages/Linear Regression:** Best for identifying steady growth or decline (trends). +- **Advanced Models:** + - **ARIMA (13+ months data):** Flexible model that accounts for trends and seasonal cycles. + - **Triple Exponential Smoothing (24+ months data):** Best for complex data with both strong trends and annual seasonality. + +### Interpreting Forecast Errors +QAT calculates several error metrics to help you select the best fit. + +| Metric | Definition | Best Used For... | +| :--- | :--- | :--- | +| **MAPE** | Mean Absolute Percentage Error. | Comparing accuracy across different data scales. | +| **WAPE** | Weighted Absolute Percentage Error. | Datasets with low or intermittent values. | +| **RMSE** | Root Mean Squared Error. | Highlighting and penalizing large outliers. | +| **R²** | Correlation Coefficient. | Measuring how well the model fits historical patterns. | + +--- + +## Tree Forecasts +Tree-based forecasting is a flexible method used when historical consumption is unavailable or unreliable. It supports **morbidity, services, and demographic** methodologies by allowing you to build a logical "tree" of drivers that result in product demand. + +### Building & Managing Trees +**Navigation:** **Forecasting Tree** > **Manage Tree**. + +You can manage your trees through the following actions: +- **Draw Your Own:** Start from a blank canvas. +- **Template:** Use a pre-defined tree structure (e.g., for specific health programs). +- **Duplicate:** Copy an existing tree structure to another program (requires both programs to be downloaded). +- **Tree Table:** Access a spreadsheet-like view for bulk editing node values without changing the structure. + +> [!NOTE] +> Trees are saved locally first. You must **Upload Version** to save your work to the server. + +### Node Types & Hierarchy +A tree is built from the top down using specific node types. Every tree must end in **Planning Units** to generate a forecast. + +| Node Type | Function | Allowed Children | Advanced Options | +| :--- | :--- | :--- | :---: | +| **∑ Aggregation** | Sums up all children. | Aggregation, Number. | - | +| **# Number** | A fixed value (e.g., total population). | Percentage, FU. | ⇅, Transfer | +| **% Percentage** | A percentage of the parent value. | Percentage, FU. | ⇅, Transfer | +| **Funnel** | Sums values from linked source nodes. | Percentage, FU. | - | +| **FU (Forecasting Unit)** | Usage parameters (Continuous/Discrete). | Planning Unit. | ⇅, Lag | +| **PU (Planning Unit)** | The final product output. | None. | Override | + +#### Node Actions +- **Delete:** Removes node and all its children. +- **Copy/Move:** Relocates a branch to a different tree or parent. +- **Add Branch Template:** Inserts a pre-defined branch (e.g., a standard drug regimen). +- **Collapse/Expand:** Simplifies the visual view of the tree. + +### Node Attributes +Each node has editable fields that define its value and behavior: + +- **# Number Node:** Define the **Node Unit** (patients, people, etc.) and its **Value** for a specific starting month. +- **% Percentage Node:** Define the percentage of the parent value. QAT uses this to calculate the node's absolute value. +- **Forecasting Unit (FU) Node:** + - **Type of Use:** + - **Continuous:** Daily/weekly usage (e.g., one pill every day). + - **Discrete:** Occasional usage (e.g., 5 vials per treatment course). + - **Lag:** Delays the start of product usage relative to the parent driver (e.g., product usage starts 2 months after diagnosis). +- **Planning Unit (PU) Node:** Defaults to the system conversion but can be overridden manually if needed. + +### Dynamic Changes (Modeling & Transfers) +Trees are not static; values can change over time to reflect program growth or transitions. + +#### 1. Modeling Types +| Type | Behavior | Best Used For... | +| :--- | :--- | :--- | +| **Linear (#)** | Adds/subtracts a fixed number each month. | Steady local growth. | +| **Linear (%)** | Adds/subtracts a fixed % of the *starting* value. | Consistent growth rates. | +| **Exponential (%)** | Multiplies the *previous* month by a percentage. | Compounding growth. | +| **Linear (% point)** | Adjusts a percentage node's value (e.g., 30% -> 31%). | Market share shifts. | + +#### 2. Transfers +Transfers link two nodes of the same level (for Number nodes) or same parent (for Percentage nodes). As the "Source" node decreases, the "Destination" node increases proportionally. This is essential for regimen transitions. + +#### 3. Seasonality & Manual Changes +You can further refine monthly data by clicking **Show Monthly Data**: +- **Seasonality Index:** Enter a percentage (e.g., `20%` for a 20% increase over baseline) to reflect cyclic demand. +- **Manual Change:** Override a specific month's value for one-off events (e.g., a massive drug campaign). + +### Modeling Calculator +If you don't know the monthly rate, use the **Modeling Calculator** (⇅) to derive it: +- **Ending Value:** Enter your start value, target date, and final target value. QAT calculates the monthly rate. +- **Annual Target:** Enter a yearly cumulative target (Actual + Target Year). QAT interpolates a smooth monthly transition to avoid "stairstep" patterns. + +### Advanced Techniques +#### Lag in Usage +Available in **FU Nodes**. Use the **Lag** field to delay product usage relative to the parent driver. +- *Example:* If patients are diagnosed in Month 1 but start treatment in Month 3, enter a lag of `2`. + +#### Calculation Methods (Discrete Usage) +- **All in First Month:** Frontloads the entire treatment course quantity into the patient's first month. (Default) +- **Month-by-Month:** Spreads usage across the duration of the course (e.g., 1 pill/month for 6 months). + +#### Funnel Nodes +Funnel nodes allow you to aggregate source nodes from different branches—or even different trees—into a single stream for further calculation. +- *Use Case:* Different demographic groups (Adults, Children) that all use the same Viral Load testing instruments. + +### Validations & Templates +#### Validations +- **Modeling Validation:** Charts showing how your drivers (Population, Patients) change over time. +- **Product Validation:** Aggregated view of all Planning Units across the tree for consistency checks. + +#### Templates +- **Tree Templates:** Pre-built global structures for standard programs (e.g., Malaria morbidity trees). +- **Branch Templates:** Reusable regimen-specific branches (e.g., "Standard First Line Adult Regimen"). +- **Usage Templates:** Presets for FU nodes (Discrete/Continuous parameters) to ensure consistency across the team. diff --git a/docs/user/12-annex-3-user-role-matrix.md b/docs/user/12-annex-3-user-role-matrix.md deleted file mode 100644 index fca1d0a..0000000 --- a/docs/user/12-annex-3-user-role-matrix.md +++ /dev/null @@ -1,1723 +0,0 @@ ---- -id: annex-3-user-role-matrix -title: "Annex 3: User Role Matrix" -sidebar_label: "Annex 3: User Role Matrix" -sidebar_position: 12 ---- - -# Annex 3: User Role Matrix - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Role - - Role description -
- Application Admin - For managing app-wide settings (labels), create roles
- Realm Admin - - For managing realm specific parameters and realm masters (planning - units, technical areas, orgs etc.) -
- Supply Plan Program Admin - - For managing program specific parameters (lead times, planning units, - ARUs, budgets etc.) -
- Supply Plan Reviewer - For those reviewing/approving supply plans.
- Supply Plan Program User - For those actively supply planning and needing to enter data.
- Supply Plan Viewer - Reports - - For anyone who only need to view reports (not including supply - planning), but not enter data. Depending on the access settings, could - be at global or program/country level. -
- Supply Plan Viewer - Supply Plan Review - - Supplemental role to reports viewer, for those who need to see status of - supply plan review process. -
- (Includes SP Notifications) -
- Supply Plan Viewer - Data - - Supplemental role to reports viewer, for those who need to access raw - data entry screens for viewing and to see status of supply plan review - process. This role allows downloading of supply plan data (allows for - offline viewing), without ability to upload back to server. -
- Forecast Program Admin - - For managing program specific parameters (forecast period, planning - units, equivalency units, usage templates, etc.). -
- Forecast Program User - - For those actively forecasting and needing to enter data/build - forecasts. -
- Forecast Viewer - - For anyone who only need to view forecasts and forecast outputs, but not - enter data. -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
- Business Function - - Application Admin - - Realm Admin - - Supply Plan Program Admin - - Supply Plan Reviewer - - Supply Plan Program User - - Supply Plan Viewer - Reports - - Supply Plan Viewer - Data - - Supply Plan Viewer - Supply Plan Review - - Forecast Program Admin - - Forecast Program User - - Forecast Viewer -
- Application Masters -
View Application DashboardYNNNNNNNYYY
Label TranslationsYNNNNNNNNNN
Database TranslationYNNNNNNNNNN
Manage CountryAdd/manageNNNNNNNNNN
Manage RoleAdd/manageNNNNNNNNNN
Manage Language Add/manageNNNNNNNNNN
Manage CurrencyAdd/manageNNNNNNNNNN
Manage DimensionAdd/manageNNNNNNNNNN
Manage UnitAdd/manageNNNNNNNNNN
Manage UserAdd/manageAdd/manageNNNNNNNNN
Assign role to userYYNNNNNNNNN
Manage RealmAdd/manageManageNNNNNNNNN
Upload User ManualYNNNNNNNNNN
Usage PeriodManageViewNNNNNNNNN
- Realm level Masters -
View Realm DashboardNYNNNNNNNNN
Realm Country NAdd/ManageNNNViewNNNNN
RegionNAdd/ManageNNNNNNNNN
Data SourceNAdd/ManageViewNViewNViewNNNN
Data Source TypeNAdd/ManageViewNViewNViewNNNN
Funding SourceNAdd/ManageAdd/ManageNViewNViewNNNN
Create/manage OrganizationNAdd/ManageViewNViewNViewNNNN
Organization TypeNManageNNNNNNViewViewN
Procurement AgentNAdd/ManageAdd/ManageNViewViewNNNNN
Procurement Agent TypeNManageNNNNNNNNN
SupplierNNNNNNNNNNN
Alternate Reporting UnitNAdd/ManageAdd/ManageNNViewNNNNN
Forecasting UnitNAdd/ManageViewNNNNNViewViewView
Planning UnitNAdd/ManageViewNNNNNViewViewView
Planning Unit CategoryNAdd/ManageViewNViewNNNViewViewN
Planning Unit VolumeNAdd/ManageNNNNNNViewViewN
Procurement UnitNAdd/ManageNNNNNNNNN
Tracer CategoryNAdd/ManageViewNViewNViewNViewViewN
Equivalency UnitNManageNNNNNNManageManageN
Technical AreaNAdd/ManageViewNViewNViewNViewViewN
Forecast MethodNManageNNNNNNViewViewN
- Program Management -
View Program DashboardNYYYYNNNYYN
Setup/create a ProgramNYNNNNNNYNN
Update program infoNManageManageNNNNNManageNN
Planning unit (for a program)NAdd/ManageAdd/ManageNNNNNAdd/ManageNN
Map Procurement AgentNAdd/ManageAdd/ManageNNNNNAdd/ManageNN
BudgetNAdd/ManageAdd/ManageN -

N

-

(they can see in Budget report)

- 		NNNNNN
Import / Export ProgramNYYNYNNNYYY
Download ProgramNYYYYNYNYYN
Upload versionNYYNYNNNYYN
PipeLine Program ImportNYNNNNNNNNN
View supply plan version & reviewNYYYYNNYNNN
Review/Approve a VersionNNNYNNNNNNN
Notification Cc ApproveNYYYYNYYNNN
Notification Cc UploadNNYNNNNNNNN
Notification Cc RejectNNYYNNNNNNN
Notification to ApproveNNNNNNNNNNN
Notification to UploadNNNYNNNNNNN
Notification to RejectNNNNNNNNNNN
Update Version SettingsNManageNNNNNNManageViewView
- Supply plan data -
- Supply plan data (consumption / inventory / shipments) in data entry - screen - NAdd/EditAdd/EditNAdd/EditNViewNNNN
ERP shipment linking and delinkingNYYNYNNNNNN
Import Quantimed dataNYYNYNNNNNN
- Supply planning -
Manage/edit Supply PlanNYYYYNNNNNN
View Supply PlanNYYYYNYNNNN
Scenario PlanningNYYYYNNNNNN
View Supply Plan ReportNYYNYYNNNNN
- Reports -
View QAT Problem List reportNYYNYNNNNNN
View Program Catalog ReportNYYNYYNNNNN
- Stock Status Reports -
View Stock Status Over Time reportNYYNYYNNNNN
View Stock Status Matrix reportNYYNYYNNNNN
View Stock Status Snapshot reportNYYNYYNNNNN
View Stock Status Snapshot (Global) reportNYYNYYNNNNN
- Consumption Reports -
View Consumption (forecast vs actual) reportNYYNYYNNNNN
View Consumption (Global) reportNYYNYYNNNNN
View Forecast Error (Monthly) reportNYYNYYNNNNN
View Forecast Error by (by planning unit) reportNYYNYYNNNNN
- Shipment Reports -
View Shipment (Global) reportNYYNYYNNNNN
View Shipment Overview reportNYYNYYNNNNN
View Shipment Details reportNYYNYYNNNNN
View Shipment Cost Details reportNYYNYYNNNNN
View Shipment Cost Overview reportNYYNYYNNNNN
View Budget reportNYYNYYNNNNN
View Procurement Agent Lead Time reportNYYNYYNNNNN
- Inventory Reports -
View Expiries reportNYYNYYNNNNN
View Cost of Inventory reportNYYNYYNNNNN
View Inventory Turns reportNYYNYYNNNNN
View Stock Adjustment reportNYYNYYNNNNN
View Warehouse Capacity (by program) reportNYYNYYNNNNN
View Warehouse Capacity (by country) reportNYYNYYNNNNN
- Consumption-Based Forecast -
Import from QAT Supply PlanNYNNNNNNYYN
Data Entry and AdjustmentNYNNNNNNYYView
ExtrapolationNYNNNNNNYYView
- Tree Forecast -
Manage TreeNYNNNNNNYYView
Tree TemplatesNYNNNNNNYYView
Usage TemplatesNManageNNNNNNManageViewView
Modeling ValidationsNYNNNNNNYYY
Product ValidationsNYNNNNNNYYY
- Forecast Analysis Output -
Compare and Select ForecastNYNNNNNNYYY
Monthly ForecastNYNNNNNNYYY
Forecast SummaryNYNNNNNNYYY
Version ComparisonNYNNNNNNYYY
- -# diff --git a/docs/user/12-forecasting-module-reports-and-outputs.md b/docs/user/12-forecasting-module-reports-and-outputs.md new file mode 100644 index 0000000..990ed77 --- /dev/null +++ b/docs/user/12-forecasting-module-reports-and-outputs.md @@ -0,0 +1,69 @@ +--- +id: forecasting-module-reports-and-outputs +title: "Forecasting Module: Reports and Outputs" +sidebar_label: "Forecasting Module: Reports and Outputs" +sidebar_position: 12 +--- + +# Forecasting Module: Reports and Outputs + +After defining your methodologies and parameters, the final stage is to compare the available models, select the most accurate forecast, and review the resulting procurement requirements. + +## Compare and Select +**Navigation:** **Forecasting Tree** > **Compare and Select**. + +This screen allows you to compare multiple forecasts (Consumption-based vs. Tree-based) side-by-side to make your final selection. + +### Key Metrics for Selection +- **Forecast Error (%):** Uses the **WAPE** calculation. A green highlight indicates the model with the lowest historical error. +- **Compare to Consumption:** For tree forecasts, QAT flags if the output is significantly higher or lower than historical consumption trends. Red text indicates the variance exceeds your set thresholds. +- **Visual Audit:** Use the **Graph** to see how different forecasts trend against historical actuals. The bolded line represents your currently selected model. + +### Selection Rules +- **One Region at a Time:** Selection is performed per Planning Unit and Region. +- **Multiple Trees:** You can select and aggregate multiple tree forecasts (e.g., for different patient groups). +- **Mutual Exclusivity:** You cannot combine a consumption-based forecast with a tree-based forecast for the same region/unit. + +> [!TIP] +> Use the **Show Data** button below the graph to see monthly data in a tabular format. Purple italicized values denote the official forecast period. + +--- + +## Monthly Forecast +**Navigation:** **Forecasting Tree** > **Monthly Forecast**. + +Use this report to verify your final selected forecasts in aggregate. It is the primary tool for a final sanity check before finishing the quantification. + +- **Aggregation:** Automatically sums regional forecasts into a national total. +- **Equivalency Units (EUs):** View the forecast in EUs (e.g., "Standard Treatment Months") to compare different product variants. +- **Analysis Views:** Toggle between planning units and forecasting units, or aggregate data by calendar/fiscal year. + +--- + +## Forecast Summary +**Navigation:** **Forecasting Tree** > **Forecast Summary**. + +This screen provides two high-level views of your quantification results across the entire forecast period. + +### 1. Regional View +- Provides a spreadsheet-style overview of all planning units across all regions. +- You can directly update forecast methods or add justification notes in this table. + +### 2. National View (Gap Analysis) +This view provides a high-level procurement surplus/gap analysis based on your forecast and existing supply data. + +> [!WARNING] +> This is a high-level tool. For granular supply planning (shipment scheduling, shelf-life tracking), you should import this forecast into the **Supply Planning** module. + +#### Formulas & Logic +QAT uses the following logic to estimate procurement needs: + +1. **Projected Stock** = (Starting Stock + Existing Shipments) - Forecasted Quantity +2. **Desired Stock** = (Forecasted Quantity × Desired Months of Stock) / Months in Period +3. **Procurement Gap** = Projected Stock - Desired Stock + +#### Cost Estimation +If a gap exists, QAT estimates costs based on your defined unit prices and freight percentages: +- **Product Cost** = Procurement Gap × Unit Price +- **Freight Cost** = Product Cost × Freight % +- **Total Cost** = Product Cost + Freight Cost diff --git a/docs/user/13-annex-1-application-realm-administrator-manual.md b/docs/user/13-annex-1-application-realm-administrator-manual.md new file mode 100644 index 0000000..504f8b7 --- /dev/null +++ b/docs/user/13-annex-1-application-realm-administrator-manual.md @@ -0,0 +1,100 @@ +--- +id: annex-1-application-realm-administrator-manual +title: "Annex 1: Application & Realm Administrator Manual" +sidebar_label: "Annex 1: Application & Realm Administrator Manual" +sidebar_position: 13 +--- + +# Annex 1: Application & Realm Administrator Manual + +## Introduction +This annex provides guidance on administrative functionalities restricted to **Application Administrators** and **Realm Administrators**. +- **Application Masters**: Global settings affecting all realms (App Admin only). +- **Realm Level Masters**: Data specific to a realm, affecting its programs and supply plans (App and Realm Admins). +- **Program Level Masters**: Settings managed by Program Admins for specific programs. + +## Administrative Dashboards +Administrators see unique tiles on their dashboards to manage global and realm-level data. + +| Tile | Admin Level | Function | +| :--- | :--- | :--- | +| **Program User** | App & Realm | Manage user roles and permissions. | +| **Total Realms** | App | Create and configure application realms. | +| **Language** | App | Manage supported UI languages. | +| **Country** | Realm | Map global countries to specific realms. | +| **Technical Area** | Realm | Define program focus areas (e.g., HIV, Malaria). | +| **Organization** | Realm | Manage partner and government entities. | +| **Total Program** | Realm | Overview and bulk update of program info. | +| **Setup Program** | Realm | Primary wizard for onboarding new programs. | + +--- + +## Managing Master Data +QAT uses a three-tier hierarchy for data management. + +### 1. Application Masters (Global) +These settings apply application-wide across all realms. + +#### Translation Management +- **Database Translation**: Used for "Dynamic Labels" (drop-down list items). English is required; others are recommended. +- **Label Translation**: Used for "Static Labels" (table headers, menu items). Changes reflect immediately. + +#### Global Entities (CRUD) +The following entities follow a standard **List > Add (+) > Update** workflow: +- **Country**: Manage global country list. Note: Use 3-letter (e.g., AGO) and 2-letter (e.g., AO) ISO codes. +- **Currency**: Manage conversion rates. Use "Sync Online" to automatically update rates against the USD. +- **Language**: Enable/Disable UI languages (English, French, Spanish, Portuguese). +- **Dimension & Unit**: Define measurable values (Weight, Volume) and units (mL, gm, Box). +- **Usage Period**: Define time intervals (Month, Week) used in forecasting calculations. + +#### User Management & Roles +- **Users**: Add new users via email, assigning them a primary Role, Realm, and Language. +- **Roles**: Administrators can modify business rules associated with roles. + > [!NOTE] + > For a full permission breakdown, see [Annex 3: User Role Matrix](15-annex-3-user-role-matrix.md). + +--- + +### 2. Realm Masters (Business Logic) +Realm settings govern the specific products, funders, and procurement logic for a group of programs. + +#### Product Catalog +The product hierarchy is central to QAT operations: +1. **Forecasting Unit (FU)**: The base unit (e.g., 1 Tablet). +2. **Planning Unit (PU)**: The dispensing pack (e.g., Bottle of 30 tabs). + - *Mapping:* Many PUs can map to one FU. + - *Volumetrics:* Administrators must map volume/weight data to PUs for shipping calculations. +3. **Procurement Unit**: Item-level description including manufacturer-specific data (GTIN, SKU) and lead times. +4. **Planning Unit Category**: Broad groupings (e.g., "ARV Pharmaceuticals"). +5. **Tracer Category**: Specific clusters (e.g., "Adult First Line"). + +#### Equivalency Units (EU) +EUs allow disparate products to be aggregated for reporting (e.g., converting bottles and tubes into "Standard Treatment Months"). +- **Logic:** Realm-level mappings apply to all programs unless overridden by a program-specific mapping. + +#### Logistics & Partners +- **Procurement Agents**: Manage lead times, color codes, and catalog integration. +- **Funding Sources**: Define the entities paying for shipments. +- **Organizations**: Manage the specific bodies (MOH, NGO) running programs. +- **Forecast Methods**: Define the available methodologies (ARIMA, TES, etc.) for the realm. + +--- + +## Setting Up a New Program +Administrators initiate programs via the **Setup Program** wizard. + +### Workflow: +1. **Choose Realm & Country**: Assign the program to its clinical/geographic context. +2. **Define Technical Area**: Select one or more areas (e.g., HIV + TB). +3. **Select Organization & Regions**: Determine the managing body and geographic scope (National or sub-national). +4. **Configure Program Data**: + - **For Supply Planning**: Set Lead Times, Stock levels, and Planning Units. + - **For Forecasting**: Set Forecast Start/End dates and review periods. +5. **Submit**: The program is now available for Program Admins to manage. + +--- + +## Utility Tools +### Resetting the QPL +Administrators can bulk-reset the **QAT Problem List (QPL)** to reopen "Addressed" issues for a new review cycle. +- **Usage:** Typically done at the start of a new submission period for approved versions. diff --git a/docs/user/13-annex-4-business-functions.md b/docs/user/13-annex-4-business-functions.md deleted file mode 100644 index c5f643c..0000000 --- a/docs/user/13-annex-4-business-functions.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -id: annex-4-business-functions -title: "Annex 4: Business Functions" -sidebar_label: "Annex 4: Business Functions" -sidebar_position: 13 ---- - -# Annex 4: Business Functions - -> Business functions are a set of capabilities available to the user. They are used when creating roles (see **Roles (App Admin** **only)**). Each role has one or more business functions. -> -> For master level data, the verbs used in the business functions are as follows: - -- **List** – Allows user to see the table with the existing data for that master data element. If only “List X” is chosen, the user can only see “X” but cannot edit or add. - -- **Edit** – Allows user to update or edit the master data element. Note: Always include “list” along with “edit” or the user will not be able to see the screen to edit data elements. **(NOTE: An entity cannot be deleted. Users can only ‘Disable” entities.)** - -- **Add** – Allows user to add a new record for the master data element. Note: Always include “list” along with “add” or the user will not be able to see the screen to add data elements. - -- **Manage**: Allows user to perform all of the aforementioned functions - -The above business function can be provided to users in any combination. For example: - -- User A has only “List” access, so they can only view existing data (“read only”) - -- User B has only “List” + “Edit” access, so they can view and edit existing data, but cannot add ‘new’ entities. - -- User C has “List” + “Add” access, so they can add new entities and view the list of entities. - -- User D has “Add” + “Edit” + “List” (Manage) access that enables performing all 3 actions. - -| \# | Menu Option | Business Function | Business Function Description (“Allows enabled user/s to…”) | -| --- | ----------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | Translations | Label translations | Input/update the “static labels” for QAT enabled languages – which are reflected during new releases | -| 2 | | Database Translation | Input/update the “dynamic labels” for QAT-enabled languages - which are reflected immediately | -| 3 | | View Translations | View the translations, whether label or database | -| 4 | Application Masters | Application Dashboard | View the application dashboard | -| 5 | | View Application-level Masters | View the master CRUDs at Application level | -| 6 | | Manage Country | Setup and manage the country | -| 7 | | Manage Currency | Setup and manage the currency | -| 8 | | Manage Dimension | Setup and manage the dimension | -| 9 | | Manage Language | Manage the language setup and administration activities | -| 10 | | Manage Role | Manage the role creation and assignments | -| 11 | | Create Realm | Create new realms (this is restricted to Application Admin role) | -| 12 | | Edit Realm | Update/edit data related to an existing realm to which he/she has been provided access | -| 13 | | List Realm | view the list of realms to which he/she has been provided access | -| 14 | | Show Realm Select | View the list of Realms available at the Application level | -| 15 | | Manage Region | Setup and manage regions at country level | -| 16 | | Manage User | View, add, and update users, as well has assign specific access and roles | -| 17 | | Manage Unit | Setup and manage the units for the dimensions | -| 18 | | Upload User Manual | Upload new version of user manual | -| 19 | | Manage Usage Period | Add, edit, view usage periods. | -| 20 | Realm Masters | View Realm Level Masters | View all Master screens at Realm level | -| 21 | | Manage Realm Country | Manage the country | -| 22 | | List Data Sources | Manage data sources at realm level | -| 23 | | Manage Data Source | | -| 24 | | List Data Source Type | Manage data sources types at realm level | -| 25 | | Manage Data Source Type | | -| 26 | | List Funding Source | Manage funding source at realm level | -| 27 | | Manage Funding Source | | -| 28 | | Supplier | Manage manufacturers at the realm level | -| 29 | | Manage Supplier | | -| 30 | | Organization | Manage organizations at realm level | -| 31 | | Manage Organization | | -| 32 | | Organization Type | Manage organization types at realm level | -| 33 | | Map Procurement Agent | Assign procurement agents to a program. | -| 34 | | Add Procurement Agent | Add/remove/edit procurement agents at the program level | -| 35 | | Add Program Specific Prices | Add program specific prices for different procurement agents | -| 36 | | Manage Forecasting Unit | Manage product attributes as listed in the options | -| 37 | | List Forecasting Units | | -| 38 | | Manage Country Planning Unit | | -| 39 | | List Planning unit | | -| 40 | | Product Category | | -| 41 | | Manage Product Category | | -| 42 | | Manage Planning Unit Capacity | | -| 43 | | Procurement Unit List | | -| 44 | | Manage Procurement Unit | | -| 45 | | Tracer Category | | -| 46 | | Manage Tracer Category | | -| 47 | | Technical Area | Manage Technical area at Realm level | -| 48 | | Manage Technical Area | | -| 49 | | Manage Equivalency Unit | Add, edit, view equivalency units | -| 50 | Program Management | View Program Level Masters | View all program level masters | -| 51 | | Alternate Reporting Unit (ARU) List | Manage product attributes as listed in the options | -| 52 | | Set Up Program | Manage a program, including updating program-level parameters (program name, lead time, freight %, etc.) | -| 53 | | Edit Program | | -| 54 | | List Programs | | -| 55 | | Manage Planning Units | Manage Planning units, including updating parameters (AMC settings, inventory parameters, shelf life, etc.) | -| 56 | | List Budget | Manage budget at the program level | -| 57 | | Manage Budget | | -| 58 | | Delete Local Programs | Delete local programs | -| 59 | | Import Program | Import program | -| | | Export Program | Export Program | -| 60 | | Download Program | Download program data (user can download the program and also use the "Down arrow" icon on the top right-hand corner of the screen | -| 61 | | PipeLine Program Import | Import pipeline data into QAT application | -| 62 | | Upload a version | Upload a local version to the server | -| 63 | | Supply Plan Version and Review | List and review the supply plan version list | -| 64 | | Approve a Version | To approve a final supply plan (enables the user to also access the supply plan & review screen). The “Reviewed” check box function and “Resolved” status are also embedded in this Business Function | -| 65 | | Manage Integrations | Add or edit a program integration | -| 66 | | Notification Bcc approve | Receive email in BCC that supply plan was approved | -| 67 | | Notification Bcc upload | Receive email in BCC that supply plan was uploaded | -| 68 | | Notification Bcc reject | Receive email in BCC that supply plan was rejected | -| 69 | | Notification To upload | Receive email that supply plan was uploaded | -| 70 | | Version Settings | Update and view forecasting program version settings | -| 71 | Supply Plan Data | Shipment Delinking | Link, delink and update ERP shipment data | -| 72 | | Manual Tagging | | -| 73 | | View Program Data Tab | View Supply Plan Data tab | -| 74 | | Quantimed Import | Manage import of data from Quantimed | -| 75 | | QAT Forecast Import | Import forecast from QAT Forecasting module | -| 76 | Supply Planning | Supply plan | View and edit access to the ‘Supply Planning’ Screen | -| | | Scenario planning | Perform supply plan-based scenario planning | -| 77 | | Supply plan report | View a supply plan report | -| 78 | Forecasting | Forecasting Module | Access to the forecasting module | -| 79 | Tree Forecasting | Tree | Add, edit, view forecasting tree(s) | -| 80 | | Tree Templates | Add, edit, view tree templates | -| 81 | | Modeling Validation | View the Modeling Validation output | -| 82 | | Product Validation | View the Product Validation output | -| 83 | | Usage Template | Add, edit, view usage templates | -| 84 | Consumption Forecasting | Data Entry and Adjustment | Access to Data Entry and Adjustment screen | -| 85 | | Extrapolation | Access to Extrapolation screen | -| 86 | | Import from QAT supply plan | Import consumption data from supply planning module | -| 87 | Reports | View Reports | View all reports available | -| 88 | | QAT Problem List | View the QAT Problem list and add new problem entries | -| 89 | | Create Problem | Create & update a "problem" data in QAT Problem List | -| 90 | | Edit Problem | | -| 91 | | Program Catalog | View the program catalog report | -| 92 | | Stock Status Over Time | View of Stock Status data over time | -| 93 | | Stock Status Matrix | View the Stock Status matrix data | -| 94 | | Stock Status Snapshot | View a snapshot of the stock status data | -| 95 | | Stock Status Snapshot (Global) | View the global (across countries and programs) stock status data | -| 96 | | Consumption (Forecast vs Actual) | View a comparison of the consumption (forecast vs actuals) | -| 97 | | Consumption (Global) | View the global (across countries and programs) consumption data | -| 98 | | Forecast Error (Monthly) | View a monthly forecast error list | -| 99 | | Forecast Error (by Planning Unit) | View a planning unit based forecast error report | -| 100 | | Shipments (Global) | View the shipments at global (across countries and program) level | -| 101 | | Shipment Overview | View of all Shipments | -| 102 | | Shipment Details | View the Shipment details | -| 103 | | Shipment Cost Details | View the Shipment cost report | -| 104 | | Shipment Cost Overview | View of the Shipments costs | -| 105 | | Budget | View the budget | -| 106 | | Procurement Agent Lead Time | View the procurement agent lead times | -| 107 | | Expiries | View the expired inventory details | -| 108 | | Cost of Inventory | View cost of inventory report | -| 109 | | Inventory Turns | View the inventory turns | -| 110 | | Stock Adjustment | View the manual stock adjustment data | -| 111 | | Warehouse Capacity (by program) | View program-wide warehouse capacity | -| 112 | | Warehouse Capacity (by country) | View the country-wide warehouse capacity | -| 113 | | Compare and Select Forecast | View the compare and select forecast report | -| 114 | | Compare Version | View the compare version report | -| 115 | | Forecast Summary | View the forecast summary report | -| 116 | | Monthly Forecast | View the monthly forecast report | diff --git a/docs/user/14-annex-2-business-rules.md b/docs/user/14-annex-2-business-rules.md new file mode 100644 index 0000000..90299e2 --- /dev/null +++ b/docs/user/14-annex-2-business-rules.md @@ -0,0 +1,102 @@ +--- +id: annex-2-business-rules +title: "Annex 2: Business Rules" +sidebar_label: "Annex 2: Business Rules" +sidebar_position: 14 +--- + +# Annex 2: Business Rules + +This annex documents the core mathematical formulas and logical conditions that drive QAT's calculations, supply planning suggestions, and data quality checks. + +## Supply Planning Module + +### 1. Inventory Basics +- **Opening Balance**: `Opening Balance(t) = Ending Balance(t-1)`. (First month defaults to 0). +- **Expired Stock**: `Sum(Ending Balance of batches expiring in month t)`. +- **Total Shipments**: `Sum(Quantities where Receive Date is in month t)`. +- **Projected Inventory**: `Opening Balance + Total Shipments ± Total Adjustments - Final Consumption - Expired Stock`. + +### 2. Final Stock & Consumption +- **Final Stock**: Sum of stock reported across all regions. +- **Total Adjustments**: Sum of manual adjustments from regions that did *not* report a stock count. +- **Final Consumption**: + - *If all regions reported actuals:* `Sum(Actual Consumption)`. + - *If any region is missing actuals:* `MAX(Sum(Actual Consumption), Sum(Forecasted Consumption))`. + +### 3. Supply Plan Parameters +- **AMC (Average Monthly Consumption)**: `[Sum(Full Demand in Past Window) + Sum(Full Demand in Future Window)] / Total Months`. +- **Min MOS**: `MAX(Program Min MOS, Realm Min MOS Guardrail)`. +- **Max MOS**: `MIN(MAX(Min MOS + Reorder Interval, Realm Min Max Guardrail), Realm Max Max Guardrail)`. +- **Min Stock**: `AMC × Min MOS`. +- **Max Stock**: `AMC × Max MOS`. +- **Ending Balance**: + - If all regions reported stock: `Final Stock`. + - Otherwise: `Projected Inventory + Auto Adjustment`. + +### 4. Shipment Suggestions (Plan by MOS) +QAT suggests a shipment when `MOS` for the current month and the following two months are all less than `Min MOS`. +- **Suggested Quantity**: `Max Stock - Ending Balance + Unmet Demand`. + +--- + +## Batch Allocation Logic (FEFO/LEFO) + +### FEFO (First Expiry, First Out) +Used for consuming stock based on the earliest expiry dates. +1. Sort all batches by **Expiry Date** (asc). +2. Calculate **Unallocated Consumption** (Final Consumption - Adjustments). +3. Loop through batches: + - `Batch Ending Balance = MAX(0, Batch Temp Balance - Unallocated Consumption)`. + - Subtract consumed amount from the total `Unallocated Consumption` pool. + +### LEFO (Last Expiry, First Out) +Used primarily for distributing negative adjustments (losses). +1. Sort batches by **Expiry Date** (desc). +2. Deduct quantities from the newest batches first until the adjustment is fully allocated. + +--- + +## QAT Problem List (QPL) Logic + +### Data Quality +| Problem | Suggestion | Logic | +| :--- | :--- | :--- | +| **Missing Actuals** | Enter actual consumption. | Flagged if actuals are missing for 3+ consecutive months. | +| **Missing Inventory** | Enter stock count. | Flagged if no stock count is reported for 3+ consecutive months. | +| **Past Shipments** | Update receive date. | Flagged if a shipment's expected date is >14 days in the past. | + +### Supply Planning +| Problem | Suggestion | Logic | +| :--- | :--- | :--- | +| **Missing Forecast** | Extend forecast period. | Flagged if any of the next 18 months lack a forecast. | +| **Non-Dynamic Forecast** | Review seasonality. | Flagged (for ARV/Malaria) if 4+ consecutive months have identical values. | +| **Min/Max Violation** | Re-evaluate supply plan. | Flagged if MOS falls outside Min/Max parameters within 18 months. | + +--- + +## Forecasting Methodology + +### Statistical Adjustments +- **Stockout Rate**: `(Stockout Days / Days in Month) × 100`. +- **Adjusted Consumption**: `(Actual Consumption / Reporting Rate) / (1 - Stockout Rate)`. +- **Interpolation**: `y = y0 + (x - x0) * (y1 - y0) / (x1 - x0)`. (Straight-line between two known points). + +### Error Metrics +- **WAPE**: `Sum(ABS(Actual - Forecast)) / Sum(Actual)`. (Calculated over a 6-month window). +- **RMSE**: `SQRT(Sum((Forecast - Actual)²) / N)`. +- **R²**: `1 - (SSR / SST)`. Measures how closely the model tracks historical patterns (0 to 1). + +--- + +## Version Conflict Resolution +When uploading a local version, QAT compares: +- **Server (Old)**: The version originally downloaded. +- **Local**: Your edited version. +- **Server (Latest)**: Current version on the server (might have been updated by others). + +### Conflict States +- **Green (Local Latest)**: Data exists only in the local version or was modified locally only. +- **Blue (Server Latest)**: Data was modified only on the server since you downloaded it. +- **Yellow (Conflict)**: The *same* record was modified in both the local and server versions. You must choose which to keep. +- **Un-highlighted**: No changes detected across versions. diff --git a/docs/user/14-annex-5-pipeline-program-import.md b/docs/user/14-annex-5-pipeline-program-import.md deleted file mode 100644 index c33df70..0000000 --- a/docs/user/14-annex-5-pipeline-program-import.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -id: annex-5-pipeline-program-import -title: "Annex 5: PipeLine Program Import" -sidebar_label: "Annex 5: PipeLine Program Import" -sidebar_position: 14 ---- - -# Annex 5: PipeLine Program Import - -In certain cases, users will be granted a special set of credentials that can import PipeLine databases if they desire to set up their program this way (see [Setting up a new program](10-annex-1-application-realm-administrator-manual.md#setting-up-a-new-program) in Annex 1). - -**Step 1: Convert the .accdb file into a JSON file:** - -_About the PipeLine Access DB to JSON conversion tool:_ Since the QAT system is only able to import program data in JSON format and PipeLine databases are in .accdb format, QAT has a downloadable tool for converting the .accdb file into a JSON file, thus allowing importation into QAT. Once installed, this tool does not require internet access to run. Also, this tool allows the user to choose their preferred language. - -1. Confirm that you have the appropriate System Configuration Requirements: - - - -- Operating System: _Windows / Linux / Ubuntu_ - -- Other Software : _Java JDK 1.8 and above._ - - - -2. Confirm that your PipeLine data is fully updated - - - -- The database cannot have negative inventory values. - -- All the shipment, stock, consumption data must be updated. - - - -3. Go to “Program Management” and click on “PipeLine Program Import”. - -4. On the top right corner click on the “Add” button. It will lead to a file input screen. - -5. Click on the downward arrow button on the top right corner. - -6. Click the “Download PipeLine Converter” will on the screen, then select your computer’s operating system (Windows or Linux). The converter will be downloaded in zip file. - -7. Open the converter file and run the tool (.exe file / .java executable file), the following screen will be displayed: - -![P7343#yIS1](/img/media/image406.png) - -Figure 251: Caution Message during PipeLine Import - -![P7345#yIS1](/img/media/image407.jpg) - -Figure 252: PipeLine Import Screen - -8. Click on first Browse button to search for the desired .accdb file to import. - -![P7349#yIS1](/img/media/image408.png) - -> Figure 253: PipeLine Import Screen – Browse - -9. Click the second Browse button to select the location where the converted file will be stored on the user’s local machine. - -10. Click on Convert. When the file is converted into. json format, you will receive the notification below: - -![P7353#yIS1](/img/media/image409.jpg) - -Figure 254: Successful Import PipeLine Screen - -**Step 2: Upload the JSON file into QAT:** - -11. In QAT go to “Program Management” \> “PipeLine Program Import” menu item. - -12. Click on the “Add” button, and a new screen will be opened. Browse to find the converted JSON file (from Step 1) from the local machine. Click on “Submit”. - -13. After completing the process, the user will get a message that the program is successfully imported. - -14. This program will be shown as a row in the program list. Click on that row to continue to Step 3. - -**Note:** While doing the program setup the QAT user can select multiple technical areas from the technical area dropdown list. - -![P7363#yIS1](/img/media/image410.png) - -Figure 255 Pipeline program import, multiple technical areas - -**Step 3: Configure data for import into QAT** - -After importing PipeLine data, the user will navigate through a series of screens where there will be prompts to enter data. After editing data on one screen, the user should click “Next” to move to the following data entry screen. If needed, navigate to previous screens by clicking “Back”. The user should navigate through the following screens: Program Info, Planning Units, Data Source, Funding Source, Procurement Agent, Consumption, Inventory, and Shipments. - -![P7369#yIS1](/img/media/image411.jpg) - -Figure 256: PipeLine Import - Country - -Each of these major screens have sub-screens where users need to enter data and map current PipeLine data to QAT realm-level master data; for example, the PipeLine products need to be mapped to QAT’s planning units. At the last step (Shipment screen) a pop-up will be displayed if any program contains negative inventory. - -![P7374#yIS1](/img/media/image412.jpg) - -Figure 257: PipeLine Import - Planning Units - -After the file is successfully imported to QAT: - -1. The users can go to “Program Management”. - -2. Click on the “Programs” menu item. - -3. The program list will show the imported program. - -4. Now the user can “Download”, “Import” and “Export” that program. - - diff --git a/docs/user/15-acronyms.md b/docs/user/15-acronyms.md deleted file mode 100644 index 94ef22e..0000000 --- a/docs/user/15-acronyms.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: acronyms -title: Acronyms & Definitions -sidebar_label: Acronyms -sidebar_position: 15 ---- - -This page provides definitions for commonly used acronyms and terms in the QAT documentation. - - -## General - -| Acronym | Definition | -|---------|------------| -| ARTMIS | Automated Requisition Tracking Management Information System | -| ERP | Enterprise Resource Planning | -| FASP | Forecasting and Supply Planning | -| FC | Forecast | -| GFPVAN | Global Family Planning Visibility and Analytics Network | -| GHSC-PSM | Global Health Supply Chain Program - Procurement and Supply Management | -| PWA | Progressive Web Application | -| QAT | Quantification Analytics Tool | -| SP | Supply Plan | -| USAID | United States Agency for International Development | - - -## Technical - -| Acronym | Definition | -|---------|------------| -| API | Application Programming Interface | -| ERD | Entity Relationship Diagram | -| CDN | Content Delivery Network | -| CSV | Comma Separated Values | -| JWT | JSON Web Token | -| IAM | Identity and Access Management | -| PWA | Progressive Web Application | -| PDF | Portable Document Format | -| R | R Programming Language | -| RDS | Relational Database Service | -| VPC | Virtual Private Cloud | diff --git a/docs/user/15-annex-3-user-role-matrix.md b/docs/user/15-annex-3-user-role-matrix.md new file mode 100644 index 0000000..b722a69 --- /dev/null +++ b/docs/user/15-annex-3-user-role-matrix.md @@ -0,0 +1,83 @@ +--- +id: annex-3-user-role-matrix +title: "Annex 3: User Role Matrix" +sidebar_label: "Annex 3: User Role Matrix" +sidebar_position: 15 +--- + +# Annex 3: User Role Matrix + +This matrix defines the permissions for every role within QAT. Permissions are categorized by functional area. + +## Role Descriptions + +| Role | Description | +| :--- | :--- | +| **Application Admin** | Global system configuration, label translations, and role creation. | +| **Realm Admin** | Manages realm-specific master data (Products, Technical Areas, Orgs). | +| **SP Program Admin** | Manages program-level settings (Lead times, Planning Units, Budgets). | +| **SP Reviewer** | Reviews and approves supply plan versions. | +| **SP Program User** | Primary data entry and supply planning role. | +| **SP Viewer** | View-only access to reports, raw data, or review status. | +| **Forecast Admin** | Manages forecast-specific parameters and templates. | +| **Forecast User** | Builds forecasts and enters consumption data. | +| **Forecast Viewer** | View-only access to forecast outputs and trees. | + +--- + +## 1. Administrative & Master Data +| Business Function | App Admin | Realm Admin | Program Admin | Users | Viewers | +| :--- | :---: | :---: | :---: | :---: | :---: | +| Label & DB Translations | **X** | - | - | - | - | +| Manage Global Countries/Users | **X** | - | - | - | - | +| Manage Realm Masters (PU/FU/Org) | - | **X** | V | V | V | +| Manage Realm Countries/Regions | - | **X** | - | - | V | +| Manage Procurement Agents | - | **X** | **X** | V | V | + +**Legend:** **X** = Full Access | **V** = View Only | **-** = No Access + +--- + +## 2. Program Management +| Business Function | Realm Admin | SP Admin | FC Admin | Users | +| :--- | :---: | :---: | :---: | :---: | +| Setup/Create New Program | **X** | - | **X** | - | +| Update Program Info & Settings | **X** | **X** | **X** | - | +| Manage Program Planning Units | **X** | **X** | **X** | - | +| Budget Management | **X** | **X** | - | V | +| Import/Export Programs | **X** | **X** | **X** | **X** | + +--- + +## 3. Supply Plan Operations +| Business Function | Realm Admin | SP Admin | SP User | SP Reviewer | SP Viewer | +| :--- | :---: | :---: | :---: | :---: | :---: | +| Data Entry (Cons./Inv./Ship.) | **X** | **X** | **X** | - | V¹ | +| Manage Supply Plan/Scenarios | **X** | **X** | **X** | **X** | V² | +| Upload Versions | **X** | **X** | **X** | - | - | +| Review/Approve Versions | - | - | - | **X** | - | +| ERP Shipment Linking | **X** | **X** | **X** | - | - | + +*¹ SP Viewer - Data only | ² SP Viewer - Data/Review* + +--- + +## 4. Forecasting Operations +| Business Function | Realm Admin | FC Admin | FC User | FC Viewer | +| :--- | :---: | :---: | :---: | :---: | +| Consumption Data Entry | **X** | **X** | **X** | V | +| Manage/Build Trees | **X** | **X** | **X** | V | +| Extrapolation | **X** | **X** | **X** | V | +| Usage/Tree Templates | **X** | **X** | **X** | V | +| Import from Supply Plan | **X** | **X** | **X** | - | + +--- + +## 5. Reports Access +| Report Type | Admins | Users | Viewers | +| :--- | :---: | :---: | :---: | +| Supply Plan / Stock Status | **X** | **X** | **X** | +| Consumption / Forecast Error | **X** | **X** | **X** | +| Shipment / Cost Reports | **X** | **X** | **X** | +| Inventory Turns / Expiries | **X** | **X** | **X** | +| Warehouse Capacity | **X** | **X** | **X** | diff --git a/docs/user/16-annex-4-business-functions.md b/docs/user/16-annex-4-business-functions.md new file mode 100644 index 0000000..7d5a0c9 --- /dev/null +++ b/docs/user/16-annex-4-business-functions.md @@ -0,0 +1,69 @@ +--- +id: annex-4-business-functions +title: "Annex 4: Business Functions" +sidebar_label: "Annex 4: Business Functions" +sidebar_position: 16 +--- + +# Annex 4: Business Functions + +Business functions are granular capabilities assigned to roles. They define exactly what actions a user can perform within the system. + +## Permission Verbs +When configuring roles, the following verbs determine the level of access: +- **List**: Allows viewing the data table only; no additions or edits. +- **Add**: Allows creating new records. +- **Edit**: Allows updating existing records. (Note: Entities cannot be deleted, only disabled). +- **Manage**: A shortcut for List + Add + Edit. + +--- + +## 1. Translations & Admin Dashboards +| Category | Business Function | Description | +| :--- | :--- | :--- | +| **Translations** | Label Translations | Update "Static Labels" (UI headers) across languages. | +| | Database Translations | Update "Dynamic Labels" (drop-down items) immediately. | +| | View Translations | Read-only access to all UI strings. | +| **Dashboards** | Application Dashboard | Access the global administrator overview. | +| | Realm Dashboard | Access the realm-specific administrator overview. | +| | Program Dashboard | Access the operational dashboard for specific programs. | + +--- + +## 2. Master Data Management +| Category | Business Function | Description | +| :--- | :--- | :--- | +| **App Masters** | Manage Country/Currency | Global configuration of geographic and monetary units. | +| | Manage User/Role | Create users and define their functional permissions. | +| | Create/Edit Realm | Global setup of administrative realms. | +| **Realm Masters** | Manage Realm Country/Region | Map global countries to specific realm territories. | +| | Manage Funding Source | Define entities providing financial support for shipments. | +| | Manage Organization | Manage partner and government bodies within the realm. | +| | Manage Products | Full control over Forecasting, Planning, and Procurement Units. | +| | Equivalency Units | Define aggregation logic for related products. | + +--- + +## 3. Program & Supply Chain Operations +| Category | Business Function | Description | +| :--- | :--- | :--- | +| **Programs** | Setup Program | Create and configure new Supply Planning or Forecast programs. | +| | Manage Planning Units | Configure program-specific lead times and stock levels. | +| | Manage Budget | Track and allocate financial resources at the program level. | +| **Version Control** | Upload Version | Sync local program edits to the central server. | +| | Review/Approve | Formally audit and finalize supply plan submissions. | +| | Notification Rules | Configure email triggers for upload/approval/rejection events. | +| **Shipments** | ERP Linking | Link QAT shipments to external procurement systems. | +| | Manual Tagging | Categorize shipments for advanced tracking. | + +--- + +## 4. Forecasting & Reporting +| Category | Business Function | Description | +| :--- | :--- | :--- | +| **Methodologies** | Tree Forecasting | Build and manage tiered demand models (Aggregation/Percentage/Number). | +| | Consumption Forecast | Access data entry, adjustment, and extrapolation screens. | +| | Templates | Manage Usage and Tree templates for rapid setup. | +| **Reports** | View Reports | Access the full suite of analytical outputs. | +| | QAT Problem List | Access and manage data quality and planning issues. | +| | Global Reports | View aggregated data across all countries and programs. | diff --git a/docs/user/17-annex-5-pipeline-program-import.md b/docs/user/17-annex-5-pipeline-program-import.md new file mode 100644 index 0000000..d579406 --- /dev/null +++ b/docs/user/17-annex-5-pipeline-program-import.md @@ -0,0 +1,55 @@ +--- +id: annex-5-pipeline-program-import +title: "Annex 5: PipeLine Program Import" +sidebar_label: "Annex 5: PipeLine Program Import" +sidebar_position: 17 +--- + +# Annex 5: PipeLine Program Import + +This annex details the process for migrating legacy **PipeLine** databases into QAT. This is a three-stage process: conversion, upload, and data mapping. + +> [!IMPORTANT] +> **Prerequisites:** +> - **Software:** Java JDK 1.8 or higher must be installed on your machine. +> - **Data Quality:** Your PipeLine database (.accdb) must not contain negative inventory values. Ensure all shipment, stock, and consumption data is finalized before starting. + +--- + +## Step 1: Convert .accdb to JSON +QAT requires data in JSON format. Use the **PipeLine Converter Tool** for this conversion. + +1. Navigate to **Program Management > PipeLine Program Import**. +2. Click the **Add (+)** button, then click the **Download (↓)** icon in the top right. +3. Select your OS (Windows or Linux) and download the `.zip` file. +4. Extract and run the converter (executable or `.jar` file). +5. **In the Converter:** + - **Source:** Browse and select your `.accdb` file. + - **Destination:** Select the folder where the resulting `.json` file should be saved. + - Click **Convert**. A notification will appear upon success. + +--- + +## Step 2: Upload to QAT +Once you have the `.json` file, you must upload it to the QAT server. + +1. In QAT, return to **Program Management > PipeLine Program Import**. +2. Click **Add (+)**. +3. Browse and select your converted `.json` file. +4. Click **Submit**. You will receive a success message, and the new program will appear in the import list. + +--- + +## Step 3: Data Mapping Wizard +The final stage involves mapping legacy PipeLine fields to QAT's realm-level master data. + +Click on your imported program row to launch the **Mapping Wizard**. You will navigate through the following screens: +1. **Program Info**: Map Technical Areas and Organizations. +2. **Planning Units**: Link PipeLine products to QAT Planning Units. +3. **Data & Funding Sources**: Map logistics and financial partners. +4. **Shipments & Inventory**: Final review of imported records. + +> [!TIP] +> Use the **Next** and **Back** buttons to navigate. If the system detects negative inventory during the final step, a warning will appear; you must resolve these discrepancies in the source data or during mapping. + +Once completed, the program will be fully active in **Program Management > Update Program Info**, where it can be downloaded for active supply planning. diff --git a/docs/user/18-acronyms.md b/docs/user/18-acronyms.md new file mode 100644 index 0000000..cdb826b --- /dev/null +++ b/docs/user/18-acronyms.md @@ -0,0 +1,59 @@ +--- +id: acronyms +title: Acronyms & Definitions +sidebar_label: Acronyms +sidebar_position: 18 +--- + +# Acronyms & Definitions + +This page provides definitions for commonly used acronyms and terms within the QAT application and documentation. + +## Supply Chain & Logistics + +| Acronym | Definition | +| :--- | :--- | +| **AMC** | Average Monthly Consumption | +| **ARU** | Alternate Reporting Unit | +| **FASP** | Forecasting and Supply Planning | +| **FEFO** | First Expiry, First Out | +| **FU** | Forecasting Unit | +| **IT** | Inventory Turns | +| **LEFO** | Last Expiry, First Out | +| **LMIS** | Logistics Management Information System | +| **MOS** | Months of Stock | +| **PU** | Planning Unit | +| **SDP** | Service Delivery Point | +| **WAPE** | Weighted Absolute Percentage Error | + +## QAT Application Terms + +| Acronym | Definition | +| :--- | :--- | +| **FC** | Forecast / Forecasting Module | +| **QAT** | Quantification Analytics Tool | +| **QPL** | QAT Problem List | +| **SP** | Supply Plan / Supply Planning Module | +| **TRA** | Technical Area | + +## Organizations & Systems + +| Acronym | Definition | +| :--- | :--- | +| **ARTMIS** | Automated Requisition Tracking Management Information System | +| **ERP** | Enterprise Resource Planning | +| **GFPVAN** | Global Family Planning Visibility and Analytics Network | +| **GHSC-PSM** | Global Health Supply Chain Program - Procurement and Supply Management | +| **USAID** | United States Agency for International Development | + +## Technical Terms + +| Acronym | Definition | +| :--- | :--- | +| **API** | Application Programming Interface | +| **CSV** | Comma Separated Values | +| **JSON** | JavaScript Object Notation | +| **JWT** | JSON Web Token | +| **PWA** | Progressive Web Application | +| **RMSE** | Root Mean Square Error | +| **WAPE** | Weighted Absolute Percentage Error | diff --git a/src/css/custom.css b/src/css/custom.css index be4820f..1ea3c00 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,14 +1,17 @@ +@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&display=swap'); + /** * Any CSS included here will be global. The classic template * bundles Infima by default. Infima is a CSS framework designed to * work well for content-centric websites. */ -/* You can override the default Infima variables here. -See: https://docusaurus.community/knowledge/design/css/variables/ -*/ :root { - /* Primary color palette */ + /* Modern Typography */ + --ifm-font-family-base: 'Poppins', sans-serif; + --ifm-heading-font-family: 'Poppins', sans-serif; + + /* Refined Primary color palette */ --ifm-color-primary: #002F6C; --ifm-color-primary-dark: #002a61; --ifm-color-primary-darker: #002557; @@ -17,17 +20,16 @@ See: https://docusaurus.community/knowledge/design/css/variables/ --ifm-color-primary-lighter: #003981; --ifm-color-primary-lightest: #003e8b; - /* Custom red color palette */ + /* Premium Accent */ --custom-accent: #BA0C2F; - --custom-accent-dark: #a70b2a; - --custom-accent-darker: #950a26; - --custom-accent-darkest: #840922; - --custom-accent-light: #cd0d34; - --custom-accent-lighter: #df0e38; - --custom-accent-lightest: #f20f3d; - - /* Colour overrides */ - --ifm-code-font-size: 95%; + --premium-shadow: 0 4px 12px rgba(0, 0, 0, 0.08); + --glass-bg: rgba(255, 255, 255, 0.85); + --glass-border: rgba(255, 255, 255, 0.2); + + /* Infima Overrides */ + --ifm-code-font-size: 90%; + --ifm-navbar-background-color: var(--glass-bg); + --ifm-footer-background-color: #f8fafc; --ifm-menu-color-active: var(--custom-accent); --ifm-menu-color-background-active: transparent; --ifm-breadcrumb-color-active: var(--custom-accent); @@ -39,52 +41,58 @@ See: https://docusaurus.community/knowledge/design/css/variables/ } [data-theme='dark'] { - --ifm-color-primary: #A6C5EC; - --ifm-color-primary-dark: #8bb3e6; - --ifm-color-primary-darker: #70a1e0; - --ifm-color-primary-darkest: #558fda; - --ifm-color-primary-light: #c1d7f2; - --ifm-color-primary-lighter: #dce9f8; - --ifm-color-primary-lightest: #f7fbff; - - --custom-accent: #ff1744; - --custom-accent-dark: #f01440; - --custom-accent-darker: #e31236; - --custom-accent-darkest: #d61134; - --custom-accent-light: #ff4569; - --custom-accent-lighter: #ff6b88; - --custom-accent-lightest: #ff97ab; - - --docusaurus-highlighted-code-line-bg: rgba(0, 47, 108, 0.3); -} - -/* add underline to all links and remove from navbar, sidebar and footer */ + --ifm-color-primary: #8bb3e6; + --glass-bg: rgba(15, 23, 42, 0.85); + --glass-border: rgba(255, 255, 255, 0.1); + --premium-shadow: 0 4px 12px rgba(0, 0, 0, 0.4); + --ifm-footer-background-color: #0f172a; +} + +/* Glassmorphism for Navbar and Sidebar */ +.navbar { + backdrop-filter: blur(12px); + -webkit-backdrop-filter: blur(12px); + border-bottom: 1px solid var(--glass-border); + box-shadow: var(--premium-shadow); +} + +.theme-doc-sidebar-container { + border-right: 1px solid var(--glass-border); +} + +/* Modern Link Hover States */ a { + transition: all 0.2s ease; text-decoration: underline; } + .navbar__inner a, .table-of-contents a, a.menu__link, a.footer__link-item, a.button { text-decoration: none; } -/* custom styles for the left sidebar */ -.menu__link--active:not(.menu__link--sublist) { - border-left: 0.25rem solid var(--custom-accent); +.menu__link { + border-radius: 8px; + margin: 2px 0; + padding: 8px 12px; } -.menu__list-item .menu__list-item-collapsible a { - text-transform: capitalize; + +.menu__link--active:not(.menu__link--sublist) { + background: linear-gradient(90deg, rgba(186, 12, 47, 0.1) 0%, transparent 100%); + border-left: 4px solid var(--custom-accent) !important; + font-weight: 600; } -/* custom styles for the top navbar - add an bottom border to the active link */ -.navbar__link--active{ - border-bottom: 0.25rem solid var(--ifm-color-primary); +/* Premium Admonitions (Callouts) */ +.admonition { + border-radius: 12px; + border-left-width: 6px; + box-shadow: var(--premium-shadow); + padding: 1.25rem; } -/* custom styles for HRs */ -.section-divider { - margin: 3rem auto; - width: 100%; - border: none; - border-bottom: .5rem solid #BA0C2F; +.admonition-icon svg { + width: 20px; + height: 20px; } .section-divider-footer { margin: 3rem auto; diff --git a/src/pages/index.js b/src/pages/index.js index 3694314..4db25f4 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -9,25 +9,33 @@ import styles from './index.module.css'; function HomepageHeader() { const {siteConfig} = useDocusaurusContext(); return ( -
+
- + Quantification Analytics Tool -

- QAT Documentation Platform +

+ Modern Country-Led Forecasting & Supply Planning

-

- The Quantification Analytics Tool (QAT), is a modernized solution for - country-led forecasting and supply planning. Funded by USAID, QAT - leverages new technologies and enhances the existing tools such as, - PipeLine and Quantimed. With an enhanced user interface and - usability, greater analytical capabilities and automated data - exchange, this new tool enables program managers to easily build - multiple forecasts for comparison and selection, optimize commodity - procurement and delivery schedules, monitor the stock status of - products and share data with external platforms and key stakeholders. +

+

+ Funded by USAID, QAT enables program managers to easily build + multiple forecasts, optimize commodity procurement, and monitor + stock status with advanced analytical capabilities and automated data exchange.

+
+ + Get Started + + + Architecture + +
+
); @@ -37,100 +45,49 @@ function ResourceColumns() { const resources = [ { image: "img/home/QAT Overview Cover.png", - heading: "Overview", - text: <> -

Download this overview to learn how QAT enhances supply planning through its improved - interface, advanced analytics, and automated data exchange.

This two-page document - highlights key features that help program managers optimize procurement, monitor - stock levels, and share data efficiently with stakeholders.

- , + heading: "Overview Guide", + description: "Learn how QAT enhances supply planning through advanced analytics and automated data exchange.", link: "https://www.ghsupplychain.org/sites/default/files/2023-02/QAT_Overview_External.pdf" }, { image: "img/home/QAT User Manual Cover Image.png", heading: "User Manual", - text: <> -

Download the QAT User Manual to learn how to use this supply planning tool.

-

The manual covers: -

    -
  1. Essential background and development information
    2. -
  2. Step-by-step guidance for both online and offline functionality
    3. -
  3. Advanced features including scenario planning and updated planning logic
    4. -
  4. Best practices for master data management and program standardization
    5. -
  5. Instructions for monitoring stock status, optimizing procurement, and sharing data
    6. -

- , + description: "Complete guide for online/offline functionality, scenario planning, and best practices.", link: "https://www.ghsupplychain.org/sites/default/files/2025-01/QAT%20User%20Manual_2024.12.31.pdf" }, { image: "img/home/QAT Reports Reference Sheet Image.png", - heading: "Reports Reference Sheet", - text: <> -

Download the QAT Reports Reference Sheet to learn about the reports available in QAT, - which cover Stock Status, Consumption, Shipment, and Inventory.

The reference sheet - provides visual examples and brief descriptions of each report, including the - Program Catalog and Supply Plan Report. This guide helps users quickly identify - the most appropriate reports for their specific data analysis needs.

- , + heading: "Reports Reference", + description: "Visual guide to Stock Status, Consumption, and Inventory reports available in QAT.", link: "https://www.ghsupplychain.org/sites/default/files/2023-11/Reports%20Reference%20Sheet.pdf" } ]; return ( -
-
- {resources.map((resource, index) => ( -
- - {resource.heading} - - - {resource.heading} - - - Download - -
- {resource.text} +
+
+
+ {resources.map((props, idx) => ( +
+
+
+ {props.heading} +
+
+ {props.heading} +

{props.description}

+ + Download PDF + +
+
-
- ))} + ))} +
-
+ ); } diff --git a/src/pages/index.module.css b/src/pages/index.module.css index 815450a..605661b 100644 --- a/src/pages/index.module.css +++ b/src/pages/index.module.css @@ -1,27 +1,122 @@ -/** - * CSS files with the .module.css suffix will be treated as CSS modules - * and scoped locally. - */ - - .heroBanner { - padding: 4rem 0; +/* Premium UI Styles */ +.heroBanner { + padding: 6rem 0; + background: linear-gradient(135deg, #002F6C 0%, #001A3D 100%); + color: white; text-align: center; position: relative; overflow: hidden; } -@media screen and (max-width: 996px) { - .heroBanner { - padding: 2rem; - } +.heroTitle { + font-family: 'Outfit', sans-serif; + font-size: 4rem; + font-weight: 700; + margin-bottom: 1rem; + background: linear-gradient(to right, #fff, #A6C5EC); + -webkit-background-clip: text; + background-clip: text; + -webkit-text-fill-color: transparent; +} + +.heroSubtitle { + font-size: 1.5rem; + opacity: 0.9; + margin-bottom: 2rem; +} + +.heroDescriptionContainer { + max-width: 800px; + margin: 0 auto; +} + +.heroDescription { + font-size: 1.1rem; + line-height: 1.6; + margin-bottom: 3rem; + opacity: 0.8; +} + +.heroButtons { + display: flex; + gap: 1rem; + justify-content: center; +} + +.features { + padding: 4rem 0; + background: #f8fafc; +} + +.premiumCard { + background: white; + border-radius: 16px; + overflow: hidden; + box-shadow: 0 4px 20px rgba(0, 0, 0, 0.05); + transition: transform 0.3s ease, box-shadow 0.3s ease; + height: 100%; + display: flex; + flex-direction: column; + border: 1px solid rgba(0, 0, 0, 0.05); +} + +.premiumCard:hover { + transform: translateY(-8px); + box-shadow: 0 12px 30px rgba(0, 0, 0, 0.1); } -.buttons { +.cardHeader { + height: 200px; + background: #f1f5f9; display: flex; align-items: center; justify-content: center; + padding: 1rem; +} + +.cardImage { + max-height: 100%; + width: auto; + filter: drop-shadow(0 4px 8px rgba(0, 0, 0, 0.1)); +} + +.cardBody { + padding: 2rem; + flex-grow: 1; + display: flex; + flex-direction: column; +} + +.cardBody h3 { + font-family: 'Outfit', sans-serif; + margin-bottom: 1rem; + color: #002F6C; +} + +.cardBody p { + font-size: 0.95rem; + color: #64748b; + margin-bottom: 2rem; + line-height: 1.5; +} + +[data-theme='dark'] .features { + background: #0f172a; +} + +[data-theme='dark'] .premiumCard { + background: #1e293b; + border-color: rgba(255, 255, 255, 0.05); +} + +[data-theme='dark'] .cardHeader { + background: #334155; +} + +[data-theme='dark'] .cardBody h3 { + color: #A6C5EC; } -.dropShadow { - box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1), 0 6px 20px rgba(0, 0, 0, 0.08); +[data-theme='dark'] .cardBody p { + color: #94a3b8; } \ No newline at end of file From 74a5159107b2c7e5c4786d35398267fe4b704d23 Mon Sep 17 00:00:00 2001 From: Juhi Date: Wed, 25 Mar 2026 10:50:55 +0530 Subject: [PATCH 2/3] reverted UI changes and restored developer documentation while keeping user documentation restructuring --- docs/developer/01_purpose.md | 11 + docs/developer/02_intro.md | 47 +++ docs/developer/03_getting-started.md | 35 +++ .../04_Architecture/data-dictionary.md | 12 + docs/developer/04_Architecture/intro.md | 40 +++ .../04_Architecture/system-hierarchy.md | 20 ++ docs/developer/04_Architecture/tech-stack.md | 1 - .../05_Database/consumption-forecast.md | 16 + .../05_Database/dataset-masterdata.md | 16 + docs/developer/05_Database/intro.md | 37 +++ .../05_Database/qat-db-application-masters.md | 16 + .../qat-db-inventory-shipment-consumption.md | 16 + .../qat-db-product-related-tables.md | 16 + .../05_Database/qat-db-realm-masters.md | 16 + .../05_Database/qat-db-user-roles-acl.md | 16 + docs/developer/05_Database/tree-forecast.md | 16 + docs/developer/05_Database/tree-template.md | 16 + .../06_Integrations/erp-shipment-linking.md | 131 +++++---- docs/developer/06_Integrations/intro.md | 41 +++ .../06_Integrations/qat-catalog-updates.md | 136 +++++++++ .../06_Integrations/qat-interfaces.md | 91 ++++++ .../qat-supply-plan-sharing.md | 14 + docs/developer/07_Installation/01_overview.md | 20 ++ docs/developer/07_Installation/02_fasp-api.md | 233 +++++++++++++++ .../07_Installation/03_fasp-core-ui.md | 62 ++++ .../04_standard-installation.md | 125 ++++++++ .../07_Installation/05_server-setup.md | 248 ++++++++++++++++ .../07_Installation/06_rollback-procedure.md | 22 +- .../08_Guides/automated-test-backend.bkp | 169 +++++++++++ .../08_Guides/automated-test-frontend.bkp | 275 ++++++++++++++++++ .../developer/08_Guides/country-dashboards.md | 14 + docs/developer/08_Guides/flyway.bkp | 87 ++++++ docs/developer/08_Guides/intro.md | 10 + docs/developer/08_Guides/r-reports.md | 41 +++ src/css/custom.css | 104 +++---- src/pages/index.js | 141 +++++---- src/pages/index.module.css | 123 +------- 37 files changed, 2140 insertions(+), 294 deletions(-) create mode 100644 docs/developer/01_purpose.md create mode 100644 docs/developer/02_intro.md create mode 100644 docs/developer/03_getting-started.md create mode 100644 docs/developer/04_Architecture/data-dictionary.md create mode 100644 docs/developer/04_Architecture/intro.md create mode 100644 docs/developer/04_Architecture/system-hierarchy.md create mode 100644 docs/developer/05_Database/consumption-forecast.md create mode 100644 docs/developer/05_Database/dataset-masterdata.md create mode 100644 docs/developer/05_Database/intro.md create mode 100644 docs/developer/05_Database/qat-db-application-masters.md create mode 100644 docs/developer/05_Database/qat-db-inventory-shipment-consumption.md create mode 100644 docs/developer/05_Database/qat-db-product-related-tables.md create mode 100644 docs/developer/05_Database/qat-db-realm-masters.md create mode 100644 docs/developer/05_Database/qat-db-user-roles-acl.md create mode 100644 docs/developer/05_Database/tree-forecast.md create mode 100644 docs/developer/05_Database/tree-template.md create mode 100644 docs/developer/06_Integrations/intro.md create mode 100644 docs/developer/06_Integrations/qat-catalog-updates.md create mode 100644 docs/developer/06_Integrations/qat-interfaces.md create mode 100644 docs/developer/06_Integrations/qat-supply-plan-sharing.md create mode 100644 docs/developer/07_Installation/01_overview.md create mode 100644 docs/developer/07_Installation/02_fasp-api.md create mode 100644 docs/developer/07_Installation/03_fasp-core-ui.md create mode 100644 docs/developer/07_Installation/04_standard-installation.md create mode 100644 docs/developer/07_Installation/05_server-setup.md create mode 100644 docs/developer/08_Guides/automated-test-backend.bkp create mode 100644 docs/developer/08_Guides/automated-test-frontend.bkp create mode 100644 docs/developer/08_Guides/country-dashboards.md create mode 100644 docs/developer/08_Guides/flyway.bkp create mode 100644 docs/developer/08_Guides/intro.md create mode 100644 docs/developer/08_Guides/r-reports.md diff --git a/docs/developer/01_purpose.md b/docs/developer/01_purpose.md new file mode 100644 index 0000000..1ebb0f6 --- /dev/null +++ b/docs/developer/01_purpose.md @@ -0,0 +1,11 @@ +--- +id: 01_purpose +title: Purpose of Document +sidebar_label: Purpose of Document +sidebar_position: 1 +--- + +# Purpose of Document + +This document seeks to provide technical overview details of the Quantification Analytics Tool (QAT) Server and provide a guide to any IT professionals wishing to further understand the back end of QAT, including the software tools used, high-level design architecture, data interfaces/integration, and server-side details on configuration and management. For example, developers who are expected to take over and do code maintenance on the system over its life span. This does not include the application and realm admin functions that are available on the front end of the software, as those are covered in the QAT user guide. + diff --git a/docs/developer/02_intro.md b/docs/developer/02_intro.md new file mode 100644 index 0000000..5eb9db8 --- /dev/null +++ b/docs/developer/02_intro.md @@ -0,0 +1,47 @@ +--- +id: 02_intro +title: Introduction to QAT +sidebar_label: Introduction to QAT +sidebar_position: 2 +--- + +# Introduction to QAT + +The Quantification Analytics Tool (QAT) is a modernized solution for country-led forecasting and supply planning. QAT leverages new technologies to enhance and modernize the functionality offered by the incumbent PipeLine (supply planning) and Quantimed (forecasting) tools by providing advanced visualizations, master data management, and updated planning logic on a cloud-based solution with offline functionality. + +QAT is being built in two modules – the supply planning module (launched December 2020) and the forecasting module (launched June 2022). For more on the Functional Requirements used to build QAT, please see [Business & Technical Requirements](./architecture/requirements). + +## Version +| Version (date) | Author/Editor | Notes & Major Changes | +| :---- | :---- | :---- | +| 1 (Mar 15, 2021\) | GHSC-PSM FASP, Altius & FHI 360 | First draft | +| 2 (Sept 14, 2022\) | Kyle Duarte | Updated to include Forecasting Module | +| 3 (Aug 01, 2024\) | Akil Mahimwala | Updated to include reference to Integration documentation. | +| 4 (Jan 28, 2025\) | Dolly Chabria | Added information for ERP Shipment linking | +| 5 (Mar 07, 2026\) | Akil Mahimwala | Combined the Documenatition from different locations into one | + + +## Contents +- [Getting Started](./getting-started) +- [Architecture](./architecture/overview) +- [Database](./database/overview) +- [Integrations](./integrations/overview) +- [Installation](./installation/overview) +- [Guides](./guides/overview) + + +## Acronyms & Definitions + +| ARTMIS | Automated Requisition Tracking Management Information System | +| :---- | :---- | +| CDN | Content Delivery Network | +| ERP | Enterprise Resource planning | +| FASP | Forecasting and Supply Planning | +| GFPVAN | Global Family Planning Visibility & Analytics Network | +| GHSC-PSM | Global Health Supply Chain \- Procurement and Supply Management program | +| IAM | Identity and Access Management | +| JWT | JSON Web Tokens | +| QAT | Quantification Analytics Tool | +| RDS | Relational Database Service | +| VPC | Virtual Private Cloud | +| USAID | United States Agency for International Development | \ No newline at end of file diff --git a/docs/developer/03_getting-started.md b/docs/developer/03_getting-started.md new file mode 100644 index 0000000..6591973 --- /dev/null +++ b/docs/developer/03_getting-started.md @@ -0,0 +1,35 @@ +--- +id: getting-started +title: Getting Started +sidebar_label: Getting Started +sidebar_position: 3 +--- + +# Getting Started + +This guide will help you set up both the frontend and backend components of the QAT application. The system consists of a React-based frontend and a Java Spring Boot backend with MySQL database. + +## Installation + +### Frontend + +See [Frontend Setup](./installation/fasp-core-ui) for detailed instructions on how to set up `fasp-core-ui`. + +### Backend + +See [Backend Setup](./installation/fasp-api) for detailed instructions on how to set up `fasp-api`. + +## Reference Documentation + +* [Official Apache Maven documentation](https://maven.apache.org/guides/index.html) +* [Spring Boot Maven Plugin Reference Guide](https://docs.spring.io/spring-boot/docs/2.2.1.RELEASE/maven-plugin/) +* [Spring Web](https://docs.spring.io/spring-boot/docs/2.2.1.RELEASE/reference/htmlsingle/#boot-features-developing-web-applications) +* [Spring Boot DevTools](https://docs.spring.io/spring-boot/docs/2.2.1.RELEASE/reference/htmlsingle/#using-boot-devtools) + + +### Guides +The following guides illustrate how to use some features concretely: + +* [Building a RESTful Web Service](https://spring.io/guides/gs/rest-service/) +* [Serving Web Content with Spring MVC](https://spring.io/guides/gs/serving-web-content/) +* [Building REST services with Spring](https://spring.io/guides/tutorials/bookmarks/) diff --git a/docs/developer/04_Architecture/data-dictionary.md b/docs/developer/04_Architecture/data-dictionary.md new file mode 100644 index 0000000..fdd4479 --- /dev/null +++ b/docs/developer/04_Architecture/data-dictionary.md @@ -0,0 +1,12 @@ +--- +id: data-dictionary +title: Data Dictionary +sidebar_label: Data Dictionary +sidebar_position: 4 +--- + +# Data Dictionary + +Please see the corresponding excel file in the zipped folder for the [Data Dictionary v2.9](https://github.com/FASP-QAT/fasp-api/raw/master/docs/Data%20dictionary%20QAT%20SP%20v2.9.xlsx). + +**Note:** while this data dictionary has been created for the supply plan output that's sent to the GFPVAN & ARTMIS \- the fields cover all data fields in the broader database structure. \ No newline at end of file diff --git a/docs/developer/04_Architecture/intro.md b/docs/developer/04_Architecture/intro.md new file mode 100644 index 0000000..a81f6a3 --- /dev/null +++ b/docs/developer/04_Architecture/intro.md @@ -0,0 +1,40 @@ +--- +id: overview +title: High-level Architecture +sidebar_label: High-level Architecture +sidebar_position: 1 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +# High-level Architecture + +QAT is built on Java spring boot backend and React front end. The high-level architecture is below. + +![QAT High-level Architecture](/diagrams/high-level-architecture.png) + +Figure:QAT High-level Architecture + + +For a more detailed explaination of the above, please refer to the [Tech Stack documentation](/docs/developer/architecture/tech-stack). + +## Front End \- React based PWA + +The React based application is hosted on a NodeJS server. It is built as a Progressive Web App (PWA) and can work even if the User is offline. To initialize the application the User will have to login to the application once while he is online. The Username and Password that the user has entered is sent to the backend and once authorized a Token is returned. The Local application then does all subsequent calls to the API using the Token to identify and authenticate the request. + +At the first login the application Syncs all the Master data with the Server side pulling in any updates to the Master data. Since Master data is only edited on the live server. Server side always takes precedence during the Sync process and updates from Server will overwrite Client side Master data. + +Once a User has logged in the application stores his credentials and access rights locally and he can then continue to Login and access the application even if he is Offline. Authentication of the Username and Password is done locally. + +To begin editing a Program the user will need to Load the Program from the Server. Once a program has been loaded the user can then begin editing the Supply Plan by making changes to the Consumption, Inventory and Shipments. All of the changes that the user has made are stored locally on the IndexedDb. Once the user is ready to commit his changes to the Server he then selects the Commit version option. + +Please refer to [Process Flows](process-flow.md) for additional information on process flows. + +## Back End \- Java Spring Boot Application + +The Back end is a Java Spring Boot application. The Front end connects to the Server side through a REST API interface. + +### API + +Please refer to [API Documentation](/docs/api) for more details on the API. + diff --git a/docs/developer/04_Architecture/system-hierarchy.md b/docs/developer/04_Architecture/system-hierarchy.md new file mode 100644 index 0000000..131c9a1 --- /dev/null +++ b/docs/developer/04_Architecture/system-hierarchy.md @@ -0,0 +1,20 @@ +--- +id: system-hierarchy +title: System Hierarchy +sidebar_label: System Hierarchy +sidebar_position: 6 +--- +import DiagramEditor from '@site/src/components/DiagramEditor'; + +# System Hierarchy + +This diagram shows the system hierarchy of the application, illustrating the relationship between the different components - Realm, Country, Health Area, Organisation, Region and Program - with an example. + +![System Hierachy](/diagrams/system-hierarchy.drawio.png) + + + diff --git a/docs/developer/04_Architecture/tech-stack.md b/docs/developer/04_Architecture/tech-stack.md index 343e988..0e60b25 100644 --- a/docs/developer/04_Architecture/tech-stack.md +++ b/docs/developer/04_Architecture/tech-stack.md @@ -100,7 +100,6 @@ Details on the end points and the parameters that you need to pass and that you As an example, to generate the JWT authorization token you need to call the `https://www.quantificationanalytics.org/authenticate` endpoint. The Username and Password should be passed to the end point as part of the Body as a JSON object. Sample JSON - ```json { "username": "sombody@somedomain.com", diff --git a/docs/developer/05_Database/consumption-forecast.md b/docs/developer/05_Database/consumption-forecast.md new file mode 100644 index 0000000..5a6f838 --- /dev/null +++ b/docs/developer/05_Database/consumption-forecast.md @@ -0,0 +1,16 @@ +--- +id: consumption-forecast +title: Consumption Forecast ERD +sidebar_label: ERD Consumption Forecast +sidebar_position: 3 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Consumption Forecast ERD](/database/consumption-forecast.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/dataset-masterdata.md b/docs/developer/05_Database/dataset-masterdata.md new file mode 100644 index 0000000..a893698 --- /dev/null +++ b/docs/developer/05_Database/dataset-masterdata.md @@ -0,0 +1,16 @@ +--- +id: dataset-masterdata +title: Master Data ERD +sidebar_label: ERD Master data +sidebar_position: 2 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Dataset Masterdata ERD](/database/dataset-masterdata.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/intro.md b/docs/developer/05_Database/intro.md new file mode 100644 index 0000000..729aa46 --- /dev/null +++ b/docs/developer/05_Database/intro.md @@ -0,0 +1,37 @@ +--- +id: overview +title: Database Design +sidebar_label: Overview +sidebar_position: 1 +--- + +# Database Design + +The application has two databases: + +1. The main database, MySQL, which is the source of truth for all data in the application. +2. The indexDB, which is a subset of the main database that allows the application to work offline. + +**MySQL**: +The `fasp-api` project uses a MySQL database. This database is stored on the server. + +**IndexDB**: +The `fasp-ui` project uses an IndexedDB database, which is a subset of the main database, and is saved on each user's computer. + +All masters data is loaded by default (restricted by access rights), and users select specific program-versions to load. + +See an overview of the QAT Data Model from 2020 in [this PowerPoint presentation](https://github.com/FASP-QAT/fasp-api/blob/master/docs/Database%20ER%20Diagrams/QAT%20Data%20Model%20Overview.pptx). + +## Entity-Relationship Diagrams (ERDs) + +Entity-Relationship Diagrams (ERDs) for the QAT Application DB: + +* [Dataset Masterdata](dataset-masterdata) +* [Consumption Forecast](consumption-forecast) +* [Tree Template](tree-template) +* [Tree Forecast](tree-forecast) +* [Application masters](application-masters) +* [Inventory, Shipment and Consumption](inventory-shipment-consumption) +* [Product related tables](product-related-tables) +* [Realm masters](realm-masters) +* [User, Roles & ACL](user-roles-acl) \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-application-masters.md b/docs/developer/05_Database/qat-db-application-masters.md new file mode 100644 index 0000000..970a074 --- /dev/null +++ b/docs/developer/05_Database/qat-db-application-masters.md @@ -0,0 +1,16 @@ +--- +id: application-masters +title: Application Masters ERD +sidebar_label: ERD Application Masters +sidebar_position: 6 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Application Masters ERD](/database/qat-db-application-masters.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-inventory-shipment-consumption.md b/docs/developer/05_Database/qat-db-inventory-shipment-consumption.md new file mode 100644 index 0000000..85e5443 --- /dev/null +++ b/docs/developer/05_Database/qat-db-inventory-shipment-consumption.md @@ -0,0 +1,16 @@ +--- +id: inventory-shipment-consumption +title: Inventory, Shipment and Consumption ERD +sidebar_label: ERD Inventory, Shipment and Consumption +sidebar_position: 7 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Inventory, Shipment and Consumption ERD](/database/qat-db-inventory-shipment-and-consumption.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-product-related-tables.md b/docs/developer/05_Database/qat-db-product-related-tables.md new file mode 100644 index 0000000..1537921 --- /dev/null +++ b/docs/developer/05_Database/qat-db-product-related-tables.md @@ -0,0 +1,16 @@ +--- +id: product-related-tables +title: Product Related Tables ERD +sidebar_label: ERD Product Related Tables +sidebar_position: 8 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Product Related Tables ERD](/database/qat-db-product-related-tables.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-realm-masters.md b/docs/developer/05_Database/qat-db-realm-masters.md new file mode 100644 index 0000000..882ed2f --- /dev/null +++ b/docs/developer/05_Database/qat-db-realm-masters.md @@ -0,0 +1,16 @@ +--- +id: realm-masters +title: Realm Masters ERD +sidebar_label: ERD Realm Masters +sidebar_position: 9 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Realm Masters ERD](/database/qat-db-realm-masters.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/qat-db-user-roles-acl.md b/docs/developer/05_Database/qat-db-user-roles-acl.md new file mode 100644 index 0000000..b2eafd5 --- /dev/null +++ b/docs/developer/05_Database/qat-db-user-roles-acl.md @@ -0,0 +1,16 @@ +--- +id: user-roles-acl +title: User, Roles & ACL ERD +sidebar_label: ERD User, Roles & ACL +sidebar_position: 10 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![User, Roles & ACL ERD](/database/qat-db-user-roles-acl.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/tree-forecast.md b/docs/developer/05_Database/tree-forecast.md new file mode 100644 index 0000000..1d4b022 --- /dev/null +++ b/docs/developer/05_Database/tree-forecast.md @@ -0,0 +1,16 @@ +--- +id: tree-forecast +title: Tree Forecast ERD +sidebar_label: ERD Tree Forecast +sidebar_position: 5 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Tree Forecast ERD](/database/tree-forecast.png) + + \ No newline at end of file diff --git a/docs/developer/05_Database/tree-template.md b/docs/developer/05_Database/tree-template.md new file mode 100644 index 0000000..941ee8c --- /dev/null +++ b/docs/developer/05_Database/tree-template.md @@ -0,0 +1,16 @@ +--- +id: tree-template +title: Tree Template ERD +sidebar_label: ERD Tree Template +sidebar_position: 4 +--- + +import DiagramEditor from '@site/src/components/DiagramEditor'; + +![Tree Template ERD](/database/tree-template.png) + + \ No newline at end of file diff --git a/docs/developer/06_Integrations/erp-shipment-linking.md b/docs/developer/06_Integrations/erp-shipment-linking.md index 074ea01..74eb3c8 100644 --- a/docs/developer/06_Integrations/erp-shipment-linking.md +++ b/docs/developer/06_Integrations/erp-shipment-linking.md @@ -6,75 +6,88 @@ sidebar_position: 5 --- # ERP Shipment linking +This section outlines the workflow and rules for linking and managing QAT and ERP shipments within the system. The ARTMIS team is sending incremental order and shipment files daily. This information is updated in QAT, and for locally loaded programs, the data is synced automatically to the user's machine. -This section outlines the workflow and rules for linking and managing QAT and ERP shipments within the system. The ARTMIS team is sending incremental order and shipment files daily. This information is updated in QAT, and for locally loaded programs, the data is synced automatically to the user's machine. - -## 1. QAT Shipments - Not Linked (QAT-Initiated Linking) - -These are QAT shipments that are currently not linked to any ERP shipment. +## 1. QAT Shipments - Not Linked (QAT-Initiated Linking) +These are QAT shipments that are currently not linked to any ERP shipment. ### User Action: - - * Select one or more QAT shipments (the first selected is treated as the Parent Shipment). - * Select one or more ERP shipments to link with. + * Select one or more QAT shipments (the first selected is treated as the Parent Shipment). + * Select one or more ERP shipments to link with. ### System Behavior: + * The selected QAT shipments are updated: + - ERP flag = true + - Active = false + * Child Shipments are created for: + - RO No + - RO Prime Line No + - Order No + - Prime Line No + - KN Shipment No + * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. + * The non-parent QAT shipments will have the Parent Linked Shipment ID set to the Parent Shipment's ID. - * The selected QAT shipments are updated: - - ERP flag = true - - Active = false - * Child Shipments are created for: - - RO No - - RO Prime Line No - - Order No - - Prime Line No - - KN Shipment No - * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. - * The non-parent QAT shipments will have the Parent Linked Shipment ID set to the Parent Shipment's ID. + -## 2. QAT Shipments - Linked +## 2. QAT Shipments - Linked +This state reflects QAT shipments that are already linked. From here, users can either de-link or update ARU and Notes. + * If Shipment is Committed: + - Parent Shipment: + + Active = false + - Child Shipments: + + Active = true + + ERP flag = false + * If Shipment is Not Committed: + - Parent Shipment: + + Active = true + - Child Shipments: + + Active = false + + ERP flag = false + -This state reflects QAT shipments that are already linked. From here, users can either de-link or update ARU and Notes. -_ If Shipment is Committed: - Parent Shipment: + Active = false - Child Shipments: + Active = true + ERP flag = false -_ If Shipment is Not Committed: - Parent Shipment: + Active = true - Child Shipments: + Active = false + ERP flag = false -## 3. ERP Shipments - Not Linked (ERP-Initiated Linking) +## 3. ERP Shipments - Not Linked (ERP-Initiated Linking) + * These are ERP shipments that are not currently linked to any QAT shipment. + * User Action: + - Select one or more ERP shipments. + - Either: + + Link them to existing QAT shipments (first selected QAT shipment becomes the Parent Shipment), or + + Choose to create new QAT shipments directly. + * System Behavior: + - The associated QAT shipments are updated: + + ERP flag = true + + Active = false + - Child Shipments are created using: + + RO No + + RO Prime Line No + + Order No + + Prime Line No + + KN Shipment No + * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. + * The QAT shipments that are not the Parent will have the Parent Linked Shipment ID set accordingly. - * These are ERP shipments that are not currently linked to any QAT shipment. - * User Action: - - Select one or more ERP shipments. - - Either: - + Link them to existing QAT shipments (first selected QAT shipment becomes the Parent Shipment), or - + Choose to create new QAT shipments directly. - * System Behavior: - - The associated QAT shipments are updated: - + ERP flag = true - + Active = false - - Child Shipments are created using: - + RO No - + RO Prime Line No - + Order No - + Prime Line No - + KN Shipment No - * All child shipments will have the Parent Shipment ID set to the ID of the selected Parent QAT shipment. - * The QAT shipments that are not the Parent will have the Parent Linked Shipment ID set accordingly. + ## 4. Status Mapping +| **ARTMIS External Status Stage** | **QAT Shipment Status** | +| :---- | :---- | +| Cancelled | Cancelled | +| Delivered | Received | +| Order on Hold \- Pending Clarification Stage | On-hold | +| Order on Hold \- Pending Release | On-hold | +| Order on Hold \- Sourcing / Fulfillment Processing | On-hold | +| Partially Delivered | Shipped | +| Pending Clarification | Submitted | +| Pending PSM Source Final Approval | Submitted | +| Pending PSM Source Initial Approval | Submitted | +| Pending Recipient Approval | Submitted | +| Pending Release | Approved | +| Pending Shipment | Approved | +| Pending USAID Approval | Submitted | +| Shipped | Shipped | +| Sourcing / Fulfillment Processing | Submitted | + + + -| **ARTMIS External Status Stage** | **QAT Shipment Status** | -| :------------------------------------------------- | :---------------------- | -| Cancelled | Cancelled | -| Delivered | Received | -| Order on Hold \- Pending Clarification Stage | On-hold | -| Order on Hold \- Pending Release | On-hold | -| Order on Hold \- Sourcing / Fulfillment Processing | On-hold | -| Partially Delivered | Shipped | -| Pending Clarification | Submitted | -| Pending PSM Source Final Approval | Submitted | -| Pending PSM Source Initial Approval | Submitted | -| Pending Recipient Approval | Submitted | -| Pending Release | Approved | -| Pending Shipment | Approved | -| Pending USAID Approval | Submitted | -| Shipped | Shipped | -| Sourcing / Fulfillment Processing | Submitted | diff --git a/docs/developer/06_Integrations/intro.md b/docs/developer/06_Integrations/intro.md new file mode 100644 index 0000000..3dbb896 --- /dev/null +++ b/docs/developer/06_Integrations/intro.md @@ -0,0 +1,41 @@ +--- +id: overview +title: QAT-ERP Integrations +sidebar_label: Overview +sidebar_position: 1 +--- + +# QAT-ERP Integrations + +QAT has several data integrations with Enterprise Resource Planning (ERP) systems, as shown in the below diagram. + +There are 3 main types of interfaces between QAT and external systems + +1. **Supply plan sharing.** QAT sends supply plans to external systems. Currently QAT shares supply plans with the GHSC-PSM order management system ARTMIS, and to the GFPVAN. +1. **Catalog Updates.** QAT receives the ARTMIS product catalog, which updates the QAT planning unit details +1. **ERP Shipment linking** Currently the only active ERP shipment linking interface is with ARTMIS for GHSC-PSM orders. + +To summarise: + +- QAT receives ARTMIS Orders and Shipments +- QAT sends QAT shipments to ARTMIS +- QAT sends QAT Supply Plans to ARTMIS and GFPVAN +- Country Dashboards. A recent addition has been made to QAT where countries can pull updated Supply plans directly from QAT via an API and build their own Dashboards for reporting. To get more information on how this works please refer to [Country Dashboard](/docs/developer/Guides/country-dashboards) +To get more information on + + +![QAT data interfaces with ERP systems](/diagrams/QAT-ERP-Integrations.png) + +Figure 1 QAT data interfaces with ERP systems + +## QAT Supply Plan Sharing + +Refer to the [QAT Supply Plan Sharing](/docs/developer/integrations/qat-supply-plan-sharing) page for more information. + +## QAT Catalog Updates + +Refer to the [QAT Catalog Updates](/docs/developer/integrations/qat-catalog-updates) page for more information. + +## ERP Shipment Linking + +Refer to the [ERP Shipment Linking](/docs/developer/integrations/erp-shipment-linking) page for more information. diff --git a/docs/developer/06_Integrations/qat-catalog-updates.md b/docs/developer/06_Integrations/qat-catalog-updates.md new file mode 100644 index 0000000..b5ea735 --- /dev/null +++ b/docs/developer/06_Integrations/qat-catalog-updates.md @@ -0,0 +1,136 @@ +--- +id: qat-catalog-updates +title: QAT Catalog Updates +sidebar_label: QAT Catalog Updates +sidebar_position: 4 +--- + +# QAT Catalog Updates + +The QAT Catalog is created using the ARTMIS data. The Forecasting Unit, Planning Unit and Procurement Unit are all taken from ARTMIS database. If user changes any one of these data and ARTMIS pushes a new feed, then the former will be replaced by the `feed`. The non-ARTMIS data can be updated by the user on QAT. All Alternate Reporting Units are managed directly on QAT. + +### Unit +**Unit** is the unit of measure. QAT checks whether a unit already exists based on the unit name and unit code. If the unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Dimension | Eaches | +| Unit Name | product_base_unit/item_uom/item_weight_uom/item_sizemeasure | +| Unit Code | product_base_unit/item_uom/item_weight_uom/item_sizemeasure | + + +### Tracer Category +**Tracer Category** are a second tier, less broad grouping of product types specific to a Realm. QAT checks whether a tracer category already exists based on the tracer category name. If the tracer category exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Realm | Global Health | +| Tracer Category Name | product_tracer_cat | +| Technical Area | Null | + + +### Product Category +**Product Category** is a broad category group used to group planning units. QAT checks whether a product Category already exists based on the product category name. If the product category exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Realm | Global Health | +| Product Category Name | commodity_subcat_long_desc | +| Parent Product Category | commodity_council_long_desc | +| Sort Order | Auto generated by QAT | + + +### Planning Unit +**Planning Unit** is the product to be planned for in QAT. It is a product with full description up to the primary packaging (e.g. bottle of 30 tablets, 10x10 blister pack, etc.). QAT checks whether a Planning Unit already exists based on the SKU Code. If the Planning Unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Forecasting Unit | product_name_no_pack | +| Planning Unit Name | product_name | +| SKU Code | product_id | +| Unit | item_uom | +| Conversion Factor | product_base_unit_mult | + + +### Procurement Agent Planning Unit +**Procurement Agent Planning Unit** is the Mapping between Procurement Agent and Planning Unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Procurement Agent | GHSC-PSM | +| Planning Unit | product_name | +| Catalog Price | wcs_catalog_price | +| MOQ | planning_unit_moq | +| Units per pallet Euro 1 | planning_unit_per_pallet | +| Units per pallet Euro 2 | planning_unit_per_pallet | +| Units per container | planning_unit_per_container | +| Volume | planning_unit_volume_m3 | +| Weight | planning_unit_weight_kg | + + +### Forecasting Unit +**Forecasting Unit** is the base unit that will be used for a specified forecasting period. e.g. one tablet, one condom, one milliliter. QAT checks whether a Forecasting Unit already exists based on the SKU Code. If the Forecasting Unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Realm | Global Health | +| Product Category | Based on commodity_council_long_desc and commodity_subcat_long_desc | +| Tracer Category | product_tracer_cat | +| Generic Name | product_international_nonproprietary_name | +| Forecasting Unit Name | product_name_no_pack | +| Unit | product_base_unit | +| SKU Code | product_id_no_pack | + + +### Procurement Unit +**Procurement Unit** is the product at item level. In other words, it is a higher-level description of the planning unit including supplier-specific attributes. This information will not be visible/selectable by QAT users but will be sent automatically from procurement management systems. QAT checks whether a Procurement Unit already exists based on the SKU Code. If the Procurement Unit exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Planning Unit | product_name | +| Procurement Unit Name | item_name | +| Unit | item_uom | +| Conversion Factor | 1 | +| Manufacturer | item_supplier_name | +| Width Qty | item_width | +| Height Qty | item_height | +| Length Unit | item_sizemeasure | +| Length Qty | item_length | +| Weight Unit | item_weight_uom | +| Weight Qty | item_weight | +| Volume Unit | Null | +| Volumn Qty | Null | +| Units per case | item_units_per_case | +| Units per pallet Euro 1 | item_num_of_units_pallet | +| Units per pallet Euro 2 | Null | +| Units Per container | units_per_container | +| Labeling | item_label_languages | + + +### Procurement Agent Procurement Unit +**Procurement Agent Procurement Unit** is the mapping between procurement agent and procurement Unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Procurement Unit | item_name | +| Procurement Agent | GHSC-PSM | +| SKU Code | item_id | +| Vendor Price | wcs_catalog_price | +| Approved to shipped lead time | 3 | +| Gtin | item_manufacturer_gtin_upc | + + +### Manufacturer +**Manufacturer**, QAT checks whether a manufacturer already exists based on the Manufacturer Name. If the Manufacturer exists, QAT updates the existing record; otherwise, it inserts a new unit. The table below shows the mapping between QAT fields and corresponding ARTMIS fields. + +| QAT Field | ARTMIS Field | +| :---- | :---- | +| Realm | Global Health | +| Manufacturer Name | item_supplier_name | + +:::warning FIXME ARTMIS Sample files +We need to put the correct files in the location +::: +:::tip ARTMIS Sample files +[ARTMIS Sample files](https://github.com/FASP-QAT/fasp-api/tree/master/docs/Sample%20ARTMIS%20Feeds) +::: \ No newline at end of file diff --git a/docs/developer/06_Integrations/qat-interfaces.md b/docs/developer/06_Integrations/qat-interfaces.md new file mode 100644 index 0000000..f64319d --- /dev/null +++ b/docs/developer/06_Integrations/qat-interfaces.md @@ -0,0 +1,91 @@ +--- +id: qat-interfaces +title: QAT Interfaces +sidebar_label: QAT Interfaces +sidebar_position: 2 +--- + +# QAT Interfaces + +This section describes the data exchange interfaces between QAT and ARTMIS and GFPVAN. + +## File formats + +The following file formats are used for data exchange: + +* Files shared with ARTMIS are done via SFTP (xml formats). The formats of the files were provided by ARTMIS and used by QAT as is. +* Files imported from Pipeline and Quantimed are via xml- (formats dictated by each software). +* Files shared with GFPVAN are JSON. + +Only if the scripts below fail will QAT send an automated notification of this failure. +* Script files on Sharepoint [here](https://chemonics.sharepoint.com/sites/FASP-FHI360_Suncontract/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FFASP%2DFHI360%5FSuncontract%2FShared%20Documents%2FGeneral%2FDocumentation%2FBatch%20job%20scripts&viewid=5438e9ce%2D8d16%2D4183%2D8b68%2Daf909e3acd8e) +* ARTMIS Sample file details [here](https://github.com/FASP-QAT/fasp-api/tree/master/docs/Sample%20ARTMIS%20Feeds) + + +## QAT Server Scripts + +The following scripts are used to transfer data between QAT and external systems: + +| Script name | Description of the script | Script Path | Source folder | Source folder after completing script | Destination folder | Log Path | Schedule Time (EST) | +| :---- | :---- | :---- | :---- | :---- | :---- | :---- | :---- | +| [task1.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task1.sh) | To pull Catalog files from ARTMIS to QAT and then import them into the QAT db | /home/ubuntu/QAT/script/task1.sh | Remote server \-\> /FASP/ARTMIS | Remote server \-\> /FASP/processed | Local server \-\> /home/ubuntu/QAT/ARTMIS | /home/ubuntu/QAT/logs/ARTMIS/task1-yyyy-mm-dd.txt | 23:00 | +| [task2.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task2.sh) | To first generate the Order and Program files and then push the files from QAT to ARTMIS | /home/ubuntu/QAT/script/task2.sh | Local server \-\> /home/ubuntu/QAT/supplyPlan | Local server \-\> /home/ubuntu/QAT/supplyPlan/processed | Remote server \-\> /FASP/supplyPlan | /home/ubuntu/QAT/logs/ARTMIS/task2-yyyy-mm-dd.txt | 23:00 | +| [task3.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task3.sh) | To push Supply Plan files from QAT to ARTMIS | /home/ubuntu/QAT/script/task3.sh | Local server \-\> /home/ubuntu/QAT/supplyPlan/Artmis | Local server \-\> /home/ubuntu/QAT/supplyPlan/Artmis/processed | Remote server \-\> /FASP/supplyPlan and Sharepoint | /home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt | Every 15 min | +| [task6.sh](https://github.com/FASP-QAT/fasp-api/raw/master/docs/scripts/task6.sh) | To push GFPVAN files from QAT to GFPVAN SFTP Server | /home/ubuntu/QAT/script/task6.sh | Local server \-\> /home/ubuntu/QAT/supplyPlan/GFPVAN | Local server \-\>/home/ubuntu/QAT/supplyPlan/GFPVAN/processed | Remote server \-\> /e2open/b2b/scpusers2/e2net/E2NETSTG/e2c0000e9a-2ed8866a49-0/in | /home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt | Every 15 min | + +Table 1 QAT Server Scripts + +Note there is no task 4 and task 5. task 4 and task 5 used to exist but are no longer in use and therefore have been removed form the documentation. + +### Task1.sh + +`importProductCatalog.sh` + +1. We have a Local Directory on QAT Server `/home/ubuntu/QAT/ARTMIS` in which we will download the data from SFTP server from the `/FASP/ARTMIS`. +1. After Downloaded we will move data in processed folder on SFTP Server `/FASP/processed`. +1. Import the files into QAT, once they are imported they are moved to the `/home/ubuntu/QAT/ARTMIS/processed` folder +1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task1-yyy-ymm-dd.txt` + +Script Location `/home/ubuntu/QAT/script/task1.sh` (QAT Server) + +### Task2.sh + +`exportProgramAndOrder.sh` + +1. Generate the Program and Order csv files in `/home/ubuntu/QAT/supplyPlan` folder +1. We have Local path in QAT server `/home/ubuntu/QAT/supplyPlan` in which we need to transfer the csv file on SFTP server in `/FASP/supplyPlan` directory. +1. After transferring all the files on SFTP Server all the files will move in local folder `/home/ubuntu/QAT/supplyPlan/processed`. +1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task2-yyyy-mm-dd.txt` + +### Task3.sh + +1. We have Local path in QAT server `/home/ubuntu/QAT/supplyPlan/Artmis` in which we need to transfer the json file on SFTP server in `/FASP/supplyPlan` directory. +1. Copy of same files will be copied to sharepoint (Only Production Server) +1. After transferring all the files on SFTP Server all the files will move in local folder `/home/ubuntu/QAT/supplyPlan/Artmis/processed` +1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt` + +Script Location `/home/ubuntu/QAT/script/` (QAT Server) + +### Task6.sh + +1. We have Local path in QAT server /home/ubuntu/QAT/supplyPlan/GFPVAN in which we need to transfer the text file on GFPVAN SFTP server in `/e2open/b2b/scpusers2/e2net/E2NETSTG/e2c0000e9a-2ed8866a49-0/in directory.` +1. After transferring all the files on SFTP Server all the files will move in local folder `/home/ubuntu/QAT/supplyPlan/GFPVAN/` processed. +1. Log will be generated in QAT Server `/home/ubuntu/QAT/logs/ARTMIS/task3-yyyy-mm-dd.txt` + +Script Location `/home/ubuntu/QAT/script/` + +:::tip ARTMIS Sample files +[ARTMIS Sample files](https://github.com/FASP-QAT/fasp-api/tree/master/docs/Sample%20ARTMIS%20Feeds) +::: + +**TO CONNECT SFTP SERVER** + +sh QAT/script/sftp.sh +``` +Prodcution Server SFTP: \ +UAT Server SFTP: \ +SHAREPOINT: \ +GFPVAN SFTP for UAT :bastion3.e2open.net +GFPVAN SFTP for PROD :bastion7.e2open.net +``` + diff --git a/docs/developer/06_Integrations/qat-supply-plan-sharing.md b/docs/developer/06_Integrations/qat-supply-plan-sharing.md new file mode 100644 index 0000000..d3e20de --- /dev/null +++ b/docs/developer/06_Integrations/qat-supply-plan-sharing.md @@ -0,0 +1,14 @@ +--- +id: qat-supply-plan-sharing +title: QAT Supply Plan Sharing +sidebar_label: QAT Supply Plan Sharing +sidebar_position: 3 +--- + +# QAT Supply Plan Sharing + +Below are diagrams of which supply plans are shared by QAT to external systems. + +![QAT Supply Plan Sharing](/diagrams/QAT-supply-plan-flow.png) + +Figure 2 QAT Supply Plan Sharing \ No newline at end of file diff --git a/docs/developer/07_Installation/01_overview.md b/docs/developer/07_Installation/01_overview.md new file mode 100644 index 0000000..433d6fa --- /dev/null +++ b/docs/developer/07_Installation/01_overview.md @@ -0,0 +1,20 @@ +--- +id: overview +title: Overview +sidebar_label: Overview +sidebar_position: 1 +--- + +Below is the current QAT service side application set up, which is the recommended set up for future implementation on other servers. + + +## Source Code + +To get started with the source code, please look at the [Getting Started](/docs/developer/getting-started) guide. + +These are the main repositories for the QAT project: +1. [fasp-api](https://github.com/FASP-QAT/fasp-api) (Server-side project for QAT that runs the API's) +2. [fasp-core-ui](https://github.com/HSS-FASP-Team/fasp-core-ui/) (Client-side project for QAT) +3. [globalTables](https://github.com/HSS-FASP-Team/globalTables) (Tools to import the programs from Global Tables) +4. [ConvertPipelineToJson](https://github.com/FASP-QAT/ConvertPipelineToJson) (Tool to convert Pipeline to JSON) +5. [altiusUtilsMaven](https://github.com/FASP-QAT/AltiusUtilsMaven) (General purpose tools used across the fasp-api project) \ No newline at end of file diff --git a/docs/developer/07_Installation/02_fasp-api.md b/docs/developer/07_Installation/02_fasp-api.md new file mode 100644 index 0000000..c46c81d --- /dev/null +++ b/docs/developer/07_Installation/02_fasp-api.md @@ -0,0 +1,233 @@ +--- +id: fasp-api +title: Backend +sidebar_label: Backend +sidebar_position: 2 +--- + +# Backend Setup + +## Prerequisites +Before proceeding, ensure you have the following installed: +- MySQL 8 +- Git +- Java 17 +- jenv (Optional: for managing multiple Java versions) + +## Installation Steps + +1. **Clone the Repository** + ```bash + git clone git@github.com:FASP-QAT/fasp-api.git + cd fasp-api + ``` + + Please make sure that you have: + - An SSH key generated on your local machine + - The SSH key added to your GitHub account + - An SSH agent running on your local machine + +2. **Set up Application Directory Structure** + + Set temporary variables to specify the location of your code and application home folder: + + ```bash + QAT_CODE="$HOME/Code/QAT" + QAT_HOME="$HOME/Code/QAT/home" + ``` + + Note: these variables are temporary and are only used to set up the application + so it's not necessary to export them. + + Create application home folder: + ```bash + mkdir -p $QAT_HOME + ``` + + Extract the required folder structure: + ```bash + 7zz x docs/QATFolders.7z -o"$QAT_HOME" + ``` + + Configure application home path: + Edit `src/main/resources/application.properties` and set `qat.homeFolder` to the path of your application home folder (i.e. `QAT_HOME`). + + +3. **Setup MySQL Database** + + You can either use Docker to run MySQL 8, or run MySQL 8 as a service on your local machine. + + Depending on your choice, follow the instructions under 3a or 3b below. + + ***3a) Using Docker*** + + **Create a Docker network** + ```bash + docker network create qat-network + ``` + + **Start MySQL container** + ```bash + docker run --name qat-mysql \ + --network qat-network \ + -e MYSQL_ROOT_PASSWORD=root \ + -e MYSQL_DATABASE=fasp \ + -p 3306:3306 \ + -d mysql:8 + ``` + + **Create database and user** (__Optional__) + ```bash + docker exec -it qat-mysql mysql -uroot -proot + ``` + Then create the database and user: + ```sql + CREATE DATABASE IF NOT EXISTS `fasp` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin; + CREATE USER 'faspUser'@'%' IDENTIFIED BY 'faspP@ssw0rd'; + GRANT ALL PRIVILEGES ON fasp.* TO 'faspUser'@'%'; + GRANT CREATE VIEW, CREATE ROUTINE ON fasp.* TO 'faspUser'@'%'; + ``` + + :::info Note: + Run this command to set MySQL config to allow group by without an alias: + ```bash + docker exec -i qat-mysql mysql -uroot -proot fasp -e "SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));" + ``` + Note: This command will need to be run every time the container is restarted.The config should be added to the MySQL config file, but the default MySQL container does not have a config file. Once we are using docker compose we should be able to add this to the startup script, so it's not needed to be run manually. + ::: + + **Import database dumps** + ```bash + cd src/main/resources + 7zz x fasp-db.7z -o"$QAT_CODE" + docker exec -i qat-mysql mysql -uroot -proot fasp < "$QAT_CODE/fasp-db.sql" + ``` + + ***3b) Locally*** + + Navigate to the project's resource directory and extract the database dump: + ```bash + cd src/main/resources + 7zz x fasp-db.7z -o"$QAT_CODE" + ``` + + Set up the database and user: + ```bash + mysql -u root -p + ``` + Then run the following SQL commands: + ```sql + CREATE DATABASE IF NOT EXISTS `fasp` DEFAULT CHARACTER SET utf8 COLLATE utf8_bin; + CREATE USER 'faspUser'@'%' IDENTIFIED BY 'faspP@ssw0rd'; + GRANT ALL PRIVILEGES ON fasp.* TO 'faspUser'@'%'; + GRANT CREATE VIEW, CREATE ROUTINE ON fasp.* TO 'faspUser'@'%'; + ``` + + Then import the database dumps: + ```bash + # Import main database structure + mysql -u root -p fasp < "$QAT_CODE/fasp-db.sql" + ``` + + Then add this line to my.conf, to allow group by without an alias, and restart MySQL: + ``` + sql_mode=STRICT_TRANS_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE,ERROR_FOR_DIVISION_BY_ZERO,NO_ENGINE_SUBSTITUTION + ``` + + +:::info +Add a user to the application by running the following SQL script: +```sql +INSERT INTO fasp.us_user (REALM_ID, USERNAME, PASSWORD, EMAIL_ID, ORG_AND_COUNTRY, LANGUAGE_ID, ACTIVE, FAILED_ATTEMPTS, EXPIRES_ON, SYNC_EXPIRES_ON, LAST_LOGIN_DATE, CREATED_BY, CREATED_DATE, LAST_MODIFIED_BY, LAST_MODIFIED_DATE, AGREEMENT_ACCEPTED, DEFAULT_MODULE_ID, DEFAULT_THEME_ID, SHOW_DECIMALS) VALUES ('1', 'Test User', "$2a$10$wk103RbWjloLY4iuWATn0.0ifqnXfAKGpKM/NaeoWgGMwh8CeaCia", 'testuser@qat.com', 'Altius', '1', '1', '0', NOW(), '2024-11-26 11:15:22', '2024-11-26 11:15:22', '1', '2020-02-12 12:00:00', '1', '2024-11-20 08:44:46', '1', '2', '1', '0'); +SET @user_id=last_insert_id(); +INSERT INTO us_user_role VALUES(null,@user_id,'ROLE_INTERNAL_USER',1,NOW(),1,NOW()); +INSERT INTO us_user_acl VALUES(null,@user_id,'ROLE_INTERNAL_USER',null,null,null,null,1,NOW(),1,NOW()); +``` + +Login will be `testuser@qat.com` with password `pass`. +::: + +4. **Update the QAT properties** + Edit `qat.properties` and add the database connection properties: + + ```bash + vi $QAT_HOME/QAT/properties/qat.properties + ``` + + ```properties + spring.datasource.url=jdbc:mysql://localhost:3306/fasp?allowPublicKeyRetrieval=true&useSSL=false + spring.datasource.username=root + spring.datasource.password=root + ``` + + +5. **Configure Java Version (Optional)** + If you're using jenv to manage Java versions: + ```bash + jenv add + jenv local 17 + ``` + +6. **Build and Run the Application** + ```bash + ./mvnw clean spring-boot:run + ``` + + :::info Logs + To monitor the application logs: + ```bash + tail -f "$QAT_HOME/QAT/logs/qat/faspLogger.log" + ``` + ::: + +## Verify the API is running + +1. Open the following URLs in your browser: + + http://localhost:8084/actuator/health + + You should see a response similar to the following: + + ```json + { + "status": "UP" + } + ``` + +## Swagger / OpenAPI + +Access the Swagger UI at: + +* http://localhost:8084/swagger-ui/index.html + +Access the OpenAPI spec at: + +* http://localhost:8084/v3/api-docs (JSON) +* http://localhost:8084/v3/api-docs.yaml + +### Authenticate + +To use the API, you need to authenticate. To do so, follow these steps: + +To get an access token: + +1. Scroll to `jwt-authentication-rest-controller` +2. Open the `Post` `/authenticate` endpoint +3. Click "Try it out" +4. Enter your login details +5. Click "Execute" + +To use the token to authenticate your requests: + +6. Scroll to the top, click "Authorize" button +7. Enter token +8. Click "Authorise" + +Now you can use the Swagger API endpoints + +# Troubleshooting + +If you encounter any issues during the setup process, please check the following: +- Ensure all prerequisites are correctly installed +- Verify that the ports 3306 (MySQL) are not already in use +- Check the application logs for detailed error messages \ No newline at end of file diff --git a/docs/developer/07_Installation/03_fasp-core-ui.md b/docs/developer/07_Installation/03_fasp-core-ui.md new file mode 100644 index 0000000..0606d41 --- /dev/null +++ b/docs/developer/07_Installation/03_fasp-core-ui.md @@ -0,0 +1,62 @@ +--- +id: fasp-core-ui +title: Frontend +sidebar_label: Frontend +sidebar_position: 3 +--- + +# Frontend Setup + +## Prerequisites + +Before you begin, ensure you have the following installed: +- Git +- Node.js 16 +- npm (Node Package Manager) +- nvm (Optional: for managing multiple Node.js versions) + +## Installation Steps + +1. **Clone the Repository** + ```bash + git clone git@github.com:FASP-QAT/fasp-core-ui.git + cd fasp-core-ui + ``` + + Please make sure that you have: + - An SSH key generated on your local machine + - The SSH key added to your GitHub account + - An SSH agent running on your local machine + +2. **Configure Node Version (Optional)** + If you're using nvm to manage Node.js versions: + ```bash + nvm install 16 + nvm use 16 + ``` + +3. **Install Dependencies** + ```bash + npm install --legacy-peer-deps + ``` + +4. **Start the Development Server** + ```bash + npm run dev + ``` + +5. **Configuration (Optional)** + To connect to a different backend server, modify the `API_URL` in `Constants.js`. The application is set up to connect to the live backend server by default. + +:::tip Login +To login to the application, you will need to create a new user in the backend. + +The instructions for creating a user are available in the [fasp-api](/docs/developer/installation/developer/fasp-api) installation guide, if you are running your own backend server. + +If you are connecting to the demo QAT server, you, you will need to request a new user account from the FASP team. +::: + +## Verify the application is running + +The application will be available at: +http://localhost:4202/ diff --git a/docs/developer/07_Installation/04_standard-installation.md b/docs/developer/07_Installation/04_standard-installation.md new file mode 100644 index 0000000..c4de83f --- /dev/null +++ b/docs/developer/07_Installation/04_standard-installation.md @@ -0,0 +1,125 @@ +--- +id: standard-installation +title: Standard Installation +sidebar_label: Standard Installation +sidebar_position: 4 +--- + +# QAT Application Installation Guide + +## Prerequisites +- Java Runtime Environment +- Node.js server with npm +- MySQL database server +- Git +- PM2 (Node.js process manager) +- Access to FASP-QAT repositories + +## Pre-Installation Preparation + +### 1. Record Current Git Commit Hash +Before pulling the latest code, record the current commit hash for both the API and UI repositories. This will allow you to revert to the previous state if needed. + +1. Navigate to the API repository: + ```bash + cd /home/ubuntu/GitRepo/fasp-api + git rev-parse HEAD > /backup/fasp/api_last_commit_$(date +%Y%m%d_%H%M%S).txt + ``` + +2. Navigate to the UI repository: + ```bash + cd /home/ubuntu/GitRepo/fasp-core-ui + git rev-parse HEAD > /backup/fasp/ui_last_commit_$(date +%Y%m%d_%H%M%S).txt + ``` + +### 2. Backup Current Database +1. Connect to your MySQL database server +2. Back up your existing database: + ```bash + mysqldump -u [username] -p fasp > backup_$(date +%Y%m%d_%H%M%S).sql + ``` + +## Installation Steps + +### 1. Database Preparation +1. Connect to your MySQL database server +2. Execute all provided SQL scripts in sequential order: + ```bash + mysql -u [username] -p fasp < [script_name].sql + ``` + + +### 2. UI Installation +1. Navigate to the UI deployment directory: + ```bash + cd /home/ubuntu/GitRepo/fasp-core-ui + ``` + +2. Stop the existing UI service: + ```bash + pm2 stop QAT-React + ``` + +3. Get the latest code: + ```bash + git checkout master + git pull + ``` + +4. Install dependencies: + ```bash + npm install + ``` + +5. Start the UI service: + ```bash + pm2 start QAT-React + ``` + +6. Verify the service status: + ```bash + pm2 status + ``` + +7. Check logs if needed: + ```bash + pm2 log + ``` + +### 3. API Installation +1. Navigate to the API directory: + ```bash + cd /home/ubuntu/GitRepo/fasp-api + ``` + +2. Build and deploy the API: + ```bash + run sh buildAndDeploy.sh + ``` + +3. Check the API logs: + ```bash + tail -f /home/ubuntu/QAT/logs/qat/faspLogger.log + ``` + +### 4. Post-Installation Verification +1. Verify API endpoints are accessible +2. Verify UI is accessible through the browser +3. Perform basic functionality testing: + - User login + - Basic navigation + - Core features +4. Monitor logs for any errors: + - UI logs: `pm2 log` + - API logs: `tail -f faspLogger.log` + +## Troubleshooting +- If services fail to start, check the log files for specific error messages +- Ensure database connectivity is established +- Confirm all required ports are open and accessible +- Verify file permissions are set correctly +- If build fails: + - Check Git branch is correct + - Verify all dependencies are installed + - Check disk space availability + - Review build logs for specific errors \ No newline at end of file diff --git a/docs/developer/07_Installation/05_server-setup.md b/docs/developer/07_Installation/05_server-setup.md new file mode 100644 index 0000000..6768091 --- /dev/null +++ b/docs/developer/07_Installation/05_server-setup.md @@ -0,0 +1,248 @@ +--- +id: server-setup +title: Server Setup +sidebar_label: "Server Setup" +sidebar_position: 4 +--- + +# Server Setup + +## Suggested Server Setup + +The below diagram explains the setup that is the suggested setup for the QAT application. The current set up is with Amazon Web Services (AWS) . For access to the login for this, please contact [Support@quantificationanalytics.org](mailto:Support@quantificationanalytics.org). + +![Server Setup](/diagrams/server-setup.png) + +Figure 2: Relational Database Service (RDS) and Virtual Private Cloud (VPC) + +This is the suggested setup the user can choose to downgrade this as per requirements. On a minimum level ,the following components are required + +a. Load balancer or WebServer +b. Application Server +c. Database Server + +:::warning FIXME +This section needs to be updated as the versions are outdated. + +You can refer to the installation guides for [fasp-api](/docs/developer/installation/developer/fasp-api) and [fasp-core-ui](/docs/developer/installation/developer/fasp-core-ui) for more information on up to date versions for some of the dependencies. +::: + +## Operating system requirements + +**Application Server**: +The Application server requires a Linux based server preferably Ubuntu with at least ver 18.04LTS or higher. + +**Database Server**: +The Database server needs MySql v 5.7 + +## Other Software + +**Application Server**: + +1. Java JDK ver 11 + `sudo apt-get install openjdk-11-jdk-headless` + +2. Apache WebServer + `sudo apt-get install apache2` + +3. Node JS version 8.10 + `sudo apt-get install nodejs` + +4. PM2 + A production process manager for Node.js applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime and to facilitate common system admin tasks. + + `sudo npm install -g pm2` + +## Setup process + +### Application Server + +#### Apache server + +To setup Apache server use the following commands +`sudo apt-get install apache2` + +Copy the SSL Certificates into a folder called `/etc/apache2/ssl/` + +Create a file called `www.quantificationanalytics.org.conf` in the following folder `/etc/apache2/sites-available/` with the following contents: + +``` + + ServerName quantificationanalytics.org + ServerAlias www.quantificationanalytics.org + ServerAdmin info@altius.cc + ErrorLog /var/log/apache2/qat_error.log + + # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. + LogLevel warn + CustomLog /var/log/apache2/qat_access.log combined + + RewriteEngine On + RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} + + + + ServerName quantificationanalytics.org + ServerAlias www.quantificationanalytics.org + ServerAdmin info@altius.cc + + ErrorLog /var/log/apache2/qat_error.log + + # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. + LogLevel warn + CustomLog /var/log/apache2/qat_access.log combined + + ProxyRequests Off + ProxyPreserveHost On + ProxyPass / http://localhost:4202/ + + SSLEngine On + SSLCertificateFile /etc/apache2/ssl/WWW.QUANTIFICATIONANALYTICS.ORG.crt + SSLCertificateKeyFile /etc/apache2/ssl/www.quantificationanalytics.org.txt + SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown + + Header always set Strict-Transport-Security "max-age=63072000;" + Header always unset X-Frame-Options + Header set X-Frame-Options "SAMEORIGIN" + Header always set X-Content-Type-Options nosniff + Header set Feature-Policy: "fullscreen 'self'" + Header set Referrer-Policy: "no-referrer" + +``` + +Create a file called `api.quantificationanalytics.org.conf` in the following folder `/etc/apache2/sites-available/` with the following contents + +``` + + ServerAlias api.quantificationanalytics.org + ServerAdmin info@altius.cc + + ErrorLog /var/log/apache2/qatapi_error.log + + # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. + LogLevel warn + CustomLog /var/log/apache2/qatapi_access.log combined + + RewriteEngine On + RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI} + + + + ServerAlias api.quantificationanalytics.org + ServerAdmin info@altius.cc + + ErrorLog /var/log/apache2/qatapi_error.log + + # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. + LogLevel warn + CustomLog /var/log/apache2/qatapi_access.log combined + + ProxyRequests Off + ProxyPreserveHost On + ProxyPass / ajp://localhost:8109/ + + SSLEngine On + SSLCertificateFile /etc/apache2/ssl/API.QUANTIFICATIONANALYTICS.ORG.crt + SSLCertificateKeyFile /etc/apache2/ssl/api.quantificationanalytics.org.txt + SSLCertificateChainFile /etc/apache2/ssl/DV_USERTrustRSACertificationAuthority.crt + + SetEnvIf User-Agent ".*MSIE.*" nokeepalive ssl-unclean-shutdown + +``` + +To enable the modules required for Apache to work execute the following: +```bash +sudo a2enmod proxy proxy_ajp proxy_http rewrite ssl +``` + +To enable the sites you need to run the following command: +```bash +sudo a2ensite www.quantificationanalytics.org.conf +sudo a2ensite api.quantificationanalytics.org.conf +``` + +To restart the apache2 service and activate your new settings run the following command: +```bash +sudo systemctl restart apache2.service +``` + +### Node JS + +Run the following command to install Node JS: +```bash +curl \-sL https://deb.nodesource.com/setup\_12.x | sudo \-E bash \- +``` + +Run the following command to install Node JS: +```bash +sudo apt-get install \-y nodejs +``` + +Run the following command to update npm to the latest version: +```bash +sudo npm install npm@latest \-g +``` + +### PM2 + +:::warning FIXME +Add instructions for installing PM2 +::: + +### API Application + +To Install the application and run it on the Server download the compiled `QAT.war` file on to the Server `/home/ubuntu/qatApi` folder + +Make sure the `QAT.war` file is executable + +Create a service file in the `/etc/systemd/system/QATAPI.service` with the following content: + +``` +[Unit] +Description=QAT API + +[Service] +User=nobody +# The configuration file application.properties should be here: +WorkingDirectory=/home/ubuntu/qatApi +ExecStart=/usr/bin/java -Xmx256m -jar QATAPI.jar +SuccessExitStatus=143 +# TimeoutStopSec=10 +# Restart=on-failure +# RestartSec=5 + +[Install] +WantedBy=multi-user.target +``` + +Make sure that service file has 755 rights +```bash +sudo chmod 755 /etc/systemd/system/QATAPI.service +``` + +Reload the daemon services +```bash +sudo systemctl daemon-reload +``` + +You can now use the following commands to start, stop or restart the application + +To start the application +```bash +sudo systemctl start QATAPI.service +``` + +To stop the application +```bash +sudo systemctl stop QATAPI.service +``` + +To check the status of the application +```bash +sudo systemctl status QATAPI.service +``` + +To restart the application +```bash +sudo systemctl restart QATAPI.service +``` \ No newline at end of file diff --git a/docs/developer/07_Installation/06_rollback-procedure.md b/docs/developer/07_Installation/06_rollback-procedure.md index deaba95..f2c05d7 100644 --- a/docs/developer/07_Installation/06_rollback-procedure.md +++ b/docs/developer/07_Installation/06_rollback-procedure.md @@ -8,9 +8,7 @@ sidebar_position: 6 # QAT Application Rollback Procedure ## Prerequisites - Before starting rollback, ensure you have: - - Previous commit hashes (saved during installation) - Database backup (taken before installation) - Access to both API and UI repositories @@ -18,7 +16,6 @@ Before starting rollback, ensure you have: ## Rollback Steps ### 1. Database Rollback - 1. Connect to your MySQL database server 2. Restore the previous database backup: ```bash @@ -26,34 +23,28 @@ Before starting rollback, ensure you have: ``` ### 2. UI Rollback - 1. Navigate to the UI directory: - ```bash cd /home/ubuntu/GitRepo/fasp-core-ui ``` 2. Stop the UI service: - ```bash pm2 stop QAT-React ``` 3. Revert to previous commit: - ```bash git checkout $(cat /backup/fasp/ui_last_commit_$(date +%Y%m%d_%H%M%S).txt) ``` 4. Clean and reinstall dependencies: - ```bash rm -rf node_modules npm install ``` 5. Start the UI service: - ```bash pm2 start QAT-React ``` @@ -64,27 +55,22 @@ Before starting rollback, ensure you have: ``` ### 3. API Rollback - 1. Navigate to the API directory: - ```bash cd /home/ubuntu/GitRepo/fasp-api ``` 2. Stop the API service: - ```bash pm2 stop fasp-api ``` 3. Revert to previous commit: - ```bash git checkout $(cat /backup/fasp/api_last_commit_$(date +%Y%m%d_%H%M%S).txt) ``` 4. Rebuild and redeploy: - ```bash run sh buildAndDeploy.sh ``` @@ -95,9 +81,7 @@ Before starting rollback, ensure you have: ``` ### 4. Post-Rollback Verification - 1. Check service status: - ```bash pm2 status ``` @@ -109,17 +93,15 @@ Before starting rollback, ensure you have: - Basic navigation - Core features 5. Monitor logs for any errors: - ```bash # UI logs pm2 log QAT-React - + # API logs tail -f /home/ubuntu/QAT/logs/qat/faspLogger.log ``` ## Troubleshooting - - If services fail to start: - Check logs for specific error messages - Verify all dependencies are installed @@ -135,4 +117,4 @@ Before starting rollback, ensure you have: - If Git checkout fails: - Verify commit hash exists - Check for uncommitted changes - - Ensure proper repository access + - Ensure proper repository access \ No newline at end of file diff --git a/docs/developer/08_Guides/automated-test-backend.bkp b/docs/developer/08_Guides/automated-test-backend.bkp new file mode 100644 index 0000000..5f9f0c4 --- /dev/null +++ b/docs/developer/08_Guides/automated-test-backend.bkp @@ -0,0 +1,169 @@ +# Automated Testing - Backend + +This document serves as a guide for setting up, writing, and running automated tests for our project. It explains the frameworks, tools, and conventions used to ensure consistency and efficiency. + +## Table of Contents + +1. [Introduction](#introduction) +2. [Test Frameworks and Tools](#test-frameworks-and-tools) +3. [Test Structure and Conventions](#test-structure-and-conventions) +4. [Running Tests](#running-tests) +5. [Writing New Tests](#writing-new-tests) +6. [Code Coverage](#code-coverage) +7. [Continuous Integration (CI) Integration](#continuous-integration-ci-integration) +8. [Troubleshooting](#troubleshooting) +9. [References](#references) + +## Introduction + +Automated tests are a crucial part of our development workflow to ensure code quality and stability. We use a combination of unit tests, integration tests, and end-to-end (E2E) tests to cover all aspects of the application. + +### Test Categories + +- **Unit Tests**: Validate individual methods and classes. +- **Integration Tests**: Test how different components interact. + +## Test Frameworks and Tools + +### Backend + +- **JUnit**: Unit testing framework for Java. +- **Testcontainers**: Manages containerized dependencies (e.g., databases) for integration tests. +- **JaCoCo**: Tracks code coverage. + +### Utilities + +- **Maven Surefire Plugin**: Runs unit and integration tests. +- **JaCoCo Maven Plugin**: Measures test coverage. + +## Test Structure and Conventions + +The tests are organized into different categories based on their scope: + +```plaintext +src/ + main/ + java/ # Application code + test/ + java/ + cc/ + altius/ + FASP # Unit and integration tests + +``` +# Naming Conventions + +- **Test Classes**: Test classes should end with `Test` (e.g., `UserServiceTest`). +- **Test Methods**: Test methods should be descriptive (e.g., `shouldReturnUserById`). + +## Annotations (JUnit) + +- `@Test`: Marks a method as a test. +- `@BeforeAll` / `@BeforeEach`: Setup methods that run before tests. +- `@AfterAll` / `@AfterEach`: Cleanup methods that run after tests. + +--- + +# Running Tests + +## Backend + +- **Run all tests**: + ```bash + mvn clean test + ``` + +- **Run specific test class**: + ```bash + mvn -Dtest=UserServiceTest test + ``` +- **Run integration tests**: + ```bash + mvn verify + ``` + +## Writing New Tests + +### Backend (JUnit) +1. Create a test class in `src/test/java`. +2. Use mocks (e.g., with Mockito) to isolate components. + +#### Example: +```java +@Test +public void shouldReturnUserById() { + when(userRepository.findById(1)).thenReturn(Optional.of(new User(1, "John Doe"))); + User result = userService.getUserById(1); + assertEquals("John Doe", result.getName()); +} +``` +### Integration Tests (Using `AbstractIntegrationTest`) +`AbstractIntegrationTest` serves as a base class for integration tests in the application. It provides a common setup and teardown logic for integration tests, ensuring consistency across tests that require database interactions and HTTP request simulations. + +### Integrated Testing Utilities and Frameworks +This class integrates several testing utilities and frameworks: +- **Spring Boot Test Framework**: Utilizes `@SpringBootTest` for testing. +- **Testcontainers**: Manages a MySQL container for database operations during testing. +- **MockMvc**: Simulates HTTP requests and responses in the context of integration tests. +- **Dynamic Property Source**: Dynamically configures the database connection properties. + +### Inherited Functionality +By extending this class, tests automatically inherit the following: +- A preconfigured `MockMvc` instance for simulating HTTP requests. +- The necessary setup for a Testcontainers-managed MySQL container. +- Common utility methods like converting objects to JSON. +- Stops the MySQL container after all tests are completed. + + + +## Code Coverage +We aim for a low minimum threshold for existing code but at least 80% coverage for new classes. Ensure your tests cover: +- Edge cases +- Error handling +- Key workflows + +### To enforce coverage thresholds: +Configure JaCoCo in `pom.xml`: +```xml + + + CLASS + + + LINE + COVEREDRATIO + 0.80 + + + + +``` +## Continuous Integration (CI) Integration +Our CI pipeline (Jenkins/GitHub Actions) automatically runs tests on every push/PR. + +### Steps: +1. Run tests: Backend and frontend tests. +2. Generate coverage reports: Both JaCoCo and frontend reports. +3. Fail build on low coverage. + +## Troubleshooting + +### Common Issues +- **Testcontainers not starting**: Verify Docker is running and accessible. + +### Debugging Tips +- Use `mvn -X` for verbose logs. +- For flaky tests, isolate and re-run: + ```bash + mvn -Dtest=FlakyTest test + ``` + +## References +- [JUnit 5 Documentation](https://junit.org/junit5/docs/current/user-guide/) +- [Testcontainers](https://www.testcontainers.org/) +- [JaCoCo Maven Plugin](https://www.jacoco.org/) + +Feel free to extend this documentation as our testing strategy evolves! + + + diff --git a/docs/developer/08_Guides/automated-test-frontend.bkp b/docs/developer/08_Guides/automated-test-frontend.bkp new file mode 100644 index 0000000..acab19a --- /dev/null +++ b/docs/developer/08_Guides/automated-test-frontend.bkp @@ -0,0 +1,275 @@ +# Automated Testing - Frontend + +This document serves as a guide for setting up, writing, and running automated tests for our frontend project. It explains the frameworks, tools, and conventions used to ensure consistency and efficiency. + +## Overview +Automated tests are crucial for ensuring our React application's reliability and maintainability. We implement three levels of testing. + +- **Unit Tests**: Vitest for component and unit testing +- **E2E Tests**: Cypress for integration and end-to-end testing +- **CI Pipeline**: GitHub Actions for automated testing + +## Test Structure + +### Directory Layout +``` +├── src/ +│ ├── __tests__/ # Unit tests +│ │ ├── components/ # Component tests +│ │ └── unit/ # Utility function tests +├── cypress/ +│ ├── e2e/ # Integration tests +│ ├── fixtures/ # Test data +│ └── support/ # Custom commands & utilities +``` + +## Writing Tests + +### Unit Tests (Vitest) + +#### Component Test Example +```jsx +import { render, screen, fireEvent } from '@testing-library/react' +import { describe, it, expect, vi } from 'vitest' +import LoginForm from '../components/LoginForm' + +describe('LoginForm', () => { + it('should handle successful login', async () => { + const onSubmit = vi.fn() + render() + + // Fill form + await fireEvent.change(screen.getByLabelText('Username'), { + target: { value: 'testuser' } + }) + await fireEvent.change(screen.getByLabelText('Password'), { + target: { value: 'password123' } + }) + + // Submit form + await fireEvent.click(screen.getByRole('button', { name: /login/i })) + + // Assertions + expect(onSubmit).toHaveBeenCalledWith({ + username: 'testuser', + password: 'password123' + }) + }) + + it('should show validation errors', async () => { + render() + + // Submit empty form + await fireEvent.click(screen.getByRole('button', { name: /login/i })) + + // Check error messages + expect(screen.getByText('Username is required')).toBeInTheDocument() + }) +}) +``` + +#### Utility Test Example +```javascript +describe('RealmService', () => { + let service; + + beforeEach(() => { + service = new RealmService(); + }); + + test('should construct URL correctly', () => { + expect(service.getUrl()).toBe(`${API_URL}/api/realm`); + }); +}); +``` + +### E2E Tests (Cypress) + +#### Login Flow Example +```javascript +describe('Login Flow', () => { + beforeEach(() => { + cy.mockRealApiCalls(); + }) + + it('should login successfully', () => { + cy.login('correctuser@qat.info', 'password'); + cy.url().should('include', '/#/ApplicationDashboard'); + }) + + it('should handle login errors', () => { + cy.intercept('POST', `${API_URL}/authenticate`, { + statusCode: 401, + body: { messageCode: 'static.message.login.invalidCredentials' } + }).as('loginRequest'); + + cy.login('wrong@email.com', 'wrongpass'); + cy.contains('Incorrect login or password').should('be.visible'); + cy.url().should('include', '/#/login'); + }) +}) +``` + +## Testing Standards + +### Unit Tests +1. **Naming Convention** + - Test files: `*.test.{js,jsx}` + - Test suites: Describe the component/function + - Test cases: Start with "should" and describe expected behavior + +2. **Component Testing** + - Test user interactions + - Test rendering logic + - Test prop changes + - Test error states + - Use React Testing Library queries in this order: + 1. getByRole + 2. getByLabelText + 3. getByText + 4. getByTestId (last resort) + +3. **Mocking** + - Mock external dependencies + - Use `vi.mock()` for module mocks + - Use `vi.fn()` for function mocks + - Reset mocks between tests + - Keep mocks minimal: + - If your test requires more than 2-3 mocks, this is often a code smell + - Consider either: + - Refactoring the component to reduce dependencies + - Writing an integration test instead of a unit test + - Breaking down the component into smaller, more focused pieces + +### E2E Tests +1. **Structure** + - Group related tests in a single spec file + - Use descriptive test names + - Setup test data in `beforeEach` + - Clean up after tests + +2. **Best Practices** + - Mock API responses for consistent tests + - Use custom commands for common operations + - Add data-testid for stable selectors + - Test the happy path first, then edge cases + +3. **Custom Commands** + ```javascript + // cypress/support/commands.js + Cypress.Commands.add('login', (email = 'test@example.com', password = 'password123') => { + cy.visit('/#/login', { + onBeforeLoad: (win) => { + win.WebSocket = undefined; + } + }); + cy.window().then((win) => { + win.localStorage.setItem('loginOnline', 'true'); + win.localStorage.setItem('sessionTimedOut', '0'); + win.localStorage.setItem('sessionChanged', '0'); + win.localStorage.setItem('lastLoggedInUsersLanguageChanged', 'false'); + }); + // Fill in the login form and submit + cy.get('#emailId').should('be.visible').type(email); + cy.get('#password').should('be.visible').type(password); + cy.get('button[type="submit"]').should('be.visible').click(); + }); + ``` + +## Running Tests + +### Unit Tests +```bash +npm test # Run tests in watch mode +npm run test:coverage # Run tests with coverage +npm run test:ui # Run tests with UI +``` + +### E2E Tests +```bash +npm run cypress:open # Open Cypress UI +npm run cypress:run # Run Cypress headless +npm run test:e2e # Start dev server and run Cypress +``` + +### All Tests +```bash +npm run test:all # Run both unit and E2E tests +``` + +## CI/CD Pipeline +- Runs on every push (excluding documentation changes) +- Sequential execution: unit tests → E2E tests → coverage reporting +- Artifacts: test videos and screenshots available on failure +- Coverage reports sent to Code Climate + +### Coverage Requirements +- Minimum overall coverage: 80% +- Minimum function coverage: 80% +- Minimum branch coverage: 75% + +## Debugging Tests + +### Unit Tests +- Use `test.only()` to run specific tests +- Use `console.log()` or `debug()` from Testing Library +- Check test coverage with `npm run test:coverage` + +### E2E Tests +- Use `cy.pause()` to pause test execution +- Use `.debug()` to inspect elements +- Check screenshots and videos in `cypress/screenshots` and `cypress/videos` +- Use Cypress UI for step-by-step debugging + +## Common Issues & Solutions + +### Unit Tests +1. **Async Updates** + ```javascript + // Wrong + fireEvent.click(button) + expect(result).toBe('updated') + + // Correct + await fireEvent.click(button) + await waitFor(() => { + expect(result).toBe('updated') + }) + ``` + +2. **Component Re-renders** + ```javascript + // Wrong + const { rerender } = render() + rerender() + + // Correct + const { rerender } = render() + rerender() + ``` + +### E2E Tests +1. **Race Conditions** + ```javascript + // Wrong + cy.get('.loading').should('not.exist') + cy.get('.content') + + // Correct + cy.get('.loading', { timeout: 10000 }).should('not.exist') + cy.get('.content').should('be.visible') + ``` + +## Contributing +1. Write tests for new features +2. Update tests for modified features +3. Ensure all tests pass locally before pushing +4. Follow the testing standards outlined above +5. Include updated test coverage reports + +## References +- [Vitest Documentation](https://vitest.dev/) +- [Testing Library](https://testing-library.com/docs/react-testing-library/intro/) +- [Cypress](https://docs.cypress.io/app/get-started/why-cypress) + +Feel free to extend this documentation as our testing strategy evolves! diff --git a/docs/developer/08_Guides/country-dashboards.md b/docs/developer/08_Guides/country-dashboards.md new file mode 100644 index 0000000..fae4329 --- /dev/null +++ b/docs/developer/08_Guides/country-dashboards.md @@ -0,0 +1,14 @@ +--- +id: country-dashboards +title: Country Dashboards +sidebar_label: Country Dashboards +sidebar_position: 3 +--- + +# Country Dashboards + +Integration with Country Dashboard + +A new functionality that allows Countries to pull completed Supply Plans for one Program at a time has just been introduced. + +The full documentation for this Integration is available in the following [file](https://github.com/FASP-QAT/fasp-api/blob/a271980e12637d6a31f4d87560df85a88789ee6e/docs/API%20Documentation%20for%20Dashboard%20integration%20v1.31.pdf) \ No newline at end of file diff --git a/docs/developer/08_Guides/flyway.bkp b/docs/developer/08_Guides/flyway.bkp new file mode 100644 index 0000000..e79c28f --- /dev/null +++ b/docs/developer/08_Guides/flyway.bkp @@ -0,0 +1,87 @@ +--- +title: Flyway Database Migration +--- + +# Flyway Database Migration + +Flyway is a database migration tool that helps manage database schema changes in a version-controlled, reliable way. + +## Why We Use It +- Version control for database schemas +- Consistent database state across all environments +- Automated, repeatable migrations +- Tracks migration history + +## How It Works +Flyway looks for migration files in the `db/migration` directory and executes them in version order. + +### Migration File Naming +``` +V1__Description_of_change.sql +│ │ └─ Descriptive text of the change +│ └─── Double underscore separator +└───── Version number (must be a number and must be unique) +``` + +### Repeatable Migrations +Repeatable migrations are used to apply changes to the database schema that do not require a version number. + +``` +R__Description_of_change.sql +│ │ └─ Descriptive text of the change +│ └─── Double underscore separator +└───── Repeatable migration name +``` + +These migrations are executed in the database every time their checksum changes. + +They are useful for applying changes to the database schema that do not require a version number. + +For example, views, stored procedures, etc. + +### Common Commands +- `migrate`: Apply pending migrations +- `clean`: Remove all objects from the schema +- `info`: Show migration status/history +- `validate`: Verify migrations and checksums +- `repair`: Fix migration history table +- `baseline`: Baseline an existing database +- `undo`: Revert most recent migration (Pro edition) + +Commands can be executed using Maven: +```bash +mvn flyway:migrate +mvn flyway:clean +mvn flyway:info +mvn flyway:validate +mvn flyway:repair +mvn flyway:baseline +``` + +Add the database credentials to the above commands. + +E.g. +``` +./mvnw flyway:info -Dflyway.url=jdbc:mysql://localhost:3306/fasp -Dflyway.user=root -Dflyway.password=root +``` + +### Best Practices +1. Never modify an existing migration file +2. Always test migrations before applying to production +3. Use descriptive names for migration files +4. Keep migrations idempotent when possible +5. Add new migration files to the end of the list +6. Do not delete migration files + +### Troubleshooting +Common issues and solutions: +- **Checksum mismatch**: Use `flyway:repair` if you're sure the change is intended +- **Failed migration**: Fix the issue in a new migration, don't modify the failed one +- **Out of order**: Enable `outOfOrder` property if you need to apply an older version +- **Connection issues**: Verify database credentials and network connectivity + + +### Further Reading +- [Flyway Documentation](https://documentation.red-gate.com/fd) +- [Flyway Concepts](https://documentation.red-gate.com/fd/flyway-concepts-271583830.html) +- [Flyway Best Practices](https://documentation.red-gate.com/fd/recommended-practices-150700352.html) diff --git a/docs/developer/08_Guides/intro.md b/docs/developer/08_Guides/intro.md new file mode 100644 index 0000000..c2ec926 --- /dev/null +++ b/docs/developer/08_Guides/intro.md @@ -0,0 +1,10 @@ +--- +id: overview +title: Guides +sidebar_label: Overview +sidebar_position: 1 +--- + +# Guides + +This section provides guides for developers working on the QAT project. Please refer to the individual pages for more information, using the sidebar on the left. diff --git a/docs/developer/08_Guides/r-reports.md b/docs/developer/08_Guides/r-reports.md new file mode 100644 index 0000000..3d81abb --- /dev/null +++ b/docs/developer/08_Guides/r-reports.md @@ -0,0 +1,41 @@ +--- +id: r-reports +title: R Reports +sidebar_label: R Reports +sidebar_position: 2 +--- + +# Running R based reports + +Please follow the below steps to install R application required for running ARIMA based reports. + +```bash +$ sudo apt update +$ sudo apt install libsodium-dev +$ sudo apt-get install libcurl4-openssl-dev +$ sudo apt install r-base +``` + +After installing R application type R in command prompt to launch the console of R application as given below. + +```bash +$ R +``` + +Once you enter the console of R application you need to install Plumber and forecast packages. Given below are the steps. + +```bash +install.packages("plumber") +install.packages("forecast") +``` + +You can run the R application with below command. + +```bash +plumber::plumb(file='/root/Documents/GitRepo/Rprojects/api_arima.r')$run(host="0.0.0.0", port=8000) +``` + +After running R application go to Postman application and enter below line in post column and enter the details. + +[http://server-ipaddress:8000/tes](http://server-ipaddress:8000/tes) + diff --git a/src/css/custom.css b/src/css/custom.css index 1ea3c00..be4820f 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,17 +1,14 @@ -@import url('https://fonts.googleapis.com/css2?family=Poppins:wght@300;400;500;600;700&display=swap'); - /** * Any CSS included here will be global. The classic template * bundles Infima by default. Infima is a CSS framework designed to * work well for content-centric websites. */ +/* You can override the default Infima variables here. +See: https://docusaurus.community/knowledge/design/css/variables/ +*/ :root { - /* Modern Typography */ - --ifm-font-family-base: 'Poppins', sans-serif; - --ifm-heading-font-family: 'Poppins', sans-serif; - - /* Refined Primary color palette */ + /* Primary color palette */ --ifm-color-primary: #002F6C; --ifm-color-primary-dark: #002a61; --ifm-color-primary-darker: #002557; @@ -20,16 +17,17 @@ --ifm-color-primary-lighter: #003981; --ifm-color-primary-lightest: #003e8b; - /* Premium Accent */ + /* Custom red color palette */ --custom-accent: #BA0C2F; - --premium-shadow: 0 4px 12px rgba(0, 0, 0, 0.08); - --glass-bg: rgba(255, 255, 255, 0.85); - --glass-border: rgba(255, 255, 255, 0.2); - - /* Infima Overrides */ - --ifm-code-font-size: 90%; - --ifm-navbar-background-color: var(--glass-bg); - --ifm-footer-background-color: #f8fafc; + --custom-accent-dark: #a70b2a; + --custom-accent-darker: #950a26; + --custom-accent-darkest: #840922; + --custom-accent-light: #cd0d34; + --custom-accent-lighter: #df0e38; + --custom-accent-lightest: #f20f3d; + + /* Colour overrides */ + --ifm-code-font-size: 95%; --ifm-menu-color-active: var(--custom-accent); --ifm-menu-color-background-active: transparent; --ifm-breadcrumb-color-active: var(--custom-accent); @@ -41,58 +39,52 @@ } [data-theme='dark'] { - --ifm-color-primary: #8bb3e6; - --glass-bg: rgba(15, 23, 42, 0.85); - --glass-border: rgba(255, 255, 255, 0.1); - --premium-shadow: 0 4px 12px rgba(0, 0, 0, 0.4); - --ifm-footer-background-color: #0f172a; -} - -/* Glassmorphism for Navbar and Sidebar */ -.navbar { - backdrop-filter: blur(12px); - -webkit-backdrop-filter: blur(12px); - border-bottom: 1px solid var(--glass-border); - box-shadow: var(--premium-shadow); -} - -.theme-doc-sidebar-container { - border-right: 1px solid var(--glass-border); -} - -/* Modern Link Hover States */ + --ifm-color-primary: #A6C5EC; + --ifm-color-primary-dark: #8bb3e6; + --ifm-color-primary-darker: #70a1e0; + --ifm-color-primary-darkest: #558fda; + --ifm-color-primary-light: #c1d7f2; + --ifm-color-primary-lighter: #dce9f8; + --ifm-color-primary-lightest: #f7fbff; + + --custom-accent: #ff1744; + --custom-accent-dark: #f01440; + --custom-accent-darker: #e31236; + --custom-accent-darkest: #d61134; + --custom-accent-light: #ff4569; + --custom-accent-lighter: #ff6b88; + --custom-accent-lightest: #ff97ab; + + --docusaurus-highlighted-code-line-bg: rgba(0, 47, 108, 0.3); +} + +/* add underline to all links and remove from navbar, sidebar and footer */ a { - transition: all 0.2s ease; text-decoration: underline; } - .navbar__inner a, .table-of-contents a, a.menu__link, a.footer__link-item, a.button { text-decoration: none; } -.menu__link { - border-radius: 8px; - margin: 2px 0; - padding: 8px 12px; -} - +/* custom styles for the left sidebar */ .menu__link--active:not(.menu__link--sublist) { - background: linear-gradient(90deg, rgba(186, 12, 47, 0.1) 0%, transparent 100%); - border-left: 4px solid var(--custom-accent) !important; - font-weight: 600; + border-left: 0.25rem solid var(--custom-accent); +} +.menu__list-item .menu__list-item-collapsible a { + text-transform: capitalize; } -/* Premium Admonitions (Callouts) */ -.admonition { - border-radius: 12px; - border-left-width: 6px; - box-shadow: var(--premium-shadow); - padding: 1.25rem; +/* custom styles for the top navbar - add an bottom border to the active link */ +.navbar__link--active{ + border-bottom: 0.25rem solid var(--ifm-color-primary); } -.admonition-icon svg { - width: 20px; - height: 20px; +/* custom styles for HRs */ +.section-divider { + margin: 3rem auto; + width: 100%; + border: none; + border-bottom: .5rem solid #BA0C2F; } .section-divider-footer { margin: 3rem auto; diff --git a/src/pages/index.js b/src/pages/index.js index 4db25f4..3694314 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -9,33 +9,25 @@ import styles from './index.module.css'; function HomepageHeader() { const {siteConfig} = useDocusaurusContext(); return ( -
+
- + Quantification Analytics Tool -

- Modern Country-Led Forecasting & Supply Planning +

+ QAT Documentation Platform

-
-

- Funded by USAID, QAT enables program managers to easily build - multiple forecasts, optimize commodity procurement, and monitor - stock status with advanced analytical capabilities and automated data exchange. +

+ The Quantification Analytics Tool (QAT), is a modernized solution for + country-led forecasting and supply planning. Funded by USAID, QAT + leverages new technologies and enhances the existing tools such as, + PipeLine and Quantimed. With an enhanced user interface and + usability, greater analytical capabilities and automated data + exchange, this new tool enables program managers to easily build + multiple forecasts for comparison and selection, optimize commodity + procurement and delivery schedules, monitor the stock status of + products and share data with external platforms and key stakeholders.

-
- - Get Started - - - Architecture - -
-
); @@ -45,49 +37,100 @@ function ResourceColumns() { const resources = [ { image: "img/home/QAT Overview Cover.png", - heading: "Overview Guide", - description: "Learn how QAT enhances supply planning through advanced analytics and automated data exchange.", + heading: "Overview", + text: <> +

Download this overview to learn how QAT enhances supply planning through its improved + interface, advanced analytics, and automated data exchange.

This two-page document + highlights key features that help program managers optimize procurement, monitor + stock levels, and share data efficiently with stakeholders.

+ , link: "https://www.ghsupplychain.org/sites/default/files/2023-02/QAT_Overview_External.pdf" }, { image: "img/home/QAT User Manual Cover Image.png", heading: "User Manual", - description: "Complete guide for online/offline functionality, scenario planning, and best practices.", + text: <> +

Download the QAT User Manual to learn how to use this supply planning tool.

+

The manual covers: +

    +
  1. Essential background and development information
    2. +
  2. Step-by-step guidance for both online and offline functionality
    3. +
  3. Advanced features including scenario planning and updated planning logic
    4. +
  4. Best practices for master data management and program standardization
    5. +
  5. Instructions for monitoring stock status, optimizing procurement, and sharing data
    6. +

+ , link: "https://www.ghsupplychain.org/sites/default/files/2025-01/QAT%20User%20Manual_2024.12.31.pdf" }, { image: "img/home/QAT Reports Reference Sheet Image.png", - heading: "Reports Reference", - description: "Visual guide to Stock Status, Consumption, and Inventory reports available in QAT.", + heading: "Reports Reference Sheet", + text: <> +

Download the QAT Reports Reference Sheet to learn about the reports available in QAT, + which cover Stock Status, Consumption, Shipment, and Inventory.

The reference sheet + provides visual examples and brief descriptions of each report, including the + Program Catalog and Supply Plan Report. This guide helps users quickly identify + the most appropriate reports for their specific data analysis needs.

+ , link: "https://www.ghsupplychain.org/sites/default/files/2023-11/Reports%20Reference%20Sheet.pdf" } ]; return ( -
-
-
- {resources.map((props, idx) => ( -
-
-
- {props.heading} -
-
- {props.heading} -

{props.description}

- - Download PDF - -
-
+
+
+ {resources.map((resource, index) => ( +
+ + {resource.heading} + + + {resource.heading} + + + Download + +
+ {resource.text}
- ))} -
+
+ ))}
-
+
); } diff --git a/src/pages/index.module.css b/src/pages/index.module.css index 605661b..815450a 100644 --- a/src/pages/index.module.css +++ b/src/pages/index.module.css @@ -1,122 +1,27 @@ -/* Premium UI Styles */ -.heroBanner { - padding: 6rem 0; - background: linear-gradient(135deg, #002F6C 0%, #001A3D 100%); - color: white; - text-align: center; - position: relative; - overflow: hidden; -} - -.heroTitle { - font-family: 'Outfit', sans-serif; - font-size: 4rem; - font-weight: 700; - margin-bottom: 1rem; - background: linear-gradient(to right, #fff, #A6C5EC); - -webkit-background-clip: text; - background-clip: text; - -webkit-text-fill-color: transparent; -} - -.heroSubtitle { - font-size: 1.5rem; - opacity: 0.9; - margin-bottom: 2rem; -} - -.heroDescriptionContainer { - max-width: 800px; - margin: 0 auto; -} +/** + * CSS files with the .module.css suffix will be treated as CSS modules + * and scoped locally. + */ -.heroDescription { - font-size: 1.1rem; - line-height: 1.6; - margin-bottom: 3rem; - opacity: 0.8; -} - -.heroButtons { - display: flex; - gap: 1rem; - justify-content: center; -} - -.features { + .heroBanner { padding: 4rem 0; - background: #f8fafc; -} - -.premiumCard { - background: white; - border-radius: 16px; + text-align: center; + position: relative; overflow: hidden; - box-shadow: 0 4px 20px rgba(0, 0, 0, 0.05); - transition: transform 0.3s ease, box-shadow 0.3s ease; - height: 100%; - display: flex; - flex-direction: column; - border: 1px solid rgba(0, 0, 0, 0.05); } -.premiumCard:hover { - transform: translateY(-8px); - box-shadow: 0 12px 30px rgba(0, 0, 0, 0.1); +@media screen and (max-width: 996px) { + .heroBanner { + padding: 2rem; + } } -.cardHeader { - height: 200px; - background: #f1f5f9; +.buttons { display: flex; align-items: center; justify-content: center; - padding: 1rem; -} - -.cardImage { - max-height: 100%; - width: auto; - filter: drop-shadow(0 4px 8px rgba(0, 0, 0, 0.1)); -} - -.cardBody { - padding: 2rem; - flex-grow: 1; - display: flex; - flex-direction: column; -} - -.cardBody h3 { - font-family: 'Outfit', sans-serif; - margin-bottom: 1rem; - color: #002F6C; -} - -.cardBody p { - font-size: 0.95rem; - color: #64748b; - margin-bottom: 2rem; - line-height: 1.5; -} - -[data-theme='dark'] .features { - background: #0f172a; -} - -[data-theme='dark'] .premiumCard { - background: #1e293b; - border-color: rgba(255, 255, 255, 0.05); -} - -[data-theme='dark'] .cardHeader { - background: #334155; -} - -[data-theme='dark'] .cardBody h3 { - color: #A6C5EC; } -[data-theme='dark'] .cardBody p { - color: #94a3b8; +.dropShadow { + box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1), 0 6px 20px rgba(0, 0, 0, 0.08); } \ No newline at end of file From 5bc40ec4b0d6121f89dba129aa3d36b2ed407d96 Mon Sep 17 00:00:00 2001 From: Juhi Date: Wed, 25 Mar 2026 10:54:06 +0530 Subject: [PATCH 3/3] applied Poppins font globally to the documentation site --- src/css/custom.css | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/src/css/custom.css b/src/css/custom.css index be4820f..51d104d 100644 --- a/src/css/custom.css +++ b/src/css/custom.css @@ -1,14 +1,11 @@ -/** - * Any CSS included here will be global. The classic template - * bundles Infima by default. Infima is a CSS framework designed to - * work well for content-centric websites. - */ +@import url('https://fonts.googleapis.com/css2?family=Poppins:ital,wght@0,100;0,200;0,300;0,400;0,500;0,600;0,700;0,800;0,900;1,100;1,200;1,300;1,400;1,500;1,600;1,700;1,800;1,900&display=swap'); -/* You can override the default Infima variables here. -See: https://docusaurus.community/knowledge/design/css/variables/ -*/ :root { - /* Primary color palette */ + --ifm-font-family-base: 'Poppins', sans-serif; + --ifm-line-height-base: 1.6; + --ifm-font-weight-normal: 400; + --ifm-font-weight-semibold: 600; + --ifm-font-weight-bold: 700; --ifm-color-primary: #002F6C; --ifm-color-primary-dark: #002a61; --ifm-color-primary-darker: #002557;