mcode · smalho01 · Jun 26, 2026
diff --git a/EnvironmentVariables.md b/EnvironmentVariables.md
@@ -4,6 +4,15 @@
 
 <!-- cSpell: off -->
 
+## Local Product Availability defaults
+
+The local Docker topology uses two PIMS pharmacy instances for NCPDP Pharmacy Product Availability testing:
+
+- `Pharmacy123` / PIMS Pharmacy A: frontend `http://localhost:5050`, backend `http://localhost:5051`, NCPDP SCRIPT/PPA endpoint `http://localhost:5051/ncpdp/script`.
+- `Pharmacy456` / PIMS Pharmacy B: frontend `http://localhost:5150`, backend `http://localhost:5151`, NCPDP SCRIPT/PPA endpoint `http://localhost:5151/ncpdp/script`.
+
+Request Generator defaults to direct PPA lookup with locator mode enabled (`VITE_PPA_LOCATOR_MODE=true`). When `VITE_USE_PHARMACY_INTERMEDIARY=true`, NCPDP NewRx and PPA JSON requests both go through `VITE_PHARMACY_INTERMEDIARY`, while the pharmacy table still supplies `Header.To` values for intermediary routing. The default equivalence map searches generic Pexidartinib (`99999-407-20`) when brand Turalio (`65597-407-20`) is unavailable. The selected product NDC is then used for REMS routing, with brand Turalio routed to REMS Admin 1 and generic Pexidartinib routed to REMS Admin 2.
+
 - mcode/rems-setup
 
   - .env
@@ -18,6 +27,12 @@
       - `oauth_token`
     - request-generator
       - `VITE_EHR_SERVER_TO_BE_SENT_TO_REMS_ADMIN_FOR_PREFETCH`
+      - `VITE_PPA_LOCATOR_MODE`
+      - `VITE_PPA_SUBSTITUTION_ALLOWED`
+      - `VITE_PPA_ENDPOINTS`
+      - `VITE_PPA_DEFAULT_STATE`
+      - `VITE_PPA_DEFAULT_POSTAL_CODE`
+      - `VITE_PPA_GENERIC_CANDIDATES`
     - rems-administrator
       - `VSAC_API_KEY`
       - `MONGO_DB_NAME`
@@ -28,7 +43,56 @@
       - `MONGO_INITDB_ROOT_USERNAME`
       - `MONGO_INITDB_ROOT_PASSWORD`
     - pims
+      - `PORT`
+      - `BACKEND_PORT`
+      - `REACT_APP_PIMS_BACKEND_PORT`
+      - `PHARMACY_ID`
+      - `PHARMACY_NAME`
       - `MONGO_URL`
+      - `MONGO_USERNAME`
+      - `MONGO_PASSWORD`
+      - `AUTH_SOURCE`
+      - `EHR_RXFILL_URL`
+      - `EHR_NCPDP_URL`
+      - `INTERMEDIARY_FHIR_URL`
+      - `INTERMEDIARY_URL`
+      - `REMS_ADMIN_FHIR_URL`
+      - `REMS_ADMIN_NCPDP`
+      - `REMS_ADMIN_2_FHIR_URL`
+      - `REMS_ADMIN_2_NCPDP`
+      - `PHARMACY_INVENTORY_JSON`
+    - pims2
+      - `PORT`
+      - `BACKEND_PORT`
+      - `REACT_APP_PIMS_BACKEND_PORT`
+      - `PHARMACY_ID`
+      - `PHARMACY_NAME`
+      - `MONGO_URL`
+      - `MONGO_USERNAME`
+      - `MONGO_PASSWORD`
+      - `AUTH_SOURCE`
+      - `EHR_RXFILL_URL`
+      - `EHR_NCPDP_URL`
+      - `INTERMEDIARY_FHIR_URL`
+      - `INTERMEDIARY_URL`
+      - `REMS_ADMIN_FHIR_URL`
+      - `REMS_ADMIN_NCPDP`
+      - `REMS_ADMIN_2_FHIR_URL`
+      - `REMS_ADMIN_2_NCPDP`
+      - `PHARMACY_INVENTORY_JSON`
+    - rems-directory
+      - `SERVER_HOST`
+      - `SERVER_PORT`
+      - `REMS_ADMIN_1_CDS_URL`
+      - `REMS_ADMIN_1_FHIR_URL`
+      - `REMS_ADMIN_2_CDS_URL`
+      - `REMS_ADMIN_2_FHIR_URL`
+      - `SPL_ZIP_PATH`
+    - rems-intermediary
+      - `EHR_BASE_URL`
+      - `REMS_ADMIN_NCPDP_PATH`
+      - `NCPDP_SCRIPT_FORWARD_URL`
+      - `PPA_PHARMACY_ENDPOINTS`
 
 - mcode/rems-admin
 
