BI API

Ab Vertec 6.4.0.14 gibt es ein API (Application Programming Interface) zur Abfrage von BI Daten aus externen Applikationen.

Dafür gibt es in der Konfigurationsdatei Das Vertec.ini - File den Parameter BI API:

[CloudServer]
BI API=True

Standard ist True .

• Das BI API kann nur verwendet werden, wenn das Business Intelligence Modul lizenziert ist. Anderenfalls wird ein Fehler zurückgegeben.
• Das BI API kann nur nach erfolgter Authentifizierung verwendet werden. Anderenfalls wird ein Fehler zurückgegeben.

Der Aufruf erfolgt über /api/bi , welches folgende Endpoints zur Verfügung stellt:

/measures

Der GET-Endpoint /measures gibt alle zur Verfügung stehenden Kennzahlen zurück.

Es kann ein optionaler Parameter f angegeben werden:

• f=csv (/api/bi/measures?f=csv ) liefert das Resultat als CSV-Datei.
• f=json (/api/bi/measures?f=json ) liefert das Resultat in Json formatiert.

Der Parameter kann statt als Query-String auch als Accept Header angegeben werden. Ist beides vorhanden, wird der Query-String verwendet.

Die Rückgabe enthält folgende Felder:

• Name
• Description
• Dimensions (string[] der Klassennamen)
• Helptext
• Unit

Die Rückgabewerte erscheinen übersetzt in der Sprache, die der User in der Web App eingestellt hat.

Beispiel Abfrage

/api/bi/measures

Liefert folgendes Resultat zurück:

/getdata

Der GET-Endpoint /getdata gibt die BI-Daten zurück. Er nimmt folgende Parameter via Query-String entgegen:

• measures: Kommaseparierte Liste der internen Kennzahlnamen (z.B. "FeesExt,MinInt" ). Obligatorisch.
• dimension:  Liste der Dimensionen, nach denen das Ergebnis gruppiert ist (z.B. "Projekt,Projektbearbeiter" . Obligatorisch, case-insensitive.
  • Als Pseudo-Dimension kann auch "Month" angegeben werden. Stichtageswerte wie OvertimeBalance werden nur akzeptiert für Zeitreihen. Bei diesen Werten muss also dimension=month angegeben werden, andernfalls erscheint eine Fehlermeldung.
  • Sind verschiedene Rolle vorhanden, kann der Zugriff über ein Suffix [Index 0 .. 4] erfolgen:
    • Projekt funktioniert wie bisher und wählt die Dimension Projekt ohne Rolle.
    • Projekt_1 wählt auf der Kennzahl die Dimension Projekt auf Index 1. Dies muss dann eine Rolle auf Projekt sein.
    • Beispiel bei Abfrage von FeesExt (Honorar extern):

          dimension0 = Projekt
          dimension1 = Projektbearbeiter_1
          dimension2 = Projektbearbeiter_2
          dimension3 = ProjektPhase
          dimension4 = Taetigkeit
          dimension5 = Month

    • Werden mehrere Kennzahlen mit unterschiedlichem "Dimensionsaufbau" angefordert und die angeforderten Dimensionen können nicht über alle Kennzahlen geliefert werden, erscheint eine entsprechende Fehlermeldung. In einem solchen Szenario müssen die Kennzahlen mit gleicher Dimensionstruktur in einer Query gebündelt und mehrere dieser Queries abgesetzt werden, um alle Daten zu extrahieren.

• startDate: Startdatum im ISO 8601 Format (2020-01-01), optional.
• endDate: Enddatum im ISO 8601 Format (2020-12-31), optional.
• selectExpression: OCL-Expression für die Selektion, optional.
• useDescriptions: True oder False. Bestimmt, ob die Spaltenbezeichnungen im Klartext und übersetzt geliefert werden oder als intern technische Bezeichnungen, die sprachunabhängig sind. Optional, Standard: False.

Der Endpoint liefert Ergebnisse in folgendem Format:

• Header (Spalten-Namen)
  • Name der angefragten Kennzahl (Interner Name). Falls der Parameter useDescriptions = true ist, wird statt des Internen Namens die Klartext-Bezeichnung der Kennzahl verwendet und gemäss aktueller Sprache der Session übersetzt zurückgeliefert.
• Datenzeile
  • Dimensionswerte
  • Kennzahl Werte 

Die BI Berechtigungen werden angewendet.

Beispiel Abfrage FTE für das erste Quartal 2020

api/bi/getdata?measures=fte&dimension0=Projektbearbeiter&useDescriptions=true&dimension1=month&startDate=2020-01-01&endDate=2020-03-01

Rückgabe:

[{"Bearbeiter":"Administrator","Monat":"2020-01-01","Vollzeitstellen":1.0},{"Bearbeiter":"Administrator","Monat":"2020-02-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Administrator","Monat":"2020-03-01","Vollzeitstellen":1.0},{"Bearbeiter":"Christoph Keller","Monat":"2020-01-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Christoph Keller","Monat":"2020-02-01","Vollzeitstellen":1.0},{"Bearbeiter":"Christoph Keller","Monat":"2020-03-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Judith Feller","Monat":"2020-01-01","Vollzeitstellen":1.0},{"Bearbeiter":"Judith Feller","Monat":"2020-02-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Judith Feller","Monat":"2020-03-01","Vollzeitstellen":1.0},{"Bearbeiter":"Paul Thomson","Monat":"2020-01-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Paul Thomson","Monat":"2020-02-01","Vollzeitstellen":1.0},{"Bearbeiter":"Paul Thomson","Monat":"2020-03-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Werner Schmid","Monat":"2020-01-01","Vollzeitstellen":1.0},{"Bearbeiter":"Werner Schmid","Monat":"2020-02-01","Vollzeitstellen":1.0},
{"Bearbeiter":"Werner Schmid","Monat":"2020-03-01","Vollzeitstellen":1.0},{"Bearbeiter":"Lars Sorenson","Monat":"2020-01-01","Vollzeitstellen":0.5},
{"Bearbeiter":"Lars Sorenson","Monat":"2020-02-01","Vollzeitstellen":0.5},{"Bearbeiter":"Lars Sorenson","Monat":"2020-03-01","Vollzeitstellen":0.5}]

Unterstützung für HTTP Basic Authentication

Für die Abfragen aus externer BI Software wird HTTP Basic Auth mit Username und Passwort unterstützt.

• Die gestartete Session hat einen Standard Timeout von 5 Minuten. Dieser kann in der [Cloud Server] Section im Vertec.ini-File mit XML Session Timeout = 5 angepasst werden (das BI API und der XML Server teilen sich die Session Timeout Einstellung).
• Nach Ablauf des Timeout wird die Session beendet und der Prozess verschwindet
• Trifft während dieser Zeit eine weitere Anfrage mit Basic Authentication und demselben Benutzer ein, wird die Session wiederverwendet.