Run Example Calculation for a Policy

This operation provides the ability to run premium calculation for a policy for a specific contract period or calculation period, without storing the results of the calculation. Instead these calculation results are returned in a response.

Resource Representation

Only policies in status Edit, Pended or Approved (last version) are eligible for running an example calculation for. This can be derived by the presence or absence of the "examplecalculation" link.

The resource representation of a policy for which an example calculation can be run, looks like this:

{
  ... policy properties ...
  "links": [
    {
      "href": "http://<host>:<port>/<contextRoot>/generic/policies/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/<contextRoot>/policies/{id}/examplecalculation",
      "rel": "policy:examplecalculation",
      "httpMethod": "GET"
    }
  ]
}

In the resource representation of a policy that is not in status Edit, Pended or Approved (last version), the "examplecalculation" link is not provided:

{
  ... policy properties ...
  "links": [
    {
    "href": "http://<host>:<port>/<contextRoot>/generic/policies/",
    "rel": "self"
    }
  ]
}

A calculation input date path parameter (in format YYYY-MM-DD) must be provided. This date is used to select the contract period or calculation period for which the example calculation has to be run. The path looks like this:

http://<host>:<port>/<contextRoot>/policies/{id}/examplecalculation/{calculationInputDate}

The following additional parameter may be specified:

Parameter	Description
billingCycle	I - Immediate Billing
	F- Forward Billing

It is also possible to fetch up to 5 calculation result dynamic fields in the response by using accept header parameter "fields". This parameter takes the dynamic field usagenames separated by '|'

For example: To get dynamicfieldusgae1 and dynamicfieldusage2 in the response , the accept header must be set as application/json;fields=dynamicfieldusgae1|dynamicfieldusage2.

Response Payload

The calculation periods that are to be calculated are selected based on the specified calculation input date.

System first triggers generation of policy calculation periods. If a policy contract period exists for the policy in context that includes the specified input date the policy calculation periods are generated with generate up-to date set to the specified input date and with the look back date set to the contract period start date. The system continues to generate periods including the contract end date.

If there is no policy contract, then the look back date is set to the input date.

The billing cycle is set as specified in the request.

The replace from date is set to the look back date.

Refer to the chapter 'Generate Policy Calculation Periods' in the premium calculation guide for details.

Once the periods are generated, for a contracted policy as of the specified input date all the calculation periods (system and policy) that overlap with that policy contract period are selected and single calculation period time line is created.

Policy calculation periods have higher priority than system calculation period. If there is a policy calculation period that overlaps with the selected system period, then the system period is not selected.

For a non contracted policy the system selects the policy calculation period that includes the input date. It then selects all the policy calculation periods having a calculation date that is the same as the calculation date of the selected policy calculation period. If no policy calculation period is found then the system calculation period that includes the specified input date is selected, provided there is no policy calculation period that overlaps with the selected system period

After the calculation periods are selected, premium is calculated for all selected periods (this is described in detail in the Implementation Guide for Premium Calculation) and the results are returned in a response. Note that the policy calculation periods and calculation results are not stored nor are financial transactions created.

The response payload containing the calculation results looks like this:

{
  "calculationResultSetTotalBasePremium": {
    "value": "",
    "currency": ""
  },
  "calculationResultSetTotalAdjustment": {
    "value": "",
    "currency": ""
  },
  "calculationResultSetTotalSurcharge": {
    "value": "",
    "currency": ""
  },
  "calculationResultSetTotalResult": {
    "value": "",
    "currency": ""
  },
  "calculationResultList": [
    {
      "calculationPeriod: {
        "startDate": "",
        "endDate": "",
        "displayName": ""
      },
      "calculationDate":""
      "referenceDate:""
      "policyContractStartDate: "",
      "policyContractEndDate: "",
      "groupAccount": {
        "code": "",
        "displayName: ""
      },
      "totalBasePremium": {
        "value": "",
        "currency": ""
      },
      "totalAdjustment": {
        "value": "",
        "currency": ""
      },
      "totalSurcharge": {
        "value": "",
        "currency": ""
      },
      "totalResult": {
        "value": "",
        "currency": ""
      },
      "calculationResultLineList": [
        {
          "sequence": "",
          "referencedCalculationResultLine": {
            "sequence": ""
          },
          "policyEnrollmentProduct": {
            "policyEnrollment": {
              "": {
               "link": {
                   "href": "http://://generic//",
                   "rel": "insurableEntityType.usageName"
                 }
              }
            },
            "enrollmentProduct": {
              "code": "",
              "displayName": ""
            }
          },
          "scheduleDefinition": {
            "code": "",
            "type": "",
            "surchargeRuleEvaluation": ""
          },
          "premiumSchedule": {
            "code": ""
          },
          "addOn": {
            "code": "",
            "displayName: ""
          },
          "resultAmount": {
            "value": "",
            "currency": ""
          },
          "retrievedAmount": {
                "currency": "",
                "value":
          },
          "percentage":""
        }
      ]
    }
  ]
}

Note, that a given implementation of the OHI application could have dynamic fields added to the calculation result. The system returns dynamic fields when accept header specifies them (see Request). For details on how external interfaces can access the values for dynamic fields 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.

Response Messages

This operation 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. This way, the operation can be executed again after the reason for failure has been fixed.

The following operation specific errors can occur:

Code	Severity	Message Text
POL-HTTP-001	Fatal	Policy must be the last version and in status Edit, Pended or Approved
POL-HTTP-005	Fatal	No calculation periods could be selected based on the specified calculation input date
POL-HTTP-018	Fatal	No more than 5 dynamic fields can be requested

Authorization

The above described operation is protected by access restriction "policies.example calculation IP". A grant for this access restriction must be provided with the Read flag set. If the access to a policy is restricted by a data access group restriction, then to perform this operation on that policy also a grant for that data access group restriction must be provided with the Read flag set.