O3-5373: Add audit trail for bill editing

[Chennamma-Hotkar]

Overview

Implements a comprehensive audit trail system for bill editing operations, providing complete transparency and accountability for all bill modifications in the OpenMRS billing module.

What This Delivers

Key Features

• Full Traceability: Track who, what, and when for every bill change
• Status Change Tracking: Capture before/after values for status transitions
• Compliance Ready: Meet audit requirements for financial transactions
• Minimal Performance Overhead: Seamless integration with existing workflows

Architecture

Clean, layered design following OpenMRS best practices:

• BillAudit – Entity model for audit records
• BillAuditService – Service layer with clean API
• BillAuditDAO – Hibernate-based data access
• BillAuditAction – Type-safe enum (CREATE, UPDATE, STATUS_CHANGE)

Database Schema

bill_audit table with columns:

• bill_id
• action
• changed_by
• changed_date
• previous_status
• new_status
• description

Changes Summary

• New files: 11 (core audit functionality + tests)
• Modified files: 2 (BillServiceImpl.java, moduleApplicationContext.xml)
• Lines added: +1,749
• Test coverage: 7 new tests, all passing

Testing

Test Results

All tests passing: 308/308
Build successful: billing-2.0.0-SNAPSHOT.omod (5.7 MB)
Zero failures, zero errors

Test Coverage

Test Suite	Coverage
BillAuditServiceTest	Service operations
BillAuditDAOTest	Data persistence
BillServiceTest	Integration scenarios

Scenarios Tested

• Audit entry created on bill creation
• Audit entry created on bill updates
• Status change tracking with before/after values
• Query audit history by bill

Usage Example

// Automatic audit logging
Bill bill = billService.getBillByUuid(uuid);
bill.setStatus(BillStatus.PAID);
billService.saveBill(bill);  // Audit entry auto-created

// Query history
List<BillAudit> audits = billAuditService.getAuditsByBill(bill);

Technical Highlights

• SOLID principles with clean separation of concerns
• Spring-managed dependency injection and transaction management
• Hibernate best practices with optimized entity mappings and queries
• Liquibase-based, version-controlled database schema changes
• Backward compatible with no breaking changes

Deployment

• Database migration included (Liquibase)
• Ready for OpenMRS 2.x environments
• No configuration changes required
• Can be deployed without system downtime

Scope Notes

• Audit trail is limited to bill create/update/status change operations
• Historical data prior to deployment is not backfilled

Related Issues

• O3-5373 – Bill Editing with Audit Trail
• O3-5370 – Billing Improvements and Enhancements 2026

---

[wikumChamith]

Can't we use Envers for this?

https://openmrs.atlassian.net/wiki/spaces/docs/pages/113999876/Enabling+Hibernate+Envers+Audit+Logging+in+OpenMRS