Omni-Gen™ Integration Services User's Guide > Installing, Configuring, and Using the Relational On-Ramp > Integration With XML (Omni Interface Document)

Integration With XML (Omni Interface Document)

Topics:

OID Element Types
Instance Child
Link to Another Subject
Variable Link to Another Subject
Code
Boilerplate Fields/Elements
OID Policies
Batch Interface
Immediate Interface
Comparing OnRamp and XML Interfaces
Migration Consideration for OID Users in Omni-Gen Version 2.x

All subjects of a deployed model in an Omni-Gen system are described by an Omni Interface Document (OID). This is a document in XML format by which records may be added, modified, or removed from the system. From the Deployments area in the Omni Console, you can download the schema of a particular OID for each subject along with a sample instance document.

The OID represents an instance of the subject as a full hierarchy (the root object and all descendants).

OID Element Types

Each business attribute in an OID may be represented by various character, numeric, and data types as specified by the schema. There are also several Omni-defined constructs that control parent/child relationships, links to other subjects, and codes and groups.

Instance Child

One or multiple instances of a child collection can be included in an OID.

Example:

<Client>    // subject name

      <OtherPhoneNumbers>    // enclosing element of child collection – list in IDS and mapping document      

      <PatientPhoneNumber version="3.0.0">    // subcollection name
        <SourceName>System_A</SourceName>    // subcollection source name
        <SourceInstanceId>1</SourceInstanceId>    // subcollection identifier
        <Type sourceName="OMNI" codeSet="0185">H</Type>  
        <StartDate format="yyyy-MM-dd">2018-01-15</StartDate>  
        <EndDate format="yyyy-MM-dd"></EndDate>  
		…
      </PatientPhoneNumber> 

     <PatientPhoneNumber version="3.0.0"> 
        <SourceName>System_A</SourceName>  
        <SourceInstanceId>2</SourceInstanceId>  
        <Type sourceName="OMNI" codeSet="0185">C</Type>  
        <StartDate format="yyyy-MM-dd"></StartDate>  
        <EndDate format="yyyy-MM-dd"></EndDate>  
		…
      </PatientPhoneNumber> 

    </OtherPhoneNumbers>  

</Client>

Link to Another Subject

Example:

<PrimarySupplier>    // link element in schema
   <Supplier>    // linked subject type (subject name)
      <SourceName>System_A</SourceName>    // subject instance source system
      <SourceInstanceId>123</SourceInstanceId>    // subject instance identifier
   </Supplier> 
</PrimarySupplier>

Variable Link to Another Subject

Example:

<ChargeableEvent>    // variable link element in schema
      <Subject>EventSubject1</Subject>    // linked subject type (subject name)
      <SourceName>System_B</SourceName>    // subject instance source system 
      <SourceInstanceId>456</SourceInstanceId>    // subject instance identifier
</ChargeableEvent>

Code

Example:

<AccountType sourceName="System B" codeSet="AccountTypes">C1</AccountType>

where:

AccountType: Is the code element in the schema.
sourceName="System B": Is the code source system.
codeSet="AccountTypes”: Is the code set name.
C1: Is the code value.

Boilerplate Fields/Elements

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

Element	Required?	Description
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.
SourceStatusCode	Optional	A user-defined status value, which may be used as a screening condition for reporting off of the model.
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.

SourceStatusCode is a user-defined status value. It may be used as a screening condition for reporting off of the model.

<SourceName>
<SourceInstanceId> 
<SourceInstanceIdName>
<SourceStatusCode>
<SourceCreatedDate format="yyyy-MM-dd hh:mm:ss">   
<SourceCreatedBy> 
<SourceModifiedDate format="yyyy-MM-dd hh:mm:ss"> 
<SourceModifiedBy>

OID Policies

An OID may direct the system to perform an upsert, replace, or delete operation on the instance data. The specific operation type is indicated by the policy=" " attribute on the root element of the OID.

Example:

<Member xmlns="http://www.ibi.com/2013/OP/Interface" policy=”replace”>

The following operations correspond to the OnRamp batch types:

Policy="merge" corresponds to an UPSERT with the upsertNullHandling option with value PRESERVE.
Policy="replace" corresponds to REPLACE_SELECTED.
Policy="delete" corresponds to DELETE.

By default, this operation will be an upsert (policy="merge") if no policy is specified.

Batch Interface

It is possible to submit several OIDs as a logical batch. To do this, multiple OIDs are wrapped into an OmniInterface document. For example:

<OmniInterface>
      
  <Member>
     ….
 <Member>
  <Member>
     ….
 <Member>
    …
</OmniInterface>

OmniInterface documents are processed as text files that are read from the following folder:

omnigen\OmniGenData\input\oid\input

Successfully submitted documents are copied to the following folder:

omnigen\OmniGenData\input\oid\processed

Unsuccessful ones are copied to the following folder:

omnigen\OmniGenData\input\oid\error

An OmniInterface document may combine OIDs of different subjects and with different policies. However, all records in an OmniInterface document sharing the same subject and policy will be submitted together as sub-batches in no specified order.

Immediate Interface

Topics:

Load OID to Ramp
Process OID

Two REST-based services are available to submit OIDs to an Omni-Gen system.

Load OID to Ramp

PUT "api/v1/server/bulk/load/{subject}"

Parameter	Description	Parameter Type	Data Type
xml	OID	Body (application/xml)	String
subject	Subject name	Path	String
batchId	Batch ID of the Ramp record(s)	query	String

This service populates the appropriate Ramp tables (parent and child collections) with the data from the OID. Multiple OIDs can be loaded into the Ramp using the same batchId and submitted together. For more information, see the Ramp submission options.

The following Swagger interface is available for testing:

https://omni-host:9512/server/swagger-ui.html#!/Bulk32Processing/bulkLoadUsingPUT

Process OID

POST "api/v1/server/processImmediate”

Parameter	Description	Parameter Type	Data Type
xml	OID	Body (application/xml)	String

This service takes a single OID and submits it to an Omni-Gen system.

The following Swagger interface is available for testing:

https://omni-host:9512/server/swagger-ui.html#!/Processing/processImmediateUsingPOST

Comparing OnRamp and XML Interfaces

OnRamp is native to Omni-Gen. OIDs are converted into Ramp batches prior to being submitted.
Full hierarchies are collected in a single document with OIDs. They are separated into different tables for the Ramp.
OnRamp allows for incremental upserts only at the child level.
OnRamp supports REPLACE_ALL and the upsertNullHandling option with values PRESERVE or OVERRIDE.

Migration Consideration for OID Users in Omni-Gen Version 2.x

In Omni-Gen version 2.x, the SourceInstanceId of an instance child was required to be unique within the source system. In Omni-Gen version 3.x, the SourceInstanceId of an instance child must be unique with respect to its parent instance.