XML Schnittstelle

Vertec XML Webservice Schnittstellenbeschrieb

Dieser Artikel beschreibt die XML Schnittstelle von Vertec. Die Schnittstelle wird von der Service Version von Vertec (VertecServer.exe) via HTTP zur Verfügung gestellt.

Die Kommunikation basiert auf dem Request / Response Schema. Eine 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 noch nicht umgesetzt, insbesondere die korrekte Behandlung von XML Namespaces fehlt in der aktuellen Version noch. Namespaces können in Requests verwendet werden, finden aber noch keine Beachtung. Die Response Messages verwenden keine Namespace Informationen.

Aufbau

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>

Request

Im ersten Teil (Header) der Anfrage werden die Login Informationen übertragen. Der zweite Teil (Body) enthält die eigentliche Abfrage mit OCL Expression.

Authentifizierung

Die Authentifizierung, analog dem Login Dialog in Vertec, ist Bestandteil jeder Request Message. Das dabei verwendete Format entspricht weitgehend der SOAP Extension Basic Authentication.

Nicht implementiert ist der in dieser Spezifikation vorgesehene Challenge Mechansismus.

Zur Authentifizierung muss das SOAP Header Element ein Subelement folgender Form enthalten:

<Header>
    <BasicAuth>
        <Name>Administrator</Name>
        <Password></Password>
    </BasicAuth>
</Header>

Objekte abfragen (Query)

Query Element

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.

Selection Element

Im Selection-Element wird die eigentliche Abfrage zusammengestellt. Folgende Unterelemente können verwendet werden:

ocl: Hier wird eine OCL-Expression angegeben:
<ocl>projekt->select(aktiv)</ocl>
objref: Gibt die Objekt-ID eines Objekts in Vertec an (Normalerweise wird die Objekt-ID über eine vorhergehende XML Abfrage eruiert). Es können auch mehrere Objekte ausgewählt werden:

<objref>4019</objref>
<objref>5129</objref>

sqlwhere: Hier kann noch ein Filter angegeben werden:
<sqlwhere>datum between "01.01.2007 and "30.05.2007"</sqlwhere>
sqlorder: Die Einträge können sortiert werden:
<sqlorder>bold_id</sqlorder>

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:
<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.

Beispielabfrage

Eine Abfrage (Query) könnte wie folgt aussehen:

<Envelope>
    <Header>
        <BasicAuth>
            <Name>administrator</Name>
            <Password></Password>
        </BasicAuth>
    </Header>
    <Body>
        <Query>
            <Selection>
                <objref>4019</objref>
                <ocl>offeneleistungen</ocl>
                <sqlwhere>datum between "01.01.2006"
                    and "30.05.2006"</sqlwhere>
                <sqlorder>bold_id</sqlorder>
            </Selection>
            <Resultdef>
                <member>datum</member>
                <member>projekt</member>
                <member>text</member>
                <member>wertext</member>
            </Resultdef>
        </Query>
    </Body>
</Envelope>

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 alle unter Resultdef angegebenen Members aufgelistet. Falls es sich bei einem dieser Members um ein eigenständiges Objekt handelt, wird von diesem die Objektreferenz (Objekt-ID) mitgeliefert:

<Envelope>
    <Body>
        <QueryResponse>
            <OffeneLeistung>
                <objid>7822</objid>
                <datum>2006-04-28</datum>
                <projekt><objref>4164</objref></projekt>
                <text>Brief an Hr. Meier<text/>
            <wertExt>120.00</wertExt>
        </OffeneLeistung>
     ...

Anmerkung: Das Datumsformat ist ISO 8601.

Objekte erzeugen (Create)

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 weise ich einen bereits bestehenden Bearbeiter und ein bereits bestehendes Projekt mittels Objekt-ID zu. Als Aufwand trage ich im Attribut minutenint 45 Minuten ein:

CreateResponse Element

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 erzeugten Objektes an.
isValid: Gibt an, ob das erzeugte Objekt in Vertec gültig ist (1) oder nicht (0).

Beispiel:

<Envelope>
    <Body>
        <CreateResponse>
            <OffeneLeistung>
                <objid>12019</objid>
                <isValid>1</isValid>
            </OffeneLeistung>
            ...
        </CreateResponse>
    </Body>
</Envelope>

Objekte ändern (Update)

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.

weiter müssen die zu ändernden Elemente angegeben werden. Im Beispiel wird bei einem Projektbearbeiter mit der Objekt-ID 4019 als Kürzel ab eingetragen:

<Body>
    <Update>
        <Projektbearbeiter>
            <objref>4019</objref>
            <kuerzel>ab</kuerzel>
        </Projektbearbeiter>
        ...
    </Update>
</Body>

Zusatzfelder modifizieren

Das Modifizieren von Zusatzfeldern funktioniert gleich wie oben, als Membernamen wird einfach der Name des Zusatzfeldes eingesetzt. Im Beispiel wird in das Zusatzfeld Projektstand auf einer Projektphase mit der ID 5491 der Text angefangen eingetragen:

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

UpdateResponse Element

Zurückgeliefert wird ein UpdateResponse Element mit folgendem Unterelement:

text: Gibt an, wieviele Objekte geändert wurden

Beispiel:

<Envelope>
    <Body>
        <UpdateResponse>
            <text>Updated 1 Objects</text>
        </UpdateResponse>
    </Body>
</Envelope>

Objekte löschen (Delete)

Um ein Objekt zu löschen, wird ein Delete Element verwendet. Dieses enthält eine Liste der zu löschenden Objekte:

objref: Hier wird die Objekt-ID des zu löschenden Objektes angegeben.

Beispiel:

<Body>
    <Delete>
        <objref>11764</objref>
        ...
    </Delete>
</Body>

DeleteResponse Element

Zurückgeliefert wird ein DeleteResponse Element mit folgendem Unterelement:

text: Gibt an, wie viele Objekte gelöscht wurden

Beispiel:

<Envelope>
    <Body>
        <DeleteResponse>
            <text>Deleted 1 Objects</text>
        </DeleteResponse>
    </Body>
</Envelope>

erstellt:	23.01.2004
geändert:	18.07.2008