Vertec REST API

Vertec liefert mit Version 6.8.0.17 ein generisches REST API zu Vertec als Webservice aus.

Er heisst REST und ist im Ordner Einstellungen > Schnittstellen > Webservices zu finden:

Der REST Webservice wird inaktiv ausgeliefert. Um ihn aktivieren und verwenden zu können, müssen dieselben Bedingungen erfüllt sein wie bei allen Webservices (Berechtigungen und API Token vorhanden).

Vertec via REST API Webservice ansprechen

Der Aufruf erfolgt über <ServerURL>/api/webservice/REST.

Auf die Vertec Objekte kann man via /objects/<classname> zugreifen. Objekte können abgefragt (GET), geändert (PUT), erzeugt (POST) oder gelöscht (DELETE) werden.

Hinweis zur Angabe des Klassennamens: In früheren Vertec Versionen konnten einzelne Objekte auch ohne Angabe des Klassennamens, nur mit ihrer ID, direkt abgefragt werden. Ab Vertec 6.8.0.20 ist dies nicht mehr möglich, der Klassenname muss immer angegeben werden. Die Gross-/Kleinschreibung des Klassennamens (in Deutsch oder Englisch) spielt an dieser Stelle keine Rolle. 

Dazu können optional die Query Parameter functions, bi_measures, result_members und result_ocl mitgegeben werden (siehe die Abschnitte Funktionen, BI Daten (Kennzahlen) und Rückgabewerte).

Berechtigungen

Um Anfragen an das REST API machen zu können, brauchen Nicht-Administratoren folgende Rechte:

• Recht Ausführen auf der Klasse Webservicedefinition
• Für Abfragen via SQL braucht es das SQL Query Recht.
• In Vertec Versionen bis 6.8.0.19 braucht es auch für Member-Suchen das SQL Query Recht. Ab Vertec 6.8.0.20 funktionieren einfache Member-Suchen ohne diese Berechtigung. Geprüft werden erst die Resultate, und die Objekte, auf die der User keine Leserechte hat, werden aus der Liste entfernt. 

Objekte abfragen (GET)

Einzelne Objekte abfragen

• Via Interne ID: /objects/project/1665
  • Mehrere Objekte können ab Vertec 6.8.0.20 mit dem Query Parameter ids in einer Komma-separierten Liste abgefragt werden: /objects/project?ids=1665,1669
• Via Eintrag ID: /objects/User/UserAdmin
• Den aktuell angemeldeten Benutzer liefert folgender Endpunkt: /functions/currentuser
• Die Metadaten (Klasse und Standardanzeige) eines einzelnen Objekts liefert ab Vertec 6.8.0.20 der Endpunkt /identify/objid

Globale Abfragen

Eine globale Abfrage der Daten kann via Member-Suche, via OCL oder via SQL geschehen.

Dafür wird eine Query abgesetzt direkt auf der Klasse, also z.B. auf /objects/Project. Die Query startet mit einem ?, gefolgt von den entsprechenden Query-Parametern. Mehrere Query-Parameter werden mit & angehängt.

Es muss zwingend eine Query angegeben werden. Es ist nicht möglich, alle Objekte der Klasse ohne Query zu laden.

Für die gefundenen Objekte wird im Anschluss eine Berechtigungsprüfung vorgenommen. Objekte, auf denen der angemeldete User keine Leserechte hat, werden aus der Liste entfernt.

Abfrage via Member-Suche

Member-Suchen sind immer global. Wird trotzdem eine ID mitgegeben für ein einzelnes Objekt, wird diese ignoriert. 

Members sind Attribute (inkl. Zusatzfelder) und Associations (inkl. Custom-Links). Alle Members finden Sie im Vertec Model Browser. Es können nur persistente Member abgefragt werden.

Mit dem Query-Parameter query_member wird der Membername angegeben, mit query_value der gesuchte Wert. Auch Zusatzfelder und Custom-Links werden einfach über den entsprechenden Membernamen abgefragt.

Für jedes abgefragte Member wird die Kombination von query_member und query_value nummeriert:

• query_member0 und query_value0,
• query_member1 und query_value1, etc. 

Bei der Abfrage eines Attributs wird als query_value der gesuchte Wert eingegeben, passend zum Datentyp des Members:

/objects/Project?query_member0=code&query_value0=com%

