Introduction

OpenVPMS version 1.3 or greater provides a document importer utility which can be used to setup automatic importing of documents into OpenVPMS.

This document describes how to configure this utility.

Background

In OpenVPMS users can add a range of documents to customers, patients and visits. 

These documents are added manually through the user interface and the attached content is added by browsing to a specific file and uploading it to the document entry.  This process is typically used for the following document types

• Customer Attachments and Images
• Patient Attachments and Images
• Patient Investigations

In many cases it is desirable to have the content added automatically rather than manually.  This is especially true of investigation results which can be electronically downloaded as a file in various formats.  It is also true for automated scanning systems where users wish to have scanned files directly imported into the customer or patient file.

To facilitate an automatic system the document umporter utility needs to be able to identify to what document entry the file belongs to. We decided the best way to accomplish this was to utilise the unique ID assigned to any document entry when you added it into OpenVPMS.  If the file to be imported has a file name made up of this ID and any extension i.e  123456.html  then the importer utility can find a unique document entry and attach the content to the entry. Heres an example of a Investigation entry in a patients Medical Records.

In this case the unique identifier is 2917.

In order for the document importer utility to attach the subsequent electronic result/report to this investigation entry this unique identifier needs to be first communicated to the provider (i.e. via a request form) and the provider needs to subsequently provide some electronic download facility to save the results into a file with the file name set to this number and with any prefix i.e  2917.pdf, 2917.html. 2917.tif etc.   Heres an example of the completed upload.

 Also notice that the status on the document has been changed from In Progress to Completed.  This will allow subsequent workflow functions in OpenVPMS to check from pending or arrived document imports.

Setting Up Automatic Document Importing (Windows)

Import Folders

The document importer utility requires two folders to operate.  The first folder is used as the source of files to be imported.  The second folder is used to archive files that have been succesfully imported.  These folders can be located anywhere on the network as long as they are accesible by the utility.   For this example I have created the following folder structure under the OpenVPMS folder.  You are free to put the folder anywhere on your server or network.

Scheduled Task

In order to have the document import utility regularly check the import folder for new files to process you need to setup a scheduled task to run the utility with the correct parameters.  You can set the utility to run as often as you like.  The frequency depends on how often the files will be downloaded into the folder so may depend on the schedules setup in your other download applications (i.e Eclinic).  The example here runs the utility every 10 minutes.

The document import utility is located in the OpenVPMS release under the bin folder. In this example the comand line used for the utility is :

For version 1.3

F:\OpenVPMS\openvpms-release-1.3\bin\docload.bat --byid --source f:\openvpms\import\in --dest f:\openvpms\import\archive --verbose

For version 1.4

In version 1.4 we have added support for multiple document versions to cater for circumstance where you receive multiple reports for the same investigation id. We also added regular expression support so you can tailor the file name patterns used to extract the id from the filename.  The one shown allows up to 1 or 2 letters followed by the investigation id and then any non numeric delimiter followed by any number of other characters.

F:\OpenVPMS\openvpms-release-1.4\bin\docload.bat --byid --source f:\openvpms\import\in --dest f:\openvpms\import\archive --verbose -o --regexp "^[a-zA-Z]{0,2}(\d+).*"

This is the command that needs to be entered into the scheduled  task Run field as shown here:

You will also notice the Start in: and Run as: are setup appropriately.  It is important that the Start In. field is set to the correct location.  The user selected to run the command must be able to access the folders setup previously.

Here you will notice I have set the import utility to start Daily at 8:00Am and to run every 10 minutes till 10:00Pm.  You can set the recurring schedule by clicking the Advanced button.

Testing

You can test the scheduled task by creating a dummy document entry in OpenVPMs and placing a file into the In folder with the correct unique name and then running the Scheduled task by right clicking on it and selecting Run.

If the task is setup correctly the file should now be attached to the document entry you created and the file should be moved from the In folder to the Archive folder.

If the import failed the file will remain in the In folder and you can check the import log which will be located in the file

f:\OpenVPMS\openvpms-release-1.4\bin\docload.log

This file will contain log entries similar to the following.

23 Mar 2009 10:38:57,505  INFO DocumentLoader,138 - Starting load at: Mon Mar 23 10:38:57 EST 2009
23 Mar 2009 10:38:57,536  INFO DocumentLoader,198 - Ending load at: Mon Mar 23 10:38:57 EST 2009
23 Mar 2009 10:38:57,536  INFO DocumentLoader,203 - Loaded: 0
23 Mar 2009 10:38:57,536  INFO DocumentLoader,204 - Errors: 0
23 Mar 2009 10:38:57,536  INFO DocumentLoader,205 - Total:  0
23 Mar 2009 10:38:57,536  INFO DocumentLoader,206 - Processed 0 files in 0.00 seconds (0.00 files/sec)
23 Mar 2009 10:53:45,070  INFO DocumentLoader,138 - Starting load at: Mon Mar 23 10:53:45 EST 2009
23 Mar 2009 10:53:45,070  INFO DocumentLoader,198 - Ending load at: Mon Mar 23 10:53:45 EST 2009
23 Mar 2009 10:53:45,070  INFO DocumentLoader,203 - Loaded: 2
23 Mar 2009 10:53:45,070  INFO DocumentLoader,204 - Errors: 0
23 Mar 2009 10:53:45,070  INFO DocumentLoader,205 - Total:  2
23 Mar 2009 10:53:45,086  INFO DocumentLoader,206 - Processed 2 files in 1.00 seconds (2.00 files/sec)

If the log file does not contain entries for the date and time you ran the scheduled task you will need to check the setup of the scheduled task itself as it may not be correctly configured.

Notes

Import Folders

In the above examples the import folder have been setup in the OpenVPMS folder.  This may not be convenient in many cases as you may want to use a central folder in a location that is accessible to specific or all users. This is particularly the case if you want users to be able to monitor these folders as well but it also would allow them to drop scanned documents/images into these folders for import.

You just need to change the paths in the above command to suit your specific location. i.e.

F:\OpenVPMS\openvpms-release-1.4\bin\docload.bat --byid --source s:\documents\import\in --dest s:\documents\import\archive --verbose -o --regexp "^[a-zA-Z]{0,2}(\d+).*"

If you use a mapped drive please be sure that this drive is mapped for the user that will run the scheduled task.

Upgrading

If upgrading OpenVPMS the location of the docload batch file will change.  In order to simplify upgrades by not having to edit the scheduled task I suggest you do the following:

1. Create a link to the current openvpms reease folder called current.    Windows 2008 and 7 can do this using the new mklink /d commmand.  Creating a shortcut does not work.
2. Update the command above to use this shortcut i.e

 F:\OpenVPMS\current\bin\docload.bat --byid --source f:\openvpms\import\in --dest f:\openvpms\import\archive --verbose -o --regexp "^[a-zA-Z]{0,2}(\d+).*" 

When the version change all you need to do is redirect the shortcut to the location of the current OpenVPMS version.