Vertec AI Chatbot

Der Chatbot hilft Ihnen bei Fragen rund um das Produkt und die Anpassbarkeit der Software. Wie bei allen AI-generierten Daten sollten die Antworten bei kritischen Informationen verifiziert werden. Nehmen Sie dafür gerne Kontakt mit uns auf. Weitere Informationen zur Verarbeitung der Chat-Daten bieten wir auf der Datenschutzseite.

Die besten Antworten liefert der Chatbot, wenn Ihr Input möglichst viele Informationen enthält. Zum Beispiel:

«Welche Apps stehen im Vertec Cloud Abo zur Verfügung?»

BI API

API für das Business Intelligence Modul

Produktlinie

Standard

|

Expert

Betriebsart

CLOUD ABO

|

ON-PREMISES

Module

Leistung & CRM

Budget & Teilprojekt

Fremdkosten

Ressourcenplanung

Business Intelligence

Erstellt: 17.11.2020
Aktualisiert: 18.01.2024 | Beschreibung zur Authentisierung via API Token angepasst.

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:

import 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

Mit Vertec Version 6.6 wurden API Tokens für die Erhöhung der Anmeldesicherheit von Web API Zugriffen eingeführt. Die HTTP Basic Authentication mit Username und Passwort wird daher ab Vertec Version 6.7 nicht mehr 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 Timeouts 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.

Bitte wählen Sie Ihren Standort