Policy In Integration Point

This web service supports the creation and maintenance of policies. It accepts either an online request for a single policy, or a data file for a set of policies. To process a file with policies, the data file has to uploaded by the data file set web service first.

Note: This web service does not support the removal or cancellation of a policy.

Online Request Message

The HTTP PUT request to: http://[hostName]:[portNumber]/[api-context-root]/policies enables external systems to create/update policies. Each request message contains the details of a single policy. The system accepts the request in the following format:

<policy
  code=""
  brandCode=""
  dataAccessGroupCode=""
  lineOfBusinessCode=""
  calculateOnCancellation=""
 >
  <policyholderList>
    <policyholder
      startDate=""
      endDate=""
    />
        <person
         correlationKey=""
        >
  <assignedProviderList>
    <assignedProvider
      providerAssignmentTypeCode=""
      startDate=""
      endDate=""
       >
      <provider
        code=""
        flexCodeDefinitionCode=""
      />
    </assignedProvider>
  </assignedProviderList>
    </policyholder>
  </policyholderList>
  <policyGroupAccountList>
    <policyGroupAccount
      groupAccountCode=""
      startDate=""
      endDate=""
    />
  </policyGroupAccountList>
  <policyBillingAccountList>
    <policyBillingAccount
      code=""
      descr=""
      billingContact=""
      default=""
    />
  </policyBillingAccountList>
  <policyCollectionSettingList>
    <policyCollectionSetting
      advanceLength=""
      advanceUom=""
      startDate=""
      spanReferenceDate=""
      endDate=""
      policyCalculationPeriods=""
      calculationPeriodLength=""
      calculationPeriodUom=""
      collectionMethodCode=""
    />
  </policyCollectionSettingList>
  <policyPremiumBillAllocationList>
    <policyPremiumBillAllocation
      scheduleDefinitionCode=""
      premiumScheduleTypeCode=""
      addOnCode=""
      enrollmentProductCode=""
      enrollmentProductCategoryCode=""
      insurableClassCode=""
      startDate=""
      endDate=""
      active=""
    >
      <policyBillReceiverList>
        <policyBillReceiver
          relationCode=""
          billingAccountCode=""
          percentage=""
        />
      </policyBillReceiverList>
    </policyPremiumBillAllocation>
  </policyPremiumBillAllocationList>
  <policyContractPeriodList>
    <policyContractPeriod
      startDate=""
      referenceDate=""
      endDate=""
    />
  </policyContractPeriodList>
  <policyBrokerAgentList>
    <policyBrokerAgent
      brokerCode=""
      agentCode=""
      startDate=""
      endDate=""
    />
  </policyBrokerAgentList>
  <policyEnrollmentList>
    <policyEnrollment
      enrollmentTypeCode=""
     />
      <!--either of the below-->
      <policyEnrollmentInsurableClassList>
        <policyEnrollmentInsurableClass
           insurableClassCode=""
           startDate=""
           endDate=""
        />
      </policyEnrollmentInsurableClassList>
      <policyEnrollmentProductList>
        <policyEnrollmentProduct
          enrollmentProductCode=""
          commission=""
          commissionAmountInterpretation=""
          commissionNumberOfDays=""
          startDate=""
          endDate=""
        />
          <premiumAmount
            currency="">
            {value}
          </premiumAmount>
          <commissionAmount
            currency="">
            {value}
          </commissionAmount>
          <parameterValueList>
            <parameterValue
              parameterAliasCode=""
              percentage=""
              number=""
              serviceDays=""
              startDate=""
              endDate=""
            >
              <parameterAmount
                currency="">
                {value}
              </parameterAmount>
            </parameterValue>
          </parameterValueList>
          <policyAddOnList>
            <policyAddOn
              addOnCode=""
              startDate=""
              endDate="">
            </policyAddOn>
          </policyAddOnList>
        />
      </policyEnrollmentProductList>
    <policyEnrollment/>
  </policyEnrollmentList>
 <attachedPolicyData
    manual=""
    ignoreBulkUpdate=""
    datePaidTo=""
  lastProcessedMessageActivityID=""
   />
</policy>

Each <policyEnrollment> must specify either an <insurablePerson> or an <insurableObject>. Which of the two depends on the policy’s line of business.

The line of business of the enrollment product in the <policyEnrollmentProduct> must match the policy’s line of business.

Information in the <attachedPolicyData> is used to update the attached policy data record.

Note: Only a user with access grant to Date Paid To restriction can update the field 'datePaidTo' on the attached data.

Submit for Processing

This request enables an external system to save or save-and-submit a policy. The URI that is used determines how the system processes the request. Use URI:

/policies to save the policy but not submit it yet
/policies/submit to save the policy and immediately submit it

If the save-and-submit URI is used, the policy is submitted for processing immediately after creation or update. See Process Policy for a detailed description of the processing flow.

Matching

The policy code drives whether a policy is created, or an existing policy is updated. If the policy code does not exist, then a new policy with the provided policy code is added to the system. If the policy code exists then the policy details are updated as per the data provided in the request. If the policy code is not specified then the policy is considered to be a new enrollment, and a code is generated by the system using the dynamic logic function with the signature 'Policy Code Generation'. If this is not configured then the policy id is assigned to policy code. If multiple policies with the same code exist a fatal message is raised (see Error Messages section).

Creating Policies

For details on how values in the request messages are handled when a policy is created, refer to the concepts in the Integration Guide.

Currency

If a premium amount and/or commission amount for a policy enrollment product is specified without the currency, the currency (on the policy enrollment product) is set to the premium currency of the related enrollment product. If a parameter amount for a parameter value is specified without the currency, the currency (on the parameter value) is set to the parameter currency of the related enrollment product.

Updating Policies

If a policy code exists then the policy is updated as per the data provided in the request.

Attribute Handling

When a policy is updated, single value attributes are handled as specified in the 'Property Representation and Handling' section in the HTTP API/IP Concepts part of the integration guide. Details are handled in a different way than the standard replacing mechanism, because updates to details may require a recalculation of premium, a new output document or a new fee as described in the Change Events implementation guide.

Instead of replacing the entire list of details when a policy 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:

Policyholders: matched on person code and start date
Policy Contract Periods: matched on start date
Policy Billing Accounts: matched on code
Policy Collection Settings: matched on start date
Policy Premium Bill Allocations: matched on insurable class code, add-on code, schedule definition code, premium schedule type code, enrollment product code, enrollment product category code and start date
Policy Bill Receivers: matched on policy premium bill allocation (see above), relation code and billing account code
Policy Brokers Agents: matched on start date
Policy Group Accounts: matched on group account code and start date
Policy Insurable Classes: matched on insurable class code and start date
Policy Enrollments:
- When the policy enrollment is for a person: matched on person code or relation identifier
- When the policy enrollment is for an object: matched on object code and object type
Policy Enrollment Products:
- When the policy does not belong to a group account: matched on enrollment product code and start date
- When the policy belongs to a group account: matched on enrollment product code of the related group account product and start date
Policy Add-ons: matched on policy enrollment product (see above), add-on code and start date
Parameter Values: matched on policy enrollment product (see above), parameter alias code and start date. If a policy enrollment product is created or updated, the line of business of the enrollment product should have a reference to the insurable entity type of the person or object enrolled. Note that a single line of business can refer to multiple insurable entity types.

Currency

If a new policy enrollment product or parameter value is inserted, the currency is set in the same way as specified in the Creating Policies section.

If an existing policy enrollment product that did not specify a premium amount is updated (premium amount is specified without the currency in the request), the currency (on the policy enrollment product) is set to the premium currency of the related enrollment product. If an existing policy enrollment product that did specify a premium amount is updated (premium amount is specified without the currency in the request), the currency (on the policy enrollment product) is set to the premium currency of the related enrollment product. To nullify the premium amount and the currency, an empty <premiumAmount> element has to be specified in the request.

If an existing parameter value for a parameter alias of type amount is updated (parameter amount is specified without the currency in the request), the currency (on the parameter value) is set to the premium currency of the related enrollment product.

Statuses

Policies can have different statuses. A description of the possible statuses of a policy (including the possible status transitions) can be found in the 'Policy Statuses' section in the Policies part of the implementation guide. What happens when a policy is updated differs per status:

Edit

Any policy messages and policy pend reasons are removed. Note that the pend reasons are not resolved in the policy pend history. The policy is updated (as specified in the 'Attribute Handling' section) and saved. If the '/policies/submit' URI is used the policy is also afterwards submitted for processing.

In Process

Any technical errors related to the processing flow are resolved. Any policy messages and policy pend reasons are removed. Note that the pend reasons are not resolved in the policy pend history. The status of the policy is changed to Edit and a policy status history record for the Edit status is created. In the Edit status the policy is updated (as specified in the 'Attribute Handling' section) and saved. If the '/policies/submit' URI is used the policy is also afterwards submitted for processing.

Pended

Any policy messages are removed. The policy pend reasons are removed. Note that they are not resolved in the policy pend history. The status of the policy is changed to Edit and a policy status history record for the Edit status is created. In the Edit status the policy is updated (as specified in the 'Attribute Handling' section) and saved. If the '/policies/submit' URI is used the policy is also afterwards submitted for processing.

Approved and Canceled

A new version of the policy is created with the Edit status and a policy status history record for the Edit status is created. The new version is a copy of the current version including its dynamic fields, dynamic records and the following details (including their dynamic fields and dynamic records):

Policyholders
Policy Contract Periods
Policy Collection Settings
Policy Premium Bill Allocations
Policy Bill Receivers
Policy Brokers Agents
Policy Group Accounts
Policy Enrollments
Policy Enrollment Products
Policy Insurable Classes
Policy Add-ons
Parameter Values (belonging to Policy Enrollment Products)

In the Edit status the policy is updated (as specified in the 'Attribute Handling' section) and saved. Note that the policy billing accounts are not copied, because they apply across the versions of a policy. If the '/policies/submit' URI is used the policy is also afterwards submitted for processing.

Dynamic Fields and Dynamic Records

A given implementation of the OHI application could have dynamic fields and dynamic records added to the policy 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 OHI application, refer to the 'Property Representation and Handling' section in the HTTP API/IP Concepts part of the integration guide.

As with other child entities in this integration point, the dynamic records and dynamic fields will not be deleted and re-inserted, but will be updated based on matching. Horizontal dynamic fields will be matched on the name of the dynamic field. Vertical dynamic fields and dynamic records will be matched on the data, if it is exactly the same, it will not be deleted and inserted. If there is a mismatch of data for the same usage name, the data for that usage name will be deleted and inserted.

Insurable Entities

This integration point also enrolls persons and objects that are new to the system.

Persons

The new person’s details have to be specified in the request. Refer to the 'Person' section in the Relation Integration Point part of the integration guide for the detail structure for the element person. The system detects a person as a new person if the specified person code does not exist. The system also detects a person as a new person if the specified person code is empty in the request. In that case a person code is generated using dynamic logic function with the signature 'Person Code Generation'. If no dynamic logic function with the signature 'Person Code Generation' exists, id will be assigned to person code.

This integration point takes in both relations and assigned providers. If the relation or provider that is being sent in does not match on the code then the enabled identifiers are used for matching. Thus, enabling the system to recognize if it is the same relation or provider. A relation or a provider can have multiple identifiers that are stored in the Oracle Health Insurance system. The identifiers could be of any type for example policy enrollment number, social security number or drivers license number etc. The user needs to have access to the identifier type in order for the identifiers to be applied during matching.

It is possible to update a subset of attributes on an existing person record by specifying only those attributes in the request message. The attribute handling for the person follows the same mechanism as described in the Relation Integration Point part of the integration guide.

A correlation key is used in the following manner to relate a member and a Policyholder. If the policyholder and a member is the same person and this person is new to the system, the person in the policyholder element and the person in the policy enrollment element must have the same person code in the request. If the person codes are left empty, with the purpose to have them generated by the system, a correlation key must be used. By adding the same correlation key to the policyholder person and to the policy enrollment person, they are recognized as being the same person. The system will create only one person who is the policyholder as well as a member on the policy. If both person codes and correlation keys are used, then matching the policyholder and the member on person codes prevails above matching on correlation key.

Matching on correlation key is only used for new persons where the request holds no person code. Correlation keys will be ignored for person updates and are not available for enrollment of insured entities that are not persons.

Objects

The new object’s details have to be specified in the request. The system detects an object as a new object if the specified object code in combination with the entity type code does not exist. If the object code is left empty a fatal message will be raised.

It is possible to update a subset of attributes on an existing object record by specifying only those attributes in the request message. The attribute handling for the object follows the standards as described in the 'Property Representation and Handling' section in the HTTP API/IP Concepts part of the integration guide.

Authorization

A grant for access restriction 'Policy In IP' must be provided to be able to initiate this operation.

Response Message

Response messages are created by the Oracle Health Insurance application in response to request messages received from external interfaces. Please refer to the 'Response Messages' section in the HTTP API/IP Concepts part of the integration guide for more details.

File Request

