# How OPD Item Listing Works — Overview ## Overview When a cashier opens a new OPD bill, the system determines which services to show in the item selection list. This is one of the most important — and most configurable — aspects of HMIS. Getting it right means cashiers see exactly the services they should bill, and nothing else. This article explains every mode of item listing and how they interact. ## The Core Question: Which Items Does a Department See? The answer depends on how items have been mapped. HMIS supports five listing modes, from most restrictive to most open: --- ### Mode 1: Department-Mapped Items Only **What happens:** Only items explicitly mapped to the billing department appear. **When to use:** A specialty department (e.g. Radiology, Cardiology) should only bill its own services. You want precise control over what each counter can bill. **How to configure:** Use [Mapping Items to a Department](Admin-Mapping-Items-to-Department). Create `ItemMapping` records linking specific items to the department. --- ### Mode 2: Institution-Mapped Items Only **What happens:** All items mapped to the institution appear, regardless of department. **When to use:** A general OPD counter should see all services available at the hospital, not limited to one department. **How to configure:** Use [Mapping Items to an Institution](Admin-Mapping-Items-to-Institution). Create `ItemMapping` records linking items to the institution (without a department restriction). --- ### Mode 3: Institution + Department Mapped Items **What happens:** Items shown are those mapped to the institution AND additionally filtered by department mapping. **When to use:** The institution has a set of "approved" services, and individual departments pick from that set. **How to configure:** First map to the institution, then map subsets to departments. The billing engine checks both. --- ### Mode 4: Items Owned by the Department **What happens:** Items whose `department` field on the service record itself is set to the billing department appear. **When to use:** Services "belong" to a department at the point of creation. Useful when items are not mapped through the mapping screens but are directly attributed to departments. **How to configure:** When creating an OPD service, set the **Department** field on the service record to the billing department. --- ### Mode 5: All Active Items (No Restriction) **What happens:** All active, non-retired items appear regardless of institution or department. **When to use:** Small deployments or test environments with no need for department filtering. Not recommended for multi-department hospitals. **How to configure:** Leave items unmapped and unattributed to any specific department. --- ## Fee Mapping and How Fees Are Resolved Once the billing system has determined which items to show, it needs to determine the *price* for each item. The fee resolution order is: 1. **Department fee** — is there a fee configured specifically for this department? Use it. 2. **Site fee** — is there a fee configured for the physical site this department belongs to? Use it. 3. **Base fee** — fall back to the default global fee for the item. This means you can set one base price for a service and override it selectively for specific departments or sites without duplicating the service record. ## Practical Setup Sequence For a typical hospital setup: 1. Create service records (**OPD Services**) 2. Map services to the institution (**Manage Institution Item Mappings**) 3. Map subsets to specific departments (**Manage Department Item Mappings**) 4. Set base fees (**Manage Pricing → Base Fees**) 5. Override fees for departments that charge differently (**Manage Pricing → Department Fees**) ## Checking What a Department Can Currently See Use **Item Counts by Department** from the item management index to audit how many items are currently mapped to each department. ## Technical Notes (Admin/Developer) Item visibility during billing is resolved by `ItemApplicationController` using `ItemMapping` records. The JPQL query joins `Item` with `ItemMapping` on both institution and department conditions. An item without any `ItemMapping` records is either shown to everyone (no restriction) or invisible depending on the billing module's query mode. The `retired` and `inactive` flags both exclude items: `retired = true` means permanently deleted; `inactive = true` means temporarily disabled. Fee resolution uses `FeeController`/`ItemFeeController` — the hierarchy checks `Department` fee first, then `Site` fee, then the base `Fee` record. ## Related Features - [Mapping Items to an Institution](Admin-Mapping-Items-to-Institution) - [Mapping Items to a Department](Admin-Mapping-Items-to-Department) - [Default Service Departments](Admin-Default-Service-Departments) - [Fee Configuration Overview](Admin-Fee-Configuration-Overview) - [Department-Level Fees](Admin-Department-Level-Fees) - [Site-Level Fees](Admin-Site-Level-Fees)