Fusion Financials Integration

This section documents the configuration for integrating with Fusion Financials. The Oracle Insurance Gateway supports the following Fusion integration use cases:

  • Fusion’s File Based Data Import (FBDI) also known as the ErpIntegrationService SOAP service for uploading zip files and importing the contents of these:

    • Load and Import Data

    • Submit a Fusion Job

  • Running a report via the Fusion BI Publisher Web Service

Load and Import Data

For the Load and Import Data use case the Oracle Insurance Gateway executes the following steps:

  • Upload a zip file to the Fusion Universal Content Management (UCM) server. This is invoking the uploadFileToUcm SOAP request.

  • Start a job for loading the zip file contents into Fusion’s interface tables. The load job is started through the submitESSJobRequest SOAP request.

  • Monitor the status of the load job using the getESSJobStatus SOAP request. The monitoring continues till the job status shows an end state, whether it succeeds or fails. The Oracle Insurance Gateway exchange step stores the status as raw payload.

  • When the data was loaded successfully into the interface tables: start a job for importing the data from the open interface tables into the Fusion application. The import job is also started through the submitESSJobRequest SOAP request.

  • Monitor the status of the import job using the getESSJobStatus SOAP request. This continues periodically till the job status shows an end state: it either succeeds or fails. The Oracle Insurance Gateway exchange step stores the status as raw payload.

This use case is encapsulated in a specific Destination called "FUSIONLOAD", it is not needed to define separate Integration Steps to execute these processes in Fusion.

The following graphic shows an overview of the steps executed as part of an Oracle Insurance Gateway Fusion integration that extracts data from an Oracle Health Insurance application and loads and imports that data into Fusion:

OIG-fusion-integration

The overview depicts the scenario where all steps are a success. If a step in the process fails, the Oracle Insurance Gateway exchange also fails. You can restart after resolving the problem.

If the Fusion job fails or delivers a warning status, the Oracle Insurance Gateway exchange continues processing. You can evaluate the import job status by using the Step Post Process function and determine the next steps, whether to continue or stop. This process is helpful when a single provider record out of a thousand fails, and you want the records to continue processing despite the one-failed record.

for (s in exchangeStep.exchange.exchangeSteps) {
  if (s.integrationStep == exchangeStep.integrationStep && s.integrationSubStep == 'checkJobStatus' && (s.getPreviousExchangeStep().integrationSubStep == 'submitJob' || s.getPreviousExchangeStep().integrationSubStep == 'importJob') && s.exchangeStepPayload.rawPayload != 'SUCCEEDED')

  {
    throw new Exception('Job status ' + s.exchangeStepPayload.rawPayload + ' in exchange step ' + s.id)
  }
}

Submitting a Fusion Job

For Submitting a Fusion Job the Oracle Insurance Gateway executes the following steps:

  • Submit a configured Fusion job through the submitESSJobRequest SOAP request. If Fusion did not accept the job request then the Exchange fails with error OIG-GATE-059, and the system triggers a workflow event.

  • Monitor the status of the job using the getESSJobStatus SOAP request. The monitoring continues periodically till the job status shows an end state, whether it succeeds or fails. If the Fusion job fails the Exchange also fails with error OIG-GATE-060, and the system triggers a workflow event. In case a Fusion Import job status shows a failure or sends a warning, the Oracle Insurance Gateway exchange continues processing. Using a Step Post Process dynamic logic function, you can evaluate an import job status and determine the next steps, whether to continue or stop. This process is relevant where one provider record fails out of a thousand, and you want the successful ones to continue processing.

This use case is encapsulated in a specific Destination called "FUSIONSUBM", and as is the case for the "FUSIONLOAD" Destination it is not needed to define separate Integration Steps to execute these processes in Fusion.

Running a Fusion BI Publisher Report

For running a Fusion report the Oracle Insurance Gateway supports calling the RunReport SOAP request in the BI Publisher ReportService. This is a synchronous request that executes the report and returns the output immediately. The Oracle Insurance Gateway captures the (Base64 encoded) report output and makes it available as Data File in a Data File Set.

This use case is encapsulated in a specific Destination called "FUSIONREPT", it is not needed to define separate Integration Steps to execute these processes in Fusion.

The Data File can be processed in a subsequent Integration Step.

Fusion Integration Requirements

This paragraph lists how the Oracle Insurance Gateway connects to Fusion’s FBDI service. It defines requirements that must be taken into account for the Fusion (technical) setup.

Security

The Fusion FBDI client in the Oracle Insurance Gateway connects to the Fusion SOAP service using Basic Authentication. Basic Authentication credentials must be registered in the Oracle Insurance Gateway by using the "credentials" resource for the key that is specified in the configuration of the Destination (see section Configuration below). The Oracle Insurance Gateway uses the same credentials for all SOAP operations that are in context of the configured Fusion Destination.

