chore(#1658): add openmrs and ltfu docs

content/en/building/concepts/interoperability.md

@@ -7,7 +7,9 @@ description: >
 keywords: interoperability integrations fhir icd openhie openhim
 relatedContent: >
   building/features/integrations
-  building/guides/interoperability/fhir
+  building/guides/interoperability/cht-config
+  building/guides/interoperability/openhim
+  building/guides/interoperability/ltfu
 aliases:
    - /apps/concepts/interoperability
 ---

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

@@ -1,12 +1,14 @@
 ---
-title: "Building Interoperability with FHIR systems"
-linkTitle: "Building Interoperability with FHIR systems"
-weight:
+title: "Configuring CHT applications for interoperability workflows"
+linkTitle: "Configuring"
+weight: 1
 description: >
-   Exchange patients and reports with FHIR compliant systems
+   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/
 ---
@@ -296,7 +298,7 @@ Using the above example form, this transition will create a patient document and
 `Encounters` and `Observations` created by interoperating systems can be sent to the CHT to be visible to CHT users.
 Similarly to patients, a mediator converts the FHIR resources to a json format that is submitted to the records API.
 Reports need to be linked to patients using a `patient_id` field which is the uuid of the patient document in CHT. The mediator extracts this id from the `CHT Document ID` identifier of the FHIR `Patient`. 
-For patients created by CHT, they need to have been sent to the interoperating system before receiving any reports. For patients created by the interoperating system, the `CHT Document ID` needs to have been set; see the section below on [Patient Ids]({{< ref "building/guides/interoperability/fhir#populating-ids" >}}).
+For patients created by CHT, they need to have been sent to the interoperating system before receiving any reports. For patients created by the interoperating system, the `CHT Document ID` needs to have been set; see the section below on [Patient Ids](#populating-ids).
 
 A CHT form needs to be configured to receive the reports via the records API.
 In the form configuration, the names of fields which should be extracted from `Observations` should be the codes of the `Observations`. Human readable labels can be added for display.

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

@@ -0,0 +1,141 @@
+---
+title: "OpenHIM Mediators"
+linkTitle: "OpenHIM Mediators"
+weight: 2
+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/
+---
+
+#### Overview
+
+The components and reference information for interoperability used in CHT Interoperability project are:
+
+- [OpenHIE](https://ohie.org/) defines the architecture for an interoperability layer.
+- [OpenHIM](http://openhim.org/) is a middleware component designed to ease interoperability between systems.
+- [HL7 FHIR](https://www.hl7.org/fhir/index.html) is a messaging format to allow all systems to understand the format of the message.
+
+#### CHT
+
+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)
+
+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" >}}).
+
+### Prerequisites
+
+- `docker`
+- `Postman` or similar tool for API testing.
+
+### Install & First Time Run
+
+1. Run `./startup.sh init` to start-up the docker containers on the first run or after calling `./startup.sh destroy`. Use `./startup.sh up` for subsequent runs after calling `init` without calling `destroy`.
+
+### OpenHIM Admin Console
+
+1. Visit the OpenHIM Admin Console at http://localhost:9000 and login with the following credentials: email - `[email protected]` and password - `interop-password`. The default User username for OpenHIM is `[email protected]` and password is `interop-password`. The default Client username is `interop-client` and password is `interop-password`.
+
+1. Once logged in, visit [http://localhost:9000/#!/mediators](http://localhost:9000/#!/mediators) and select the only mediator with the `Name` 'Loss to Follow Up Mediator'.
+
+1. Select the green `+` button to the right of the default channel to add the mediator.
+
+1. You can test the mediator by running:
+
+```bash
+curl -X GET http://localhost:5001/mediator -H "Authorization: Basic $(echo -n interop-client:interop-password | base64)"
+```
+
+You should get as a response:
+
+```json
+{ "status": "success" }
+```
+
+If everything is successful you should see this:
+
+<img src="good-client-screen.png" width="600">
+
+### CHT configuration with Docker
+
+The following steps apply when running CHT via the Docker setup provided in this repository:
+
+1. CHT can be accessed via `http://localhost:5988`, and the credentials are `medic`/`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 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'
+```
+
+### 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 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.
+
+![](bad-client-screen.png)
+
+#### 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.