eCHIS users App management page improvements

[PhilipNgari]

linked to #https://github.com/moh-kenya/config-echis-2.0/issues/2504.

Intended capabilities to strengthen user management.

1. The ability of a user manager to view no of users in an instance via the user management page
2. Ability to export the users

[jkuester]

Thanks for raising this @PhilipNgari! Can you describe a bit more about #2?

1. What kind of data would you like to export for each user? Is this for reporting/data collection about the instance or are you wanting to be able to re-import these users back into another instance?
2. Do you need to export the data for all users, just a single user, or for some sub-set of users?
3. What is the desired format for the data? (e.g. JSON array, CSV, etc)

[PhilipNgari]

The export would be needed for all users, and in a CSV format.

[jkuester]

Got it, thanks! And finally, what kind of data do you want to be included for the user? For example our users REST API returns data like this:

{
  "id": "org.couchdb.user:demo",
  "rev": "14-8758c8493edcc6dac50366173fc3e24a",
  "type": "district-manager",
  "fullname": "Example User",
  "username": "demo",
  "place": {
    "_id": "eeb17d6d-5dde-c2c0-62c4a1a0ca17d38b",
    "type": "district_hospital",
    "name": "Sample District",
    "contact": {
      "_id": "eeb17d6d-5dde-c2c0-62c4a1a0ca17fd17",
      "type": "person",
      "name": "Paul",
      "phone": "+2868917046"
    }
  },
  "contact": {
    "_id": "eeb17d6d-5dde-c2c0-62c4a1a0ca17fd17",
    "type": "person",
    "name": "Paul",
    "phone": "+2868917046"
  }
}

I am thinking that some sub-set of this data might be the most useful to export. 🤔

[PhilipNgari]

Thanks @jkuester ,here is the format

county name	Names (philip ngari,etc)	eCHIS username	designation (CHP,CHA,county focal person)	CHU name	CHU Code	link facility name	link facility code	telno

[jkuester]

Thanks! For some of these fields, it is pretty clear (I think) where we can load the data from the db:

• user-settings.fullname - Names (philip ngari,etc)
• user-settings.name - eCHIS username
• user-settings.roles - designation (CHP,CHA,county focal person)
• user-settings.phone - telno

It would be good if someone familiar with the ECHIS data could confirm this is correct.

For the other fields, I need a bit more info on how they are used. For the CHU and the Link Facility, are these the parent/grandparent places for the users contact? What is the "Code" value for these? And finally, where/how is the county name stored for the user?

• county name
• CHU name
• CHU Code
• link facility name
• link facility code

[PhilipNgari]

cc'ing @alexosugo to guide who can team tag with you.Cheers.

[PhilipNgari]

Checking on the progress of this. The current eCHIS restoration and CHW-R will likely piggyback on this, as counties might be required to frequently conduct data clean-up. I request we re-prioritise.

[jkuester]

👍 @alexosugo can we get clarification and more information for my question above?

[alexosugo]

Hey @jkuester. The CHU is the grandparent place for a user's contact. The contact document for the CHU also contains the CHU Code, Link Facility name and code. This data is referenced from KMFHR.

The Link Facility code is a 5-digit numeric code while the CHU code is a 6-digit numeric code. Below is a sample CHU document with that information:

{
  "_id": "3d64ca2c-f7dc-4d07-b84a-5f36ba8b2ee3",
  "_rev": "2-301a86cf67f937822bd209453a35ee8b",
  "name": "Abdisamit Community Health Unit",
  "code": "700908",
  "link_facility_name": "Abdisamit Dispensary",
  "link_facility_code": "17009",
  "type": "contact",
  "contact_type": "c_community_health_unit",
  "parent": {
    "_id": "0aaba6fc-e6f4-4ffd-a84f-c8a3e1caeef5",
    "parent": {
      "_id": "94cb035f-cc30-44de-b7e3-2a2452546882"
    }
  },
  "user_attribution": {
    "tool": "cht-user-management-1.3.15",
    "username": "medic",
    "created_time": 1714040073851
  },
  "contact": {
    "_id": "fbb29ea3b84725fb3323c0e7a801bf00"
  },
  "reported_date": 1714040073965,
  "form_version": {
    "time": 1725258584684,
    "sha256": "c1fbf0de4b1563415595d08ce0e2eebca1c5992bae7f4cd491a3202eaeab3152"
  }
}

The county name is stored in the grandparent place of the CHU. The hierarchy is chp -> chp area -> chu -> subcounty -> county

[jkuester]

Thanks @alexosugo! So, based on what has been provided, does this breakdown look accurate?

From user-settings:

• Names (philip ngari,etc) - {{user-settings}}.fullname
• eCHIS username - {{user-settings}}.name
• designation (CHP,CHA,county focal person) - {{user-settings}}.roles
• telno - {{user-settings}}.phone

