Sync by Team & Sync by Location mapping definition

[dubdabasoduba]

How to sync patient data

• The FHIR practitioner details fetching work is a pre-requisite to this work.
• All the resource linkage definitions here are governed by this location mapping diagram https://github.com/opensrp/fhircore/blob/main/docs/assets/resource-graph/unified-resource-graph-v01.png

Pre-Requisites

• All patients should be assigned to a group
• A care team should be created and all practitioners responsible for providing care to patients added to the care team.
• All care teams should have a managing organisation. This can be a virtual organisation that represents a larger team in a facility. E.g we can have a team called Facility A this team can be a managing organisation to CareTeam A, CareTeam B in the same facility.
• Locations will only be assigned to Organisations i.e Location A will only be assigned to Facility A and all the care teams infer their locations from this assignment.

- Sync By team.

Implementation Process (Using the Care team as the main team)

• Get the care team from the practitioner details fetch after login.
• Check the subject attribute on the Care team. This will have the Groups that the Care team is responsible for.
• Fetch the patients in the group by checking the participant attribute.
  • The member attribute holds the patient reference. Fetch this list and display them to the logged-in user.

Implementation Process (Using the Organization as the main team) 🚧 -- FHIR search does not allow searching using the managingOrganization attribute.

• Get the care team from the practitioner details fetch after login.
• Get the Organization managing the Care team by checking the managingOrganization attribute.
• Fetch the organisation and get its identifier.
• Search for all the care teams managed by this organization by using the following endpoint. 🚧 -- Needs figuring out
• Get all the groups in each care team
  • Aggregate the patient lists and display the list to the logged-in user.

- Sync By Location.

Implementation Process

• Get the care team from the practitioner details fetch after login.
• Using the practitioner id, get the care team the practitioner is assigned to.
• Using the care team get the organization the care team is assigned to by checking the managingOrganization
• Using the organization id get the organization affiliation that links the locations to organizations
• This should get the location id.
• With the Group Location extension get all the groups with the specified location.
  • Loop through all the groups with the matching extension and get the patients in each.

[pld]

Are the pre-reqs the same for both syncs? If so, we could say these are general pre-reqs for sync and list them once

1. How do we know what Group to assign a Patient to?
2. What is the meaning associate with the Patient Groups?
3. Can we avoid the loop in the final step of sync by location implementation process?

[pld]

Cool, that makes sense to me. Thinking about groups based on health track

• patients will definitely be assigned to multiple groups sometimes, like a TB and ANC patient
• group assignments will need to change offline (if we want them to be accurate), like an ANC patient may become an L&D, then PNC patient all offline, but the server would not know about this until after re-sync, and they might never know the patient was in an intermediate group

I think my main hesitation is do we need the indirection of groups here between Care Teams and Patients? What if we assign Patients directly as subjects to the CareTeams? I'm not convinced we lose much there, and we gain simplicity

[dubdabasoduba]

@pld another reason for the addition of groups was the subject attribute in the careteams resource only accept one object and not an array.
The participant attribute accepts an array but we are already using that to assign practitioners. I am not sure if reusing the same field for patients is advisable.

[dubdabasoduba]

K, can you explain the context and ask on the WHO Tuesday call, what people would use to track which patients are assigned to which health tracks? And that we are considering using groups for this. There might a standard way to do this, @trevorgowing @bausmeier have you seen how others do this in your FHIR work?

Sure, I will follow up with @f-odhiambo to make sure it's added to the agenda.

[dubdabasoduba]

• group assignments will need to change offline (if we want them to be accurate), like an ANC patient may become an L&D, then PNC patient all offline, but the server would not know about this until after re-sync, and they might never know the patient was in an intermediate group

• Could we track these movements via encounters? i.e if an encounter that moves a woman from ANC > PNC is available then we use it to show the previous health track.

[pld]

@pld another reason for the addition of groups was the subject attribute in the careteams resource only accept one object and not an array. The participant attribute accepts an array but we are already using that to assign practitioners. I am not sure if reusing the same field for patients is advisable.

Good point, we could not use the subject field that has cardinality of 0 or 1.

Reading the resource more carefully, I do think it is appropriate to use the participant attribute, because it allows Patient resources to be referenced from member and lets you set a role of type Participant Roles, which includes the role Patient.