@@ -117,14 +181,22 @@
     - `VITE_PASSWORD`
     - `VITE_PATIENT_FHIR_QUERY`
     - `VITE_PIMS_SERVER`
+    - `VITE_USE_PHARMACY_INTERMEDIARY`
+    - `VITE_PHARMACY_INTERMEDIARY`
+    - `VITE_PPA_LOCATOR_MODE`
+    - `VITE_PPA_SUBSTITUTION_ALLOWED`
+    - `VITE_PPA_ENDPOINTS`
+    - `VITE_PPA_DEFAULT_STATE`
+    - `VITE_PPA_DEFAULT_POSTAL_CODE`
+    - `VITE_PPA_GENERIC_CANDIDATES`
     - `VITE_PUBLIC_KEYS`
     - `VITE_REALM`
     - `VITE_RESPONSE_EXPIRATION_DAYS`
     - `VITE_SMART_LAUNCH_URL`
     - `VITE_URL`
     - `VITE_URL_FILTER`
     - `VITE_USER`
-    - `VITE_USE_INTERMEDIARY`
+    - `VITE_USE_PRESCRIBER_INTERMEDIARY`
     - `VITE_INTERMEDIARY`
     - `HTTPS`
     - `HTTPS_CERT_PATH`
@@ -138,19 +210,29 @@
     - `ALLOWED_ORIGIN`
     - `AUTH_SOURCE`
     - `BACKEND_PORT`
+    - `PHARMACY_ID`
+    - `PHARMACY_NAME`
+    - `PHARMACY_INVENTORY_JSON`
     - `EHR_RXFILL_URL`
     - `HTTPS_CERT_PATH`
     - `HTTPS_KEY_PATH`
     - `INTERMEDIARY_FHIR_URL`
+    - `INTERMEDIARY_URL`
     - `MONGO_PASSWORD`
     - `MONGO_URL`
     - `MONGO_USERNAME`
     - `USE_HTTPS`
     - `USE_INTERMEDIARY`
+    - `REMS_ADMIN_FHIR_URL`
     - `REMS_ADMIN_NCPDP`
+    - `REMS_ADMIN_2_FHIR_URL`
+    - `REMS_ADMIN_2_NCPDP`
+    - `EHR_NCPDP_URL`
   - frontend/.env
     - `PORT`
     - `REACT_APP_PIMS_BACKEND_PORT`
+    - `REACT_APP_PIMS_BACKEND_URL`
+    - `VITE_CACHE_DIR`
   - pm2.config.js
     - `NODE_ENV`
 
@@ -173,12 +255,24 @@
     - `VITE_CLIENT`
     - `REMS_ADMIN_HOOK_PATH`
     - `REMS_ADMIN_FHIR_PATH`
+    - `REMS_ADMIN_NCPDP_PATH`
     - `SMART_ENDPOINT`
     - `FRONTEND_VITE_AUTH`
     - `VITE_SCOPE_ID`
     - `DIRECTORY_API_PATH`
     - `DIRECTORY_SPL_PATH`
     - `NCPDP_SCRIPT_FORWARD_URL`
+    - `PPA_PHARMACY_ENDPOINTS`
+
+- mcode/rems-directory
+  - .env
+    - `SERVER_PORT`
+    - `SERVER_HOST`
+    - `SPL_ZIP_PATH`
+    - `REMS_ADMIN_1_CDS_URL`
+    - `REMS_ADMIN_1_FHIR_URL`
+    - `REMS_ADMIN_2_CDS_URL`
+    - `REMS_ADMIN_2_FHIR_URL`
 
 ## Repositories that use environment variables
 
@@ -249,13 +343,22 @@
     - `VITE_LAUNCH_URL`
     - `VITE_PATIENT_FHIR_QUERY`
     - `VITE_PIMS_SERVER`