This request enables the handling of multiple policies in one go. Because this service supports requests with significant volume, it relies on the data file set web service to import the policies payload into the application before it reads and processes the data. For more information about how to create a data file set please refer to Data File Set Integration Point

Each data file has <policies> as its root element. This data file has the following structure:

<policies>
   <policy
     code=""
     elementId=""
   >
</policies>

The metadata for the above structure is accessible on the /[api-context-root]/writepolicies/payload/definition as swagger definition.

In the remainder of this description we assume that an input data file set containing at least one datafile with a structure as was outlined above has been created. To start the policies import process, submit a HTTP POST request to http://[hostName]:[portNumber]/[api-context-root]/writepolicies.

A write policies batch (initiation) request has the following structure:

{
 "dataFileSetCode" : "...",
 "submit" : "..."
 "responseDataFileSetCode" : "..."
 }

The response data file set holds the results of the file payload.The responseDataFileSetCode is an optional attribute.

The submit flag in the payload determines how the file request gets processed. When the submit flag is set to "true" the policies are both imported and submitted and if it is set to "false" the policies get only imported but not submitted.

Note

The submit flag is set to "false" by default.
The batch process does not wait for the submit process to complete, but only triggers it.

File Processing Mechanism

For more specifics of how the policies are updated refer to the "Submit For Processing" section above.

Authorization

A grant for access restriction 'policies batch IP’ ' must be provided to be able to initiate this operation.

File Response

There are several ways to track the progress of the import process. The typical approach is to subscribe to a notification event.

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

If the notification endpoint is configured on the specific: POLICY_IMPORT, all other related properties like media type, authentication, etc. are also fetched based on POLICY_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 Integration 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 Integration Guide.

The response notification includes a data file set link of the completed writepolicies request and it contains messages (fatal/info) for each policy that is imported.

The system responds with HTTP 201 (Created) and a location header for the long running operation.

The response data file set holds data files containing the result of the policies with the following mock XML structure:

<policiesResponse>
   <resultMessages result="S">
    <resultMessage code="GEN-FILE-006"> The total number of successfully processed records is 4
   </resultMessage>
 </resultMessages>
<resultMessages result="F" elementId="1">
     <resultMessage code="GEN-FIEL-002"> The field flex1 with code fcX and flexCodeDefCode SIMP could not be resolved
    </resultMessage>
 </resultMessages>
</policiesResponse>

Notes

The <policiesResponse> element contains one or more policies. Each policy is identified by the code if specified in the payload , if not the element ID is used and if both are not specified then NO_Key. Each policy contains one or more messages which relate to that particular policy. The response only contains <policy> elements for those policies that actually generated error/info messages during processing.

Error Messages

The following error messages that are specific to the policies interface may be returned in the response messages:

Code	Severity	Message
POL-IP-POLI-001	Fatal	Brand code {code} is unknown
POL-IP-POLI-002	Fatal	Data access group code {code} is unknown
POL-IP-POLI-003	Fatal	Group account code {code} is unknown
POL-IP-POLI-005	Fatal	Insurable entity code {code} is unknown and there are not enough attributes specified to create a new {usageName}
POL-IP-POLI-006	Fatal	Enrollment product code {code} is unknown
POL-IP-POLI-007	Fatal	Parameter alias code {code} is unknown
POL-IP-POLI-008	Fatal	Add-on code {code} is unknown
POL-IP-POLI-018	Fatal	Group account with code {code} does not have a group account product with code {code}
POL-IP-POLI-019	Fatal	Multiple policies exist with the same code
POL-IP-POLI-021	Fatal	Broker code {code} is unknown
POL-IP-POLI-022	Fatal	Agent code {code} is unknown
POL-IP-POLI-023	Fatal	Relation code {code} is unknown
POL-IP-POLI-024	Fatal	Insurable entity type code {code} is unknown for the policy’s line of business with code {code}
POL-IP-POLI-025	Fatal	Line of business of enrollment product {code} does not match the policy’s line of business with code {code}
POL-IP-POLI-026	Fatal	Line of business {code} is unknown
POL-IP-POLI-027	Fatal	Unresolved pend reasons exist and you don’t have the privileges to resolve them
POL-IP-POLI-028	Fatal	Policy in status {status} cannot be submitted
POL-IP-POLI-029	Fatal	Insurable class code {code} is unknown
POL-IP-POLI-030	Fatal	Schedule definition code {code} is unknown
POL-IP-POLI-031	Fatal	Premium schedule type code {code} is unknown
POL-IP-POLI-032	Fatal	Enrollment product category code {code} is unknown
POL-IP-POLI-033	Fatal	Enrollment type code {code} is unknown
POL-IP-POLI-034	Fatal	Billing account code {code} is unknown
POL-IP-POLI-035	Fatal	Collection method {code} is unknown
POL-HTTP-010	Fatal	Data file set code {code} is unknown

