How to Authorize REST API Integration for OSCAR
Documentation Copyright © 2024 by Adrian Starzynski
These instructions are general steps for connecting a 3rd party REST API integration with OSCAR EMR. Examples include: online booking systems, kiosk/registration systems, appointment reminder systems, etc.
1. You should create a dedicated provider and security record for each REST API integration (name the provider as the name of your integration – i.e. if the integration is a booking app called ABCD then name the provider as such). That way there is proper login (so you can tell who did what).
2. Once you create the provider record and security record for the provider, assign the role(s) to this provider user. Most integrations will require you to assign “doctor” as primary role and “admin” as secondary role.
3. REST modules need to be enabled on your OSCAR system if you don’t see options for “REST” under Administration>Integrations OR if it says “no service was found.”
Open a ticket with your OSCAR provider and ask them to enable the REST module (ModuleNames=REST) in the oscar.properties file.
See below email template:
“Hello to Oscar provider,
The REST API module must be enabled for our OSCAR system (in the oscar.properties file).
Please change the oscar.properties file as follows (with any other modules you need as well) and restart tomcat:## REST: enable restful web servicesModuleNames=REST
Thank you”
4. After REST is enabled, go to Administration>Integrations>REST Clients
5. Click “Add New”
6. Enter the name of the app that is integrating, the URI (the app will provide you what URI to enter), and a token lifetime. Normally the token lifetime is -1 which means it won’t expire.
7. Click “Add Client”
8. A Client Key and Client Secret will be generated for the application, which you will see in the table at the top. Copy the client key and secret and paste them into the integration.
9. The integration will require you to complete OAUTH authorization as the final step to connect OSCAR. Open a new incognito window in your browser, go to the integration’s OSCAR connection page, and follow the integration’s steps. After pressing the connect button you will be redirected to OSCAR EMR’s OAUTH authorization screen. You will need to login with the credentials you created for the integration provider and authorize the app. The reason why you have to use incognito mode is because if you’re already logged into another OSCAR user then the integration will connect as THAT already logged-in user, which is wrong because each integration should have it’s own login; when you open a new incognito window, there are no other logins that it can recognize so it will correctly prompt you to login with the credentials you created.