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?»
Vertec ist mit einer XML Schnittstelle ausgerüstet. Diese wird vom Vertec XML Server bereitgestellt. Mit dieser Schnittstelle können Anfragen in XML formuliert und via http an Vertec geschickt werden. Die Antwort kommt ebenfalls in XML formatiert.
Standard
|
Expert
CLOUD ABO
|
ON-PREMISES
Leistung & CRM
Budget & Teilprojekt
Fremdkosten
Ressourcenplanung
Business Intelligence
Erstellt: 13.06.2022
Aktualisiert: 20.03.2024
|
Delimeter für MLStrings dokumentiert, ismale (gender) korrigiert.
Mit der XML Schnittstelle lassen sich alle Daten aus Vertec abfragen, erzeugen, ändern, oder löschen. Die Schnittstelle eignet sich demzufolge für Anbindungen von Drittsystemen aller Art.
Die Kommunikation basiert auf demRequest / ResponseSchema. Ein Client schickt via HTTP POST eine in XML formulierte Anfrage und erhält als Ergebnis eine Antwort in XML.
Das Format der dabei verwendeten XML Messages basiert auf der SOAP Spezifikation. Vollständige SOAP Kompatibilität ist nicht umgesetzt, insbesondere die Behandlung von XML Namespaces fehlt. Namespaces können in Requests verwendet werden, finden aber keine Beachtung. Die Response Messages verwenden keine Namespace Informationen.
Der Aufbau der XML Messages ist grundsätzlich immer gleich. So enthält jede Message, ob Request oder Response, immer das Grundelement Envelope und als Unterelement 'Body':
<Envelope>
<Body>
</Body>
</Envelope>
XML Server
Authentisierung
Die Authentisierung beim XML Server erfolgt via API Token, welches im Parameter api_token übergeben wird. Beispiel:
Innerhalb des Timeout-Intervalls wird immer die gleiche Session verwendet.
Hinweis: In Vertec Versionen vor 6.6 erfolgte die Authentisierung über einen eigenen Endpoint /auth/xml. Das entsprechende Handling finden Sie im Artikel zuunterst.
Mehrere Sessions starten
Pro XML Session kann ein eigener Vertec.Session Prozess gestartet werden. Damit können Probleme mit langlaufenden Sessions vermieden werden.
Falls explizit eine neue (parallele) Session verwendet werden soll, kann optional ein HTTP Header VertecSessionTag mit einem beliebigen Wert (z.B. 1) mitgegeben werden. Es sind maximal 36 Zeichen erlaubt. Beispiel:
Pro VertecSessionTag wird eine neue Session gestartet. Somit basiert die Session Affinität auf der Kombination von API Token und Session-Id.
Session Handling
Bei einem XML Request auf /xml wird zuerst das Token auf Gültigkeit geprüft.
Anschliessend wird geprüft, ob für dieses Token bereits eine Vertec-Session läuft. Falls ja, wird der Request dieser Session übergeben.
Falls noch keine Session für die angegebene XML Session-ID existiert, wird eine angelegt (bzw. aus dem Idle Pool genommen).
Eine XML Session hat einen Session Timeout von 5 Minuten. Wenn während dieser Zeit kein neuer Request für die Session empfangen wird, wird die Session beendet. On-Premises kann dieser Wert bei Bedarf im Vertec.ini angepasst werden.
Wenn die Session aufgrund des Timeouts beendet wurde, wird einfach eine neue Session gestartet. Dank den Idle Sessions ist die Verzögerung auch bei einer neuen Session minimal.
Testen der XML Schnittstelle
Zum Testen von XML Request steht eine einfache Web-Oberfläche unter /xml/query zur Verfügung.
Im Feld XML Request wird das Body-Element des XML Requests eingegeben.
Das Ergebnis-XML wird unterhalb dargestellt:
Beachten Sie bitte, dass Sie damit unter Umständen auf Ihre reale Datenbank zugreifen und sich Datenänderungen auf Ihre realen Daten auswirken können, sofern Sie nicht eine unabhängige Testinstallation eingerichtet haben.
Encoding
Der XML Server arbeitet mit UTF-8 Encoding, beim Senden und Empfangen von Daten.
Um Objekte mittels XML Message abzufragen, wird der Abfrage-Block in ein Query-Element verpackt. Dieses Element enthält wiederum die Elemente Selection und Resultdef.
<Query>
<Selection>
<objref>676</objref>
<ocl>offeneleistungen</ocl>
<sqlwhere>datum between '01.10.2021' and '31.12.2021'</sqlwhere>
<sqlorder>bold_id</sqlorder>
</Selection>
<Resultdef>
<member>datum</member>
<member>projekt</member>
<member>text</member>
<member>wertext</member>
</Resultdef>
</Query>
Selection-Element
Im Selection-Element wird die eigentliche Abfrage zusammengestellt. Darin können folgende Unterelemente verwendet werden: <objref>, <ocl>, <sqlwhere> und <sqlorder>.
<objref>
Mit dem <objref> Element können Vertec Objekte mittels ihrer Objekt Id abgefragt werden.
Sollen die Ergebnisse sortiert oder gefiltert werden, kann das mit den gewohnten OCL Listenoperatoren geschehen (->select(), ->orderby() etc.). Achten Sie auch hier auf einen performanten Zugriff.
<sqlwhere>
Im <sqlwhere> Element kann ein SQL-Filter angegeben werden. Das <ocl> Element gibt dabei den Klassennamen an (achten Sie dabei auf die Gross-/Kleinschreibung).
In Kombination mit <sqlwhere> können die Objekte mit <sqlorder> sortiert werden:
<Selection>
<ocl>OffeneLeistung</ocl>
<sqlwhere>datum between '01.01.2023' and '31.12.2023'</sqlwhere>
<sqlorder>datum</sqlorder>
</Selection>
Resultdef-Element
Das Resultdef-Element gibt an, welche Informationen angefordert werden. Es können folgende Unterelemente verwendet werden:
member: Hier wird in OCL ein Member des Resultat-Objekts angegeben.Handelt es sich beim angegebenen Member um ein eigenständiges Objekt, wird davon die Vertec Objekt-ID zurückgeliefert (im Beispiel für das Member projekt). Es können beliebig viele Members aufgelistet werden.
alias-expression: Möchte man ein member um if-else-Bedingungen oder Berechnungen erweitern, wird ein Alias in einer Expression verwendet. In dieser können OCL Expressions eingesetzt werden. Der Aufbau ist wie folgt:
Im <ocl>-Bereich sind sämtliche OCL Expressions möglich.
Es muss nicht unbedingt ein Resultdef-Element angegeben werden. Wird nur ein einzelner Wert angefordert (und nicht, wie oben beschrieben, eine Liste von Objekten), kann dieses Element einfach weggelassen werden. Z.B. liefert die Selection <ocl>projektbearbeiter->size</ocl> die Anzahl Bearbeiter zurück. Die Response liefert dann einen <Value>Anzahl</Value> zurück.
XML Response
QueryResponse-Element
Das Resultat wird in einem QueryResponse-Element zurückgeliefert. Dieses enthält immer eine Auflistung von Objekten.
objid: Jedes zurückgelieferte Objekt wird als eigenständiges Element geliefert. Bei jedem dieser Result-Objekten wird eine objid mitgeliefert, welche die Vertec Objekt-ID enthält:
<objid>7822</objid>
Des Weiteren werden alle unter Resultdef angegebenen Members aufgelistet. Falls es sich dabei um eigenständige Objekte handelt, wird von diesen die Objektreferenz (Objekt-ID) mitgeliefert:
Um ein Objekt zu erzeugen wird ein Create-Element verwendet. Dieses enthält eine Liste von zu erzeugenden Objekten. Als zu erzeugendes Objekt wird jeweils der entsprechende Klassenname angegeben. Die einzelnen Members enthalten entweder eine Objektreferenz (Objekt-ID) eines bestehenden Objektes in Vertec oder den beim Member einzutragenden Wert.
Als Beispiel wird eine offene Leistung erzeugt. Dieser wird ein bereits bestehender Bearbeiter und ein bereits bestehendes Projekt mittels Objekt-ID zugewisen. Als Aufwand wird im Attribut minutenint 45 Minuten eingetragen:
Zurückgeliefert wird ein CreateResponse-Element. Dieses enthält eine Liste der erzeugten Objekten, die jeweils den Klassennamen des erzeugten Objektes angibt. Diese wiederum enthalten folgende Unterelemente:
objid: Gibt die Objekt-ID des neu erzeugten Objektes an.
isValid: Gibt an, ob das erzeugte Objekt in Vertec gültig ist (1) oder nicht (0).
Das Ändern von Objekten funktioniert ähnlich wie das Erzeugen, einfach wird dafür ein Update-Element verwendet. Dieses enthält eine Liste von zu ändernden Elementen. Angegeben wird jeweils der Klassenname des zu ändernden Objekts als Unterelement.
objref: Für jedes zu ändernde Element muss die Objektreferenz (Objekt-ID) angegeben werden. Wichtig ist, dass diese zuoberst angegeben wird, also vor den anderen Attributen, sonst wird die Änderung nicht durchgeführt.
Weiter müssen die zu ändernden Attribute angegeben werden. Im Beispiel wird bei einem Projektbearbeiter mit der Objekt-ID 4019 als Kürzel CKE eingetragen:
Das Ändern von Zusatzfeldern funktioniert gleich wie oben, als Membernamen wird einfach der Name des Zusatzfeldes eingesetzt. Im Beispiel wird im Zusatzfeld Projektstand auf einer Projektphase mit der ID 5491 der Text Angefangen eingetragen:
Um einen Wert, der bereits gesetzt ist, wieder zu leeren (auf NULL setzen), können Sie dem Attribut einen leeren Wert zuweisen. Im Beispiel wird die Tagespauschale auf dem Bearbeiter geleert:
Etwas verwirrlich ist, dass es bei der Abfrage von Boolean-Werten einen Unterschied von eingebauten Feldern und Zusatzfeldern gibt. Eingebaute Boolean-Felder wie z.B. aktiv auf Projekten liefern 1 und 0, die Boolean-Zusatzfelder jedoch Y und N zurück.
Das Setzen erfolgt jedoch in beiden Fällen gleich, nämlich wie oben beschrieben mit 0 und 1.
Benötigt man einen einheitlichen XML-Response, kann man anstelle der einfachen <member>-Abfrage eine Expression angeben, die den Rückgabewert steuert:
<expression><alias>myboolean</alias><ocl>if zusatzfeldbool('myboolean') then 1 else 0 endif</ocl></expression>
MLString-Feld setzen
Bei MLString-Feldern braucht es nach dem Sprachtext einen "record separator" (RS) mit dem Code 30 (Hex 1E). Dafür wird die XML Entity  eingesetzt:
Mit Version 6.6 wurden API Tokens für die Erhöhung der Anmeldesicherheit von Web API Zugriffen eingeführt. Die API Tokens erhöhen die Anmeldesicherheit der Vertec XML Schnittstelle und der BI API Schnittstelle.
Das alte System – die Authentisierung via Username und Passwort – wird ab Vertec Version 6.7 nicht mehr unterstützt. Der XML Server und das BI API erlauben nur noch Authentisierungen via API Token. Der Endpunkt /auth/xml wurde entfernt und Calls gegen diesen Endpunkt melden einen Fehler
Beispiele für die Verwendung der Schnittstelle
In der folgenden Tabelle sind Beispiel XML Queries zum Erzeugen und Updaten von Adresseinträgen beschrieben.
Query
XML Response
Suche nach Firma mit Referenznummer:
<Query>
<Selection>
<ocl>Firma</ocl>
<sqlwhere>referenz like '123456789'</sqlwhere>
</Selection>
</Query>
Die Antwort ist eine Liste von objid, welche dem Suchkriterium entsprechen.