+    - `VITE_USE_PHARMACY_INTERMEDIARY`
+    - `VITE_PHARMACY_INTERMEDIARY`
+    - `VITE_PPA_LOCATOR_MODE`
+    - `VITE_PPA_SUBSTITUTION_ALLOWED`
+    - `VITE_PPA_ENDPOINTS`
+    - `VITE_PPA_DEFAULT_STATE`
+    - `VITE_PPA_DEFAULT_POSTAL_CODE`
     - `VITE_RESPONSE_EXPIRATION_DAYS`
     - `VITE_CLIENT_SCOPES`
     - `VITE_SMART_LAUNCH_URL`
     - `VITE_URL_FILTER`
     - `VITE_HOOK_TO_SEND`
     - `VITE_URL_FILTER`
     - `VITE_DISABLE_MEDICATION_STATUS`
+  - src/util/ppaProductEquivalents.js
+    - `VITE_PPA_GENERIC_CANDIDATES`
   - src/util/auth.js
     - `VITE_AUTH`
     - `VITE_CLIENT`
@@ -294,12 +397,38 @@
     - `EHR_RXFILL_URL`
     - `USE_INTERMEDIARY`
     - `INTERMEDIARY_FHIR_URL`
+    - `PHARMACY_NAME`
+    - `REMS_ADMIN_NCPDP`
+  - backend/src/lib/ppaInventory.js
+    - `PHARMACY_ID`
+    - `PHARMACY_NAME`
+    - `PHARMACY_INVENTORY_JSON`
+  - backend/src/lib/pharmacyConfig.js
+    - `USE_INTERMEDIARY`
+    - `INTERMEDIARY_URL`
+    - `REMS_ADMIN_NCPDP`
+    - `EHR_NCPDP_URL`
   - backend/src/database/data.js
     - `REMS_ADMIN_FHIR_URL`
+    - `REMS_ADMIN_NCPDP`
+    - `REMS_ADMIN_2_FHIR_URL`
+    - `REMS_ADMIN_2_NCPDP`
   - frontend/src/App.tsx
     - `REACT_APP_PIMS_BACKEND_PORT`
     - `REACT_APP_PIMS_BACKEND_URL`
-    - `REMS_ADMIN_NCPDP`
+  - frontend/vite.config.ts
+    - `PORT`
+    - `VITE_CACHE_DIR`
+
+- mcode/rems-directory
+  - src/server.ts
+    - `SERVER_HOST`
+    - `SERVER_PORT`
+  - src/data.ts
+    - `REMS_ADMIN_1_CDS_URL`
+    - `REMS_ADMIN_1_FHIR_URL`
+    - `REMS_ADMIN_2_CDS_URL`
+    - `REMS_ADMIN_2_FHIR_URL`
 
 - mcode/rems-smart-on-fhir
   - src/views/Patient/MedReqDropDown/MedReqDropDown.tsx
@@ -337,12 +466,14 @@
     - `WHITELIST`
     - `REMS_ADMIN_HOOK_PATH`
     - `REMS_ADMIN_FHIR_PATH`  
+    - `REMS_ADMIN_NCPDP_PATH`
     - `SMART_ENDPOINT`
     - `FRONTEND_VITE_AUTH`
     - `VITE_SCOPE_ID`
     - `DIRECTORY_API_PATH`
     - `DIRECTORY_SPL_PATH`
     - `NCPDP_SCRIPT_FORWARD_URL`
+    - `PPA_PHARMACY_ENDPOINTS`
   - src/server.ts
     - `HTTPS_CERT_PATH`
     - `HTTPS_KEY_PATH`
@@ -351,4 +482,4 @@
     - `VITE_AUTH`
     - `VITE_USER`
     - `VITE_PASSWORD`
