Nuanced Record Matching Logic

[drobadey]

This is somewhat related to https://github.com/HUD-Data-Lab/Data.Exchange.and.Interoperability/issues/11 in the context of storing ID matches.

Summary The API specs as they stand now do not appear to allow for nuanced record matching logic for things like CE assessments. Without a more nuanced matching logic, a CE assessment (or any enrollment-related record) may not be connected to a relevant enrollment. The API specs should be updated in the context of assessments (as one example) to incorporate a more nuanced record matching logic. Below is a scenario to illustrate this concern.

Scenario

• A community has established Healthcare Provider A as a Coordinated Entry Access Point
• Healthcare Provider A uses an electronic healthcare record system (EHR)
• That specific EHR does not have the concept of a program/enrollment but does allow end users to create an assessment
• The community is seeking to integrate that EHR with HMIS so that CE assessments can be completed by Healthcare Provider A
• In order for an assessment to be included in the CE APR, that assessment must be connected to an enrollment that is connected to an applicable program (https://files.hudexchange.info/resources/documents/FY24-HMIS-Programming-Specifications-CE-APR.pdf)

Primary question Given that the EHR in this scenario doesn’t have the concept of a program/enrollment, what logic determines how that assessment from EHR connects to correct enrollment in HMIS?

Assumptions

• The logic should not be built into the EHR platform itself. Rationale:
  • It would need data from HMIS in order to process
  • It would be asking non-HMIS systems to update their codebase to accommodate HMIS needs
• The logic could potentially be hardcoded into HMIS platforms, but that may not be the best solution. Rationale:
  • The logic needs to be standardized across HMIS platforms
  • This logic needs to be dynamic/easily updateable as definitions and data elements are updated
  • This matching logic doesn’t appear to be applicable outside of the context of APIs/interoperability
• The logic for the nuanced connection of records should reside within the API specs. Rationale:
  • This will allow for standardization of logic across systems
  • Updates to this logic will be solely to endpoints rather than a system’s codebase
  • Data connection can happen within the API call rather than needing to store data on a database and then process that data to determine the connection

Concern The API specs as they exist currently appear to assume a 1:1 relationship of IDs between systems. At the higher level of the record hierarchy, pulling a list of IDs and then matching based on those IDs may be satisfactory (as proposed in Issue 1 - https://github.com/HUD-Data-Lab/Data.Exchange.and.Interoperability/issues/1). However, in the scenario described above, in order to identify the correct enrollment to connect an assessment to, the API would need to pull the EnrollmentID that would include it in the CE APR. This logic should include, but is not limited to, ensuring that:

• The assessment occurred within the enrollment date range
• The enrollment is connected to an applicable program (continuum project, CE participation status, etc.)
• There is a tiebreaker if there is more than one enrollment connected to an applicable program and the assessment date falls within the date range of every enrollment.

Note 1: this concern may not be as applicable for CE systems where Healthcare Provider A can be set up as their own agency/program but would be very applicable for communities that have all of their CE process go through one agency/program.

Note 2: The need for more nuanced matching logic may also be applicable to connecting:

• An enrollment to the correct program
• Services to the correct enrollment
• CE Events to the correct enrollment

Conclusion As the API specs are currently written, a CE assessment may not be connected to the enrollment that would ensure the inclusion of that assessment in the CE APR. As a result, the API specs should be updated in the context of assessments, and in several other places, to incorporate more nuanced matching logic.

[drobadey]

This will be reviewed with the future iteration of the HMIS API Reference that entails CE assessments.

A portion of this concern has already been resolved with "summary" endpoints.