Skip to content

Integration Guide

MD.ai reporting can be effortlessly integrated into any PACS, RIS, or web application using iframes. By leveraging our secure token-based authentication, you can enable direct access to reports within an iframe embedded in your application. This eliminates the need for users to log in separately on MD.ai, streamlining workflows and enhancing user experience.

You can also choose to launch our reporting app in a new tab or a new window. We also support syncing new reports in the same reporting window, whether it is an iframe or a separate window, so that launching a new exam or item in the worlist will also open the new report in the same existing reporting window.

Each site (SiteID) provisioned by MD.ai is assigned site administrators who have full control over the reports being generated within the system. As a site admin, you have the ability to assign reports to specific users by passing the necessary user details in your POST request. This allows the users, who are already logged in to your system, to directly access the reporting interface and begin dictating reports immediately without the need to go through another login process on MD.ai.

We will work with your team to designate site administrators and they will then be able to configure and manage launching these reports within your iframe.

Embed MD.ai Reporting as an Iframe

To embed MD.ai reporting within your application using iframes, follow these steps:

First, you need to generate a report link by sending a POST request using the MD.ai Reporting API. In addition to all the relevant clinicalInfo mentioned, your request MUST include the userInfo parameter in the JSON body:

userInfo:
  UserEmail: Email of the user you want to assign the report to
  UserName: Name of the user you want to assign the report to
  Auth: The MD.ai access token from a site admin of your site on MD.ai. This is important and only the token from one of the site admins will work.

Site admin access token requirement

Please note the inclusion of the Auth, UserName, and UserEmail parameters within the userInfo. The Auth parameter must contain the access token from a site admin. The report will not launch in your iframe if these parameters are missing, since logging in to the MD.ai interface from an iframe is prohibited. Therefore, only site admins can create authenticated report links necessary for iframe integration. But in case the x-access-token in the headers already contains the token from a site admin, you can skip adding the Auth field.

Example POST Request

POST /api/report/launch/clinical HTTP/1.1
Host: chat.md.ai
Content-Type: application/json
x-access-token: YOUR_ACCESS_TOKEN

{
  "clinicalInfo": {
    "SiteID": "test",
    "PatientMRN": "test-mrn",
    "Accession": "test-accession",
    "PatientName": "John Doe",
    "PatientBirthDate": "2024-01-01",
    "PatientAge": "50",
    "PatientSex": "M",
    "Modality": "CT",
    "BodyPartExamined": "Abdomen",
    "StudyDescription": "CT abdomen w/wo contrast",
    "StudyDate": "2024-01-01",
    "StudyTime": "122009",
    "StudyInstanceUID": "1.2.1.2",
    "ReasonForExam": "History of colon cancer and new onset abdominal pain.",
    "KeyFindings": "This is a test report",
    "ReferringPhysician": "Dr. John Doe, M.D.",
    "ReportingPhysician": "Dr. Jane Doe, M.D.",
    "Notes": "No allergies or medications"
  },
  "reportingApp": {
    "AppLanguage": "en",
    "SpeechLanguage": "en",
    "ReturnFormat": "HL7",
    "SyncLaunch": true
  },
  "userInfo": {
    "Auth": "SITE_ADMIN_MDAI_ACCESS_TOKEN",
    "UserName": "testphysician",
    "UserEmail": "testphysician@md.ai"
  },
  "response": {
    "type": "link"
  }
}

Example Response

The response will include the generated report link.

{
  "status": "Draft",
  "owner": {
    "name": "testphysician",
    "email": "testphysician@md.ai"
  },
  "reportLink": "https://chat.md.ai/reporting/launch-report/clinical?token=8ojevgk4rr"
}

Note

The owner of this report will now be testphysician and you have successfully created an authenticated and encrypted report link for them to start working on the report. You can now embed the reportLink to launch in a new window/iframe.

2. Embed the Iframe

Once you have the generated report link, you can embed it within an iframe in your application. Use the src attribute of the iframe tag to include the report link.

<iframe src="https://chat.md.ai/reporting/launch-report/clinical?token=8ojevgk4rr" allow="microphone;screen-wake-lock;clipboard-read;clipboard-write" title="MD.ai Reporting"></iframe>

You can customize the width, height, and other attributes of the iframe to suit your application requirements.

For cross-origin iframes, the allow attribute in the iframe specifies essential permissions required for full functionality:

  • microphone: For voice recording/transcription.
  • screen-wake-lock: Prevents the screen from going to sleep during active sessions.
  • clipboard-read and clipboard-write: Allows copying and pasting text in the iframe.

Many of our customers have added a button within their worklists that launches both their image viewer and the MD.ai reporting interface side by side, streamlining the workflow and improving user efficiency.

Here is an example of the reporting system integrated within MD.ai's DICOM viewer and annotation platform as an iframe:

Launch Reports in the Same Reporting Window/Iframe

To synchronize and launch new reports automatically within the same iframe/tab/window when navigating to a new study in your application or worklist, please follow the steps outlined below:

  1. The first time a user launches a report in a new reporting iframe/tab/window, that needs to remain synchronized, you must add the "SyncLaunch": true parameter in the reportingApp section of the API call as mentioned here. This parameter is essential for establishing the initial synchronization and will keep track of all new report launches in the same site for that user. Use the retrieved reportLink from the API in this window.
  2. When the user switches to a different study in your application, make another call to the same endpoint with the new study's clinical information. This action will then automatically update the previously opened reporting iframe, tab, or window with this study's report, maintaining synchronization without requiring additional user intervention. The user does not have to click any buttons or manually open the report link in this case.

Here is an example of sync enabled with iframe integration when navigating studies within our DICOM viewer:

sync-report-launch-iframe

Here is an example of sync enabled when opening MD.ai Reporting in a separate browser tab/window and navigating studies:

sync-report-launch-window

Access Signed Reports as HTML

Signed reports can be exported in various formats, such as HL7 and PDF. We also allow for access to the signed report as HTML via a direct API call, which can be rendered directly in the client application.

Method: POST

API endpoint: https://chat.md.ai/api/report/export/html

Request Header:

x-access-token: SITE_ADMIN_TOKEN

Request Body:

  • clinicalInfo: Query for report by SiteID, PatientMRN and Accession. (required)
  • timeZone: Specifies the time zone for all formatted dates. (optional)
{
  "clinicalInfo": {
    "SiteID": "test",
    "PatientMRN": "test-mrn",
    "Accession": "test-accession"
  },
  "timeZone": "America/New_York" // optional
}

Response:

{
  "html": "...",
}