Vertec XML Schnittstelle

Authentisierung

Session Handling

Requests

• Objekte abfragen (Query)
• Objekte erzeugen (Create)
• Objekte ändern (Update)
• Objekte löschen (Delete)

Responses

• QueryResponse
• CreateResponse
• UpdateResponse
• DeleteResponse

Spezialfälle

• Zusatzfelder
• Schreiben von Keys / Tags
• Abfragen von Keys / Tags
• Einen Wert auf NULL setzen
• Ja/Nein-Werte (Boolean)
• MLString Feld setzen
• Datumswerte setzen

Beispielanwendungen

Testen der XML Schnittstelle

<objref>

Abfrage von Einzelobjekten

Mit dem <objref> Element können einzelne Vertec Objekte mittels ihrer Internen ID abgefragt werden.

In der gleichen Selection können nacheinander auch mehrere Vertec Objekte so abgefragt werden.

Für eine globale Abfrage via OCL oder SQL wird das <objref> Element weggelassen.

Einzelobjekt:

<Query>
    <Selection>
        <objref>676</objref>
    </Selection>
</Query>

Mehrere Einzelobjekte:

<Query>
    <Selection>
        <objref>676</objref>
        <objref>12345</objref>
    </Selection>
</Query>

<ocl>

Abfrage via OCL

Im <ocl> Element kann eine OCL Expression angegeben werden. Diese wird wie folgt angewendet:

• Ist ein einzelnes <objref> Element angegeben, wird das OCL darauf ausgeführt.
• Ist kein <objref> Element angegeben, wird das OCL global ausgeführt.
• Sind mehrere <objref> Elemente angegeben, wird das OCL nicht ausgeführt.

Das Filtern und Sortieren der Ergebnisliste erfolgt direkt im OCL mit den gewohnten OCL Operatoren (->select(), ->orderby() etc.).

Achten Sie auf einen performanten Zugriff.

OCL auf ein <objref> Element:

<Query>
    <Selection>
        <objref>1206</objref>
        <ocl>ownprojects</ocl>
    </Selection>
</Query>

Globale OCL Abfrage:

<Query>
    <Selection>
        <ocl>projektbearbeiter->orderby(name)</ocl>
    </Selection>
</Query>

<sqlwhere>

Abfrage via SQL

Die Abfrage via SQL ist immer global und kann weder mit einer OCL Expression noch mit einem Einzelobjekt kombiniert werden. Sie dient dazu, gefilterte Listen performanceoptimiert direkt auf der Datenbank abzufragen. Für ungefilterte Listen (alle Objekte einer Klasse) verwenden Sie stattdessen die Abfrage via OCL.

Eine SQL Abfrage wird wie folgt aufgebaut:

•  <ocl>: Im Hilfselement <ocl> wird der Klassenname angegeben. Dieser wird immer Gross geschrieben. Zu Verfügung stehen alle Klassen im Vertec Model Browser, die im Feld Table Mapping ein OWN haben und also unter diesem Namen in der Datenbank zu finden sind.
• <sqlwhere>: Im <sqlwhere> Element wird die WHERE-Klausel angegeben, also der Filter, der auf der unter <ocl> angegebenen Klasse angewandt werden soll.
• <sqlorder>: Optional. Die Ergebnisliste aus <sqlwhere> kann mit dem <sqlorder> Element sortiert werden.

Der ausführende Bearbeiter muss über Administratorenrechte oder über das SQL Query Recht verfügen.

<Query>
    <Selection>
        <ocl>OffeneLeistung</ocl>
        <sqlwhere>fixedprice = 1</sqlwhere>
        <sqlorder>datum</sqlorder>
    </Selection>
</Query>

<member>

Abfrage eines einzelnen Members

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.

<Query>
    <Selection>
        <ocl>Session.allInstances->first.login.ownprojects</ocl>
    </Selection>
    <Resultdef>
        <member>code</member>
        <member>betreffend</member>
    </Resultdef>    
</Query>

<expression>

Abfrage via OCL Expression

Für Bedingungen (if-then-else-endif), Berechnungen (mb1+mb2, ->sum etc.) oder um Werte eines verlinkten Objekts (Associations im Vertec Model Browser) auszugeben, wird das <expression> Element verwendet. Es enthält zwei Unterelemente:

• <alias>: Hier kann man den Namen angeben, unter welchem der berechnete Wert ausgegeben wird. Es dürfen keine Leerschläge und Sonderzeichen verwendet werden. 
• <ocl>: Das <ocl> Element enthält die OCL Expression. 

<Query>
    <Selection>
        <ocl>Session.allInstances->first.login.ownprojects</ocl>
    </Selection>
    <Resultdef>
        <member>code</member>
        <member>betreffend</member>
        <expression>
            <alias>OffeneLeistungen</alias>
            <ocl>offeneLeistungen.wertext->sum</ocl>
        </expression>
    </Resultdef>    
</Query>

Objekt

• <Klasse>: Für jedes Objekt wird ein Element mit der Klasse des Objekts zurückgeliefert, mit folgenden Unterelementen:
  • <objid>: Liefert die interne ID des Objekts

