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:
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
andAccession
. (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:
Here is an example of sync enabled when opening MD.ai Reporting in a separate browser tab/window and navigating studies: