Share via

Launch Dragon Copilot using token authentication

This API displays the Dragon Copilot user interface in your EHR after validating an authentication token.

Base URL

HTTP requests to the Dragon Copilot integration service use the following base URLs, depending on the region you connect to:

Region Base URL
US https://dragon-ehr.copilot.us.dragon.com
Canada https://dragon-ehr.copilot.ca.dragon.com/
France https://dragon-ehr.copilot.fr.dragon.com/
Germany https://dragon-ehr.copilot.de.dragon.com/
UK https://dragon-ehr.copilot.uk2.dragon.com/

The previous base URL for the US region is deprecated and should not be used: https://ehr-integration.copilot.dragon.com.

Dragon Copilot endpoint

To launch the web UI, send an HTTP POST request to the following endpoint:

/api/{ehr}/token-launch

Access token requirements

For information on the access token requirements, see: App authentication.

If you're using Microsoft Entra as your identity solution to generate an access token, the authentication scope must be:

40d36082-d340-492f-a5af-e42ef68f4b2b/Connector.Access

Customizable access token claims

Some of the access token claims are customizable. As part of the onboarding process, you can share information on claims you would like to customize and we can configure those claims accordingly. Each of these claims is optional; you may choose to ignore or exclude these claims. If the claims aren't provided, Dragon Copilot looks for the default claim name.

App config Default claim name
UserEmailClaim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
UserFirstNameClaim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
UserLastNameClaim http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

Request parameters

Type Name Required Description Schema
URL ehr Yes The name of the EHR system making the call. This value is agreed with Microsoft as the identifier of your EHR app when you onboard to Dragon Copilot. Once agreed, Microsoft needs to configure this value before it can be used. String

Request body

Send the body as Form URL Encoded, with the key as "data" and the value as a JSON structure represented by the following fields:

Name Required Description
firstName No The user's first name.
lastName No The user's last name.
email No The user's email address.
partnerId Yes The Microsoft-defined identifier of the product for which the session is being created.
orgId Yes The Microsoft-defined identifier of the customer for whom the session is being created.
correlationId Yes The globally unique identifier for a session that's specific to the partner system and helps track and associate recordings with the corresponding encounter. The correlation ID must be associated with every recording of a session and is also associated with the AI output. The identifier must have the following characteristics:

  • Globally unique.

  • Opaque and doesn't contain any inherent meaning. It therefore doesn't contain any personal information (PII or PHI) and can be safely logged as plain text and shared between parties (customer, partner and Microsoft).
productId Yes The Microsoft-defined identifier of the product for which the session is being created.
clientName Yes The client name. This provides additional information on the EHR/client instance. For example, "QA client".
sectionName No The document section that the user is viewing.
documentSections No The document sections that had data, as a comma-separated list.
documentVersion No The version of the document that the user is viewing.
launchType No The Dragon Copilot functionality that you want to display in your EHR. Possible values:

summaryFeedback - displays a UI where the user can provide feedback on the note created by Dragon Copilot from ambient recordings. This is the default if no value is provided. The user can select one of the following options:
Looks right
Needs improvement
Offensive, inappropriate or biased

The user can also type free text comments.

copilot - redirects to the Dragon Copilot web app.
appVersion No The client app version.
accessToken Yes The partner-issued access token.

Response

The token launch API uses the POST-REDIRECT-GET (PRG) pattern.

  • POST (form submission): When the provider submits a form, it sends a POST request to the server. The server processes the form data  and prepares a response.

  • Redirect (PRG step): Instead of returning a view to the POST request, the server issues an HTTP redirect (HTTP status code 302) to a different URL, depending on the launchType.

  • GET (response retrieval): The browser follows the redirect and performs a GET request to retrieve the page specified by the redirect. The redirected URL corresponds to a GET request, which retrieves the WebView as a response.

    When launchType == summaryFeedback, the redirection is to the Submit AI summary feedback UI, hosted by the EHR Integration Service.

    When launchType == copilot, the redirection is to the Dragon Copilot web app.

The PRG pattern is commonly used in web development. It prevents duplicate form submissions and enhances the user experience by avoiding form resubmission when users refresh the page.

Recommendations when implementing the token launch API

  • For the POST (form submission), the target should open in a new tab or window. For example, form.target='_blank'.

  • REST API clients such as Postman, Bruno, and Insomnia aren't recommended.

Sample test client to invoke token launch

<!DOCTYPE html>
<html>
<head></head>
<body>
<h2>Token Launch Tester</h2>
The correlation id must be provided [guid]
<br/>
Correlation id: <textarea rows="1" cols="40" id="uuid"></textarea>

<br/><br/>
Launch Type:
<select id="launchType">
  <option value="summaryFeedback">summaryFeedback</option>
  <option value="copilot" selected="selected">copilot</option>
</select>
<br/><br/>

<form onsubmit="postAndOpenInNewTab(event)">
   <input type="submit" value="Submit">
</form>
<script>

function postAndOpenInNewTab(event) {
  event.preventDefault();
  // Define the target URL and JSON data
  const url = `<EHR_URL/api/{ehr}/token-launch>`;

  // Create a form element
  const form = document.createElement('form');
  form.method = 'POST';
  form.action = url;
  form.target = '_blank'; // Open in a new tab or window

  // Create a hidden input field to hold the JSON data
  const input = document.createElement('input');
  const correlationId = document.getElementById("uuid").value
  const launchType = document.getElementById("launchType").value
  
  input.type = 'hidden';
  input.name = 'data'; // The name of the parameter expected by the server

  const somePayload = {
      "partnerId": "<PARTNER_ID>",
      "orgId": "<NMS_ORG_GUID>",
      "productId": "<PRODUCT_ID>",
      "clientName": "<CLIENT_NAME>",
      "correlationId": correlationId,
      "launchType": launchType, // summaryFeedback or copilot
      "sectionName": "sectionA",
      "documentVersion": "1",
      "documentSections": "section1",
      "appVersion": "1",
      // CHANGE TOKEN HERE
      "accessToken": "<ACCESS TOKEN HERE>"
  }
  input.value = JSON.stringify(somePayload);

  // Append the input field to the form
  form.appendChild(input);

  // Append the form to the body (required for submission)
  document.body.appendChild(form);

  // Submit the form
  form.submit();

  // Remove the form from the body after submission
  document.body.removeChild(form);
  }
</script>
</body>
</html>

Error codes

The Dragon Copilot integration service returns the following errors in response to failure scenarios:

HTTP status code Error code Name Description
400 7 LaunchParametersMissing The iss or launch parameter is missing.
400 26 EhrIdMissing The EHR ID was not provided in the context.
400 39 HmsServiceError Failed to retrieve data from the HMS.
400 46 LaunchUserObjectIdMissing The token launch user's object ID is missing.
401 53 InvalidLicense The user doesn't have a valid Dragon Copilot license.
500 1 Generic A generic error on the backend side. This requires further investigation by the backend team.
500 42 HmsUserFetchError Failed to retrieve user details from the HMS.
500 27 EhrContextInvalid The context is invalid. Validate the context parameters.
  • Last updated on