Huge thanks to the community and mentors for the support and guidance so far. Since the results were announced on May 8, I’ve attended the GSoC orientation and had my first mentor meeting. We’ve decided that the first key step is to break down the main project requirements into smaller, actionable tickets that will guide implementation over the summer.
This thread will continue to serve as the primary place for project updates, community discussions, and feedback especially from anyone interested in audit logging for OpenMRS.
Two(02) weeks of GSoC’ 2025 are gone already, and I am happy to share the progress so far.
You can find the update writeup on medium at: week-02 update
Given details of what has been achieved so far on the project progress.
Hello everyone, it’s been 4 weeks today since official GSoC coding started.
Catch the progress on the “Improve Audit Logging System on OpenMRS” project.
The following is the blog post housing the progress update so far. Find it on medium.com
Hi @njiddasalifu ! Thanks for these updates. As you know I’m really excited about this project because we have sooo many implementers (and really their funders/governments) asking for Audit Logging. My hope is that we’ll have a UI Audit Log we can launch into the EMR product from your project!
Could you share some screenshots of your progress? Can’t wait to see how it’s looking
Thank you @michaelbontyes, for the questions. At the moment, we are starting to implement the filtering of logs, and what you just mentioned will be seriously considered.
More updates will be coming up soon in regards to this.
As part of improving auditing and traceability in OpenMRS, I previously worked on exposing audit logs in the Admin UI (via JSPs) to help system administrators view log activity.
I’m now taking the next step, designing a REST API to expose these audit logs to external systems in a secure, structured, and read-only way. This will make it possible to integrate with external audit reporting tools, monitoring platforms, or data pipelines.
Below is the initial design proposal for the REST API. I’d love community feedback as I begin building it out.
Below is the design proposal for the community to review, comment on, and improve.
What This API Will Do
This REST API will expose audit log records such as:
When a patient or encounter was created, updated, or deleted
Who performed the action
When the action occurred
What the affected resource was
All data will be exposed via standard OpenMRS REST conventions (/ws/rest/v1/...) and will be read-only.
API Resource Structure
Base URI: /ws/rest/v1/auditlogs
Supported Methods:
Method
URI
Description
GET
/ws/rest/v1/auditlogs
List all logs (paginated)
GET
/ws/rest/v1/auditlogs/{auditId}
Get log entry by UUID
GET
/ws/rest/v1/auditlogs/classes
Filter logs by criteria
This resource will not support POST, PUT, or DELETE, in order to maintain log immutability.
Fields in Each Log Entry
Field
Description
revisionId
Unique log identifier
eventType
Type of change: CREATE, UPDATE, etc.
className
Java class of the affected entity
persistedObjectId
ID or UUID of the affected domain object
message
Human-readable summary (optional)
dateCreated
Timestamp of the logged action
creator
User who triggered the action
Pagination & Filtering
Supports standard pagination (limit, startIndex) from OpenMRS
Filtering options under consideration:
eventType
entity
creator
startDate / endDate
Example usage:
GET /auditlogs?eventType=DELETE&entity=Patient
Security Considerations
Requires OpenMRS authentication
Requires privileges like View Audit Logs
Read-only access (no creation, update, or deletion) audit logs remain immutable
Next Steps
I’m currently seeking feedback from:
Module authors
Platform maintainers
Implementers
Anyone interested in logging/auditing in OpenMRS
To help ensure we have a unified design of our Audit Logging Module
Thank you so much @nsalifu for this update and demo. Ministries of Health and procurement officers around the world continue to ask for Audit Logging as a must-have requirement for EMR systems, including OpenMRS!
Question for @jayasanka@jwnasambu@dkigen : Did this feature make it in to the 3.5 RefApp Release? I don’t see it in the Sys Admin in dev3 so I’m guessing not. Is it possible for the 3.6 release?
Thanks @grace for asking as @nsalifu has said it will be featured in the next release since there were 2 pending PRs that made it impossible for production.
Hello there,
For audit logging in OpenMRS, Hibernate Envers is used for tracking DB changes (CUD ops). It’s enabled on any OpenMRS instance by adding some properties in the openmrs-runtime prop file. For Envers to store these logs, they must be Envers audit tables present in the database. These tables can be created automatically on start-up when hibernate.hbm2ddl.auto=update. However, we can not use ddl.auto.update on prod. This brought us on the idea, let’s dynamically initialize audit tables on module start-up. That is we simply check look at all audited entities (those annotated with @Audited), check the database if there’s any audit table for them, if not, create one. You can see implementation here: (feat) AUDIT-23: Add audit table initialization logic using runtime property flag to create missing audit tables by nsalifu · Pull Request #21 · openmrs/openmrs-module-auditlogweb · GitHub
Although this works, it doesn’t address the case of what if an entity schema changes ? This means the audit table won’t be updated.
We thought of another idea of using OpenMRS liquibase scripts to initiate the audit tables, such that whenever there is a schema the tables will be updated accordingly. I started looking into this idea, it’s in progress.
Now the Question:
Where can we add this behaviour of dynamically creating Envers audit logging? I am not sure if this should be done in the openmrs-core or audit logs module. I am seeking suggestions and better ideas on how to handle this in the best-case scenario.
Thanks in advance!
Hi @nsalifu, thank you for this great question. Tagging @dkayiwa for his feedback
(FYI @veronica - Wikum plans to add the above improved functionality, re. dynamically created Envers audit logs, to the next iteration of this feature; we want to release this into the RefApp with v1 as-is basically, once Wikum is done a few improvements.)
If someone makes a new foobar module, is it the responsibility of the foobar module to enable auditing capability? Or is it the job of the auditing module(s) to support foobar?
If it’s the former case, then I’d expect modules to add and own support for auditing by creating and maintaining their audit table (e.g., using liquibase). If it’s the latter case, then the responsibility would fall to the audit log module(s).
If audit tables could be created automatically by the audit log module and maintaining audit log table changes could be done without requiring a lot of audit/Hibernate expertise on the part of the module author, then I would think placing the responsibility of maintaining model changes to the module author would be the most scalable approach.
@grace That will be great. I agree with the idea of having the completed audit logging work in this release and making improvements in the future release.
If you placed the behaviour of dynamically creating Envers audit logging in a module, does this mean that without this module, there would not be any auditing in openmrs-core?
I think yes, if the creation of audit tables is handed over to the auditlog module, and the audit logs module is missing, then there will be no audit tables for audited entities, hence no audit in the system.
Except hibernate.hbm2ddl.auto=update is enabled in openmrs-runtime.properties file. That’s ultimately what we want to avoid. @dkayiwa
GSoC 2025 - Improved Audit Logging: Exploring Ideas and Next Steps for Proposal
This thread will continue to serve as the primary place for project updates, community discussions, and feedback especially from anyone interested in audit logging for OpenMRS.
