Using the Oracle Health Insurance Integration Connector

Introduction

The Integration Connector builds on an Oracle Health Insurance application’s capability to configure business rules for detecting changes and the ability to inform external systems of these. It allows processing of Change Events of type 'Message' into messages that an external system can consume. The Integration Connector’s high-level workflow is outlined in the following diagram:

Integration Connector Configuration and Runtime

Change Event Rules

The Security Guide of an Oracle Health Insurance application that features the Integration Connector provides details on configuration of Change Event Rules of type 'Message'. The same documentation lists the Event Levels, like Person or Organization, and how Change Events of a certain level are aggregated into Aggregate Event types.

Aggregate Events

The system translates detailed Change Events into Aggregate Events. An example is a change that is detected at the level of an Organization Address; the system translates that in an Aggregate Event at the Organization level.

Aggregate objects define the level at which messages are constructed using Dynamic Logic: aggregate objects are passed in as bind variables. The Developer Guide defines the signature for Message Transformation Dynamic Logic functions.

The system periodically aggregates Change Events into Aggregate Events. The period is configurable through system property "ohi.connector.event.aggregation.interval". By default it is 300 seconds. By decreasing the aggregation interval external systems can be informed of changes faster.

If multiple details for an aggregate object are changed over time, decreasing the aggregation interval may result in the external system having to handle a larger amount of messages for the same aggregate object.

Integration Connector Configuration

Integration Connector configurations define how Aggregate Events are transformed into an external format (using Dynamic Logic), with which frequency this is done and to which Channel type the output is delivered. The combination of Aggregate Type, Dynamic Logic and Channel type must be unique.That means that messages for a changed aggregate can be published to multiple channels in different formats and at different time intervals.

The code of an Integration Connector configuration must be unique. Note that the code is referenced in system properties, it is suggested to make it meaningful.

Please be aware that connector codes are stored in uppercase, even when submitted in mixed case. System properties must also be created as uppercase for the connector to function.
Table 1. Integration Connector Configuration
Field Description

Code

The unique code of the connector configuration

Aggregate Type

The type of the aggregate object

Channel Type

Messages are published to this configured channel type, for details on each type refer to the section on publishing messages

  • REST

  • DataFileSet

  • DataFileSetWithGateway

Message Interval

Time interval in seconds with which the system processes changes

Mime Type

Media type of the message

Change List

The list of changes that are consider in scope for this configuration

Message Dynamic Logic Function

Dynamic logic function of signature Message Transformation. For more details on message transformation logic refer Dynamic Logic guide.

Enabled?

Indicates if the connector configuration is enabled or not.

Using Change List

The 'Changes List ' field on the connector configuration contains the details of the entity and the DML operations, including the list of attributes per entity in JSON format. This information is then compared with the change list that is composed by aggregating the source change logs of all the applicable aggregate event that triggered the connector configuration. The connector configuration is considered when at least one change as specified in the changes list is present in the source changes.

If the 'Change List' is not specified, the connector configuration is considered and message function is always invoked.

The change list can be specified below

{
    "changeRuleList": [
        {
            "entityName": "name of the entity, defined in view objects page",
            "op": "create"/"update"/"delete",
            "fieldList":["field1", "field2"] - comma separated list of fields that can be tracked for updates, when not specified all the fields are considered as applicable

        },
        ...
    ]
}

Example -If the message function should only be invoked if either the status ( a dynamic field ) on the group client is changed or when a new billing account is added, then the change list for the aggregate type group client must be specified as:

{
    "changeRuleList": [
        {
            "entityName": "GroupClient",
            "op": "update",
            "fieldList":["status"]
        },
        {
            "entityName": "GroupClientBillingAccount",
            "op": "create"
        }
    ]
}

Publishing Messages

The following Channel types are supported:

  • REST: the system sends a POST or PUT request for each aggregate object; the transformed message is the request’s payload. The Integration Connector Configuration allows specification of the mime-type that will be used as "Content-Type" request header.

  • Data File Set: the system bundles multiple transformed messages into one or more Data Files that are part of a Data File Set and sends out a notification to a configured endpoint. The notification message contains a list of Data Files and the URLs for obtaining their contents.

  • Data File Set With Gateway: the system bundles multiple transformed messages into one or more Data Files that are part of a Data File Set and uploads the Data File contents to a configured endpoint in Oracle Health Insurance Integration Gateway.

The endpoint URI and HTTP method for either REST or Data File Set/Data File Set With Gateway notification requests must be defined using system properties "ohi.connector.configuration.{configuration_code}.uri" and "ohi.connector.configuration.{configuration_code}.httpmethod" respectively. The "configuration_code" points to an Integration Connector configuration.

