The OpenEMR API

From OpenEMR Project Wiki

Overview

The OpenEMR API is divided into many modules, few of which have been documented.

There is presently a documentation project underway. please see OpenEMR API for an overview.

Core API

globals.php

globals.php defines a series of global variables, most of which are editable via the 'Administration->Globals' page.

The prefered method of including globals.php is to use require_once, providing a relative path from where your file is located, to interface/globals.php. for instance: require_once('../../globals.php');.

The following variables are common to use everywhere in OpenEMR:

Variable Used For Default Value
$GLOBALS['athletic_team'] True if we need to check squads. part of 'sports team' functionality. False
$GLOBALS['concurrent_layout'] decide on target of back action in a form. True or False
$GLOBALS['encounter'] the ID of the current encounter, or empty for none. is_numeric() or ""
$GLOBALS['fileroot'] the path to the top of openemr in the filesystem. /var/www/openemr/
$GLOBALS['OE_SITE_DIR'] a per-site directory
$GLOBALS['phone_country_code'] calendar code.
$GLOBALS['pid'] The unique identifier of the current patient. is_numeric(), or empty.
$GLOBALS['srcdir'] find files for inclusion. $GLOBALS['fileroot']/library/
$GLOBALS['style']
$GLOBALS['temporary_files_dir'] A directory on the server for storing temporary files outside of the web-visible space. /tmp (on *nix), or C:/windows/temp (on windows)
$GLOBALS['webroot'] the path of the top of openemr, when generating URIs. /openemr/
$css_header include the global css stylesheet.
$tmore the text string that should be the label next to the page name, on a show form page.

The following variables are old, and depreciated.

Variable Use Reason for Depreciation Replaced By
$top_bg_line colour selection. The same function can be accomplished by editing the global openemr CSS stylesheet.
$srcdir find includes. Globals in the lowercase namespace are deprecated. $GLOBALS['srcdir']
$incdir find interface. Globals in the lowercase namespace are deprecated. $GLOBALS['fileroot']/interface

api.inc

The prefered method of including api.inc is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/api.inc');.

The following functions are common to use everywhere in OpenEMR:

acl_check()

This function is used to check if a user has a given type or types of access to an ACO(access control object).

Parameters

A category/subcategory describing a the ACO to which permission is being requested, and optionally the type or types of permissions being requested.

Returns

TRUE or FALSE if a single permission is being checked, or an array of TRUE/FALSE values coresponding to the types of permission requested.

auth.inc

auth.inc handles various functions, such as verification of the user's password, and implementing a timeout if the user has not been active in the interface.

It has a block of code starting at the begining of the file, that parses variables from the form submitted, and reacts accordingly. Important variables to note are:

skip_timeout_reset

Submit this item with your form to prevent the automatic timeout function from seeing your form as activity.

formdata.inc.php

formdata.inc.php includes functionality for safely handling form data from the web browser, either via POST, GET, or from a cookie.

The preferred method of including formdata.inc.php is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/formdata.inc.php');.

The following functions should be used in OpenEMR, in leiu using the _POST[], _GET[], and _REQUEST[] variables:

Function Use Accepts Returns
formData retrieve a variable from post, get, or cookie data submitted by the browser. The name of the variable requested, the type of data stream to look for it in (post, get, or request), and whether to use trim() against the data. A string containing the requested data, put through strip_escape_custom(), add_escape_custom() and (optionally) trim().

htmlspecialchars.inc.php

htmlspecialchars.inc.php includes functionality for handling escaping of characters in html received from the client, and stored in the database.

The preferred method of including htmlspecialchars.inc.php is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/htmlspecialchars.inc.php');.

The following functions should be used in OpenEMR, in leiu of calling htmlspecialchars:

Function Use Accepts Returns
text Escape a PHP string for use as (part of) an HTML / XML text node. The string to escape, possibly including "&", "<", or ">". The string, with "&", "<", and ">" escaped.

patient.inc

patient.inc includes functions for manipulating patient information.

The preferred method of including patient.inc is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/patient.inc');.

The following functions are common to use everywhere in OpenEMR:

Function Use Accepts Returns
getPatientData Get a patient's demographic data. A patient ID, and optionally a subsection of the patient's demographic data to retrieve. The requested subsection of a patient's demographic data. If no subsection was given, returns everything, with the date of birth as the last field.

sql.inc

sql.inc includes functions for manipulating the database directly. Please try to use one of the APIs and the built in functions for manipulating/retrieving your data, rather than always reaching for a SQL statement.

The preferred method of including sql.inc is to use require_once. for instance: require_once($GLOBALS['srcdir'].'/sql.inc');.

Function Use Returns
sqlInsert perform insert query the id of the newly inserted row.
sqlStatement perform query result of mysql_query
sqlQuery perform query result of mysql_fetch_array

Forms API

The Forms API includes all of the functions required to create both per-encounter and non-encounter forms in the OpenEMR system. see The Forms API for more information.

Notes API

The Notes API manages non-medical notes, attached to a client's medical record. See The Notes API for more information.

Reminders API

The Reminders API manages reminders, which can be sent to ones self or others, and may have a patient associated with them. See The Reminders API for more information.