You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Current »

API Description

The DrCloud MU3 API is a web-based, CCDS-compliant API that is used to request and receive data from a DrCloudEHR server.

  • When a user 'logs in' to the API, a token is received that can be used to authenticate later API calls.
    • User creation is handled by the existing User management interface.
    • Tokens are valid for up to 60 minutes.   However, a user may request a new token at any time.
  • Parameters are passed to the API scripts using POST variables.
    • The programs written to test the API are PHP scripts that use libcurl to communicate with the API scripts.
  • The scripts return requested MU3 data formatted as an XML file.
    • For API calls that request MU3 section data, the returned files are generated by DrCloud's CCDA reporting code.

Software Release Version

DrCloudEHR 2020

MU3 API

This table shows the API for Meaningful Use validation.   Most of the API calls make use of POST variables.   Browser-based HTML forms can be used to access these, though the test scripts can be scripted for simpler automated testing.


FilenamePOST Variables

Returns

(status = 0)

Errors

(status != 0)

Comments
getallpatients.php
  • site
  • token

XML file containing an array of records containing:

  • id
  • pid
  • firstname
  • lastname
  • middlename
  • phone
  • dob
  • gender
  • patient profile image
  • 1 - No Patient Vitals data found
  • 1 - Error processing patient records
  • -2 - You are not authorized to perform this action
  • -2 - Invalid token

Can be used to find patient ID's, if you don't know the patient's name.

Call using getallpatients.bash


getlist.php
  • token
  • patientId
  • type
  • visit_id



getpatientrecord.php
  • site
  • patientId
  • token
  • zero or more section names, separated by spaces

An XML file containing either a complete set of CCDS sections, or individual CCDS sections, as specified.

If no section names are specified, all sections will be returned.


Call using getpatientrecord.bash

Section Names:

'SMOKES' - SocialHistory
'SOCHIS' - SocialHistory
'PROBS' - Problems
'MEDS' - Medications
'ALLRGS' - Allergies
'LABPRC' - LabProcedures
'LABRES' - LabResults
'VITALS' - VitalSigns
'PROCS' - Procedures
'CARETM' - CareTeam
'IMMUNS' - Immunizations
'IMPLTS' - ImplantableDevces
'ASSMTS' - Assessments
'TRPLAN' - PlanOfCare
'GOALS' - Goals
'CNCRNS' - HealthConcerns

getuserlist.php
  • site
  • token

An XML file containing an array of records, consisting of:

  • id
  • fname
  • lname
  • name
  • username
  • -1 - ERROR: Sorry, there was an error processing your data. Pleas re-submit the information again.
  • -2 - You are not Authorized to perform this action
  • -2 Invalid Token

initsetup.phpN/A

HTML page containing the message:

Database Updated Successfully

HTML page containing the message:

Database Failed to Update

Must be called from browser.

Creates api_tokens table, if it doesn't already exist.

Adds columns to users table to support API.token

login.php
  • username
  • password
  • date*
  • site

An XML file containing an array of records, consisting of:

  • token
  • id (user)
  • provided
  • firstname
  • lastname
  • title
  • -1 - Appointment not found
  • -1 - Prescription records not found
  • -1 - Lab results not found
  • -1 - Mesages not found
  • -1 - Username/Password incorrect.

Call using login.bash

If date not specified, current date is assumed.


report_visits.php
  • token
  • facility
  • provider
  • from_date
  • to_date
  • new_patients (boolean)

Returns a pdf file and a html file containing the summary of visits.


Use this to find patient encounter ID's

Call using report_visits.bash

Test script returns report_visits.pdf, report_visits.html.

searchpatient.php
  • token
  • firstname
  • lastname
  • site

An XML file containin an array of records, consisting of:

  • id
  • pid
  • firstname
  • lastname
  • phone
  • dob
  • gender

  • -1 - ERROR: Sorry, there was an error processing your data. Pleas re-submit the information again.
  • -2 - You are not Authorized to perform this action
  • -2 Invalid Token

Use this to find patient ID, if you know the patient's name.

example POST variables:

firstname = "Artemis", lastname="Osborne"

Returns patient list entries that match at least one of the search parameters.

Call using searchpatient.bash


API Test Programs Overview

The DrCloudEHR API Test Programs are a set of PHP scripts that serve as a demonstration of the DrCloudEHR API.   While the Test Programs are written in PHP, the API should work with any programming language that is capable of implementing a RESTful API.

These scripts have been tested on a Linux system, but should also work on MacOS.  It may also work on Windows, using a package like WAMP, plus a Unix/Linux-type shell program, such as git-bash.

The "test_settings.inc" file must be customized before running these scripts.
See the 


Script NameArgumentsCorresponding PHP API scriptReturnsNotes
login.bash(none)test_login.php
  • -1 - Appointment not found
  • -1 - Prescription records not found
  • -1 - Lab results not found
  • -1 - Mesages not found
  • -1 - Username/Password incorrect.


getallpatients.bash(none)test_getallpatients.php
  • 1 - No Patient Vitals data found
  • 1 - Error processing patient records
  • -2 - You are not authorized to perform this action
  • -2 - Invalid token

getpatientrecord.bash
  • encounter ID
  • zero or more section names

test_getpatientrecord.php

These status values are returned by this script.

  • 1 - Encounter ID missing
  • 2 - No valid section names found


getuserlist.bash
test_getuserlist.php
  • -1 - ERROR: Sorry, there was an error processing your data. Pleas re-submit the information again.
  • -2 - You are not Authorized to perform this action
  • -2 Invalid Token

report_visits.bash(none)test_reportvisits.php

searchpatient.bash

  • -1 - ERROR: Sorry, there was an error processing your data. Pleas re-submit the information again.
  • -2 - You are not Authorized to perform this action
  • -2 Invalid Token

