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 -

1. Generate the Report Link

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."
    },
    "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" title="MD.ai Reporting"></iframe>

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

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 sync and launch new reports automatically in the same iframe/tab/window when moving to a new study in your own application or worklist, you need to configure two API calls in sequence as explained below. You can add these calls during study navigation in your application -

1. Use the Report Generation API

Request a new report using our Report Generation API when launching/loading your new exam, with the "SyncLaunch": true parameter in the reportingApp section as mentioned here. This ensures that the report is ready without actually launching the link separately. This parameter also ensures if another reporting window is opened on a new device, the report will stay synced.

You should also pass the userInfo parameters, especially UserEmail to make sure per user syncing is enabled and behaves as expected, otherwise any new report in the same site could get synced in the user's reporting window instead of only the reports relevant to them.

2. Use the Report Sync API

Sync existing or already opened reporting window for a user to the new study's report using the API below -

Method: POST

API endpoint: https://chat.md.ai/api/report/launch/sync

Request Header:

    Content-Type: application/json
    x-access-token: YOUR_MDAI_ACESS_TOKEN

Request Body:

clinicalInfo: A dictionary object that stores the clinical information/tags related to the exam/study. The list of required tags are SiteID, PatientMRN and Accession. (required)
UserEmail: Email of the user you want to assign and sync the report for. Make sure this is same as the UserEmail for the first API call in step 1. (required)

    {
        "clinicalInfo": {
            "SiteID": "test",
            "PatientMRN": "test-mrn",
            "Accession": "test-accession"
        },
        "UserEmail": "test@md.ai"
    }

If the response is OK that means the new report is now synced and updated in the existing reporting window.

Step 1 creates a new report for the study if it does not already exist. Step 2 checks for the existence of the report and opens it in place, in the existing reporting windows, without the need to launch a new window.

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