Mit Resultdef Definition

• <name>: Des Weiteren werden alle unter Resultdef angeforderten Werte als einzelne Elemente mit dem Namen des abgefragten Members/Association/Alias aufgelistet.
  • Falls es sich dabei um eigenständige Objekte handelt (z.B. bei Abfrage einer Association), wird von diesen die Objektreferenz (interne ID) in einem <objref> Unterelement zurückgeliefert.

<Envelope>
  <Body>
    <QueryResponse>
      <Projekt>
        <objid>1195</objid>
        <betreffend>Prozessberatung</betreffend>
        <code>PROCESS CONSULTING</code>
        <OffeneLeistungen>15’037.75</OffeneLeistungen>
      </Projekt>
      <Projekt>
        <objid>1192</objid>
        <betreffend>Laufende Betreuung</betreffend>
        <code>JOB MANAGEMENT</code>
        <OffeneLeistungen>16’644.85</OffeneLeistungen>
      </Projekt>
    </QueryResponse>
  </Body>
</Envelope>

Wert

Ist das Resultat des Query Requests kein Objekt, sondern ein Wert, wird dieser in einem <Value> Element zurückgeliefert, welches den abgefragten Wert enthält. 

• Bei Boolean (True/False) Werten wird 1 für True und 0 für False zurückgeliefert.

<Envelope> 
  <Body> 
    <QueryResponse> 
      <Value>7</Value> 
    </QueryResponse> 
  </Body> 
</Envelope>

Kein

Gibt es keinen Rückgabewert, wird einfach ein leeres <QueryResponse /> Element zurückgeliefert. 

<Envelope> 
  <Body> 
    <QueryResponse/>
  </Body>
</Envelope>

Zusatzfelder

Das Schreiben von Werten in Zusatzfeldern funktioniert gleich wie bei normalen Members. Als Element wird einfach der <name> des Zusatzfeldes eingesetzt.

Die verschiedenen Zusatzfeldarten werden via XML wie folgt geschrieben:

• Zeichen, Text: Text als Wert übergeben, ohne Anführungszeichen
• Boolean (Wahr/Falsch): 0 für Falsch, 1 für Wahr. Siehe auch Beschreibung unten.
• Ganzzahl: Integer
• Minuten: Integer
• Festkommazahl: Zahl mit Dezimalstellen. Ohne Tausendertrennzeichen angeben. 
• Datum: Format ISO 8601, siehe unten. 
• Auswahl: Integer mit der Position in der Auswahlliste, beginnend mit 0

Die Abfrage von Zusatzfeldern erfolgt via OCL.

Zusatzfeld Projektstand auf einer Projektphase:

<Update> 
  <Projektphase> 
    <objref>5491</objref> 
    <Projektstand>1</Projektstand>
  </Projektphase>
</Update>

Schreiben von Keys/Tags

Für das Setzen von Keys und Tags via XML gibt es folgende Elemente:

• <keyvalue> mit den Unterelementen <key> und <value>
• <tag> mit den Unterelementen <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>

Abfragen von Keys/Tags

Die Abfrage von bestehenden Keys und Tags erfolgt via OCL direkt auf den abgefragten Objekten. 

<Query>
    <Selection>
        <ocl>projektbearbeiter->select(hasTag('selected'))</ocl>
    </Selection>
</Query>

Einen Wert auf NULL setzen

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 (Boolean)

Ja/Nein-Werte (Booleans) werden mit 0 und 1 gesetzt:

• 0: Nein
• 1: Ja

Bei der Abfrage von Boolean-Werten gibt es 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.

<Update>
    <Projekt>
        <objref>2880</objref>
        <aktiv>1</aktiv>
    </Projekt>
</Update>

Benötigt man eine einheitliche QueryResponse, kann man bei Zusatzfeldern 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 Sprache und Begriff jeweils einen "record separator" mit dem Code 30 (Hex 1E). Dafür wird die XML Entity  eingesetzt. 

Es können keine einzelnen Sprachen gesetzt werden, es werden immer alle Sprachen gesetzt. Gibt man also eine der Sprachen nicht an, ist sie nachher leer, auch wenn vor dem Update Request etwas angegeben war. Beachten Sie dazu folgende Anmerkungen:

• Der Begriff ist in allen Sprachen gleich: 
  • Nur den NV (Native) setzen: NVProjektidee
• Der Begriff ist in verschiedenen Sprachen unterschiedlich:
  • Nur den NV (Native) Begriff setzen (siehe oben) und, falls der Begriff nicht schon automatisch übersetzt wird, einen Übersetzungseintrag in Vertec erfassen, um den Begriff in die anderen Sprachen zu übersetzen.
  • Alternativ NV setzen sowie die benötigten Sprachen (DE, DD, EN, IT, FR), in denen der Begriff vom NV abweicht: NVProjektideeENProject ideaITIdea progettoFRIdée projet

<Update>
    <Report>
        <objref>34741</objref>
        <designation>NV&#30;Projektidee&#30;EN&#30;Project idea&#30;</designation>
    </Report>
</Update>

Datumswerte setzen

Datumswerte müssen unabhängig von den Regionaleinstellungen im Format ISO 8601 angegeben werden.

