chore(#1414): organize interoperability documentation under the same section

content/en/building/interoperability/_index.md

@@ -0,0 +1,11 @@
+---
+title: Interoperability
+linkTitle: "Interoperability"
+weight: 10
+description: >
+  Exchanging data between the CHT and other health systems 
+keywords: interoperability integrations fhir icd openhie openhim
+aliases:
+   - /building/guides/interoperability/
+---
+

content/en/building/guides/interoperability/cht-config.md → content/en/building/interoperability/cht-config.md

@@ -1,16 +1,16 @@
 ---
 title: "Configuring CHT applications for interoperability workflows"
 linkTitle: "Configuring"
-weight: 1
+weight: 3
 description: >
    Guide to setting up forms and outbound push for interoperability
 keywords: interoperability fhir integrations openmrs
 aliases: 
   - /building/guides/integrations/fhir/
-  - /building/guides/interoperability/fhir/
-  - /building/guides/interoperability/cht-config/
-relatedContent: >
-  building/concepts/interoperability/
+  - /building/interoperability/fhir/
+  - /building/interoperability/cht-config/
+aliases:
+  - /building/guides/interoperability/cht-config
 ---
 
 ## Overview

content/en/building/guides/interoperability/ltfu.md → content/en/building/interoperability/ltfu.md

@@ -1,13 +1,14 @@
 ---
 title: "Loss To Follow-Up reference workflow"
 linkTitle: "Loss To Follow-Up"
-weight: 3
+weight: 4
 description: >
    Guide to testing the Loss to Follow-Up (LTFU) reference workflow
 keywords: openmrs interoperability
 relatedContent: >
-  building/guides/interoperability/cht-config
-  building/concepts/interoperability/
+  building/interoperability/cht-config
+aliases:
+  - /building/guides/interoperability/ltfu
 ---
 
 ## Workflow Testing
@@ -27,7 +28,7 @@ The section includes placeholders for URLs. Replacing these placeholders with th
 ## Steps
 
 The following steps assume you have running OpenHIM and CHT instances you successfully logged into.
-See the [OpenHIM guide]({{< ref "building/guides/interoperability/openhim" >}}) for instructions to set up a local development instance of OpenHIM.
+See the [OpenHIM guide]({{< ref "building/interoperability/openhim" >}}) for instructions to set up a local development instance of OpenHIM.
 
 1.  Create an **Endpoint** and an **Organization**
 

content/en/building/guides/interoperability/openhim.md → content/en/building/interoperability/openhim.md

@@ -6,10 +6,11 @@ description: >
    Guide to running OpenHIM and Mediators with Docker Compose
 keywords: openmrs interoperability
 relatedContent: >
-  building/guides/interoperability/cht-config
-  building/guides/interoperability/ltfu
-  building/concepts/interoperability/
-  building/guides/integrations/openmrs/
+  building/interoperability/cht-config
+  building/interoperability/ltfu
+  building/guides/integrations/openmrs
+aliases:
+   - /building/guides/interoperability/openhim
 ---
 
 ### Overview
@@ -24,13 +25,24 @@ The components and reference information for interoperability used in CHT Intero
 
 The structure of documents in the CHT database reflects the configuration of the system, and therefore, does not map directly to a FHIR message format. To achieve interoperability, the CHT uses a middleware to convert the CHT data structure into a standardized form so the other systems can read it. Below is the standard data workflow:
 
-![](flow.png)
+```mermaid
+graph LR
+cht[CHT]
+mediator_a([Mediator])
+mediator_b([Mediator])
+openhim[OpenHIM]
+
+cht -- Outbound pushfa:fa-arrow-right --- mediator_a
+cht -- API requestfa:fa-arrow-left --- mediator_b
+mediator_a -- Requestfa:fa-arrow-right --- openhim
+mediator_b -- Channelfa:fa-arrow-left --- openhim
+```
 
 CHT Interoperability uses OpenHIM as the middleware component with [Mediators](http://openhim.org/docs/configuration/mediators/) to do the conversion. [Outbound Push]({{< ref "building/reference/app-settings/outbound" >}}) is configured to make a request to the middleware when relevant documents are created or modified in the CHT. A Mediator then creates a FHIR resource which is then routed to OpenHIM. OpenHIM routes the resource to any other configured systems.
 
 Conversely, to bring data into the CHT, OpenHIM is configured to route the updated resource to the Mediator, which then calls the relevant [CHT APIs]({{< ref "building/reference/api" >}}) to update the document in the CHT database. This will then be replicated to users’ devices as per usual.
 
-See more information on the [CHT interoperability page]({{< ref "building/concepts/interoperability" >}}).
+See more information on the [CHT interoperability page]({{< ref "building/interoperability/overview" >}}).
 
 ### Prerequisites
 

content/en/building/guides/interoperability/openmrs.md → content/en/building/interoperability/openmrs.md

@@ -1,19 +1,20 @@
 ---
 title: "OpenMRS Interoperability"
 linkTitle: "OpenMRS"
-weight: 4
+weight: 5
 description: >
    Exchange data with systems based on OpenMRS using FHIR APIs
 keywords: openmrs interoperability
 relatedContent: >
-  building/guides/interoperability/cht-config
-  building/concepts/interoperability
-  building/guides/interoperability/openhim
+  building/interoperability/cht-config
+  building/interoperability/openhim
+aliases:
+  - /building/guides/interoperability/openmrs
 ---
 
 [OpenMRS](https://openmrs.org) is an open-source electronic medical record system used in dozens of countries. Integrating CHT apps with OpenMRS can open up opportunities to improve health outcomes for patients by promoting better coordination of care. For example, referrals by CHWs in the community can be sent electronically to health facilities using OpenMRS so that nurses and clinicians can prepare for their visit and have full access to the assessment done by a CHW.
 
-Integrating CHT apps with OpenMRS can be achieved using the CHT's [Interoperability Tools]({{< ref "building/guides/interoperability/openhim" >}}) and following the guidance in the [Building interoperability with FHIR APIs documentation]({{< ref "building/guides/interoperability/cht-config" >}}). 
+Integrating CHT apps with OpenMRS can be achieved using the CHT's [Interoperability Tools]({{< ref "building/interoperability/openhim" >}}) and following the guidance in the [Building interoperability with FHIR APIs documentation]({{< ref "building/interoperability/cht-config" >}}). 
 
 ## Overview
 
@@ -24,7 +25,7 @@ The steps to create an OpenMRS interoperability workflow are:
 1. Profile the workflow in terms of what data needs to be exchanged between OpenMRS and the CHT application.
 1. Set up a test environment including an OpenMRS instance, a CHT instance, and OpenHIM. The [interoperability project](https://github.com/medic/cht-interoperability) has docker compose files so that you can set this up locally by running `./startup.sh up-openmrs` in the interoperability project.
 1. Create or find [concepts](https://guide.openmrs.org/configuration/managing-concepts-and-metadata/)  in OpenMRS that represent any data that needs to be exchanged.
-1. [Configure outbound push and forms]({{< ref "building/guides/interoperability/cht-config" >}}) in the CHT application to match the interoperability workflow.
+1. [Configure outbound push and forms]({{< ref "building/interoperability/cht-config" >}}) in the CHT application to match the interoperability workflow.
 1. Test and debug any configuration issues in the test environment.
 1. Once the configuration is confirmed to be working as expected, start deploying to production by uploading the CHT configuration to production.
 1. Add any OpenMRS concepts or forms to production.
@@ -44,7 +45,7 @@ Depending on what data needs to be exchanged, [outbound push]({{< ref "building/
 
 ### Sending patients CHT->OpenMRS
 
-When sending patient data to OpenMRS, configure an outbound push mapping as described in the [CHT FHIR config documentation]({{< ref "building/guides/interoperability/cht-config#outbound-patients" >}}).
+When sending patient data to OpenMRS, configure an outbound push mapping as described in the [CHT FHIR config documentation]({{< ref "building/interoperability/cht-config#outbound-patients" >}}).
 Patients synced to OpenMRS will have two new [identifier types](https://guide.openmrs.org/getting-started/openmrs-information-model/#patient-identifier): `CHT Document Id`, the uuid of the document that is sent, and `CHT Patient ID`, if there is a `patient_id` field on the patient document.
 These identifier types are created automatically when the OpenMRS Channel is registered.
 
@@ -126,7 +127,7 @@ curl -X GET localhost:8090/openmrs/ws/fhir2/R4/Patient/?identifier=[identifier]
 
 Any data sent from CHT to OpenMRS needs to map to a [concept](https://wiki.openmrs.org/display/docs/Concept+Dictionary+Basics) in OpenMRS. Each concept has a code which will be used to identify the concept in the CHT Application, the FHIR Server, and OpenMRS.
 For any fields to send to OpenMRS, first find or create matching concepts in OpenMRS.
-Then, using the appropriate codes, configure an outbound push as described in the [CHT FHIR config documentation]({{< ref "building/guides/interoperability/cht-config#outbound-reports" >}}).
+Then, using the appropriate codes, configure an outbound push as described in the [CHT FHIR config documentation]({{< ref "building/interoperability/cht-config#outbound-reports" >}}).
 
 In OpenMRS, all form submissions are represented as `Home Visit` encounter types, with a `Visit Note` encounter.
 Any fields in the outbound push config are converted to FHIR observations, which are linked to the `Visit Note`.
@@ -173,7 +174,7 @@ curl -X GET localhost:8090/openmrs/ws/fhir2/R4/Encounter/?identifier=[identifier
 ```
 ## Starting the interop project
 
-Once the CHT and OpenMRS configs are ready, set up OpenHIM and install the mediators by following the instructions [here]({{< ref "building/guides/interoperability/openhim" >}}).
+Once the CHT and OpenMRS configs are ready, set up OpenHIM and install the mediators by following the instructions [here]({{< ref "building/interoperability/openhim" >}}).
 Set `OPENMRS_URL`, `OPENMRS_PORT`, and `OPENMRS_HOST` in .env to configure the necessary channel automatically.
 | Name                      | Description                                                                                     |
 |---------------------------|-------------------------------------------------------------------------------------------------|
@@ -206,7 +207,7 @@ This includes:
 
 ### Troubleshooting
 
-In case of errors when setting up the OpenHIM project please see the [Troubleshooting guide]({{< ref "building/guides/interoperability/openhim#troubleshooting" >}}).
+In case of errors when setting up the OpenHIM project please see the [Troubleshooting guide]({{< ref "building/interoperability/openhim#troubleshooting" >}}).
 
 If the openhim project starts up correctly but something else does not work as expected, it can be helpful to first check the transaction log page of OpenHIM to see which requests were sent, and the request and response bodies.
 See the sequence diagrams above for the expected requests/responses.

content/en/building/concepts/interoperability.md → content/en/building/interoperability/overview.md

@@ -1,17 +1,18 @@
 ---
-title: Interoperability
-linkTitle: "Interoperability"
-weight: 8
+title: Overview
+linkTitle: "Overview"
+weight: 1
 description: >
-  Exchanging information between the CHT Core and other health systems 
+  Interoperability key concepts
 keywords: interoperability integrations fhir icd openhie openhim
 relatedContent: >
   building/features/integrations
-  building/guides/interoperability/cht-config
-  building/guides/interoperability/openhim
-  building/guides/interoperability/ltfu
+  building/interoperability/cht-config
+  building/interoperability/openhim
+  building/interoperability/ltfu
 aliases:
-   - /apps/concepts/interoperability
+  - /apps/concepts/interoperability
+  - /building/concepts/interoperability
 ---
 
 ## Introduction 
@@ -20,26 +21,6 @@ Interoperability refers to the ability of different health information systems a
 
 Interoperability is the best practice for health systems because it allows information from one system to be shared with one or more other systems with no additional development. Interoperability allows technical teams to scale in an efficient and repeatable manner due to the already predefined standards. 
 
-## CHT Interoperability
-
-The native CHT database structure does not map directly to a [Fast Healthcare Interoperability Resources (FHIR)](http://www.hl7.org/fhir/) message format. To be compatible, we use a middleware to convert the CHT data structure into a standardized JSON format so the other systems can read it. See below the data workflow:
-
-```mermaid
-graph LR
-cht[CHT]
-mediator_a([Mediator])
-mediator_b([Mediator])
-openhim[OpenHIM]
-
-cht -- Outbound pushfa:fa-arrow-right --- mediator_a
-cht -- API requestfa:fa-arrow-left --- mediator_b
-mediator_a -- Requestfa:fa-arrow-right --- openhim
-mediator_b -- Channelfa:fa-arrow-left --- openhim
-```
-OpenHIM was utilised as the middleware component with [Mediators](http://openhim.org/docs/configuration/mediators/) to do the conversion. [Outbound Push]({{< ref "building/reference/app-settings/outbound" >}}) is configured to make a request to the middleware when relevant documents are created or modified in the CHT. A Mediator then creates a FHIR resource, which is then routed to OpenHIM. OpenHIM routes the resource to any other configured systems.
-
-Conversely to bring data into the CHT, OpenHIM is configured to route the updated resource to the Mediator, which then calls the relevant [CHT APIs]({{< ref "building/reference/api" >}}) to update the document in the CHT database. This will then be replicated to users’ devices as per usual.
-
 ## Standards & Components
 
 - [OpenHIE](https://ohie.org/): OpenHIE is an open-source framework for building interoperable health information systems. OpenHIE provides a set of standards and protocols for enabling different health systems and applications to communicate with each other.
@@ -48,8 +29,9 @@ Conversely to bring data into the CHT, OpenHIM is configured to route the update
 
 - [FHIR](http://www.hl7.org/fhir): FHIR is a standard for exchanging healthcare data electronically. FHIR provides a modern, web-based approach to exchanging healthcare data and is rapidly becoming the preferred standard for healthcare interoperability.
 
-A reference application for this pattern is available in the [CHIS Interoperability repository](https://github.com/medic/cht-interoperability). 
-This application implements a Loss to Follow Up (LTFU) workflow system for CHIS based on the OpenHIE LTFU Guide. 
+## CHT Interoperability
+
+[CHT Interoperability](https://github.com/medic/cht-interoperability) implements interoperability between the CHT and other health information systems based on [OpenHIE architecture](https://ohie.org/) and [HL7 FHIR](https://www.hl7.org/fhir/index.html) messaging format.
 
 ## Frequently Asked Questions
 
@@ -79,5 +61,5 @@ The flexibility of mediators also means the CHT is future-proof and can be confi
 4. [Organization](https://build.fhir.org/organization.html)
 5. [Endpoint](https://build.fhir.org/endpoint.html)
 
-You can find additional information and instructions for setting up locally in the [cht-interoperability repository](https://github.com/medic/cht-interoperability).
+You can find additional information and instructions for setting up [cht-interoperability](https://github.com/medic/cht-interoperability) in the [dedicated guidelines]({{< ref "building/interoperability/openhim" >}}) .
 

content/en/glossary.md

@@ -141,7 +141,7 @@ An arrangement of an organization's information systems that allows them to comm
 
 ###### Interoperability
 
-The ability of health information systems to work together, even if they weren't specifically designed to work together. With interoperability, patient information can be seen, exchanged, and used across different platforms. {{< see-also page="building/concepts/interoperability" prefix="Read more" >}}
+The ability of health information systems to work together, even if they weren't specifically designed to work together. With interoperability, patient information can be seen, exchanged, and used across different platforms. {{< see-also page="building/interoperability" prefix="Read more" >}}
 
 ## J
 

content/en/why-the-cht.md

@@ -73,7 +73,7 @@ Apps built with the Core Framework are fully responsive Progressive Web Applicat
 
 ## Ready for national scale
 
-Around the world, countries are adopting a model of primary health care that starts in communities and homes where high-quality, integrated services are delivered by trusted health workers who are empowered with technology. The scalability and flexibility of the CHT facilitates the creation of holistic digital community health tools that are [well integrated]({{< ref "building/concepts/interoperability" >}}) throughout the hierarchy of national health systems and across the patient continuum of care. As of 2022, six governments have selected the CHT as a tool of choice for their national community health systems.
+Around the world, countries are adopting a model of primary health care that starts in communities and homes where high-quality, integrated services are delivered by trusted health workers who are empowered with technology. The scalability and flexibility of the CHT facilitates the creation of holistic digital community health tools that are [well integrated]({{< ref "building/interoperability" >}}) throughout the hierarchy of national health systems and across the patient continuum of care. As of 2022, six governments have selected the CHT as a tool of choice for their national community health systems.
 
 ## Made for localization