Run Calculation and Produce Sample Invoice for a Policy

This operation provides a convenient way to execute several steps involved in calculate premium and invoice generation in one go to produce a sample invoice.

The process from calculation up to and including the production of a sample invoice is available for a single policy in the status 'Approved' (last approved version) , 'Edit' and Pended'. It consists of the following sub steps:

  • calculate premium for a particular policy

  • 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 Developer Guide for more information).

Resource Representation

The operation sample invoice can be triggered for a policy in Oracle Health Insurance by executing operation 'sampleinvoice'.

{
  ... policy properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]generic/policies/{id}",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/policies/{id}/sampleinvoice",
      "rel": "policy:sampleinvoice",
      "httpMethod": "POST"

    }
  ]
}

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":"2018-04-01"
  "finTransDynLogic": "PREMTRANSLO-02",
  "comFinTransDynLogic": "COMTRANSLO-01",
  "disableRevGrouping": true,
  "createInvoiceDynLogic": "INV-01",
  "createInvoiceLineDynLogic": "INVLINE-01",
  "createAccountingDetailDynLogic": "ACCDETAIL-01",
  "replacePolicyCalculationPeriods:false,
  "recalculateBeforeDatePaidTo":  false
  "parameters": [
    {
      "name": "string",
      "value": "string"
    }
    ... upto 5 parameters
  ]
 }
}

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 (non-persisted).That way the effect of any existing policy events can be taken into account during premium calculation.

  • If the parameter recalculateBeforeDPT is set to true and the system property indicates that the registrations should be applied to the periods, then the system creates a mutation of type re-calculation with the effective date set to calculation input date.

calculate premium (Default)

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

  • The system assumes policy calculation period generation is set to 'Yes'

  • 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.

  • The parameters propagates to the policy calculation period segmentation logic.

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 parameters propagates to the policy calculation period segmentation logic.

  • The premium calculation process starts the period generation set to 'Yes' and with the 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.

    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.

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

  • select financial transactions into a set and supersed

A financial transaction set is used to group financial transactions together for financial processing. All 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.

  • 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.

Response Messages

This operation will provide HTTP status codes as defined in Response Messages. If successful, the financial message is returned in the response. If an error occurs, HTTP status code 401, 403, 409 or 422 is returned. This way, the operation can be sent again after the reason for failure has been fixed. In case there are no messages generated, the response would be empty with status code 200.

The following operation specific errors can occur:

Table 2. Response Messages
Code Severity Message Text

POL-HTTP-017

Fatal

Policy must be either the last approved version or the last version and in status Edit or Pended.

POL-HTTP-019

Fatal

No more than five parameters can be specified.

Authorization

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