Linking Locations to Other Resources for use on OpenSRP 2.0

[dubdabasoduba]

Linking Locations to Other Resources for use on OpenSRP 2.0

• OpenSRP 2.0 mobile application codenamed "fhircore" has a GeoWidget module integrated. This module serves the purpose of rendering FHIR Location resources containing valid coordinates or GeoJson objects.
  • The primary function is to visualize geographical information.
• Given the context, these Location resources often require association with other resources for data extraction. Two specific instances are highlighted:
  • Household Location:
    • Signifying the geographical point where a group of clients, constituting a family unit, resides.
  • Inventory Assignment:
    • Denoting the geographical location where certain products are assigned for utilization.
• This discussion focuses on delineating various methodologies to establish standard links between distinct resources representing disparate concepts within fhircore.
• The links defined below are using the

Link using the List resource

• The List resource has several properties facilitating the linkage of the location to various resources. The utilization of the following attributes is integral:
  • identifier: This attribute retains the identifier of the List resource.
  • status: It signifies the status of the link. If designated as current, the link is considered active; if marked as retired, the link is inactive.
  • title: This property holds the list title, which may be a composite of the Location and the name of the associated resource.
  • code: This attribute holds the code used to identify the Resource link List resources.
  • subject: It preserves the list subject, representing the location intended for linking with other resources.
  • entry: This property contains a reference to the other resource destined for linkage with the Location resource. The entry itself encompasses the subsequent attributes:
    • flag: It holds a code facilitating the easy identification of the linked resource.
    • date: This attribute retains the date when the link was initially created.
    • item: It stores the reference to the resource intended for linking with the Location resource.
• A sample instance of a linked List resource is provided below for reference.

{
  "resourceType": "List",
  "identifier": [
    {
      "use": "official",
      "value": "f39c5f68-ab0f-4ae5-a9e2-47b0beb73d8e"
    }
  ],
  "status": "cuurent",
  "title": "Kilimani - Maternity Bed",
  "code": {
    "coding": [
      {
        "system": "http://smartregister.org/",
        "code": "invetory_link",
        "display": "Location Inventory Reference"
      }
    ],
    "text": "Location Inventory Reference"
  },
  "subject": {
    "reference": "Location/fd394f54-3c75-4851-b5da-9c43709ea776"
  },
  "entry": [
    {
      "flag": {
        "coding": [
          {
            "system": "http://smartregister.org/",
            "code": "inventory",
            "display": "Inventory Reference"
          }
        ],
        "text": "Inventory Reference"
      },
      "date": "2024-02-01T00:00:00.00Z",
      "item": {
        "reference": "Group/fd394f54-3c75-4851-b5da-9c43709ea776"
      }
    }
  ]
}

Link using the Linkage resource

• The Linkage resource has several properties that can be used for linking the location with other resources. The process involves leveraging the following key attributes:
• identifier: This attribute serves as the repository for the List resource identifier.
• active: It functions as the indicator of link status. A value of true denotes an active link, while false signifies an inactive link.
• item: This attribute holds the reference intended for linkage with the Location resource and other resources interconnected with it. The item attribute has following properties:
  • type: This property stores a code to help with the identification of the Location resource. The assigned type is source.
  • resource: It retains the reference to the pertinent resources.
• A sample instance of a linked Linkage resource is provided below for illustrative purposes.

{
  "resourceType": "Linkage",
  "identifier": [
    {
      "use": "official",
      "value": "f39c5f68-ab0f-4ae5-a9e2-47b0beb73d8e"
    }
  ],
  "active": true,
  "item": [
    {
      "type": "source",
      "resource": {
        "reference": "Location/fd394f54-3c75-4851-b5da-9c43709ea776"
      }
    },
    {
      "resource": {
        "reference": "Group/fd394f54-3c75-4851-b5da-9c43709ea776"
      }
    }
  ]
}

Other suggestions that were not considered

Linking via extensions

• The proposed approach entails appending an extension to the other resources, establishing a reference to the Location resource.
• While theoretically viable, this solution was initially dismissed due to a limitation which is the non-searchable nature of extensions.
• Our App configuration functionality relies extensively on search capabilities, which, by default, operate seamlessly with searchable resource attributes.
• Despite this, a potential workaround involves updating the search functionality by:-
  1. incorporating custom search attributes through the software development kit (SDK)
  2. defining new search parameters via the SearchParameter resource in the API.
• This needs some R&D to make sure it works.

[pld]

Two high level questions:

1. Do we have cases where we linking > 1 locations to 1 entity?
2. Do we have cases where we want to enforce that a location can only link to a single entity?

But also, can you please give specific examples of what we would be linking? Let's walk through a couple of uses cases and see what that shows us about these options

[ageryck]

Based on the use cases given above;

1. Household Location linkage will have a 1-to-1 linkage relationship which should be enforced to the single-entry
2. Inventory may require both 1-to-1 or multiple depending on how it's being tracked, a commodity of the same code can be distributed to multiple locations or to just a single location, and a single location can hold 1 or many inventories.

[pld]

OK thanks @ageryck!

@dubdabasoduba do you have thoughts on the pros/cons of List vs Linkage, and a suggestion on what to use for the time being?

[dubdabasoduba]

@pld

Pros on the List

• Makes it easy to search because it directly references a location as a subject. This means we do not have to go through an array to find the location
• The ability to add codes that we can use to identify the linkage lists correctly
• Linkage is used to link 2 resources that mean the same thing. Based on this I would say we use the LIST resource

Cons on the List

• We already LISTs for other use cases.

Pros on the LInkage

• This is be a new resource that's not used for any other use case on OpenSRP
• It provides a way to identify the base resource i.e the Location but it does this using a type property

Cons on the Linkage

• Using the Linkage resource for this use case if semantically wrong

cc: @ageryck

[pld]

Cool, these make sense, lets go w/LIST