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,minutesint"). Obligatorisch. Die Liste der internen Namen der mitgelieferten Standard-Kennzahlen finden Sie hier.
• dimension:  Liste der Dimensionen, nach denen das Ergebnis gruppiert ist (z.B. "Projekt,Projektbearbeiter". Obligatorisch, case-insensitive. Die Liste der Dimensionen der mitgelieferten Standard-Kennzahlen finden Sie hier.
  • 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.

• _variable und OCL Expression: Ab Vertec 6.5.0.11 können zu jedem Dimensions-Parameter (dimension0=Projekt, dimension1=Projektbearbeiter etc.) Alias-Parameter mit einer OCL Expression als Wert angeben werden, z.B. dimension0_Projekttyp=typ.bezeichnung. Dies bewirkt, dass in der Antwort ein neues Feld Projekttypauftaucht, welches die Bezeichnung des Projekttyps des Projekt Dimensionswertes enthält. Pro Dimension können mehrere Alias-Parameter angegeben werden. Entspricht der verwendete Parameter einem Namen, der bereits verwendet wird (als Measurenamen, Klassennamen bzw. deren Übersetzungen oder Alias einer anderen Dimension), wird ein Fehler gemeldet.
• 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
  • Objekt Id der Dimensionen (ab Vertec 6.5.0.11): Für jeden Dimensionswert gibt es eine Eigenschaft mit gleichem Namen und Suffix _Id welche als Wert die Objekt Id des Dimensionswertes enthält: {"Bearbeiter":"Administrator","Bearbeiter_Id": 301,"Monat":"2020-01-01", ...}. Dimensionen Monat erscheinen ohne _Id-Feld im Ergebnis.
  • 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.