[New Feature] Add Related Entity Location Tag to newly created resources

[f-odhiambo]

Background & Context

As a health practitioner, I want to be able to distinguish patients based on the location they are located at.

As a data collector or service monitor, I want to be able to distinguish information related to a point of interest based on its connection to that point of interest.

Also see discussion item

• https://docs.google.com/document/d/1D7fXYo3zFMAO3j5Vh8FmpfSVeRfxfVjHAefDtw2KmSk/edit
• https://github.com/ona-health/sid-dto-fhir-resources/discussions/753

Proposed Solution

High level:

• Add a meta.tag called Related Entity Location to every resource generated on the app that is tied to a related entity that could be a Patient, a Group, or a Location (eg representing a service point or POI).
• The related entity is itself or is connected to a location at its time of creation.

Assigning a value to meta.tag: "Related Entity Location" can happen in 3 ways

1. Using a location ID submitted in a Questionnaire and stored in a QR (QuestionnaireResponse).
   • This will happen during entity creation, e.g. creation of a Patient, Group (e.g. representing a family), or Location (e.g. represent a service point)
   • When creating the entity the users selects a location in the registration questionnaire, this is saved in the QR
   • In extraction a StructureMap creates a Location resource, or references an existing Location
   • This location is stored in the meta.tag: "Related Entity Location" of the related entity (in this case the related entity is the entity itself).
2. When saving a resource connected to a related entity, set to the value in the related entity
   • This applies when the registration above has already happened and the data is generated through other operations, e.g the generation of CarePlans and Tasks via $apply or the extraction of Observations via StructureMaps.
   • We assume a subject or similar field links the newly saved resource to the related entity
   • Set [new resource].meta.tag: "Related Entity Location" = [related entity].meta.tag: "Related Entity Location"

Example meta tag:

{
  "system": "https://smartregister.org/related-entity-location-tag-id",
  "code": "1a8ae4f2-c94b-4366-ac31-f55ccf3168a2",
  "display": "Related Entity Location"
}

Patient resource with meta-tag:

{
  "resourceType": "Patient",
  "id": "21248",
  "meta": {
    "versionId": "1",
    "lastUpdated": "2023-06-20T12:43:56.633+00:00",
    "source": "#e58f8eb4117b05a8",
    "tag": [
      {
        "system" : "https://smartregister.org/care-team-tag-id",
        "code"   : "2309fc1e-9fbc-46f3-8a70-8dbd9d2448ed"      ,
        "display": "Practitioner CareTeam"
      },
      {
        "system" : "https://smartregister.org/app-version",
        "code"   : "0.2.2-bunda"                          ,
        "display": "Application Version"
      },
      {
        "system" : "https://smartregister.org/location-tag-id",
        "code"   : "Not defined"                              ,
        "display": "Practitioner Location"
      },
      {
        "system" : "https://smartregister.org/organisation-tag-id",
        "code"   : "1a8ae4f2-c94b-4366-ac31-f55ccf3168a2"         ,
        "display": "Practitioner Organization"
      },
      {
        "system" : "https://smartregister.org/practitioner-tag-id",
        "code"   : "6e744577-cf1c-4876-a122-2d0e9c5e0f23"         ,
        "display": "Practitioner"
      },
      {
        "system" : "https://smartregister.org/related-entity-location-tag-id",
        "code"   : "1a8ae4f2-c94b-4366-ac31-f55ccf3168a2"                    ,
        "display": "Related Entity Location"
      }
    ]
  },
  .....................
  .....................
  "generalPractitioner": [
    {"reference": "Practitioner/6e744577-cf1c-4876-a122-2d0e9c5e0f23"}
  ],
  "managingOrganization": {
    "reference": "Organization/1a8ae4f2-c94b-4366-ac31-f55ccf3168a2"
  }
}

[f-odhiambo]

TBD From where do we retrieve the Location ID - this needs to follow a configurable approach

1. From the Location selection profile view in the case of EUSM
2. Get Location selection from newly created Group/Patient in the case of SID

Some thoughts

For the case of SID maybe create a group and then save the location to the shared pref. For subsequent family member addition, the use the stored group location id in pref. To avoid issues we will not have location selection in the add member form.

Every time we switch to a new group update the location is in the shared preference. i.e. new Family selection

[pld]

I rewrote to abstract this a bit.

• This is not necessarily a patient location, so change it to a Related Entity Location
• Split the assignment into the 2 cases, first of saving an entity that knows it's own location and saving an entity connected to an entity that knows its own location, which @f-odhiambo suggested when we last spoke about this
• The second case is saving an entity that's related to that entity, where we take it's metatag and propagate it. It's not clear how well defined this will be, but it seems it should be well defined most of the time, or we can make it so, like by putting a hidden link to the entity with its location meta tag set in the Questionnaire storing data

[dubdabasoduba]

TBD From where do we retrieve the Location ID - this needs to follow a configurable approach

1. From the Location selection profile view in the case of EUSM
2. Get Location selection from newly created Group/Patient in the case of SID

Some thoughts

For the case of SID maybe create a group and then save the location to the shared pref. For subsequent family member addition, the use the stored group location id in pref. To avoid issues we will not have location selection in the add member form.

Every time we switch to a new group update the location is in the shared preference. i.e. new Family selection

@pld @f-odhiambo I think this is defined here. The idea is to also find the subject of the data being created and then find the Location linked to it based on the linkage defined here

We can decide to use the Questionnaire subject to find the Entity the data belongs to. This will however break for use on workflows that do not need a questionnaire to be filled.

[pld]

I update the issue to add more details

[ellykits]

@dubdabasoduba @f-odhiambo

Can you confirm the system used for this new resource tag.

  {
                "system": "https://smartregister.org/patient-location-tag-id",
                "code": "1a8ae4f2-c94b-4366-ac31-f55ccf3168a2",
                "display": "Related Entity Location"
            }

The strings for the other tags are hardcoded in the string.xml file for the app. So we need to get it right.

[dubdabasoduba]

@ellykits here you go

{
  "system": "https://smartregister.org/related-entity-location-tag-id",
  "code": "1a8ae4f2-c94b-4366-ac31-f55ccf3168a2",
  "display": "Related Entity Location"
}

[f-odhiambo]

Update needed for Resources created from the patient's profile. At the moment the Related Entity Location Tag is not cascaded when you start a workflow from the profile

CC @ellykits