Create an MPI Adapter

Overview

CONNECT comes with an out-of-the-box light weight reference MPI. In reality, organizations either already have their own MPI or will desire to utilize a more robust implementation. This guide will give an overview on how to integrate your MPI with CONNECT.

The MPI adapter's main purpose for CONNECT is to support patient discovery with remote organizations. The gateway queries the MPI with the patient demographics from the remote organization. If a result is returned from the MPI, the gateway will store a "correlation" between the local and remote patient identifiers to be used for future workflows.

The MPI is used both during a patient discovery request from a remote organization and on a patient discovery initiated by the local gateway. The logic for responding to a patient discovery request is sketched below (I've simplified the diagram to focus on the MPI's role by excluding items such as policy, audit, and connection management).

FindCandidates

The MPI is responsible for implementing the FindCandidates method, returning the local demographics of a patient that meets the query parameters with a high degree of certainty.

The request message is a PRPA_IN201305, more easily referred to as a 201305. The 201305 contains the query, including the demographics of the patient being retrieved.

The implementation of executing this query will depend on the MPI being used and the business rules of the implementing organization. In general, the implementation will include:

• Create a webservice that implements the FindCandidates
• Accept the 201305 and transform to MPI request
• Retrieve the patient from the MPI
• Transform the result to a 201306

Create a webservice that implements the FindCandidates method
The mechanics for creating a webservice will vary depending on the toolstack that you use. In general, you will be driving the webservice from AdapterComponentSecuredMpi.wsdl, method FindCandidates. Keep in mind that this is a "secured" webservice which includes 2-way SSL, a SAML token, and digital signature described in the WSDL.

Accept the 201305
The webservice receives a 201305 which contains the query. At this point, you will generally convert this into something that can be used to query your MPI (HL7v2, custom web service request, SQL, etc).

A snippet of the 201305 portion of the message is shown below and a more complete sample can be found (here). Although the message below only contains a few demographic elements, this message supports many more demographic elements as intended by the HL7 spec.

<queryByParameter>
	<queryId extension="-abd3453dcd24wkkks545" root="1.1"/>
	<statusCode code="new"/>
	<responseModalityCode code="R"/>
	<responsePriorityCode code="I"/>
	<parameterList>
		<livingSubjectName>
			<value>
				<family partType="FAM">YOUNGER</family>
				<given partType="GIV">GALLOW</given>
			</value>
			<semanticsText representation="TXT"/>
		</livingSubjectName>
	</parameterList>
</queryByParameter>

Reusable java extraction routines to pull the demographic elements out of the message can be found here.

When constructing the resulting 201306 (sample 201306), there are a few pointers:

• The main element for including the resulting patient is the "patient" node (if no patient were found, this element would be absent from the resulting message).
• The patientPerson should represent the patient in the local mpi. That is, include the demographics from "your" organization, not the demographics sent in the query.

• Be sure to populate the qualified patient identifier to represent the patient. The extension represents the local patient identifier and the root represents the assigning authority of this MPI / organization.

  <id extension="D123401" root="1.1"/>

FAQ

Q: Is this the same as a patient search?
A: No. A patient search returns patient that might be a result. The find candidates method is intended to return the patient that is deemed to be the same patient. Depending on your implementation/rules, this could be an exact match or a match with a high matching threshold.

Q: What if no patients are found?
A: If no patients are found, leave the "patient" node blank.

Q: What is multiple patients are found?
A: The MPI can either return no patients or return all patients. In the case of the gateway querying for patient discovery, the gateway will interpret this as an ambiguous match and not create any correlations.

Q: What is the matching algorithm used by the MPI?
A: That is up to you! The light weight reference implementation uses an overly simple exact name match. The MirthMatch and Mural ESC implementations uses a more sophisticated probabilistic matching algorithm. If you are integrating your own MPI, the matching algorithm is what fits the bill for your business rules.

Q: What demographic traits should be used by the MPI?
A: Again, up to you. You have at your disposal anything that is provided by the HL7v3 specification. In an NHIN implementation, the NwHIN specification for Patient Discovery provides guidance on required fields.

Q: Can I use the unsecure interface?
A: At the moment, CONNECT does not utilize the unsecure version of the MPI adapter. This can be solved by implementing a proxy to call to it and configuring Spring to use this proxy. I would expect this to be fixed in 3.1 or 3.2 during refactoring of "core", with a focus on the proxies.