Oracle Insurance Gateway Fusion FBDI client does not sign the zip file contents before sending these to Fusion.

The Fusion BI Publisher Report Service requires sending username and password credentials as part of the SOAP body. These credentials must also be registered in the Oracle Insurance Gateway by using the "credentials" resource for the key that is specified in the configuration of the Destination (see section Configuration below).

Transmitting Zip File Contents

The Fusion FBDI service supports two ways for transmitting a zip file containing the data that must be loaded into Fusion:

  1. In-line, as a base64 encoded string.

  2. Using SOAP Message Transmission Optimization Mechanism/XML-binary Optimized Packaging (MTOM/XOP).

The Fusion FBDI client in the Oracle Insurance Gateway sends a zip file using the MTOM/XOP option.

Receiving Report Contents

The Fusion Report Service client in the Oracle Insurance Gateway is set up to receive and process the entire report contents in single, in-memory operation. Ensure that the setup of run frequency for reports is such that the amount of data that is returned is within system limits.

Load and Import Data Configuration

Integrations for Fusion are configured using HTTP APIs. Before going into the details of configuring Fusion Destinations the requirements for an Oracle Insurance Gateway Integration are outlined.

Integration Requirements

For integrating with Fusion’s FBDI service, data that must be loaded into Fusion applications is typically in CSV format and must be transmitted as zip file. An integration that is configured to produce a raw payload is not supported in combination with the Fusion specific Destination.

Before the Oracle Insurance Gateway constructs the SOAP request all input for it must be complete. Usually, constants that must be passed in the request are part of the Destination configuration. Some input can only be determined when the Exchange for the Integration is being processed, that is the case for job parameters for example. The Oracle Insurance Gateway expects all job parameters to be available as Exchange Properties before it constructs the SOAP request.

Load and Import Data Destination Configuration

The following sample Destination configuration is for a Load and Import Data scenario (formatted for readability):

{ "code" : "fusion_load_suppliers",
  "addressKey" : "address.key.fusion_load_suppliers.service.uri",
  "credentialKey" : "fusion_load_suppliers.credential.key",
  "subtype" : "FUSIONLOAD",
  "typeConfig" :
  { "documentTitlePrefix" : "OHI_Supplier",
    "documentAuthor" : "supplier_manager",
    "documentSecurityGroup" : "FAFusionImportExport",
    "documentAccount" : "prc/supplier/import",
    "loadJobPackageName" :
      "oracle/apps/ess/financials/commonModules/shared/common/interfaceLoader",
    "loadJobDefinitionName" : "InterfaceLoaderController",
    "loadJobParameters" :
      "interfaceDetails,fusionDocumentId,supplierImportOptions,supplierReportExceptionsOnly",
    "loadJobTimeOutValue" : 600,
    "loadJobStatusCheckInterval" : 60,
    "importJobPackageName" :
      "oracle/apps/ess/cdm/foundation/bulkImport",
    "importJobDefinitionName" : "CDMAutoBulkImportJob",
    "importJobParameters" :
      "supplierBatchId,jobType,jobEntity,jobDocumentFormat",
    "importJobTimeOutValue" : 1800,
    "importJobStatusCheckInterval" : 300
  }
}

Explanation of the typeConfig attributes:

  • The "documentTitlePrefix" is used to compose the document title. As Fusion requires the document title to be unique, the Oracle Insurance Gateway creates it by appending a unique (technical) ID to the documentTitlePrefix.

  • The values for attributes "documentAuthor", "documentSecurityGroup", "documentAccount", "loadJobPackageName", "loadJobDefinitionName", "importJobPackageName" and "importJobDefinitionName" are passed to the FBDI SOAP operation verbatim; these must match the Fusion job setup.

  • The values for attributes "loadJobParameters" and "importJobParameters" defines the job parameters that are passed to Fusion for the load and import jobs respectively. Note that the order in which these are specified determines the order in which the (values for these) job parameters are passed to Fusion. How job parameter values are set is explained in the following paragraph.

  • The "loadJobStatusCheckInterval" and "importJobStatusCheckInterval" define the interval used by the Oracle Insurance Gateway to check the status of the load and import jobs respectively. These are defined in seconds.

  • Finally, the "loadJobTimeOutValue" and "importJobTimeOutValue" determine how long the Oracle Insurance Gateway keeps polling for the load and import jobs respectively to reach an end state from the moment that the job was submitted to Fusion. If the timeout period is reached before the status of the job reaches an end state, the Oracle Insurance Gateway marks the Exchange as Failed. These are defined in seconds.

The configuration must be entered using the "fusionloadimportdatadestinations" resource.

