Understanding the Structure and Usage of OmniElements

A practical example of an OmniLink is the Patient Subject referencing its Preferred Provider. In this case, the referenced Subject must be specified with the same SourceName and SourceInstanceId that it has when submitted on its own.

In the example below, it is assumed that the Provider had been loaded separately (additional OmniElements were omitted for brevity). In order to reference the same Provider from a Patient OID, the only requirement is to use the same SourceName and the SourceInstanceId used by the previously submitted Provider. If the SourceName and/or SourceInstanceId are referred to in a different manner than when it was originally submitted, it will result in a new incomplete Provider instance.

The recommended implementation is shown in the following example:

<!-- Pre-loaded Provider -->
<Provider>
	<SourceName>TestSource</SourceName>
	<SourceInstanceId>Provider:4567890</SourceInstanceId>
	<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Provider>
<Patient>
	<SourceName>TestSource</SourceName>
	<SourceInstanceId>Patient|12345678</SourceInstanceId>
	<PreferredProvider>
		<Provider>
			<SourceName>TestSource</SourceName>
			<SourceInstanceId>Provider: 4567890</SourceInstanceId>
			<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
		</Provider>
	</PreferredProvider>
	<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Patient>

The non-recommended implementation is shown in the following example:

<!-- Pre-loaded Provider -->
<Provider>
	<SourceName>TestSource</SourceName>
	<SourceInstanceId>Provider|4567890</SourceInstanceId>
	<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Provider>
<Patient>
	<SourceName>TestSource</SourceName>
	<SourceInstanceId>Patient|12345678</SourceInstanceId>
	<PreferredProvider>
		<Provider>
			<!-Same logical Provider as above, but a mismatched SourceName and
SourceInstanceId. This results in a new, sparsely populated instance record
being created for this Provider.
			-->
			<SourceName>TestSource2</SourceName>
			<SourceInstanceId>Patient|12345678|Provider|4567890</SourceInstanceId>
		</Provider>
	</PreferredProvider>
	<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Patient>

Key definitions in the ISO/IEC 11179 metadata registry standard provide important background for understanding how codified values are handled within Omni-Patient:

• data element concept. A concept that can be represented in the form of a data element, described independently of any particular representation.
• value domain. Set of permissible data values for a data element or data element concept.
• permissible values. Expression of a value meaning allowed in a specific value domain.
• enumerated value domain. Value domain that is specified by a list of all its permissible data values, and their value meanings.

A concrete example, such as the handling of a Country Code, might better explain how to apply each of these technical metadata terms:

• data element concept: Country Code
• value domain: ISO 3166-1 - Country Codes.
• permissible values for Country Code as an enumerated value domain:
  • AD, Andorra
  • AE, United Arab Emirates
  • AF, Afghanistan
  • ….
  • ZW, Zimbabwe

  In this particular case, the Country Code is classified as a data element concept because its enumerated value domain may be used for multiple data element representations in the system (i.e. Person.Citizenship, PersonAddress.Country, OrganizationAddress.Country).

  Omni-Patient uses the ideas expressed above to define the following equivalent terms:

  • code set. A specific representation of an enumerated value domain (for example, CountryCodes), containing a list of permissible values.
  • code. Permissible value in the enumerated value domain for the code set.
  • description. The text-based value meaning for a code value in the enumerated value domain for the code set.

With these background definitions in mind, it is possible to see how they are applied to the structure of a SourceCodeType.

Any data element defined as a SourceCodeType will have the following common structure, as defined in the Interface Document Specification.

<SourceCode  sourceName="owner" sourceCodeSet="codeSetName" sourceCode="Code">Description</SourceCode>

The structural components of a SourceCodeType are listed and described in the following table.

CASE_SENSITIVE LOOKUP

A practical example of a SourceCodeType may look like the following:

<Gender sourceName="TestSource" sourceCodeSet="genderCodeSet" sourceCode="f">Female</Gender>

In the overwhelming majority of cases, the SourceName attribute of the SourceCodeType will be the same value as the required SourceName data element of its parent OmniObject. For the sake of brevity on the large volume of data elements designated as a SourceCodeType, the following alternate representation may be more commonly utilized.

<Gender sourceCodeSet="genderCodeSet" sourceCode="f">Female</Gender>