-    - `VITE_CLIENT`
+    - `VITE_CLIENT`
diff --git a/REMS.code-workspace b/REMS.code-workspace
@@ -26,6 +26,9 @@
     },
     {
       "path": "../cql-to-fhir-library"
+    },
+    {
+      "path": "../fhir-medication-rems-ig"
     }
   ],
   "launch": {

diff --git a/Verify-REMS-Integration-Prototype-Works.md b/Verify-REMS-Integration-Prototype-Works.md
@@ -37,4 +37,46 @@
 22. Return to the SMART on FHIR App launched in step 17, assume the prescriber role, and click **Check Pharmacy** to view the prescription status.
 23. Repeat step 20 to submit followup/monitoring requests via the **Patient Status Update Form**, on an as need basis. These forms can be submitted multiple times in the prototype, with each submission appearing as a distinct ETASU element.
 
+## Verify Product Availability and Generic REMS Routing
+
+The local Docker topology starts two pharmacy systems:
+
+- PIMS Pharmacy A: <http://localhost:5050>, backend NCPDP endpoint `http://localhost:5051/ncpdp/script`
+- PIMS Pharmacy B: <http://localhost:5150>, backend NCPDP endpoint `http://localhost:5151/ncpdp/script`
+
+The default inventory is configured so brand Turalio (`65597-407-20`) is unavailable at Pharmacy A, while generic Pexidartinib (`99999-407-20`) is available at Pharmacy B. Brand Turalio routes to REMS Admin 1; generic Pexidartinib routes to REMS Admin 2.
+
+1. Start from the EHR UI at <http://localhost:3000> as the prescriber.
+2. If you have used this browser with older settings, click **Settings**, click **Reset Settings**, then click **Save Settings**. This clears stale endpoint settings from browser local storage.
+3. In **Settings**, verify these Product Availability settings:
+   - **Use Product Locator Across Pharmacies** is checked.
+   - **Allow Product Substitution in Availability Lookup** is checked.
+   - **Use Pharmacy Intermediary** is unchecked for the direct-pharmacy test.
+   - The **PPA Pharmacy Endpoints** table has enabled rows for `Pharmacy123` and `Pharmacy456`, and both URL columns use `/ncpdp/script`.
+4. Return to the request screen.
+5. Click **Select a Patient** and choose **John Snow**.
+6. In the medication request dropdown, choose **Turalio 200 MG Oral Capsule**.
+7. Click **Select**.
+8. Click **Check Availability**.
+9. Verify the availability result shows `KA: Pexidartinib Hydrochloride 200 MG Oral Capsule available at PIMS Pharmacy B`.
+10. Verify the result list includes `PIMS Pharmacy A: Turalio 200 MG Oral Capsule - BJ` and `PIMS Pharmacy B: Turalio 200 MG Oral Capsule -> Pexidartinib Hydrochloride 200 MG Oral Capsule - KA`.
+11. Click **Sign Order**. This creates the REMS case for the selected product. If the selected product is generic Pexidartinib, the case should be created at REMS Admin 2.
+12. Click **Send Rx to Pharmacy**.
+13. Open PIMS Pharmacy B at <http://localhost:5150>.
+14. Click **Doctor Orders** and verify the new order appears in Pharmacy B, not Pharmacy A.
+15. Verify the order medication display and NDC are the selected generic Pexidartinib product and its REMS routing/status comes from REMS Admin 2.
+16. Click **View ETASU** and verify the modal shows the selected generic product's REMS requirements instead of a failed GuidanceResponse.
+17. Continue the pharmacist workflow using **Verify ETASU**, **Verify Order**, and **Mark as Picked Up** as needed.
+
+### Optional Intermediary Product Availability Check
+
+1. Return to the EHR UI at <http://localhost:3000>.
+2. Open **Settings**.
+3. Check **Use Pharmacy Intermediary**.
+4. Confirm **Pharmacy Intermediary URL (NCPDP Endpoint)** is `http://localhost:3003/ncpdp/script`.
+5. Click **Save Settings**.
+6. Repeat the direct test steps from selecting John Snow through **Check Availability**.
+7. Verify the same `KA` generic availability result from PIMS Pharmacy B. Request Generator still uses the pharmacy endpoint table to populate `Header.To`, and the intermediary forwards by that value.
+8. Click **Send Rx to Pharmacy** and verify the order still arrives at PIMS Pharmacy B.
+
 Congratulations! The REMS Integration prototype is fully installed and ready for you to use!
-Original file line number
+Diff line change
@@ Expand Up / @@ -26,6 +26,9 @@ @@
         },
         {
           "path": "../cql-to-fhir-library"
+        },
+        {
+          "path": "../fhir-medication-rems-ig"
         }
       ],
       "launch": {
@@ Expand Down @@