Run Calculation and Produce Invoice for a Policy

The process from calculation of an approved policy to the production of an invoice consists of separate steps. It is always convenient to have a way to execute several steps in one go rather than one by one. When a payer provides a portal to individuals or group accounts, it becomes necessary rather than just convenient because otherwise a lot of conversation back and forth would be obligatory.

The complete process of a member enrolling online could look like this:

  • an interested individual goes through the menu of options on the payer’s website and confirms the choices made

  • the policy is created, submitted and approved in Oracle Health Insurance

  • the member initiates the obligation to pay from the portal

  • Oracle Health Insurance calculates the premium and produces an invoice which is sent to the portal

  • the member pays which is reflected in the financial back end system

A similar use case can exist for a policy that is already longer in the system, where the member makes some changes in the portal - for example, adding an enrollment product. After the change is submitted and approved in Oracle Health Insurance, the same need can arise to initiate the obligation to pay and receive the invoice from Oracle Health Insurance after (re)calculation.

The process from calculation up to and including the production of an invoice is thus restricted to a single approved policy. It consists of the following sub steps:

  • calculate premium for a particular policy

The calculation of commission is embedded in the premium calculation as a percentage of the policy enrollment product premium and policy add-on premium. That’s why the commission calculation also takes place, but the result can be sent to a different endpoint than the result of the premium calculation.

  • select financial transactions into a set

  • supersede financial transactions

  • generate financial message (XML format)

The first sub step is described in detail in the Operations Guide for Premium Calculation while the subsequent sub steps are described in detail in the Operations Guide for Financial.

If the Currency Conversion (Billing or Commission) function dynamic logic exists, it will do the conversion as specified in the function. If the function does not find an exchange rate, technical error GEN-CURR-002 is thrown (see the "Dynamic Logic" chapter in the Developer Guide for more information).

Resource Representation

Only approved policies (last approved version) are eligible for being processed. If the policy is for a group account, then the group account’s group client must have the status Approved for the policy to be eligible for processing. Whether a policy can be processed or not, can be derived by the presence or absence of the "invoice" link.

The resource representation of a policy that can be processed looks like

{
  ... policy properties ...
  "links": [
    {
      "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/[api-context-root]/policies/<id>/invoice",
      "rel": "policy:invoice",
      "httpMethod": "POST"

    }
  ]
}

In the resource representation of a policy that is not approved (last version), the invoice link is missing:

{
  ... policy properties ...
  "links": [
    {
    "href": "http://<host>:<port>/[api-context-root]/generic/policies/<id>",
    "rel": "self"
    }
  ]
}

Payload

The payload needs to provide the necessary information for all the sub steps to be executed, it looks like this:

{
  "calculationPeriod": "2018-04-01"
  "lookBackDate": "2017-01-01",
  "finTransDynLogic": "PREMTRANSLO-02",
  "comFinTransDynLogic": "COMTRANSLO-01",
  "disableRevGrouping": true,
  "createInvoiceDynLogic": "INV-01",
  "createInvoiceLineDynLogic": "INVLINE-01",
  "createAccountingDetailDynLogic": "ACCDETAIL-01",
  "premiumEndPoint": "https://cust/ex/prem.html",
  "commissionEndPoint": "https://cust/ex/comm.html",
  "generatePolicyCalculationPeriods": true,
  "replacePolicyCalculationPeriods": false,
 }

This payload maps to the different sub steps as follows:

  • mutations

    • Policy events for recalculation of level 'Policy' (referring to the policy at hand) or level 'Insurable Entity' (referring to one of the policy enrollments of the policy at hand) are picked up and translated into policy mutations (described in detail in the Configuration Guide for Change Events). That way, all policy mutations can be subjected to the premium calculation after which they can be discarded.

  • calculate premium (Default)

    • If the look back date is unspecified, then the look back date is set to the calculation input date.

    • The premium calculation process starts the period generation with billing context set to Immediate Billing

    • The attribute replacePolicyCalculationPeriods is taken into consideration to determine if the periods should be replaced or not

    • The pcp generation process considers any catch up period as part of its own regualar cycle. A catch up period can occur when the collection setting start date is before the span start date.

  • calculate premium (AU Localization, when system property indicates that the registrations should be applied to the periods)

    • Process registrations and apply registrations to periods processes are executed before calculate premium and after events are translated to mutations

    • The premium calculation process starts the period generation with billing context set to Immediate Billing.

    • The pcp generation process considers any catch up period as part of its own regualar cycle. A catch up period can occur when the collection setting start date is before the span start date.

    • The input value of the following parameters is not considered, instead the process always (re)set them to values as specified below (after executing apply registrations process):

Table 1. Payload
Name Description

Look Back Date

This is set to the Date Paid To plus one of the policy as determined by the apply registration process. This is to ensure that any periods to which payments have been applied are not accidentally re-calculated. These periods can only be re-calculated by 'Apply Registration to Periods' process.

If Date Paid To is unspecified, the look back date is set to the earliest policy enrollment product starts or to the start date of the earliest non reversed calculation result or to the calculation input date, whichever is earlier.

This is set per policy.

Generate Policy Calculation Periods

This is set to true

Replace Policy Calculation Periods?

When set to Yes in combination with the indicator Generate Policy Calculation Periods, the policy calculation periods are replaced from the look back date up to the input calculation date.

  • select financial transactions into a set
    A financial transaction set is used to group financial transactions together for financial processing. All the financial transactions that were created during the calculation are put into a new set; this encompasses both premium and commission financial transactions. All the unhandled financial transactions for the given policy, including all the unhandled financial transactions that already existing in a different set are selected and moved into this set as well. This situation is not likely for the portal use case, but it is possible when a member makes a change in the portal while there were already unhandled financial transactions in the system. Because the financial transaction set is only used as a vehicle for financial processing, it is not stored in a persistent way.

  • supersede financial transactions

  • generate financial message (XML format)
    The dynamic logic for the creation of invoice, invoice line and account detail is mandatory, just as it is when starting the generation of the financial message directly within the application. The endpoints for premium and commission are both optional: if an endpoint is not specified, it defaults to the endpoint for Generate Financial Message in the properties file. For premium and commission always separate financial messages will be created, even if they are delivered to the same endpoint.

Response Messages

This operation will provide HTTP status codes as defined in Response Messages. If successful, the financial messages ( premium and commission) is sent in the response and also to the specified endpoints, the response will be HTTP status code 200. If an error occurs, HTTP status code 401, 403, 409 or 422 is returned and a notification is sent containing error details. This way, the operation can be sent again after the reason for failure has been fixed.

In a situation when the process to generate invoice was successful but the sending of the financial message to the endpoint failed, the response will be HTTP status code 200 and will contain links to recover the failed activity (or activities if there are two messages, one for premium and one for commission) of sending out messages along with the financial message(s). The response will also not contain the financial message that was failed to sent out in the response.

In a situation when the process to generate invoice was successful, however no messages were generated as there was nothing (no message) to generate, the response will be 200 without any recovery link or financial message.

The following operation specific error can occur:

Table 2. Response Messages
Code Severity Message Text

POL-HTTP-006

Fatal

Could not resolve end point {0}

POL-HTTP-016

Fatal

Policy must be the last approved version

Authorization

The operation "Run Calculation and Produce Invoice for a Policy" can be protected by access restriction "policies.invoice IP".