3 Soap Integration Points

3.1 Attribute Handling

Each integration point request message contains data values of a top-level entity (e.g. relation or provider) that have been created or updated in a source system. Within each message are several categories of data such as simple entity-level attributes, lists of non-time valid details, and lists of time-valid details. This section describes how each category of data is handled by OHI applications and also covers guidelines for handling differences in data categories between source systems and OHI applications.

The way that an OHI application handles web service requests is based on the principle that the copy of information in the OHI application is to be kept up-to-date with the (master) information in the system of record.  It is not required that the OHI application is informed of every update system of record; only the values at the time of creating the web service requests are important.  For example, if an interface periodically creates requests for all outstanding additions and updates, only the values of source system data at the time that the interface is run need to be sent. Whether a record has been updated several times or once since the last interface run is irrelevant.

If an existing record is sent again and it contains the exact same data that is already stored in the system, the existing data will not be updated. This means that the audit columns in the database will also remain unchanged. Tracking these messages can be done through the interface messages log.

3.1.1 Single Value Attributes

These are fields that can have only one single value and the value does not have a start and end date. When the application creates a new record, single value attributes are handled as follows: if the attribute is not included in the request, then the corresponding attribute in the new record will be set to null; if the attribute is included in the request, then the corresponding attribute in the new record will be set to the specified value.

When the application updates a record, a single value attribute is handled as follows: if the attribute is not included in the request, then the existing value in the application remains untouched; if the attribute is included in the request, then the attribute value is updated with the specified value.

For example, consider a new relation being added in the system of record. Because the OHI application keeps a local copy of relation records, the system of record sends the following request to the OHI application:

<relation
  code="1333"
  name=Jones
>
  <personDetails
    firstName="John"
  >
>

Since this is the first time that the relation with code 1333 is being sent, the OHI application creates a new relation record with only code, name, and firstName having values. All other attributes in the new record in the OHI application will be null. The relation is updated in the source system; the first name is changed from "John" to "Jonathan". The system of record sends the following request to the OHI application:

<relation
  code="1333"
>
  <subTypeDetails>
    <person
      firstName="Jonathan"
    >
  </subTypeDetails>
</relation>

Since there is already a relation with this code, the OHI application will update the relation record with code = 1333 setting <person firstName> to Jonathan. <Relation name> will not be changed or set to null.

External Interface Design Notes

If a given type of data is a single value attribute in an Integration Point message definition and a time valid detail list in the source system, the external interface is expected to only send the latest / current value.

If a given type of data is a single value attribute in an Integration Point message definition and a non time valid detail list or otherwise not a one-to-one match in the source system, the external interface will require (dynamic) logic needed to determine what value should be provided.

3.1.1.1 Amount and Currency

Amount and currency are two attributes that belong together, so they are always represented together in a separate element. For example:

<authorizedAmount
  amount="100"
  currencyCode="USD"
/>

If the element is not included in the request, then the existing values for amount and currency in the application remain untouched; if the element is included in the request, then the values are updated with the specified values. In order to send in an update that clears the values, the update request should include the element without any attributes and values (empty element).