visitdocumentsui...without the visit

Hi @mksrom and @mksd ,

We are back again to needing, in the relatively short term, a solution for document uploading into a patient chart. Specifically, we are running into the situation where paper record/archive storage is completely full at some of our clinics, and there is a requirement that we scan a patient’s paper dossier and upload it into OpenMRS. The plan is then to move the paper records to an off-site (or not immediately accessible) storage facility.

To do this, one approach that is being considered (and will likely be adopted, at least in some cases) is to simply scan the entire existing chart as a single PDF and upload it, rather than scanning into individual encounter / visit documents. Thus we will need to be able to support patient documents that are not necessarily associated with a specific visit.

Do you have a sense of whether:

  • You would approve of expanding the module’s functionality for this kind of use case (eg. visitless documents)?
  • If so, how much effort this would be to add?

I’d hate to have to re-invent the document handling functionality you’ve already written for the reference application, and would love for us to be positioned to start being able to leverage visit-based document uploading in the future, so hopefully we can find a solution that would support this.

Thanks! Mike

cc: @mogoodrich / @ddesimone / @ball / @cioan

Hi @mseaton and PIH team,

Well in fact you’re putting your finger on a spectacular misnaming, because attaching documents to visits (only) is certainly not the aim of VDUI. VDUI aims at being a versatile patient documents/attachments management tool. Initially the idea was that it would be a tool to manage any complex obs, but it could go further than that (such as having the ability to handle person attribute-images). Based on an instruction string that is provided when uploading a document, VDUI can be expanded to do literally anything one would want. In that light I have been contemplating for a quite some time a next iteration refactoring it into Patient Attachments UI.

Some of the things I have envisioned for it:

  1. Refactor the name into PDUI.
  2. Ship it with an OWA layer. But probably not as two artifacts (such as Appointments Scheduling and Appointments Scheduling UI). Just an OpenMRS module with an OWA layer for the UI components to start with.
  3. Make it RESTful. It is already partially REST compliant and there is already a VisitDocumentResource. The idea would be to fully implement the PatientAttachmentResource that would finish the job.

So the short answers:

Absolutely yes.

Outside of fitting it with a well designed REST API it would mainly consist in creating new views and inserting them where they should in the UI of the target distro (Ref App). There are already many flexible and reusable Angular components. To name some:

  • The thumbnail that expands the document’s content ‘on click’.
  • A gallery to display bunches of thumbnails.

Basically you would want to create new gallery views based on specific queries ("where visit = null"), and figure out how/where to integrate this within the Ref App.

Thanks @mksd! I’m looking forward to digging into this deeper… will keep you posted on how it goes.

Is there a reason the Visit Document artifacts haven’t been posted to the OpenMRS Maven repo? Do you mind if I go ahead and do so?

Take care, Mark

Sure go ahead and push the artifacts. There is no good reason why this wasn’t done before, we just didn’t have the access back in the days and in the meantime we setup our own in house repo.

Do you guys want to do a design call about VDUI so that we could settle on a roadmap for its v2.0 (which would be then PDUI)? Or are you guys rather looking at a smaller tweak to make the existing work also when visit = null?

Thanks @mksd. That’s great news, and very helpful.

BTW, some of my assumptions above were based on the README comments in the visitdocumentsui github project, under Quick Facts:

Although every patient document can be handled, VDUI’s interface only allows to add documents within a visit. This complies to the usual Ref App’s workflow where medical documentation happens within visits through medical encounters.

This made me think that this restriction was by design, rather than something that you might want to change. We might want to soften that wording if we agree to expand beyond visits.

We’re happy to jump on a design call and understand the roadmap we are trying to aim for. I don’t know if we necessarily need to hit all of the aspirational goals (particularly around OWA) in order to meet our short term need or not, but it would be good to have an agreed vision so we know how best to fit into going forward.

Thanks, I hope this works out! Mike

Agree with Mike… in particular, at this point realistically we will be focused on our short-term need, but even if it that only hits a small subset of the functionality you’d like to add I’d hope we can make sure we add it in a way that contributes to the long-term version, rather than as just a temporary hack.

I’ve added the visit document module to our build pipeline, but haven’t really taken a look at the code at all since a few months ago… I plan to look into it in more detail next week, and then hopefully I’ll have a better sense of what we’d like to do.

