Product Benefit Specification Integration Point (HTTP)

This web service supports importing products, product details, benefit specifications and benefit specification details into Claims. This is an asynchronous and file based service. It includes operations to create and update the following entities:

  • Country Region Groups

  • Benefit Priorities

  • Benefit Specifications

  • Products and its details including product benefit specifications

Product Benefit Specification Request

Before this web service is called, the user has to upload the product benefit specification payload into the system, using the Data File Set web service. This web service is described in the Configuration Guide.

We recommend uploading files with sizes under 20 MB. Larger files impact the stability of the system.

The different elements included in the payload have inter-dependencies that require them to be processed in a specific sequence. For that reason the payload is distributed over three to four separate data files, all in the same set. These three to four data files are distinguished by the first position of their code ('their prefix').

They are processed in the following sequence:

  1. A datafile with prefix '1' is processed first. This file contains country region groups. An example of the code of this file "1CountrRegionGroups".

  2. Next is the datafile with prefix '2' containing benefit priorities. An example of the code of this file "2BenefitPriorities".

  3. Then prefix '3' for benefit specifications.

  4. Last is prefix '4' for products.

Once the data file set - containing one or more datafiles with a product benefit specification payload - is created, the product benefit specification import process is initiated by a HTTP POST request to: http://[hostName]:[portNumber]/[api-context-root]/writeproductbenefitspecifications. A write product benefit specification (initiation) request has the following structure:

{
  "dataFileSetCode" : "..."
  "responseDataFileSetCode" : "..."
 }

The request can also be submitted with the equivalent XML payload, contained by the root element: <writeProductBenefitSpecificationInput>. In the above request the dataFileSetCode refers to the data file set that contains the datafile(s) with product benefit specification records that needs to be imported. The response data File Set Code refers to the data file set that contains the datafile(s) response file with productbenefitspecification.

The following sections specify the expected payload per data file type.

Country Region Groups

The payload contains root element:

<countryRegionGroups/>

Country region groups are structured as follows:

<countryRegionGroups>
  <countryRegionGroup
    elementId
    uuid // UUID of the country region group
    code
    description>
    <countryRegionGroupDetailList>
      <countryRegionGroupDetail
        countryRegionCode
        countryCode
      />
    </countryRegionGroupDetailList>
  </countryRegionGroup>
</countryRegionGroups>

Benefit Priorities

The payload contains root element:

<benefitPriorities/>

Benefit priorities are structured as follows:

<benefitPriorities>
  <benefitPriority
    elementId
    uuid
    code
    displayName
    priority
  />
<benefitPriorities>

Data File Type BENEFIT SPECIFICATIONS

Data files of this type contain only <benefitSpecifications>

<benefitSpecifications>
  <benefitSpecification
    elementId
    uuid // UUID of the benefit specification
    code
    description
    serviceOptionServiceCode
    active
    subType
    claimFormTypeCode
    procedureGroup1Usage
    procedureGroup1Code
    procedureGroup2Usage
    procedureGroup2Code
    procedureGroup3Usage
    procedureGroup3Code
    procedureConditionUsage
    procedureConditionCode
    diagnosisGroupCode
    diagnosisGroupUsage
    diagnosisConditionCode
    diagnosisTypeCode
    employerCountryRegionUsage
    employerCountryRegionGroupCode
    employerCountryRegionCode
    employerCountryRegionCountryCode
    providerCountryRegionUsage
    providerCountryRegionGroupCode
    providerCountryRegionCode
    providerCountryRegionCountryCode
    personCountryRegionUsage
    personCountryRegionGroupCode
    personCountryRegionCode
    personCountryRegionCountryCode
    productProviderGroupScope
    specificProviderGroupScope
    regimeCode
    caseDefinitionCode
    gender
    ageFrom
    ageTo
    authorizationMissing
    consumeAuthorization
    priorityCode
    locationTypeUsage
    modifierUsage
    specialtyUsage
  >
    <benefitSpecificationDynamicLogicList>
      <benefitSpecificationDynamicLogic
         code
      />
    <benefitSpecificationDynamicLogicList>
    <benefitSpecificationProviderGroupList>
      <benefitSpecificationProviderGroup
         code
         assignmentLabel
      />
    </benefitSpecificationProviderGroupList>
    <benefitSpecificationLocationTypeList>
      <benefitSpecificationLocationType>
        <locationType
          code
          claimFormTypeCode
        />
      </benefitSpecificationLocationType>
    </benefitSpecificationLocationTypeList>
    <benefitSpecificationModifierList>
      <benefitSpecificationModifier
        code
      />
    </benefitSpecificationModifierList>
    <benefitSpecificationSpecialtyList>
      <benefitSpecificationSpecialty
       code
      />
    </benefitSpecificationSpecialtyList>
  </benefitSpecification>