This technique assumes that the sourceName is obtained from the parent OmniObject of the SourceCodeType, as depicted in the following example.

<Person>
  <SourceName>TestSource</SourceName>
  <SourceInstanceId>Patient|12345678|Person|PersonKey</SourceInstanceId>
  <!--The SourceName attribute of the Gender below is assumed to be
   equivalent to the SourceName data element of the parent Person
   OmniObject.-->
  <Gender sourceCodeSet="genderCodeSet" sourceCode="1">Female</Gender>
  <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Person>

There are often scenarios where Omni-Patient expects a SourceCode for a particular data element, but the SourceSystem may not have a codified value. A common example of this may be the Medical Record Number (MRN), which can be represented in some source systems as a column on a database, but is expected as an IdentifierType in Omni-Patient.

In cases such as these, it is acceptable to map directly to another specified SourceCodeSet, such as those supplied by Omni-Patient:

<PersonIdentifier>
  <SourceName>TestSource</SourceName>
  <SourceInstanceId> Patient|12345678|Person|PersonKey|PersonIdentifier|MR
  </SourceInstanceId>
  <!-The SourceName attribute of the IdentifierType below can explicitly
  reference the IdentifierType SourceCodeSet (0203) provided by
  OmniPatient.-->
  <IdentifierType sourceName="OMNI" sourceCodeSet="0203" sourceCode="MR">
  </IdentifierType>
  <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</PersonIdentifier>

A SourceCodeSet represents a named, enumerated value domain in Omni-Patient. CodeSetNames must be unique by SourceName. All SourceCodeSets implement the following common structure.

<SourceCodeSet>
   <SourceName>TestSource</SourceName>
   <CodeSetName>UniqueCodeSetName</CodeSetName>
   <Description>A further description of the Code Set Name</Description>
   <SourceCodes/>
   <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01
    10:12:32</SourceModifiedDate>
</SourceCodeSet>

The SourceCodes OmniCollection in the SourceCodeSet IDS provides the mechanism for communicating an enumerated value domain, as well as its mapping to another standardized SourceCodeSet. The SourceCodes OmniCollection assumes a list of SourceCode OmniObjects, which implement the following common structure.

<SourceCode>
  <SourceName>TestSource</SourceName>
  <SourceCode> EnumeratedValue </SourceCode>
  <Description> The text-based value meaning of the code value specified by
  the SourceCode.</Description>
  <ParentCode>
    <SourceCode>
      <SourceName>TestSource</SourceName>
      <CodeSetName> TestSourceCodeSetName</CodeSetName>
      <SourceCode>EnumeratedValue</SourceCode>
    </SourceCode>
  </ParentCode>
  <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01
   10:12:32</SourceModifiedDate>
</SourceCode>

Prior to executing common Cleanse, Match, and Merge rules for mastering, it is essential that code values from disparate systems be unified into a common codeset. However, from a data lineage perspective, it is also imperative to understand the value as it was sent by the source system. The process of translating a SourceCode into a unified standard is called Code Standardization. For more information on the Code Standardization process, please see [Document Reference]. The following is a practical example of two SourceCodeSets, each from different SourceNames, which are unified on the 0001 Administrative Sex codeset supplied by Omni-Patient.

The following is a Code Standardization example.

<SourceCodeSet>
  <SourceName>CPSI</SourceName>
  <CodeSetName>GenderCodeSet-CPSI</CodeSetName>
  <Description>Gender Code representation from CPSI</Description>
  <SourceCodes>
    <SourceCode>
      <SourceName>CPSI</SourceName>
      <SourceCode> 1</SourceCode>
      <Description>Female</Description>
      <ParentCode>
        <SourceCode>
           <SourceName>OMNI</SourceName>
           <CodeSetName> 0001</CodeSetName>
           <SourceCode>f</SourceCode>
        </SourceCode>
      </ParentCode>
      <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
      10:12:32</SourceModifiedDate>
        </SourceCode>
        <SourceCode>
           <SourceName>CPSI</SourceName>
           <SourceCode> 2</SourceCode>
           <Description>Male</Description>
           <ParentCode>
             <SourceCode>
               <SourceName>OMNI</SourceName>
               <CodeSetName> 0001</CodeSetName>
               <SourceCode>m</SourceCode>
             </SourceCode>
           </ParentCode>
           <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
            10:12:32</SourceModifiedDate>
            </SourceCode>
 </SourceCodes>
 <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
  10:12:32</SourceModifiedDate>