I also just pushed the 1.3 version to the OpenMRS maven repo… I had to add a distribution management section to the pom… I’ll issue a pull request with those changes on Monday, gotta run now…

Take care! Mark

Thanks @mogoodrich, we’ll be awaiting the PR.

@mseaton, yes the README states what VDUI is right now, in particular UI-wise, but it doesn’t state what it aims to be. Sorry if this lead to confusion. Fundamentally there is no restriction, and we should aim at enriching the REST API so that as many use cases as possible become covered. Front-end wise there is no fundamental restriction either. As I said above, there are reusable components that are agnostic about - for example - the belonging or not of the documents to a visit. However the module is currently released in a shape that fits the default Ref App workflow, which is: visit, encounters, obs… etc. It represents the Ref App-way to combine its UI components and consume its backend services, but it doesn’t prevent to put together other ways of doing so. I hope this clarifies things a little.

The more I think about it the more I believe that the “hack” to make things work outside of visits might not be much to do. As you guys said, I hope we can find a middle ground that tackle your short term goal while aligning with the longer term vision/roadmap that we had in mind for this module.

Again let us know how you want to move this forward.

@mksd I had chance to play around with this today… this is pretty great, and, yes, I think it might be straightforward to apply to our use case.

I added the dashboard widget and the overall action that links to the main “visit documents” page, and I think I see what you mean about there being no front-end restrictions. Although the visit documents page currently expects there to be a visit in the context to work, I didn’t realize how loosely tied to a visit the whole thing was–that is, in the UI the documents (as far as I can tell) aren’t grouped or sorted by visit. I did a some quick hacks and just by adding a few lines to work around NPE that occur if there are no visit in the context, I think I got the functionality to work pretty much the way we want it to work.

I’m going to review with the team here, but if it seems like what we want I can go back with my hacks and replace them with proper handling of the “visit-less” case and then can submit the pull request to you.

Take care, Mark

1 Like

Great, happy to read that the needed changes can be executed quite easily.

P.S. And I still hope that somehow we’ll be able to push our roadmap forward at some point in the future.

@mksd hopefully I will be able to issue a pull request in the coming days for this. One other piece of functionality we are looking to add is the ability to store the document and their obs without an associated encounter. However, I’m thinking this would be straightforward as well. I will be looking into as well.

Question: do you want me to track these as tickets at all? I didn’t see Visit Documents as a project in OpenMRS JIRA, but perhaps I missed it.

Take care, Mark

Thanks @mogoodrich. We’ll be curious to see how you have handled the no visit case within the Ref App workflow.

VDUI has not yet become an OpenMRS project on GitHub, until now everything was tracked in our in-house JIRA. Perhaps is now the time to migrate it, and at the same time give it an OpenMRS JIRA project?

Yes i think it is time to migrate and create a JIRA project for it.


Or we can just create a new JIRA project for it but not worry about migration of old tickets if anything makes this preventative. I defer to you guys.

I think switching to a non-visit model will be fairly simple, but I haven’t fully tested yet so I could be missing something.

Also, we had a design discussion today and we’d like to not create new encounters for each document, just store the documents as stand-alone obs. My thought for this is to simply not create an encounter if the implementation explicitly clears out the GP that specifies the encounter type to use. If you see any objections with this, let me know.

Hope to have pull request by the end of the day.

Take care, Mark


Okay, I just submitted my pull request:

Let me know your thoughts… it is working for our use case and doesn’t break the existing use case (I fired up a standard version of the reference application and loaded in my changes) to the best of my understanding on how things should work.

Basic usage is this–if the “encounterUuid” global property is set to a blank string, then it won’t create an encounter to go along with the obs, nor will it associate it with the active visit. In these cases, it just creates a stand-alone obs to save the data. This also means that with this configuration set you can always upload a document from the visit documents page, you don’t need to be in the context of a visit.

If you want, we could make this an explicit configuration set via a GP rather than base it on the encounterUuid property. I went back and forth on what path to take.

Take a look when you get a chance and let me know your thoughts. Thanks!

Take care, Mark



I am working on trying to contribute to OpenMRS. What does OWA stand for?

Welcome Chris,

OWA stands for Open Web Apps. You can get more details here:

Hi Daniel,

Thanks for the links, they were very helpful!