Zum Hauptinhalt springen

Steuerung der Nooxl Apps über ein REST-API

Eine REST-API (Representational State Transfer Application Programming Interface) ist eine Schnittstelle, die die Regeln und Konventionen für den Austausch von Daten zwischen verschiedenen Softwareanwendungen über das Internet definiert. Das Nooxl REST-API verwendet das JSON Format für den Austausch von Daten. Durch die Verwendung des REST-API kann eine einfach Integration mit Drittanbieterdiensten (wie z.B. Microsoft Power Automate, Zapier, Zoho Flow, IFTTT, Hubspot Operations Hub,...) erreicht werden.

Datenaustausch mit Nooxl Apps und Automatisierungen​

Innerhalb der Nooxl Apps werden die meisten Arbeitsprozesse über Spreadsheets automatisiert, wie z.B. das Berechnen von Spreadsheet-Modellen oder kompletter Nooxl Apps, das Importieren, Exportieren, Kopieren oder Speichern von Daten sowie das Aufbereiten von Cube-Daten. Für die Steuerung dieser Automatisierungsprozesse von außerhalb reicht eine REST-API aus. Weitere Möglichkeiten der Excel-kompatiblen Nooxl Modelle finden Sie in der Nooxl Dokumentation.

Funktion des REST-API "model calculate"​

Über das REST-API "model calculate" werden ein ausgewähltes Nooxl Modell mit einem ausgewähltes Datensatz in Nooxl Apps geöffnet, Daten erfasst, optional gespeichert und berechnete Daten aus dem Modell zurückgegeben. Folgende Schritte laufen beim Aufruf des REST-API "model calculate" in Nooxl Apps ab:

1. Autorisierung​

Ein Bestandteil der REST-URL ist eine verkürzte Nooxl App GUID. Beim Aufruf des REST-API wird ein API-Token mit gesendet, über den der Nutzer einer lokalen Anmeldung ermittelt wird und seine Zuordnung zur Nooxl App geprüft wird. (Es ist keine weitere Berechtigung zum Öffnen der Nooxl App nötig.)

2. Auswahl des Nooxl Modells​

Ein Bestandteil des JSON-Body des API-Aufrufes ist entweder der Modell-Name oder die Modell-Id anhand das Spreadsheet-Modell ermittelt wird. Es wird geprüft, ob der Nutzer des REST-API die Berechtigung in Nooxl Apps hat, das Modell zu öffnen.

3. Auswahl des Datensatzes​

Über die Namen von Datenlabel oder deren Ids wird der Datensatz im Nooxl Zellspeicher ermittelt. Die Reihenfolge der Datenlabel beim API-Call muss der Reihenfolge in den Nooxl Apps entsprechen.

4. Laden des Modells mit Daten​

Es wird geprüft, ob der Anwender ein Leserecht auf den Datensatz hat. Die aktuelle Version des Modells wird mit dem ausgewählten Datensatz geöffnet und berechnet.

5. Eingabe von Werten​

Falls einen Input-Bereich bei Aufruf des API mit übergeben wurde, werden die Input-Werte in die Spreadsheet-Zellen des Modells eingegeben. Dabei wird vorher geprüft ob die Zellen eine Eingabezelle ist (Eingabefarbe) und ob Aktionen durch die Eingabe ausgelöst werden müssen. Das Modell wird berechnet.

6. Speichern der Daten​

Wenn die Speichern-Option gesetzt ist, ob der Anwender ein Schreibrecht auf den Datensatz hat und die Daten in den Zellspeicher geschrieben.

7. Rückgabe von Werten​

Für die angeforderten Bereiche werden die Werte aus dem Modell ausgelesen und der Antwort hinzugefügt. Das Modell wird geschlossen und die Antwort gesendet.

Verwendung der REST-API "model calculate"​

Die komplette OpenAPI-Definition (Swagger JSON) des REST-API kann hier heruntergeladen werden.

Auslesen von Parametern aus der Nooxl App​

Das folgende Anwendungsbeispiel zeigt die Verwendung des REST-API "model calculate" mit passenden Werten für die Nooxl App "API-Demo" mit einem Spreadsheet-Modell "Cash flow" in unserer Demo-Umgebung.

