Visit Documents Module - New Features

@mksd & all others who are interested…

We demoed the Visit Documents functionality last week to our implementers in Haiti and they liked it and think it will generally fit their needs.

(Have you had a chance to look at our “visitless” pull request yet? :slight_smile: )

They did have a few feature requests, some hopefully straightforward, and some definitely more complicated. I don’t know if we have the bandwidth to implement more than that straightforward ones at this point, but wanted to run them by you to get your feedback.


  • They’d like discrete permissions to “upload” and “delete” so that they can give a subset of users upload privileges, and an even smaller subset of users “delete” privileges

  • For users that have “upload” but not “delete” privileges, they’d like to handle the “upload by accident” use case by specifying some logic like “a user can delete a file they uploaded, even if they doesn’t have delete privileges, as long as it’s within 5 minutes of the date created”


  • They’d like to record every time a user downloads a document so they can track who is downloading what for auditing purposes. I could see adding a separate table for this, though this would be a bit “heavyweight”. It’s also possible we could piggyback/utilize some existing audit functionality (I believe there’s been an “audit module”, and there’s also the “usage statistics” module). Alternatively, we could store each download as an obs, though that doesn’t seem “correct”.

  • Getting a lot more complicated, they asked if it was possible to add a custom watermark each time a user downloads a PDF. They are planning on uploaded PDF scans of the patient charts, and so the idea is when a provider downloads the documents it will be watermarked with their user id or some other piece of identifying information, so that if they start forwarding the records on when they shouldn’t be, it can be tracked back to them. This is certainly way beyond something that would actually be build into the module, and I doubt we will have a chance to work on it anytime soon, but I did check into a bit and there is an Apache library for manipulating PDFs. If we did do this my thought would be to create some sort of “pre-download transformation” interface. If an implementer defined a bean in their distro that implemented this interface, the file would be passed to this interface prior sending it out to the user. I haven’t given any thought to how feasible this would actually be to implement though.

Any thoughts?

Take care, Mark

Hi @mogoodrich,

Thanks for this, really great to get that kind of feedback.

I think the permissions changes will indeed be straightforward enough.

Regarding the auditing, would every document’s view be recorded then? As you may have seen, from the backend’s perspective there is no difference between viewing and downloading a document. Of course you may decide to only audit requests for certain views (in the complex data sense of the term ‘view’ here). You could for example bypass auditing when thumbnails are fetched, which typically would make sense for PDF files (but not necessarily for images or other content types where the thumbnail itself might already represent sensitive information).

I guess the same remark applies to when to apply watermarks. Btw that’s quite an interesting feature idea! I guess it would require the development of a third-party library for watermarking files based on their MIME type. Again you don’t mention images, will there never be a case where sensitive data will be uploaded as an image?

Also, surely PIH must have developed some sort of patient summary reports? And if yes I would assume that those reports could be downloaded. And again if yes, does watermarking not apply there too?

Thanks @mksd!

Yeah, the idea would that any view/download would be tracked. I didn’t think about thumbnails, but agree that it varies based the content type… I could see tracking 1) full view/downloads and 2) thumbnail views and then administrators could just look at whatever is relevant to them,

Right now there we are only planning on dealing with PDFs, so that would our focus–we have an initiative at one of our hospitals to scan old paper records and archive them to save space in our archives room. I could see wanting to add images at one point, but this would be enough as a start.

We do have summary reports that are downloadable, but there is currently no watermarking on them. However, there’s a smaller subset of users that have access to them… I think there’s a greater interest/concern when putting full patient charts online in an easily downloadable format and opening them up to all clinicians.

Take care, Mark

@mksd There was mention of renaming this module, is it still in the pipeline?

@ssmusoke renaming the module yes, into something like ‘Patient Attachments’ or simply ‘Attachments’. But that’s only the icing on the cake, there would be some more refactoring to do. Mainly:

  1. Make it fully REST.
  • Streamline the Angular front-end.

Could I suggest this:

We would take on the first mile consisting into renaming it, moving it to an OpenMRS repo, integrating it into the CI pipeline… etc. Then I could mentor one or several students/graduates/apprentices to cover the tickets behind 1 and 2 + features suggested by others.