• Datum: YYYY-MM-DD
• Datum und Zeit: YYYY-MM-DD HH:MM:SS

<Update>
  <OffeneLeistung>
    <objref>34743</objref>
    <datum>2025-07-01</datum>
  </OffeneLeistung>
</Update>

Firma mit Referenznummer

Das Feld Referenznummer auf der Firma ist ein String-Feld, kann also sowohl Text als auch Ziffern enthalten.

<Query>
  <Selection>
    <ocl>Firma</ocl>
    <sqlwhere>referenz like '123456789'</sqlwhere>
  </Selection>
</Query>

Firma erzeugen

Die Sprache der Firma wird mit einem Integer angegeben:

• 0: DE
• 1: EN
• 2: FR
• 3: IT

Die Adresse sowie die Kommunikationsmittel sind eigenständige Objekte und müssen separat geschrieben werden (siehe unten). Die CreateResponse liefert die interne ID der neu erstellten Firma zurück, damit kann dann weitergearbeitet werden. 

<Create>
  <Firma>
    <name>Goldhaus AG</name>
    <zusatz>Standort Testenhausen</zusatz>
    <referenz>123456789</referenz>
    <sprache>1</sprache>
    <betreuer><objref>1206</objref></betreuer>
  </Firma>
</Create>

Adressobjekt ermitteln

Die Adresse resp. das entsprechende Adressobjekt wird beim Erzeugen eines Adresseintrags automatisch von Vertec angelegt. 

Um das Adressobjekt zu ermitteln, fragen wir - z.B. auf der neu erstellten Firma - nach defaultadresse.adresse (siehe auch UML Modell Adressen) und erhalten als Response die interne ID des Adressobjekts.

<Query>
  <Selection>
    <objref>4562</objref>
    <ocl>defaultadresse.adresse</ocl>
  </Selection>
</Query>

Adressdaten schreiben

Auf dem ermittelten Adressobjekt können wir nun die Adresse schreiben.

<Update>
  <Adresse>
    <objref>2865</objref>
    <adresse>Hauptstrasse 1</adresse>
    <plz>9999</plz>
    <ort>Testenhausen</ort>
    <kanton>Zürich</kanton>
    <land>Schweiz</land>
  </Adresse>
</Update>

Kommunikationsmittel erstellen

Um ein Kommunikationsmittel (Klassenname: KommMittel) auf einem Adresseintrag zu erzeugen, müssen zwei Dinge vorgängig bekannt sein:

• Die interne ID des Adresseintrags (z.B. der oben neu erzeugten Firma), auf dem das Kommunikationsmittel angelegt werden soll.
• Die interne ID des Kommunikationsmitteltyps (Klassenname: KommMittelTyp) in Vertec.

Folgende Felder werden geschrieben:

• typ: <objref> mit der internen ID des KommMittelTyps
• eintrag: <objref> mit der internen ID des Adresseintrags
• zieladresse: Die eigentliche Telefonnummer resp. E-Mail-Adresse, URL, etc.
• bezeichnung: Optional. Wird in der Liste der Kommunikationsmittel auf der Adresse angezeigt und dient der Übersichtlichkeit.

Soll das neu erzeugte KommMittel auf dem Adresseintrag als Standard markiert werden, muss es zusätzlich je nach internem Typ des KommMittelTyps mit dem Adresseintrag wie folgt verlinkt werden:

• T: fromDefaultTelefon
• M: fromDefaultMobile
• E: fromDefaultEmail
• H: fromDefaultHomepage
• L: fromDefaultLinkedIn
• F: fromDefaultFax

Zu beachten: Falls bereits ein KommMittel dieses Typs als Standard markiert ist auf dem Adresseintrag, wird dieses dadurch als bisheriger Standard entfernt.

Abfrage des Typs, hier 'T' für Telefon:

<Query>
  <Selection>
    <ocl>kommMittelTyp->select(internerTyp='T')</ocl>
  </Selection>
</Query>

KommMittel erstellen und als Standard verlinken:

<Create>
  <KommMittel>
    <typ><objref>142</objref></typ>
    <eintrag><objref>4562</objref></eintrag>
    <zieladresse>043 219 87 65</zieladresse>
    <bezeichnung>Zentrale</bezeichnung>
    <fromDefaultTelefon><objref>4562</objref></fromDefaultTelefon>
  </KommMittel>
</Create>

Kontakt erstellen

• firma = interne ID der Firma
• gender = male für männlich, female für weiblich, oder eines der in den Systemeinstellungen Adressen hinterlegten zusätzlichen Geschlechter.

<Create>
  <Kontakt>
    <firma><objref>4562</objref></firma>
    <name>Duck</name>
    <vorname>Donald</vorname>
    <gender>male</gender>
  </Kontakt>
</Create>

Ein Projekt einem Stichwortordner zuordnen

Weist einem Projekt (hier mit interner ID 1170) einen Stichwortordner (hier mit interner ID 31426) zu.

<Update>  
  <Projekt>
    <objref>1170</objref>
    <ordner><objref>31426</objref></ordner>
  </Projekt>
</Update>