</benefitSpecifications>

Data File Type PRODUCTS

Data files of this type contain only <products>

<products>
  <product
    elementId
    uuid // UUID of the product
    code
    description
    aggregationLevel
    priorityCode
    productLineCode
    productFamilyCode
    fundingArrangementCode
    brandCode
    currencyCode
    buildNumber
  >
    <productProviderGroupList/>
    <productBenefitSpecificationList/>
    <productLimitList/>
  </product>
</products>

Product provider grouplist are structured as follows:

<productProviderGroupList>
  <productProviderGroup
    providerGroupCode
    assignmentLabel
    startDate
    endDate
  />
</productProviderGroupList>

Product limits are structured as follows:

<productLimitList>
  <productLimit
    limitCode
    renewalReference
    renewalPeriodLength
    renewalPeriodUnitOfMeasure
    carryOverPeriodLength
    carryOverPeriodUnitOfMeasure
    otherProductsCarryOverPeriodLength
    otherProductsCarryOverPeriodUnitOfMeasure
    startDate
    endDate
  />
</productLimitList>

Product benefit specifications within the <product> element are structured as follows

<productBenefitSpecificationList>
  <productBenefitSpecification
    uuid
    benefitSpecificationCode
    startDate
    endDate
  >
    <productBenefitSpecificationLimitList>
      <productBenefitSpecificationLimit
        limitCode
        aliasCode
        displayName
        maximumNumber
        maximumServiceDays
        coverWithholdCategoryCode
        reachedAction
        excludeFromCarryOver
        startDate
        endDate
      >
        <maximumAmount
          currency
          value
        />
      </productBenefitSpecificationLimit>
    </productBenefitSpecificationLimitList>
    <productBenefitSpecificationValueList>
      <productBenefitSpecificationValue
        coverWithholdCategoryCode
        aliasCode
        displayName
        percentage
        startDate
        endDate
      >
        <coverWithholdAmount
          currency
          value
        />
      </productBenefitSpecificationValue>
    </productBenefitSpecificationValueList>
    <productBenefitSpecificationReinsuranceList>
      <productBenefitSpecificationReinsurance
        aliasCode
        displayName
        startDate
        endDate
      >
      </productBenefitSpecificationReinsurance>
    </productBenefitSpecificationReinsuranceList>
  </productBenefitSpecification>
</productBenefitSpecificationList>

Processing a Request

Taking into account the interdependence between the elements in the payload, they are processed the following sequence:

  1. Product Setup

    • Creation and updates of country region grouplist

    • Creation and updates of benefit priorities

    • Remove

  2. Benefit Specifications

    • Creation and updates of benefit specifications

  3. Products

    • Creation and updates of products

Creation and Updates of Country Region Groups

Each <countryRegionGroup> is processed as a separate transaction. This means that if the creation or update of the group fails, no database changes are committed for that group and the processing continues with the next <countryRegionGroup> element.

The last step is to add the country region group details to the (either updated or newly created) group.

Adding a detail to a country region group can fail because the country region cannot be found or is deactivated. This leads to the following errors:

Table 1. Creation and Updates of Country Region Groups
Code Sev Message

GEN-RULE-001

Fatal

It is not possible to link with inactive {0} for: country region

RCL-IP-PRBS-036

Fatal

Country region {code} for country {code} is unknown

RCL-IP-PRBS-059

Fatal

Country {code} is unknown

Creation and Updates of Benefit Priorities

Each <benefitPriority> is processed as a separate transaction.

Creation and Updates of Benefit Specifications

