Omni-Patient™ Server User’s Guide > Anatomy of Omni Interface Documents > Understanding the Structure and Usage of OmniObjects

Understanding the Structure and Usage of OmniObjects

Topics:

SourceName
SourceInstanceId Selection
Extended Attributes

As depicted above, OmniObjects are the primary building blocks for any IDS. They contain child OmniElements, OmniGroups, and OmniCollections to further describe the OmniObject and its relationship to other OmniObjects. Every IDS is comprised of at least one OmniObject, known as the Subject of the IDS.

All OmniObjects have a number of common OmniElements and OmniCollections, as depicted in the following example:

<OmniObject version="Object Version Number">
   <SourceName>TestSource</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
   <SourceInstanceIdName></SourceInstanceIdName>
   <ExtendedAttributes/>
   <SourceCreatedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
    10:12:32</SourceCreatedDate>
   <SourceCreatedBy>SourceCreatedBy</SourceCreatedBy>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-
    01</SourceModifiedDate>
   <SourceModifiedBy>SourceModifiedBy</SourceModifiedBy>
</OmniObject>

The following table lists and describes the supported elements that can be configured within OmniObjects.

Element	Required?	Description
Version	Recommended	This value is only used when referring to a Subject, as defined above. It assists with backward compatibility and is designed to help Omni-Patient understand which version of a given IDS is being processed. By default, the assumption is that the Version is the latest Version installed at the customer site.
SourceName	Required	Defines the source system from which the OmniObject originated. It is used in conjunction with the SourceInstanceId to uniquely identify the OmniObject.
SourceInstanceId	Required	A repeatable unique identifier which can be constructed from the available data in the originating system. It is used in conjunction with the SourceName to uniquely identify the OmniObject.
SourceInstanceIdName	Optional	This element can be used to give an indication of where the data came from in the source system to provide traceability.
SourceCreatedDate	Optional	DateTime that the record was created in the originating system.
SourceCreatedBy	Optional	Description of the entity that created the record in the source system.
SourceModifiedDate	Recommended	DateTime that the record was modified in the originating system.
SourceModifiedBy	Optional	Description of the entity that modified the record in the source system.
ExtendedAttributes	Optional	List of custom extensions to an OmniObject.

Interface Document Specifications are constructed to support insert or update operations, in whole or in part, for any OmniObject contained within a given OID. Therefore, the minimum data required for processing an OmniObject is its unique identifiers, SourceName and SourceInstanceId.

Although not required, it is strongly recommended to include the SourceModifiedDate with each OmniObject. The reason is that during initial load, history records for each instance may be loaded within minutes of one another. If the user would like to ask an "as of" query to see what the data looked like for an instance record at a certain point in time, the result would be severely constricted if basing off of the OmniModifiedDate, or the date on which the record was modified in Omni-Patient. In order to understand what the instance record for a given OmniObject may have looked like on a certain date in the Source system, the user should create "as of" queries using the SourceModifiedDate.

The minimum required implementation for an OmniObject is shown in the following example:

<OmniObject>
   <SourceName>TestSource</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
</OmniObject>

The minimum recommended implementation for an OmniObject is shown in the following example:

<OmniObject>
   <SourceName>TestSource</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
   <!-Facilitates "as of" queries against instance data. -->
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-
    01</SourceModifiedDate>
</OmniObject>

SourceName

The SourceName is used to define the source system from which the OmniObject originated. Therefore, it is not recommended to embed additional information, such as the transport method, in the SourceName.

Regardless of transport method, all records submitted from a single originating system shall have the same SourceName and SourceInstanceId. If they do not, an additional duplicate instance record is created and the history of the instance record is adversely impacted.

The recommended implementation for SourceName is shown in the following examples:

Initial Load

<OmniObject>
   <SourceName>TestSource</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</OmniObject>

Update

<OmniObject>
   <SourceName>TestSource</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-02</SourceModifiedDate>
</OmniObject>

The non-recommended implementation for SourceName is shown in the following examples:

Initial Load

<OmniObject>
   <SourceName>TestSource</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</OmniObject>

Update

<OmniObject>
   <!-SourceName is different than Initial Load. This will result in
    another physical instance record. -->
   <SourceName>TestSource-HL7</SourceName>
   <SourceInstanceId>UniqueKey</SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-02</SourceModifiedDate>
</OmniObject>

SourceInstanceId Selection

Topics:

Subject
One-to-One OmniObject Relationship

Once a common SourceName is determined for both the initial load and on-going updates, it is essential that a repeatable SourceInstanceId be selected. It must not contain transient information, such as the message ID from an HL7 MSH segment, or a specific database row ID, which may change over time. This will potentially result in a significant number of additional unintended instance records.

The following sections will discuss guidelines for SourceInstanceId selection for two types of OmniObjects:

Subject
One-to-One OmniObject relationship

For more information on SourceInstanceId selection within a One-to Many OmniObject relationship, see the OmniCollection section.

For more information on SourceInstanceId selection for a One-to-One reference to another Subject, see the OmniLink section.

Subject

