BI API

API für das Business Intelligence Modul

Standard

Expert

CLOUD ABO

ON-PREMISES

Leistung & CRM

Budget & Teilprojekt

Fremdkosten

Ressourcenplanung

Business Intelligence

Erstellt: 17.11.2020

Aktualisiert: 17.04.2023 | Authentisierung umgestellt auf API Token

Ab Vertec 6.4.0.14 gibt es ein API (Application Programming Interface) zur Abfrage von BI Daten aus externen Applikationen. Der Aufruf erfolgt über <ServerURL>/api/bi.

In der Konfigurationsdatei Vertec.ini gibt es dafür den Parameter BI API:

[CloudServer]
BI API=True

Standard ist True. Das heisst, dass das BI API auch läuft, wenn der Parameter nicht angegeben ist.

Das BI API kann nur verwendet werden, wenn das Business Intelligence Modul lizenziert ist.

Die BI Berechtigungen werden angewendet.

Hier finden Sie eine ausführliche BI API - Beispielanwendung mit Postman/Excel.

Authentisierung

Die Authentisierung an das BI API erfolgt via API Token. Dieses muss als Bearer Token in einem Authorization Header mitgegeben werden:

impport requests
url = 'http://localhost:8081/api/bi/measures'
api_token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.MGVhZmUzMzYtNmVhMi00MDdhLTgxNjQtZDYxZmI0NzU2MWZi._r16YlvWmZCMJ3qdDX3bK5_DJHwcczTYaWoKUYUNZuk'
headers = {'Authorization': 'Bearer %s' % api_token}
r = requests.get(url, headers=headers)
measures = r.text

Hinweis: In Vertec Versionen vor 6.6 erfolgte die Authentisierung via HTTP Basic Auth mit Username und Passwort. Das entsprechende Handling finden Sie im Artikel zuunterst.

Endpoints

Unter /api/bi stehen folgende GET-Endpoints zur Verfügung:

/getdata

Die BI-Daten werden mittels Endpoint /getdata abgefragt. Er nimmt folgende Parameter via Query-String entgegen:

measures	Obligatorisch. Kommaseparierte Liste der internen Kennzahlnamen (z.B. `"feesext,minutesint"`). Die Liste der internen Namen der mitgelieferten Standard-Kennzahlen finden Sie hier.
dimension	Obligatorisch, case-insensitive. Liste der Dimensionen, nach denen das Ergebnis gruppiert ist (z.B. `"Projekt,Projektbearbeiter"`). 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 für die Dimension verschiedene Rollen vorhanden, kann der Zugriff über ein Suffix [Index 0-4] erfolgen. `Projekt` 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. usw.. Beispiel bei Abfrage der Kennzahl 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	Optional. 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 `Projekttyp` auftaucht, welches die Bezeichnung des Projekttyps des Projekt-Dimensionswertes enthält. Pro Dimension können beliebig viele 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	Optional. Startdatum im ISO 8601 Format (2020-01-01)
endDate	Optional. Enddatum im ISO 8601 Format (2020-12-31)
selectExpression	Optional. OCL-Expression für die Selektion.
useDescriptions	Optional, True oder False. Standard: False. Bestimmt, ob die Spaltenbezeichnungen im Klartext und übersetzt geliefert werden oder als intern technische Bezeichnungen, die sprachunabhängig sind.
f	Optional. Bestimmt, in welchem Format das Resultat ausgegeben wird: csv: liefert das Resultat als CSV-Datei 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.

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

Beispiel Abfrage FTE für das erste Quartal 2023

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

Rückgabe:

"Bearbeiter","Bearbeiter_Id","Monat","Vollzeitstellen"
"Christoph Keller",676,"2023-01-01",0.8
"Christoph Keller",676,"2023-02-01",0.8
"Christoph Keller",676,"2023-03-01",0.8
"Judith Feller",682,"2023-01-01",1
"Judith Feller",682,"2023-02-01",1
...

/measures

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

Es kann der optionale Parameter f angegeben werden (siehe oben).

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.

Unterstützung für HTTP Basic Authentication

In Vertec Versionen vor 6.6 wurde für die Authentisierung HTTP Basic Auth mit Username und Passwort verwendet. Aus Backwards-Kompatibilitätsgründen wird diese Möglichkeit noch parallel zur Authentisierung via API-Token unterstützt, mit Vertec Version 6.7 jedoch abgeschaltet.

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.

Wenn sowohl API Token als auch Username/Password in einem Request angegeben sind, wird nur das API Token berücksichtigt. Ist es ungültig, wird nicht automatisch ein Login-Versuch mit Username/Password vorgenommen.