If the remote resource endpoint requires authentication, use the "ohi.service.{configuration_code}.client.authentication" system property to define the authentication mechanism (Basic Authentication and OAuth2 are supported) and configure a credential with the key matching the connector configuration code via the Oracle Health Insurance application’s "/credentials" resource.

With respect to bundling one or more transformed messages into a Data File Set:

  • System property ohi.connector.transformation.bucketsize determines how many messages are bundled in a Data File.

  • When collecting messages in Data Files, the system does not add any further details like header or footer elements.

Re-publishing Messages

If the delivery of the messages failed (for example, the external system is not available), it is possible to configure Oracle Health Insurance application to retry publishing of the failed messages by setting the system property "ohi.connector.message.republishing.activated" to true (false by default). The system periodically retries publishing of failed messages. The period is configurable through system property "ohi.connector.message.republishing.interval". By default, it is 300 seconds.

If the delivery of the messages failed due to client error (that is, 4xx http status codes), then re-publishing will not be attempted. Once the root cause of client error is resolved, it is possible to retry publishing of those failed messages by invoking (POST) the following IP operation.

http://://connectorconfigurations/{id}/republishfailedmessages

The following error messages return as part of the response:

  • 404 Not Found: when the id of the connector configuration could not be found in the database.

  • 409 Conflict: when there are no failed message publishing result to be re-published for this connector configuration.

Configuring the Integration Connector

By default, the Integration Connector feature is disabled. Next to defining Change Event Rules of type 'Message', the following steps are needed to enable and configure the Integration Connector:

  1. Set system property ohi.connector.event.aggregation.activated to true. This enables periodic aggregation of Change Events into Aggregate Events.

  2. Configure a Message Transformation Dynamic Logic (see the example below).

  3. Configure the Integration Connector through its HTTP API resource "/connectorconfigurations", referencing the Dynamic Logic. See its Swagger / OpenAPI specification for details. The following is an example configuration message for an Integration Connector configuration (in context of Oracle Health Insurance Enterprise Policies Administration):

{ "code": "TEST_GROC_REST",
  "aggregateType": "GROC",
  "channelType": "REST",
  "mimeType": "text/plain",
  "timeIntervalInSeconds": 60,
  "transformationLogic": { "code": "TEST_GROC_DYLO" }
}

This example configures the system to aggregate Group Client changes every 60 seconds, transform de-duplicated Group Client objects using a Dynamic Logic that is denoted by code TEST_GROC_DYLO into messages with a mime type 'text/plain' and publish these to a REST resource endpoint. 4. Complement Integration Connector configuration with system properties as explained above.

Message contents are opaque to Oracle Health Insurance applications, the system does not inspect or interpret the messages in any way. The output can be any text format, such as comma-delimited ASCII text, XML or JSON.

The following is an example Message Transformation Dynamic Logic that creates an XML message for a Group Client aggregate object:

import groovy.xml.*

static void addBillGroup(GroupClientBillingAccount groupClientBillingAccount, MarkupBuilder mb) {
  mb.BillGroup{Bill_Group_Name{ Bill_Group_Name_Type("Type")
                                Bill_Group_Name_Value(groupClientBillingAccount.code)
                              }
               }
}

static void addCustomerData(GroupClient groupClient, MarkupBuilder mb) {
  mb.CustomerData{ Customer_Name(groupClient.organizationEmployer.name)
                   Customer_Type()
                     Primary_ID {
                       Primary_ID_Type()
                       Primary_ID_Value(groupClient.code)
                     }
                 }
}

static void addHeader(MarkupBuilder mb) {
  mb.Header{ Message_ID{}
             Message_Batch_ID(1234)
             Source_System_Transaction_ID{}
             Source_System_Customer_ID{}
             Business_Object_Name{}
             Status{}
             Create_Date_Time{}
             Business_Transaction_Type{}
           }
}

static void addPlan(GroupAccountProduct groupAccountProduct, MarkupBuilder mb) {
  mb.Plan{ Product(groupAccountProduct.displayName) }
}

static void addPolicyData(GroupAccount groupAccount, MarkupBuilder mb) {
  mb.PolicyData{ Policy_Name(groupAccount.descr)
                 groupAccount.groupAccountProductList.each{
                   groupAccountProduct -> addPlan(groupAccountProduct, mb)
                 }
               }
}