Setting Job Parameter Values

Using the sample Destination configuration introduced earlier, this paragraph lists (some) alternative use cases for setting job parameter values.

For some Fusion jobs passing parameters is not required, in that case the literal value "null" is typically used. If an empty job parameter list is used for a job that does require parameters, Fusion is likely to return the following ServiceException:

JBO-29000: Unexpected exception caught: java.lang.NullPointerException, msg=null: null

Note that Oracle Insurance Gateway’s Fusion client does not pass the literal "null" value as job parameter if the job parameter list is left empty.

Passing Constant Parameter Values when Initiating the Exchange

Create an exchange for the fusion_load_suppliers integration through an HTTP POST request to /api/exchanges/integration/fusion_load_suppliers using:

https://.../api/exchanges/integration/fusion_load_suppliers/withParameters

and pass the following parameters:

Parameter Name

Parameter Value

supplierImportOptions

N

supplierReportExceptionsOnly

N

Note that Parameter Extraction Dynamic Logic must be used to extract parameters and values from the request and make these available as Echange Properties. The following paragraph shows how parameters are translated into Exchange Properties.

Setting Exchange Properties in Dynamic Logic

The following Transformation Dynamic Logic gets its input from a Data File that was uploaded when the Exchange was initiated using the "with file" option of the Exchange resource. It defines a unique Batch ID that is used to create supplier records that need to be imported into Fusion. In order to also pass the Batch ID as job parameter it is listed as an Exchange Parameter. The following sample is formatted for readability:

import com.google.gson.*
import org.apache.commons.csv.*

// Get a CSV writer for creating a Data File
def csvPrinter = outputWriters.
  getDataFileOutputWriter("Supplier_" + exchangeStep.getId(), "text/csv").
  csvPrinter(CSVFormat.DEFAULT)

// The 'batch id' is used in the payload records and should subsequently be
// passed as job parameter to Fusion. Only records that were imported into
// the open interface tables with the batch id that matches the job parameter
// are processed.
def supplierBatchId = "OHI" + exchangeStep.getId()

// The Exchange was triggered "with file"
trigger.dataFiles.each { df ->

  def gson = new GsonBuilder().create()
  def jsonReader = fileReader.jsonReader(df)

  jsonReader.beginObject()
  jsonReader.nextName()
  jsonReader.beginArray()

  while( jsonReader.hasNext() ) {
    def supplier = gson.fromJson(jsonReader, Map.class)

    csvPrinter.printRecord("CREATE",supplier["id"],null,null,null,
    supplier["taxorganizationtype"],null,null,supplier["relationship"],
    null,null,null,"N",null,null,null,null,null,null,"N",
    supplier["countrycode"],supplier["taxpayerid"],null,null,null,null,
    null,null,null,null,null,null,null,"EFT",null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,null,null,null,null,null,null,null,null,
    null,null,null,null,null,supplierBatchId,null,null,null,null,null,
    null,"END")
  }
}

// List job parameters as Exchange Properties
// Note that the property names match the job parameters definition
// in the Destination configuration

// list load job parameters as Exchange properties
properties.put("interfaceDetails", "24")
properties.put("supplierImportOptions", "N")
properties.put("supplierReportExceptionsOnly", "N")
properties.put("supplierBatchId",supplierBatchId)

// list import job parameters as Exchange properties
properties.put("jobType","BATCH")
properties.put("jobEntity","SUPPLIER")
properties.put("jobDocumentFormat","CSV")

Note that for loading Supplier data the Batch ID may contain alphanumeric values. For loading Customer data the Batch ID must be a unique numeric value only. If that requirement is not adhered to then job requests result in an error.

Configure the Integration

The following sample Integration configuration shows an Integration that assumes that an inbound supplier file should be transformed (e.g. from JSON format to CSV) and that the resulting zip file containing the CSV file should be delivered to Fusion. Moreover, the configuration for the Integration Step specifies that the Exchange halts after delivering the zip file to Fusion and submitting the Fusion job for processing the zip file contents: it expects to be resumed after receiving a notification when the Fusion job completes. Note that checking that the Fusion job completed and sending the notification to resume the Exchange is not handled automatically by the Oracle Insurance Gateway. It could be dealt with in a separate Integration. The Oracle Insurance Gateway expects the step to finish and receive the notification within the specified allowed time of 10 minutes. After the allowed time expires the Oracle Insurance Gateway checks if the Exchange was resumed. If that is not the case then it checks again after 10 minutes. This repeats 3 times. If the Exchange was not resumed after the third and final check, in this example after 30 minutes, then the Oracle Insurance Gateway marks the Exchange as TimedOut.