sucht nach Projekten, deren Code mit com beginnt. Als Operatoren unterstützt werden = sowie <, >, <=, >= für die Datentypen Integer, Date, Datetime und Currency.

Bei der Abfrage einer Association wird als query_value die Interne ID des gesuchten Objekts angegeben:

/objects/Project?query_member0=type&query_value0=179.

Abfrage via SQL

Mit dem Query-Parameter sql kann eine globale SQL Abfrage abgesetzt werden: /objects/Project?sql=bold_id IN (SELECT project FROM openservice).

Abfrage via OCL

Mit dem Query-Parameter ocl wird eine OCL Expression abgesetzt: /objects/user?ocl=user->select(active).

Im Gegensatz zu SQL können OCL Expressions auch auf einzelnen Objekten abgesetzt werden: /objects/user/1665?ocl=openservices.

Rückgabewerte

Das Resultat enthält ein Objekt oder eine Liste von Objekten. Zurückgegeben werden standardmässig von jedem Resultatobjekt die Interne ID (objid), die Standardanzeige des Objekts (stringrepresentation), der Klassenname (classname) sowie bei UserEinträgen, ob das Objekt gültig ist (isvalid) und der Grund (hintisvalid), wenn ein Objekt ungültig ist.

Um weitere Members auszugeben, kann mit dem Query-Parameter result_members eine kommagetrennte Liste der entsprechenden Members angegeben werden: /objects/project/1665?result_members=code,description,regarding. Die angegebenen Members werden für jedes Resultatobjekt ausgegeben.

Ab Vertec 6.8.0.20 kann mit result_ocl auch OCL auf den Resultatobjekten ausgeführt werden. Der Query-Parameter erwartet eine Bezeichnung für die Ausgabe sowie eine OCL Expression für den Wert: ?result_ocl:anzahlleistungen=offeneleistungen->size.

Funktionen

Über den Query-Parameter functions können Funktionen auf Projektbearbeitern, Projekten und Phasen aufgerufen werden. Mehrere Funktionen können kommasepariert angegeben werden.

Mit den Parametern date_from und date_till können nach Bedarf Start- und Enddatum übergeben werden. Diese müssen unabhängig von den Regionaleinstellungen im Format ISO 8601 (2026-03-31) angegeben werden.

Das Beispiel ruft die Sollzeit und die Arbeitszeit des angemeldeten Bearbeiters im Monat Januar 2026 auf:

/functions/currentuser?functions=getStdHours,getWorkingHours&date_from=2026-01-01&date_till=2026-01-31

{
    "classname": "User",
    "stringrepresentation": "Christoph Keller",
    "objid": 1588,
    "isvalid": true,
    "hintisvalid": "",
    "getStdHours": 10710,
    "getWorkingHours": 10785
}

Liste der Funktionen

Alle Funktionen, die über functions aufgerufen werden können, sind hier nachfolgend aufgelistet.

Funktionen auf Projektbearbeitern
Viele dieser Werte sind dieselben und funktionieren gleich wie die OCL Operatoren für Bearbeiter. Diese sind entsprechend verlinkt.
getStdHours		getVacationCarryoverDate	getAssignedStdHoursGroup
getWorkingHours		getVacationStart	getStdHoursOnlyGroupAbs
getOvertimeCarryover		getVacationEnd	getEmploymentLevel
getOvertimeCarryoverDate		getVacationBalance	getAbsenceTimeOff
getOvertimeBalance		getVacationBalanceAccrued	getStdHoursGroup
getVacationCredit		getSalary	currentAbsences
getVacationTaken		getOverheads	getTrackingUsers
getVacationCarryover		getAssignedStdHours	isBlockedDate
enteringprojects	Liste der Projekte, für die der Benutzer Leistungen und Spesen erfassen darf.

Funktionen auf Projekten
enteringphases	Liste der Projektphasen des Projekts, auf die der Benutzer Leistungen und Spesen erfassen darf.

Funktionen auf Projektphasen
enteringservicetypes	Liste der Tätigkeiten, die der Benutzer bei der Leistungserfassung auf dieser Phase verwenden darf.
enteringexpensetypes	Liste der Spesentypen, die der Benutzer bei der Spesenerfassung auf dieser Phase verwenden darf.

BI Daten (Kennzahlen)

Das REST API kann BI Kennzahlen für die Objekte liefern. Die Parameter dafür sind:

• bi_measures: Hier wird der interne Name der BI Kennzahl angegeben. Es können mehrere BI Kennzahlen kommasepariert angegeben werden. 
• bi_date_from: Startdatum im Format ISO 8601 (2026-01-20)
• bi_date_till: Enddatum im Format ISO 8601
• bi_currency: Optional. Für Werte der Einheiten Betrag oder Stundensatz kann optional ein Währungscode mitgegeben werden, falls die Ausgabe nicht in Leitwährung erfolgen soll. Siehe dazu auch den Artikel Business Intelligence.
• projection_dimension: Optional. Hier kann eine (einzelne) Dimension angegeben werden, nach der das Resultat gruppiert wird (z.B. "Projekt,Projektbearbeiter" ). Eine detaillierte Beschreibung dazu finden Sie im Artikel BI API.

Beispiel

/objects/user/1588?bi_measures=FeesExt,FeesExtCharged&bi_date_from=2025-01-01&bi_date_till=2025-12-31

{
    "classname": "User",
    "stringrepresentation": "Christoph Keller",
    "objid": 1588,
    "isvalid": true,
    "hintisvalid": "",
    "FeesExt": 68681.25,
    "FeesExtCharged": 34013.75
}

Daten ändern (PUT)

Mit einem PUT-Aufruf wird ein bestehendes Vertec Objekt angepasst. Die zu ändernden Felder werden im JSON-Body übergeben. Die Objekt-ID kommt aus der URL und der Body enthält die neuen Werte für die gewünschten Members.

• PUT /objects/User/UserAdmin oder /objects/User/1588  
• Body: JSON-Set mit den zu ändernden Members

Dabei wird pro Zeile ein Membername als String angegeben, gefolgt vom Wert, der eingetragen werden soll, passend zum Datentyp des zu setzenden Feldes. Datentypen werden validiert und konvertiert (z.B. Datum im ISO-Format, Booleans, Ganzzahlen, Währungen). 

{
  "abbreviation": "AD",  
  "level": 5270,    
}

Für jedes Feld prüft das API, ob es ein gültiges, persistentes Feld der Klasse ist. Zusatzfelder werden gleich behandelt. 

Bei Associations wird als Wert die interne ID (objid) des zu verknüpfenden Objekts übergeben. 

• Single-Links: die interne ID des Objekts
• Multi-Links: die interne ID eines einzelnen Objekts oder einer Liste von Objekten
• Bei Custom-Links wird die Rolle als Member gesetzt und als Wert ebenfalls die interne ID übergeben:

  {"Verwaltungsrat": 47083}

Im Erfolgsfall wird wie bei einer GET-Abfrage ein Resultat zurückgegeben, das das aktualisierte Objekt enthält.

Objekte erzeugen (POST)

Mit einem POST-Aufruf wird ein neues Vertec Objekt angelegt. Die Klasse des Objekts wird über die URL festgelegt und die Werte der Felder werden im JSON-Body übergeben. Im Unterschied zu PUT geht es hier nicht um das Aktualisieren eines bestehenden, sondern um das Erzeugen eines neuen Objektes.

• POST /objects/Project erzeugt ein neues Projekt

Der JSON Body sieht aus wie bei PUT und schreibt die entsprechenden Members auf dem neu erstellten Objekt. ​Tritt dabei ein Fehler auf (z.B. ungültiger Wert oder fehlendes Recht), wird das neu erzeugte Objekt wieder gelöscht und eine Fehlermeldung zurückgegeben.

Im Erfolgsfall entspricht die Antwort der Ausgabe eines GET-Aufrufs für das neu angelegte Objekt.

Objekte löschen (DELETE)

Über einen DELETE-Aufruf wird ein bestehendes Vertec Objekt endgültig gelöscht. Die zu löschende Instanz wird dabei über die objid oder die entryID in der URL identifiziert.

• DELETE /objects/activity/13787

Das angegebene Objekt wird gesucht und anschliessend falls möglich gelöscht.

Im Erfolgsfall wird kein Objekt als JSON-Antwort zurückgeliefert, sondern nur der HTTP-Status 200 OK zurückgegeben.

Dokumente schreiben

Über das REST API können auf Aktivitäten, Spesen und Kreditoren auch Dokumente (z.B. PDFs oder Bilder) gespeichert werden. 