@dev5, is that something doable?

Yes. Create the necessary tickets as a starting point.

Yep, sounds like a great idea to me as well.

Take care, Mark

@mogoodrich, what about openmrs-module-attachments? From what you’ve seen of it, do you think this would be an appropriate name? Or perhaps openmrs-module-documents, but that’s vaguer and may lead to confusion.

Anyone else? @hpardess, @mksrom, @yadamz, @ssmusoke

Sorry, was out of vacation last week.

Off the top of my head, “attachments” sounds good to me, but would certainly be willing to hear other ideas. Might be worth starting a new thread with a title specifically related to renaming so others can weigh in? (Though if you don’t want too much input, I’d say feel to not do this). :slight_smile:

Take care, Mark

Thanks Mark. Since I personally like ‘attachments’, I will just do a last call on this thread :wink:

@dkayiwa, @ssmusoke, pros/cons on openmrs-module-attachments? After all this will primarily be for the Ref App.

@mksd I think attachments are good … you could also use a paper clip icon to reinforce it - thats what email clients and others use

Thanks @ssmusoke, that is already the case within the app :slight_smile:


I will look into having this on the GitHub repo title/description.

Does this module support any type of annotation of uploaded documents? Not necessarily marking up images, but two use cases to consider:

  • A free text caption/comment – e.g., “Photo of rash on patient’s left arm”

  • Some form of categorization – e.g., associating with a tag or concept so you could, for example, know that the document is a consent vs. a scanned lab result vs. a scanned pulmonary function test

Hi @burke,

So ‘comment/annotation’, yes as you can see in the snapshot above (actually that’s simply stored as the obs comment).

‘Some form of categorization’… no. It sounds like something that could be added to its roadmap. Could you describe in more details the sort of flow that you imagine here?

This is also an interesting idea for VDUI: ‘Display multiple images under single Window to have a comparison by the doctor in consultation view’.

Thanks, i will go through and revert.

Regards, Kiran

Hello! Can you please provide some further information about what is expected for this? I have a few questions below…

  • Will the categories be predetermined (e.g., drop down, radio buttons)?
  • Can multiple categories be applied?
  • What is the benefit of adding a category attribute?
  • Would users be able to search by category to find all matching files?

Hi @mogoodrich, I had some doubts regarding the uploading priviledges. I feel that instead of restricting permissions for uploading documents to a limited number, we can give that priviledge to everyone but posted in the repository only after it is reviewed from a trusted member of the organisation which will assure that legit data is uploaded. This can be helpful as there can be really important data that could be uploaded by an anonymous user. but if the user does not have permission to upload it it can be a knowledge loss for the organisation. The other requirements seem accurate to me.

Regards, Priyanka Bhangale

Thanks @priyankab… not sure I agree, but I think there could be potential for both approaches.

I think there will always be implementations that want to restrict the uploading to a specific subset of users. On top of that, there could be a new privilege that could giving that would allow a “upload with review” as you describe.

Then individual implementations could how they want to assign privileges on their system.

There also isn’t currently a review workflow, and I wouldn’t want waiting on this to stop us from adding the upload privilege… adding the “review” workflow and associated privilege could be another task/ticket. Thoughts?

Take care, Mark

Hi @slope018,

Probably rather an autocomplete text field.

Yes, so from a UI standpoint let’s think of it as some sort of tags or predefined labels.

This would help code attachments by mapping them to specific categories. After all EMR systems are all about coding observations.

Yes we could imagine that those categories/tags/labels could become queries filters.

This feature requires some UI/UX thinking. Adding categories will likely happen from the thumbnail, perhaps through a ‘+’ button popping up an autocomplete search field?
And then when categories have been applied, they should also display somewhere on the thumbnail. They should be visible enough to be useful, while not bloating the thumbnail (which is a small UI component).

From the backend perspective there is also some thinking about the best way to map those categories to an attachment. There is in fact no attachment DAO entity behind the scenes, it’s a complex obs. The question is: how to add categories to an obs then? We may need a new database table there…

@burke is suggesting to use concepts as categories, which obviously makes sense from a coding standpoint. A concept set could be used to define which concepts could be picked from.

Does that clarifies things a little? @burke do you agree?