From grandparent place (the CHU) for user contact:

• CHU name - {{chu-contact}}.name
• CHU Code - {{chu-contact}}.code
• link facility name - {{chu-contact}}.link_facility_name
• link facility code - {{chu-contact}}.link_facility_code

From great-great-grandparent place (the county) for the user contact:

• county name - {{county-contact}}.name

---

One question I have is for the "Names" and "telno" information, should we load that from the user's contact doc or from the user-settings doc? Which is more likely to be populated/accurate?

The big design question we face here, though, is how do we distill this feature such that it fulfills these requirements, but is still generic enough to be useful to the broader community (and not eCHIS-specific)....? 🤔

Another issue is going to be how to make this perform reasonably on an instance with thousands of users? I count at least 4 docs we will have to load for each user. 😬 I think it might be fine (since we are mostly just looking up by _id), we will want to pay attention to this going forwards...

[PhilipNgari]

@alexosugo pinging you on this.

[alexosugo]

Hey @jkuester @PhilipNgari.

One question I have is for the "Names" and "telno" information, should we load that from the user's contact doc or from the user-settings doc? Which is more likely to be populated/accurate?

The contact doc is more likely to be accurate as it would get more updates over the user-settings.

The big design question we face here, though, is how do we distill this feature such that it fulfills these requirements, but is still generic enough to be useful to the broader community (and not eCHIS-specific)....? 🤔

Loading entire user lists for counties with a lot of users is quite slow. One way would be to have the list default to the CHW since they're the main users of eCHIS and have a drop-down for choosing other user types.

[jkuester]

Okay, so digging in a bit here, I think the level of effort is going to depend on exactly how much of this data is required (and how convenient it needs to be to access the data).

---

The existing GET /api/v2/users endpoint already will support returning this data for all users (works on all CHT instances 4.1.0+):

• "eCHIS username" - {{user}}.name
• "designation (CHP,CHA,county focal person)" - {{user}}.roles
• "Names (philip ngari,etc)" - {{chw-contact}}.fullname
• "telno" - {{chw-contact}}.phone

---

Adding this to our normal export endpoints so this data is returned as a CSV (and a user can export this CSV from the Admin app) should be trivial. ("Extra small" tee shirt size estimate.)

---

Enhancing the new export endpoint to return more data about the parent hierarchy for the user would also be fairly simple. We could have it include the name values of all the parents in the hierarchy. (Once we have the contact data for the user, we should have all the hierarchy Ids and so can get the parent docs directly or get the summaries via the medic/doc_summaries_by_id view). This would give access to:

• "CHU name" - {{chu-contact}}.name
• "county name" - {{county-contact}}.name

Here we are probably looking at a "Small" tee shirt size estimate. The data flow should still be pretty straight forward.

---

Unfortunately, we are still missing this data:

• "CHU Code" - {{chu-contact}}.code
• "link facility name" - {{chu-contact}}.link_facility_name
• "link facility code" - {{chu-contact}}.link_facility_code

As I noted before, this is going to be more tricky to include in the export endpoint because (as I understand it) these fields are custom to the ECHIS deployment and are not included directly on the user's contact document.

The current GET /api/v2/users endpoint will return the entire contents of the user's contact doc. So, if we could de-normalize this data down into the user's contact, it would be returned automatically. Unfortunately, I think if we try to return the entire contact docs for all the contacts in each user's hierarchy it will just be too much data to export.

[jkuester]

Just to add more context here, @PhilipNgari confirmed on Slack that this functionality really needs to be accessible to users on the front-end (and so a custom script is not going to be feasible). So, the main options I see here are:

1. Add the user export functionality so the Admin app offers a self-service user export-to-csv tab (similar to the other contacts/reports/etc). The exported data would include the same info as returned from the GET /api/v2/users endpoint plus at least the names of each of the parent contacts in the hierarchy. However, the CHU Code, Link Facility Name, and Link Facility Code will not be included. a. One variant here would be to de-normalize the CHU Code, Link Facility Name, and Link Facility Code down onto the user's contact docs (e.g. copy them in in the create form) then this data would be automatically included in the exported data. (Would need some script to update the existing user contact docs too.)
2. The other, more "outside-the-box" alternative would be to leverage the incoming CHT Plugin functionality and have a custom client-side widget that could perform some custom export logic to not only get the /api/v2/users endpoint data, but also to include the CHU Code, Link Facility Name, and Link Facility Code for each user. Really the logic/data-model is very straightforward and I think it is very aligned with a lot of the other problems that the plugin squad is looking to solve. The downside is that we have only just started the design discussion around plugins and support for that is definitely not going to land in the CHT this year.

[PhilipNgari]

Thanks @jkuester, option no. 1 a seems a workable solution for the situation at hand. Allow me to rope @freddieptf here as he has extensively worked in the UMT.His thoughts might help us unlock a solution quickly.