Getting Started With Modules

This is an extension of the basic getting started. In this guide we will extend the refactor the basic model in order to support two alternative use-cases:

  1. the interest rate is passed in to the calculation from an external source (external interest rate)
  2. the interest rate is calculated from the client’s credit score (interest rate from score)

What is a Module

In the first getting started we did not use explicit modules.

However, modules allow the modeller to structure their project and create a logical collection of formulas and table resources. A Module structure can be used for several purposes :

  • segment a model (e.g. different formulas for A and B products put into two respective modules)
  • model a formula hierarchy where modules build on each other (complex calculations built on top of some more basic ones)
  • override certain formulas so that when calculations are defined, different set of modules provide different implementations for the same formulas)
  • etc.

We opted against hierarchical module structure to keep projects easier to work with, so you cannot create modules within modules.

Our use of modules in this context

You might recall we have a variable named r m . We will create two separate formulas to calculate this variable to support our use-cases.

Refactor the model for the external interest rate case

  1. Create a new module for the mortgage formula:
  • name: PMT
  • description: Payment calculation example
  1. Create another one for the interest rate formula:
  • name: Interest from input
  • description: Monthly Interest calculation based on yearly interest input


You might want to note down name and description of the module as markdowns.

At this point your model should look like this:


It is time to move modules into their places:

  1. Select three formulas shown (ctrl+click) below and click Move to move formulas to the PMT Module.

The move dialog:


Shows moving Formulas to the new module.

  1. When you navigate back to the Main module you will find a single formula - the monthly interest rate formula - there. Move it to the Interest from Input module.
  2. Click on the workbook named Getting started to set the new modules in the 2 contexts we have previously created:
  • In the Gettings started context select the PMT module.
  • In the PMT-simple context select the PMT and Interest from input modules.

This will show the variables correctly defined.

Now that formulas are placed in modules, you will need to refactor the API to tell it to include them.

  1. Open the sidebar and select API
  2. Click into the Calculation Group Mortgage PMT. You will see the Calculation PMT and all variables coloured red, telling you that these can not be resolved.
  1. The Modules dropdown you find Main module, click into it and select both PMT and Interest from input modules.

The above figure shows that variables are resolved, red coloring disappeared after selecting the modules including the specified variables in the API.

  1. Rebuild the Build and try it: Open the sidebar and select Deployment, click Build button on the top right

With this we have refactored our existing functionality into Modules.

Add interest rate calculation based on Scoring

Next you will add the interest rate calculation based on scoring. The calculation is very simple, it will lookup an annual percentage rate (apr) from a table based on the client’s score.

The score to rate table is the following:

From To Rate
760 850 4.17
700 759 4.392
680 699 4.569
660 679 4.569
640 659 5.213
620 639 5.759

You will need to take the row where the given score is between the from and to values and return the Rate.

The modifications are the followings (we will not detail tasks you already know):

  1. Create a new module
  • Name: Interest from Scoring
  • Description: Interest rate calculation with scoring parameter
  1. Create a new table within this module (click on the plus sign, choose Table/Upload option)
  • Name: F
  • Description: FICO Score table


You can create table manually too with choosing Table/New option.

  1. Download the provided CSV and save it for the next step:

Download this CSV

  1. Click on Local file to upload the file you downloaded in the previous step.
  2. Select Use first row as header in layout option:

Scoring table

  1. Now create the formula that will select the right row from the table:
  • Title: Select APR with the given score
  • Formula source: apr = ((e)_'APR | e (- @F : (e)_'From <= Score /\ (e)_'To >= Score)
Dissecting the above:
  • apr = : tells we are going to assign a value to the apr variable
  • e (- @F : tells e is an element of the F resource table, the at sign marks table resources
  • (e)_'APR : tells the table query will return the APR column from the table
  • (e)_'From <= Score && (e)_'To >= Score : this is the query part that says we need the element where the Score is between the From and To columns
  • Score : remember that in this use case this variable value will be passed into the calculation
  1. Last formula in this exercise is to calculate monthly interest rate from apr. Create a new formula (still in the Interest from Scoring module)
  • Title: Calculate monthly interest rate
  • Formula source: r_'m = (apr / 12) / 100
  • Documentation: Calculate monthly interest rate from APR

Here is how should your module look like now:


Evaluate the APR selection formula

While we are here, let’s evaluate the table selection formula.

Create a new workbook for testing score selection.

  • workbook name: APR
  • module import: Interest from scoring
  • variables as formulas in configuration:
    • Score (input) and
    • apr (output)

Set Score to 760 and click Run all. You should see the result 4.17 displayed for our apr variable. If you want, you can add r m too to see it’s value set.


Create the Scoring API

Let’s now create the Scoring API which is based on the client’s score instead of the annual interest rate passed into the service.

Navigate to the API menu (left sidebar)

  • Click New Calculation Group button.
    • Set the Name of the Calculation Group to MortgagePMTFromScore. Leave the API ID to it’s default.
    • Set the Modules included in the Calculation Group scope to PMT and Interest from Scoring
  • Click New Calculation button.
    • Set the name of the Calculation to PMT. Leave the API ID to it’s default.
  • Select input variables: Score, T, P
  • Select output variable: c r

Similar to the mortgage from input interest rate case, you will need to specify some details for the users of your API:

Input variable Score :

  • API Id: clientScore
  • Domain: %Z_+ (positive or zero real)

Input variable T :

  • API Id: term
  • Domain: %Z_+ (positive or zero integer)

Input variable P :

  • API Id: principal
  • Domain: %R_+ (positive or zero real)

Output variable c r :

  • API Id: monthlyPayment
  • Domain: %R (any real)

To also give further documentation for your API client developers, add this documentation to the API elements:

  • General description: PMT formula from FICO score
  • inputs:
    • term: term in years
    • clientScore: client's FICO score
    • principal: principal of loan
  • output:
    • monthlyPayment: monthly loan payment


One of the goals of this exercise was to show how to use modularization to expose different APIs of the same model to different clients.

Let’s now imagine a fictitious back-office application that will calculate the score (maybe calling another Formulative API) and pass this score into Formulative to get the loan payment amount. For this we need another secure client endpoint that includes this new API. To achieve this we will first create a new Build Configuration and a new Client.

To create the Build configuration:

  • Open the sidebar and select Deployment
  • Click New (New Build Config)
  • Name: MortgagePMTFromScore
  • Select only the MortgagePMTFromScore calculation group
  • Enable the Web Service target
  • Click Create to create the new Build Configuration

Build configuration

  • Create a Draft Build for this Build configuration - just click Build and follow the wizard.

When you are done with Building you will be returned to the Build Configuration’s build list:


Build list

Since this is not your first Build, there are no defaults provided:

  • your Build will not be configured to be accessible to the existing Client Application
  • your Build will not be installed in any existing containers.

To fix these, do the followings:

  • Click Access above to tell which Client Applications will have access to your new API.
  • Click Create Client Application to create a new application and name it internal-app
  • Click Save

Internal Client Application

Install your Build’s Web Service Target on your default container:
  • Click Install Web Service
  • Leave the Default Container selected and click Install


You could have opted to create a new Container for your new API. We leave it to you this time to try that if you want.

Once installed, you can test your web service to see if it is working:

  • Click into the Draft Build card
  • Click on the Web Service tab
  • Click Get Token
  • Scroll down to the mortgagePmtFromScore section (open it)
  • Fill in the request body parameters
  • Click Execute

Web Service Call parameters to test the deployed mortgage service

Once you executed the service call, you will see the calculation results.


In this extension we showed you how to:

  • organize model resources into modules
  • work with tables
  • keep some common Formulas in a shared module
  • separate two variations of calculating the monthly rate into separate modules
  • created two separate, secure endpoints (client applications) for the two APIs. One maybe an external portal, while the other some in-house application.