Each <benefitSpecification> is processed as a separate transaction. This means:

  • If the creation or update of the benefit specification fails, no database changes are committed for that element. But processing continues with the next <benefitSpecification> element.

  • In case of an update, the benefit specification fields are updated according to the values in the <benefitSpecification> element.

    • If an attribute is not specified in the <benefitSpecification> element, the existing value is retained.

The following situations cause the insert or update of a single <benefitSpecification> element to fail:

Table 2. Creation and Updates of Benefit Specifications
Code Sev Message

GEN-RULE-001

Fatal

It is not possible to link with inactive {0}

for: country region, coverage regime, authorization regime, waiting period regime, post benefits regime, case definition

RCL-IP-PRBS-002

Fatal

Regime {code} is unknown

RCL-IP-PRBS-031

Fatal

Country region group {code} is unknown

RCL-IP-PRBS-007

Fatal

Procedure group code {code} is unknown

RCL-IP-PRBS-006

Fatal

Diagnosis group code {code} is unknown

RCL-IP-PRBS-066

Fatal

Diagnosis type code {code} is unknown

RCL-IP-PRBS-004

Fatal

Case definition {code} is unknown

RCL-IP-PRBS-019

Fatal

Benefit priority {code} is unknown

RCL-IP-PRBS-064

Fatal

Claim form type {code} is unknown

Violation of the business rules on benefit specification, such as:

  • specifying both a procedure group and a procedure condition.

  • age from should not be larger than age to

  • diagnosis Group scope does not have a valid value ("I"or "N")

  • reference code is not accompanied by a transaction source code

  • dynamic fields cannot be processed

are handled by the standard business rule handling.

If a <conditions> element is specified, then all existing benefit specification conditions are removed. A condition is added for each <benefitSpecificationDynamicLogic> element. Adding a condition can fail because the dynamic logic condition cannot be found.

Table 3. Adding a <conditions> Element
Code Sev Message

RCL-IP-PRBS-001

Fatal

The condition {code} is unknown

If a <benefitSpecificationProviderGroupList> element is specified, then all existing benefit specification provider groups are removed. A benefit specification provider group is added for each <benefitSpecificationProviderGroup> element. Adding a provider group can fail because the group cannot be found.

Table 4. Adding a <benefitSpecificationProviderGroupList> Element
Code Sev Message

RCL-IP-PRBS-008

Fatal

Provider group code {code} is unknown

If a <benefitSpecificationLocationTypeList> element is specified, then all existing benefit specification location types are removed. A benefit specification location type is added for each <benefitSpecificationLocationType> element. Adding a location type can fail if the system either cannot find or cannot uniquely identify the appropriate location type.

Table 5. Adding a <benefitSpecificationLocationTypeList> Element
Code Sev Message

RCL-IP-PRBS-060

Fatal

The combination of location type {code} and claim form type {code} is unknown

RCL-IP-PRBS-061

Fatal

Location type {code} cannot be uniquely identified

The modifier list and benefitspecificationspeciality list apply a simpler matching pattern, because their code attribute is unique.

Table 6. Unique Code Attribute
Code Sev Message

RCL-IP-PRBS-062

Fatal

The modifier {code} is unknown

RCL-IP-PRBS-063

Fatal

The specialty {code} is unknown

Creation and Updates of Products

Each <product> is processed as a separate transaction. That means that if the creation or update of the product including its details elements <underwriter>, <provider group> and <product limit> fails, no database changes are committed for that element, but processing continues with the next <product> element.

In case of an update, the product fields are updated according to the values in the <product> element. If an attribute is not specified in the <product> element, the existing value is retained. In case a new product is created, the fields are set to the values specified in the <product> element.

Currency

A product always has a steering currency. This currency is used for product limits, product benefit specification limits and benefit specification values whenever an amount is specified. That’s why only the steering currency can be sent in, while the amount elements in product limits, product benefit specification limits and benefit specification values lack the possibility of specifying a currency.

Processing the <product> element fails when the product priority code or the brand code is unknown:

Table 7. Currency
Code Sev Message

RCL-IP-PRBS-018

Fatal

Product priority {code} is unknown

RCL-IP-PRBS-009

Fatal

Brand {code} is unknown

RCL-IP-PRBS-027

Fatal

Product line {code} is unknown.