Demo-Anmeldung über Nooxl App

Auf der Demo App apps-demo.nooxl.com gelangen Sie zuerst zur Standard-Demo-App mit einer automatischen Anmeldung. Bitte melden Sie sich bitte zuerst von der "Demo Auto Login"-Anmeldung mit dem Menü rechts oben ab und melden Sie sich dann neu an. Die Anmeldung (nur Lesezugriff) erfolgt mit:

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

Ohne Neuanmeldung befinden Sie sich in der Standard-Demo-Umgebung und finden die nötige App "API-Demo" nicht.

Nachdem Sie ein Modell mit Datensätzen ausgewählt haben, werden in der Url die Parameter für die ausgewählten Elemente sichtbar:

Auswahl Modell und Datensatz in der Nooxl App "API-Demo" Aus der angezeigen Url in der Nooxl Demo App können die folgenden, später benötigten Parameter für den API-Aufruf ausgelesen werden:

  1. Dies ist der Hostname des Nooxl-Web-Servers (und nicht des zugehörige Nooxl-API-Servers!, s.u.).
  2. Dies ist App-Id nooxlAppNuid mit dem Wert tJel71R1YEGFu80GinVMCw.
  3. Dies ist die Modell-Id modelId mit dem Wert 3466.
  4. Die Datensatz-Selektionen modelSelections haben die Label-Ids dataLabelId 97662 und 97664.
  5. Alternative zur Modell-Id kann auch der Modell-Name "Cash flow" verwendet werden.
  6. Alternative zu den Label-Ids dataLabelId kann aber auch ein dataLabelName mit "2024-01" und "Asset A" verwendet werden.

Für die App-Id gibt es keine Alternative mit Namen.

Parameter in der REST-API Url​

Das REST-API "model calculate" wird mit folgenden Parametern aufgerufen: https://{nooxlApiHostName}/api/v1/app/{nooxlAppNuid}/ModelCalculate

Der Name des Nooxl-API-Server nooxlApiHostName hängt von der Installation ab und lautet für unser Demo-Beispiel https://ncs-demo.nooxl.com.

Damit werden die Parameter wie folgt in die URL eingefügt: https://ncs-demo.nooxl.com/api/v1/app/tJel71R1YEGFu80GinVMCw/ModelCalculate

Autorisierung über API-Token​

Mit dem Aufruf der REST-API Url muss ein Header Authorization mit dem Access-Token Bearer {token} mit gesendet werden. Das Token erhält man vorher über den Aufruf des REST-API "authenticate".

Parameter im REST-API Body​

Zusätzlich zu den oben genannten Parametern werden im Body noch die Inputs dataOutputs, Outputs dataOutputMarkupNames und Optionen modelOptions festgelegt. Für die Inputs und Output werden die Markup-Namen markupName vewendet. Diese sind nur für berechtigte Anwender im Entwurfsmodus sichbar und mit der Demo-Anmeldung nicht verfügbar.

Input- und Output-Parameter der Demo

  1. Rechts in der Liste der Markierung finden Sie die Markup-Namen, die als Input oder Output verwendet werden können.
  2. Bei Auswahl einer Markierung wird der Bereich im Arbeitsfenster rot markiert.

Bei den Inputs wird noch die Eingabe-Werte cellValues mit übergeben in einem 2-dimensionalen Array aus Zeilen von Spalten. Für Outputs werden nur die Namen genannt. Unser Beispiel-Body sind dann wie folgt aus:

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 den Optionen modelOptions kann mit "saveModel": true ein Speichern des Modells (bei ausreichender Berechtigung) erreicht werden.

Hinweis

Für die Demo-App hat der User "API-Tester" keine Speicher-Berechtigung.

Ergebnis-Anwort REST-API​

Nach dem Aufruf des REST-API gibt Nooxl Apps bei Erfolg einen Response-Body aus. Im Fehlerfall wird eine Fehlermeldung zurückgegeben. Der Response-Body sieht für unser Demo-Request wie folgt aus:

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 den Outputs dataOutputs sehen wir die Ausgabe-Werte cellValues mit übergeben in einem 2-dimensionalen Array aus Zeilen von Spalten.