OSCAR’s API

UpdatedFebruary 6, 2024

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.

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

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)

The full OSCAR EMR REST API reference is available here.

OSCAR EMR REST API REFERENCE

NOTE:

Every demographic record must have a parallel admission record. The programID is used when there are multiple clinics. It’s part of the old CAISI code.

The programID comes from the program table.
select id from program where name = ‘oscar’;
It’s usually 10016 by default. When creating demographic through REST API, you may need to adjust this to the id from the query that other demographics have, otherwise it won’t be viewable by users in OSCAR.

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.

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

Note that some OSCAR versions have slightly different content-type requirements for certain endpoints. For example, some OSCAR systems only accept content-type:application/xml for some endpoints while others have been updated to accept content-type:application/json. You can find out based on the OSCAR version’s REST Java Files.

OSCAR Source Code REST Java Files

OSCAR 19’s Java source code files for the REST endpoints:
oscaremr / oscar / src / main / java / org / oscarehr / ws / rest — Bitbucket

Full List of Web Services

Whether you’re developing a SOAP or REST integration with OSCAR, you can go to your OSCAR server base URL /ws to see the WSDL (SOAP API definition) 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).

SOAP Services

This page lists all the available SOAP services in OSCAR.

OSCAR publishes SOAP WSDL’s so you’re able to generate stubs off those (https://example.com/oscar/ws). Standard SOAP data types and (only standard SOAP types) are used and WS-Security is used for security. You can import the WSDL’s to Postman for testing, but the request bodies will need some modifications.

The web service endpoints are stateless so you need to set the WS-Security for each request made.

The SOAP web services are intended for server to server communications, not server to browser.

These SOAP services are intended to be compatible with all programming languages (so don’t try and send java.util.Collections objects like List or Map, they will not unmarshall properly in different frameworks).

For versioning of methods and transfer objects, the latest version number is appended to the method/object name, i.e. login(), login2(), login3() etc. In general you should use the latest / largest version number of any method or object that you can find. The older methods and objects are deprecated.

OSCAR uses Apache CXF for the SOAP implementation.

OSCAR 19’s Java source code files for the SOAP endpoints:
oscaremr / oscar / src / main / java / org / oscarehr / ws — Bitbucket

SOAP Authentication

Authentication validation is done on a per-request basis against the Security table on the ID and password (not username). This is for efficiency purposes and immutability purposes of the ID. To get the ID some one can always use the LoginWs first which should supply you with the ID from the username. The LoginWs may also provide you with a security token which can then be used in place of the password.²

Sample getDayWorkSchedule SOAP API request

Here’s a sample SOAP API request to get a provider’s schedule availability with template codes (getDayWorkSchedule) as there is no endpoint for this action in the REST API. This is the endpoint that online booking systems use to query when a provider is available for booking, for example.

HTTP POST https://localhost/oscar/ws/ScheduleService
Headers: Content-type:text/xml; charset=utf-8

Request Body:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ws="http://ws.oscarehr.org/" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <soap:Header>
        <wsse:Security>
            <wsse:UsernameToken>
                <wsse:Username>{{LoginSecurityRecordNo}}</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">{{LoginPassword}}</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soap:Header>
    <soap:Body>
        <ws:getDayWorkSchedule>
            <arg0>2</arg0>
            <arg1>2024-01-19T00:00:00</arg1>
        </ws:getDayWorkSchedule>
    </soap:Body>
</soap:Envelope>

Notes:

{{LoginSecurityRecordNo}} needs to be replaced with the security_no – this is the ID of the login user from the security table (find it by running DB query: select * from security) | OR you can get it from the LoginWs (will return securityId)
{{LoginPassword}} needs to be replaced with the password of the user you’re logging in with (the user from security_no) | OR you can use LoginWs which will return securityTokenKey from username and password supplied

Sample Response for getDayWorkSchedule

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:getDayWorkScheduleResponse xmlns:ns2="http://ws.oscarehr.org/">
            <return>
                <holiday>false</holiday>
                <timeSlotDurationMin>15</timeSlotDurationMin>
                <timeSlots>
                    <date>2024-01-19T09:00:00-08:00</date>
                    <scheduleCode>49</scheduleCode>
                </timeSlots>
                <timeSlots>
                    <date>2024-01-19T09:15:00-08:00</date>
                    <scheduleCode>49</scheduleCode>
                </timeSlots>
                <timeSlots>
                    <date>2024-01-19T09:30:00-08:00</date>
                    <scheduleCode>49</scheduleCode>
                </timeSlots>
                <timeSlots>
                    <date>2024-01-19T09:45:00-08:00</date>
                    <scheduleCode>49</scheduleCode>
                </timeSlots>
                <timeSlots>
                    <date>2024-01-19T10:00:00-08:00</date>
                    <scheduleCode>49</scheduleCode>
                </timeSlots>
            </return>
        </ns2:getDayWorkScheduleResponse>
    </soap:Body>
</soap:Envelope>

Notes:

getDayWorkSchedule returns the available timeslots for the provider based on template codes (scheduleCode) configured in the schedule template for that day
The template codes are returned in ASCII format
- Ex: <scheduleCode>49</scheduleCode> means the template code is 1 because 49 represents 1 in ASCII

Sample login2 SOAP API request

HTTP POST https://localhost/oscar/ws/LoginService
Headers: Content-type:text/xml; charset=utf-8

Request Body:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <login2 xmlns="http://ws.oscarehr.org/">
      <arg0 xmlns="">{{LoginUsername}}</arg0>
      <arg1 xmlns="">{{LoginPassword}}</arg1>
    </login2>
  </soap:Body>
</soap:Envelope>

Sample Response for login2

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>
        <ns2:login2Response xmlns:ns2="http://ws.oscarehr.org/">
            <return>
                <provider>
                    <address></address>
                    <billingNo></billingNo>
                    <comments></comments>
                    <dob>0001-01-01T00:00:00-08:00</dob>
                    <email></email>
                    <firstName>doctor</firstName>
                    <hsoNo></hsoNo>
                    <lastName>oscardoc</lastName>
                    <ohipNo></ohipNo>
                    <phone></phone>
                    <practitionerNo></practitionerNo>
                    <practitionerNoType></practitionerNoType>
                    <providerActivity></providerActivity>
                    <providerNo>999998</providerNo>
                    <providerType>doctor</providerType>
                    <rmaNo></rmaNo>
                    <sex></sex>
                    <signedConfidentiality>0001-01-01T00:00:00-08:00</signedConfidentiality>
                    <specialty></specialty>
                    <status>1</status>
                    <team></team>
                    <title></title>
                    <workPhone></workPhone>
                </provider>
                <securityId>128</securityId>
                <securityTokenKey>5778187650930</securityTokenKey>
            </return>
        </ns2:login2Response>
    </soap:Body>
</soap:Envelope>

Notes:

You can use the securityId and securityTokenKey returned for the WS-Security authentication in your SOAP requests (wsse:Username, wsse:Password). OR you can just supply the security_no and password of the user.
There is also an older endpoint ‘login’ which only returns securityId and securityTokenKey, without any other information about the provider.

Credits

Part of the REST configurationm Sample OAUTH Workflow, some info on Oscar’s SOAP is from Marc Dumontier’s original article “Connecting to OSCAR’s REST API” (publish date unknown).
oscaremr / oscar / src / main / java / org / oscarehr / ws / OscarUsernameTokenValidator.java — Bitbucket

The rest is by Adrian Starzynski

Tags:

OSCAR’s API

Introduction

REST and SOAP APIs

REST API Reference

Configuration

Sample OAUTH 1.0a Workflow1

REST Services

OSCAR Source Code REST Java Files

Full List of Web Services

SOAP Services

SOAP Authentication

Sample getDayWorkSchedule SOAP API request

Sample Response for getDayWorkSchedule

Sample login2 SOAP API request

Sample Response for login2

Credits

Sample OAUTH 1.0a Workflow¹