feat(#129): adding back instructions from README

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

@@ -27,10 +27,11 @@ The document provided includes placeholders for URLs. Replacing these placeholde
 ## Steps
 
 The following steps assume that you successfully logged in into OpenHIM and the CHT instances.
+See the [OpenHIM guide]({{< ref "building/guides/interoperability/openhim" >}}) for instructions to set up a local development instance of OpenHIM.
 
 1.  Create an **Endpoint** and an **Organization**
 
-    1. **HTTP Request** - Use Postman to create an `Endpoint` Resource in the Mediator. You can view the API documentation for creating an `Endpoint` [here](#endpoint-resource). Once you send the request, the Mediator will return a JSON response containing the `id` of the newly created endpoint.
+    1. **HTTP Request** - Use Postman to create an `Endpoint` Resource in the Mediator. You can view the API documentation for creating an `Endpoint` [here](#endpoint-resource). Once you send the request, the Mediator will return a JSON response containing the `id` of the newly created endpoint. Save this `id` for the next step.
 
     1. **HTTP Request** - Create an `Organization` Resource in the Mediator using as `endpoint.reference` the example value replacing `${ENDPOINT_ID}` with the actual `id` of the `Endpoint` you created in the previous step. Once you send the request, the Mediator will return a JSON response containing the `id` of the newly created `Organization`. You can view the API documentation for creating an `Organization` [here](#organization-resource).
 
@@ -40,7 +41,7 @@ The following steps assume that you successfully logged in into OpenHIM and the
 
 1.  Create a **Patient**
 
-    1. **CHT** - Log in to the CHT platform using the credentials for the `chw` user.
+    1. **CHT** - Log in to the CHT platform using the credentials for the `chw` user (if the `chw` user does not already exist, you can [create one]({{< ref "building/contact-management/contact-and-users-1#4-create-the-chw-user" >}}).
     1. **CHT** - Navigate to the `People` tab in the CHT dashboard. From there, select a Facility where you want to create a new `Person`. Click on the `New Person` button and fill in the required details for the Person. Make sure to select `Patient` as the `Person`'s role for this flow.
     1. **CHT** - Once you have created the new `Person`, you need to retrieve their unique identifier from the browser's URL. You can do this by copying the alphanumeric string that appears after `person/` in the URL. Keep this identifier safe as you will need it for the next steps.
     1. **OpenHIM Admin Console** - To verify that the `Patient` creation was successful, navigate to the `Transaction Log` in the OpenHIM Admin Console. You should see two successful API calls recorded in the log, one to `/mediator/patient/` and one to `/fhir/Patient/`.

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

@@ -27,16 +27,16 @@ The structure of documents in the CHT database reflect the configuration of the
 
 ![](flow.png)
 
-This project uses OpenHIM as the middleware component with [Mediators](http://openhim.org/docs/configuration/mediators/) to do the conversion. [Outbound Push](https://docs.communityhealthtoolkit.org/apps/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.
+This project 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](https://docs.communityhealthtoolkit.org/apps/reference/api/) to update the document in the CHT database. This will then be replicated to users’ devices as per usual.
+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](https://docs.communityhealthtoolkit.org/apps/concepts/interoperability/) page on the CHT documentation site.
+See more information on the [CHT interoperability]({{< ref "building/concepts/interoperability" >}}) page on the CHT documentation site.
 
 ### Prerequisites
 
 - `docker`
-- `Postman` or similar tool for API testing. This will play the role of the `Requesting System` from the sequence diagram above.
+- `Postman` or similar tool for API testing.
 
 ### Troubleshooting
 
@@ -70,6 +70,43 @@ 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.

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

@@ -29,7 +29,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-test` in the interoperability project.
 1. Create or find concepts in OpenMRS that represent any data that needs to be exchanged.
-1. Configure outbound push and forms in the CHT application to match the interoperability workflow.
+1. Configure [outbound push]({{< ref "building/reference/app-settings/outbound" >}}) and forms 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.
@@ -56,7 +56,7 @@ The first step is to profile the workflow.
 
 ## Configuring CHT And OpenMRS
 
-Depending on what data needs to be exchanged, outbound push configurations and JSON forms need to be added to CHT.
+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
 
@@ -148,7 +148,7 @@ Then, using the appropriate codes, configure an outbound push as described in th
 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`.
 
-After setting up the putbound push, test that it works in the test environment by submitting a report to the form in the CHT application.
+After setting up the outbound push, test that it works in the test environment by submitting a report to the form 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 all the fields from the form that were mapped to concepts.
     ![](cht-post-encounter.png)