[New Feature Request]: Bulk import/export tool for user accounts, location hierarchies, and team/location assignments

[joyce-x-chen]

Feature Use Case

Users of OpenSRP/FHIR Web (e.g. program administrators, project managers, and/or technical partners) need to do the following at scale:

• establish location hierarchies
• create user accounts
• create teams
• assign each user to a team
• assign each team to one or more locations

The current solution of creating the location hierarchy, user accounts, and teams manually, and making assignments manually for each user, is not feasible at scale.

Acceptance criteria

There is demand for a tool that allows bulk import of location hierarchies, user accounts, team names, and corresponding assignments using a simple format (e.g. CSV) that does not require programming skills. The tool would ideally also validate the data and generate an error message for missing, invalid, or inconsistent assignments. Potential outputs include:

• Templates using standardized data model with
  1. establish location hierarchies
  2. create teams and and their corresponding location assignments
  3. create user accounts (including minimum required information - e.g. role, password) and their corresponding team (and location) assignments
• UI with validations for import of
  1. location hierarchies
  2. teams
  3. user accounts
• UI for export
  1. location hierarchy
  2. teams and their location assignments
  3. user accounts information, including roles and assignments

Project Contact

All digital health PMs

Relevant Information

This has been requested by many internal and external stakeholders for a number of digital health projects. The current method of creating user accounts and location hierarchies manually, and making those assignments manually, is time-consuming and error prone. A substantial amount of time in the post-deployment phase is spent troubleshooting and supporting partners with user account, location hierarchy, and assignment errors.

[Wambere]

More details: https://docs.google.com/document/d/10prv9DrMBy7ydNmWJxtPBm5c_qBFO6BFLGjwqVIOIq8/edit

Tasks:

• [ ] Build spreadsheet template for location units
• [ ] Build spreadsheet template for user accounts
• [x] Read csv
• [x] Build location resource payloads
• [x] Build keycloak user payload
• [x] Build keycloak group payload
• [x] Build practitioner resource payload
• [x] Build group resource payload
• [x] POST request

[peterMuriuki]

User creation request and payload currently done by the web

Keycloak User

use:

• role based access.

endpoint: POST https://keycloak-stage.smartregister.org/auth/admin/realms/<realm>/users

payload:

ref:

• https://www.keycloak.org/docs-api/18.0/rest-api/#_users_resource
• payload-structure - https://www.keycloak.org/docs-api/18.0/rest-api/#_userrepresentation

• fhir-core-app-id: https://github.com/opensrp/web/issues/1147

  The web gets the keycloak-id in the response to the post request.

  {"firstName": ,"id":,"lastName":,"username":,"enabled":true,"attributes":{"fhir_core_app_id":[]}, credentials: }

Keycloak Group

prerequisite:

• created user
• groups on keycloak

use:

• Add created user to a group

endpoint: PUT https://keycloak-stage.smartregister.org/auth/admin/realms/<realm>/users/<user-id>/groups/<group-id>

payload: ref:

• https://www.keycloak.org/docs-api/18.0/rest-api/#_joingroup

Practitioner Resource

prerequisite:

• create keycloak user

use:

• Represents a fhir keycloak user on fhir.

endpoint: PUT: https://fhir.labs.smartregister.org/fhir/Practitioner/<guid>

payload:

ref:

• https://hl7.org/fhir/r4b/practitione.html#resource

  const payload: IPractitioner = { resourceType: practitionerResourceType, id: , identifier: [{use: "Official", value: }, {use: "secondary", value: }], active: , name: [ { use: IdentifierUseCodes.OFFICIAL, family: values.lastName, given: [values.firstName, ''], }, ], telecom: [ { system: 'email', value: values.email, }, ], };

PractiitonerRole Resource

prerequisite:

• create user
• create practitioner

use:

• To categorize users as either supervisor or Normal Practitioners
• see https://github.com/opensrp/web/issues/1095

endpoint: PUT: https://fhir.labs.smartregister.org/fhir/PractitionerRole/<guid>

payload:

ref:

• https://hl7.org/fhir/r4b/practitionerrole.html#resource

• https://github.com/opensrp/web/issues/1095#issuecomment-1306884156

  const payload: IPractitionerRole = { resourceType: "PractitionerRole", id: , identifier: [ { use: IdentifierUseCodes.OFFICIAL, value: , }, { use: IdentifierUseCodes.SECONDARY, value: }, ], active: , practitioner: { reference: Practitioner/${practitionerID}, display: , }, code: , // see issue comment }

Fhir Group Resource

prerequisite:

• create user
• create practitioner

use:

• https://github.com/opensrp/web/issues/1094

endpoint: PUT: https://fhir.labs.smartregister.org/fhir/Group/<guid>

payload:

ref:

• https://hl7.org/fhir/r4b/Group.html#resource

• https://github.com/opensrp/web/issues/1094#issuecomment-1263316788

  const payload: IGroup = { resourceType: "Group", id: , identifier: [ { use: "official", value: }, { use: "secondary", value: }, ], active: , type: 'practitioner', actual: true, code: { coding: [ { system: 'http://snomed.info/sct', code: PRACTITIONER_USER_TYPE_CODE, display: 'Assigned practitioner', }, ], }, name: , member: [ { entity: { reference: Practitioner/${practitionerID}, display: }, }, ], };

[Wambere]

Initial PR with MVP https://github.com/onaio/fhircore-tooling/pull/3

[Wambere]

Hey @dubdabasoduba, couple of questions for you here

• the organization has an official identifier should I generate a new uuid for this or is it pulled from somewhere?
• I was planning on matching what the web does by including "type":[{"coding":[{"code":"team","system":"http://terminology.hl7.org/CodeSystem/organization-type"}]}] - but then I've noticed that this is not in all organizations. Can you confirm if I should include it or not?

[dubdabasoduba]

@Wambere

• The official identifier is an auto-generated UUID.
• "type":[{"coding":[{"code":"team","system":"http://terminology.hl7.org/CodeSystem/organization-type"}]}] should be added. The organisation resource can represent different things. The above code type helps us identify the Organization resource representing teams.