Define Formula Expressions
This is where you build business formulas based on your business needs. Using pre-defined arguments, you can structure a formula into steps and test it. The formula expressions support different types of results (simple or collection).
To define a formula expression:
- Open the Main Menu in FintechOS Studio and select Automation Blocks > Business Formulas > Formula
- Click Insert at the top right corner of the page.
- Enter a Name for the formula.
- Select the Start Date when you wish to activate the formula (see Formula Versioning). By default, it uses the current date and time.
- In the Formula Input field, select the set of arguments that will be processed by the formula (see Define Formula Inputs for details).NOTE
Once you Activate a Formula, you can no longer change the formula input.
- The End Date and Version fields are populated automatically based on the formula's versioning. For details, see Formula Versioning.
- Tick the Is Audited checkbox if you wish to track the formula usage. This will save auditing details in the
EbsMetadata_FTOS_CALC_FormulaAudittable every time the formula is run.
- Click Save and Reload.
Add steps to a formula
Steps allow you to process a formula in successive stages and to use the output from a step as an input argument in subsequent steps.
For example, you can create a formula that calculates the premium amount in the first step, then use the result as an input in the second step to calculate the monthly payment installments (by dividing the premium amount to the number of months).
- In the formula screen, in the Formula Steps section, click Insert to add a step. This will open the Add Formula Step screen.
- Enter a Name for the step. The name must be unique in the formula (Two steps can be named the same, but must be in different formulae.) This name can be used in subsequent steps as an input argument.
- The Formula Id field is automatically populated with your formula name.
- Check the Exclude From Mapping checkbox if you want to disable the output parameter mapping for the step (see Formula Parameter Mapping for details). This is useful, for instance, if you wish to safely test your formula without affecting entries in the database.
- In the Master Type field select the data type for the step's result. This can be either Simple Type (a single value) or Collection (a set of multiple values).
If the master type is a Collection, you will have to specify in the Number of Iterations field the formula argument that will be iterated to generate the collection.
For example, to generate a collection with the first x numbers in Fibonacci sequence, use a whole number input argument called x for the number of iterations (make sure x is greater than or equal to 2) and use the following formula expression:
“result = 1;
result[i] = result[i-1] + result[i-2];”Simple Type
This stands for the following types of data parameters:
Data type Example Whole number 30000 euros - income Decimal 350.78 GBP - rent expenses Boolean Is married - marital status Text Construction type e.g. wood - quality of the object for insurance Object
It is a grouping of arguments that are connected.
e.g. “Age”: “WholeNumber”,
This stands for the following types of data parameters:
Data type Example Whole number 30000 euros -income Decimal 350.78 GBP - rent expenses
List of insurable goods in a house.HINT
Where the formula body is complex, needs periodic update or must be simplified for transparency and traceability, we suggest you split it in separate steps, each with its own expression. This architecture allows calling the result of step N-1 in step N (“result = step 1 + a;”).
In the Sub-Type field, enter the data type for the step's result:
- Whole Number
- Boolean - only for Simple Type master types
- Text - only for Simple Type master types
- Object - only for Simple Type master types
- Calculation Type can be set as either Normal or as an Iteration, in which case you will have to specify the formula argument that will be iterated in your formula. Current Formula Step cannot be set as iteration argument.
- Enter the expression for the formula step in the Formula field. For details, see Formula Editor.
- Click Save and Close .
- Repeat for any additional steps you wish to include in your formula. The output from a step can be used as an input argument in subsequent steps. NOTE
New formula steps cannot be added on an active formula. To add steps to a formula create a new versioning (see Formula Versioning).
After you've added all the steps, click Save and Close .
The order used for each step is indicated in the Oder Index column on the right in the grid.
Test Your Formula
You can create various tests for a formula to see how it performs.
To create a formula test:
- In the formula screen, in the Formula Tests section, click the Insert button to add a test.
- Enter a Name for your test.
- Enter a Reference Date for the test. By default this will be the current date and time. This allows you to test your formula with various data set versions, for instance with a data set that will become active in the future (see Data Set Versioning).
- The Formula field will be automatically populated with the formula name.
- Click Save and Reload. A new button will appear called ''Test Formula''.
- Edit the Input field with the desired input parameters. This field is filled in automatically with the input form the formula and with default values for each argument from this input. The user can just insert some values, not necessarily arguments.
- Click the Test Formula button at the top right corner of the page.
- Check the Execution Successful checkbox and the Output field to investigate the formula execution.
If the result is an error a new text box will appear. In the text box, the system will retrieve the reason for the error.
When you first create a formula, it will be in a Draft state, meaning that it can be edited and tested, but not used by the system. Users cannot create a new version from this state by clicking the button ''Create new version'' on the right-side of the screen.
To activate a formula draft, in the formula page, click the Next Status: Active field in the top left corner of the screen.
The activation stage implies new conditions for the formula:
- it is possible to create a new version of the formula
- the formula has at least one step
- the form is readonly
- when a versioned formula goes into Active status, the parent formula end date will be updated with the versioned formula start date and its status will be updated to Closed.
- you can no longer update or delete the formula's input.
You can still run a closed version of a formula with the server.formula.runFormula Server SDK method.
Once activated, you can revert an active formula to the draft status only if:
- Its start date/time is later than the current date/time.
- There is no other draft created in a newer formula version (see Create a New Formula Version Draft).
Otherwise, an active formula can only go into the Closed state.
Clone a Formula
After activation, you can create a clone of that formula by clicking the Clone button at the top-right corner of the screen.
This allows you create variations based on the same formula as a starting point.
A formula that is currently in use cannot be modified. Instead, a ''Create New Version'' button will appear in the top right corner of your formula page. This button will allow anyone to create a new version of the same formula and a user will be able to make modifications for the new version. It will create a new version with start date today or the start date of the formula if it is in the future.
Click the Create New Version button to create a new Draft version based on the active formula. You can edit the draft version while the active formula is still enabled. It will have the same name as the original one, but the version number will be increased by one, and the start date will be current date, or start date of the previous version plus one day. To find the New Formula Version Draft, open the formula you wish to change and click the History tab where all modifications are shown.
The start date of the new version must be later than or equal to the current date and time (v22.1.1 or later).
Activate a Formula Version Draft
Once you finish updating the draft version, change its status from Draft to Active as shown in the Activate a Formula section. The previously active version will be set to a Closed state, and the draft version will become the currently active version.
You can track the formula versions in the History tab of the formula page.
Let's say you have to build a formula to determine the price of the risks for an home insurance. Depending on the construction type and the array of risks, a formula will be written to return the price. The array for the risks are actually coefficients that are whole number e.g. 1, 2, 3, 4, 5.
Firstly, create the input data by creating an argument. In this case we need as arguments the construction type, the structure type and the risks.
Secondly, create the two steps of the formula, where the first step becomes the input argument of the second step. In the first step, we will calculate the array of prices for the risks and in the second step calculate the sum of those prices.
Thirdly, test the formula by adding a data set and in the formula test grid inserting a structure type, a construction type and an array of risk (the coefficient of those risks that mark a real risk).