Skip to main content

Controlling the Nooxl apps via a REST API

A REST API (Representational State Transfer Application Programming Interface) is an interface that defines the rules and conventions for exchanging data between different software applications over the Internet. The Nooxl REST API uses the JSON format for the exchange of data. By using the REST API, easy integration with third-party services (such as Microsoft Power Automate, Zapier, Zoho Flow, IFTTT, Hubspot Operations Hub,...) can be achieved.

Data exchange with Nooxl apps and automation​

Within the Nooxl apps, most work processes are automated via spreadsheets, such as calculating spreadsheet models or complete Nooxl apps, importing, exporting, copying or saving data and preparing cube data. A REST API is sufficient to control these automation processes from outside. Further options for Excel-compatible Nooxl models can be found in the Nooxl documentation.

Function of the REST-API "model calculate"​

The "model calculate" REST API is used to open a selected Nooxl model with a selected data set in Nooxl Apps, record data, optionally save it and return calculated data from the model. The following steps are performed when calling the REST-API "model calculate" in Nooxl Apps:

1. authorization​

A component of the REST URL is a shortened Nooxl App GUID. When the REST API is called, an API token is also sent, which is used to determine the user of a local login and check their assignment to the Nooxl app. (No further authorization is required to open the Nooxl app).

2. selection of the Nooxl model​

Part of the JSON body of the API call is either the model name or the model ID, which is used to determine the spreadsheet model. It is checked whether the user of the REST-API has the authorization in Nooxl Apps to open the model.

3. selection of the data set​

The data set in the Nooxl cell storage is determined via the names of data labels or their IDs. The order of the data labels in the API call must correspond to the order in the Nooxl apps.

4. loading the model with data​

The system checks whether the user has read permission for the data set. The current version of the model is opened and calculated with the selected data set.

5. input of values​

If an input range was transferred when the API was called, the input values are entered in the spreadsheet cells of the model. The system first checks whether the cells are input cells (input color) and whether actions must be triggered by the input. The model is calculated.

6. saving the data​

If the save option is set, the system checks whether the user has write access to the data set and writes the data to the cell memory.

7. return of values​

The values for the requested areas are read from the model and added to the response. The model is closed and the response is sent.

Use of the REST-API "model calculate"​

The complete OpenAPI definition (Swagger JSON) of the REST-API can be downloaded here.

Reading parameters from the Nooxl app​

The following application example shows the use of the REST-API "model calculate" with suitable values for the Nooxl app "API-Demo" with a spreadsheet model "Cash flow" in our demo environment.

Demo registration via Nooxl app

On the demo app apps-demo.nooxl.com you will first be taken to the standard demo app with an automatic login. Please log out of the "Demo Auto Login" first using the menu in the top right corner and log in again. The login (read-only access) is done with :

Login name: API-Tester
Password: ivtP@t>UN>KF9

Without a new login, you are in the standard demo environment and cannot find the required App "API Demo ".

Once you have selected a model with data records, the parameters for the selected elements are visible in the url:

Selection of model and data set in the Nooxl app "API demo" The following parameters required later for the API call can be read from the url displayed in the Nooxl demo app:

  1. this is the host name of the Nooxl web server (and not the associated Nooxl API server!, see below).
  2. this is App-Id nooxlAppNuid with the value tJel71R1YEGFu80GinVMCw.
  3. this is the model ID modelId with the value 3466.
  4. the data set selections modelSelections have the label IDs dataLabelId 97662 and 97664.
  5. as an alternative to the model ID, the model name "Cash flow" can also be used.
  6. as an alternative to the label IDs dataLabelId, a dataLabelName with "2024-01" and "Asset A" can also be used.

There is no alternative with a name for the app ID.

Parameters in the REST-API Url​

The REST-API "model calculate" is called with the following parameters: https://{nooxlApiHostName}/api/v1/app/{nooxlAppNuid}/ModelCalculate

The name of the Nooxl API server nooxlApiHostName depends on the installation and is https://ncs-demo.nooxl.com for our demo example.

This inserts the parameters into the URL as follows: https://ncs-demo.nooxl.com/api/v1/app/tJel71R1YEGFu80GinVMCw/ModelCalculate

Authorization via API token​

When the REST-API Url is called, an Authorization header with the access token Bearer {token} must also be sent. The token is obtained beforehand by calling the REST-API "authenticate".

Parameters in the REST-API body​

In addition to the parameters mentioned above, the inputs dataOutputs, outputs dataOutputMarkupNames and options modelOptions are also defined in the body. The markup names markupName are used for the inputs and outputs. These are only visible to authorized users in design mode and are not available with the demo login.

Input and output parameters of the demo

  1. on the right in the list of markups you will find the markup names that can be used as input or output.
  2. when a markup is selected, the area in the work window is highlighted in red.

For inputs, the input values cellValues are also transferred in a 2-dimensional array of rows of columns. Only the names are specified for outputs. Our example body is then as follows:

REST-API 'model calculate' Request JSON-Body
{ "modelName": "Cash flow",
  "modelSelections": [
    {"dataLabelName": "2024-01"},
    {"dataLabelName": "Asset A"}
  ],
  "dataInputs": [
    {"markupName": "Usage Inputs",
     "cellValues": [
        ["810","16","","20.00","4%"],
        ["245","4","","25.75","4%"],
        ["140","1","","14.80","4%"],
        ["950","15","","14.30","1%"]
      ]
    },
     {"markupName": "Rent Inputs",
     "cellValues": [
        ["20.11","3.00%"],
        ["21.00","2.00%"],
        ["34.70","1.50%"],
        ["15.40","5.00%"]
      ]
    },
    {"markupName": "Parameter Inputs",
     "cellValues": [
        ["1.84%"],["7.79%"],["7.53%"],["466.81"],["1.00%"],["35.00"],["2.00%"],["3.15"],["18.75%"],["2.00%"],["3.73%"],["4.29%"],["1.49%"],["0.00%"],["2.50"],["1.50%"],["5.00"]
      ]
    }
  ],
  "dataOutputMarkupNames":  [
    "Total annual revenue Outputs", "Total annual expense Outputs"
  ],
  "modelOptions": {
    "saveModel": true
  }
}

In the modelOptions options, "saveModel": true can be used to save the model (with sufficient authorization).

Hinweis

The user “API Tester” does not have permission to save data for the demo app.

Result response REST-API​

After calling the REST-API, Nooxl Apps returns a response body if successful. In case of an error, an error message is returned. The response body for our demo request looks like this:

REST-API 'model calculate' Request JSON-Body
{
    "dataOutputs":[
        {
            "markupName":"Total annual revenue Outputs",
            "cellValues":[
                ["477,715.82","493,584.47","502,651.10","512,028.82","521,734.43","531,788.61","542,213.04","553,030.50","564,264.85","575,941.13"]
            ]
        },
        {
            "markupName":"Total annual expense Outputs",
            "cellValues":[
                ["221,563.00","223,969.94","226,453.86","228,968.19","231,513.78","234,091.03","236,700.40","239,342.33","242,017.28","244,725.71"]
            ]
         }
    ],
    "errorCodes":[]
}

In the output data, we see the output values 'cellValues' passed in a 2-dimensional array of rows and columns.