getSingleBestRecord

The getSingleBestRecord method returns an individual Person record by filtering out the single best record associated with each cluster of records. The selection of the best record in a cluster of records that have been linked together is based on the configuration of the Singe Best Record module. The module is configured by adding a section to the mpi-config.xml file for the instance. The configuration section takes the form of a sequence of rules that specify which record should be selected. When processing a request for the single best record, the module evaluates the rules in sequence until it finds one that evaluates to true and returns the record that satisfied the rule.

Here is an example configuration of the Single Best Record module below. The "entity-name" attribute specifies which entity this configuration module applies to and is especially important when hosting multiple entities on a single instance of OpenEMPI. The "ruleset" section consists of a sequence of rules, each of which specifies the field to which the rule applies and the condition that is being evaluated. In the example below, there is one rule, indicating that the service should return the first record in the cluster that has a non-null value for the postal code field. The configuration section should be inserted after the matching algorithm configuration section. Also, you will need to add the definition of the new namespace at the top of the mpi-config.xml file, as shown in the example below.

<mpi-config
	xsi:schemaLocation="http://configuration.openempi.openhie.org/mpiconfig mpi-config.xsd
	http://configuration.openempi.openhie.org/file-loader file-loader.xsd
	http://configuration.openempi.openhie.org/basic-blocking-hp basic-blocking-hp.xsd
	http://configuration.openempi.openhie.org/exact-matching exact-matching.xsd
	http://configuration.openempi.openhie.org/single-best-record single-best-record.xsd"
	xmlns="http://configuration.openempi.openhie.org/mpiconfig"
	xmlns:bb="http://configuration.openempi.openhie.org/basic-blocking-hp"
	xmlns:em="http://configuration.openempi.openhie.org/exact-matching"
	xmlns:fl="http://configuration.openempi.openhie.org/file-loader"
	xmlns:mpi="http://configuration.openempi.openhie.org/mpiconfig"
	xmlns:pm="http://configuration.openempi.openhie.org/probabilistic-matching"
	xmlns:sbr="http://configuration.openempi.openhie.org/single-best-record"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
     ...
 
	<sbr:single-best-record entity-name="person">
		<sbr:implementation-name>singleBestRecord</sbr:implementation-name>
		<sbr:implementation-description>Rule-based Single Best Record Implementation</sbr:implementation-description>
		<sbr:ruleset>
			<sbr:rule>
				<sbr:field-name>postalCode</sbr:field-name>
				<sbr:condition>not-null</sbr:condition>
			</sbr:rule>
		</sbr:ruleset>
	</sbr:single-best-record>

The module supports four different conditions, listed in the table below.

Condition	Description
not-null	Returns the first record in the cluster for which the value of the field specified in the rule is not null.
null	Returns the first record in the cluster for which the value of the field specified in the rule is null.
maximum	Returns the record in the cluster that has the maximum value of all the records in the field in the cluster.
minimum	Returns the record in the cluster that has the minimum value of all the records in the field in the cluster.

Method

The method uses the GET HTML method.

Input

The input to the method is the unique id (personId field) for one of the records in the cluster of person records that have been linked together.

Output

The output is the single best record Person entry selected by the configuration specified, if found or a null value if no entry is known by the system with that unique id.

Example

In this scenario we have two records that have been linked together by the matching algorithm. The Single Best Record module has been configured using the section shown above. We use the findPersonsByAttributes method to return the sample records for the example.

http://localhost:8080/openempi-admin/openempi-ws-rest/person-query-resource/findPersonsByAttributes

Input:

{
  "givenName": "James",
  "familyName": "Dedicoat"
}

Output

{
    "person": [
        {
            "address1": "12 Sheaffe Street",
            "address2": "Herbert River",
            "city": "Houston",
            "dateCreated": "2018-03-08T13:00:00.249-05:00",
            "dateOfBirth": "1948-02-24T00:00:00-05:00",
            "familyName": "Dedicoat",
            "givenName": "James",
            "personId": "3727",
            "personIdentifiers": {
                "dateCreated": "2018-03-08T13:00:00.249-05:00",
                "identifier": "rec-3044-dup-0",
                "identifierDomain": {
                    "identifierDomainId": "14",
                    "identifierDomainName": "IHENA",
                    "namespaceIdentifier": "IHENA",
                    "universalIdentifier": "1.3.6.1.4.1.21367.2010.1.2.300",
                    "universalIdentifierTypeCode": "ISO"
                },
                "personIdentifierId": "3728"
            },
            "phoneNumber": "6534628928",
            "ssn": "868066233",
            "state": "MI"
        },
        {
            "address1": "12 Sheaffe Street",
            "address2": "Herbert River",
            "city": "Houston",
            "dateCreated": "2018-03-08T12:59:54.402-05:00",
            "dateOfBirth": "1948-02-24T00:00:00-05:00",
            "familyName": "Dedicoat",
            "gender": {
                "genderCd": "2",
                "genderCode": "M",
                "genderDescription": "Male",
                "genderName": "Male"
            },
            "givenName": "James",
            "personId": "1806",
            "personIdentifiers": {
                "dateCreated": "2018-03-08T12:59:54.402-05:00",
                "identifier": "rec-3044-org",
                "identifierDomain": {
                    "identifierDomainId": "14",
                    "identifierDomainName": "IHENA",
                    "namespaceIdentifier": "IHENA",
                    "universalIdentifier": "1.3.6.1.4.1.21367.2010.1.2.300",
                    "universalIdentifierTypeCode": "ISO"
                },
                "personIdentifierId": "1807"
            },
            "phoneNumber": "6534628928",
            "postalCode": "60618",
            "ssn": "868066233",
            "state": "MI"
        }
    ]
}

We now submit a getSingleBestRecord request using the personId of the first record. Note that the record specified has a null value for the postalCode field.

http://localhost:8080/openempi-admin/openempi-ws-rest/person-query-resource/getSingleBestRecord?personId=3727

The service returns the second record in the cluster since this is the record that satisfied the single best record rule of having a value for the postalCode field.

{
    "address1": "12 Sheaffe Street",
    "address2": "Herbert River",
    "city": "Houston",
    "dateCreated": "2018-03-08T12:59:54.402-05:00",
    "dateOfBirth": "1948-02-24T00:00:00-05:00",
    "familyName": "Dedicoat",
    "gender": {
        "genderCd": "2",
        "genderCode": "M",
        "genderDescription": "Male",
        "genderName": "Male"
    },
    "givenName": "James",
    "personId": "1806",
    "personIdentifiers": {
        "dateCreated": "2018-03-08T12:59:54.402-05:00",
        "identifier": "rec-3044-org",
        "identifierDomain": {
            "identifierDomainId": "14",
            "identifierDomainName": "IHENA",
            "namespaceIdentifier": "IHENA",
            "universalIdentifier": "1.3.6.1.4.1.21367.2010.1.2.300",
            "universalIdentifierTypeCode": "ISO"
        },
        "personIdentifierId": "1807"
    },
    "phoneNumber": "6534628928",
    "postalCode": "60618",
    "ssn": "868066233",
    "state": "MI"
}