mu3_get_ccda.bash


Same as getpatientrecord.php
mu3_get_generic.bash


Generic script used to implement the following convenience scripts.

The following convenience scripts are "dynamically linked" to mu3_get_generic.bash. Their actions are determined by checking the script name.

NOTE: The generated C-CDA files will include other sections due to requirements unrelated to MU3.

mu3_get_social

mu3_get_socialhistory

  • encounterId

C-CDA file including Social History section.

mu3_get_probs

mu3_get_problems

  • encounterId

C-CDA file including Problems section.

mu3_get_meds

mu3_get_medications

  • encounterId

C-CDA file including Medications/ Prescriptions(?) section.

mu3_get_allrgs

mu3_get_allergies

  • encounterId

C-CDA file including Med Allergies section.

mu3_get_labprc

mu3_get_labprocedures

  • encounterId

C-CDA file including Lab Procedures section.

mu3_get_labres

mu3_get_labresults

  • encounterId

C-CDA file including Lab Results section.

mu3_get_vitals

mu3_get_vitalsigns

  • encounterId

C-CDA file including Vital Signs section.

mu3_get_procs

mu3_get_procedures

  • encounterId

C-CDA file including Procedures section.

mu3_get_caretm

mu3_get_careteam

  • encounterId

C-CDA file including Care Team section.

mu3_get_immuns

mu3_get_immunizations

  • encounterId

C-CDA file including Immunizations section.

mu3_get_implts

mu3_get_implantabledevices

  • encounterId

C-CDA file including Implantable Devices section.

mu3_get_assmts

mu3_get_assessments

  • encounterId

C-CDA file including Assessments section.

mu3_get_trplan

mu3_get_planofcare

  • encounterId

C-CDA file including Care Plan section.
mu3_get_goals
  • encounterId

C-CDA file including Social History section.

mu3_get_cncrns

mu3_get_healthconcerns

  • encounterId

C-CDA file including Health Concerns section.

Setting up DrCloudEHR API

Installation

If you are installing this on a DrCloudEHR instance that includes the MU3 code, then you can find the API and test scripts in the ccr/ccd/mu3/directory.  


$ ls -l ccr/ccd/mu3/
total 332
drwxrwxr-x 3 jfo jfo   4096 Sep 18 17:45 api
drwxrwxr-x 4 jfo jfo   4096 Sep 19 13:06 drcloud
-rw-rw-r-- 1 jfo jfo  35147 Sep 18 17:02 license.txt
-rw-rw-r-- 1 jfo jfo 286711 Sep 18 17:02 Medmasterpro-API.pdf
drwxrwxr-x 3 jfo jfo   4096 Sep 18 17:02 openemr
-rw-rw-r-- 1 jfo jfo    317 Sep 18 17:02 README.md
$ ls -l contrib/mu3/openemr-api-master/drcloud
total 12
drwxr-xr-x 4 jfo jfo 4096 Sep 19 14:31 api
-rw-rw-r-- 1 jfo jfo 3272 Sep 19 12:50 README.ensoftek
drwxrwxr-x 2 jfo jfo 4096 Sep 19 16:32 tests
$

Unfortunately, both the api/ and tests/ directories need to be (recursively) copied into other locations.  The api/ directory must be copied to a top level directory, due to limitations in the implementation.   The tests/ directory should be copied into a directory in the user's home directory, or a directory that is writeable by the user.

initsetup.php

The initsetup.php script sets up the additional tables and columns needed to integrate the API into DrCloudEHR

http://<server:port>/<drcloud>/api/initsetup.php?site=<site-name>

https://<server:port>/<drcloud>/api/initsetup.php?site=<site-name>

https://test.drcloudemr.com/dc_ehr_qa/api/initsetup.php?site=jsmdpa


Create the test_settings.inc file

The test_settings.inc file is used to simplify the creation of test scripts.

There is a sample_test_settings.inc file that can be used as a template.

NOTE: $USERNAME and $PASSWORD are only used by test_login.php.  The test_login.php could be rewritten to require the user to pass the username and password on the command line.

test_settings.inc
<?php
# URL of the API directory.
$URL = "http://dc-xenial-02/dc_ehr_qa/api";
$USERNAME = "admin";
$PASSWORD = "demo";
$SITE = alpha;

Login to API

To "login" to the API, the user must run the "login.bash" script.  When you run this bash script, it will create the file token.inc, which contains token variable, $token.  This file, along with the test_settings.inc file, will be used by the other test_*.php scripts.  The token also contains the expiration timedate.   The expiration timedate is set whenever the user logs in.   It is currently set to the current time + one hour.  This is currently not configurable.  The API will check the expiration timedate every time it validates the token.

Running login.bash
bash ./login.bash

  or if the file has execute permissions, 
./login.bash

Terms of Use

This is a legal agreement ("Agreement") between you, the "User", and EnSoftek Inc ("Company").  BY ACCEPTING THIS AGREEMENT, YOU ARE CONSENTING TO BE BOUND BY ITS TERMS. Read the terms of the agreement here. 

Definitions

As used herein: the "Software" means the DrCloudEHR Application Programming Interface (API).

License Grant

All Users SHALL possess an active DrCloudEHR license agreement.   Use of this Software SHALL BE COVERED BY THE TERMS OF THAT LICENSE AGREEMENT.

Limitation of Liability

Limitation of Liability for this Software SHALL BE COVERED BY THE TERMS OF THAT LICENSE AGREEMENT.

License Restrictions

The Company may limit the number of persons that can use the Software.  

Usage

If you become aware of any unauthorized access or use of the Software, you shall immediately notify the Company.

  • No labels