Web Launch

When an EMR uses SMART Launch through the EMR or Standalone, it calls a page on your web application, which handles the request, authorizes your webapp, and redirects to a pre-determined page.

EMR Authorization

The following is an example of a function to handle the SMART Launch. I.e., when the browser launches the application, it must be directed to the page that runs the following. E.g., this could be https://www.yourwebsite.com/launch

Example function with optional secret

import { LAUNCH, SmartLaunchHandler } from "@topologyhealth/smarterfhir";

async function handleWebLaunch() {
  try {
    const emrClientID = YOUR_EMR_CLIENT_ID;
    const emrClientSecret = EMR_CLIENT_SECRET; // OPTIONAL -> Only Required if your EMR Authentication was registered with a Secret
    const redirectPath = "/redirectUriPath"; // Tells the Launch where to redirect the browser after successful launch. Must be a valid registered URI
    const smartLaunchHandler = new SmartLaunchHandler(
      emrClientID,
      emrClientSecret
    ); // If no secret, use 'new SmartLaunchHandler(emrClientID)'
    await smartLaunchHandler.authorizeEMR(LAUNCH.EMR, redirectPath); // If Standalone, use 'await smartLaunchHandler.authorizeEMR(LAUNCH.STANDALONE)'
  } catch (e) {
    if (e instanceof Error) console.error("WebLaunch failed", e);
    console.error("Unexpected Error", e);
  }
}

Here's a list of the relevant dynamic properties:

Name
emrClientID
Description
Pass in the Client ID of the EMR Client that you want to connect to.
Name
emrClientSecret
Description
Pass in the Client Secret of the EMR Client that you want to connect to.
Name
SmartLaunchHandler
Description
Our Handler Object. Used mainly with authorizeEMR() to authorize the app and redirect accordingly.

Standalone Launch Details

Relevant if using Standalone Launch.

When running handleWebLaunch for Standalone Launch, an iss query parameter must be passed to the webpage.

To aid in simplicity, you can use this example button that navigates to the page that runs handleWebLaunch and passes in the appropriately required iss:

Example button: Initiates standalone launch

import { ClientUtils } from "@topologyhealth/smarterfhir";

<button onClick={startStandaloneLaunch}>
  {"Execute Standalone Launch"}
</button>;

const startStandaloneLaunch = () => {
  const emrType = YOUR_REACT_APP_EMR_TYPE.toLowerCase() as EMR; // YOUR_REACT_APP_EMR_TYPE must be set to 'EPIC' or 'CERNER' (More EMRs to come!)
  const emrEndpoints = ClientUtils.getEndpointsForEmr(emrType);
  const iss = emrEndpoints.r4.toString(); // Defaults to the EMR sandbox endpoint for testing.
  const pathname = "/standalonelaunch" // This pathname should make a request to the page that runs 'handleWebLaunch'
  const search = `iss=${encodeURIComponent(iss)}`
  window.location.href = `${pathname}?${search}`;
};

SMART Client

The following is an example of a function to instantiate the SMART Client after SMART Launch has completed. During SmartLaunch, the EMR will authenticate your application. Once completed, it will redirect to the assigned redirect path. The code below should be set to run upon successful authentication and redirect:

import { ClientFactory, LAUNCH } from "@topologyhealth/smarterfhir";

async function mySmartClientInstantiator() {
  try {
    const clientFactory = new ClientFactory();
    const client = await clientFactory.createEMRClient(LAUNCH.EMR); // If Standalone, use 'await clientFactory.createEMRClient(LAUNCH.STANDALONE)'
    if (!client) throw new Error("no client found");
    return client;
  } catch (reason) {
    if (!(reason instanceof Error)) console.error("Unknown Error", reason);
    if (
      reason.message.includes(
        "No 'state' parameter found. Please (re)launch the app."
      ) ||
      reason.message.includes("Could not find any JWT token") ||
      reason.message === NO_CODE
    ) {
      return console.log("No EMR connection established.");
    }
    if (reason.message.includes("User is not available"))
      return console.log("Waiting for Web Launch...");
    console.error(reason.message);
  }
}

Here's a list of the relevant dynamic properties:

Name
clientFactory
Description
Object for creating new EMRClients post-SMART authentication.
Name
client
Description
Client object for performing operations against the EMR for writing/receiving data.