iMedRIS offers a REST (Representational State Transfer) API (Application Program Interface) to provide read-only access for querying iRIS™ data via SQL (Standardized Query Language). The iRIS™ REST API employs both server side and client side components.

On the iRIS™ server side, a system administrator defines SQL queries to be made available to the client side via internet-accessible REST API endpoints.

On the client side, the institution supplies a REST-compatible application or script to access the data sets returned by the iRIS™ system administrator’s SQL queries. The client-side software can only access data exposed by the pre-defined SQL queries, but the software can be used to filter, group or format the incoming data as desired. Data access on the client side can be further limited by user login.

This manual describes configuration, functionality and operation of the iRIS™ REST API in full detail.

REST API Prerequisites

iRIS™ configuration changes are required at the server level to enable access to the REST API.

After those changes are made iMedRIS personnel must update iRIS™ System Setup Reserved Settings to expose the Search API Setup page, where queries to be accessed via the REST API are defined.

An iRIS™ system administrator or designee must define the SQL queries to be accessed via the REST API and communicate the final query names and required parameters to whomever will be managing the client-side process.

Finally, the institution must provide its own client-side software to pass required parameters to the REST API, query the REST API endpoint, and receive data sets from the API.

iRIS™ System Requirements

Changes must be made to the institution’s iRIS™ server configuration and Reserved Settings under iRIS™ System Setup to enable access to the REST API.

iRIS™ Server Configuration Changes

The web.xml file supplied with each iRIS™ installation sets certain environment variables. Individual system configurations can vary but the web.xml file is most often located in the ROOT > WEB.INF folder on the server where iRIS™ is installed.

iMedRIS uses the Java GlassFish servlet for its REST API implementation. By default, code that enables GlassFish is commented out in the web.xml file provided by iMedRIS because GlassFish consumes system resources and is only needed at institutions where external interface functionality is implemented.

In order to enable GlassFish, iMedRIS personnel or the institution’s own IT department personnel must uncomment the web.xml code section shown below and save the file with changes.

iRIS™ Reserved Settings Changes

In the iRIS™ system under System Administration > System Configuration > Reserved Settings, the system.use_iRIS_Data_Feed_API_Setup property must be set to “Yes”.

This property is set to “No” by default and can only be changed by designated iMedRIS personnel.

iRIS™ System Setup Changes

After the system.use_iRIS_Data_Feed_API_Setup property is set to “Yes”, a new Search API Setup menu item appears in the Other Configuration(s) section on the System Setup tab of the List Configuration and Maintenance page under System Administration.

iRIS™ System Administration Requirements

The REST API client-side software is only granted access to data sets returned by SQL queries that are defined in the iRIS™ system. Those queries must be created by an iRIS™ system administrator or designee.

The person given responsibility for query definition and maintenance must have a thorough knowledge of iRIS™ system table definitions and intermediate to advanced SQL skills. That person should also employ a REST API testing tool (e.g. SoapUI®, Postman, etc.) to validate their SQL queries.

Search API Setup

Click the Search API Setup link (System Administration > List Configuration and Maintenance > [Other Configuration(s) section]) to begin.

The Search API Setup page opens. This is where queries that define the data sets made available through the REST API are created and maintained.

Previously created queries are listed on the page. The first time the page is accessed the query list is blank, as there are no default queries defined.

Add a Query

Click the Add Query button to add a SQL query. The Add New Query panel opens.

The Authentication Settings section contains fields for Allowed IP’s and Required Headers (system credentials).

The Allowed IP’s field defaults to 0.0.0.0, indicating that any IP (Internet Protocol) address will be allowed to access the endpoint for this query. To limit access to this query by IP address, enter the IP address(es) to which access is granted. Separate multiple IP addresses with a comma ( , ).

The Required Headers (system credentials) field is used for login authentication to the endpoint for this query.

If the field is left blank client-side login will be authenticated with the iRIS™ login credentials of the account running the client-side process. The result set will be limited to records and forms to which the iRIS™ account has access within the iRIS™ system. This is the default, basic authentication method.

To authenticate with explicit credentials, enter desired variables to serve as receptacles for login key(s) and password(s) that will be passed from the client side, as demonstrated in the help text to the right of the field: Use pattern key1=pass1,key2=pass2. This is a useful option for sharing endpoint data with non-users of iRIS™.

An incoming “key” value corresponds to a username or user id and an incoming “pass” value corresponds to the associated password for the user. To allow for explicit authentication by multiple client-side users, enter multiple key/pass pairs separated with a comma ( , ). Variable names chosen for key/pass pairs must be communicated to whomever will be managing the client-side process.

The API Index field is an internal tracking number assigned to each query by the iRIS™ system administrator. The API Index assigned to each query must be unique, and dictates the order in which queries are listed on the Search API Setup page.

The Query Name field is used to assign a name to the query. The query name must be communicated to whomever will be managing the client-side process.

Enter the desired top-level SQL query in the Insert query here: text field.

In the example below the form is filled, but the SQL query is incomplete because it requires a parameter input from the client side.

Click the Insert API MergeCode button to create and add a parameter variable field to the query. A new section is exposed at the bottom of the query text field.

Select the applicable data type for the parameter by clicking on it in the Data Type: dropdown. This data type must be communicated to whomever will be managing the client-side process.

Enter the desired parameter variable name in the MergeCode: field. This name must be communicated to whomever will be managing the client-side process.

Click in the query text field to place the cursor where the MergeCode is to be inserted, then click the Add button. In the example shown below a MergeCode parameter variable named “INT_user_ID” of Data Type “Single Integer/Number” is to be inserted where the cursor is currently located in the query text field.