// Test if the aggregate is a GroupClient as expected
if (aggregateObject instanceof GroupClient) {
  def groupClient = aggregateObject
  def writer = new StringWriter()
  def CustStruct = new groovy.xml.MarkupBuilder(writer)

  Struct.StructuredMessage() {
    Message {
      addHeader(CustStruct)
        Data {
          addCustomerData(groupClient, CustStruct)
          groupClient.groupClientBillingAccountList.each{
            groupClientBillingAccount -> addBillGroup(groupClientBillingAccount, CustStruct)
          }
          groupClient.groupAccountList.each{
            groupAccount -> addPolicyData(groupAccount, CustStruct)
          }
       }
    }
  }

  // Return a collection of messages as per the Message Transformation signature
  messages.add(writer.toString())
}

which would produce the following example XML message:

<StructuredMessage>
  <Message>
    <Header>
      <Message_ID />
      <Message_Batch_ID>1234</Message_Batch_ID>
      <Source_System_Transaction_ID />
      <Source_System_Customer_ID />
      <Business_Object_Name />
      <Status />
      <Create_Date_Time />
      <Business_Transaction_Type />
    </Header>
    <Data>
      <CustomerData>
        <Customer_Name>ACME Employer</Customer_Name>
        <Customer_Type />
        <Primary_ID>
          <Primary_ID_Type />
          <Primary_ID_Value>DGC</Primary_ID_Value>
        </Primary_ID>
      </CustomerData>
      <BillGroup>
        <Bill_Group_Name>
          <Bill_Group_Name_Type>Type</Bill_Group_Name_Type>
          <Bill_Group_Name_Value>1234.5678.90</Bill_Group_Name_Value>
        </Bill_Group_Name>
      </BillGroup>
      <BillGroup>
        <Bill_Group_Name>
          <Bill_Group_Name_Type>Type</Bill_Group_Name_Type>
          <Bill_Group_Name_Value>4321.8765.09</Bill_Group_Name_Value>
        </Bill_Group_Name>
      </BillGroup>
      <PolicyData>
        <Policy_Name>Acme Engineering</Policy_Name>
        <Plan>
          <Product>ACME_PPO</Product>
        </Plan>
        <Plan>
          <Product>ACME_HMO</Product>
        </Plan>
      </PolicyData>
      <PolicyData>
        <Policy_Name>Acme Sales</Policy_Name>
        <Plan>
          <Product>ACME_PPO</Product>
        </Plan>
        <Plan>
          <Product>ACME_HMO</Product>
        </Plan>
      </PolicyData>
    </Data>
  </Message>
</StructuredMessage>

Dynamic Logic should also be used to filter aggregate events that are not functionally relevant: in that case the Dynamic Logic function should not produce and return messages.

The following messages can occur during the transformation (that is, during the execution of the dynamic logic):

Table 2. Configuring the Integration Connector
Code Sev Message Text

INT-INCN-001

Fatal

Exception transforming persistable with id {id}

Working With the Oracle Health Insurance Integration Gateway (OIG)

For delivering Data Files via SFTP (to an SSH FTP v3 capable SFTP server), the Integration Connector can be configured to work with the Oracle Health Insurance Integration Gateway. The solution setup, in this case based on use of the Integration Connector in Oracle Health Insurance Enterprise Policy Administration, is outlined in the following diagram:

Integration connectoer and gateway deployment

The Integration Connector is configured to upload the contents of all the Data Files of the Data File Set (using multipart/form-data) to the Oracle Health Insurance Integration Gateway’s "/api/exchanges/integration/{integration_code}" resource URL in which the "integration_code" points to an integration configuration with an integration step which refers to a destination with SFTP configuration that contains specific SFTP endpoint parameters.

The Oracle Health Insurance Integration Gateway saves the contents of all the Data Files in the Data File Set and they are transferred by SFTP to the configured destination.

See the Oracle Health Insurance Integration Gateway documentation for configuration details for SFTP endpoints.

Recovery of Failed Activities

For output transformation the Integration Connector makes use of the Oracle Health Insurance Activity processing framework. To transform large sets of aggregate objects, work is divided into multiple so called child activities under one Integration Connector activity.

In case an exception occurs, for example in Message Transformation Dynamic Logic code, the child activity in the context of which the exception occurred completes with errors, also causing the top-level Integration Connector activity to complete with errors. The other child activities may finish successfully and for those the system will publish the transformed messages to the configured channels.

When the problem is resolved, in this case by fixing the Message Transformation Dynamic Logic function, the top-level Integration Connector activity that completed with errors may be restarted. See the Developer Guide for recovering failed activities.