Stock Management Module Configuration Guide

Location Tags Setup

Required Location Tags

The stock management module requires three specific location tags:

1. Main Store – Primary storage location
2. Main Pharmacy – Main pharmacy location
3. Dispensary – Dispensing location

Step-by-Step Location Tag Creation

1. Create Location Tags

1. Access Admin Interface
   • Go to https://your-domain.com/openmrs
   • Login with admin credentials
   • Navigate to Administration → Manage Location Tags
2. Create Main Store Tag
   • Click Add Location Tag
   • Name: Main Store
   • Description: Primary storage location for stock management
   • Save
3. Create Main Pharmacy Tag
   • Click Add Location Tag
   • Name: Main Pharmacy
   • Description: Main pharmacy location for stock management
   • Save
4. Create Dispensary Tag
   • Click Add Location Tag
   • Name: Dispensary
   • Description: Dispensing location for stock management
   • Save

2. Assign Tags to Locations

1. Navigate to Locations
   • Go to Administration → Manage Locations
2. Tag Main Store Location
   • Edit your primary storage location (e.g., “Laboratory” or “Main Store”)
   • Add the Main Store tag
   • Save
3. Tag Main Pharmacy Location
   • Edit your main pharmacy location
   • Add the Main Pharmacy tag
   • Save
4. Tag Dispensary Location
   • Edit your dispensing location (can be the same as Main Pharmacy)
   • Add the Dispensary tag
   • Save

Important: The same location can have multiple tags. For example, a pharmacy location can have both “Main Pharmacy” and “Dispensary” tags.

Concept Configuration

Required Concept Sets

The stock management module requires four concept sets for proper functionality:

1. Stock Source Type – Types of stock sources
2. Stock Item Category – Categories for stock items
3. Stock Adjustment Reason – Reasons for stock adjustments
4. Stock Take Reason – Reasons for stock takes

Step-by-Step Concept Creation

1. Create Stock Source Type Concept Set

1. Create Main Concept
   • Go to Administration → Manage Concepts
   • Click Add Concept
   • Name: Stock Source Type
   • Description: Types of sources for stock items
   • Concept Class: Misc
   • Data Type: N/A
   • Set: Yes (check this box)
   • Retired: Leave unchecked
   • Save
2. Create Individual Answer Concepts Create these concepts first (as individual concepts, not sets):
   • Purchase
     • Name: Purchase
     • Description: Stock received through purchase
     • Concept Class: Misc
     • Data Type: N/A
     • Set: No
   • Donation
     • Name: Donation
     • Description: Stock received through donation
     • Concept Class: Misc
     • Data Type: N/A
     • Set: No
   • Transfer In
     • Name: Transfer In
     • Description: Stock received through transfer
     • Concept Class: Misc
     • Data Type: N/A
     • Set: No
   • Return
     • Name: Return
     • Description: Stock received through return
     • Concept Class: Misc
     • Data Type: N/A
     • Set: No
   • Other
     • Name: Other
     • Description: Other source types
     • Concept Class: Misc
     • Data Type: N/A
     • Set: No
3. Add Answers to Concept Set
   • Go back to the “Stock Source Type” concept
   • Navigate to the Set Members tab
   • Click Add Set Member
   • Search for and select each answer concept you created
   • Save after adding each member

2. Create Stock Item Category Concept Set

1. Create Main Concept
   • Name: Stock Item Category
   • Description: Categories for classifying stock items
   • Concept Class: Misc
   • Data Type: N/A
   • Set: Yes
   • Retired: Leave unchecked
2. Create Answer Concepts
   • Medications
   • Medical Supplies
   • Laboratory Supplies
   • Surgical Instruments
   • Other
3. Add Set Members
   • Add all answer concepts as set members

3. Create Stock Adjustment Reason Concept Set

1. Create Main Concept
   • Name: Stock Adjustment Reason
   • Description: Reasons for adjusting stock quantities
   • Concept Class: Misc
   • Data Type: N/A
   • Set: Yes
2. Create Answer Concepts
   • Expired Items
   • Damaged Items
   • Theft/Loss
   • Counting Error
   • Quality Control
   • Other
3. Add Set Members
   • Add all answer concepts as set members

4. Create Stock Take Reason Concept Set

1. Create Main Concept
   • Name: Stock Take Reason
   • Description: Reasons for conducting stock takes
   • Concept Class: Misc
   • Data Type: N/A
   • Set: Yes
