chore(#1658): add openmrs and ltfu docs #1657

witash · 2024-10-28T09:41:52Z

Description

Closes #1658

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

njuguna-n

Great work on this! I have added some minor comments and typo fixes but approving now to unblock.

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

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

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

lorerod

Thanks @witash. Left some suggestions inline. Let me know what you think.

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

lorerod · 2024-11-12T17:25:18Z

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

+3. Receiving patient and patient contact data from OpenMRS.
+4. Receiving reports data (encounters and observations) from OpenMRS.
+
+The steps to create an OpenMRS interoperability workflow are:


The steps could be more actionable and descriptive to ensure readers understand each part thoroughly.

do you have any specific suggestions?

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

Co-authored-by: njuguna-n <[email protected]>

andrablaj · 2024-11-28T09:16:54Z

@witash I merged the main branch into this branch to get the latest updates from the site revamp. This helps better understand the overall Building section structure.

andrablaj

Thank you for the extended work in putting together this doc!
I shared a first batch of suggestions. Mainly:

Replace _ with - in the file/folder names.
Simplify linkTitle names to make the hierarchy simpler to read and navigate.
Added weight to pages so that the guides appear in a logical order.

I will go through the OpenMRS steps and add more comments, if any.

content/en/building/concepts/interoperability.md

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

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

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

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

andrablaj

Some suggestions based on my own comments above.

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

Co-authored-by: Andra Blaj <[email protected]>

witash · 2024-12-13T11:25:09Z

I removed the section on incoming patients from OpenMRS. Although technically the Gandaki flow does support this, it requires a lot of steps that may be difficult to generalize, so maybe we can not support this "officially" or include any documentation on it, which will necessarily either be incomplete, or add a lot stuff to this document.

andrablaj · 2024-12-16T08:36:46Z

@witash I see various updates on this PR. Is it ready for another review?

witash · 2025-01-10T08:52:43Z

@witash I see various updates on this PR. Is it ready for another review?

I think this is ready for another review

andrablaj

@witash I reviewed the content but didn't try to reproduce the OpenMRS steps.

This is a massive amount of work, thank you for putting it together! ⚡️

I added a few non-blocking suggestions.

It would be lovely if someone could go through the OpenMRS setup steps (@lorerod, @mrjones-plip ?) to validate the clarity of the instructions. I will try to do this myself next week, but I don't want to be a blocker to having this merged.

andrablaj · 2025-01-10T17:04:36Z

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

+
+## Steps
+
+The following steps assume that you successfully logged in into OpenHIM and the CHT instances.


Suggested change

The following steps assume that you successfully logged in into OpenHIM and the CHT instances.

The following steps assume you have running OpenHIM and CHT instances you successfully logged into.

suggestion: For extra clarity, I would mention that the reader should have running instances.

andrablaj · 2025-01-10T17:18:53Z

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

+> It is important to note that you only need to create an `Organization` once, which you can use for future requests. So, after creating the `Organization`, you can save the `organization.identifier[0].value` value and use it for all future `ServiceRequest` requests.
+
+
+1.  Create a **Patient**


For some reason (maybe because of the Note above), this appears as 1. in the list, and not as 2.

andrablaj · 2025-01-10T17:20:41Z

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

+    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`. This collection allows testing the LTFU flow while running the instances locally.


Suggested change

An API test collection that can be used with Postman or similar tools can be found under `/docs/local-test`. This collection allows testing the LTFU flow while running the instances locally.

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.

andrablaj · 2025-01-10T17:22:48Z

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

+  building/guides/integrations/openmrs/
+---
+
+#### Overview


Suggested change

#### Overview

### Overview

andrablaj · 2025-01-10T17:23:41Z

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

+- [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


Suggested change

#### CHT

#### Interoperability with the CHT

andrablaj · 2025-01-10T17:34:00Z

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

+- `docker`
+- `Postman` or similar tool for API testing.
+
+### Install & First Time Run


Suggested change

### Install & First Time Run

{{% alert title="Note" %}}

Users getting errors when running the following installation steps, please see the [Troubleshooting guide]({{< ref "#troubleshooting" >}}).

{{% /alert %}}

### Install & First Time Run

andrablaj · 2025-01-10T17:35:04Z

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

+
+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'.


Suggested change

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. 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".

andrablaj · 2025-01-10T17:36:18Z

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

+
+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:


Suggested change

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:

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:

andrablaj · 2025-01-10T17:38:17Z

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

+```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.


Suggested change

4. After updating the mediator code or cht configuration, you need to run `./startup.sh up-dev` to upload the changes to docker compose.

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.

andrablaj · 2025-01-10T17:39:34Z

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

+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.


Suggested change

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. 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.

lorerod · 2025-01-10T17:49:08Z

It would be lovely if someone could go through the OpenMRS setup steps (@lorerod, @mrjones-plip ?) to validate the clarity of the instructions. I will try to do this myself next week, but I don't want to be a blocker to having this merged.

@andrablaj, I have a pending re-review of this PR, and I will follow the OpenMRS setup steps next week.

witash added 2 commits October 28, 2024 12:40

feat(#129): add openmrs and ltfu docs

16f51d6

fix(#129): updating related links

35bd527

andrablaj changed the title ~~feat(#129): add openmrs and ltfu docs~~ feat(#1658): add openmrs and ltfu docs Oct 28, 2024

andrablaj changed the title ~~feat(#1658): add openmrs and ltfu docs~~ chore(#1658): add openmrs and ltfu docs Oct 28, 2024

witash added 3 commits October 30, 2024 13:07

fix(#129): add screenshots, troubleshooting, fix links, wording

5460126

feat(#129): adding steps, screenshots, and sample requests

34232e9

fix(#129): capitalization fixes, wording changes, small fixes

0b74681

witash marked this pull request as ready for review November 8, 2024 13:53

witash requested review from lorerod, andrablaj and njuguna-n November 8, 2024 13:54

njuguna-n approved these changes Nov 12, 2024

View reviewed changes

lorerod requested changes Nov 12, 2024

View reviewed changes

witash and others added 2 commits November 19, 2024 15:05

Apply suggestions from code review

a4f820d

Co-authored-by: njuguna-n <[email protected]>

Merge branch 'main' into 129-openmrs-interop

c5af60a

andrablaj requested changes Nov 28, 2024

View reviewed changes

content/en/building/guides/interoperability/troubleshooting.md Outdated Show resolved Hide resolved

content/en/building/guides/interoperability/troubleshooting.md Outdated Show resolved Hide resolved

andrablaj reviewed Nov 28, 2024

View reviewed changes

content/en/building/guides/interoperability/troubleshooting.md Outdated Show resolved Hide resolved

andrablaj mentioned this pull request Dec 12, 2024

Update OpenMRS documentation with CHT interoperability resources medic/cht-interoperability#155

Open

witash and others added 9 commits December 13, 2024 10:25

Merge branch 'main' into 129-openmrs-interop

560e0c1

feat(#129): adding back instructions from README

e4de838

feat(#129): cahning file names

788bcc9

Apply suggestions from code review

c02775d

Co-authored-by: Andra Blaj <[email protected]>

feat(#129): review suggestions

3f16a32

feat(#129): moving troubleshooting section

d9a6bce

feat(#129): changing image

44b60ca

feat(#129): review suggestions

5f1cdce

feat(#129): removing references to creating CHT patients in OpenMRS

a8c5428

Merge branch 'main' into 129-openmrs-interop

1172468

witash requested review from andrablaj, njuguna-n and lorerod and removed request for njuguna-n January 10, 2025 08:52

andrablaj approved these changes Jan 10, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

chore(#1658): add openmrs and ltfu docs #1657

chore(#1658): add openmrs and ltfu docs #1657

witash commented Oct 28, 2024 •

edited by andrablaj

Loading

njuguna-n left a comment

lorerod left a comment

lorerod Nov 12, 2024

witash Jan 10, 2025

andrablaj commented Nov 28, 2024

andrablaj left a comment

andrablaj left a comment

witash commented Dec 13, 2024

andrablaj commented Dec 16, 2024

witash commented Jan 10, 2025

andrablaj left a comment

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

andrablaj Jan 10, 2025

lorerod commented Jan 10, 2025


		## Steps

		The following steps assume that you successfully logged in into OpenHIM and the CHT instances.

	The following steps assume that you successfully logged in into OpenHIM and the CHT instances.
	The following steps assume you have running OpenHIM and CHT instances you successfully logged into.

		> It is important to note that you only need to create an `Organization` once, which you can use for future requests. So, after creating the `Organization`, you can save the `organization.identifier[0].value` value and use it for all future `ServiceRequest` requests.


		1. Create a Patient

		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`. This collection allows testing the LTFU flow while running the instances locally.

-### Install & First Time Run
+{{% alert title="Note" %}}
+Users getting errors when running the following installation steps, please see the [Troubleshooting guide]({{< ref "#troubleshooting" >}}).
+{{% /alert %}}
+### Install & First Time Run


		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'.

	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:
	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:

	4. After updating the mediator code or cht configuration, you need to run `./startup.sh up-dev` to upload the changes to docker compose.
	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.

	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. 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.

chore(#1658): add openmrs and ltfu docs #1657

Are you sure you want to change the base?

chore(#1658): add openmrs and ltfu docs #1657

Conversation

witash commented Oct 28, 2024 • edited by andrablaj Loading

Description

License

njuguna-n left a comment

Choose a reason for hiding this comment

lorerod left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrablaj commented Nov 28, 2024

andrablaj left a comment

Choose a reason for hiding this comment

andrablaj left a comment

Choose a reason for hiding this comment

witash commented Dec 13, 2024

andrablaj commented Dec 16, 2024

witash commented Jan 10, 2025

andrablaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lorerod commented Jan 10, 2025

witash commented Oct 28, 2024 •

edited by andrablaj

Loading