/
Improved Audit Logging

Improved Audit Logging

Overview

With OpenMRS 2.7.0, Hibernate Envers was integrated to provide audit logging, enabling detailed tracking of database changes. However, there is currently no built-in way for admin users to view or manage these logs easily. This project aims to develop a backend module to facilitate audit log management, making it more accessible and useful within OpenMRS.

https://youtu.be/LtjJ2AHLEpE

Key Features

  • Audit Reads on Selected Tables – Hibernate Envers does not support auditing table reads. We need to implement a system that integrates with Envers to track read operations on selected tables. This could leverage Hibernate Event Listeners, but alternative approaches are welcome.

  • Audit Log Viewer – Retrieve and display audit logs for database tables (legacy-ui).

    • Change Log: Log of changes made, by who

  • Filtering Options – Allow users to filter logs by:

    • User (who made the changes)

    • Date/Time (when the changes occurred)

    • Entity/Field (what was changed)

  • REST Endpoints – Expose APIs to allow external systems to access audit data.

Expectations for Contributors

Your report should include the following:

  • Legacy UI Designs – Ensure compatibility with OpenMRS’s legacy interface and provide mockups or wireframes.

  • Detailed Solution Architecture – Define the system’s structure, including:

    • Database schema

    • API design

    • Module integration

  • Feature Implementation Plan – Explain how you plan to implement each feature in the project.

  • Potential System Improvements – Suggest any updates or enhancements that could be made to improve the system further.

Skills You Will Use

  • Java, Hibernate, and Spring – Backend development expertise.

  • JSP & UI Design – Basic UI skills for designing the audit log viewer.

  • OpenMRS Backend Development – Understanding of OpenMRS modules and architecture.

  • Interest in Healthcare IT – Passion for improving open-source medical record systems.

This project will provide valuable experience in enterprise-level auditing, modular backend development, and healthcare information technology while contributing to OpenMRS’s long-term sustainability.

Example Requirements

These requirements are from one government’s list of audit-trail requirements for a nationally-approved EMR:

  • provide an audit trail of all access and modifications to the medical record.

    • (Top Priority) e.g. Clinical Docs: The system shall maintain an audit trail of all entries, modifications, and deletions in the clinical documentation, including the date, time, and identity of the user who made the change

    • e.g. Prescriptions: The system shall maintain an audit trail of all prescription activities, including the creation, modification, and deletion of prescriptions, with a timestamp and the user's identification

    • e.g. Referrals: The system shall maintain an audit trail of all referral activities, including the creation, modification, and deletion of referrals, with a timestamp and the user's identification.

    • (Possibly out of scope here; confirm w/ Mentor) e.g. Data Exchange: The system shall maintain an audit trail of all data transmissions, including the source, destination, date, time, and user, to support data integrity and accountability.

    • (Out of Scope here) e.g. CDS: The system shall maintain an audit trail of all decision support activities, including the use of alerts, guidelines, and other tools, with a timestamp and the user's identification.

  • Note: The most important one to get right first is the Clinical Docs, followed by Prescriptions. CDS is out of scope for this project.

Major Milestones
week 1 - 2:

  1. Audited Entity Discovery: Implemented logic using Java Reflection to identify all @Audited entities within the OpenMRS org.openmrs package. These are cached and made selectable via the UI.

  2. Audit Log Retrieval Service: Developed a service layer that integrates with Hibernate Envers to fetch revision history for any audited entity, including metadata like the user, timestamp, and operation type.

  3. Initial Audit Log Viewer: Added a basic JSP-based admin interface to select entities and display audit logs from Envers.

  4. Unit Tests Added: Core logic (audited entity detection and revision retrieval) is now covered with unit tests using JUnit and Mockito.

week 3 - 4:

  1. Enhanced audit log details to clearly show who made changes, what was changed, and when/how it happened.

  2. Refined the UI design for improved readability and a smoother user experience.

  3. Handled edge cases like missing fields gracefully.

  4. Refactored controllers by moving business logic into services for cleaner architecture.

  5. Replaced hardcoded paths and added license headers to meet OpenMRS coding standards.

  6. Introduced sorting of audit log entries (newest first).

  7. Implemented pagination at the backend for efficient data handling and better frontend performance.

  8. Started refactoring the DAO layer to remove service-level calls, improving separation of concerns and enabling better unit testing.

  9. Shared progress during the OpenMRS Platform Team call and received useful feedback.

What’s Coming Next

  1. Add filtering support (by user, date/time).

  2. Improve the audit detail view to highlight changed fields.

  3. Begin work on RESTful endpoints for programmatic access.

  4. Prepare for midterm evaluation by refining documentation and test coverage.

Useful Links

  1. GitHub Repository: https://github.com/openmrs/openmrs-module-auditlogweb

  2. JIRA Board: https://openmrs.atlassian.net/jira/software/c/projects/AUDIT/summary

  3. Progress Discussion Thread: Talk

🙌 Acknowledgements

Thanks to my mentors @Wikum Weerakutti and @Manoj Rathnapriya and everyone within the community for their support and encouragement on getting ‘OpenMRS Audit Logging’ project come alive.

References

https://openmrs.atlassian.net/wiki/spaces/docs/pages/113999876

https://github.com/wikumChamith/openmrs-module-auditlogui