RCL-IP-PRBS-028

Fatal

Funding arrangement {code} is unknown.

RCL-IP-PRBS-058

Fatal

Product family {code} is unknown.

Product Provider Groups and Product Limits

Processing the <productProviderGroupList> element fails when a provider group code is unknown. Processing the <productLimitList> element fails when a limit code is unknown. If processing of one of these three product sub elements fails, the processing of the <product> element fails.

Table 8. Product Provider Groups and Product Limits
Code Sev Message

RCL-IP-PRBS-012

Fatal

Limit code {code} is unknown

RCL-IP-PRBS-008

Fatal

Provider group code {code} is unknown

Product Benefit Specifications

Before starting on the payload the system marks all product benefit specification in the product for deletion. As it processes each of the product benefit specifications from the payload, the system attempts to match to one of the existing product benefit specifications:

  • If the match succeeds, that product benefit specification is updated with the information from the payload and it is unmarked for deletion.

  • If the match fails, the information in the payload is used to create a new product benefit specification

A successful match requires that the product code, benefit specification code and the product benefit specification start date are the same.

If the benefit specification code from the payload is unknown the system raises the error:

Table 9. Product Benefit Specifications
Code Sev Message

RCL-IP-PRBS-005

Fatal

Benefit specification code {code} is unknown

When a match succeeds and the product benefit specification is updated. Product benefit specification fields and and details that are not included in the payload are cleared and discarded; note that this is different from the usual update pattern for Oracle Health Insurance integration points.

Once all product benefit specifications in the payload have been processed, the ones that are still marked for deletion are discarded. If this is not possible (e.g. because it has been applied to a claim) then the product benefit specification is disabled instead.

Currency

A product always has a steering currency. This currency is used for product benefit specification limits and benefit specification values whenever an amount is specified. That’s why product benefit specification limits and benefit specification values lack the possibility of specifying a currency, they just inherit the steering currency of the (already existing) existing product.

Response

As is described in Long Running Operations through REST there are multiple ways in which one can get the response/result of this long running operation. Typically though one would opt for using notification events.

A notification message can be sent out to a pre-configured endpoint. The notification endpoint can be configured on 'ohi.activityprocessing.notification.endpoint.PRODUCT_IMPORT' or to a more generic endpoint: ohi.activityprocessing.notification.endpoint.

If the notification endpoint is configured on the specific: PRODUCT_IMPORT, all other related properties like media type, authentication, etc. are also fetched based on PRODUCT_IMPORT, or else defaults are used. Similarly, if the endpoint for the notification is configured without the specific code, then all other properties are fetched on a generic use case code 'ActivityNotificationClient'. Please see section "Outbound RESTful Service Invocations" in Security Guide for the process and more properties.

The notification message has the common notification structure as described in the chapter "Long Running Operations through REST" in the Security Guide.

The response notification includes a data file set link of the completed productbenefitspecification request. This enables an integration pattern that relies on polling progress which allows the user to perform a collection queries over productbenefitspecification resources.

The response datafile set contains the response of the corresponding datafiles that are sent in the request, i.e, each data file in the request maps to one data file in the response.

The country region response is structured as follows:

<countryRegionGroups>
  <countryRegion
    elementId
    code
  >
    <resultMessages/>
  </countryRegionGroup>
</countryRegionGroups>

The benefit priorities response is structured as follows:

<benefitPriorities>
  <benefitPriority
    elementId
    code
  >
    <resultMessages/>
  </benefitPriority>
</benefitPriorities>

The benefit specifications response is structured as follows:

<benefitSpecifications>
 <benefitSpecification
    elementId
    code
  >
    <resultMessages/>
  </benefitSpecification>
<benefitSpecifications>

The products response is structured as follows:

<products>
 <product
    elementId
    code
  >
    <resultMessages/>
  </product>
<products>

Authorization

A grant for access restriction 'Product Benefit Specification IP' must be provided to be able to initiate this operation.

Error Messages

The following error messages that are specific to the product benefit specification interface may be returned in the response messages

Table 10. Error Messages
Code Sev Message

CLA-HTTP-010

Fatal

Data file set code {code} is unknown

RCL-IP-PRBS-069

Fatal

Type code {code} is unknown