B Adding IHE Profile Support to User-defined MPI Object Model

When creating a new IHE Project in OHMPI 3.0, you have an option to use either the out-of-box MPI Project or use a user-defined MPI Project. For the out-of-box MPI Project, OHMPI provides default mapping between the out-of-box MPI Object Model and the IHE Patient Object Model. For user-defined MPI Project, it is your responsibility to provide a customized mapping between the user-defined MPI Object Model and the IHE Patient Object Model.

Creating IHE Project with User-defined MPI Project

This section describes how to add IHE Profile support to user-defined MPI Project.

From the NetBeans IDE, click File and then select New Project.

The New Project dialog box appears.
In the Projects section of the Choose Project panel, select IHE Project and click Next.

The New IHE Project dialog box appears.
In the Name and Location panel, perform the following:
1. In the Project Name field, enter a name for your project (for example, IHEProject1).
2. In the Project Location field, browse to the path where you want to create the IHE project.
  
  The Project Folder field populates with the path and name of your project.
3. From the Server drop-down list, select the application server.
4. From the Database drop-down list, select a database (for example, Oracle).
5. In the V2 Service Port field, enter the port number (for example, 4447).
6. Click Next.
  
  The Select MPI Project screen appears.
Select the Select User Defined MPI Project option and then click Browse to select a path of an existing MPI Project.
Click Next.

The Select Mapper Project screen appears.
Select Create Mapper Project.
Enter the project name in the Mapper Project Name field.
In the Mapper Project Location field, browse to the path where you want to create the Mapper project.
Click Finish.

When the IHE Project is created, a Java Mapper Project is also created with an empty implementation. The IHE Project is linked to the user-defined MPI Project and the Java Mapper Project, so building the IHE Project should also build the MPI Project and the Java Mapper Project automatically.

Note:

You must to run "Generate Master Index Files" on the user-defined MPI Project explicitly. In the case of MPI Project never been generated while creating the IHE Project, the Mapper Project will contain unresolved reference (mpi-client.jar) upon creation. That unresolved reference warning is fixed when the "Generate Master Index Files" action is invoked on the MPI Project.

Implementing Customized Mapper Project

Mapper Project Overview

The purpose of the Mapper Project is to provide two-way mapping between the user-defined MPI Object Model and OHMPI's internal IHE Patient Object Model.

Mapping from the IHE Patient Object Model to the MPI Patient Object Model is required by the following IHE transactions:

Patient Identity Feed
Patient Demographics Query (Request)

Mapping from the MPI Patient Object Model to the IHE Patient Object Model is required by the following IHE transactions:

Patient Demographics Query (Response)
PIX Update Notification

Java programming knowledge is required to implement the mapping.

For OHMPI's internal IHE Patient Object Model, see samples\ihe\javadoc\index.html under your OHMPI installation directory for the Javadoc. Package oracle.hsgbu.ohmpi.model contains the IHE Object Model that you must map from and to your MPI Object Model.

Also, see Javadoc for the oracle.hsgbu.ohmpi.services.IMapperService Interface and understand the three methods you must implement in your mapper implementation class.

Mapper Example

In this section, we use a simplified version of the Person Template Project as an example to illustrate the mapping process.

The following figure shows the Object Model of a simplified Person MPI Project.

Figure B-1 Object Model

Description of ''Figure B-1 Object Model''

