# Inward Service and Item Requests (Approval Queue) ## Overview External systems — such as a patient mobile app or a ward request terminal — can send **service requests** (for example Oxygen Charges, ward services) and **stock item requests** (for example Panadol, dressings, consumables) for an admitted patient's BHT. Each request arrives as a **Pending** entry in the receiving department's queue. Nothing is charged to the patient and no stock moves until a department user actually processes the request through the normal billing pages. This gives the department full control over what is actually supplied and billed, and lets a single request be fulfilled gradually across more than one visit. ## When to Use Use the Service/Item Requests queue when: - Your department (ward, ward store, etc.) receives service or stock item requests from an external requesting system - You need to charge a patient's BHT for the requested services and issue the requested stock items - You need to reject lines that cannot be fulfilled, with a reason - You want to check what requests are still waiting to be processed ## How It Works Every request line (each individual item or service on a request) is tracked separately: 1. **Pending** — the line has been received. The patient has **not** been charged and no stock has been deducted for it. 2. **Fulfilled** — a department user processed the line through the normal billing pages (Add Services & Investigations for services/investigations, Direct Issue to BHTs for stock items). The patient's BHT is now charged (and, for stock items, department stock has been deducted). 3. **Rejected** — a department user rejected the line with a reason. No charge, no stock movement. A request as a whole can be **Pending**, **Partially Fulfilled**, **Fulfilled**, **Rejected**, or **Partially Fulfilled and Rejected**, depending on the mix of its lines. A request can be fulfilled across multiple visits — for example, a service line can be billed today and a stock line issued tomorrow, once stock becomes available. > **Important:** Charging only happens when a line is actually processed through Add Services or Direct Issue and that page's own **Settle** button is clicked. A pending or rejected line never affects the patient's bill or your stock. ## How to Use ### Opening the Queue 1. Log in and select the department that receives the requests (for example a ward). The queue only shows requests addressed to your **current login department**. 2. Click **Inward** in the main menu. 3. Click **Service/Item Requests** (clipboard-check icon). 4. The **Pending Item/Service Requests** page opens, showing your department name in the header. > **Note:** The menu item only appears if you hold the processing or rejection privilege — see [Permissions](#permissions-admin) below. ### Reading the Queue ![Pending queue showing a request with both remaining-lines tables and all three action buttons](images/item-request-pending-queue-two-buttons.png) Each row shows one request that still has at least one unfulfilled line: - **Request No** — the request's bill number - **BHT No** and **Patient Name** — the admitted patient the request is for - **Requested At** / **Requested By** — when the request arrived and which user (or API account) submitted it - **Remaining Services/Investigations** — the still-unfulfilled service and investigation lines with quantities - **Remaining Inventory Items** — the still-unfulfilled stock item lines with quantities - **Actions** — up to three buttons, shown only when relevant (see below) Once every line on a request is fulfilled or rejected, the request disappears from the queue entirely. ### Processing Service/Investigation Lines The **Process Services/Investigations** button appears only while the request still has unfulfilled service or investigation lines. 1. Click **Process Services/Investigations** on the row. 2. You are taken to the normal **Add Services & Investigations** page for that patient's BHT, with the requested service/investigation lines already added to the bill at the requested quantities. ![Add Services page immediately after processing a request, showing the pre-loaded line before Settle](images/item-request-add-services-preloaded-cart.png) 3. Review the pre-loaded line(s). Add, remove, or adjust anything as you normally would on this page — it behaves exactly like adding services manually. 4. Click **Settle** as usual. The patient's BHT is charged and a normal bill is created. 5. Return to the queue (**Inpatient** → **Service/Item Requests**). The processed line(s) now show under "None remaining" for that column. ### Processing Inventory Item Lines The **Process Inventory Items** button appears only while the request still has unfulfilled stock item lines. 1. Click **Process Inventory Items** on the row. 2. You are taken to the normal **Direct Issue to BHTs (Native SQL)** page for that patient's BHT, with a suggested (non-expired, earliest-expiry) stock batch already added for each requested item at the requested quantity. ![Direct Issue page immediately after processing a request, showing the pre-loaded stock item before Settle](images/item-request-direct-issue-preloaded-cart.png) 3. Review the pre-loaded item(s) and quantities. If no suitable stock batch was available for a line, that line is simply left out of the cart — it stays in the queue as still remaining, so you can Reject it or wait until stock arrives. 4. Click **Settle** as usual. Stock is deducted and the patient's BHT is charged at the batch's retail sale rate. ![Queue after processing the service line, showing "None remaining" and only the inventory button left](images/item-request-queue-after-services-processed.png) ### Rejecting Remaining Lines The **Reject Remaining Lines** button rejects only the lines that are still pending — any line already fulfilled by a real bill is left untouched. 1. Click **Reject Remaining Lines** on the row. 2. The **Reject Remaining Lines** dialog opens. 3. Type the reason in **Reason for Rejection** — this is mandatory. ![Reject Remaining Lines dialog with the mandatory reason field filled in](images/item-request-reject-remaining-lines-dialog.png) 4. Click **Confirm Reject**, then confirm the browser prompt. 5. The message **"Remaining lines rejected."** appears. Once every line on the request is fulfilled or rejected, the request disappears from the queue. ![Queue empty after all lines on every request have been fulfilled or rejected](images/item-request-queue-empty-after-completion.png) ## Understanding Messages ### Success Messages - **"Remaining lines rejected."** — the still-pending lines were closed with your reason; any already-fulfilled lines and their bills are unaffected. - **"Bill Saved"** (Add Services page) / **"Bill settled successfully."** (Direct Issue page) — the processed line(s) have been charged to the BHT (and stock deducted, for inventory lines). ### Error Messages - **"You do not have privileges to process item/service requests."** — ask your administrator to grant the processing privilege (see below). - **"You do not have privileges to reject item/service requests."** — ask your administrator to grant the rejection privilege (see below). - **"This request belongs to another department's queue."** — you are logged in to a different department than the one the request was sent to. Switch to the correct department and reopen the queue. - **"No remaining service/investigation lines on this request."** / **"No remaining inventory lines on this request."** — every line of that type on the request has already been fulfilled or rejected; the queue refreshes automatically so the corresponding button disappears. - **"Rejection reason is required"** — you clicked Confirm Reject (or the browser alert fired) without typing a reason in the dialog. - **"This request has no remaining lines to reject."** — every line on the request has already been fulfilled or rejected before you clicked Reject. ## Best Practices - **Decide promptly** — patients may be waiting on a service or a stock item. - **Review the pre-loaded cart before settling** — Add Services and Direct Issue behave exactly like manual entry, so you can add, remove, or adjust items before clicking Settle. - **If a stock item doesn't appear pre-loaded**, it usually means no suitable batch was found in your department; receive stock first, or reject that line with a reason. - **Write meaningful rejection reasons** — they explain to the requester (and to anyone reviewing the request later) why a line could not be supplied. - **Log in to the correct department** — you only ever see requests addressed to your current login department. - A request can be worked on in stages — it's fine to process the service line today and come back for the inventory line once stock is available. ## Permissions (Admin) Two privileges control this feature, granted per user per department in the usual privilege management screens: - **Inward Service/Item Request Approval** — user can process (bill/issue) remaining service, investigation, and inventory lines - **Inward Service/Item Request Rejection** — user can reject remaining lines The **Service/Item Requests** menu item is visible only to users holding at least one of these privileges. See [Assigning Privileges to a Role](Admin-Assigning-Privileges-to-a-Role). ## Setup (Admin) Before requests can flow, the requestable items must exist: 1. **Service and investigation items** — create them as inward services or investigations with fees configured, and make sure each has a **category** set (services without a category cannot be added on the Add Services page). A service without a configured fee simply bills at zero until a fee is set up. 2. **Stock items** — create them as normal stock-tracked items and receive stock into the **target department** through the usual GRN flow. Processing an inventory line deducts from that department's stock and charges the batch retail sale rate. 3. **API key** — issue an API key to the external requesting system (Admin → API Key Management). See the [Inward Item Request API](Inward-Item-Request-API) page for the integration details. ## FAQ **Q: Can I process only some lines of a request?** A: Yes — this is the normal way this feature works. Process whichever lines you can fulfill now (services and/or inventory), and reject or leave pending anything you can't handle yet. **Q: Can the requesting system process or reject its own requests?** A: No. Processing and rejection only happen inside HMIS, by a privileged department user, through the normal Add Services and Direct Issue pages. The external system can only submit, view, and cancel its own pending requests. **Q: What if two users try to process the same line at the same time?** A: Each real bill created from a line links back to that specific request line. Once a line is fulfilled by one bill, it no longer shows as remaining, so a second attempt at the same line will not double-charge the patient. **Q: When exactly is the patient charged?** A: Only when a real bill is settled from the Add Services or Direct Issue page — the charge appears against the BHT like any other inward charge and is included in interim/final bills as usual. **Q: Can a rejected line be reconsidered?** A: No. Rejection is final for that line. The requesting system (or the ward) would need to submit a new request for that item. **Q: Where can I see which real bill fulfilled a request line?** A: The external system can see this via `GET /api/itemrequests/{id}` — each fulfilled line reports the bill id and bill type that fulfilled it. There isn't a separate in-app screen for this; the bill itself is a normal Inward or Pharmacy bill, searchable as usual. ## Related Features - [Inward Item Request API](Inward-Item-Request-API) — how external systems submit and track requests - [Inpatient Module](Inward) — module index - [Add Services and Investigations](Add-services-and-Investigations) — the page used to process service/investigation lines