{ "code" : "fusion_load_suppliers",
  "integrationSteps" : [
    { "code" : "transform_and_deliver",
      "sequence" : "1",
      "subtype" : "DELIVERY",
      "functionTransformation": {
        "code" : "fusion_transform_suppliers"
      },
      "destination" : {
          "code" : "fusion_load_suppliers"
      },
      "indicatorExpectNotification": true,
      "typeConfig" : {
          "timeAllowed" : 10
      }
    }
  ]
}

Fusion Import Results

The Oracle Insurance Gateway tracks the status of loading and importing data. Please note that although the import process finishes with status 'succeeded' that does not necessarily mean that all data was imported successfully. Check the results of the import process in Fusion itself. For example, the following screenshot shows the results of a CUSTOMER import batch that completed with status 'succeeded':

fusion-data-import-batch

Of 8 records that were uploaded in CSV files 5 were imported but 3 were not.

Submitting a Fusion Job Configuration

Configuring the use case for Submitting a Fusion Job is comparable to the Load and Import Data Configuration that was explained in the previous paragraph. The main difference is the use of a specific Destination type which is covered in the next section.

Submitting a Fusion Job Destination Configuration

The following sample Destination configuration is for the Submitting a Fusion Job scenario:

{ "code" : "fusion_submit_job",
  "addressKey" : "address.key.fusion_submit_job.service.uri",
  "credentialKey" : "fusion_submit_job.credential.key",
  "subtype" : "FUSIONSUBM",
  "typeConfig" :
  { "jobPackageName" : "theJobPackageName",
    "jobDefinitionName" : "theJobDefinitionName",
    "jobParameters" :
      "nameForParameter,nameForAnotherParameter",
    "jobTimeOutValue" : 600,
    "jobStatusCheckInterval" : 60
  }
}

Explanation of the typeConfig attributes:

  • The values for attributes "jobPackageName" and "jobDefinitionName" are passed to the FBDI SOAP operation verbatim; these must match the Fusion job setup.

  • The value for attribute "jobParameters" defines the job parameters that are passed to Fusion for the job. Note that the order in which these are specified determines the order in which the (values for these) job parameters are passed to Fusion. How job parameter values can be set as Exchange properties was explained in the previous paragraph.

  • The "jobStatusCheckInterval" defines the interval used by the Oracle Insurance Gateway to check the status of the submitted job. It must be defined in seconds.

  • Finally, the "jobTimeOutValue" determines how long the Oracle Insurance Gateway keeps polling for the job to reach an end state from the moment that the job was submitted to Fusion. If the timeout period is reached before the status of the job reaches an end state, the Oracle Insurance Gateway marks the Exchange as Failed. The value is defined in seconds.

The configuration must be entered using the "fusionsubmitjobdestinations" resource.

Running a Fusion BI Publisher Report

Run Report Destination Configuration

The following sample Destination configuration is for a Fusion BI Publisher Run Report scenario:

{ "code" : "fusion_runreport",
  "addressKey" : "address.key.fusion_runreport.service.uri",
  "credentialKey" : "fusion_runreport.credential.key",
  "subtype" : "FUSIONREPT",
  "typeConfig" :
  { "reportFormat" : "xml",
    "reportLocale" : "en-AU",
    "reportTemplate" : "OHI Payment Invoice",
    "reportAbsolutePath" : "Custom/OHI Payment Invoice/OHI Payment Invoice.xdo",
    "reportParameters" : [{
      "name" : "P_ORGANIZATION_NAME",
      "value" : "reportOrganizationName"
     },{
      "name" : "P_START",
      "value" : "reportStartDate"
     },{
      "name" : "P_END",
      "value" : "reportEndDate"
     }]
  }
}

Explanation of the typeConfig attributes:

  • The values for "reportFormat", "reportLocale", "reportTemplate", and "reportAbsolutePath" are passed to the RunReport SOAP operation verbatim; these must match the Fusion report setup.

  • The values for attribute "reportParameters" defines the parameters that are passed in the Run Report request. Note that parameters are passed as name - value pairs, this differs from passing parameters for the Fusion FBDI service. What is similar is the use of Exchange properties: the property values should refer to names of Exchange properties. At the time the parameters are collected to be communicated to Fusion, these Exchange properties must have a value.

The configuration must be entered using the "fusionrunreportdestinations" resource.

Log SOAP Messages

It is possible to log request and response SOAP messages by configuring the SOAP handler that is available for that purpose. Note that it makes use of the Java Logging API and requires use of a logging.properties file. A default file is not bundled with Oracle Insurance Gateway.

The following is a sample logging.properties file that logs SOAP messages to the console:

handlers = java.util.logging.ConsoleHandler
java.util.logging.ConsoleHandler.level=ALL

Point to the logging.properties file by setting JVM property "java.util.logging.config.file" to point to this file.