Email Document Loader Job

The Email Document Loader is a scheduled job that loads mail attachments from emails to existing patient Investigations.

Attachments are associated with Investigations by parsing their identifier from the attachment file name.

Emails can be read from mail servers that support IMAP.

Guidelines for Use

The job is intended to be used to load Investigations results from emails, where a laboratory doesn't directly integrate with OpenVPMS.

It is recommended that a dedicated email folder for results is used to:

  • limit the possibility that attachments will be loaded to incorrect Investigations
  • avoid errors for emails not associated with results

Users can:

  • set up an email account solely for processing attachments
  • set up a folder for attachments and manually move emails into it to be processed by the job

Emails must be marked unread in order to be processed by the job.

Job Execution

When the job runs, it searches for unread emails from the specified Source Folder.
If From is specified, only those emails with a matching From address will be processed.

The job examines each email for attachments.
If it finds an attachment with an identifier that matches an Investigation, it loads it.

Once processed, emails are marked read so they aren't processed again when the job next runs.

Emails that have been processed successfully will be moved to the Target Folder, if it has been specified.
Emails that can't be processed will be moved to the Error Folder, if it has been specified.

On completion, a summary message will be sent to the user or group specified by Notify.


Job Configuration


The fields are as follows:

  • Name
The job name.
  • Description 
The job description.
  • Active

Schedules the job to run if checked, or prevents it from being run if unchecked.

  • Host
The mail server host. E.g.
  • Port
The mail server port. E.g. 993
  • Timeout

The timeout, in seconds for sending and receiving data from the mail server.
A value of 0 indicates no timeout.
This can be used to prevent the job waiting indefinitely if there are mail server or network problems.

  • From
A comma separated list of From addresses. Optional.
If specified, only messages from the specified addresses will be processed.
  • Source Folder 
The folder to read emails from.
  • Target Folder 
The folder to move processed emails to. If unspecified, emails will remain in the Source Folder.
  • Error Folder
The folder to move emails that can't be processed. If unspecified, emails will remain in the Source Folder.
  • Id Pattern
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
  • Enable Logging
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.
  • Minutes
    Day Of Month
    Day Of Week

These determine when the job is run.

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 ?

  • Run As

The field specifies the user to run the job as. This user is required to establish the permissions to:

  • update Investigations
  • send notification messages
  • Notify
The 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.

Security Settings

  • Connection Security
Set to None, SSL/TLS, or STARTTLS as required by the mail server.
  • Authentication Method             
One of:
  • Username
The server user name. Editable when Username & Password is selected as the Authentication Method. When OAuth2 is selected, this displays the authenticated user.
  • Password
The server password. Only applicable when Username & Password is selected as the Authentication Method.


OpenVPMS supports authentication using OAuth2 for Gmail and Microsoft Outlook.
Consult the relevant How To documents on how to configure these:



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


Syndicate content