The following table shows the field mapping that we choose to implement: (Please note that unformattedTelephoneNumber in the IHE Patient Object Model only gets populated from HL7v3 Patient Identity Feed. To support data coming from HL7 v2 Patient Identity Feed, you need to check the other fields under the IHE Model's Telecom object as well when doing the mapping. We skip that part here for simplicity.)

User-defined MPI Object Model	IHE Patient Object Model
FirstName	givenName
LastName	familyName
SSN	SSN
DOB	dateOfBirth
Gender	gender
Phone.PhoneType	Telecom.telecomUseCode
Phone.Phone	Telecom.unformattedTelephoneNumber
Phone.PhoneExt	Telecom.extension

The following is a sample implementation of the IMapperService interface based on the field mapping we identified above:

package com.example;

import com.sun.mdm.index.objects.exception.ObjectException;
import com.sun.mdm.index.objects.person.PersonObject;
import com.sun.mdm.index.objects.person.PhoneObject;
import java.util.Collection;
import java.util.logging.Logger;
import oracle.hsgbu.ohmpi.commons.PatientName;
import oracle.hsgbu.ohmpi.model.IHEPatientObject;
import oracle.hsgbu.ohmpi.model.IHETelecomObject;
import oracle.hsgbu.ohmpi.services.IMapperService;

/**
 * Customized mapper implementation to bridge the standard IHE Patient Object Model and customized MPI Object Model.
*/
public class MyMapperImpl implements IMapperService {

 private static final Logger logger = Logger.getLogger(MyMapperImpl.class.getName());

 public IHEPatientObject getIHEPatientObject(Object mpiPatientObject) throws Exception {
  IHEPatientObject ihePO = new IHEPatientObject();

  PersonObject mpiPO = (PersonObject) mpiPatientObject;

  ihePO.setGivenName(mpiPO.getFirstName());
  ihePO.setFamilyName(mpiPO.getLastName());
  ihePO.setGender(mpiPO.getGender());
  ihePO.setSSN(mpiPO.getSSN());
  ihePO.setDateOfBirth(mpiPO.getDOB());

  if (mpiPO.getPhone() != null) {
   for (PhoneObject mpiPhone : (Collection<PhoneObject>) mpiPO.getPhone()) {
    IHETelecomObject ihePhone = new IHETelecomObject();
    ihePhone.setExtension(mpiPhone.getPhoneExt());
    ihePhone.setTelecomUseCode(mpiPhone.getPhoneType());
    ihePhone.setUnformattedTelephoneNumber(mpiPhone.getPhone());
    ihePO.addTelecom(ihePhone);
   }
  }

  return ihePO;
}
public Object getMPIPatientObject(IHEPatientObject ihePO) throws Exception {
  PersonObject mpiPO = null;

  mpiPO = new PersonObject();
  mpiPO.setFirstName(ihePO.getGivenName());
  mpiPO.setLastName(ihePO.getFamilyName());
  mpiPO.setGender(ihePO.getGender());
  mpiPO.setSSN(ihePO.getSSN()); 
  mpiPO.setDOB(ihePO.getDateOfBirth());}

  if (ihePO.getTelecoms() != null) {
   for (IHETelecomObject ihePhone : ihePO.getTelecoms()) {
    PhoneObject mpiPhone = new PhoneObject();

    mpiPhone.setPhoneExt(ihePhone.getExtension());
    mpiPhone.setPhoneType(ihePhone.getTelecomUseCode());
    mpiPhone.setPhone(ihePhone.getUnformattedTelephoneNumber());

    mpiPO.addPhone(mpiPhone);
   }
  }

  return mpiPO;
}

// Convenience method to avoid a full-blown mapping from MPI PO to IHE PO
public PatientName getPatientName(Object mpiPatientObject) throws Exception {

  PersonObject po = (PersonObject) mpiPatientObject;
  return new PatientName(po.getLastName(), po.getFirstName(), null, null);

}
}

Value Mapping

The sample mapper implementation in Mapper Example only shows field mapping. However, if any code list is defined in the MPI Object Model, then the mapper implementation also needs to take care of value mapping. For example, if the user-defined MPI Object Model's Gender field has a code list of "1"/ "2"/ "0", where "1" represents Male, "2" represents Female and "0" represents Unknown, these values must be properly mapped to HL7 code list ("M"/ "F"/ "UN") for IHE's Patient Demographics Query, and vice versa for IHE's Patient Identity Feed.

MPI's Gender Codes	IHE HL7's Sex Codes	Comment
1	M	Male
2	F	Female
0	UN	Unknown

