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.
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:
-
A datafile with prefix '1' is processed first. This file contains country region groups. An example of the code of this file "1CountrRegionGroups".
-
Next is the datafile with prefix '2' containing benefit priorities. An example of the code of this file "2BenefitPriorities".
-
Then prefix '3' for benefit specifications.
-
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 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:
-
Product Setup
-
Creation and updates of country region grouplist
-
Creation and updates of benefit priorities
-
Remove
-
-
Benefit Specifications
-
Creation and updates of benefit specifications
-
-
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:
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:
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:
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.
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.
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.
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.
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:
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.
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:
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>