Patient Portal

From OpenEMR Project Wiki


There are two options for setting up a patient portal. The first option is a functional Patient Portal, included with OpenEMR (The Native Patient Portal). The second option is using the CMS patient portal, which utilizes a set of APIs included within OpenEMR. The second option uses a WordPress installation as the patient interface, providing a rich platform for website development and secure isolation from OpenEMR without requiring a third-party service. (The WordPress portal is under reconstruction)

To set up a patient portal will require your OpenEMR instance to be open to the web. Doing this securely requires intimate knowledge of all the pieces involved (OpenEMR, Apache, MySQL, PHP, https, certificates, routers, firewalls, etc.). A wiki page has been created for the community to begin standardizing ways to ensure that OpenEMR is secure, which can be found at the Securing OpenEMR wiki page.

Native Patient Portal

This is a fully functional onsite (meaning served from the same site as OpenEMR) patient portal.

Version 2 Native Patient Portal - Only Onsite-Patient-Portal as of OpenEMR version 5.0.2


  • To turn the portal on, toggle on Administration->Globals->Portal->Enable Patient Portal
  • Set the portal web address at Administration->Globals->Portal->'Version 2 Onsite Patient Portal Site Address' (this address is the link to your portal that gets emailed to patients)
  • Note that if you have multi-site configured for OpenEMR, then need to use the following link to ensure the patient goes to the correct site: (where the default is substituted with the site directory)
  • Portal is at openemr/portal/
  • Physician portal in OpenEMR is at Miscellaneous->Portal Dashboard (note that because of session issues, you can not open the patient portal and this GUI at the same time in the same browser).
  • To authorize a patient to use portals, need to set the following demographic entry to 'YES': Demographics->Choices->'Allow Patient Portal'. To allow emailing of the portal login credentials to the patient also need to set an email address in the patient demographics and need to set the following demographic entry to 'YES': Demographics->Choices->'Allow Email'.
  • Patient portal login credentials for patients can be created/reset in the patient summary screen at the 'Create/Reset Onsite Portal Credentials' button (button is located at the top of the summary screen).
  • When click 'Save' in the portal login credentials screen, it will email the credentials to the patient and the credentials can also be printed out. (note that for an email to work, the patient needs to 1) ok email in demographics->choices, 2) have a email address entered in demographics, 3) an email address needs to be set in Administration->Globals->Notifications->'Patient Reminder Sender Email' )
  • When a patient logs into the portal for the first time (or after credentials are reset), the patient will be forced to set another password.
  • Portal features include the following:
  • Listing of features is PENDING.
  • The portal is also set to work with OpenEMR's translation engine and uses the same translation login settings of OpenEMR that are set at Administration->Globals->Locale (by default, it will ask the patient for language on login).
This portal was added in OpenEMR 5.0.1.

CMS Portal

The CMS Patient Portal, developed by Sunset Systems, is an interface from OpenEMR to a content management system such as WordPress. Initially only WordPress is supported, and for simplicity the remainder of this document will focus on that.

Why a CMS Portal?

Important aspects of the CMS Portal are:

  • Security. A compromise of the public portal is not a compromise of OpenEMR.
  • No need to trust and pay for an outside service for portal hosting and management. Anyone who can set up and maintain a WordPress web site can operate their own portal.
  • As the portal is based on the world's most popular content management system, it is easily made an integral part of a more general public web site for the practice.
  • The full power of WordPress and its more than 35,000 available plug-ins are available to enrich the functionality of the site. E-commerce is one example.

Features include:

  • New or existing patients may register for an account with the portal.
  • Demographics, history and insurance information may be submitted via the portal.
  • Issues (medical problems, allergies, medications etc.) are also supported.
  • The administrator may create clinical portal forms that correspond to existing "layout based forms" in OpenEMR but are easy for patients to understand and use. Patients can then fill these out to save transcription time and improve accuracy, and perhaps eliminate some visits entirely.
  • Images and documents may be uploaded by the patient and then stored in OpenEMR.
  • Secure messaging between clinic and patient, including transfer of attached documents.
  • Clinic staff may generate patient reports that are sent directly to the portal, and the doctor may choose to copy lab reports to the patient as they are e-signed.
  • Easy user interfaces in OpenEMR for reviewing, correcting and storing data from the portal.
  • Document templates in OpenEMR may be customized with layout-based form data that was imported from the portal, thereby easily producing documents such as referral reports.

Regarding security, notice we say the interface is "from OpenEMR", not "to OpenEMR". An important design aspect is to not expose OpenEMR to connections from potentially dangerous sources. Otherwise it can be very bad news if the CMS is compromised. Thus the design is that all connections between the EMR and CMS are initiated by the EMR.

Also in the interests of security and privacy, patient data items stored on the CMS are transient and kept to a bare minimum.

WordPress Site Requirements