2. Create Answer Concepts
   • Routine Count
   • Suspected Discrepancy
   • End of Period
   • Audit
   • System Migration
   • **Other`
3. Add Set Members
   • Add all answer concepts as set members

Stock Operation Types

Verification

Stock operation types should be automatically created by the stock management module. Verify they exist:

1. Check Operation Types
   • API call: GET /openmrs/ws/rest/v1/stockmanagement/stockoperationtype?v=default
   • Should return: Adjustment, Disposal, Transfer Out, Receipt, Return, Stock Issue, Requisition, Stock Take, Opening Stock

Required Operation Types

The following operation types should be present:

• Adjustment – Physical quantity adjustments
• Disposal – Item disposal
• Transfer Out – Items transferred to other locations
• Receipt – Items received from external sources
• Return – Items returned to main store
• Stock Issue – Items issued between locations
• Requisition – Stock requests
• Stock Take – Physical inventory counts
• Opening Stock – Initial stock quantities

User Role Configuration

Required Roles

The stock management module expects these specific role UUIDs:

• d210eb66-2188-11ed-9dff-507b9dea1806 – Inventory Clerk
• cca4be4b-2188-11ed-9dff-507b9dea1806 – Inventory Manager
• 84bdd876-4694-11ed-8109-00155dcc3fc0 – Inventory Dispensing
• a49be648-6b0a-11ed-93a2-806d973f13a9 – Inventory Reporting
• 2083fd40-3391-11ed-a667-507b9dea1806 – Inventory Administrator

Creating User Role Scopes

1. Access Stock Management
   • Go to Stock Management → User Role Scopes
2. Create New User Role Scope
   • Click Add User Role Scope
   • Select User: Choose a user with appropriate roles
   • Select Role: Choose from available stock management roles
   • Enable/Disable: Set as needed
   • Permanent: Set if the role is permanent
   • Active Dates: Set if not permanent
   • Stock Operations: Select allowed operation types
   • Locations: Select allowed locations
   • Save

Frontend Configuration

Configuration File

Update frontend/config/config-promedhis.json:

{
  "@openmrs/esm-stock-management-app": {
    "autoPopulateResponsiblePerson": true,
    "dispensingUnitsUUID": "162402AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "enablePrintButton": true,
    "logo": {
      "src": "/openmrs/spa/promed_logo.svg",
      "alt": "Promed MRS",
      "name": "Promed MRS"
    },
    "packingUnitsUUID": "162402AAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
    "printBalanceOnHand": false,
    "printItemCost": false,
    "stockAdjustmentReasonUUID": "YOUR_STOCK_ADJUSTMENT_REASON_UUID",
    "stockItemCategoryUUID": "YOUR_STOCK_ITEM_CATEGORY_UUID",
    "stockSourceTypeUUID": "YOUR_STOCK_SOURCE_TYPE_UUID",
    "stockTakeReasonUUID": "YOUR_STOCK_TAKE_REASON_UUID",
    "useItemCommonNameAsDisplay": true
  }
}

Getting Concept UUIDs

1. Find Concept UUIDs
   • Go to Administration → Manage Concepts
   • Search for each concept set you created
   • Copy the UUID from the concept details page
2. Update Configuration
   • Replace the placeholder UUIDs in the config file
   • Restart the frontend: docker compose restart frontend

Troubleshooting

Common Issues

1. 404 Error for Concepts

Error: Server responded with 404 () for url /openmrs/ws/rest/v1/concept/[UUID]

Solution:

• Verify the concept exists in OpenMRS
• Check the UUID is correct
• Ensure the concept is not retired

2. 500 Error When Saving User Role Scopes

Error: Error Saving user role scope - Server responded with 500

Solution:

• Ensure all three location tags exist: Main Store, Main Pharmacy, Dispensary
• Verify at least one location has each required tag
• Check that stock operation types exist

3. Empty Dropdowns in Stock Management

Error: Dropdowns for source types, categories, etc. are empty

Solution:

• Verify concept sets have been created with answers
• Check that individual answer concepts exist
• Ensure answers are added as set members

4. No Locations Available for User Role Scopes

Error: No locations appear in the location selection

Solution:

• Verify locations are tagged with Main Store, Main Pharmacy, or Dispensary
• Check that the FHIR API is accessible: /openmrs/fhir/Location?_tag=main store,main pharmacy,dispensary

Debugging Steps

1. Check API Endpoints# Check stock operation types curl -u "admin:password" "https://your-domain.com/openmrs/ws/rest/v1/stockmanagement/stockoperationtype?v=default" # Check locations with tags curl -u "admin:password" "https://your-domain.com/openmrs/fhir/Location?_tag=main store,main pharmacy,dispensary" # Check concepts curl -u "admin:password" "https://your-domain.com/openmrs/ws/rest/v1/concept/[UUID]"
2. Check Server Logsdocker logs openmrs-backend --tail 100
3. Verify Database# Connect to database docker exec -it openmrs-db mysql -u openmrs -p[password] openmrs # Check concepts SELECT c.uuid, cn.name FROM concept c JOIN concept_name cn ON c.concept_id = cn.concept_id WHERE cn.name LIKE '%stock%'; # Check location tags SELECT lt.name, l.name as location_name FROM location_tag lt JOIN location_tag_map ltm ON lt.location_tag_id = ltm.location_tag_id JOIN location l ON ltm.location_id = l.location_id;