Improved Audit Logging(GSoC 2025)

1. Overview

With OpenMRS 2.7.0, Hibernate Envers was integrated to provide audit logging, enabling detailed tracking of database changes. However, there was no easy way for administrators to view or manage these logs.

The Audit Log Web Module makes audit logs accessible, searchable, and actionable within OpenMRS by:

• Providing a legacy UI viewer for administrators to review Create, Update, and Delete operations.

• Adding filters for user, date/time, and entity type.

• Exposing REST endpoints for external systems to integrate with audit logs.

• Automatically handling pagination and sorting for performance.

This module improves accountability and transparency across the OpenMRS platform.

2. Key Features

• Audit Log Viewer (UI): View Create, Update, and Delete operations for audited entities.

• Filtering Options: Search logs by user, date/time, and entity type.

• Sorting & Pagination: Logs are sorted by newest first and paginated for performance.

• REST API Endpoints: External systems can fetch logs via /ws/rest/v1/auditlogs?<entityType=&username=&startDate=&endDate=

• Automatic Audit Table Initialization: Missing Envers audit tables are auto-created at startup (configurable).

3. User Guide

This section helps admins/users set up and use the module.

3.1 Installation

• Download the latest .omod from Releases on GitHub or Clone the module repository and build from sources.

• Install via the OpenMRS Module Admin page.

• Restart OpenMRS.

3.2 Configuration

• For this module, ensure envers is enable on the OpenMRS server you want to deploy it. See this

• To allow the module to auto-create missing Hibernate Envers _AUD tables for @Audited entities on startup, set the following runtime property in your openmrs-runtime.properties

  file: auditlogweb.runAuditTableInit=true

• Audit logging is enabled automatically for all entities annotated with @Audited.

• Logs can be accessed in Admin → Audit Logs (legacy UI).

• Permissions:

  • View Audit Logs – required to access the logs in UI.

  • View Audit Logs (REST) – required to access logs via REST API.

3.3 REST API Usage Examples

4. Developer Guide

This section is for contributors and maintainers.

4.1 Architecture & Design Decisions

• Envers Integration: Hibernate Envers is used for CUD auditing.

• Custom DAO Layer: Provides filtering (user, entity, date range), sorting, and pagination.

• UI: Legacy UI JSP-based log viewer.

• REST Layer: Exposes audit logs for integration with external systems.

• Read Auditing (Future): Research; not yet implemented.

4.2 Module Structure

4.3 Database Schema

• Reuses Envers audit tables (<entity>_AUD, REVINFO).

• Custom DAO queries aggregate and filter logs across entities.

• No new custom tables created.

4.4 REST API Design

• Base URI/Endpoint: /ws/rest/v1/auditlogs

• Supported Filters on the base Endpoint:

  • Get /ws/rest/v1/auditlogs – Gives all logs on the system without given the actual change-log, just the entites

  • ?username=&entityType=&... – list all logs of the entity for the user with detailed change-log (supports pagination + filters)

  • ?startDate=&endDate=... – fetch logs within the date range

4.5 Development Setup

• Clone repo: git clone https://github.com/openmrs/openmrs-module-auditlogweb.git

• Import into IntelliJ/VSCode/Eclipse as Maven project.

• Run: mvn clean install

• Deploy .omod into OpenMRS where envers is enabled

4.6 Testing

• Unit tests written with JUnit + Mockito.

• Running:

  mvn clean install

5. Roadmap / Future Work

• Complete read operation auditing.

• Export logs (CSV, JSON, Excel).

• Advanced search and reporting.

• Performance optimizations for large datasets.

• Automated UI and REST API testing.

6. 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

7. 🙌 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

This section has some details info on how the project started and how it was introduced in gsoc.

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

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

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.