Im JSON-Body eines PUT- oder POST-Aufrufs wird das entsprechende Dokumentfeld (Membername) mit einem Base64-kodierten String gefüllt (Wert). Das API dekodiert diesen Base64-String und speichert die Datei intern in einem eigenen Dokumentobjekt.

Beispiel: Dokument an eine Rechnung anhängen

• PUT /objects/Invoice/9876 
• JSON-Body:

{
  "document": BASE64DATEN
}

Hier wird für die Rechnung mit der internen ID 9876 ein Dokument gespeichert, indem das Feld document mit dem Base64-kodierten Inhalt gefüllt wird. 

Spezialfall bei Aktivität: Bei Aktivitäten ist zusätzlich das Feld documentfullname erforderlich. Dieses Feld enthält den Dateinamen inklusive Dateiendung, damit Vertec den Namen des abgelegten Dokuments kennt. 

• PUT /objects/Activity/12345  
• JSON-Body:

{
  "document": BASE64DATEN
  "documentfullname": "Besuchsbericht.pdf"
}

In diesem Beispiel wird bei der Aktivität mit der objid 12345 ein Dokument mit dem Dateinamen Besuchsbericht.pdf gespeichert. Das API ruft dazu intern die passende Dokument-Funktion der Klasse Aktivität auf und legt ein DocumentData-Objekt mit den übergebenen Binärdaten an. 

Logging des API-Zugriffs

Die für die Nutzung des REST APIs notwendigen Definitionen sind im Vertec Python Modul "vtcrest" implementiert.

Die Webserviceklasse VertecREST verfügt über eine Methode onrequest(self), die bei jedem WebRequest aufgerufen wird. In der Basisimplementierung hat diese Methode keine Funktion. Sie können diese Methode in einer abgeleiteten Klasse überschreiben, um für jeden Request eine definierte Funktion, beispielweise Logging, auszuführen. Tauschen Sie dann die Klassenreferenz im Webservice (vtcrest.VertecREST) gegen Ihre neue Klassenreferenz aus. Nachfolgend ein Beispiel für eine onrequest(self) Implementierung:

Ein Script namens CustomREST (benötigt erweiterte Berechtigungen):

from vtcrest import VertecREST

class REST(VertecREST):

    def onrequest(self):
        method = self.http_method
        path = "/".join(self.path_parameters)
        query = self.querystring
        self.log("Received request: {} {}?{}".format(method, path, query))

Der REST Webservice-Eintrag:

Fehlercodes

Das REST API antwortet üblicherweise mit den folgenden HTTP Fehlercodes:

400 Bad Request
Dieser Statuscode wird für alle fachlichen und technischen Fehler verwendet, die durch falsche Eingaben oder ungültige Anfragen entstehen. Typische Ursachen sind: 

• Ungültige Klassen- oder Feldnamen (z.B. „Attribut 'xyz' nicht gefunden für Klasse Project“)  
• Falsche Datentypen (z.B. „Value 'abc' für member 'startdate' konnte nicht zu 'date' konvertiert werden“)  
• Ungültige Objekt-IDs (z.B. „No Vertec object was found with objid=999999“)  
• Fehlende oder falsche Pflichtparameter (z.B. „'customer' is required as parameter“)  
• Syntaxfehler in OCL/SQL-Ausdrücken  
• Ungültige Base64-Daten bei Dokumenten  
• Logikfehler (z.B. „Association 'customer' must be a multi-link, but is a single-link“) 

403 Forbidden
Dieser Statuscode signalisiert fehlende Berechtigungen für die angeforderte Operation. Häufige Ursachen sind:

• Fehlende Leseberechtigung für Objekte/Felder („Read access denied while reading member 'salary'“)  
• Fehlende Schreib-/Löschberechtigung („Write access denied when writing value '1000' for member 'budget'“)  
• SQL-Query-Rechte fehlen („getwithsql failed - no SQL query right“)  
• OCL-Ausführungsrechte fehlen  
• BI-Datenzugriff nicht erlaubt  
• Zugriff auf WrapperLinkTypes untersagt 

Die Fehlermeldungen enthalten meist:  

•   betroffene Klasse und interne ID
•   betroffenes Feld/Parameter  
•   erwarteter Datentyp/Wert  
•   Original-Fehlertext aus Vertec (z.B. von `evalocl`, `bigetdata`, `getwithsql`) 

Bei korrekten Anfragen wird immer HTTP 200 OK zurückgegeben (auch bei DELETE).