The SourceInstanceId for a subject should primarily consist of a commonly understood business key, such as a Medical Record Number (MRN) for the Patient Subject or National Provider Identifier (NPI) for the Provider Subject.

It is recommended that the SourceInstanceId for a Subject follow the pattern:

Subject<Separator>BusinessKey

While it is technically not a requirement to specify the Subject and Separator so long as the BusinessKey is provided, it is recommended that it be included for readability and debugging purposes.

The recommended implementation for SourceInstanceId is shown in the following example:

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

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

<Patient>
   <SourceName>TestSource</SourceName>
   <!-The Message ID will change every time the Patient is sent via HL7. 
    This will result in a new instance record every time the Patient is 
    submitted.  History of change to the Patient will be improperly
    recorded.-->
   <SourceInstanceId>Patient|<MSH.MSG_ID></SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Patient>
<Provider>
   <!-If the DB is moved or reloaded, the DB.ROW_ID may no longer be valid.-
->
   <SourceName>TestSource</SourceName>
   <SourceInstanceId> <DB.ROW_ID></SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Provider>

One-to-One OmniObject Relationship

There are occasions where an IDS calls for a one-to-one relationship with another OmniObject that is not a subject which can be fed separately. In these cases, the OmniObject solely exists within the context of its parent.

An example of this is a Person OmniObject contained within a Patient Subject. Person may not be fed directly into Omni-Patient, but it is an OmniObject that appears within several Subjects. Since SourceInstanceIds are stored uniquely by OmniObject, it is recommended that the Person OmniObject use the same SourceInstanceId as its parent object (in this case Patient), for ease of traceability and debugging.

For this scenario, the SourceInstanceId should follow the pattern:

ParentObject.SourceInstanceId<Separator> Object<Separator>ObjectKey

The recommended implementation for SourceInstanceId is shown in the following example:

<Patient>
  <SourceName>TestSource</SourceName>
  <SourceInstanceId>Patient|12345678</SourceInstanceId>
  <Person>
     <Person>
     <!-Same SourceInstanceId as parent helps assist with traceability. 
      When viewing the Person table, it is possible to understand what 
      object the Person is related to. -->
   <SourceName>TestSource</SourceName>
   <SourceInstanceId> Patient|12345678|Person|PersonKey</SourceInstanceId>
   <SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
     </Person>
  </Person>
     <SourceModifiedDate format="yyyy-MM-dd">2013-01-
01</SourceModifiedDate>
</Patient>

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

<Patient>
	<SourceName>TestSource</SourceName>
	<SourceInstanceId>Patient|12345678</SourceInstanceId>
	<Person>
		<Person>
			<!-When viewing the Person table, traceability is difficult. -->
			<SourceName>TestSource</SourceName>
			<SourceInstanceId> Person|PersonKey></SourceInstanceId>
			<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
		</Person>
	</Person>
	<SourceModifiedDate format="yyyy-MM-dd">2013-01-01</SourceModifiedDate>
</Patient>

Extended Attributes

There are often scenarios where important customer data is not reflected in the IDS because it may not have as much relevance to the broader customer-base. To address these customer-specific extensions of Omni-Patient, capability has been provided for all OmniObjects to have an ExtendedAttributes OmniCollection.

The data elements of an ExtendedAttribute are shown in the following example:

<OmniObject>
  <SourceName>TestSource</SourceName>
  <SourceInstanceId>UniqueKey</SourceInstanceId>
  <ExtendedAttributes>
    <ExtendedAttribute>
       <SourceName>TestSource</SourceName>
       <SourceInstanceId>UniqueKey:ExtendedAttribute:XyzDate
       </SourceInstanceId>
       <Name>XyzDate</Name>
       <Type>Date</Type>
       <Format>yyyy-MM-dd</Format>
       <Value>2000-01-01</Value>	
       <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
        10:12:32</SourceModifiedDate>
    </ExtendedAttribute>
  </ExtendedAttributes>
  <SourceModifiedDate format="yyyy-MM-dd hh:mm:ss">2000-01-01 
   10:12:32</SourceModifiedDate>
</OmniObject>

The following table lists and describes the supported data elements of an ExtendedAttribute.

Element	Required?	Description
Name	Required	Defines the name of the Extended Attribute. It should be thought of as the equivalent of a DataElement name.
Type	Required	The data type of the named Extended Attribute.
Format	Optional	Allows the integrator to provide further specifics on how the Value is represented. A common use of this attribute would be in providing the Format when the Type="Date".
Value	Required	The value of the named Extended Attribute.

Use of these attributes should be judicious. A good rule of thumb for determining whether to add an ExtendedAttribute is if the data element falls into one of the following scenarios:

There is a desire to Cleanse and/or Match and Merge the data element.
It is desirable to maintain the history of that element with respect to other data that is being submitted for that OmniObject.

If the data element is being used strictly for Business Intelligence (BI) purposes (not used in Cleanse, Match, or Merge processes), another technique may be considered. The data element can be incorporated directly into a Reporting Data Mart (RDM) that is comprised of Omni-Patient and non-Omni-Patient source data, effectively bypassing the Omni-Patient repository.