InterestRateCalculation
The business rule defines the type and details used to calculate interest performed over fixed funds. Interest rate calculation methodologies can be assigned to fixed funds using this rule. In most cases, this rule is overridden on a specific fund.
Note: When all the three types of rates (Current, Guaranteed and Additive) are present, the additive rate(s) can always be applied to the minimum or maximum of Current and Guaranteed compare, whichever should be the correct result for the fund. Also, the user can specify to which rate (Current, Guaranteed or the result of Current and Guaranteed compare) to add Additive Interest Rates.
Specific values from the database can be retrieved without writing SQL statements by using the available defined prefixes and fields for configuration. Please see the Available Prefixes and Fields for Configuration for a list.
| Element/Tag | Attribute | Definition | Element/Attribute Value and Description |
|---|---|---|---|
|
<InterestRateCalculation> |
|
Opening and closing tag for the rule. |
|
|
<InterestType> |
|
Required: Indicates the formula that will be used to calculate interest for the fund.
|
Compound: Existing calculation type.
|
| SIMPLEINTERESTREFERENCEDATE |
Required: when the fund is a simple interest fixed fund type. The value must resolve to a valid date. |
Literal date value, Plan field, Policy field or Valuation data using the following syntax: Plan:date field Policy:date field Valuation:Deposit:date variable/field Valuation: Fund: date variable/field |
|
|
<LeapYearMethod> |
|
Required: Opening tag to define a node that describes leap year affect on interest calculations.
|
|
|
<Method> |
Required: Opening tag to define the leap calculation method employed by this fund. |
|
|
| YEAR |
Required: Opening tag to define the calculation method of the numerator and denominator. |
Calendar:indicates that leap year is determined based on the calendar year. 360: the actual value to use in the denominator. |
|
|
<MethodReferenceDate> |
|
Required: This is required when YEAR is ReferenceDate. The value must resolve to a valid date.The number of days between anniversaries becomes the value of the denominator. |
Literal date value, Plan field, Policy field or Valuation data using the following syntax Plan:date field Policy:date field Valuation:Deposit:date variable/field Valuation: Fund: date variable/field |
|
<Method365IncludeLeapDayInNumerator> |
|
Required: When YEAR is 365. This determines if February 29th is skipped while calculating the number of days for the numerator. |
No: skip February 29th. |
| <MaintainMonthEnd> |
|
Optional: This attribute is only applicable when YEAR is ReferenceDate and is ignored for all other values of YEAR. Default value is "No". This will indicate when an alternative anniversary result is desired. |
Yes: When the natural calculation of anniversaries or month-aversaries is an invalid date, the result will be the last day of the month (For example, 2/29/2015 will become 2/28/2015). No: When the natural calculation of anniversaries or month-aversaries is an invalid date, the result will be the first day of the next month (For example, 2/29/2015 will become 3/1/2015). This is the default behavior. |
|
<InterestPeriod> |
|
Required: This determines the boundary dates where the numerator and denominator change. Needed with leap year and/or interest rate changes. |
Begin: the interest to be calculated includes interest for the beginning date of the date range (last valuation date) and excludes the ending date. |
|
<ValueAsOfPreviousDate> |
|
Optional: Indicates a one day adjustment to both ends of the date range. This provides the ability to value the fixed fund up to but not including the valuation date. The default value is No. |
Yes: the start and end dates of the date range will be adjusted one day prior to the valuation date. |
| <CalculationScale> | Optional:Optional. Provides the scale used in the interest calculation formula to achieve a desired value precision and interest result. This affects the time portion of the interest formulas: ([days in time period] / [days in year]). The default value is 10. |
Any numeric value from 0 through 100. The higher the number the more decimal positions the calculation carries. |
|
|
<GuaranteedInterestRate> |
|
Optional: Opening tag defining a node that describes the look-up of the guaranteed interest rate. Ultimately, the rate used to calculate interest must be the greater of the result from this node and the result from the CurrentInterestRate node. When this node is not present, consider the result to be 0. |
|
| USERATE | Optional: This indicates which of the GuaranteedInterestRate or CurrentInterestRate to use in the interest calculation. |
Higher – use the higher of the two rates. This is the default. Lower – use the lower of the two rates. |
|
|
<RateType>
|
Required. Opening tag for the node that defines the rate or its retrieval. | ||
|
TYPE |
Required. Describes whether the rate is provided in the rule (Static) or from a retrieval of AsRate/AsRateGroup (Lookup).
|
Static – rate is provided in <StaticRate>. Lookup – rate will be retrieved from AsRate using information provided within <RateLookup>. |
|
| <StaticRate> | Required when TYPE is Static. Defines a static rate in the rule that never changes. Value must resolve to a decimal data type. | The interest rate as a percentage or decimal equivalent. | |
| <RateAsPercent> | Optional: Default value is No. Indicates when the rate is expressed as a percentage or a decimal equivalent. |
- Yes – rate is expressed as a percent and will be divided by 100 before being used in the interest calculations. - No – rate, as expressed, is used in the interest calculations (default). |
|
|
<RateLookup>
|
|
Required in each interest rate node where RateType is Lookup. This is the opening tag defining how to look-up the interest rate and the behavior for changing an interest rate. |
|
| <Math> | Optional: Opening tag for a Math node with scope limited to this interest rate node. | ||
| <MathVariables> | Required: Opening tag for the variables within the Math node. | ||
| <MathVariable> | Required: Defines the variables that will support tag values needed in subsequent tags in this interest rate node. | ||
|
<RateDescription>
|
|
Required: Provides the rate description of the rate(s) to look up. The same rate description that is in AsRate and AsRateGroup. |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:data field Policy:data field Math:data variable Valuation:Deposit:data variable/field Valuation: Fund: data variable/field |
| <EffectiveDate> | Required: A date mapped to AsRateGroup’s EffectiveDate. It is used to filter rates based on an approval date. Value must resolve to a valid date. |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:date field Policy:date field Math:date variable Valuation:Deposit:date variable/field Valuation: Fund: date variable/field |
|
| <Criteria> | Optional: Opening tag that holds the rate criteria that may be used to look-up a rate. | ||
| <RateCriteria> | Optional: Provides a value to a Criteria column that will be used to retrieve the correct rate(s). This may be repeated up to 11 times (one for each criteria column and one for the IntegerCriteria column) as needed depending in the structure of the set of rates being retrieved. Correct data types will be enforced. |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:data field Policy:data field Math:data variable Valuation:Deposit:data variable/field Valuation: Fund: data variable/field |
|
| NAME | Required: The name for the column as provided by AsRateGroup. | ||
| DEFAULT | Optional: Provides a secondary value from which the criteria column may be compared to if the use of the primary value has returned no value(s) from the database. Correct data types will be enforced. |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:data field Policy:data field Math:data variable Valuation:Deposit:data variable/field Valuation: Fund: data variable/field |
|
| OPERATION | Optional: Default value is EQ. Provides a comparison operator between the database value and the value referenced by the parent tag’s value. | LT: Less than GT: Greater than EQ: Equal to LTEQ: Less than equal to GTEQ: Greater than equal to |
|
| DATATYPE | Optional: Default value is TEXT. Tells the system the data type comparison rules to follow. |
- TEXT – use text rules - DATE – use date rules - INTEGER – use integer rules - DECIMAL – use decimal rules |
|
| <DateCriteria> | Optional: Provides a value to the DateCriteria column that will be used to retrieve the correct rate(s). The field or math variable must resolve to a valid date. |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:date field Policy:date field Math:date variable Valuation:Deposit:date variable/field Valuation: Fund: date variable/field |
|
| DEFAULT | Optional: Provides a secondary value from which the criteria column may be compared to if the use of the primary value has returned no value(s) from the database. Correct data types will be enforced. |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:date field Policy:date field Math:date variable Valuation:Deposit:date variable/field Valuation: Fund: date variable/field |
|
| OPERATION | Optional: Default value is EQ. Provides a comparison operator between the database value and the value referenced by the parent tag’s value. | LT: Less than GT: Greater than EQ: Equal to LTEQ: Less than equal to GTEQ: Greater than equal to |
|
| <RateChange> | Required: Opening tag for the rate change node. Defines the behavior of the rate changes that should occur. | Child nodes in this section are required only when TYPE = ReferenceDate. | |
| TYPE | Required. Defines how the system treats interest rate changes that occur inclusively between the last valuation and current valuation date. |
- Never – interest rate changes should not be recognized by the system. - ReferenceDate – provides a date from which to calculate anniversaries/monthaversaries. - Immediate – interest rate changes on the date it is effective (DateCriteria). |
|
| <ReferenceDate> |
|
Required when the value of TYPE is ReferenceDate. The value must resolve to a valid date. The value provides a date from which to calculate durations (if needed) and anniversaries/monthaversaries for shadow removals (if needed). |
Literal value, Plan field, Policy field, Math variable or Valuation data using the following syntax Plan:date field Policy:date field Math:date variable Valuation:Deposit:date variable/field Valuation: Fund: date variable/field |
| <EffectivePeriod> | Required when TYPE is ReferenceDate. Value is the number of years or months a particular interest rate is applicable. This maintains a rate for a specific period of time no matter how many rate changes may exist between the last valuation date and the current valuation date. | Any number of years or months is valid. 0 means that the rate may change at any time negating the value of a reference date. | |
| INTERVAL | Required when TYPE is ReferenceDate. Defines how EffectivePeriod is expressed. |
Years – value of <EffectivePeriod> is expressed as years. Months – value of <EffectivePeriod> is expressed as months. |
|
| <LookUpChangeRateBy> | Required when TYPE is ReferenceDate. Defines how to look up a changed rate after determining that the date range is eligible for rate changes. |
LastRateAtDuration – use a duration calculated as the full number of years or months (see INTERVAL) between <ReferenceDate> and the start date of the time period in which interest is being calculated. Map to the IntegerCriteria column. LastEffectiveRate – retrieve the last rate that was declared on or prior to an anniversary/monthaversary (see INTERVAL) that is based on <ReferenceDate>. Map to DateCriteria column. |
|
| <CurrentInterestRate> | Opening tag defining a node that describes the look-up of the current interest rate. It is an optional section if <GuaranteedInterestRate> is present. Otherwise, it is required. Ultimately, the rate used to calculate interest must be the greater of the result from this node and the result from the GuaranteedInterestRate node. When this node is not present, consider the result to be 0. | ||
| <RateType> | See above for common <RateType> xml data. | ||
| ... | ... | ... | ... |
|
<AdditiveInterestRates> |
|
Optional: Opening tag defining one or more additive rates. Each additive rate is added to the final rate used to calculate interest. |
|
|
<AdditiveInterestRate>
|
|
Required: Opening tag defining a node that describes calculation of one additive interest rate. The result from this node will be added to the <GuaranteedInterestRate> result, to the <CurrentInterestRate> result or to the result of the greater of <GuaranteedInterestRate> and <CurrentInterestRate>.
|
|
| CODE |
Required.Uniquely identifies this node with a code value that provides a business name for the interest rate that is being calculated. |
Any valid code value from AsCodeAdditiveRateCode. |
|
| <RateType> | See above for common <RateType> xml data. | ||
| ... | ... | ... | ... |
XML Schema
<InterestRateCalculation>
<InterestType SIMPLEINTERESTREFERENCEDATE="[valid date]">[Compound|Simple]</InterestType>
<LeapYearMethod>
<Method YEAR="[Calendar|ReferenceDate|365|360]">
<MethodReferenceDate>[valid date]</MethodReferenceDate>
<Method365IncludeLeapDayInNumerator>[Yes|No]</Method365IncludeLeapDayInNumerator>
</Method>
</LeapYearMethod>
<MaintainMonthEnd>[Yes}No]</MaintainMonthEnd>
<InterestPeriod>[Begin|End]</InterestPeriod>
<ValueAsOfPreviousDate>[Yes|No]</ValueAsOfPreviousDate>
<CalculationScale>[0 | 1 | 2 | 3 | … | 99 | 100]</CalculationScale>
<GuaranteedInterestRate USERATE="[Higher|Lower]">
<RateType TYPE="[Static|Lookup]">
<StaticRate>[valid rate]</StaticRate>
<RateAsPercent>[Yes|No]</RateAsPercent>
<RateLookup>
<Math>
<MathVariables>
<MathVariable>[math statement]</MathVariable>
</MathVariables>
</Math>
<RateDescription>[valid rate description]</RateDescription>
<EffectiveDate>[valid date]</EffectiveDate>
<DateCriteria OPERATION="[valid operation]" DEFAULT="default value]">[valid date]</DateCriteria>
<Criteria>
<RateCriteria NAME="[column name]" OPERATION="[LT|GT|EQ|LTEQ|GTEQ]" DATATYPE="[TEXT|DATE|INTEGER|DECIMAL]" DEFAULT="[default value]">[criteria value]</RateCriteria>
</Criteria>
<RateChange TYPE="[Never|ReferenceDate|Immediate]">
<ReferenceDate>[valid date]</ReferenceDate>
<EffectivePeriod INTERVAL="[Years|Months]">[0 | 1 | 2 | 3 | ...]</EffectivePeriod>
<LookUpChangeRateBy>[LastRateAtDuration|LastEffectiveRate]</LookUpChangeRateBy>
</RateChange>
</RateLookup>
</RateType>
</GuaranteedInterestRate>
<CurrentInterestRate>
<RateType TYPE="[Static|Lookup]">
<StaticRate>[valid rate]</StaticRate>
<RateAsPercent>[Yes|No]</RateAsPercent>
<RateLookup>
<Math>
<MathVariables>
<MathVariable>[math statement]</MathVariable>
</MathVariables>
</Math>
<RateDescription>[valid rate description]</RateDescription>
<EffectiveDate>[valid date]</EffectiveDate>
<DateCriteria OPERATION="[valid operation]" DEFAULT="default value]">[valid date]</DateCriteria>
<Criteria>
<RateCriteria NAME="[column name]" OPERATION="[LT|GT|EQ|LTEQ|GTEQ]" DATATYPE="[TEXT|DATE|INTEGER|DECIMAL]" DEFAULT="[default value]">[criteria value]</RateCriteria>
</Criteria>
<RateChange TYPE="[Never|ReferenceDate|Immediate]">
<ReferenceDate>[valid date]</ReferenceDate>
<EffectivePeriod INTERVAL="[Years|Months]">[0 | 1 | 2 | 3 | ...]</EffectivePeriod>
<LookUpChangeRateBy>[LastRateAtDuration|LastEffectiveRate]</LookUpChangeRateBy>
</RateChange>
</RateLookup>
</RateType>
</CurrentInterestRate>
<AdditiveInterestRates>
<AdditiveInterestRate CODE="[code value]">
<RateType TYPE="[Static|Lookup]">
<StaticRate>[valid rate]</StaticRate>
<RateAsPercent>[Yes|No]</RateAsPercent>
<RateLookup>
<Math>
<MathVariables>
<MathVariable>[math statement]</MathVariable>
</MathVariables>
</Math>
<RateDescription>[valid rate description]</RateDescription>
<EffectiveDate>[valid date]</EffectiveDate>
<DateCriteria OPERATION="[valid operation]" DEFAULT="default value]">[valid date]</DateCriteria>
<Criteria>
<RateCriteria NAME="[column name]" OPERATION="[LT|GT|EQ|LTEQ|GTEQ]" DATATYPE="[TEXT|DATE|INTEGER|DECIMAL]" DEFAULT="[default value]">[criteria value]</RateCriteria>
</Criteria>
<RateChange TYPE="[Never|ReferenceDate|Immediate]">
<ReferenceDate>[valid date]</ReferenceDate>
<EffectivePeriod INTERVAL="[Years|Months]">[0 | 1 | 2 | 3 | ...]</EffectivePeriod>
<LookUpChangeRateBy>[LastRateAtDuration|LastEffectiveRate]</LookUpChangeRateBy>
</RateChange>
</RateLookup>
</RateType>
</AdditiveInterestRate>
</AdditiveInterestRates>
</InterestRateCalculation>
<InterestRateCalculation>
<InterestType SIMPLEINTERESTREFERENCEDATE="[valid date]">[Compound|Simple]</InterestType><LeapYearMethod>
<Method YEAR="[Calendar|ReferenceDate|365|360]">
<MethodReferenceDate>[valid date]</MethodReferenceDate>
<Method365IncludeLeapDayInNumerator>[Yes|No]</Method365IncludeLeapDayInNumerator>
</Method>
</LeapYearMethod>
<MaintainMonthEnd>[Yes|No]</MaintainMonthEnd><InterestPeriod>[Begin|End]</InterestPeriod>
<ValueAsOfPreviousDate>[Yes|No]</ValueAsOfPreviousDate>
<CalculationScale>[0 | 1 | 2 | 3 | ... | 99 | 100]</CalculationScale>
<GuaranteedInterestRate USERATE="[Higher|Lower]">
<RateType TYPE="[Static|Lookup]">
<StaticRate>[valid rate]</StaticRate>
<RateAsPercent>[Yes|No]</RateAsPercent>
<RateLookup>
<RateAsPercent>[Yes|No]</RateAsPercent>
<Math>
<MathVariables>
<MathVariable>[math statement]</MathVariable>
</MathVariables>
</Math>
<RateDescription>[valid rate description]</RateDescription>
<EffectiveDate>[valid date]</EffectiveDate>
<DateCriteria OPERATION="[valid operation]" DEFAULT="default value]">[valid date]</DateCriteria>
<Criteria>
<RateCriteria NAME="[column name]" OPERATION="[valid operation]" DATATYPE="[valid datatype]" DEFAULT="[default value]">[criteria value]</RateCriteria>
</Criteria>
<RateChange TYPE="[Never|ReferenceDate|Immediate]">
<ReferenceDate>[valid date]</ReferenceDate>
<EffectivePeriod INTERVAL="[Years|Months]">[0 | 1 | 2 | 3 | ...]</EffectivePeriod>
<LookUpChangeRateBy>[LastRateAtDuration|LastEffectiveRate]</LookUpChangeRateBy>
</RateChange>
</RateLookup>
</RateType>
</GuaranteedInterestRate>
<CurrentInterestRate>
<RateType TYPE="[Static|Lookup]">
<StaticRate>[valid rate]</StaticRate>
<RateLookup>
<RateAsPercent>[Yes|No]</RateAsPercent>
<Math>
<MathVariables>
<MathVariable>[math statement]</MathVariable>
</MathVariables>
</Math>
<RateDescription>[valid rate description]</RateDescription>
<EffectiveDate>[valid date]</EffectiveDate>
<DateCriteria OPERATION="[valid operation]" DEFAULT="default value]">[valid date]</DateCriteria>
<Criteria>
<RateCriteria NAME="[column name]" OPERATION="[valid operation]" DATATYPE="[valid datatype]" DEFAULT="[default value]">[criteria value]</RateCriteria>
</Criteria>
<RateChange TYPE="[Never|ReferenceDate|Immediate]">
<ReferenceDate>[valid date]</ReferenceDate>
<EffectivePeriod INTERVAL="[Years|Months]">[0 | 1 | 2 | 3 | ...]</EffectivePeriod>
<LookUpChangeRateBy>[LastRateAtDuration|LastEffectiveRate]</LookUpChangeRateBy>
</RateChange>
</RateLookup>
</RateType>
</CurrentInterestRate>
<AdditiveInterestRates>
<AdditiveInterestRate CODE="[code value]">
<RateType TYPE="[Static|Lookup]">
<StaticRate>[valid rate]</StaticRate>
<RateLookup>
<RateAsPercent>[Yes|No]</RateAsPercent>
<Math>
<MathVariables>
<MathVariable>[math statement]</MathVariable>
</MathVariables>
</Math>
<RateDescription>[valid rate description]</RateDescription>
<EffectiveDate>[valid date]</EffectiveDate>
<DateCriteria OPERATION="[valid operation]" DEFAULT="default value]">[valid date]</DateCriteria>
<Criteria>
<RateCriteria NAME="[column name]" OPERATION="[valid operation]" DATATYPE="[valid datatype]" DEFAULT="[default value]">[criteria value]</RateCriteria>
</Criteria>
<RateChange TYPE="[Never|ReferenceDate|Immediate]">
<ReferenceDate>[valid date]</ReferenceDate>
<EffectivePeriod INTERVAL="[Years|Months]">[0 | 1 | 2 | 3 | ...]</EffectivePeriod>
<LookUpChangeRateBy>[LastRateAtDuration|LastEffectiveRate]</LookUpChangeRateBy>
</RateChange>
</RateLookup>
</RateType>
</AdditiveInterestRate>
</AdditiveInterestRates>
</InterestRateCalculation>
