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
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.
Mit Vertec Version 6.1.0.10 wurde der XML Server in den Cloud Server integriert. Das deckt folgende Anforderungen ab:
Damit der XML Server aktiviert wird, muss im Vertec.ini folgende Einstellung gesetzt sein (Standard):
[CloudServer] XML Server = true
Die Kommunikation basiert auf dem Request / Response Schema. 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>
Der Client muss einen Authentisierungs-Request mit Angabe von Username/Password an den Cloud Server senden. Als Antwort erhält er ein Authentisierungs-Token, welches bei jedem Request im XML Request eingesetzt werden muss.
Die Authentisierung erfolgt in zwei Schritten:
vertec_username und password an /auth/xml.import requests
authurl = 'http://localhost/auth/xml'
xmlurl = 'http://localhost/xml'
params = {'vertec_username':'keller', 'password':'UXhfn6P.'}
r = requests.post(authurl, params)
token = r.text
Dafür muss das requests-Modul vorhanden sein, siehe z.B. http://docs.python-requests.org/en/master/.
Set XML = CreateObject("MSXML2.XMLHTTP")
XML.Open "POST", "http://localhost:8081/auth/xml", False
XML.send "&vertec_username=administrator&password="
token = XML.responsetext
<Envelope>
<Header>
<BasicAuth><Token>.....token ......</Token></BasicAuth>
</Header>
<Body>
<Query>
<Selection>
<ocl>projektbearbeiter</ocl>
</Selection>
</Query>
</Body>
</Envelope>
Beim Token handelt es sich um ein signiertes Token gemäss dem JWT (java web token) Standard. Es enthält folgende Angaben, die vom Server ausgewertet werden:
Alle ausgegebenen Tokens sind nach einem Neustart des Cloud Servers nicht mehr gültig (der private Key für die Signatur wird beim Starten des Cloud Servers gewürfelt).
/xml wird zuerst das Token auf Gültigkeit und Ablaufdatum geprüft.[CloudServer] XML Session Timeout = 10
Zum Testen von XML Request steht eine einfache Web-Oberfläche unter /xml/query zur Verfügung.
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.
Der XML Server arbeitet mit UTF-8 Encoding, beim Senden und Empfangen von Daten.
Der XML Request enthält einen Header, in welchem die Authentisierungs-Informationen übertragen werden.
<Envelope> <Header> </Header> <Body> </Body> </Envelope>
Der Body enthält dann die eigentliche Abfrage:
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>
Im Selection-Element wird die eigentliche Abfrage zusammengestellt. Folgende Unterelemente können verwendet werden:
<objref>4019</objref> <objref>5129</objref>
<ocl>offeneleistungen</ocl>
<sqlwhere>datum between '01.10.2021' and '31.12.2021'</sqlwhere>
Der ausführende Benutzer muss über Administratorenrechte oder über das SQL Query Recht verfügen.
<sqlorder>bold_id</sqlorder>
Das Resultdef-Element gibt an, welche Informationen angefordert werden. Es können folgende Unterelemente verwendet werden:
projekt). Es können beliebig viele Members aufgelistet werden.<expression> <alias>abgeschrieben</alias> <ocl>wertint-wertext</ocl> </expression>
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.
Das Resultat wird in einem QueryResponse-Element zurückgeliefert. Dieses enthält immer eine Auflistung von Objekten.
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:
<Envelope>
<Body>
<QueryResponse>
<OffeneLeistung>
<objid>7822</objid>
<datum>2021-11-14</datum>
<projekt><objref>4164</objref></projekt>
<text>Brief an Hr. Meier<text/>
<wertExt>120.00</wertExt>
</OffeneLeistung>
...
Anmerkung: Das Datumsformat ist ISO 8601.
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:
<Create>
<OffeneLeistung>
<bearbeiter><objref>4036</objref></bearbeiter>
<projekt><objref>4132</objref></projekt>
<minutenint>45</minutenint>
</OffeneLeistung>
</Create>
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:
<Envelope>
<Body>
<CreateResponse>
<OffeneLeistung>
<objid>12019</objid>
<isValid>1</isValid>
</OffeneLeistung>
...
</CreateResponse>
</Body>
</Envelope>
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.
CKE eingetragen:<Update>
<Projektbearbeiter>
<objref>4019</objref>
<kuerzel>CKE</kuerzel>
</Projektbearbeiter>
...
</Update>
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:
<Update>
<Projektphase>
<objref>5491</objref>
<Projektstand>Angefangen</Projektstand>
</Projektphase>
</Update>
Ab Vertec 6.3 können Key-Values und Tags über den XML Server gesetzt bzw. entfernt werden. Dafür gibt es folgende Elemente:
<keyvalue> mit Sub-Elementen <key> und <value><tag> mit Sub-Elementen <add> und <remove><Update> <Projektbearbeiter> <objref>4019</objref> <kuerzel>ABC</kuerzel> <keyvalue> <key>ExternalId</key> <value>123465</value> </keyvalue> <tag> <add>selected</add> </tag> </Projektbearbeiter> </Update>
Die Abfrage von bestehenden Key-Values bzw. Tags im Query-Element kann wie gewohnt via OCL erfolgen, hier gibt es keine speziellen Elemente:
<Query>
<Selection>
<ocl>projektbearbeiter->select(hasTag('selected'))</ocl>
</Selection>
<ResultDef>
<member>kuerzel</member>
</ResultDef>
</Query>
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:
<Update>
<Projektbearbeiter>
<objref>300</objref>
<tagespauschaleext/>
</Projektbearbeiter>
</Update>
Ja/Nein-Werte (Booleans) werden mit 0 und 1 gesetzt:
<Update>
<Projekt>
<objref>2880</objref>
<aktiv>1</aktiv>
<myboolean>0</myboolean>
</Projekt>
</Update>
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>
Zurückgeliefert wird ein UpdateResponse-Element mit folgendem Unterelement:
<Envelope>
<Body>
<UpdateResponse>
<text>Updated 1 Objects</text>
</UpdateResponse>
</Body>
</Envelope>
Um ein Objekt zu löschen, wird ein Delete-Element verwendet. Dieses enthält eine Liste der zu löschenden Objekte:
<Delete>
<objref>11764</objref>
...
</Delete>
Zurückgeliefert wird ein DeleteResponse-Element mit folgendem Unterelement:
<Envelope>
<Body>
<DeleteResponse>
<text>Deleted 1 Objects</text>
</DeleteResponse>
</Body>
</Envelope>