</SourceCodeSet>

<SourceCodeSet>
  <SourceName>Cerner</SourceName>
  <CodeSetName>GenderCodeSet-Cerner</CodeSetName>
  <Description>Gender Code representation from Cerner</Description>
  <SourceCodes>
    <SourceCode>
       <SourceName>Cerner</SourceName>
       <SourceCode> female</SourceCode>
       <Description>Female</Description>
       <ParentCode>
         <SourceCode>
           <SourceName>OMNI</SourceName>
           <CodeSetName> 0001</CodeSetName>
           <SourceCode>f</SourceCode>
         </SourceCode>
       </ParentCode>
        <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
        10:12:32</SourceModifiedDate>
       </SourceCode>
       <SourceCode>
          <SourceName>Cerner</SourceName>
          <SourceCode> male</SourceCode>
          <Description>Male</Description>
          <ParentCode>
             <SourceCode>
              <SourceName>OMNI</SourceName>
              <CodeSetName> 0001</CodeSetName>
              <SourceCode>m</SourceCode>
            </SourceCode>
          </ParentCode>
          <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
           10:12:32</SourceModifiedDate>
           </SourceCode>
  </SourceCodes>
  <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
  10:12:32</SourceModifiedDate>
</SourceCodeSet>

A summarization of the result of loading these two SourceCodeSets is described in the following table.

During the Code Standardization phase of Omni-Patient processing, the values supplied by CPSI and Cerner will be translated into the parent equivalent. The SourceCode will be associated with the instance record, and the Parent SourceCode will be populated on the golden record after Cleansing, Matching, and Merging rules have been applied.

In this case, both a value of '1' sent from CPSI, and a value of 'female' sent by Cerner, will result in a value of 'F' on the Golden Record to represent 'Female'.

At startup, Omni-Patient loads a series of SourceCodeSets that are maintained and shipped with the product. These codesets use the reserved word 'OMNI' in the SourceName. These SourceCodeSets are primarily used as ParentCodes that unify disparate values from various source systems. Given the unique nature of each customer's business, there may be a need to extend one or more of these enumerated value domains by submitting an update to the appropriate SourceCodeSet with additional customer-specific values.

Important: Default Cleanse, Match, and Merge rules that ship with the product are based on values in the SourceCodeSets provided by Omni. These rules must be customized in the customer environment should they need to take into account extended values in an Omni SourceCodeSet.

The following is a sample Omni SourceCodeSet.

<SourceCodeSet>
   <SourceName>OMNI</SourceName>
   <CodeSetName>0001</CodeSetName>
   <Description>AdministrativeSex</Description>
   <SourceCodes>
     <SourceCode>
       <SourceCode> A</SourceCode>
       <Description>Ambiguous</Description>
     </SourceCode>
    <SourceCode>
       <SourceCode> F</SourceCode>
       <Description>Female</Description>
    </SourceCode>
    <SourceCode>
       <SourceCode> M</SourceCode>
       <Description>Male</Description>
    </SourceCode>
  </SourceCodes>
</SourceCodeSet>

The following is a custom Omni SourceCodeSet extension.

<SourceCodeSet>
   <SourceName>OMNI</SourceName>
   <CodeSetName>0001</CodeSetName>
   <SourceCodes>
   <SourceCode>
      		<!-Customer-specific extension of the Enumerated value domain. -->
      <SourceCode> CustomerCode</SourceCode>
      <Description>Customer Code Description</Description>
   </SourceCode>
  </SourceCodes>
</SourceCodeSet>

A parent SourceCodeSet is one that is referred to by the ParentCode of another SourceCodeSet. All SourceCodeSets should be processed in the following order:

1. SourceCodeSets provided by Omni.
2. Customer extensions of the SourceCodeSets provided by Omni.
3. All other parent SourceCodeSets.
4. All other customer-specific SourceCodeSets.

All parent SourceCodeSets must be loaded before they are referred to in an OmniLink. The SourceCodeSets provided by Omni are always loaded first during startup. It is essential that any extensions to the SourceCodeSets provided by Omni-Patient be run subsequent to the initial load of these SourceCodeSets. This ensures that the values supplied by Omni-Patient will never overwrite the custom extensions created by the customer.