To support this value mapping, in the getIHEPatientObject() implementation, replace

ihePO.setGender(mpiPO.getGender());

by the following code snippet:

String mpiGender = mpiPO.getGender();
if ("1".equals(mpiGender)) {
  ihePO.setGender("M");
} else if ("2".equals(mpiGender)) {
  ihePO.setGender("F");
} else {
  ihePO.setGender("UN");
}

Also, in getMPIPatientObject() implementation, replace

mpiPO.setGender(ihePO.getGender());

by the following code snippet:

String iheGender = ihePO.getGender();
if ("M".equals(iheGender)) {
  mpiPO.setGender("1");
} else if ("F".equals(iheGender)) {
  mpiPO.setGender("2");
} else {
  mpiPO.setGender("0");
}

Required Fields

In the user-defined MPI Object Model, some fields might be defined as required fields. When a required MPI field does not have corresponding value in the IHE Patient Feed, your mapper implementation may choose to throw oracle.hsgbu.ohmpi.exceptions.ValidationException to reject the Patient Feed, or it may choose to provide some default value in getMPIPatientObject() implementation in order to successfully process the IHE Patient Identity Feed and persist the patient record into the MPI database.

Mapping Context

In some scenario, your mapper implementation might need to have a better understanding of the mapping context or need to get more information about the underlying MPI system. For this purpose, a new oracle.hsgbu.ohmpi.services.AbstractMapperImpl class is introduced to provide such support.

For example, the mapping from the IHE Patient Object to the MPI Object (getMPIPatientObject()) is used for both Patient Identity Feed and PDQ. (It is used in PDQ because a MPI template Patient Object instance needs to be constructed based on the search criteria specified in the PDQ request.). There might be a need to determine whether the current mapping is performed inside a Patient Identity Feed transaction or not. For example, if some field (say, gender) is required by the MPI Object Model but is missing in the Patient Identity Feed, the mapper implementation might choose to provide some default value (for example, Unknown). On the other hand, if the current transaction is PDQ, then no default value should be provided in the mapping, otherwise, it changes the search criteria.

To differentiate Patient Identity Feed and PDQ in the user-defined mapper implementation, instead of implementing the oracle.hsgbu.ohmpi.services.IMapperService interface, change your mapper implementation class to extend oracle.hsgbu.ohmpi.services.AbstractMapperImpl instead, then call the helper method isInPatientIdentityFeed() to determine whether the current transaction is a Patient Identity Feed or not.

Code System Support

The IHE Patient Object Model provides code system support. For example, IHEPatientObject provides the following 4 APIs to get/set patient's gender:

String getGender()
setGender(String gender)
IHECodeObject getGenderCode()
setGenderCode(IHECodeObject genderCode)

The first two APIs are provided for convenience. If code system is not important in your application, your mapper implementation can simply use the first two APIs to deal with gender values (for example, M, F). On the other hand, if the code system is important in your application, your mapper implementation can have complete code system access using the last two APIs. An IHECodeObject simply represents a code value under some code system, for example, "M" under code system "2.16.840.1.113883.5.1".

As a side note, for simplicity, codes are not scoped by namespaces in the out-of-box MPI Object Model. For example, gender is a simple attribute (instead of coded value with namespace) on the Patient Object, and Race is a simple Child Object with only one attribute (instead of coded value with namespace).

Configuring IHE Project

Edit the following properties in IHE Project's services.properties under "Configuration Files" before building the IHE Project.

# Application Name of the User-defined MPI Project
mpi/application/name=Person
# Primary Object Name in the Object Model of the User-defined MPI Project
mpi/primary_object/name=Person
# Primary Object's Fully-Qualified Class Name in the User-defined MPI Project 
mpi/primary_object/class_name=com.sun.mdm.index.objects.person.PersonObject
# Fully Qualified Class Name of the IHE-MPI Mapper Service Implementation
service/mapper/class_name=com.example.MyMapperImpl

Adjust the above property values accordingly based on your own MPI Project and Mapper Project's implementation.