Getting Started

To get started we show you how to implement a mortgage calculation and publish it as a scalable web service in a couple of minutes.

The model shown is simple, taken from the public domain, a mortgage calculation formula on Wikipedia

Prerequisites

You should be registered and should be able to login to Formulative.

Create a project

Once you signed in you are taken to your Projects list. Click New Project to create your mortgage calculation project:

• Name: Mortgage
• Description: Fixed rate mortgage calculation example

Don’t bother with the API ID for now.

Create a module

Click on the plus sign and choose Module:

• Name: Main module

It is time to get your feet wet, let’s create the first Formula. Checking out the Wikipedia documentation for the Monthly payment formula, you will see this:

$\mathit{c}=\left\{\begin{array}{ll}\frac{\mathit{r}\mathit{P}}{\left(\mathrm{1}-{\left(\mathrm{1}+\mathit{r}\right)}^{-\mathit{N}}\right)}& \mathit{r}\ne \mathrm{0}\\ \frac{\mathit{P}}{\mathit{N}}& \mathit{r}=\mathrm{0}\end{array}\right\$

We will not get deeper this time into what the formula means (you can check the Wikipedia) article for that). It is enough to see that this is basically a switch case formula that provides two expressions for two cases:

• one for the case when we have a non zero interest rate
• one for the case when the interest rate is 0.

Checking the Formula Language Reference you can find that there is a switch construct (miscellaneous section). One way to develop formulas is to copy-paste these into your own Formulas. Here we do not do that but give you the final Formula instead, so simply go ahead and click on the plus sign in the right pane. First choose Markdown to write the title of the formula than create a Formula:

• Title: ## Mortgage payment (PMT) formula
• Formula source: c = {{  r_'m P/(1-(1+r_'m)^{-N}) # r_'m /= 0 ## P/N # r_'m = 0 }

You might add a bit of formatting to your formula to look like this:

Add a Markdown section again by clicking plus sign. You can enter markdown according to the Documentation language syntax.

download this file and copy-paste it into the editor.

Add the rest of the formulas

Number of months in term:

• Title: ## Number of months in term
• Formula source: N = T * 12
• Documentation: Number of months in term, calculated from **T** the term in years.

Monthly interest rate (from yearly):

Payment rounding:

• Title: ## Rounded Payment
• Formula source: c_'r = $round_2 c • Documentation: Round the payment to 2 decimal places. You might note the followings: • we do not need to use the asterisk to use multiplication (similar to math formulas) • we used an internal function to round the calculated monthly payment, the decimals to round to is expressed with the lower subscript. With this entered let’s go on to evaluating and publishing our Mortgage Service. Evaluating your model Up until now you have been editing your formulas, you can do that in any text editor too. Now comes the interesting part, let’s get on to actually see what the formulas do. The left pane has another list above the modules, the Workbooks section. We created an empty workbook for you. First rename the workbook to Getting Started with the Rename option under the options menu. Click the workbook to open a new tab on the right. Now if you look at the right pane than you can see a square icon next to the plus sign. Click on that, choose the Main module from the list. This way you can configure which modules would you like to try. When entering the Formulas you might have noticed that some variables are calculated by the math expressions you edited while others are not defined by the model. We call these (not surprisingly) input and output variables. Let’s start editing the Getting Started evaluation context by adding some variables. To begin with let’s add: • $\mathit{T}$ (input) and • $\mathit{N}$ (output) While T is input N is calculated from T so, let’s set their attributes accordingly. Input variables need some data too, so add 30 for T. Clicking on Run all will set the result for N. Your result should look like this: Evaluate the mortgage payment (PMT) formula Next we configure a new workbook to see how our PMT formula works. We will use the example from the wikipedia article to check the result. According to this, the monthly payment for a home loan of$200,000 with a fixed yearly interest rate of 6.5% for 30 years is 1264.14.

Let’s see if we get to the same result:

• create a new workbook (click the plus icon next to the Model and select Workbook)
• name the workbook: PMT-simple
• import the required module: Main module
• add the required variables: c, P, r_'y and T

It will look like this:

Set the input variable values as in the article:

• P = 200000
• ${\mathit{r}}_{\mathsf{y}}$ = 6.5
• T=30

Set all but c, you might recall that c is our monthly payment amount.

Note

You can reorder formulas if you like by select them and use the arrow buttons above.

Now, if you ask the engine to run the formulas, the result you will get a long decimal for c.

Let’s add our rounded ${\mathit{c}}_{\mathsf{r}}$ variable to the outputs too. Recalculating the model should give you this:

This gives us ${\mathit{c}}_{\mathsf{r}}=\mathrm{1264.14}$ which is the same as our reference example. In an extension of this tutorial you will see even more sophisticated ways of testing your model :)

Let’s rush on and skip testing for now. You have the calculation model and you want to create an API for calling the payment calculation function. Similar to how you define an evaluation configuration, calculations also need a configuration specifying the input and output variables (and some other details).

Start by opening the left sidebar and select the API menu.

• Click New Calculation Group button.
• Set the Name of the Calculation Group to MortgagePMT. Leave the API ID to it’s default.
• Select Main module in Modules.
• Click New Calculation button.
• Set the name of the Calculation to PMT. Leave the API ID to it’s default.
• Select input variables: P, r_'y, T
• Select output variable: c_'r

Once you have done this, you need to give some more details that will help users of your API. Setting API IDs will give the API caller a meaningful name and specifying the Domain will make data conversion unambiguous.

Input variable $\mathit{T}$:

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

Input variable ${\mathit{r}}_{\mathsf{y}}$:

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

Input variable $\mathit{P}$:

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

Output variable ${\mathit{c}}_{\mathsf{r}}$:

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

If you were following, your API should look like this:

You might further help your API user by documenting the API and it’s variables on the Documentation tab (next to the Variables tab)

• General description: PMT formula, see wikipedia
• inputs:
• term: term in years
• interestYearly: yearly interest rate (as a decimal, e.g. 6.5)
• principal: principal of loan
• output:
• monthlyPayment: monthly payments

Deployment

Almost there, we have the model and defined our API. One last thing to do before your client applications can use your API is to do the deployment.

Note

This functionality might be outside the comfort zone of a domain expert. If your role does not require you to know about Web Services, HTTP endpoints and such, you might just as well skip the rest of this tutorial.

Do this to deploy your model as a web service:
• Open the sidebar and select Deployment
• Click Build, it will launch a Build Wizard and should tell you that no errors were found with your model in it’s first step
• Click Next, this step in the wizard checks your model for changes since the last build, since there were no builds yet all your API definnitions will be shown as new
• Click Build again on the last panel, this will actually trigger generating code and documentation for the API
• If everything goes well, you should see the success message.

During this process some defaults were used in order to make the first steps easier. One default taken is the Web Service target in the build that resulted in a web service deployment created from your model. Looking at the screenshot below:

Clicking into the Build above (click anywhere on the Draft Build panel) you are taken to the Build results overview and for each target you have a tab that let’s you access the specific Build Target.

Next Click on the Web Service tab and follow the steps below:

• Click Manage Access, this bring you to your current client applications (a proxy for the application you intend to integrate your API with)
• Click Create Application to actually create one (you probably do not have any) - Give the application a name like mortgage-portal and click Create
• Click Save
• Click Get Token below: this will get a token for the client application just created. Do not bother for now, it is there to demonstrate the steps required to use the API.
• Click into Invoke Calculation to see how you can make a test call to your deployed Web Service.
• Fill in the body (params section) of the request parameters as on the screen below:

Click on Execute below the request body.

After waiting for a few seconds (initial deployment takes some secs) you should see the results from our deployed web service:

Summary

With this we conclude this beginner’s guide, In summary we have shown you how to create a simple mathematical model and publish it to the web in a couple of minutes. Admittedly the model was simple, having said that we found that even moderately complex models can stay close to their source mathematical form.

Deploying your model is a straight-forward process, and you are ready to start integrating calculations into applications.

There are more features regarding each step in the process, which we could not cover in this guide. See other guides related to:

We hope you enjoyed following through and thank you for your time with us. You can help our work if you give us feedback on your thoughts.