A starter application for integrating the Medplum platform with Photon Health.
This example app demonstrates the following:
- Creating a new React app with Vite and TypeScript
- Syncing your patients to your Photon project
- Syncing your drug formulary or catalog to your Photon project. For more details on formularies, see the Modeling a Formulary docs
- Writing prescriptions and medication orders in Photon from within your Medplum project
This demo is organized into two main directories: src and data.
The src directory contains the React app that implements the prescription UI. In addition it contains a bots directory, which has Medplum Bots to implement syncing patients, syncing your formulary, and receiving webhooks from Photon.
The data directory contains sample data that can be uploaded for use in the demo app.
If you haven't already done so, follow the instructions in this tutorial to register a Medplum project to store your data.
Fork and clone the main Medplum repo.
Move into the medplum-photon-integration directory
cd examples/medplum-photon-integrationNext, install the dependencies
npm installThen, run the app
npm run devThis app should run on http://localhost:3000/
To use this app, you will also need to sign up for a Photon Health account, which can be done here.
This app interfaces with Photon's sandbox environment, called Neutron Health. Follow their Getting Started guide to set up a Neutron App project.
Once your Neutron project is created, you will need to set up credentials for the following items to ensure it works properly with Medplum:
- Photon Auth Token
- Photon Elements
- Photon Webhooks
This app reads and writes from Neutron's API, which requires the auth token from your Nuetron project. Authentication is handled by bots, but the necessary secrets must be set up in your Medplum project.
These credentials can be accessed in your Neutron project by navigating to your project settings and clicking on the Developers Tab. Copy the Client ID and Client Secret from the Machine to Machine Application section. If this section does not appear in your settings, you will need to reach out to Photon Support at support@photon.health to ensure that it is properly set up.
Once you have copied your Client ID and Client Secret you will need to add these as secrets in your Medplum project. This can be done in the Medplum App. Navigate to admin page by clicking on Project in the Admin section of the sidebar. In the Secrets tab, click Add Secret and create secrets for your Client ID and Secret with names of PHOTON_CLIENT_ID and PHOTON_CLIENT_SECRET. These names are used in this app to access these values, so if you use different names, you will need to manually update the code to reflect your own names.
To enable Photon Elements you will need the Single Page Application Client ID and the Organization ID from your Neutron project. These can be found in the settings section of the Neutron App. The Client ID is found in the Single Page Application section of the Developers tab, while the Organization ID is found in the Organization tab.
Copy these values into the corresponding variables in the config file in this project's src directory. These values will link Photon elements to your project, allowing you to log in and authenticate to create prescriptions from within this demo.
This demo listens for webhooks from Photon Health and executes bots when an order or prescription is created or updated. This requires setting up the webhooks in your Neutron project using information from your Medplum project.
Note: Your bots must be deployed and uploaded to your Medplum project prior to setting up webhooks.
To set up webhooks, access the Neutron App and navigate to the Developers tab of the Settings page. At the bottom of the page is a Webhooks section. Click on Add Webhook to open a modal that will allow you to set up your webhooks.
The Payload URL should be the execute endpoint for the bot that will handle this webhook. This is formatted as https://<client-application-id>:<client-secret>@api.medplum.com/fhir/R4/Bot/<bot-id>/$execute. The client application ID and client secret in this url refer to your Medplum application ID and client secret. These can be found in the Medplum App in the details for your ClientApplication resource. Note that only admins can access this resource. For more details on the execute endpoint see the Bot Execute docs.
The Secret can be any string, but it is recommended to use a UUID. Medplum currently does not pass along the webhook header to the executing bot. Because of this, this secret will not be used to verify the event. In the future, this will be updated to include the header so we can verify webhooks as they come through. Since this is not used, you can set the secret to an empty string if you wish.
In the events section, select Let me select specific events. This demo implements two bots: one for prescription events and one for order events. For your order events bot, select all of the events corresponding to orders. For the prescription bot, select all prescription events except for the photon:prescription:active event. This is an uncommon edge case that is not supported by this demo.
Medplum is an open-source, API-first EHR. Medplum makes it easy to build healthcare apps quickly with less code.
Medplum supports self-hosting, and provides a hosted service. Medplum Hello World uses the hosted service as a backend.
- Read our documentation
- Browse our react component library
- Join our Discord