Group Client Integration Point
The system facilitates through this synchronous integration point the creation of a group client and its details (for example group accounts, group account products, premium bill allocations, etc.) by an external system. Through this integration point an external system can:
The path looks like this:
http://<host>:<port>/<contextRoot>/groupclients
This integration point is protected by access restriction "group clients IP".
Request Messages
Each request message may contain the details of one group client. The external interfaces will create request messages for the initial data load, in response to entry of new group clients and updates to previously sent group clients. The details of exactly what information needs to be in a given request message varies based on factors such as whether details have been sent before, and the category of details that have been added or updated.
The system accepts the request in the following format:
{
"code": "",
"descr": "",
"displayName": "",
"status": "",
"parentGroupClientCode": "",
"employerOrganizationCode": "",
"billReceiverOrganizationCode": "",
"amountDistribution": "",
"partialPeriodResolution": "",
"enrolledDaysThreshold": "",
"contactRelationCode": "",
"representativePersonCode": "",
"groupProcessFlowCode": "",
"groupClientCollectionSettingList": [
{
"advanceLength": "",
"advanceUom": "",
"spanReferenceDate": "",
"startDate": "",
"endDate": "",
"policyCalculationPeriods": "",
"calculationPeriodLength": "",
"calculationPeriodUom": "",
"collectionMethodCode":""
}
],
"groupClientBillingAccountList": [
{
"code": "",
"descr": "",
"contactRelationCode": "",
"default": ""
}
],
"groupClientBrokerAgentList": [
{
"enrollmentProductCategoryCode": "",
"brokerCode": "",
"agentCode": "",
"startDate": "",
"endDate": ""
}
],
"groupClientPremiumScheduleList": [
{
"enrollmentProductCode": "",
"enrollmentProductCategoryCode": "",
"premiumScheduleCode": "",
"addonCode":""
"startDate": "",
"endDate": ""
}
],
"groupClientAdjustmentList": [
{
"enrollmentProductCode": "",
"enrollmentProductCategoryCode": "",
"scheduleDefinitionCode": "",
"sequence": "",
"startDate": "",
"endDate": ""
}
],
"groupClientEventList": [
{
"descr": "",
"eventDateTime": "",
"policyCode": "",
"groupAccountCode": "",
}
],
"groupAccountList": [
{
"code": "",
"descr": "",
"displayName": "",
"startDate": "",
"amountDistribution": "",
"partialPeriodResolution": "",
"enrolledDaysThreshold": "",
"dataAccessGroupCode": "",
"contactRelationCode": "",
"groupAccountTimePeriodList": [
{
"displayName": "",
"startDate": "",
"endDate": ""
}
],
"groupAccountInsurableClassList": [
{
"insurableClassCode": ""
}
],
"groupAccountCollectionSettingList": [
{
"advanceLength": "",
"advanceUom": "",
"spanReferenceDate": "",
"startDate": "",
"endDate": "",
"policyCalculationPeriods": "",
"calculationPeriodLength": "",
"calculationPeriodUom": "",
"collectionMethodCode":""
}
],
"groupAccountBrokerAgentList": [
{
"enrollmentProductCategoryCode": "",
"brokerCode": "",
"agentCode": "",
"startDate": "",
"endDate": ""
}
],
"brokerAgentSwitchRuleList": [
{
"commissionExistingEnrollment": "",
"commissionNewEnrollment": "",
"thirdPartyRelationCode": "",
"startDate": "",
"endDate": ""
}
],
"groupAccountPremiumScheduleList": [
{
"enrollmentProductCategoryCode": "",
"premiumScheduleCode": "",
"addonCode":""
"startDate": "",
"endDate": ""
}
],
"groupAccountAdjustmentList": [
{
"enrollmentProductCategoryCode": "",
"scheduleDefinitionCode": "",
"sequence": "",
"startDate": "",
"endDate": ""
}
],
"groupAccountProductList": [
{
"enrollmentProductCode": "",
"displayName": "",
"displaySequence": "",
"amountDistribution": "",
"partialPeriodResolution": "",
"enrolledDaysThreshold": "",
"groupAccountProductPremiumScheduleList": [
{
"premiumScheduleCode": "",
"addonCode":""
"startDate": "",
"endDate": ""
}
],
"groupAccountProductAdjustmentList": [
{
"scheduleDefinitionCode": "",
"sequence": "",
"startDate": "",
"endDate": ""
}
],
"groupAccountProductProviderGroupList": [
{
"providerGroupCode": "",
"assignedProviderGroupLabelCode": "",
"startDate": "",
"endDate": ""
}
],
"parameterDomainList": [
{
"parameterAliasCode": "",
"discrete": "",
"numberOfUnits": "",
"percentage": "",
"serviceDays": "",
"amount": {
"value": "",
"currency: ""
},
"startDate": "",
"endDate": ""
},
"parameterDomainValueList": [
{
"default": "",
"dynamicLogicCode": "",
"numberOfUnits": "",
"percentage": "",
"serviceDays": "",
"amount": {
"value": "",
"currency": ""
}
}
]
}
],
"groupAccountAvailableProductList": [
{
"insurableClassCode": "",
"startDate": "",
"endDate": ""
}
]
}
]
}
],
"premiumBillAllocationList": [
{
"groupAccountCode": "",
"insurableClassCode": "",
"scheduleDefinitionCode": "",
"premiumScheduleTypeCode": "",
"enrollmentProductCode": "",
"enrollmentProductCategoryCode": "",
"addOnCode": "",
"startDate": "",
"endDate": "",
"active": "",
"billReceiverList": [
{
"dynamicLogicCode": "",
"groupClientBillingAccountCode": "",
"percentage": ""
}
]
}
],
"groupCommissionRateList": [
{
"groupAccountCode": "",
"enrollmentProductCode": "",
"enrollmentProductCategoryCode": "",
"brokerCode":"",
"agentCode":"",
"percentage": "",
"amountInterpretation="",
"numberOfDays="",
"amount": {
"value": "",
"currency: ""
},
"startDate": "",
"endDate": ""
}
]
}
For a description of the properties refer to the "Data Model" chapter in the Operations Guide.
Submit for Processing
This request enables an external system to save or save-and-submit a group client. The URI that is used determines how the system processes the request. Use URI:
-
/groupclients to save the group client but not submit it yet
-
/groupclients/submit to save the group client and immediately submit it
If the save-and-submit URI is used, the group client is submitted for processing immediately after creation or update. See Process Group Clients for a detailed description of the processing flow.
Dynamic Fields and Dynamic Records
A given implementation of the Oracle Health Insurance application could have dynamic fields and dynamic records added to the group client and related entities that need to be interfaced. For details on how external interfaces can provide values for dynamic fields and dynamic records in request messages and how they are handled by the Oracle Health Insurance application, refer to Property Representation and Handling (PUT, POST, PATCH).
Updating Group Clients
If a group client code exists then the group client is updated as per the data provided in the request. When a group client is updated, single value attributes are handled as specified in Property Representation and Handling (PUT, POST, PATCH). Details are handled in a different way than the standard replacing mechanism, because updates to details may require a recalculation of premium, or a new output document as described in the "Change Events" chapter of the configuration guide.
The group client status can only be set from Approved to Changed. To change the status from Changed to Approved submit the 'Process group client' operation for this group client'.
Instead of replacing the entire list of details when a group client is updated, the details in the request message are matched with the existing details on specific attributes (see below). Existing details that match with details in the request are updated (only if there is a change), details in the request that do not match with existing details are inserted and existing details that do not match with details in the request are deleted. If the list element is not included, no changes to current details are made. If an empty list element is included, all current detail records are removed. This applies to the following lists of details:
-
Group Client Level
-
Group Client Collection Settings: matched on start date
-
Group Client Brokers Agents: matched on enrollment product category code and start date
-
Group Client Premium Schedules: matched on enrollment product category code, enrollment product code, add-on-code, premium schedule code and start date
-
Group Client Adjustments: matched on enrollment product category code, enrollment product code, schedule definition code and start date
-
Premium Bill Allocations: matched on group account code, insurable class code, add-on code, schedule definition code, premium schedule type code, enrollment product code, enrollment product category code and start date
-
Bill Receivers: matched on premium bill allocation (see above), dynamic logic code and group client billing account code
-
-
Group Commission Rates: matched on group account code, enrollment product code, enrollment product category code, broker code, agent code and start date
-
Group Client Billing Account: matched on contact relation code
-
-
Group Account Level
-
Group Account Time Periods: matched on group account (see above) and start date
-
Group Account Insurable Classes: matched on group account (see above) and insurable class code
-
Group Account Collection Settings: matched on group account (see above) and start date
-
Group Account Brokers Agents: matched on group account (see above), enrollment product category code and start date
-
Broker Agent Switch Rules: matched on group account (see above) and start date
-
Group Account Premium Schedules: matched on group account (see above), enrollment product category code, add-on code, premium schedule code and start date
-
Group Account Adjustments: matched on group account (see above), enrollment product category code, schedule definition code and start date
-
Group Account Products: matched on group account (see above) and enrollment product code
-
Group Account Contact Relation: matched on contact relation code
-
-
Group Account Product Level
-
Group Account Product Premium Schedules: matched on group account product (see above), add-on code, premium schedule code and start date
-
Group Account Product Adjustments: matched on group account product (see above), schedule definition code and start date
-
Group Account Product Provider Groups: matched on group account product (see above), provider group code, assigned provider group label code and start date
-
Parameter Domains: matched on group account product (see above) and parameter alias code
-
Parameter Domain Values: matched on parameter domain (see above), start date, amount value, number of units, percentage and service days (only one the last four can have a value),
-
-
Group Account Available Products: matched on group account product (see above) and group account time period start date
-
Group Client Event details in the request are always inserted. There is no matching on existing records. If the same request is send in twice, the group client events will be inserted twice. Existing records will not be deleted if they don’t exist in the request. Only if an empty list is included, all current group client event detail records will be removed.
Group Client Messages cannot be added, updated or removed by this integration point.
Response Messages
This integration point will provide HTTP status codes as defined in Response Messages. If an error occurs, the appropriate HTTP status code is returned, and a notification is sent containing error details. The following error messages that are specific to the group client interface may be returned in the response messages:
Code | Severity | Message |
---|---|---|
POL-IP-GROC-001 |
Fatal |
Group client code {code} is unknown |
POL-IP-GROC-002 |
Fatal |
Organization code {code} is unknown |
POL-IP-GROC-003 |
Fatal |
Broker code {code} is unknown |
POL-IP-GROC-004 |
Fatal |
Agent code {code} is unknown |
POL-IP-GROC-005 |
Fatal |
Enrollment product category code {code} is unknown |
POL-IP-GROC-006 |
Fatal |
Enrollment product code {code} is unknown |
POL-IP-GROC-007 |
Fatal |
Premium schedule code {code} is unknown |
POL-IP-GROC-008 |
Fatal |
Schedule definition code {code} is unknown |
POL-IP-GROC-009 |
Fatal |
Data access group code {code} is unknown |
POL-IP-GROC-010 |
Fatal |
Insurable class code {code} is unknown |
POL-IP-GROC-011 |
Fatal |
Provider group code {code} is unknown |
POL-IP-GROC-012 |
Fatal |
Assigned provider group label code {code} is unknown |
POL-IP-GROC-013 |
Fatal |
Parameter alias code {code} is unknown |
POL-IP-GROC-014 |
Fatal |
Dynamic logic code {code} is unknown |
POL-IP-GROC-015 |
Fatal |
Group account time period start date {start date} is unknown |
POL-IP-GROC-016 |
Fatal |
Group account code {code} is unknown |
POL-IP-GROC-017 |
Fatal |
Premium schedule type code {code} is unknown |
POL-IP-GROC-018 |
Fatal |
Add-on code {code} is unknown |
POL-IP-GROC-019 |
Fatal |
Group client billing account code {code} is unknown |
POL-IP-GROC-020 |
Fatal |
Third party relation code {code} is unknown |
POL-IP-GROC-021 |
Fatal |
Collection method code {code} is unknown |
POL-IP-GROC-022 |
Fatal |
Contact relation {code} is unknown |
POL-IP-GROC-023 |
Fatal |
Group representative {code} is unknown |
POL-IP-GROC-024 |
Fatal |
Process flow code {code} is unknown |
POL-IP-GROC-025 |
Fatal |
Line of business code {code} is unknown |
In addition, functional business rule messages may be returned as well as the standard messages related to dynamic fields and dynamic records. See also Response Messages. .