Admin OPD Item Listing Overview - hmislk/hmis GitHub Wiki

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. 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. 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