Admin OPD Doctor Payment Behaviour - hmislk/hmis GitHub Wiki
Admin — OPD Doctor Payment Behaviour
Several configuration keys control how the OPD doctor payment screens behave, especially around the relationship between shift closure (Mark In / Mark Out) and the ability to settle payments. This article lists each key, explains its effect, and gives recommendations.
For the cashier workflow these keys influence, see OPD Doctor Payments — Per Shift and OPD Doctor Payments — All Due.
The complete key list
Shift-closure requirement
| Key | Type | Default | Effect when true |
|---|---|---|---|
OPD Doctor Payments can be given without closing the shift. |
Boolean | false | Surfaces the Process All Due Payments button on /opd/pay_doctor.xhtml and enables the All-Due workflow (OPD Doctor Payments — All Due). When false, only the per-shift workflow is available. |
The All-Due payment screen (
/opd/professional_payments/payment_staff_bill.xhtml) and the OPD Doctor Payment Index (/opd/opd_doctor_payment_index.xhtml) can also be reached directly from the menu independent of this key, but the legacypay_doctor.xhtmlonly exposes the button when the key is on.
Mark-In / Mark-Out gating
| Key | Type | Default | Effect when true |
|---|---|---|---|
Pay Doctors only After Marking Out |
Boolean | false | The per-shift payment workflow restricts the bill-fee window to bills issued before the Mark Out timestamp. Effectively, a doctor cannot be paid for their shift until they have marked out. |
Pay Doctors only After Marking In |
Boolean | false | The per-shift workflow restricts the window to bills issued on or after the Mark In timestamp. Bills booked earlier in the day, before the doctor marked in, are excluded from the payment. |
These two keys are independent. Setting both true means the payable window is exactly [Mark In, Mark Out]. Setting both false makes the window open-ended.
Refund handling
| Key | Type | Default | Effect when true |
|---|---|---|---|
Remove Refunded Bill From OPD Staff Payment |
Boolean | false | The All-Due payment screen excludes bill fees whose underlying bill item has been refunded. Without this key, refunded bills can still appear in the due-fees grid (because the fee was not itself cancelled), which leads to over-payment if not noticed. |
Recommended: keep this on. The cost is a per-row sub-query that runs while building the due-fees list; the cost in user attention without it is significantly higher.
How the screen experience changes with each key
Default install (all keys false)
- Pay Doctor screen shows only Process Shift Payments.
- Per-shift payment uses the doctor's last Working Time and pays for every OPD bill against that doctor, regardless of when within the day the bill or the shift was timed.
- All-Due workflow is hidden; cashiers cannot batch-pay across multiple shifts.
"Allow All-Due settlement" (the most common production setting)
OPD Doctor Payments can be given without closing the shift.= true- Other keys still false
Now cashiers see both Process Shift Payments and Process All Due Payments. The all-due path is also reachable through the OPD Doctor Payment Index.
Strict per-shift hospital
OPD Doctor Payments can be given without closing the shift.= false (no all-due button)Pay Doctors only After Marking Out= truePay Doctors only After Marking In= true
Cashiers can only pay per shift, and only after the doctor has marked out. The payable bill window is exactly the shift. This is the strictest configuration.
Mid-shift cash advance allowed
Pay Doctors only After Marking Out= falsePay Doctors only After Marking In= trueOPD Doctor Payments can be given without closing the shift.= true
Cashiers can pay a doctor for whichever bills accrued since Mark In, even while the shift is still open. The Mark-In timestamp anchors the start of the window; Mark Out is not required.
Setting the keys
Edit through Administration → Application Configuration (or whichever menu entry maps to the configuration screen in your installation). Type the key exactly as shown above — keys are case- and punctuation-sensitive, including the trailing period on OPD Doctor Payments can be given without closing the shift..
Set the value to true / false (boolean) for the gates and to a numeric value for Withholding Tax Limit and Percentage (covered in Admin — Withholding Tax Configuration).
Verification after changing
- Sign out and back in (some configuration is read at session start, not per-page).
- Open the per-shift payment screen and confirm the All-Due button appears or disappears as expected.
- Mark a test doctor in and out, raise a test OPD bill, and run the payment flow to confirm the bill window matches your intent.
Limitations
- Global scope. These keys cannot vary per institution in the stock installation; the same behaviour applies to every branch.
- No time-of-day cutoff. You cannot configure "doctors can only be paid after 6 pm" or similar. Shift closure is the only signal.
- No grace period. If a doctor marks out at 17:55 and a late-arriving OPD bill is booked at 17:58, that bill falls outside the window. The user must either mark out later or use the all-due workflow.