Pharmaceutical Item Management - hmislk/hmis GitHub Wiki
Pharmaceutical Item Management
Overview
Pharmaceutical Item Management allows administrators to maintain the master list of all pharmaceutical, store, and laboratory items used across the system. From this module you can add new items, edit existing records, activate or deactivate items, permanently delete items, and review the full audit history of every change.
All item types (VTMs, ATMs, VMPs, AMPs, VMPPs, and AMPPs) share the same management interface and workflow, so once you learn how to manage one type, the same steps apply to all others.
When to Use
- Add a new medicine, store item, or lab item to the system
- Edit the name, code, or other details of an existing item
- Deactivate an item that is temporarily out of use (it can be reactivated later)
- Reactivate a previously deactivated item
- Permanently delete an item that was entered by mistake
- Review who created, edited, activated, or deactivated an item and when
Navigation
- Click Administration in the main menu
- Select Pharmaceutical Management
- On the left-hand panel, expand one of these sections:
- Pharmaceutical Component Management - for pharmacy medicines
- Store Item Management - for general store items
- Lab Item Management - for laboratory items
- Click the item type you want to manage (e.g. AMPs, VMPs, VTMs, etc.)
Item Types at a Glance
| Abbreviation | Full Name | What It Represents | Example |
|---|---|---|---|
| VTM | Virtual Therapeutic Moiety | A generic drug name | Paracetamol |
| ATM | Actual Therapeutic Moiety | A brand/trade name | Panadol |
| VMP | Virtual Medicinal Product | A generic formulation | Paracetamol 500mg Tablet |
| AMP | Actual Medicinal Product | A specific branded product | Panadol 500mg Tablet |
| VMPP | Virtual Medicinal Product Package | A generic package | Paracetamol 500mg Tablet x 100 |
| AMPP | Actual Medicinal Product Package | A branded package | Panadol 500mg Tablet x 100 |
Three Item Categories
The system manages the same item types across three separate categories. Each category has its own set of VTMs, ATMs, VMPs, AMPs, VMPPs, and AMPPs:
- Pharmaceuticals - medicines dispensed by the pharmacy
- Store Items - consumables and supplies managed by the general store
- Lab Items - reagents and materials used in the laboratory
Common Workflow
Every item management page follows the same layout and workflow described below.
Page Layout
The page is divided into two panels:
- Left panel - status filter, search field, and action buttons
- Right panel - detail form showing the selected item's fields
Filtering by Status
At the top of the left panel, three filter buttons control which items appear in search results:
- Active (green) - show only active items (default)
- Inactive (red) - show only deactivated items
- All (blue) - show all items regardless of status
A label below the buttons confirms the current filter (e.g. "Currently showing: Active items only").
Note: Filter buttons are disabled while you are editing or adding a new item. Save or cancel the current operation first.
Searching for an Item
- Type at least 2 characters in the search field
- A dropdown list appears with matching items
- Each result shows the item name and a status badge (ACTIVE in green or INACTIVE in red)
- Click on the desired item to select it
- The detail form on the right populates with the item's information
Adding a New Item
- Click Add New (green plus button)
- The detail panel switches to "Adding New" mode and all fields become editable
- Fill in the required fields (marked with an asterisk *)
- Click Save to create the item
- A success message appears at the top of the page
Note: While adding a new item, the search field, filter buttons, and other action buttons are disabled. Click Cancel to exit without saving.
Editing an Existing Item
- Search for and select the item you want to edit
- Click Edit Selected (pencil button) - this button is only enabled when an item is selected
- The detail panel switches to "Editing" mode and fields become editable
- Make your changes
- Click Save to apply changes, or Cancel to discard them
Important: You must first select an item before the Edit Selected button becomes active.
Changing Active / Inactive Status
You can deactivate an item to temporarily remove it from dropdowns and transaction screens without permanently deleting it. Deactivated items can be reactivated at any time.
- Search for and select the item
- Click the status toggle button:
- If the item is currently active, the button reads Deactivate (orange/warning)
- If the item is currently inactive, the button reads Activate (green/success)
- A confirmation dialog appears asking you to confirm the action
- Click Yes to proceed or No to cancel
- The item's status badge updates immediately
Tip: Use Inactive filter to find all deactivated items when you need to reactivate one.
Deleting an Item
Deletion is permanent and cannot be undone.
- Search for and select the item
- Click Delete Selected (red trash button)
- A confirmation dialog appears: "Are you sure you want to delete this record?"
- Click Yes to permanently delete or No to cancel
Warning: Deleted items cannot be recovered. If you only need to temporarily remove an item from use, deactivate it instead.
Viewing Audit History
Every action (create, edit, activate, deactivate, delete) is recorded in the audit trail. See Pharmaceutical Audit History for the full guide.
- Search for and select the item
- Click Audit History or History (clock button)
- The audit events page opens showing the complete change log
Fields by Item Type
VTM (Virtual Therapeutic Moiety)
| Field | Required | Description |
|---|---|---|
| Name | Yes | The generic drug name (e.g. Paracetamol) |
| Code | No | An optional identifier code |
| Description | No | Additional details about the VTM |
| Instructions | No | Usage instructions |
ATM (Actual Therapeutic Moiety)
| Field | Required | Description |
|---|---|---|
| Name | Yes | The brand/trade name (e.g. Panadol) |
| Code | No | An optional identifier code |
| Description | No | Additional details |
VMP (Virtual Medicinal Product)
| Field | Required | Description |
|---|---|---|
| Name | Yes | The generic formulation name |
| Generic Name | Yes | Select the parent VTM |
| Dosage Form | Yes | Select the dosage form (e.g. Tablet, Capsule) |
| Category | Yes | Select the pharmaceutical item category |
| Strength | No | Numeric strength value |
| Strength Unit | Yes | Select the unit of strength (e.g. mg, ml) |
| Dose Unit | No | Select the dose measurement unit |
| Dispensing Unit | Yes | Select the unit used when dispensing |
| Description | No | Additional details |
| Instructions | No | Usage instructions |
AMP (Actual Medicinal Product)
| Field | Required | Description |
|---|---|---|
| AMP Name | Yes | The branded product name |
| Code | No | Auto-generated if left blank; click the generate button |
| Barcode | No | Product barcode |
| VMP | Yes | Select the parent VMP |
| Dosage Form | Display only | Inherited from the selected VMP |
| Allow Discounts | No | Whether discounts can be applied |
| Allow Refunds | No | Whether refunds are permitted |
| Consumable | No | Whether this is a consumable item |
| Allow Fractions | No | Whether fractional quantities are allowed |
VMPP (Virtual Medicinal Product Package)
| Field | Required | Description |
|---|---|---|
| Pack Name | Yes | The generic package name |
| Select VMP | Yes | Select the parent VMP |
| Pack Size | Yes | Number of units in the package |
| Pack Unit | Yes | Select the unit of measurement |
| Description | No | Additional details |
| Allow Fractions | No | Whether fractional quantities are allowed |
AMPP (Actual Medicinal Product Package)
| Field | Required | Description |
|---|---|---|
| Pack Name | Yes | The branded package name |
| Select AMP | Yes | Select the parent AMP |
| Pack Size | Yes | Number of units in the package |
| Pack Unit | Yes | Select the unit of measurement |
| Description | No | Additional details |
| Allow Fractions | No | Whether fractional quantities are allowed |
Best Practices
- Deactivate rather than delete - if an item might be needed again, deactivate it instead of deleting
- Use the Active filter for day-to-day work to keep search results clean
- Check audit history before making changes to understand the item's modification history
- Fill in all required fields before saving to avoid validation errors
- Use consistent naming when adding new items to maintain data quality
FAQ
Q: What is the difference between deactivating and deleting an item? A: Deactivating hides the item from transaction screens but preserves the record. You can reactivate it later. Deleting permanently removes the record and cannot be undone.
Q: Can I edit an inactive item without reactivating it first? A: Yes. Switch to the Inactive filter, search for and select the item, then click Edit Selected. You can modify its details while it remains inactive.
Q: Why can't I click the Edit or Delete buttons? A: You must first select an item from the search results. The buttons are disabled until an item is selected. They are also disabled if you are already in edit or add mode.
Q: Does deactivating an item affect existing transactions? A: No. Existing bills, stock records, and other transactions that reference the item are not affected. The item simply stops appearing in new transaction searches and dropdowns.
Q: Are Store Items and Lab Items managed the same way as Pharmaceuticals? A: Yes. The interface and workflow are identical across all three categories. Only the item data is separate.