4.2 Attribute Handling

Each integration point request message contains data values of a root element (e.g. organization or organization 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, dynamic fields and dynamic records. 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 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 in the system of record; only the values at the time of creating the 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.

4.2.1 Single Value Attributes

Single value attributes are fields that can have only one single value and the value does not have a start and end date. Single value attributes can be represented in the requests as attributes (for example name in the organizationProvider request) or as elements (for example parentOrganizationProvider in the organizationProvider request). When the application creates a new record, single value attributes are handled as follows:

• Represented as attributes: if the attribute is not included in the request, then the value of 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.
• Represented as elements: if the element is not included in the request, then the value of the corresponding attribute in the new record will be set to null; if the element 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: 

• Represented as attributes: 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. In order to send in an update that clears the value, the update request should include the attribute with an empty value.
• Represented as elements: if the element is not included in the request, then the existing value in the application remains untouched; if the element is included in the request, then the attribute value is updated with the specified value. In order to send in an update that clears the value, the update request should include the element without any attributes and values (empty element).

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

<organization
  code="1333"
  name="Jones Administration"
  outputLanguage="en"
  businessPhoneNumber="0301111111"
/>

Since this is the first time that the organization with code "1333" is being sent, the OHI application creates a new organization record (relation of subtype organization) with only code, name, language and business phone number having values. All other attributes in the new record in the OHI application will be null. The organization is updated in the source system; the business phone number is changed from "0301111111" to "0301111112". The system of record sends the following request to the OHI application:

<organization
  code="1333"
  businessPhoneNumber="0301111112"
/>

Since there is already an organization with this code, the OHI application will update the organization record with code "1333", setting the business phone number to "0301111112". The name and the language 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.

4.2.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).