Search the OSCAR Documentation
< All Topics
Print

OSCAR’s API

Updated
ByAdrian Starzynski
Share this

Documentation Copyright © 2023 Adrian Starzynski. Some content from other creators see Credits

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.

This article will focus on OSCAR’s REST API.

Read more about SOAP vs. REST

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.

Configuration

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

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 Workflow1

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

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:
Table of Contents