# Disposal Return Workflow - Developer Guide ## Overview This guide documents the implementation of the Pharmacy Disposal Issue Return workflow, covering the architecture, workflow states, navigation patterns, and code structure for developers working on this module. ## Workflow Architecture The Disposal Return workflow follows a three-stage approval process similar to the GRN Return workflow: 1. **Create/Save Draft** - User creates return request and can save multiple times 2. **Finalize** - User finalizes the return request (sets `checkedBy`) 3. **Authorize** - Privileged user approves and completes the return (sets `completed`) ### Bill States | State | Field | Condition | Description | |-------|-------|-----------|-------------| | Draft | `checkedBy = null` | Not finalized | User can save and edit | | Finalized | `checkedBy != null` | Not completed | Ready for approval | | Completed | `completed = true` | Approved | Fully processed return | ## Page Structure and Navigation ### Main Pages #### 1. Search Page - `pharmacy_search_issue_bill_for_return.xhtml` **Purpose**: Search and select disposal issue bills to create returns **Location**: `/pharmacy/pharmacy_search_issue_bill_for_return.xhtml` **Key Features**: - Search disposal issue bills by date range - Display bill status (Available, Partially Returned, Fully Returned) - Prevents creating returns for fully returned bills - Navigation action: `issueReturnController.navigateToReturnDisposalIssueBill(bill)` **Privilege Required**: `CreateDisposalReturn` #### 2. Return Processing Page - `pharmacy_bill_return_issue.xhtml` **Purpose**: Unified page for creating, finalizing, and authorizing returns **Location**: `/pharmacy/pharmacy_bill_return_issue.xhtml` **Modes**: - **Edit Mode** (`printPreview = false`): Show data table with editable items - **Print Preview Mode** (`printPreview = true`): Show receipt for printing **Action Buttons**: ```xhtml ``` **Privilege Required**: - `CreateDisposalReturn` - For creating and saving - `FinalizeDisposalReturn` - For finalizing - `ApproveDisposalReturn` - For authorizing #### 3. Finalize List Page - `pharmacy_disposal_return_finalize.xhtml` **Purpose**: List disposal returns that need finalization **Location**: `/pharmacy/pharmacy_disposal_return_finalize.xhtml` **Query Logic**: ```java // Find bills that are NOT finalized (checked = false or null) WHERE b.checked = false OR b.checked IS NULL ``` **Navigation**: `disposalReturnWorkflowController.navigateToProcessDisposalReturn(bill)` **Privilege Required**: `FinalizeDisposalReturn` #### 4. Approve List Page - `pharmacy_disposal_return_approve.xhtml` **Purpose**: List disposal returns that need approval **Location**: `/pharmacy/pharmacy_disposal_return_approve.xhtml` **Query Logic**: ```java // Find bills that are finalized but NOT completed WHERE b.checked = true AND (b.completed = false OR b.completed IS NULL) ``` **Navigation**: `disposalReturnWorkflowController.navigateToProcessDisposalReturn(bill)` **Privilege Required**: `ApproveDisposalReturn` #### 5. Completed Returns Page - `pharmacy_disposal_return_completed.xhtml` **Purpose**: List completed disposal returns with print functionality **Location**: `/pharmacy/pharmacy_disposal_return_completed.xhtml` **Query Logic**: ```java // Find bills that are completed WHERE b.completed = true ORDER BY b.completedAt DESC ``` **Navigation**: `disposalReturnWorkflowController.navigateToPrintCompletedDisposalReturn(bill)` **Privilege Required**: `ViewDisposalReturn` ## Controller Architecture ### IssueReturnController **Scope**: `@SessionScoped` **Key Methods**: #### saveDisposalIssueReturnBill() ```java public void saveDisposalIssueReturnBill() { // Validate return quantities if (!validateReturnQuantities()) { return; } saveBill(); // Save bill entity saveBillComponents(); // Save bill items JsfUtil.addSuccessMessage("Saved"); } ``` #### finalizeDisposalIssueReturnBill() ```java public void finalizeDisposalIssueReturnBill() { // Validate and save first if (!validateReturnQuantities()) { return; } saveDisposalIssueReturnBill(); // Mark as finalized getReturnBill().setEditedAt(new Date()); getReturnBill().setEditor(sessionController.getLoggedUser()); getReturnBill().setChecked(true); getReturnBill().setCheckeAt(new Date()); getReturnBill().setCheckedBy(sessionController.getLoggedUser()); getBillFacade().edit(getReturnBill()); printPreview = true; // Switch to print preview mode JsfUtil.addSuccessMessage("Finalized"); } ``` #### settleDisposalIssueReturnBill() ```java public void settleDisposalIssueReturnBill() { // Validate bill is finalized if (getReturnBill().getCheckedBy() == null) { JsfUtil.addErrorMessage("Please Finalize Bill First. Cannot Return"); return; } // Validate quantities if (!hasQtyToReturn(returnBillItems)) { JsfUtil.addErrorMessage("Return Quantity is Zero. Cannot Return"); return; } if (!validateReturnQuantities()) { return; } // Save as completed calculateBillTotal(); saveSettlingBill(); // Sets completed = true saveSettlingBillComponents(); // Update references getReturnBill().setReferenceBill(getOriginalBill()); getBillFacade().edit(getReturnBill()); getOriginalBill().setRefundedBill(getReturnBill()); getOriginalBill().setRefunded(true); getOriginalBill().getRefundBills().add(getReturnBill()); getBillFacade().edit(getOriginalBill()); printPreview = true; JsfUtil.addSuccessMessage("Successfully Returned"); } ``` **Key Properties**: ```java private Bill originalBill; // The original disposal issue bill private Bill returnBill; // The return bill being created private List returnBillItems; private boolean printPreview; // Toggle between edit/print mode ``` ### DisposalReturnWorkflowController **Scope**: `@SessionScoped` **Key Methods**: #### fillDisposalReturnsToFinalize() ```java public void fillDisposalReturnsToFinalize() { Map params = new HashMap<>(); String jpql = "SELECT b FROM Bill b " + "WHERE b.retired = :retired " + "AND b.billTypeAtomic = :billTypeAtomic " + "AND b.department = :department " + "AND (b.checked = :checked OR b.checked IS NULL) " + "AND (b.cancelled = :cancelled OR b.cancelled IS NULL) " + "ORDER BY b.createdAt DESC"; params.put("retired", false); params.put("billTypeAtomic", BillTypeAtomic.PHARMACY_DISPOSAL_ISSUE_RETURN); params.put("department", sessionController.getDepartment()); params.put("checked", false); params.put("cancelled", false); disposalReturnsToFinalize = billFacade.findByJpql(jpql, params); } ``` #### fillDisposalReturnsToApprove() ```java public void fillDisposalReturnsToApprove() { Map params = new HashMap<>(); String jpql = "SELECT b FROM Bill b " + "WHERE b.retired = :retired " + "AND b.billTypeAtomic = :billTypeAtomic " + "AND b.department = :department " + "AND b.checked = :checked " + "AND (b.cancelled = :cancelled OR b.cancelled IS NULL) " + "AND (b.completed = :completed OR b.completed IS NULL) " + "ORDER BY b.checkeAt DESC"; params.put("retired", false); params.put("billTypeAtomic", BillTypeAtomic.PHARMACY_DISPOSAL_ISSUE_RETURN); params.put("department", sessionController.getDepartment()); params.put("checked", true); params.put("cancelled", false); params.put("completed", false); disposalReturnsToApprove = billFacade.findByJpql(jpql, params); } ``` #### fillCompletedDisposalReturns() ```java public void fillCompletedDisposalReturns() { Map params = new HashMap<>(); String jpql = "SELECT b FROM Bill b " + "WHERE b.retired = :retired " + "AND b.billTypeAtomic = :billTypeAtomic " + "AND b.department = :department " + "AND b.completed = :completed " + "AND (b.cancelled = :cancelled OR b.cancelled IS NULL) " + "ORDER BY b.completedAt DESC"; params.put("retired", false); params.put("billTypeAtomic", BillTypeAtomic.PHARMACY_DISPOSAL_ISSUE_RETURN); params.put("department", sessionController.getDepartment()); params.put("completed", true); params.put("cancelled", false); completedDisposalReturns = billFacade.findByJpql(jpql, params); } ``` #### navigateToProcessDisposalReturn() ```java public String navigateToProcessDisposalReturn(Bill disposalReturnBill) { if (disposalReturnBill == null || disposalReturnBill.getReferenceBill() == null) { JsfUtil.addErrorMessage("No disposal return bill selected"); return null; } // Reload bills to get fresh data Bill returnBill = billService.reloadBill(disposalReturnBill); Bill originalBill = billService.reloadBill(disposalReturnBill.getReferenceBill()); // Set in IssueReturnController issueReturnController.setReturnBill(returnBill); issueReturnController.setOriginalBill(originalBill); issueReturnController.setReturnBillItems(returnBill.getBillItems()); issueReturnController.setOriginalBillItems(originalBill.getBillItems()); // Navigate to processing page return "/pharmacy/pharmacy_bill_return_issue?faces-redirect=true"; } ``` #### navigateToPrintCompletedDisposalReturn() ```java public String navigateToPrintCompletedDisposalReturn(Bill completedReturnBill) { if (completedReturnBill == null || completedReturnBill.getReferenceBill() == null) { JsfUtil.addErrorMessage("No disposal return bill selected"); return null; } // Reload bills Bill returnBill = billService.reloadBill(completedReturnBill); Bill originalBill = billService.reloadBill(completedReturnBill.getReferenceBill()); // Set in IssueReturnController issueReturnController.setReturnBill(returnBill); issueReturnController.setOriginalBill(originalBill); issueReturnController.setReturnBillItems(returnBill.getBillItems()); issueReturnController.setOriginalBillItems(originalBill.getBillItems()); // Enable print preview mode issueReturnController.setPrintPreview(true); // Navigate to print preview return "/pharmacy/pharmacy_bill_return_issue?faces-redirect=true"; } ``` ## Navigation Buttons Pattern All workflow pages include consistent navigation buttons in the header: ```xhtml ``` ## Database Schema ### Key Fields | Field | Type | Purpose | |-------|------|---------| | `billTypeAtomic` | Enum | `PHARMACY_DISPOSAL_ISSUE_RETURN` | | `referenceBill` | Bill | Original disposal issue bill | | `checked` | Boolean | Finalized flag | | `checkedBy` | WebUser | User who finalized | | `checkeAt` | Date | Finalization timestamp | | `completed` | Boolean | Approved/completed flag | | `completedBy` | WebUser | User who approved | | `completedAt` | Date | Approval timestamp | | `cancelled` | Boolean | Cancellation flag (not used for returns) | | `billClosed` | Boolean | Closed/abandoned flag | | `retired` | Boolean | Soft delete flag | ## Close/Abandon Return Functionality Users can close (abandon) a pending return to create a new one for the same disposal issue bill. ### Close Method **Method**: `closeDisposalReturn(Bill returnBillToClose)` **Location**: `DisposalReturnWorkflowController.java:314` ```java public void closeDisposalReturn(Bill returnBillToClose) { // Validate bill can be closed if (returnBillToClose.isCompleted()) { JsfUtil.addErrorMessage("Cannot close a completed disposal return"); return; } if (returnBillToClose.isBillClosed()) { JsfUtil.addErrorMessage("This disposal return is already closed"); return; } // Mark as closed returnBillToClose.setBillClosed(true); billFacade.edit(returnBillToClose); // Refresh lists fillDisposalReturnsToFinalize(); fillDisposalReturnsToApprove(); JsfUtil.addSuccessMessage("Disposal return closed successfully..."); } ``` ### Updated Validation Query The `hasPendingDisposalReturnForSpecificBill()` method excludes closed bills: ```java String jpql = "SELECT COUNT(b) FROM Bill b " + "WHERE b.retired = :retired " + "AND b.billTypeAtomic = :billTypeAtomic " + "AND b.department = :department " + "AND b.referenceBill = :referenceBill " + "AND (b.cancelled = :cancelled OR b.cancelled IS NULL) " + "AND (b.billClosed = :closed OR b.billClosed IS NULL) " // Exclude closed + "AND (b.completed = :completed OR b.completed IS NULL) "; params.put("closed", false); ``` ### UI Implementation **Close Button Pattern**: - **Style**: `ui-button-danger ui-button-outlined` (red outlined) - **Icon**: `fas fa-times` (X icon) - **Confirmation**: Always require confirmation - **Width**: `min-width: 70px` **Finalize Page** (`pharmacy_disposal_return_finalize.xhtml:224`): ```xhtml ``` **Approve Page** (`pharmacy_disposal_return_approve.xhtml:226`): ```xhtml ``` **Status Badge**: ```xhtml Closed ``` ### Close vs Cancel **Why `billClosed` instead of `cancelled`?** | Aspect | `cancelled` | `billClosed` | |--------|------------|--------------| | **Purpose** | Cancel actual transactions | Abandon pending requests | | **Complexity** | Creates `CancelledBill` object | Simple boolean flag | | **Semantics** | Permanent cancellation | Temporary abandonment | | **Stock Impact** | May reverse stock movements | No stock impact (not yet completed) | | **Use Case** | Approved/completed bills | Draft/pending returns | ### Workflow States with Close | State | Field Values | Can Close? | Close Button Location | |-------|--------------|------------|---------------------| | **Draft** | `checkedBy = null` | ✅ Yes | Finalize page | | **Finalized** | `checkedBy != null`, `completed = null` | ✅ Yes | Approve page | | **Completed** | `completed = true` | ❌ No | N/A | | **Closed** | `billClosed = true` | ❌ No | N/A (already closed) | **Close Button Rendering Logic**: - **Finalize Page**: Show when `billClosed ne true AND checkedBy eq null` (draft only) - **Approve Page**: Show when `billClosed ne true AND completed ne true AND checkedBy ne null` (finalized only) ## Validation Logic ### Return Quantity Validation ```java public boolean validateReturnQuantities() { if (returnBillItems == null || returnBillItems.isEmpty()) { JsfUtil.addErrorMessage("No items found to return"); return false; } for (BillItem returnItem : returnBillItems) { if (returnItem == null || returnItem.getReferanceBillItem() == null) { continue; } double requestedReturnQty = returnItem.getQty(); if (requestedReturnQty <= 0) { continue; // Skip zero quantities } // Validate against original issued quantity and previous returns if (!validateItemReturnQuantity(returnItem)) { return false; } } return true; } ``` ### Preventing Duplicate Returns ```java public boolean hasPendingDisposalReturnForSpecificBill(Bill disposalIssueBill) { String jpql = "SELECT COUNT(b) FROM Bill b " + "WHERE b.retired = :retired " + "AND b.billTypeAtomic = :billTypeAtomic " + "AND b.department = :department " + "AND b.referenceBill = :referenceBill " + "AND b.checked = :checked " + "AND (b.cancelled = :cancelled OR b.cancelled IS NULL) " + "AND (b.completed = :completed OR b.completed IS NULL)"; // ... parameters Long count = billFacade.countByJpql(jpql, params); return count != null && count > 0; } ``` ## Privileges | Privilege | Purpose | Required For | |-----------|---------|--------------| | `CreateDisposalReturn` | Create and save returns | Search page, Save Draft, Finalize | | `FinalizeDisposalReturn` | Finalize returns | Finalize list page | | `ApproveDisposalReturn` | Approve/authorize returns | Approve list page, Authorize button | | `ViewDisposalReturn` | View completed returns | Completed returns page | ## Print Templates The system supports multiple print formats configured via `ConfigOptionController`: 1. **A4 Paper** - `disposal_issue_return` composite component 2. **Custom Format 1** - `disposal_issue_return_custom_1` composite component 3. **Custom Format 2** - `disposal_issue_return_custom_2` composite component Print format selection via Settings dialog (privilege: `ChangeReceiptPrintingPaperTypes`). ## File Locations ### XHTML Pages - `/pharmacy/pharmacy_search_issue_bill_for_return.xhtml` - `/pharmacy/pharmacy_bill_return_issue.xhtml` - `/pharmacy/pharmacy_disposal_return_finalize.xhtml` - `/pharmacy/pharmacy_disposal_return_approve.xhtml` - `/pharmacy/pharmacy_disposal_return_completed.xhtml` ### Java Controllers - `com.divudi.bean.pharmacy.IssueReturnController` - `com.divudi.bean.pharmacy.DisposalReturnWorkflowController` ### Composite Components - `/resources/pharmacy/disposal_issue_return.xhtml` - `/resources/pharmacy/disposal_issue_return_custom_1.xhtml` - `/resources/pharmacy/disposal_issue_return_custom_2.xhtml` ## Workflow Diagram ``` ┌─────────────────────────────────────────────────────────────────┐ │ Disposal Return Workflow │ └─────────────────────────────────────────────────────────────────┘ 1. SELECT DISPOSAL ISSUE BILL pharmacy_search_issue_bill_for_return.xhtml ↓ issueReturnController.navigateToReturnDisposalIssueBill(bill) ↓ 2. CREATE/EDIT RETURN pharmacy_bill_return_issue.xhtml (Edit Mode) ├─ Save Draft → saveDisposalIssueReturnBill() │ (checked = null) │ └─ Finalize → finalizeDisposalIssueReturnBill() (checked = true, checkedBy = user, printPreview = true) ↓ 3. FINALIZE WORKFLOW pharmacy_disposal_return_finalize.xhtml ├─ Lists: checked = false OR null └─ Edit → navigateToProcessDisposalReturn(bill) → Returns to Step 2 ↓ 4. APPROVE WORKFLOW pharmacy_disposal_return_approve.xhtml ├─ Lists: checked = true AND completed = false/null └─ Approve → navigateToProcessDisposalReturn(bill) → pharmacy_bill_return_issue.xhtml → settleDisposalIssueReturnBill() (completed = true, completedBy = user) ↓ 5. COMPLETED RETURNS pharmacy_disposal_return_completed.xhtml ├─ Lists: completed = true └─ Print → navigateToPrintCompletedDisposalReturn(bill) → pharmacy_bill_return_issue.xhtml (Print Preview Mode) ``` ## Best Practices ### For Developers 1. **Always reload bills** before processing to ensure fresh data ```java Bill returnBill = billService.reloadBill(disposalReturnBill); ``` 2. **Validate before state transitions** - Check `checkedBy` before allowing approval - Validate quantities before save/finalize/authorize 3. **Use consistent navigation** - All pages should have same navigation buttons - Privilege-based rendering for buttons 4. **State management** - Use `printPreview` flag to toggle modes - Clear state when navigating away 5. **JPQL queries** - Always filter by department - Check `retired = false` and `cancelled = false` - Use appropriate NULL checks for state fields ### Common Pitfalls 1. **Not checking for pending returns** ```java // ALWAYS check before creating new return if (disposalReturnWorkflowController.hasPendingDisposalReturnForSpecificBill(bill)) { // Error: Pending return exists } ``` 2. **Incorrect state queries** ```java // WRONG: Only checks false WHERE b.checked = false // CORRECT: Checks both false and null WHERE (b.checked = false OR b.checked IS NULL) ``` 3. **Not setting print preview mode** ```java // After finalize/authorize, set print preview printPreview = true; ``` ## Testing Checklist - [ ] Create new disposal return from search page - [ ] Save draft multiple times - [ ] Validate quantity restrictions - [ ] Finalize return request - [ ] View in finalize list - [ ] Edit finalized return (should navigate to view mode) - [ ] Approve return from approve list - [ ] Verify completed flag set - [ ] View completed return in completed list - [ ] Print completed return - [ ] Test all navigation buttons - [ ] Verify privilege-based access control - [ ] Test with fully returned bills (should prevent new returns) - [ ] Test with pending returns (should prevent duplicate returns) ## Related Documentation - [GRN Return Workflow](Pharmacy-Procurement-GRN-Returns) - Similar pattern - [Privilege System](https://github.com/hmislk/hmis/blob/development/developer_docs/security/privilege-system.md) ## Change Log | Date | Version | Changes | |------|---------|---------| | 2025-01-03 | 1.0 | Initial documentation - Disposal return workflow implementation with navigation buttons and completed returns page | --- **Maintained By**: Development Team **Last Updated**: January 3, 2025