To use the portal, the WordPress site should have these plug-ins installed:

  • Nav Menu Roles
  • Peter's Login Redirect
  • User Role Editor
  • Cartpauj PM (1.0.11 or greater)
  • Ninja Forms
  • Ninja Forms File Uploads (optional, non-free)
  • Ninja Forms Conditionals (optional, non-free)
  • Sunset Patient Portal (

In addition it may be useful to install a plug-in to facilitate sending email, such as WP Mail SMTP.

Also the WordPress site must be configured to use SSL (HTTPS). This is very important for encryption of passwords and patient data over untrusted networks.

OpenEMR Requirements

Support for the CMS portal is built in to OpenEMR as of release 4.1.3. You may need to make sure PHP cURL support is included; in Ubuntu and Debian installation of the php5-curl package does this. The other important requirement is network access to the WordPress site, which will usually be via the Internet.

Configuring WordPress

Setting up the portal is mostly an exercise in learning WordPress and its Ninja Forms plug-in. There is also a fair amount of detail work in creating your desired forms, although sample forms are available.

Your WordPress server should be configured with SSL. For this you will need a domain name and a SSL certificate. There are many commerical sources for these -- if you don't already have one you are comfortable with, try and their "RapidSSL" certificates. Alternatively, is free.

The WordPress download page is here:

WordPress installation instructions are here:

After installing WordPress, choose a theme that you like and install the plug-ins mentioned above. Also spend some time with the instructions and getting to know how to navigate the system.

The first plug-in to configure is "User Role Editor". In the administrative area go to Users -> User Role Editor. Click "Add Role" and create a new role with an ID of "patient" (this specific ID is required, all lower case) and a display name of "Patient". Make it a copy of the Subscriber role so that its only capability is "read". This is the role that will be assigned to your patients. Also if patients will self-register for a portal account, be sure to set the primary default role to "patient".

Also with User Role Editor, click "Add Capability" and create a capability with ID "manage_portal". This specific capability should be assigned to the user that OpenEMR will use for connecting to the portal (see "Configuring OpenEMR" below).

Then it would be good to review and customize all of your system settings. In the administrative area you'll see that "Settings" is broken down into about 9 sections: General, Writing, Reading, etc. The WP instructions will help you with these, but here are a some special notes:

  • In Reading, you probably want your front page to display a static page.
  • In Login/logout redirects, you will want the "patient" role to redirect to a suitable page upon login. Plan to set that up after you have created some initial pages.
  • Be sure to configure WP Mail SMTP or whatever you use to manage outgoing mail. This is to make sure that you and your users get any appropriate mail that may be generated.

Next, configure the "Cartpauj PM" plug-in which supports private messaging between patient and clinic. In the Cartpauj PM Settings page specify "Login name of administrative user" to indicate the WordPress user who is the clinic contact for private messaging.

You probably want most or all of your pages with forms to be available only to logged-in patients. The Nav Menu Roles plug-in will make that easy.

There's an important Apache configuration issue if you use the Ninja Forms File Uploads plugin. This plugin stores uploaded files in a directory on the server for all to see. So you must have something like this in the site's configuration file:

 <Directory "/var/www/wp-content/uploads/ninja-forms">
   AllowOverride None
   Order deny,allow
   Deny from all

Configuring OpenEMR

Aside from setting up your layout-based forms, the only OpenEMR setup needed is to tell it how to access your WordPress site. For that go to Administration -> Globals -> Portal and fill in the 4 "CMS Portal" fields there.

"Site Address" is the base URL of the secure WordPress site and should start with "https://". Check the "Enable CMS Portal" checkbox and also fill in the WordPress login name and password of the desired administrative user. OpenEMR will be logging in as that user when connecting to WordPress.

Creating Forms in the CMS

Each form that you define in the CMS for patients to fill out will have a specific prescribed name. The name depends on the type of form and must begin with one of the following:

  • Demographics
  • Insurance
  • History
  • Issue
  • Upload
  • LBFxxx which matches the name of any layout-based encounter form in OpenEMR

Sample Ninja files may be downloaded from Right-click the form name and "Save Link as" to your computer. Import into Wordpress under Dashboard -> Forms -> Import/export -> Browse -> Click the file and Import. On the top of the page you should then see "import successful".

Another special thing you must do in these Ninja forms is to specify the field names from the corresponding OpenEMR layout. To see what they should be, open the form in OpenEMR's Layout Editor and look at the ID column. Those the names you want. There's no such layout for insurance but a sample Ninja form is provided for that .

To specify a LBF field name in the Ninja Forms Field Settings, check "Add Description" for the field. In the editor select the Text (not Visual) tab if it's not already selected. In the description textarea enter the field ID as an HTML comment, like this:

 <!-- field_id -->

where "field_id" is the field ID.

If you also want visible description text, then just make sure this comment comes first; otherwise set the Description Position to "None".

There is an exception to this field naming convention. If the LBF field type is Exam Results, then multiple Ninja form fields must be created, one for each type of exam. In that case the field name in the Description area must be of the form "fieldid:itemid" where fieldid is the LBF field ID and itemid is the list item ID of the desired exam type. For example the field ID for a breast exam in the History form will be "exams:brs".

Some data types require a choice from a list, however the values are hard-coded in OpenEMR and do not have a corresponding list there. These data types and their value choices are:

  • Exam Results: "0" = N/A, "1" = Normal, "2" = Abnormal.
  • Lifestyle Status: "current", "quit", "never", "not_applicable".
  • Smoking Status: "current", "quit", "never", "not_applicable".

These conventions for putting OpenEMR form names, field names and values into your Ninja forms allow their data to be later matched up with and copied into the right places in OpenEMR. You must get these names exactly right, including capitalization, in order for this to work. And of course if you change your layouts in OpenEMR, you may need to make corresponding changes to your Ninja forms.