Document Loader
The Document Loader is a scheduled job that periodically load files from a directory and attaches them to documents or investigations.
Files are associated with documents or investigations by parsing their identifier from the file name.
The Active field:
- schedules the job to run if checked; or
- prevents it from being run if unchecked
The Source Directory is the directory to load files from.
The Destination Directory is the directory to move successfully loaded files to.
The Error Directory is the directory to move files to that couldn't be loaded.
Note that the Tomcat application must have write access to Destination and Error directories.
(nb. on linux servers you must use the direct path, not a symbolic link and the group that owns the the source and destination directories must have read and write permissions and the tomcat user must belong to that group eg. use 'sudo usermod -a -G group tomcat7')
The Id Pattern is a regular expression that enables the document identifier to be parsed from the file name. The default expression is [^\d]*(\d+).* - this looks for the first digit string in the file name. For example, the following file names all have the ID 3035108:
DAO DAO_TSANG_ _3035108_20150226_115435_4762.pdf
3035108 CBC test.jpg
Xray DAO DAO_TSANG 3035108.jpg
The Overwrite field determines if files should be loaded if one already exists. If selected, the existing content will be replaced, if it doesn't duplicate the existing content. For documents that support versioning*, the existing content will be saved as a version. The following table indicates the behaviour if a document has been previously loaded:
| Case | File | Ovewrite=n | Overwrite=y |
|---|---|---|---|
| 1 | Same name, same content | Skipped | Skipped |
| 2 | Same name, different content | Skipped | Loaded |
| 3 | Different name | Skipped | Loaded |
Note that in case 2 & 3, if the document supports versioning, then the previous document is set as a version, and the primary document is replaced.
In case 2, if the previous document already exists in the Destination Directory, then the loader will fail and terminate. The file in the Destination Directory needs to be manually moved aside.
* all of the standard document archetypes with the exception of act.documentTemplate in OpenVPMS support versioning. The Document Loader cannot be used to load act.documentTemplate instances.
The Recurse Subdirectories field determines if subdirectories of the source directory should be searched for documents to load.
The Archetypes field is a comma separated list of archetype short names, identifying the document archetypes that may be loaded to. These may include wild cards. Use of wildcards is NOT recommended, as malformed file names may result in files being loaded to incorrect documents. For Investigations, use act.patientInvestigation.
The Enable Logging field determines if loading should be logged. This can be used to help track down problems. The information is written to the OpenVPMS logs in <TOMCAT-HOME>/logs.
If Stop On Error is selected, the loader will stop on the first error it encounters. Note that this means 'stop this run', it does not 'stop all future scheduled runs'. For normal operation, you should leave this unticked, otherwise, it is possible that an error with one document (say because it has a name that does not contain an ID) will prevent other documents being loaded.
The Minutes, Hours, Day Of Month, Month, and Day Of Week fields determine when the job is run. [Note that if you change the schedule, the new schedule will take effect immediately.]
These are a defined using a simplified version of a Cron expression:
| Field | Allowed Values | Allowed Special Characters |
|---|---|---|
| Minutes | 0-59 | , - * / |
| Hours | 0-23 | , - * / |
| Day Of Month | 1-31 | , - * ? / |
| Month | 1-12 or JAN-DEC | , - * / |
| Day Of Week | 1-7 or SUN-SAT | , - * ? / |
Note that only one of Day Of Month and Day Of Week may be specified. If one is specified, the other must be set to ?.
Examples
| Description | Minutes | Hours | Day Of Month | Month | Day Of Week |
|---|---|---|---|---|---|
| Run at 8am every weekday | 0 | 8 | ? | * | mon-fri |
| Run every 30 minutes | */30 | * | * | * | ? |
| Run every 2 hours | 0 | */2 | * | * | ? |
| Run every 15 mins between 8am and 6pm on weekdays | */15 | 8-18 | ? | * | mon-fri |
The Run As field specifies the user to run the job as. This user is required to establish the permissions to:
- create and update the specified archetypes
- send notification messages
The Notify field specifies the user or user group to notify when a load has completed. Notification only occurs when documents are loaded, or errors are encountered. You may want to use a 'real' user or group of real users, or you may want to create a user such as 'Document Loader Message Receiver' used only for these notifications.