In the example below the Add button was clicked and the MergeCode “INT_user_ID” was added to the query.

Note that the curly braces surrounding the inserted MergeCode are automatically added by the system, and were not included in the name entered into the MergeCode field.

Click the Save button at the bottom of the page (shown in previous screenshots) to save the query.

The new query is now listed on the Search API Setup page.

Click the Edit button to open the query for editing.

Click the Delete button to delete the query. A confirmation popup window appears.

Click the CONFIRM button in the popup to confirm deletion.

Click the CANCEL button in the popup to return to the Search API Setup page without deleting the query.

Add a Subquery

Subqueries can be added to refine or expand the data set returned by the first, top-level query. With a top-level query entered or opened for editing, click the Add Sub Query button to add a subquery.

A subquery form is opened.

The subquery form is indented to visually indicate it is a child query. In this case, the parent is the first, top level query, as represented in the hierarchy fields Parent:, Current:, Level: and Order:.

The Parent: value displays a concatenated string consisting of:

parent query level + parent subquery level (if any) _ + parent query order

In this case the parent query level is “1”, there is no parent subquery, and the parent query order is “1”, so the string reads “1_1”.

The Current: value displays a concatenated string consisting of:

parent query level + current (subquery) level + current sub-subquery level (if any) + _ + current (subquery) order

In this case the parent query level is “1”, the current subquery level is “2”, there is no sub-subquery, and the order of the current subquery is “1”, so the string reads “12_1”.

The Level: value displays the level of the current subquery in the overall query hierarchy. In this case the level of the current subquery is “2” so the field reads “2”.

The Order: value displays the order of the current subquery within its level. In this case the level of the current subquery is “1” so the field reads “1”.

In the example shown below the system administrator wishes to include forms in the result set for users identified in the first, top-level query.  

As indicated by the note at the bottom of the subquery text entry field, the subquery must include a filter that exists in the parent query and that filter must be wrapped in double curly braces. Red arrows in the screenshot demonstrate that the filter SYSTEM_STUDY_ID from the parent query is being used for record selection by the subquery.

The subquery above is named “forms” and uses “SYSTEM_STUDY_ID” as its filter from the parent query.

Click the Cancel button to close the form without saving the subquery.

Click the Save button to add the subquery to the parent query. The Search API Setup page now displays a plus sign icon to the left of the query name, indicating it has one or more subqueries.

Click the plus sign icon to expand subquery details.

Subquery details are displayed. All subqueries associated with the parent query will be shown here.

Note that Edit and Delete buttons are provided at the level of the parent query. Subqueries cannot be edited or deleted directly due to potential negative impacts on data dependencies across the overall query hierarchy. The parent query must be opened for editing in order to edit or clear any of its subqueries.

Query / Subquery Hierarchy

Note the location of the Add Sub Query buttons in the Add Query / Edit Query panel.

Clicking an Add Sub Query button adds a subquery at the level of the query where that button is located.

To add a subquery to the top-level query, click the Add Sub Query button to the right of the top-level query. In the example shown above, this will add a second level 2 subquery, with hierarchy details of Parent: 1_1, Current: 12_2, Level: 2 and Order: 2.

To add a subquery to an existing subquery, click the Add Sub Query button to the right of the existing subquery. As shown below a form is opened to add a new level 3 subquery, with hierarchy details of Parent: 12_1, Current: 123_1, Level: 3 and Order: 1.

Notice that there is no Add Sub Query button available at level 3, subqueries can only be added at levels 1 and 2 of the hierarchy.

Subquery Limitations

Because the result set can get very large very quickly when querying iRIS™ data, there are limitations on subqueries.

A maximum total of 10 subqueries can be added to the top-level query, including sub-subqueries.

This means that if four subqueries are added to the top-level parent query, a maximum of six additional subqueries can be added. These can all be level two subqueries, they can all be level 3 sub-subqueries, or they can be a mix of subqueries and sub-subqueries.

iRIS™ System Administrator Responsibility to Client Side

The iRIS™ system administrator or designee has a responsibility to share query details and parameter requirements with the party responsible for managing client-side operations and processing.

The client side must know, or have access to, all top-level query names, login credentials required for each query, and all MergeCode (parameter variable) names and associated data types for each query.

Any time a query is deleted or edited in a manner that impacts on client-side requirements, the iRIS™ system administrator is responsible for promptly notifying the client side. Ideally, the system administrator and client side personnel should work together to coordinate any such changes.

Client-Side Requirements

The iRIS™ REST API serves endpoints for querying iRIS™, but it has no client-side interface for passing parameters to the API nor for receiving its output. The institution must build or otherwise supply its own client-side software to perform those tasks. iMedRIS does not require nor recommend any specific application or tool, but the client-side software must be able to parse and output JSON (JavaScript Object Notation) name:value pairs.

REST API Endpoint for Data

The REST API endpoint for data is https://[client.com]/sysinterface/searchapis/deepsearch/{qryName}, where [client.com] is the base URL for the institution’s iRIS™ installation.

The {qryName} value is supplied by the iRIS™ system administrator. Note that the query name is the only parameter passed in the URL itself. Any required MergeCode variable parameters or explicit login credentials must be passed by the code employed to query the data endpoint from the client side.

REST API Endpoint for Forms

The REST API endpoint for forms is https://[client.com]/sysinterface/searchapis/documents/{docType}/{docIndex}, where [client.com] is the base URL for the institution’s iRIS™ installation.

The {docType} and {docIndex} values are supplied by the iRIS™ system administrator. Note that {docType} and {docIndex} are the only parameters passed in the URL itself. Any required MergeCode variable parameters or explicit login credentials must be passed by the code employed to query the forms endpoint from the client side.