File Browser Module


The File Browser module was designed to give users immediate and convenient access to patient records whose contents may not easily fit within the OpenMRS data model / application. For example, a new implementation may wish to give clinicians access to patient’s old paper charts by quickly scanning them instead of taking the time to manually back-enter this data. Other use cases include having a repository for patient notes saved as word documents, test results received in PDF format, or clinically relevant photographs.

The module accomplishes this by adding a tab to the patient dashboard containing a file browser. The browser automatically opens to a patient-specific folder stored on the server with a name equal to the patient’s preferred ID. In addition to downloading/viewing the files contained in this folder, the module allows users to upload files of any format and perform basic file-system operations such as renaming and deleting. 

How it works

The File Browser module creates a tab on the dashboard with an iframe pointed at a full-featured PHP file browsing/management script. The module passes the patient’s ID number to the script so that the proper folder opens by default. The module also ensures that the folder exists for the patient, and if not creates it (useful for new patients).

Installation Instructions

  1. Organize existing patient files into folders named by the preferred OpenMRS Identification number
  2. Setup a web server with PHP on the same machine as the OpenMRS server (Apache works great)
  3. Place patient folders somewhere in the webserver. Make sure that tomcat has permission to read/write this folder directly.
  4. Download the Simple Directory Listing PHP script by David Wan (attached to this wiki page) and put it on your webserver
  5. Install the File Browser Module through the module repository
  6. Set the global property filebrowser.url to the URL of the file browser PHP script and append ?cwdRelPath= then the pathname of the files on your webserver. For example, 
  7. Set the global property filebrowser.patientfilepath to the local path containing the folders for the patients. For example: /www_root/patientfiles/
  8. Set the global property filebrowser.tabname whatever you want the tab to be called on your dashboard

How to use it 

  1. Go to the patient dashboard
  2. Click the "File Browser" tab (or whatever you named it using the global property)
  3. To view a file:
    1. Click on any file that you want to view, it will download and open
  4. For all other file operations:
    1. Click the small "login" link at the bottom of the file browser
    2. The default username is admin and password is test, this can be changed by directly editing the php file.
    3. Click the icon at the bottom for rename, upload, delete, etc.

A note on security

Installing the PHP script will allow anybody with the proper URL to access any file/folder on your webserver! If your webserver is publicly accessible from the Internet, establishing security using .htaccess or another method (such as from within the php file browser script itself) is essential!

Known issues

  • If for some reason a patient’s preferred ID number changes, the File Browser module will automatically create a new file-system folder for that patient. However, the module will not delete an old folder or move files contained within an old folder to this newly created folder. Although the files won’t get deleted – they are effectively lost to the user until a system admin manually fixes the problem by putting files where they should be.
  • Since patient folders are not removed when a patient is deleted from the system, the file system may contain artifacts. If in the future a new patient is created with an ID that was previously used they may “adopt” the old patients’ files.
  • Although the starting folder is that of the patient, it is possible for a user to browse to other folders in the filesystem and even upload in the wrong place. 
  • After logging in for "admin functions" of the file system for the first time in a session the user gets put back to the root directory. A simple refresh fixes this problem but if the user doesn't notice they may upload the file in the wrong place. One fix is to disable admin security but this will allow everyone to edit/delete etc.


  1. Simple Directory Browsing PHP Script by David Wan
  2. File Browser Module in the module repository



This module was developer by Tobin Greensweig for MigrantHealth:IL