Embedded: Web App EHR Integration
There are currently three methods of integration that Autoscriber, as described below high-level:
- Embedded Web App:
This option is perfect for EHRs wanting a simple integration with Autoscriber's digital AI scribe and is happy to embed Autoscriber's UI in an iframe (or web viewer) within the EHR, with the ability to sync the resultant structured note with the EHR.
- SDK:
This option enables the EHR to have control over their frontend UI, and from there, utilise the Autoscriber Scribe SDK to manage the audio recording and automatically generate the resultant structured note and post it back to the EHR via API.
- Scribe API:
This option is the most flexible of the three options, and provides the EHR with the capability to utilise the backend APIs to generate structured notes from audio that is passed from the EHR. However, this option can be considered the most complex out of the three available as the EHR manages the recording within the EHR and needs to pass audio chunks to Autoscriber via API in real-time.
This article discusses the steps required to set up Option 1.
Table of Contents
Overview
As mentioned above, integrating the Autoscriber Web Application is the quickest and easiest way to add the Autoscriber AI capabilities into your EHR.
This article will guide you through the steps to integrate the Web Application into your EHR by embedding it in an iframe in your EHR.
Architecture Diagram
The below steps in red represent the authentication flow.
Steps to Embed the Web App
a. Request an API Key
You can request an API key by emailing autoscriber at integrations@autoscriber.com
We will provide you with an API key via a secure 1password link.
b. Call Endpoint (Step 1 in Architecture Diagram)
Call the below endpoint through a POST
request:
https://io.autoscriber.com/v1/embed
Headers
The headers are as follows:
api-key
- Type: string
- Value: Your api-key generated in Step a.
Content-Type
- Type: string
- Value:
application/json
Body
The body attributes are as follows:
Name |
Description |
Type |
Required/Optional |
priority | Value between 1-9, you can prioritise certain requests within your bandwidth. | Integer | |
billingReference | This is the value (between 0 and 40 characters) Autoscriber uses to distinguish between EHRs, environments and customers. Therefore, please use the following guidelines: EHR Test Environment: "EHRName_Test" EHR Prod Environment: "EHRName_Prod" Once a customer starts using the integration, please use the following guidelines: "EHRName_CustomerName_Test" or "EHRName_CustomerName_Prod" |
String | Required |
userId | An optional userId that enables the api to personalise the response. Value must between 0 and 40 characters. | String | Optional |
config | Configuring the embedded screen | Object | Optional |
The above config
attributes are as follows:
Name |
Description |
Type |
Required/Optional |
webhook | Configuration for webhook | Object | Required |
webhook sub attribute 1: url |
The url Autoscriber should call when posting the note |
WebhookDTO | Required |
webhook sub attribute 2: headers |
Optional headers we'll use when posting to your url (e.g. auth headers) | String | Optional |
displayName | Display name for the user interface. | String | Optional |
gender | The patient's gender | String | Optional |
specialty | The User's specialty | String | Optional |
preferredMicrophone | Preferred microphone device ID. | String | Optional |
interface_language | The language the interface is displayed in | String | Optional |
languages | Languages the user can select from. Options include en|nl|de |
Array<String> | Optional |
templates | Output types the user can select from. See the section on templates here. The order in which you list the templates will determine what order they are displayed to Users in the embedded app. |
Array<String> | Optional |
sortTemplates | If this is left out, the default value is If If |
Boolean | Optional |
editing | Allow the user to edit the text after the note gas been generated. | Boolean | Optional |
crossOriginTarget | Optionally include the url of the parent, if included the embedded app will push the state to the parent. | String | Optional |
theme | Change the main colour. |
Object | Required |
Theme sub attribute: primaryColor |
A hex color string | String | Required |
exitAfterSync | If yes, the Autoscriber app will close after the "Approve and Synchronise" button has been clicked and the generated note synced with your EHR. | Boolean | Optional |
askConsent | Whether the user has to click consent before recording. | Boolean | Optional |
newTemplate | Whether a user is allowed to generate multiple outputs. | Boolean | Optional |
toggleCodes | To indicate if you want to receive medical coding with the note. | Boolean | Optional |
coding_systems | Whether SNOMED_CT or ICD10 medical codes are generated. If coding is needed, then either "SNOMED_CT" or "ICD10" must be included |
String | If If |
Example body
An example of the body is as follows:
{ "priority": "1", "billingReference": "EHRName", "userId": "user123", "config": { "webhook": { "url": "https://example.com/webhook", "headers": {"Authorization": "Bearer your_token_here"} }, "displayName": "Jane Doe", "gender": "female", "specialty": "gp", "preferredMicrophone": "device_id_1234", "preferred_languages": "nl", "languages": ["en", "nl"], "templates": ["standard_en"], "sortTemplates": "false", "editing": ["true"], "crossOriginTarget": "https://parent.example.com", "theme": { "primaryColor": "#FF5733" }, "exitAfterSync": true, "askConsent": true, "newTemplate": true, "toggleCodes": true, "coding_systems": ["SNOMED_CT"] } }
Example Response:
{ "id": "<ID>", "location": "https://api.autoscriber.com/v1/embed/<ID>", "embedLocation": "https://embed.autoscriber.com/?token=eyJhbGc..." }
- The
embedLocation
is the full iframe src URL, including the token. - The
token
is your JWT and is embedded as a query parameter inembedLocation
. - You can use
embedLocation
directly as the value for thesrc
attribute in your iframe.
Templates
The current templates
that are supported are given in the following articles:
In the above-linked webpages you will see the template specialisation, name, fields and the associated template value. You need to include the template value in the request body.
The templates shown to the user depend on the Specialty and any templates included in the request:
If a Specialty is provided:
The user will see all templates linked to that Specialty, plus the default GENERIC templates.
If a Specialty and additional templates are provided:
The user will see:
- Templates linked to the Specialty
- GENERIC templates
- The additional templates listed in the request
If no Specialty is provided:
Only the templates explicitly included in the request will be shown.
Also note: The order in which you list the templates in the request will determine what order they are displayed to Users in the embedded app.
c. Embed the iFrame code (Step 2 in Architecture Diagram)
Using the {embedLocation} acquired in the response in Step c., use the following code in your HTML, or render it in React:
<iframe title="Embedded Autoscriber app" src={embedLocation} allow="clipboard-write; microphone {embedLocation}" style="width: 100%; height: 600px;" ></iframe>
Note:
- The clipboard-write and microphone access permissions need to be extended to the iframe from the host app.
- See the
allow
line above for reference
Receiving the Summary and Transcript (Step 4 in architecture diagram)
In the Embedded Web App integration, when a User completes a conversation and selects the button "Approve and Synchronise" in the App, Autoscriber will do a POST
to the webhook URL included in the request body provided in Step 3.b, referenced as per the below:
"webhook": { "url": "https://example.com/webhook", "headers": {"Authorization": "Bearer your_token_here"} }
This POST
from Autoscriber will contain the template name, headings and content.
An example can be seen as follows:
{ "standard_en": { "final": true, "data": [ { "items": [ { "sentences": [], "text": "Strong heachaches since 5 days" } ], "section": "Subjectief" }, { "items": [ { "sentences": [], "text": "Refer to neurologist" } ], "section": "Plan" } ], "count": 1, "feedback": {}, "error": false } }
- The
count
represents the order of the generated note. For example, if the User generates the initial template, and then decides to generate another note using a different template, then thecount
of the second note will be 2. - The
feedback
is populated with the feedback the user gave after the note was generated. - The
error
is populated with an error message if applicable.
Activating Integration for Customers
Assuming the embedded integration is set up in your EHRs Test environment, very limited changes are required to set up the integration in the launching customer's environments.
This is what is required:
- Follow the above steps from calling the Autoscriber endpoint for the customer's EHR instance/environment.
- The same api key can be used as previous.
- Adjust the billingReference to include the name of the EHR and the relevant customer. E.g. "EHRName_CustomerName"
- With reference to the information provided above in the templates section, the values assigned to the
specialty
andtemplates
attributes must be determined depending on which healthcare practitioners will use Autoscriber from the launching customer. - Once the URL has been generated and embedded in the iframe, thorough testing must be done to ensure that all templates generated can be successfully synced to the EHR and presented accurately to the user.