opalmedapps · mschoettle · Apr 9, 2025 · Apr 2, 2025 · Apr 2, 2025 · Apr 3, 2025
diff --git a/.markdownlint.yml b/.markdownlint.yml
@@ -10,17 +10,20 @@ ul-indent:
   indent: 4
 
 # Allow inline HTML to support image captions
-MD033: false
+no-inline-html: false
+
+# Allow screenshots to have no alt text
+no-alt-text: false
 
 # Allow bare URLs since we use magiclink to convert bare URLs automatically to links
-MD034: false
+no-bare-urls: false
 
 # Need to disable in order to support PyMdown Tabbed extension
 # See: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
-MD046: false
+code-block-style: false
 
 # Allow same heading name if the parent is different
-MD024:
+no-duplicate-heading:
   siblings_only: true
 
 max-one-sentence-per-line:

diff --git a/REUSE.toml b/REUSE.toml
@@ -9,6 +9,15 @@ precedence = "override"
 SPDX-FileCopyrightText = "Copyright (C) 2023 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <[email protected]>"
 SPDX-License-Identifier = "CC-BY-SA-4.0"
 
+[[annotations]]
+path = [
+    "docs/user/**/images/*.jpg",
+    "docs/user/**/images/*.png",
+]
+precedence = "override"
+SPDX-FileCopyrightText = "Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <[email protected]>"
+SPDX-License-Identifier = "CC-BY-SA-4.0"
+
 [[annotations]]
 path = [
     ".vscode/extensions.json",

diff --git a/docs/user/openemr/diagnosis/add_diagnosis.md b/docs/user/openemr/diagnosis/add_diagnosis.md
@@ -0,0 +1,91 @@
+<!--
+SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <[email protected]>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# OpenEMR: Adding a diagnosis to a patient
+
+This document does not provide full OpenEMR instructions for creating and adding a diagnosis to a patient. It is intended for clinics or health systems integrating with the Opal application, with the minimal OpenEMR requirements for this integration.
+
+If you need more information about the OpenEMR system and its complete set of features, please refer to this link: [https://www.open-emr.org/](https://www.open-emr.org/)
+
+The purpose of this document is to show the steps for adding a diagnosis to the OpenEMR system, with the objective of assigning it to a patient, so that they or their caregiver can view it in their Opal account. This document is intended for the Hospital's administrator staff.
+
+## Adding a diagnosis in OpenEMR
+
+1. To access OpenEMR - Opal Application, go to the **OpenEMR** website (Refer to [https://www.opalmedapps.com/](https://www.opalmedapps.com/) ).
+
+1. A **Calendar** section will appear. A list of **Providers** will be located on the left of the screen. By clicking on a specific name of the list, you can see the provider's calendar and their scheduled appointments.
+
+1. At the top of the screen, click on the **Admin** section. A drop-down menu will be displayed. Click on the **Forms** tab, and then click on **Lists**.
+
+    ![](images/1_OpenEMR_Calendar_AdminList.png)
+
+1. A **List Editor** section will be displayed. Click on the drop-down menu (where you read “Address Book Types”) and select the **Medical Problem List** option.
+
+    ![](images/2_OpenEMR_Diagnosis_ListEditor_MedicalProblem.png)
+
+1. A list of previously added diagnosis codes will be displayed, showing their titles, their IDs and other information, like the example of Parkinson disease diagnosis codes shown in the figure below. Click on a blank **Code** field.
+
+    ![](images/3_OpenEMR_ListEditor_AddingDiagnosis.png)
+
+1. A pop-up window will appear and a drop-down menu will be located at the top left of the screen. Click on the drop-down menu and select the **ICD10 Diagnosis**.
+
+    ![](images/4_OpenEMR_Diagnosis_ICD10List_Selected.png)
+
+1. You must search for the diagnosis/code that will be added to the patient's Medical Record. In the figure below, the diagnosis to be added is *Tuberculosis of lung*. You can also search for a diagnosis on the **Search** field at the top right of the screen.
+
+    ![](images/5_OpenEMR_Diagnosis_Dashboard_ICD10List_Tuberculosis.png)
+
+1. Once the diagnosis has been found from the **ICD 10 Diagnosis list**, you should copy its **Code** and **Description** and paste them at an empty **ID** and **Title** fields, respectively, located at the **List Editor** section. After pressing the enter button of your computer, the complete diagnosis code will appear automatically at the **Code** field at the same section. These three fields, **ID**, **Title** and **Code** are mandatory fields and must be completed.
+
+1. You must select the **Active** checkbox for the patient's diagnosis to appear in the Opal application. At the optional **Subtype** field (optional), you can choose **Diagnosis** from the drop-down menu.
+
+    ![](images/6_OpenEMR_ListEditor_Medical_IssueList_checkbox.png)
+
+1. The order of the diagnosis can be chosen according to your preference, by adding the proper number in the **Order** field, like shown in the figure below.
+
+    ![](images/7_OpenEMR_ListEditor_Medical_IssueList_DiagnosisOrder.png)
+
+## Assigning a diagnosis to a patient in OpenEMR
+
+1. Once in the OpenEMR system, a **Calendar** section will appear. At the top of the screen, click on the **Patient** button. A list will appear with three options: **New/Search, Visits** and **Records**. Click on the **New/Search** tab.
+
+    ![](images/8_OpenEMR_Calendar_NewSearchPatient.png)
+
+1. The **Search or Add Patient** section will be displayed. You can search for the patient, to whom you want to assign the diagnosis, in two ways: by typing in the patient's personal information, such as **Name, Last Name, RAMQ** or Medical Record Number (**MRN**) then clicking on the **Search** button; or by clicking <span style="text-decoration:underline;">directly </span>on the **Search** button, where a list of all patients with their information will appear, and you must search the specific patient.
+
+    ![images9](images/9_OpenEMR_SearchAddPatientTab.png)
+
+    ![](images/10_OpenEMR_PatientSearch_ListofPatients.png)
+
+1. Once you have found the patient's name, double click on it. The patient's **Medical Record Dashboard** will be displayed, showing several health information sections as default. At the **Medical Problems** section, click on the **pencil** button located on the top right side of the section.
+
+    ![](images/11_OpenEMR_Dashboard_EditDiagnosis.png)
+
+1. A **Patient Issues** tab will be displayed. The patient already may or may not have a previous diagnosis on their list of Medical Problems. At the right side of this section, click on the **Add** button.
+
+    ![](images/12_OpenEMR_Diagnosis_PatientIssues_MedicalProblems_Add.png)
+
+1. An **Add/Edit** Issue window will pop-up and you can search for the name of the diagnosis codes by clicking on the drop-down menu and selecting it from the list, or by entering the diagnosis name in the **Title** field.
+
+    After adding the diagnosis name, click on the blue **Save** button.
+
+    ![](images/13_OpenEMR_Diagnosis_PatientIssues_IssueTab.png)
+
+    ![](images/14_OpenEMR_Diagnosis_IssueTab_Tuberculosis.png)
+
+1. On the **Patient Issues** tab, the diagnosis just assigned to the patient will appear. If you expand the information by clicking on the down arrow shown in the figure below, you can see the date of when the diagnosis was last modified and also the diagnosis code.
+
+    ![](images/15_OpenEMR_Diagnosis_PatientIssues_MedicalProblems_Tuberculosis.png)
+
+1. By clicking on the patient's name at the top left of the screen, a **Dashboard** tab will be displayed. You will see the patient's **Medical Record Dashboard** and, in the **Medical Problems** section, the diagnosis that has just been assigned to the patient will be written.
+
+    ![](images/16_OpenEMR_Diagnosis_Dashboard_MedicalProblems_Tuberculosis.png)
+
+1. Only after assigning a diagnosis to a patient in the OpenEMR system, its diagnosis code will appear in the Opal Admin system. In this system, the diagnosis code will need to be aliased, so that the patient or caregiver can see the diagnosis in their Opal account.
+
+1. After logging into their Opal account, the patient or caregiver is able to view the new diagnosis by clicking on the Diagnosis tab at the Chart section.
+
+![](images/17_OpalApp_DiagnosisSection.jpg){ width=250 }
diff --git a/docs/user/openemr/diagnosis/images/10_OpenEMR_PatientSearch_ListofPatients.png b/docs/user/openemr/diagnosis/images/10_OpenEMR_PatientSearch_ListofPatients.png
diff --git a/docs/user/openemr/diagnosis/images/11_OpenEMR_Dashboard_EditDiagnosis.png b/docs/user/openemr/diagnosis/images/11_OpenEMR_Dashboard_EditDiagnosis.png
diff --git a/...emr/diagnosis/images/12_OpenEMR_Diagnosis_PatientIssues_MedicalProblems_Add.png b/...emr/diagnosis/images/12_OpenEMR_Diagnosis_PatientIssues_MedicalProblems_Add.png
diff --git a/docs/user/openemr/diagnosis/images/13_OpenEMR_Diagnosis_PatientIssues_IssueTab.png b/docs/user/openemr/diagnosis/images/13_OpenEMR_Diagnosis_PatientIssues_IssueTab.png
diff --git a/docs/user/openemr/diagnosis/images/14_OpenEMR_Diagnosis_IssueTab_Tuberculosis.png b/docs/user/openemr/diagnosis/images/14_OpenEMR_Diagnosis_IssueTab_Tuberculosis.png
diff --git a/...osis/images/15_OpenEMR_Diagnosis_PatientIssues_MedicalProblems_Tuberculosis.png b/...osis/images/15_OpenEMR_Diagnosis_PatientIssues_MedicalProblems_Tuberculosis.png
diff --git a/...iagnosis/images/16_OpenEMR_Diagnosis_Dashboard_MedicalProblems_Tuberculosis.png b/...iagnosis/images/16_OpenEMR_Diagnosis_Dashboard_MedicalProblems_Tuberculosis.png
diff --git a/docs/user/openemr/diagnosis/images/17_OpalApp_DiagnosisSection.jpg b/docs/user/openemr/diagnosis/images/17_OpalApp_DiagnosisSection.jpg
diff --git a/docs/user/openemr/diagnosis/images/1_OpenEMR_Calendar_AdminList.png b/docs/user/openemr/diagnosis/images/1_OpenEMR_Calendar_AdminList.png
diff --git a/...user/openemr/diagnosis/images/2_OpenEMR_Diagnosis_ListEditor_MedicalProblem.png b/...user/openemr/diagnosis/images/2_OpenEMR_Diagnosis_ListEditor_MedicalProblem.png
diff --git a/docs/user/openemr/diagnosis/images/3_OpenEMR_ListEditor_AddingDiagnosis.png b/docs/user/openemr/diagnosis/images/3_OpenEMR_ListEditor_AddingDiagnosis.png
diff --git a/docs/user/openemr/diagnosis/images/4_OpenEMR_Diagnosis_ICD10List_Selected.png b/docs/user/openemr/diagnosis/images/4_OpenEMR_Diagnosis_ICD10List_Selected.png
diff --git a/...enemr/diagnosis/images/5_OpenEMR_Diagnosis_Dashboard_ICD10List_Tuberculosis.png b/...enemr/diagnosis/images/5_OpenEMR_Diagnosis_Dashboard_ICD10List_Tuberculosis.png
diff --git a/...er/openemr/diagnosis/images/6_OpenEMR_ListEditor_Medical_IssueList_checkbox.png b/...er/openemr/diagnosis/images/6_OpenEMR_ListEditor_Medical_IssueList_checkbox.png
diff --git a/...nemr/diagnosis/images/7_OpenEMR_ListEditor_Medical_IssueList_DiagnosisOrder.png b/...nemr/diagnosis/images/7_OpenEMR_ListEditor_Medical_IssueList_DiagnosisOrder.png
diff --git a/docs/user/openemr/diagnosis/images/8_OpenEMR_Calendar_NewSearchPatient.png b/docs/user/openemr/diagnosis/images/8_OpenEMR_Calendar_NewSearchPatient.png
diff --git a/docs/user/openemr/diagnosis/images/9_OpenEMR_SearchAddPatientTab.png b/docs/user/openemr/diagnosis/images/9_OpenEMR_SearchAddPatientTab.png
diff --git a/docs/user/openemr/document/add_document.md b/docs/user/openemr/document/add_document.md
@@ -0,0 +1,57 @@
+<!--
+SPDX-FileCopyrightText: Copyright (C) 2025 Opal Health Informatics Group at the Research Institute of the McGill University Health Centre <[email protected]>
+
+SPDX-License-Identifier: CC-BY-SA-4.0
+-->
+
+# OpenEMR: Adding a document
+
+This document does not provide full OpenEMR instructions for creating documents. It is intended for clinics or health systems integrating with the Opal application, with the minimal OpenEMR requirements for this integration.
+
+If you need more information about the OpenEMR system and its complete set of features, please refer to this link: [https://www.open-emr.org/](https://www.open-emr.org/)
+
+The purpose of this document is to show the steps for adding a new document, for example a clinical note, to the OpenEMR system, with the objective of a patient or their caregiver being able to view it in their Opal account. This document is intended for the Hospital front desk staff.
+
+1. To access OpenEMR - Opal Application, go to the **OpenEMR** website (Refer to [https://www.opalmedapps.com/](https://www.opalmedapps.com/)).
+
+1. A **Calendar** section will appear. A list of **Providers** will be located on the left of the screen. By clicking on a specific name of the list, you can see the provider's calendar and their scheduled appointments.
+
+1. At the top left of the screen, click on the **Patient** section. A list will appear with two options: **Find Patient** and **Add Patient**. Click on the **Find Patient** tab.
+
+    ![Find Patient](images/1_OpenEMR_FindPatient.png)
+
+1. The **Patient finder** section will be displayed. You will see a list of patients added to the system and some of their personal information, such as the Home Phone and the Date of Birth. Select a patient to whom you want to add the document to the file and double click on the name.
+
+    ![Patient Finder](images/2_OpenEMR_PatientFinder_list.png)
+
+1. The patient's **Medical Record Dashboard** will be displayed, showing their Demographics information as default. Click on **Documents** located above the Demographics section.
+
+    ![Medical Record Dashboard](images/3_OpenEMR_PatienDashboard.png)
+
+1. A **Documents** tab will be displayed and you can see a Documents List on the left side of the screen. To be able to add a document to the patient's profile, you must click on the **Medical Record** category in the list.
+
+1. The **Document Uploader/Viewer section** will show the options to upload the document that will be added to the patient's Medical Record Dashboard. Click on the **Choose Files** button located under **Source File Path**.
+
+    ![Choose file](images/4_OpenEMR_DocumentsTab_DocListDocUploader.png)
+
+1. A window will pop-up, showing the path to where the document is located. After selecting the document that will be added to the system, click on the blue **Upload** button.
+
+    ![Upload](images/5_OpenEMR_DocumentsTab_DocUploader_Files.png)
+
+1. You must verify and confirm that the correct document was uploaded, by checking if the PDF file's name is showing on the right side of the **Choose Files** button and also under the word **Uploaded** at the bottom of the screen.
+
+    ![Choose Files](images/6_OpenEMR_DocumentsTab_DocUploader_FileUploaded.png)
+
+    ![Uploaded](images/7_OpenEMR_DocumentsTab_FileUploaded.png)
+
+1. Once the document has been uploaded, the patient will receive a "**New Document**” push notification on their mobile device.
+
+    ![Push Notification](images/8_PushNotification_NewDoc.jpg){ width="250"}
+
+1. After logging into their Opal account, the patient is able to view the new document in two ways: by accessing the **Notification** page at the **Home** section and clicking on the **New Document** received or by accessing the **Clinical Reports** page at the **Chart**section and clicking on the new document "Medical Record” received.
+
+    ![Notification Page](images/9_OpalApp_NotificationSection_NewDoc.jpg){ width="250" }
+
+    ![Chart Page](images/10_OpalApp_Chart_ClinicalReport.jpg){ width="250" }
+
+    ![Clinical Reports Page](images/11_OpalApp_ClinicalReportSection.jpg){ width="250" }
diff --git a/docs/user/openemr/document/images/10_OpalApp_Chart_ClinicalReport.jpg b/docs/user/openemr/document/images/10_OpalApp_Chart_ClinicalReport.jpg
diff --git a/docs/user/openemr/document/images/11_OpalApp_ClinicalReportSection.jpg b/docs/user/openemr/document/images/11_OpalApp_ClinicalReportSection.jpg
diff --git a/docs/user/openemr/document/images/1_OpenEMR_FindPatient.png b/docs/user/openemr/document/images/1_OpenEMR_FindPatient.png
diff --git a/docs/user/openemr/document/images/2_OpenEMR_PatientFinder_list.png b/docs/user/openemr/document/images/2_OpenEMR_PatientFinder_list.png
diff --git a/docs/user/openemr/document/images/3_OpenEMR_PatienDashboard.png b/docs/user/openemr/document/images/3_OpenEMR_PatienDashboard.png
diff --git a/docs/user/openemr/document/images/4_OpenEMR_DocumentsTab_DocListDocUploader.png b/docs/user/openemr/document/images/4_OpenEMR_DocumentsTab_DocListDocUploader.png
diff --git a/docs/user/openemr/document/images/5_OpenEMR_DocumentsTab_DocUploader_Files.png b/docs/user/openemr/document/images/5_OpenEMR_DocumentsTab_DocUploader_Files.png
diff --git a/...ser/openemr/document/images/6_OpenEMR_DocumentsTab_DocUploader_FileUploaded.png b/...ser/openemr/document/images/6_OpenEMR_DocumentsTab_DocUploader_FileUploaded.png
diff --git a/docs/user/openemr/document/images/7_OpenEMR_DocumentsTab_FileUploaded.png b/docs/user/openemr/document/images/7_OpenEMR_DocumentsTab_FileUploaded.png
diff --git a/docs/user/openemr/document/images/8_PushNotification_NewDoc.jpg b/docs/user/openemr/document/images/8_PushNotification_NewDoc.jpg
diff --git a/docs/user/openemr/document/images/9_OpalApp_NotificationSection_NewDoc.jpg b/docs/user/openemr/document/images/9_OpalApp_NotificationSection_NewDoc.jpg
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -22,6 +22,9 @@ nav:
   - Home: index.md
   - User Guide:
     - user/index.md
+    - OpenEMR:
+      - Adding a document: user/openemr/document/add_document.md
+      - Adding a diagnosis: user/openemr/diagnosis/add_diagnosis.md
   - Contribute:
     - development/index.md
     - Architecture:
@@ -135,9 +138,11 @@ markdown_extensions:
   - def_list
   - footnotes
   # enable HTML in Markdown for image captions
+  # https://squidfunk.github.io/mkdocs-material/reference/images/
   # https://squidfunk.github.io/mkdocs-material/reference/images/#image-captions
   # https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#markdown-in-html
   - md_in_html
+  - attr_list
   - tables
   - toc:
       permalink: true