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?»
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.
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):
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)
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.
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.
