Client Merge and Unmerge in HSLynk - servinglynk/hslynk-open-source-docs GitHub Wiki

Client master person ID merge/unmerge in HSLynk

HSLynk uses OpenEMPI's (v2.2.9 free version) master patent index algorithm to determine a global client id to uniquely identify client matches. This matching algorithm is robust and works according to its design specification. However, there may be anomalies in contributing source system personal identifier data, which could cause the dedupe client id (aka "global client ID" or "master person ID") to be incorrect, and hence, there's often a need for case managers and system administrators to unmerge and then possibly remerge those automatically merged clients. We offer two ways to merge and unmerge in Sections 1 and 2 below. Both ways work the same under the hood:

• using the HSLynk Admin App's web interface, or
• using the APIs directly from your own app.

Client IDs versus Client Dedupe IDs

In HSLynk, every identified client in the Global Human Services, HMIS, Coordinated Entry, Custom Surveys, Assessments, Linked Data, etc. has a corresponding record in the HSLynk Base Schema. These Base Schema ClientIDs are what are grouped under a single Client Dedupe ID and later possibly ungrouped from that Client Dedupe ID, when you perform Merge/Unmerge operations.

Let's talk about how merge and unmerge works, conceptually.

Client Merge

We currently use the following attributes to determine a client's dedupe ID, and it is highly possible that when creating a client, some essential client information may have been missed or inputted incorrectly. This may then result in an incorrect dedupe client id. We plan to offer identifier mix and weighting tunability per project group, soon.

1. First Name
2. Last Name
3. DOB
4. SSN

For example: Let's assume it's really the case that the two clients above were really the same person. So, they were incorrectly assigned, at first, two different dedupe client IDs. After calling the Merge API, we receive back correctly matching dedupe client IDs.

Client Unmerge

Clients often need to be unmerged, when we identify that two actually different clients have erroneously been assigned the same dedupe client ID, when they should have been assigned their own unique dedupe client ID.

For example: Let's assume that the two clients above were really different. So, after calling the Unmerge API, we correctly obtain the result of different dedupe client IDs for each client.

Technical perspective

Client merge/unmerge is a two step process for either action:

Step 1) Call the merge/unmerge web endpoint (with the Admin App user interface, or directly with the API, details on those below) and you'll get an expected dedupe client ID (dedupClientId). Based on this information, you or your algorithm must decide what to do (keep the dedupe client ID, or change it from the expected dedupe client ID).

Step 2) Make a call to the POST /events API to actually make the merge/unmerge happen, if you decide to change it.

The events endpoint uses the publish/subscribe (aka "Pub/Sub") HSLynk microservice to actually update the dedupe client ID for a client across all the required subsystems and HUD HMIS schema years. That way, all those exterior places can "listen/subscribe" to/for client ID changes, and receive "notifications/publications" of the change events.

Section 1: Merge/Unmerge via the HSLynk APIs

The documentation for step 1 is below.

• https://api.hslynk.com/?urls.primaryName=Global%20Api#/default/POST_clients-clientId-dedup-merge
• https://api.hslynk.com/?urls.primaryName=Global%20Api#/default/POST_clients-clientId-dedup-unmerge

The documentation for step 2 is below.

• https://api.hslynk.com/?urls.primaryName=Global%20Api#/default/POST_events

Section 2: Merge/Unmerge via the HSLynk Admin App

You can also perform merge/unmerge via the HSLynk Admin web app user interface.

To use it:

Log in to the HSLynk Admin App. https://admin.hslynk.com/hmis-admin/#/login

UnMerge Client:

1. Upon successful login, you will see a Merge Client and Unmerge Client option in the left menu for performing unmerge. Below is the screenshot to unmerge a client.

2) The actual unmerging happens only after the below screenshot.

Merge Client:

1. Upon successful login, you will see a Merge Client and Merge Client option in the left menu for performing merge. Below is the screenshot to merge a client.
2. The actual merging happens only after the below screenshot.