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 your first formula

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:

c = r P 1 1 + r N r 0 P N r = 0

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 create a new Formula. After clicking New Formula you can edit details on the right pane:

  • 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:

../_images/pmt-formula.png

Let’s add some documentation

Clicking on the Documentation tab on the right pane (beside the Formula tab) you are taken to your formula documentation edit panel. You can enter markdown according to the Documentation language syntax.

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

Add the rest of the formulas

Add formulas below:

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):

  • Title: Monthly interest rate
  • Formula source: r_'m = (r_'y / 12) / 100
  • Documentation

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.

Clicking on Evaluate and Getting Started (if you had not perviously created any contexts) will take you to the evaluation dialog. Here you can set up your evaluation configurations. (more later on these configurations)

The left panel shows an empty list, saying no variables are selected. 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 Default evaluation context by adding some variables.

To begin with let’s add:

  • T (input) and
  • 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 Calculate will give you a calculation log (on the right) and set the result for N.

../_images/evaluate-n.png

Evaluate the mortgage payment (PMT) formula

Next we configure a new context 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 configuration (click New to the right of the configuration dropdown)
  • name the configuration: PMT-simple
  • add the required variables to the configuration: c, P, r_'y and T

The dialog will look like this:

../_images/variables_to_evaluate_pmt.png

Set all but c as inputs. You might recall that c is our monthly payment amount.

Set the input variable values as in the article:

  • P = 200000
  • r y = 6.5
  • T=30

You can reorder variables if you like by dragging c (grab the icon with horizontal bars on the left) to the bottom

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

Let’s add our rounded c r variable to the outputs too. Recalculating the model should give you this:

../_images/pmt-rounded-evaluation-result.png

This gives us c r = 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 :)

Create your model API

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.
  • 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 T :

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

Input variable r y :

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

Input variable P :

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

Output variable c r :

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

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

../_images/pmt-api-variables.png

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 screen-shot below:

../_images/default-build-result.png

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:
../_images/ws-call-parameters.png

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:

../_images/ws-call-result.png

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.