Code

Severity

Message

POL-IP-POLI-001

Fatal

Brand code {code} is unknown

POL-IP-POLI-002

Fatal

Data access group code {code} is unknown

POL-IP-POLI-003

Fatal

Group account code {code} is unknown

POL-IP-POLI-005

Fatal

Insurable entity code {code} is unknown and there are not enough attributes specified to create a new {usageName}

POL-IP-POLI-006

Fatal

Enrollment product code {code} is unknown

POL-IP-POLI-007

Fatal

Parameter alias code {code} is unknown

POL-IP-POLI-008

Fatal

Add-on code {code} is unknown

POL-IP-POLI-018

Fatal

Group account with code {code} does not have a group account product with code {code}

POL-IP-POLI-019

Fatal

Multiple policies exist with the same code

POL-IP-POLI-021

Fatal

Broker code {code} is unknown

POL-IP-POLI-022

Fatal

Agent code {code} is unknown

POL-IP-POLI-023

Fatal

Relation code {code} is unknown

POL-IP-POLI-024

Fatal

Insurable entity type code {code} is unknown for the policy’s line of business with code {code}

POL-IP-POLI-025

Fatal

Line of business of enrollment product {code} does not match the policy’s line of business with code {code}

POL-IP-POLI-026

Fatal

Line of business {code} is unknown

POL-IP-POLI-027

Fatal

Unresolved pend reasons exist and you don’t have the privileges to resolve them

POL-IP-POLI-028

Fatal

Policy in status {status} cannot be submitted

POL-IP-POLI-029

Fatal

Insurable class code {code} is unknown

POL-IP-POLI-030

Fatal

Schedule definition code {code} is unknown

POL-IP-POLI-031

Fatal

Premium schedule type code {code} is unknown

POL-IP-POLI-032

Fatal

Enrollment product category code {code} is unknown

POL-IP-POLI-033

Fatal

Enrollment type code {code} is unknown

POL-IP-POLI-034

Fatal

Billing account code {code} is unknown

POL-IP-POLI-035

Fatal

Collection method {code} is unknown

POL-HTTP-010

Fatal

Data file set code {code} is unknown

Apart from the above error messages, the following error messages from relation interface may be returned in the response messages:

Code	Severity	Message
REL-IP-RELA-004	Fatal	Title code {code} is unknown
REL-IP-RELA-006	Fatal	Prefix code {code} is unknown
REL-IP-RELA-007	Fatal	Name format code {code} is unknown
REL-IP-RELA-008	Fatal	Language code {code} is unknown
REL-IP-RELA-009	Fatal	Country code {code} is unknown
REL-IP-RELA-010	Fatal	Bank code {code} is unknown
REL-IP-RELA-011	Fatal	Bank account validation code {code} is unknown
REL-IP-RELA-012	Fatal	Country region code {code} is unknown
REL-IP-RELA-015	Fatal	Provider identified by code {code} and flex code definition code {code} is unknown
REL-IP-RELA-016	Fatal	Provider assignment type code {code} is unknown
REL-IP-RELA-017	Fatal	Capitation contract code {code} is unknown

Code

Severity

Message

REL-IP-RELA-004

Fatal

Title code {code} is unknown

REL-IP-RELA-006

Fatal

Prefix code {code} is unknown

REL-IP-RELA-007

Fatal

Name format code {code} is unknown

REL-IP-RELA-008

Fatal

Language code {code} is unknown

REL-IP-RELA-009

Fatal

Country code {code} is unknown

REL-IP-RELA-010

Fatal

Bank code {code} is unknown

REL-IP-RELA-011

Fatal

Bank account validation code {code} is unknown

REL-IP-RELA-012

Fatal

Country region code {code} is unknown

REL-IP-RELA-015

Fatal

Provider identified by code {code} and flex code definition code {code} is unknown

REL-IP-RELA-016

Fatal

Provider assignment type code {code} is unknown

REL-IP-RELA-017

Fatal

Capitation contract 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 (refer to the 'Response Messages' section in the HTTP API/IP Concepts part of the integration guide).