Apply Registrations to Periods
This functionality makes it possible to apply payment registrations and determine the coverage period that can be considered to be paid for. The retroactive changes on policy, late or early payments, etc. have an effect on the premium that is calculated by the system for a given period. The money that is paid may no longer be enough to cover the full period because of these changes and therefore the coverage period must be re-established by re-calculating it. This process re-calculates the periods taking into the effect, the time the payment is made and the amount for which it is made. At the end of the activity the Date Paid To - that is the period up to which the coverage is paid for is determined. Any policy calculation periods beyond this date are deleted and the results are reversed
This process can be started by making a POST request to the URI: https://<context:root>/api/applyregistrations. This process is an example of a Long Running Operation through REST. The general concepts of these operations are described in the HTTP API/IP Concepts chapter of the integration guide. A grant for access restriction 'applyregistration IP' must be provided to be able to initiate this operation.
The user can control the scope of the calculation by selecting values for the following parameters:
| Name | Description |
|---|---|
Brand |
If specified, the calculation only picks up policies for that brand. If not, then the calculation picks up policies due for calculation from any brand. |
Group Client |
If specified, the calculation only picks up policies for the group accounts in the group client [1]. If not, then calculation picks up policies due for calculation from any account. |
Group Account |
If specified, the calculation only picks up policies for that group account. If not, then the calculation picks up policies due for calculation from any account [2]. If unspecified is selected, the calculation only picks up individual policies (group client parameter should be empty in that case). |
Premium Financial Transaction Function |
This function facilitates the modification of 1) financial transaction details and 2) financial transaction and financial transaction process data attributes of the premium financial transaction. |
Commission Financial Transaction Function |
This function facilitates the modification of 1) financial transaction details and 2) financial transaction and financial transaction process data attributes of the commission financial transaction. |
Disable Grouping on Reversal Indicator for Invoice Lines? |
The default behavior is that invoice lines are grouped on (among others) the reversal indicator; as a consequence credit and debit invoice lines can never result in a single zero result invoice line. Setting the parameter to 'Y' will disable this default behavior. |
The following messages can occur while starting this process:
| Code | Sev | Message Text |
|---|---|---|
POL-VL-AREG-001 |
Fatal |
Brand code {code} is unknown |
POL-VL-AREG-002 |
Fatal |
Group account code {code} is unknown |
POL-VL-AREG-003 |
Fatal |
Function dynamic logic code {code} is unknown or has an invalid signature |
POL-VL-AREG-004 |
Fatal |
Group client code {code} is unknown |
If a single group account (X) includes policies that belong to brand A and other policies that belong to brand B, it is possible to start a calculation for only those policies that belong to account X and brand A, or only those policies that belong to account X and brand B. If the user specifies account X as a parameter - and leaves the brand empty - then the calculation picks up all policies that belong to account X, both for brand A and B.
The process then selects all policies that may be eligible for calculation. This is done by determining a look back date per policy. The look back date is the date at which the recalculation for this policy has to start.
The look back date is used two ways:
-
In filtering out the policies where the group account or enrollment product relationships have ended before the specified value.
-
It also determines from which point forward the payment registrations must be re-applied.
Per policy the Look back date is determined in the following way:
-
If the date paid to is set and there exists a mutation with effective date on or before the date paid to, then the look back date is set to the earliest effective date of the mutation. This is when the payment registrations are applied in order, that is, there exists no applied payment registration with the pay date being after the pay date on the earliest new payment registration.
-
If the payment registrations are not applied in an order then the system must considers the pay date on the new payment registrations while determining the look back date. In such a case, the look back date is set to the earliest effective date of the mutation or the pay date of the earliest new payment registration, whichever is earlier.
-
-
If date paid to is set and there exists no mutation with effective date before the date paid to, then the process checks if there is at least one new payment (other than the carry over). In this case, the look back date is set to the date paid to plus one. Here too, the system checks if the payments are being applied in order or not.
-
If the payment registrations are not applied in order then the system must considers the pay date on the new payment registrations while determining the look back date. In such a case, the look back date is set to date paid to plus one or to the pay date of the earliest new payment registration, whichever is the earlier.
-
-
If the date paid to is not set and there is a new registration (other than carry over), then the look back date is set to the earliest of the following:
-
the start date of the earliest policy enrollment product
-
the earliest effective date of the mutation
-
the pay date on the earliest new payment, whichever is earlier
-
Further Adjust the Look Back Date?
The process selects the policy calculation period in which the look back date takes effect. If there are earlier policy calculation periods with the same pay date before the selected period, the look back date is set to the start date of the earliest period thereby ensuring that the past periods with the same pay date are selected and (re)calculated.
Policy Selection
These are all policies (latest Approved versions) that:
-
have the look back date set (meaning look back date is not empty)
-
have no 'new' (unapplied) refund registration
-
belong to the specified group account, or - if the group account parameter has the value unspecified -* have no group account
-
a policy belongs to a group account if the policy group account relation has not ended before the look-back date.
-
-
have a policy enrollment product that has not ended before the look back date or have a non-reversed calculation result with a calculation period start date that includes or starts after the look back date
The system then calculates the premium for each of the eligible policies, as specified in the section Apply Registrations to Periods per policy.
Apply Registrations to Periods per Policy
The following sections contain detailed descriptions of the system logic for each of these steps.
Note that if in any of the steps a message is raised (for example if multiple applicable premium schedule lines are found), the element id of the message is set to the policy code of the policy in context (for example: element Id="POL0002340").
Select Registrations to Apply
The process identifies the policy calculation period in which the look back date takes effect. The pay date on this period gives the point in time from which the registrations must be re-applied. As the next step, the process selects all the payment registrations having their pay date on or after this date (pay date which is selected previously) and marks them 'New' and deletes all the carryovers and carryover offset having their pay date on or after this date. This is because the system will recalculate the periods and create carryovers (when applicable).
If there is no policy calculation period in which the look back date takes effect, then all the registration having pay date on or after the look back date are marked 'New'.
Once the payments are marked to 'New' (to be reapplied), then this may require a further adjustment to the look back date. The system selects all the calculation periods with the pay date equal to the applied payments that are now being marked as 'New' and sets the look back date to the earliest calculation period start date.
The process then selects carryover transaction having a carryover applied pay date same as the pay date on the PCP to which the look back date belongs to and sets its status to 'New'. This is the carryover transaction that must be re-applied (with the earliest new registration).
If the look back date is on or before the date paid to (when date paid to is not null) and there are no new registrations in the selection, system logs a fatal message 'POL-FL-AREG-001'.
| Code | Sev | Message Text |
|---|---|---|
POL-FL-AREG-001 |
Fatal |
No registration can be found to (re)apply, for the periods being recalculated from {look back date} to the Date Paid to {date paid to} |
The next steps are performed only when there are new registrations (other than a carry over) in the selection.
Generate Policy Calculation Period
When look back is on or before the date paid to, the policy calculation periods are replaced from the look back date and are generated up to the date paid to. If the date paid to is null, the policy calculation periods are replaced with replace from date set to the look back date and are generated up to the earliest policy enrollment product start date. For details on policy calculation period generation process refer to the section Generate Policy Calculation Period per Policy of the chapter Generate Policy Calculation Periods.
If the look back is after the date paid to, the periods are replaced and re-generated as of the look back date.
Process may generate more periods as the registrations are applied. This is described later in the guide in the section Calculate Premium and Apply Registration.
Select Calculation Period
The policy has to be calculated or recalculated from the look back date, until there are no more registrations to apply.
All the policy calculation periods starting on or after the look back date are included. Next, the system selects the first period and includes the periods with the same calculation date of that first period (which might be starting earlier, but are part of the same cycle).
| Generate period activity splits the periods to a line with calculation period segments based on contract periods and group account settings. Assumption is there is no use case with apply payments where one policy calculation period can contain multiple calculation period segments. |
Reference Date of the Calculation Period
For every identified calculation period the system uses the reference date setting on the policy calculation period; if the policy calculation period reference date is left blank, then the policy calculation period start date is used.
Verify Calculation Periods
The previous step resulted in a list of all calculation periods for a single policy that may require (re)calculation. This step filters the list down to only the calculation periods needing (re)calculation.
The next step is executed individually for each of the identified calculation periods.
Calculation Period Without Enrollments
If there is no previous non reversed calculation result and there is no effective policy enrollment product during (any part of) the calculation period, then the calculation period is removed from the list.
For a policy with a contract period, if there is a previous calculation result and there is no effective contract period during any part of the calculation period, then the calculation period is removed from the list.
This check prevents the system from attempting to calculate calculation period a policy during which there is no enrollment (and contract) yet.
Retroactively Ended Policies
If there is a previous non reversed calculation result, but there is no effective policy enrollment product during (any part of) the calculation period, then the calculation period results are flagged for financial reversal.
If there is a previous calculation result related to a contract period, but if there is no effective contract period during any part of the calculation period, then the calculation period results are flagged for financial reversal.
This situation can occur in the following cases:
-
If all policy enrollment products (and contract period) on the policy have been end-dated retroactively
or -
When a contract start date or policy group account changes.
Calculate Premium and Apply Registrations
In this step, the new registrations (going forward) are applied to the calculation periods in the selection starting with the earliest start date.
In a situation when there are new registrations (other than carryover), but no policy calculation period in the selection, system keeps generating policy calculation periods, until all the registration are applied. It is possible that no valid periods can be generated by the process to cover the full registration amount, for example, there is no policy enrollment product valid on the policy anymore, in this case the process creates an offset and a carryover for the difference between the received registration amount and the amount that could be applied. The date paid to is moved to the end date of the last period up to which the registrations are applied. When there are no applied periods, date paid to is set to null.
Apply Registrations to Period(s)
The process selects 'New' registrations with the earliest pay date and applies them to the earliest policy calculation period in the selection (after the verify calculation period step). Applying a registration means identifying the coverage period (policy calculation period) that can be bought by the amount on the registration.
Early or late payments can influence the premium which is applicable for the period. And therefore, before applying the registrations, the premium must be re-calculated for the policy calculation period being considered. The pay date of the registration (not the carryover, as the carryover belongs to past period) is the date when the premium for the period under consideration is actually received. The pay date on the policy calculation period is updated to this date and premium is re-calculated as per the steps described in Calculation per Period section in this guide.
This total amount on the computed result is compared to the total amount on the registrations having the same pay date and any carryover in the status 'New'. If these amounts are a match, the date paid to is updated to the policy calculation period end date, the registrations and the carryover (from the past calculation) are marked 'Applied', the field applied pay date on the carryover is set to the registration pay date and the calculation result is flagged for persistence.
If this amount is not a match then either of the following three scenarios may apply:
Registration amount is zero
The selected registrations (including carry over) are marked 'Applied'.
If there are new registrations (other than carryover) to apply then the process moves to the next registration (going forward based on pay date) and repeats process Apply Registrations to Period(s).
If there are no new registrations to apply then the period is deleted and the date paid to is updated to period start date minus 1. All other periods that start after the date paid to are deleted.
Registration amount is less than the calculation result
If the total registration amount is less than the calculation result then the process tries to identify the number of days for which the coverage can be bought by the amount paid. To do that, the process determines the amount required to buy one day of coverage. One day coverage amount is given by the total amount calculated for the period divided by the total number of days in the period. The integral value of the amount received (registration) when divided by the per day coverage amount gives the total number of days for which the registrations could apply.
An integral value of zero, implies that registration(s) cannot buy a full day. In this case, the registration is marked as applied, a negative offset (status applied) and a carryover (status new) transactions are created. If there are new registrations (other than carryover) to apply, the process moves to the next registration (going forward based on pay date) and repeats process Apply Registrations to Period(s).
If the integral value is not zero, then the policy calculation period is adjusted to match the number of coverage days by splitting it into two. The first part (the first part after the split, having the number of days equal to the coverage days) is recalculated and this gives the exact amount that can be applied. The process then calculates the difference between the total registration amount and the actual amount that is applied. The process then tries to apply the difference to subsequent period(s) until the total registration amount is not equal to cover a full day. When this happens the process creates a new negative carry over offset equal to the total amount unapplied as 'Applied' and a new carry over transaction with the status 'New' (this new carry over is applied with the next registration). The date paid to is updated to the end date of policy calculation period under consideration. The registrations and the carryover (from the past calculation) are marked 'Applied', the applied pay date on the carryover (if applicable from the past calculation) is set to the registration pay date and the calculation result is flagged for persistence.
If there are new registrations (other than carryover) to apply, the process moves to the next registration(going forward based on pay date) and repeats process Apply Registrations to Period(s) to the second period created because of the split. Otherwise, the process stops and all the periods that starts after the date paid to are deleted.
Consider the following example to clarify:
The premium for a weekly policy calculation period with the start date 28th March 2019 to 3rd April 2019, pay date of 25th is calculated as 15.00. Assuming premium schedule line that applies is configured as 15.00 for 7 days. Customer pays 7.00 as of 30the March 2019, that is registration for payment of 7.00 is received with a pay date of 7.00. The pay date on the PCP is updated to 30th March and premium is recalculated, assuming the recalculated premium amount is 15.00 the next steps are carried out.
-
Amount of 7.00 can buy 3 days, the integral value of 7/ (15.00/7)
-
15.00/7 is the amount needed for one day of coverage.
-
-
PCP is split into two
-
PCP A 28th March - 30th March (pay date 30th March)
-
PCP B 31st March - 3rd April
-
-
PCP A is recalculated and the results are flagged for persistence with no invoice , and the premium for PCP A is 6.43
-
The difference between the received amount and the premium is 7 - 6.43 = 0.57
-
A negative offset (-0.57) and a carryover (0.57) transactions
-
-
Registrations
The registrations after the payment is applied will look like
Description |
Pay date |
Amount |
Status |
Payment |
30-March -2019 |
7.00 |
Applied |
CARRYOVER_OFFSET |
30-March-2019 |
-0.57 |
Applied |
CARRYOVER |
30-March-2019 |
0.57 |
New |
-
If there are new registrations (other than carryover) to apply, the process will apply the next subsequent registration to PCP B, if there are no new registrations then the PCP B and PCPs after it will be deleted.
Registration amount is more than the calculation result
If the registration amount is more than the calculation result, the system tries to see if the amount can be applied to the subsequent calculation period(s). The process updates the pay date of the subsequent policy calculation period to the registration pay date and calculates the premium for it. The totals are compared again, this time the amount of the first and the subsequent periods are added. If the total matches, the results are persisted, the status of the registrations is updated to 'Applied' and the date paid to is updated to the end date of the second period. If the amount on the registration is still more, the process is repeated until the amount on the registration(s) matches or the total amount on the registrations become less. In a situation when there is no policy calculation period in the selection, but the total on registration is still greater than the amount of the calculation results, then system keeps generating policy calculation period and calculating premium for policy calculation period, until any of the following occurs:
-
the amount on the registration(s) matches
-
or the total amount for the registration become less
-
or the amount on the registration is more, but no more valid periods can be generated
When the amounts are a match, the registrations are marked 'Applied' and the date paid to is updated to the end date of the last period considered. The results are persisted.
When the total registration amount does not match but becomes less than the total amount on the calculation results, the process must identify the date up to which the coverage can be bought by the total amount received (registration amount). To do that total available registration amount for the period (after considering which the registration amount become less than total amount on the calculation results) must be calculated. This is done by subtracting the calculated amount for all the past periods except the last period from the total registration amount.
After the available registration amount is known, the next steps in the process are identical to the use case when the total registration amount is less than calculation period amount. The last period is split so that all the past period plus the first period (after the split) form the total coverage period. The date paid to is updated to the end of the coverage period (i.e. end date of the first part of the spit), the registrations and the carryover (from the past calculation) is updated to the status 'Applied', the applied pay date for the carry over is set to the registration pay date, a new carryover might be created and the calculation results are flagged for persistence.
If there are new registrations (other than carryover) to apply, the process moves to the next registrations(going forward based on pay date) and repeats process Apply Registrations to Period(s) to the second period created because of the split. If there are no new registrations, the process stops and the all the periods beyond the date paid to are deleted.
If the total on the registration is more and the process cannot generate more valid period for which premium can be calculate because 1) there is no valid policy enrollment product for the non contracted policies 2) or there is no valid policy enrollment product or a contract for contracted polices. The process creates an offset and a carryover for the difference between the received registration amount and the amount that could be applied. The date paid to is updated to the end date of last applied period. When there are no applied periods, date paid to is set to null. The registrations are marked 'Applied'. An informative message 'POL-FL-AREG-002' is logged and the process stops.
More registrations to apply?
If there are new registrations (other than carryover) to apply, the system moves to the next policy calculation period in the selection and repeats the process Apply Registrations to Period(s) until all the registration are applied. In a situation when there are new registrations (other than carryover), but no policy calculation period in the selection, system keeps generating policy calculation periods, until all the registrations are applied.
If there are new registrations, but policy calculation periods cannot be generated any further, the registration is not applied. An informative message 'POL-FL-AREG-002' is logged and the process stops.
If there are no new registrations (other than carryover) to apply, but there are policy calculation periods in the selection then the periods are deleted.
| Code | Sev | Message Text |
|---|---|---|
POL-FL-AREG-002 |
Informative |
New registrations from {pay date} cannot be applied as no policy calculation periods after {end date of the last period} can be generated. |
Generate Periods
When no policy calculation periods are present for the policy, then the periods are generated with generated up to date set to the earliest policy enrollment product start date.
If periods are already present for a policy then the next periods are generated by starting the period generation process with generate up to date and look back date set to last available period’s end date plus one. For every period that is generated, the steps 2) Reference Date of the Calculation Period and 3) Verify Calculation Periods as described earlier in the guide are performed.
It is possible that the next period generated is not identified as a valid period, the process keeps generating periods if there is a valid policy enrollment product that starts after the generated period:
-
For a non contracted policy if there exists no valid policy enrollment product that spans over the generated period, then the next periods are generated with generate up to date set to the start date of earliest policy enrollment product that starts after the generated period and the look back date set to the end date of last period in the selection.
-
For a contracted policy if there exists no valid policy enrollment product or a contract that spans over the generated period, then the next periods are generated with generate up to date set to the earliest date after the generated period for which there exists a contract and a policy enrollment product. The look back date set to the end date of last period in the selection.
Consider the following example to clarify
-
Policy enrollment product A : start date 01/01/2019, end date 31/03/2019
-
Policy enrollment product B: start date 01/06/2019, end date 31/03/2020
-
Policy enrollment product C: start date 01/07/2019, end date 31/03/2020
-
Collection setting is set to monthly payments
-
Monthly periods are generated upt0 march with pay date set to be two days before the start date of the period
-
Premium per month is $100.00
Suppose the date paid to is set to 28/02/2019. Registration of $200.00 is received with the pay date of 27/02/2019. The process will start applying $200.00 from March onward. Since the registration amount is more that the premium for March, the system must generate the next period by starting generate policy calculation periods process with generate up to date 01/04/2019 and look back 01/04/2019. Policy calculation period 'April' is generated. This period is not a valid period as there is no policy enrollment product that is valid during its time span and is therefore not considered. The process checks for valid policy enrollment product that starts after 30/04/2019. In this case policy enrollment product B and policy enrollment product C are selected. The periods are generated with generate up to date 01/06/2019 and look back 28/02/2019. The next periods May and June are generated. No policy enrollment product applies for May and is therefore removed from the selection. PEP B is valid for June and premium for June gets calculate. Suppose the premium for June is $100.00, then the registration of $200.00 is marked as 'Applied'. The date paid to is updated to 30/6/2019.
If there are more new registrations to apply then the process keeps generating periods and keeps applying registrations until no valid periods can be generated or all the registrations are marked applied.
-
Updating the pay date on the periods*
When the pay date on the pcp is updated, the segment function is called with this PCP as an input. Pay date can affect the value of the dynamic fields on the PC and therefore might required to be adjusted further.
Reverse Calculation Results
Reverse Future Calculation Results
Existing non reversed calculation results that have start date after the date paid to and are not already reversed, are flagged for financial reversal and the policy version in context is set as the reversal policy on the results. These calculation period are not recalculated but are picked up in the last step 'Write Calculation Results and Financial Transactions' of the premium calculation process.
Reverse Calculation Results Without Corresponding CalculationPeriods
If there are previous calculation results having the start date that is within the current (re)calculation timeline but do not have any calculation period with the same start date in the timeline then these results are flagged for reversal.
Calculation per Period
Select Policy Enrollment Products
The steps to select policy enrollment products are identical to the steps described in the section "Select Policy Enrollment Products", of the calculate premium guide.
Calculate Enrollment Product Premium
The steps to calculate enrollment product premium are identical to the steps described in the section "Calculate Enrollment Product Premium", of the calculate premium guide.
Note - Au implementation has only PCPs, so calculation method is always 'Policy Calculation Period Based'.
Calculate Add-on Premium
The steps to calculate add-on premium are identical to the steps described in the section "Calculate Add-on Premium", of the calculate premium guide.
Calculate Surcharges on Premium
The steps to calculate surcharges on Premium are identical to the steps described in the section "Calculate Surcharges on Premium", of the calculate premium guide.
Calculate Adjustments
The steps to calculate the adjustments are identical to the steps described in the section "Calculate Adjustment", of the calculate premium guide.
Response
As is described in Long Running Operations through REST there are multiple ways in which one can get the response/result of this long running operation. Typically though one would opt for using notification events.
A notification message can be sent out to a pre-configured endpoint. The notification endpoint can be configured on 'ohi.activityprocessing.notification.endpoint.APPLY_REGISTRATIONS' or to a more generic endpoint: ohi.activityprocessing.notification.endpoint.
If the notification endpoint is configured on the specific: APPLY_REGISTRATIONS, all other related properties like media type, authentication, etcetera, are also fetched based on APPLY_REGISTRATIONS, 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.