OSCAR’s API

UpdatedJuly 5, 2023

ByAdrian Starzynski

Introduction

OSCAR supports REST and SOAP connections. However, you’ll need to use REST for performing some operations that require a higher security level. Also, it is recommended to only use the REST integration, because most OSCAR systems now have MFA/2FA and a requirement for PIN, meaning SOAP won’t work (since SOAP needs a login only with username/password and no PIN, and MFA also requires a unique code/push notification to be accepted, which won’t work with SOAP). REST also provides access to more web services and requires the app to be authenticated in OSCAR first via OAUTH.

OSCAR exposes it’s web services to authorized users only. Apps must be registered on the OSCAR it would like to integrate with and it’s not the app that “logs in”, it’s the provider. The provider will login directly into OSCAR, which will generate a token for the app to make further calls.

The protocol implemented in OAUTH 1.0a (https://oauth.net/core/1.0a/)

(OSCAR uses OAUTH 1.0a for REST authentication)

When setting up the OAUTH you may experience challenges around how the payload is encrypted. I believe it only works to use plaintext, or one of the various options.

REST and SOAP APIs

	SOAP	REST
Authentication	WS-Security	OAuth 1.0a
Data Format	Only XML.	Plain text, HTML, XML, JSON, YAML, and others.
Performance	Less reliable than REST and consumes more resources	Better performance and reliability compared to SOAP
Approach	Function-driven (data available as services, e.g.: “getAllergy”)	Data-driven (data available as resources, e.g. “user”).
Statefulness	Stateless by default, but it’s possible to make a SOAP API stateful.	Stateless (no server-side sessions).
Caching	API calls cannot be cached.	API calls can be cached.
Overall	High security, standardized, lower performance, more complexity, less flexibility.	Scalability, better performance, browser-friendliness, flexibility.

REST API Reference

The full OSCAR EMR REST API reference is available here.

Configuration

To configure your application to work with OSCAR via REST API, follow the steps¹:

1. Enable the REST API in OSCAR for connecting apps. In the oscar.properties file of the OSCAR system, find the line “ModuleNames=” and add REST to it. If it does not exist simply add like below (or just uncomment the line if it exists commented):
ModuleNames=REST
(then restart Tomcat)

2. Register the app with OSCAR through the Administration interface.
Go to Administration>Integration>REST Clients

3. Click “Add New“
Enter a valid URI for the application (must be the base URL of your web application), and a Token Lifetime. You can enter a Token Lifetime of -1 if the token shouldn’t expire (this is the most common setting for integrations).

4. Use the Client Key and Client Secret in your app’s OAUTH initialization.

Sample OAUTH 1.0a Workflow¹

1. Client makes a REST call including proper “Authorization” header. (for example: https://example.com/oscar/ws/services/providerService/providers_json)

2. OSCAR will either return the results of the call (regular 200 HTTP status) or a 401 requiring the user to authorize with OSCAR first. Assuming we get the 401,

3. Client will initiate the OAUTH 1.0a flow by calling initiate (https://example.com/oscar/ws/oauth/initiate). Make sure the client properly manages any cookies as well. This call will also include the callback URL to your application. This will get called when the OAUTH workflow is completed. This will return you a Request Token.

4. Client now redirects user to https://example.com/oscar/ws/oauth/authorize?oauth_token=<request_token>.

5. User authorizes with OSCAR

4. User is redirected to the Callback URL of your application (specified in the initiate, and must be within the URI of the registered application). The URL will have parameters for the oauth_token and oauth_verifier.

5. Client requests an access token from https://example.com/oscar/ws/oauth/token

6) Client makes REST calls using Authorization header with access token.

Full List of Web Services

Whether you’re developing a SOAP or REST integration with OSCAR, you can go to your OSCAR server URL /ws to see the WSDL and WADL files for all the services offered on that particular OSCAR version. OSCAR vendors have added their own additional features/fixes to their version’s API.

Example: https://example.com/oscar/ws

For a zip file with the example WADL files of the RESTful services click here

Click the above link to get the WADL files that describe the REST services available on most OSCAR versions. Some vendors have added additional functionality/endpoints (check your OSCAR system’s /oscar/ws link for the exact specifications for your version).

REST Services

OSCAR offers a multitude of RESTful web services.

Here is the standard list of RESTful web services that are available in 99% of all OSCAR systems:

-App
/app/getApps

-Billing
/billing/uniqueServiceTypes
/billing/billingRegion

-Consultation
/consults/searchRequests
/consults/getRequest
/consults/getRequestAttachments
/consults/saveRequest
/consults/searchResponses
/consults/getResponse
/consults/getResponseAttachments
/consults/saveResponse

-DemographicMerge
/demographics/merge

-Demographic
/demographics
/demographics/{id}
/demographics/ POST/DELETE
/demographics/quickSearch
/demographics/search
/demographics/searchIntegrator

-Forms
/forms/{demo}/all
/forms/allEForms
/forms/selectedEncounterForms
/forms/{demo}/completedEncounterForms
/forms/groupNames
/forms/getK2AEForm

-Inbox
/inbox/mine

-Messaging
/messaging/unread
/messaging/count

-Notes
/notes/{demo}/all
/notes/{demo}/tmpSave
/notes/{demo}/save
/notes/{demo}/saveIssueNote
/notes/{demo}/getCurrentNote
/notes/getIssueNote/{noteId}
/notes/getGroupNoteExt/{noteId}
/notes/getIssueId/{issueCode}
/notes/ticklerGetNote/{ticklerNo}
/notes/ticklerSaveNote

-OscarJob
/jobs/type/current
/jobs/types/all
/jobs/all
/jobs/{jobId}
/jobs/saveJob
/jobs/cancelJob
/jobs/saveCrontabExpression
/jobs/saveJobType
/jobs/enableJob
/jobs/disableJob

-Patient Detail Status
/patientDetailStatusService/getStatus
patientDetailStatusService/validateHC

-Persona
/persona/rights
/persona/hasRight
/persona/hasRights
/persona/navbar
/persona/setDefaultProgramInDomain
/persona/patientLists
/persona/preferences
/persona/updatePreferences

-Pharmacy
/pharmacies
/pharmacies/{pharmId}
/pharmacies (POST/PUT/DELETE)

-Product Dispensing
/productDispensing/saveDrugProduct
/productDispensing/drugProduct/{id}
/productDispensing/drugProducts
/productDispensing/drugProductsByCode
/productDispensing/drugProducts/uniqueNames
/productDispensing/drugProducts/uniqueLots
/productDispensing/deleteDrugProduct/{id}
/productDispensing/productLocations
/productDispensing/status/{drugId}
/productDispensing/drugProductTemplates

-Program
/program/patientList
/program/programList

-Provider
/providerService/providers
/providerService/provider/{id}
/providerService/provider/me
/providerService/providers/search
/providerService/getRecentDemographicsViewed
/providerService/getActiveTeams
/providerService/settings/get
/providerService/settings/{providerNo}/save

-RecordUX
/recordUX/{demo}/recordMenu
/recordUX/{demo}/summary/{summaryName}
/recordUX/{demo}/getFamilyHistory
/recordUX/{demo}/getMedicalHistory
/recordUX/{demo}/getOngoingConcerns
/recordUX/{demo}/getOtherMeds
/recordUX/{demo}/getReminders

-Reporting
/reporting/demographicSets/list
/reporting/demographicSets/demographicSet/{name}
/reporting/demographicSets/patientList
/reporting/eformReportTool/list
/reporting/eformReportTool/add
/reporting/eformReportTool/populate
/reporting/eformReportTool/remove
/reporting/eformReportTool/markLatest

-RSS Feed
/rssproxy/rss

-Schedule
/schedule/day/{date}
/schedule/statuses
/schedule/add
/schedule/getAppointment
/schedule/deleteAppointment
/schedule/updateAppointment
/schedule/{demo}/appointmentHistory
/schedule/appointment/{id}/updateStatus
/schedule/appointment/{id}/updateType
/schedule/appointment/{id}/updateUrgency
/schedule/fetchMonthly/{providerNo}/{year}/{month}
/schedule/types

-Status
/status/checkIfAuthed

-Tickler
/tickler/search
/tickler/mine
/tickler/ticklers
/tickler/complete
/tickler/delete
/tickler/update
/tickler/textSuggestions
/tickler/add

SOAP Services

This page lists all the available SOAP services in OSCAR

OSCAR Source Code REST Java Files

For those who wish to review OSCAR’s Java source code files for the REST endpoints:

oscaremr / oscar / src / main / java / org / oscarehr / ws / rest — Bitbucket

Credits

1. Part of the REST configuration and Sample OAUTH Workflow is from Marc Dumontier’s original article “Connecting to OSCAR’s REST API” (publish date unknown)

Tags: