Our journey with the Encompass 360 Loan Custom Field Calculations continuous in this article too. In this article, we have explained a few other operators like Date-Based Operations, Calendar-Based Operations etc.
Please refer our other two articles on Encompass 360 Loan Custom Field Calculations. They are:
Encompass 360 Loan Custom Field Calculations – Part 1
Encompass 360 Loan Custom Field Calculations – Part 2
Lets touch base Date-Based Operations now.
Date-Based Operations:
| Function | Description | Example |
| Day(x) | Returns the day portion of the date value x. The parameter x must be a valid date or the calculation will fail. | Day([1402]) |
| Month(x) | Returns the month portion of the date value x. The parameter x must be a valid date or the calculation will fail. | Month([1402]) |
| Year(x) | Returns the year portion the of date value x. The parameter x must be a valid date or the calculation will fail. | Year([1402]) |
| DateAdd(period, count, x) | Add a fixed number of days, months, or years to the date value x. The period should be one of “d” (days), “m” (months), or “yyyy” (years). The count is the number of days/months/years to add. If any parameter is invalid, the entire calculation will result in a blank value. | DateAdd(“yyyy”, 1, [1402]) |
| XDateAdd(period, count, x) | Add a fixed number of days, months, or years to the date value x. The period should be one of “d” (days), “m” (months), or “yyyy” (years). The count is the number of days/months/years to add. If any parameter is invalid, an empty value is returned from the function and the calculation will proceed. | XDateAdd(“yyyy”, 1, [1402]) |
| DateDiff(period, x, y) | Computes the difference between the dates x and y in days, months or years. The period should be one of “d” (days), “m” (months) or “yyyy” (years). If any parameter is invalid, the entire calculation will result in a blank value. | DateDiff(“d”, [1402], [1403]) |
| XDateDiff(period, x, y) | Computes the difference between the dates x and y in days, months or years. The period should be one of “d” (days), “m” (months) or “yyyy” (years). If any parameter is invalid, an empty value is returned from the function and the calculation will proceed. | XDateDiff(“d”, [1402], [1403]) |
| XDate(x, default) | Converts the value x to a date. If x is a string, the date value it represents is returned. If the value cannot be converted successfully, the optional default value is returned. If no default is provided, the date 1/1/1 is returned. | XDate([1402], “11/30/2010”) |
| XMonthDay(x, default) | Converts the value x to a “month-day” value. A month-day is represented as a date within the year 2010. For example, XMonthDay(“3/15”) would return the date 3/15/2010. If the value cannot be converted to a month-day value, the optional default is provided. | XMonthDay(“3/15”) |
| Today | Returns today’s date. | DateAdd(“d”, 7, Today) |
Calendar-Based Operations:
| Function | Description | Example |
| Calendar.AddBusinessDays (date, count, moveToNext) | Adds the specified number of days from your company’s Business Calendar to the date provided. The moveToNext parameter is a Boolean which indicates if the date should first be advanced to the next business day if the date specified is not a business day. | Calendar.AddBusinessDays ([763], 5, true) |
| Calendar.AddPostalDays (date, count, moveToNext) | Adds the specified number of days from the US Postal Calendar to the date provided. The moveToNext parameter is a Boolean which indicates if the date should first be advanced to the next business day if the date specified is not a business day. | Calendar.AddPostalDays ([763], 5, true) |
| Calendar.AddRegZBusinessDays (date, count, moveToNext) | Adds the specified number of days from the Reg-Z Business Day Calendar to the date provided. The moveToNext parameter is a Boolean which indicates if the date should first be advanced to the next business day if the date specified is not a business day. | Calendar.AddRegZBusinessDays ([763], 5, true) |
Branching and Logic Operations
Many custom calculations require complex branching (if…then) logic in order to arrive at the desired value.
To accommodate this need, the custom calculations provide the IIF() function, which can be used to express if…then…else logic. The basic syntax of this function is as follows:
IIF(Boolean expression, True value, False value)
The first argument to IIF() is an expression that evaluates to either TRUE or FALSE. If that expression evaluates as TRUE, then the IIF function returns the value specified in the second parameter (the “True value”). Otherwise, the IIF function returns the third parameter, the “False value.”
For example, the following custom calculation returns 2% of the loan amount for loan amounts above $100,000 and 5% of the loan amount for loans below $100,000:
IIF([1109] > 100000, 0.02 * [1109], 0.05 * [1109])
The Boolean expression of an IIF statement can use the AND and OR operations to perform more complex logic, for example:
IIF([1109] > 100000 AND [1335] < 20000, 0.02 * [1109], 0.05 * [1109])
Often, you may encounter the need to handle more than just two cases (a TRUE case and a FALSE case). In these scenarios, you can use nested IIF statements. For example, the following code demonstrates performing a calculation based on the purpose of the loan.
IIF([1811] = “PrimaryResidence”, 0.05 * [1109],
IIF([1811] = “SecondHome”, 0.02 * [1109],
IIF([1811] = “Investor”, 0.01 * [1109], 0)))
The expression above evaluates to 5% of the loan amount if the loan is for the borrower’s primary residence, 2% if it’s a second home, 1% for an investment property and return the value “0” if the loan purpose has not yet been specified.
IMPORTANT: When the IIF function is invoked, the calculation engine first evaluates both the second and third parameters of the function before evaluating the Boolean expression. Therefore, both parameters need to evaluate to valid values even though only one value will be used. For example, the following IIF statement will fail.
IIF(5 > 0, 1, 2 * [4000])
The expression 2 * [4000] is typically invalid since field 4000 contains the borrower’s first name (which is typically not numeric). Even though the logical expression 5 > 0 will always evaluate to TRUE (and thus the value returned by IIF will always be 1), the failure of the third parameter to evaluate successfully will cause the entire calculation to fail.
To work around this issue, you can use any of the following techniques:
• Use the safe arithmetic operations, e.g. IIF(5 > 0, 1, Mult(2, [4000])). These operations ensure that no errors will occur.
• Use the field modifiers, e.g. IIF(5 > 0, 1, 2 * [#4000]). The numeric conversion modifier will convert non-numeric values to 0, allowing the calculation to be carried out successfully (refer to “Calculation Errors” on page 9).
• Use a combination of two custom fields, for example:
CX.FIELD1 = 2 * [4000]
CX.FIELD2 = IIF(5 > 0, 1, [CX.FIELD1])
When field 4000 is non-numeric, the calculation for field CX.Field1 will be invalid and, as a result, the field will be blank. However, the expression for CX.Field2 can now be evaluated successfully since the substitution of the value CX.FIELD1 will always work (even if the value happens to be blank).
As a second example, the expression above that branches based on the loan purpose would be rewritten as follows to ensure safe evaluation regardless of the value in field 1109:
IIF([1811] = “PrimaryResidence”, 0.05 * [#1109],
IIF([1811] = “SecondHome”, 0.02 * [#1109],
IIF([1811] = “Investor”, 0.01 * [#1109], 0)))
In addition, the custom calculation engine provides a few functions which can be used to determine the state of a field so you can add condition logic that behaves appropriately
| Function | Description | Example |
| IIF(x, truepart, falsepart) | Returns the truepart if x is true, the falsepart otherwise. | IIF([#1109] > 100000, 10, 20) |
| IsEmpty(x) | Returns a boolean indicating if the value x is the empty string. | IsEmpty([1109]) |
| IfEmpty(x, val) | Returns the value x if it is non-empty, otherwise returns the value val. | IfEmpty([1109], 0) |
| IsNumeric(x) | Returns a boolean indicating if the value x can be converted into a numeric value. | IsNumeric([1109]) |
| IsDate(x) | Returns a boolean indicating if the value x can be converted to a valid date | IsDate([1402]) |
List-Based Operations
Evaluating a custom calculation will frequently require logic which involves looking up a value in list of possible values or within a range of values. These operations could be carried out using one or more nested IIF() expressions as demonstrated above, but the calculation engine offers several functions to simplify this task.
| Function | Description | Example |
| Match(x, value0, value1, …) | Returns the index of the first value in the list that matches x. If not match is found, the value -1 is returned. | Match([608], “Fixed”, “GraduatedPaymentMortgage”, “AdjustableRate”, “OtherAmortizationType”) |
| Range(x, value0, value1, …) | Returns the index of the first value which is greater than x. | Range([1109], 100000, 200000, 500000) |
| RangeLow(x, value0, value1, …) | Returns the index of the first value which is greater than or equal to x. | RangeLow([1109], 100000, 200000, 500000) |
| Pick(x, value0, value1, …) | Returns the value whose index is x. | Pick([#16] – 1, “1 unit”, “2 units”, “3 units”, “4 units”) |
| Count(value0, value1, …) | Returns the number of parameters that are non-empty. | Count([4000], [4002], [98], [99]) |
Using these functions, this calculation:
IIF([1811] = “PrimaryResidence”, 0.05 * [#1109],
IIF([1811] = “SecondHome”, 0.02 * [#1109],
IIF([1811] = “Investor”, 0.01 * [#1109], 0)))
could be rewritten as:
Pick(Match([1811], “PrimaryResidence”, “SecondHome”, “Investor”, “”), 0.05 * [#1109], 0.02 * [#1109], 0.01 * [#1109], 0)
Advanced Functions
The Encompass Custom Calculation Engine leverages the Visual Basic.NET programming language when evaluating your calculation. As a result, you may make use of any function which is provided as part of the VB.NET programming language. For a complete reference of these functions, visit Microsoft’s VB.NET Reference.
Keep in mind that your calculation should not invoke any method which can trigger the display of a user interface of any kind as this can cause Encompass or the Encompass Server to fail.
We hope the articles on Encompass 360 Loan Custom Field Calculations are really useful and helpful when building custom forms and their respective custom fields.
Looking for more information on integrating Encompass 360 with Velocify or need help in integrating right technology, leave us a message.
Take Five Consulting is a technology company, based in Virginia U.S., that specializes in the Mortgage Banking vertical especially LOS implementation and application development. Take Five Consulting creates and implement mortgage technology and software specifically for Mortgage Industry.