[Server Side] Add the Practitioner Details Fetch endpoint

[dubdabasoduba]

Is your feature request related to a problem? Please describe.

• We would like to be able to get all the practitioners' details which include things like ROLEs, Demographic information & any FHIR resources (e.g teams, care teams e.t.c) associated with the logged-in user.

Describe the solution you'd like

• Add a practitioner details fetch endpoint. The endpoint is to be named /practitioner-details/{keycloak-uuid} , the method is aGET
• The following items should be returned by the endpoint response.
  • Practitioner ROLEs & Practitioner demographics from keycloak.
    • Currently you could get the keycloak id by checking the secondary identifier in the Practitioner object.

{
	"resourceType": "Practitioner",
	"identifier": [
	  	{
			"use": "official",
			"value": "ce2e430b-64be-477e-9d86-b36c666c0211" --- Auto generated same as the uuid
		},
		{
			"use": "secondary",
			"value": "287aff05-ff9b-4b07-b525-8860c70377d0" --- User id from keycloak
		}
	],
	"active": true, --- use the enabled values. true for yes & false for no
	"name": [
		{
			"use": "official", -- use as is
			"family": "Williams", --- last name
			"given": [
				"Ward", --- middle name
				"N" -- last name
			]
		}
	],
	"telecom": [
		{
			"system": "email", --- use as is 
			"value": "[email protected]" --- email collected 
		}
	]
}

• FHIR related data points
  • Fetch all the care teams a practitioner is added to.
  • Fetch all the organizations a practitioner is assigned to this is using the practitioner roles.
  • Using the Organisation affiliation get the locations a practitioner is assigned to.
  • The location hierarchy for the location the practitioner is assigned to.

Sample endpoint calls to fetch the data.

• HAPI FHIR practitioner resource endpoint e.g https://fhir.labs.smartregister.org/fhir/Practitioner/_search?identifier=287aff05-ff9b-4b07-b525-8860c70377d0
  • Gets the Practitioner details using the keycloak Id.
• HAPI FHIR practitioner role & Organisation endpoint e.g https://fhir.labs.smartregister.org/fhir/PractitionerRole/_search?practitioner=102
  • Practitioner assigned organization
    • From the endpoint above we can get the Organisation name and the Organisation Id. For us to get the whole organization we will need another query to the organization.
• HAPI FHIR CareTeam endpoint role e.g https://fhir.labs.smartregister.org/fhir/CareTeam/_search?participant=104
  - Practitioner assigned care teams
• HAPI FHIR practitioner role & Organisation endpoint e.g https://fhir.labs.smartregister.org/fhir/PractitionerRole/_search?practitioner=102 & the Organisation Affiliation Resource endpoint e.g https://fhir.labs.smartregister.org/fhir/OrganizationAffiliation/_search?primary-organization=212
  • Practitioner assigned location
    • First get all the Organisations a practitioner is assigned to. Then get all the Locations an Organisation is assigned to by reference in the Organization Affiliation.
    • For us to get a full Location Object then we will need to get hit the Location resource endpoint with the location id (s) from a specific organization affiliation.
  • Practitioner Location Hierarchy
    • We need to hit the location hierarchy endpoint with the location Id(s) from the organization affiliation endpoint.
      https://fhir.labs.smartregister.org/fhir/LocationHierarchy?identifier=93bc9c3d-6321-41b0-9b93-1275d7114e22
    • The Location hierarchy endpoint requires an identifier and not the id

Additional context

• Sample response

[pld]

Suppose I'm a supervisor app and I need the details on the HCWs I'm managing to show them in a list, see their assigned tasks, maybe modify assignments or details.

How would I get the details for a set of practitioners?

[rehammuzzamil]

As per our discussion @dubdabasoduba , a practitioner can be assigned to several organizations/teams at a time, which in return can cause a practitioner to be tied up to numerous locations. Therefore, we will keep the provision of multiple location hierarchies in the response payload.
cc : @f-odhiambo @RaaziaTarique

[pld]

Suppose I'm a supervisor app and I need the details on the HCWs I'm managing to show them in a list, see their assigned tasks, maybe modify assignments or details.

How would I get the details for a set of practitioners?

any comment on this?

[rehammuzzamil]

Suppose I'm a supervisor app and I need the details on the HCWs I'm managing to show them in a list, see their assigned tasks, maybe modify assignments or details.
How would I get the details for a set of practitioners?

any comment on this?

Apologies @pld for missing your prior comment.
Yes, I believe that in this instance, we need to update API to return a list of practitioners (together with their assigned tasks) that the supervisor is in charge of. Currently, the scope of the practitioner-details end-point does not contain this, but we can perform some research and development on it.
We can also change the API contract (signature) to only deliver a set of practitioner details if the request parameters specify that the user is a "supervisor."

Wrt the modification of assignments and details, this would require a separate POST end-point.
cc : @dubdabasoduba Please share your thoughts.

[pld]

No worries, ok that sounds good! As you've explained, based on the way the APIs are scoped this is not relevant to the work we're doing towards this specific issue, that makes sense to me, thanks!

[f-odhiambo]

@rehammuzzamil Do we have a PR for this work ? What's the status?

[rehammuzzamil]

@rehammuzzamil Do we have a PR for this work ? What's the status?

Yes @f-odhiambo , the following three PRs are for the practitioner details end-point.

1. https://github.com/opensrp/fhir-common-utils/pull/1/files
2. 853 : Expose Practitioners Detail Endpoint hapi-fhir-opensrp-extensions#12
3. https://github.com/opensrp/hapi-fhir-jpaserver-starter/pull/24/files

There is one pre-requisite PR on JPA Server to bump up HAPI FHIR Versions to mitigate log4j vulnerabilities. It is failing CI as there were a few changes done on the HAPI version >= 5.6.0 and refactoring were not done on the JPA project. Therefore, it is a kind of a blocker (from the HAPI side) to merge this opened PR.

As per my suggestion shared with @dubdabasoduba , we can merge our Practitioner Details end-point opened PRs and let the version upgrade one in the backlog to fix it later.
cc : @dubdabasoduba

[f-odhiambo]

Updated by @rehammuzzamil on Mar 22nd

Practitioner Details End-point:

• I have re-tested the flow on my local, and it works completely fine.
• To further debug the API, I have pointed Keycloak configurations to the Stage Keycloak server and it worked fine.
• I also requested Ben to share Stage HAPI DB Creds but I am unable to access the stage database from my machine. Tried connecting via IDE/SSH both does not work, also tried to make a connection directly via code, but it also fails.
  psql: error: connection to server at "postgres.opensrp-shared-stage.smartregister.org" (34.251.85.94), port 5432 failed: Connection timed out
  Is the server running on that host and accepting TCP/IP connections?
  and
  org.postgresql.util.PSQLException: The connection attempt failed.
• As per discussion with Ben, it's because I am not authorized to access ONA servers. Shared IP for whitelisting

[rehammuzzamil]

Brief Updates as of 13th July, 2022:

• Testing out by pointing my local server to the FHIR Stage DB (IP got whitelisted earlier)
• Explored high-level advanced search features.
• Implemented advanced search to fetch OrganizationAffiliation and Locations within a single search call, this helped us to reduce the count of searches in our Rest API by 1.
• Observed that one more search call can be reduced by implementing advanced search on fetching of Practitioner Roles and Organizations in a single call (Under development/testing)
• Fetching of care teams takes quite a long to complete (Bottleneck)
• Raw/Draft PR link https://github.com/opensrp/hapi-fhir-opensrp-extensions/pull/24/files (will update)

cc : @f-odhiambo @dubdabasoduba @ageryck