+
+ 1. **CHT** - Select an option (Yes or No) and submit the `Tasks`.
+ 1. **OpenHIM Admin Console** - Verify that the Encounter creation was successful in both OpenHIM Mediator & FHIR Resource. Navigate to the `Transaction Log` in the Admin Console. You should see two successful API calls, one to `/mediator/encounter/` and one to `/fhir/Encounter/`, as in the image below.
+ 
+ 1. If your callback URL test service was set up correctly, you should receive a notification from the mediator.
+
+
+An API test collection that can be used with Postman or similar tools can be found under `/docs/local-test` in the [cht-interoperability repository](https://github.com/medic/cht-interoperability/tree/main/docs/local-test). This collection allows testing the LTFU flow while running the instances locally.
+
+## Resources
+
+The following [FHIR Resources](https://www.hl7.org/fhir/resource.html) are used to implement the flow above:
+
+- [Patient](https://www.hl7.org/fhir/patient.html)
+- [Encounter](https://build.fhir.org/encounter.html)
+- [Subscription](https://build.fhir.org/subscription.html)
+- [Organization](https://build.fhir.org/organization.html)
+- [Endpoint](https://build.fhir.org/endpoint.html)
+
+The payload samples in the documentation contain placeholder values you must replace with the actual content. To do so, replace the entire `${}` placeholder with the appropriate value. Be aware that some placeholder keys have the format `_\_IDENTIFIER` and refer to the value in the `Resource.identifier[0].value` field. These keys differ from the `_\_ID` placeholders used in the request, which refer to the `Resource.id` field. It is important to make this distinction, as using the wrong value may cause unexpected behavior in the system. Therefore, always ensure you use the right value in the right context to avoid errors.
+
+
+> **Note:** The payload only contains the required fields or a subset of the possible options. Please refer to the appropriate FHIR resource specifications to view all the available fields.
+
+
+### `ServiceRequest` Resource
+
+The FHIR `ServiceRequest` resource represents a request for a healthcare service to be performed, such as a diagnostic test or a treatment. It contains information about the requested service, including the **type of service**, the **patient** for whom the service is requested, the **date/time the service is requested**, and the **healthcare provider or organization** making the request. In the context of the LTFU workflow, this resource is used to request a CHW follow-up in the CHT.
+
+#### `POST ${MEDIATOR_ENDPOINT}/service-request`
+
+This endpoint triggers the creation of a `record` on `CHT` and a `Subscription` resource on FHIR. The endpoint associated with the `Organization` resource in the requester is used as the callback URL for the `Subscription` which gets called when FHIR receives an `Encounter` resource with matching `Patient` identifier. The callback endpoint receives a FHIR `Subscription` response as its payload whenever the request is fulfilled. To learn more about FHIR
+subscriptions, you can visit the official documentation [here](https://build.fhir.org/subscription.html).
+
+##### Request
+
+```http
+POST ${MEDIATOR_ENDPOINT}/service-request
+```
+```json
+{
+ "intent": "order",
+ "subject": {
+ "reference": "Patient/${PATIENT_IDENTIFIER}"
+ },
+ "requester": {
+ "reference": "Organization/${ORGANIZATION_IDENTIFIER}"
+ }
+ ,
+ "status": "active"
+}
+```
+
+##### Response
+
+```json
+{
+ "resourceType": "Subscription",
+ "id": "4",
+ "meta": {
+ "versionId": "1",
+ "lastUpdated": "2023-04-19T04:41:17.656+00:00",
+ "tag": [
+ {
+ "system": "http://hapifhir.io/fhir/StructureDefinition/subscription-matching-strategy",
+ "code": "IN_MEMORY",
+ "display": "In-memory"
+ }
+ ]
+ },
+ "status": "requested",
+ "reason": "Follow up request for patient",
+ "criteria": "Encounter?identifier=003b24b5-2396-4d95-bcbc-5a4c63f43ff0",
+ "channel": {
+ "type": "rest-hook",
+ "endpoint": "https://callback.com",
+ "payload": "application/fhir+json",
+ "header": ["Content-Type: application/fhir+json"]
+ }
+}
+```
+
+### `Endpoint` Resource
+
+The FHIR `Endpoint` resource describes the network address of a system or service where messages or payloads can be exchanged. It defines the communication characteristics for sending and receiving messages, such as the **transport protocol**, the **payload format**, and the **messaging endpoint's address**. The `Endpoint` resource can specify where to send data for specific purposes, such as notifications, alerts, or reports. It can be used in various contexts, such as clinical care, public health, or research, where different systems or services need to exchange data seamlessly.
+
+#### `POST ${MEDIATOR_ENDPOINT}/endpoint`
+
+In the LTFU workflow, the `Endpoint` is crucial in creating a `ServiceRequest`. It is obtained from the `Organization` attached to the `ServiceRequest` as the requester. The `Endpoint` represents the destination where the FHIR server sends notifications about matching `Encounter` resources. When the FHIR server receives a matching `Encounter` resource, it sends a notification to the endpoint. The endpoint is used as a **callback URL** for the FHIR server to notify the requester about the status of the `ServiceRequest`. Therefore, ensuring that the endpoint is accurate and valid for successful communication between the FHIR server and the requesting system is important.
+
+- **ENDPOINT_ID:** _(Optional)_ A preferred `id` for the `Endpoint`. By default, the mediator will generate an `id` for the `Endpoint`.
+- **ENDPOINT_IDENTIFIER:** An identifier for the `Endpoint` that can be used when querying the FHIR database in the future.
+- **ORG_CALLBACK_URL:** A callback URL that the mediator can use to contact the requesting system (`Organization`) in the future when a `ServiceRequest` has been fulfilled.
+
+> **NOTE** The FHIR `Subscription` that will be created ulteriorly requires `ORG_CALLBACK_URL` to accept HTTP `PUT` requests matching this path `${ORG_CALLBACK_URL}/:resourceType/:resourceId` and return a 200. In this workflow, the callback should expect to receive an `Encounter` resource sent back to the requesting system on `${ORG_CALLBACK_URL}/Encounter/:id`.
+
+##### Request
+
+
+```http
+POST ${MEDIATOR_ENDPOINT}/endpoint
+```
+```json
+{
+ "id": "${ENDPOINT_ID}",
+ "identifier": [
+ {
+ "system": "official",
+ "value": "${ENDPOINT_IDENTIFIER}"
+ }
+ ],
+ "connectionType": {
+ "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
+ "code": "hl7-fhir-rest"
+ },
+ "payloadType": [
+ {
+ "text": "application/json"
+ }
+ ],
+ "address": "${ORG_CALLBACK_URL}",
+ "status": "active"
+}
+```
+
+##### Response
+
+
+```json
+{
+ "resourceType": "Endpoint",
+ "id": "1",
+ "meta": {
+ "versionId": "1",
+ "lastUpdated": "2023-04-19T04:40:44.401+00:00"
+ },
+ "identifier": [
+ {
+ "system": "official",
+ "value": "ENDPOINT_ID"
+ }
+ ],
+ "status": "active",
+ "connectionType": {
+ "system": "http://terminology.hl7.org/CodeSystem/endpoint-connection-type",
+ "code": "hl7-fhir-rest"
+ },
+ "payloadType": [
+ {
+ "text": "application/json"
+ }
+ ],
+ "address": "https://callback.com"
+}
+```
+
+### `Patient` Resource
+
+The FHIR `Patient` resource represents an individual receiving or awaiting healthcare services. It includes **patient demographics**, **clinical observations**, and **medical history**. It is a foundational resource in healthcare and can be used to track patient progress, manage care plans, and facilitate communication between healthcare providers.
+
+#### `POST ${MEDIATOR_ENDPOINT}/patient`
+
+This endpoint creates a `Patient` in the LFTU workflow. Patients are created by CHT automatically whenever a new Patient is added to the system.
+
+##### Request
+
+```http
+POST ${MEDIATOR_ENDPOINT}/patient
+```
+```json
+{
+ "identifier": [
+ {
+ "system": "official",
+ "value": "${PATIENT_IDENTIFIER}"
+ }
+ ],
+ "name": [
+ {
+ "family": "Doe",
+ "given": [
+ "John"
+ ]
+ }
+ ],
+ "gender": "male",
+ "birthDate": "2000-01-01"
+}
+```
+
+##### Response
+
+
+```json
+{
+ "resourceType": "Patient",
+ "id": "3",
+ "meta": {
+ "versionId": "1",
+ "lastUpdated": "2023-04-19T04:41:01.217+00:00"
+ },
+ "text": {
+ "status": "generated",
+ "div": "| Identifier | 003b24b5-2396-4d95-bcbc-5a4c63f43ff0 |
| Date of birth | 01 January 2000 |
+
+For testing other mediators, replace the URL (http://localhost:5001/mediator) with the appropriate values for the specific mediator you are testing.
+For example if using the OpenMRS mediator, you can test it by running:
+
+```bash
+curl -X GET localhost:5001/mediator/openmrs/sync -H "Authorization: Basic $(echo -n interop-client:interop-password | base64)"
+```
+
+### CHT configuration with Docker
+
+The following steps apply when running CHT via the Docker setup provided in the cht-interoperability repository:
+
+1. CHT can be accessed via [http://localhost:5988](http://localhost:5988), and the credentials are `admin`/`password`.
+2. Create a new user in the CHT instance with the username `interop-client` using these [instructions]({{< ref "building/contact-management/contact-and-users-1#4-create-the-chw-user" >}}). For the role you can select `Data entry` and `Analytics` roles. Please note that you can use any username you prefer but you would have to update the config with the new username. You can do that by editing the `cht-config/app_settings.json` file and updating the `username` value in the `outbound` object e.g. on this [line](https://github.com/medic/interoperability/blob/main/cht-config/app_settings.json#L452).
+3. Securely save the `interop-client` user's password to the database using the instructions [here]({{< ref "building/reference/api#credentials" >}}). Change the values `mykey` and `my pass` to `openhim1` and your user's password respectively. An example of the curl request is below:
+
+```bash
+curl -X PUT -H "Content-Type: text/plain" http://admin:password@localhost:5988/api/v1/credentials/openhim1 -d 'interop-password'
+```
+
+### Local setup of CHT Configuration
+
+The following steps apply when running CHT locally in development mode and when making configuration changes locally:
+
+#### CHT Development Environment
+
+1. Set up a local CHT instance using [these instructions]({{< ref "building/local-setup" >}}).
+2. Create a new user in the CHT instance with the username `interop-client` using these [instructions]({{< ref "building/contact-management/contact-and-users-1#4-create-the-chw-user" >}}). For the role you can select `Data entry` and `Analytics` roles. Please note that you can use any username you prefer but you would have to update the config with the new username. You can do that by editing the `cht-config/app_settings.json` file and updating the `username` value in the `outbound` object e.g. on this [line](https://github.com/medic/interoperability/blob/main/cht-config/app_settings.json#L452).
+3. Securely save the `interop-client` user's password to the database using the instructions [here]({{< ref "building/reference/api#credentials" >}}). Change the values `mykey` and `my pass` to `openhim1` and your user's password respectively. An example of the curls request is below:
+
+```bash
+curl -X PUT -H "Content-Type: text/plain" http://medic:password@localhost:5988/api/v1/credentials/openhim1 -d 'interop-password'
+```
+4. After updating the mediator code or the CHT configuration, you need to run `./startup.sh up-dev` to upload the changes to docker compose.
+
+#### CHT Configuration
+
+1. Go into the `cht-config` directory by running `cd cht-config`.
+1. Run `npm install` to install the dependencies.
+1. Create a file named `.env` under `/mediator` folder, copy over the contents of `/mediator/.env.template` and update the `CHT_USERNAME` and `CHT_PASSWORD` values with the admin credentials of your CHT instance.
+1. Set up a proxy to your local CHT instance by running using something like [nginx-local-ip](https://github.com/medic/nginx-local-ip) or [ngrok](https://ngrok.com/) and update the `CHT_URL` value in the `.env` file with the new URL.
+1. Ensure you have [cht-conf](https://www.npmjs.com/package/cht-conf) installed and run `cht --local` to compile and upload the app settings configuration to your local CHT instance.
+1. To verify if the configuration is loaded correctly is to create a `Patient` and to access a URL like `https://*****.my.local-ip.co/#/contacts/patientUUID/report/interop_follow_up`. This should retrieve correctly the follow up form.
+1. To verify if the configuration in CouchDB, access `http://localhost:5984/_utils/#database/medic/settings`.
+
+### Shutdown the servers
+
+- To shut-down the containers run `./startup.sh down` to stop the instances.
+- To then restart the containers, run `./startup.sh up`. You do not need to run `init` again like you did in the initial install above.
+- To shut-down and delete _everything_, run `./startup.sh destroy`. You will have to subsequently run `./startup.sh init` if you wish to start the containers.
+
+### Troubleshooting
+
+#### Error "bind: address already in use"
+Users encountering:
+
+> Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:5000 -> 0.0.0.0:0: listen tcp 0.0.0.0:5000: bind: address already in use
+
+when running `./startup.sh init` need to update ports to available values in the `/docker/docker-compose.yml` file, under the `ports` verb.
+
+#### Error when running mediator `curl` request
+If the mediator `curl` request fails, visit [http://localhost:9000/#!/clients](http://localhost:9000/#!/clients) and click on the icon the red arrow points to in the image below.
+
+
+
+#### Error "Preset ts-jest is invalid:" when running `npm test`
+Users encountering the error below when running `npm test`:
+
+> Preset ts-jest is invalid:
+> The "id" argument must be of type string. Received null
+> TypeError [ERR_INVALID_ARG_TYPE]: The "id" argument must be of type string. Received null
+
+need to run `npm i --save-dev ts-jest` before running `npm test`.
+
+#### Error "unsuccessful npm install" when running `npm install`
+Users encountering the error when running `npm install`:
+
+> npm ERR! code EACCES
+> npm ERR! syscall unlink
+> npm ERR! path /Users/phil/interoperability/cht-config/node_modules/.package-lock.json
+
+need to run `npm install` as root user.
diff --git a/content/en/building/guides/interoperability/openhim/bad-client-screen.png b/content/en/building/guides/interoperability/openhim/bad-client-screen.png
new file mode 100644
index 000000000..8ad64f758
Binary files /dev/null and b/content/en/building/guides/interoperability/openhim/bad-client-screen.png differ
diff --git a/content/en/building/guides/interoperability/openhim/flow.png b/content/en/building/guides/interoperability/openhim/flow.png
new file mode 100644
index 000000000..cdd640f91
Binary files /dev/null and b/content/en/building/guides/interoperability/openhim/flow.png differ
diff --git a/content/en/building/guides/interoperability/openhim/good-client-screen.png b/content/en/building/guides/interoperability/openhim/good-client-screen.png
new file mode 100644
index 000000000..b3c1b5831
Binary files /dev/null and b/content/en/building/guides/interoperability/openhim/good-client-screen.png differ
diff --git a/content/en/building/guides/interoperability/openmrs.md b/content/en/building/guides/interoperability/openmrs.md
new file mode 100644
index 000000000..5bf82185d
--- /dev/null
+++ b/content/en/building/guides/interoperability/openmrs.md
@@ -0,0 +1,225 @@
+---
+title: "OpenMRS Interoperability"
+linkTitle: "OpenMRS"
+weight: 4
+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
+---
+
+[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" >}}).
+
+## Overview
+
+The CHT's interoperability tools support sends patient and reports data to OpenMRS.
+
+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. 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.
+1. [Set OpenMRS credentials and CHT credentials](#starting-the-interop-project) in the interoperability project, and start it in a production deployment.
+
+## Profiling
+
+The first step is to profile the workflow.
+
+1. Which patients should be sent to OpenMRS, and how is a patient defined in the CHT application?
+2. Which forms should be sent to OpenMRS?
+3. Which fields on those forms should be sent to OpenMRS, and which concepts do they map to?
+
+## Configuring CHT And OpenMRS
+
+Depending on what data needs to be exchanged, [outbound push]({{< ref "building/reference/app-settings/outbound" >}}) configurations and JSON forms need to be added to CHT.
+
+### 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" >}}).
+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.
+
+After setting up the outbound push config, test that it works in the test environment by creating a patient in the CHT application.
+Log in to OpenHIM and view the transaction log. You should see:
+1. A request from the CHT application to the CHT Mediator, containing the patient document.
+ 
+ ```json
+ {
+ "doc": {
+ "_id": "75905106a4bc2a9046ed28df070016ce",
+ "name": "John Test",
+ "phone": "+2548277217095",
+ "date_of_birth": "1980-06-06",
+ "sex": "male",
+ "patient_id": "13985"
+ }
+ }
+ ```
+1. A request from the CHT mediator to the FHIR Server, using a PUT request to upsert a FHIR patient created from the CHT patient document.
+ 
+ ```json
+ {
+ "resourceType": "Patient",
+ "id": "75905106a4bc2a9046ed28df070016ce",
+ "meta": {
+ "versionId": "1",
+ "lastUpdated": "2024-10-31T04:53:44.026+00:00"
+ },
+ "text": {
+ "status": "generated",
+ "div": "| Identifier | 13985 |
| Date of birth | 06 June 1980 |