Would we be able to index the member list by role? If so we could get nice quick look-ups of our Patient sub-list vs our Assigned Practitioners (that's also on Participant Roles, it lets you break down practitioner roles into nurse, medical, etc too) sub-list

[dubdabasoduba]

Sync By Team (Organization) UML diagram

[dubdabasoduba]

Sync By CareTeam UML diagram

[dubdabasoduba]

Sync By Location diagram

[ekigamba]

Syncing patient-related data

Patient-related data are Observations, Encounters, Condition and QuestionnaireResponses. These resources form a majority of the data synced by the app since they are generated for every patient encounter.

I believe these resources except configs(Parameters, Binary and/or Questionnaires) will also need to be synced by team, location or organisation.

We need sync by team, organisation and location for the remaining resources for the following reasons:

• Security of medical data i.e patient status, observations, tests and medications need to be synced and accessible to only the approved team, organisation or location
• Reduce the amount of data synced. This will improve performance in terms of smaller sync data size, shorter sync time and save space on an offline database

We can have each device-generated resource tagged with the respective filter i.e:

Filter	Tag URL	Tag value
Team	https://smartregister.org/fhir/sync-filter	{{team-resource-id}}
Location	https://smartregister.org/fhir/sync-filter	{{location-resource-id}}
Organisation	https://smartregister.org/fhir/sync-filter	{{organisation-resource-id}}

Below are the reasons for using the Resource.meta.tag is:

• It can be used for any resource since it's a property on the base Resource. See here and here.
• We can add multiple tags on a resource
• Provides better performance compared to alternatives such as syncing each patient's observation using Observation.subject. The alternatives would require multiple API calls, and more sync logic to achieve this and it would require customisation for each resource filtered by location, team or organisation
• It is natively indexed on both the server and client. Therefore it can be used as a search parameter on either client (location-selector changes) and server(syncing)
• The client code tagging implementation applies to all resources and therefore less logic/time to implement. The logic is also more generic
• Search by _tag filter can be used to for multiple OR values or AND values i.e. we need resources that have both tags or we need resources that have either or the tags

Sync from server

1. Perform binary sync
2. Perform Parameter sync
3. Perform patient sync by one of the proposed methods above
4. Perform other resources sync various _tag filters eg. team, location, organisation.

Examples:

• Search url to provide WFP-CODA Questionnaires : https://fhir.labs.smartregister.org/fhir/Questionnaire?_tag=https%3A%2F%2Fsmartregister.org%2FappId%7Cwfp-coda&_sort=_lastUpdated

How to sync the data based on the different sync strategies

Sync by Location

• Sync by Location means getting all the records that have a location tag that's equal to the Location Id for the logged-in user and all the child locations under it.
  • We can find the child Location Ids from the parentChildren property of the hierarchy returned by the Practitioner details endpoint (sample) we have the child location Ids saved.

       {
       "parentChildren": [
  	{
  		"identifier": "Location/109211",
  		"childIdentifiers": [
  			"Location/136256"
  		]
  	},
  	{
  		"identifier": "Location/136256",
  		"childIdentifiers": [
  			"Location/137151"
  		]
  	},
  	{
  		"identifier": "Location/137151",
  		"childIdentifiers": [
  			"Location/138395"
  		]
  	 }
       ]
      }

  • We interact through resources and fetch all the resources tagged to each location recursively. e.g if we had 2 locations then we would have 2 calls on the Patient resource. Each request for each location.

Sync by Team (Organization)

• Sync by Team (Organization) means getting all the records that have an organization tag equal to the Team (Organization) Id for the logged-in user. In addition to this, we would get all the CareTeam(s) assigned to this Team (Organization) and get all the resources tagged by these CareTeam(s) IDs.
  • E.g if I have 1 Organization with 2 CareTeams then I would have 3 calls to the server to sync Patients.
    • A patient call to get all the Patient resources tagged by the Team (Organization) if any.
    • 2 Calls to get patient resources tagged by either of the CareTeam(s)
• If the user is assigned to 2 Team (s) (Organization) the time it takes to sync increases.

Sync by CareTeam

• Sync by CareTeam means getting all the records that have a CareTeam tag equal to the CareTeam Id for the logged-in user.
  • E.G if a user is assigned 3 CareTeam(s) and wants to Query the Patient Resource then we will have at least 3 API queries. 1 for each CareTeam.

[dubdabasoduba]

@ekigamba My thinking here was we could get the Patient Resources and then download everything else tied to the patient. That way we only need to worry about syncing the Patient Resource using the 3 attributes.

We could however use the meta idea for resources that are not referenced to the patients.

[ekigamba]

This makes sense. The only challenge might be the number of requests required to achieve this for every sync. I assume that for every x-patient-related resources we need to make a single call which means if we have 1000 clients then we make 1000 calls for the initial sync and every subsequent sync operation. The alternative which is filtering resources by patient references requires a every call to have a filter that will hold 1000 patient IDs and in some cases the filter path needs to be tailored for that specific resource.

[pld]

agree, does FHIR/HAPI support on the server side creating a bundle that is the patient resource and anything tied to that patient?

[pld]

More notes on this, trying to find the intersection of flexible and minimal

on the pre-reqs:

• Why do all patients need to be "added to a group"?
  • ok I see why, because subject can only connect to 0 or 1 entity
• I want to clarify that the hierarchy is
• [[[CareTeam A, ...] -> Organization A], ... -> Location A], ...
  • Practically CareTeams are healthcare teams, Organizations are catchment areas (not only facilities), and Locations are regions, is that correct?
  • Wait, but Location can only point to a single Org so this won't work
• The final point in the pre-reqs seems incomplete, catchment areas (Organizations) will also need to store their specific locations, which may be a shape (area) not just a point

on sync by team:

• do we need a separate group, why can't the careteam be a group, is there a use case that can't accommodate?
  • ok I see why, because subject can only connect to 0 or 1 entity
• I think we should split out Sync by CareTeam (Healthcare Team) from Sync by Organization (Catchment Area)

on sync by location

• if a location can only point to a single managing org, I'm struggling to see how this would be different

I think I'm missing something, if a location can only point to a single org we can't use this in the way we had discussed yesterday