RESTful Webservices
Benutzer- und Gruppenlisten abrufen
Einführung
todo4teams bietet eine umfangreiche RESTful Webservices API an. REST steht für Representational State Transfer, siehe here für eine Erläuterung des Standards.
Diese Schnittstelle erlaubt externen Anwendungen, Tickets zu erstellen, zu ändern, abzurufen, zu suchen und zu löschen.
Die todo4teams RESTful Services können mir den Datenformaten XML and JSON, sowie beim Abruf von Tickets in HTML) verwendet werden. Der Client wählt über das HTTP-Header-Attribut Accept (beim Abruf von Daten) und das Attribut Content-Type (beim Senden von Daten) das jeweilige Format.
Zum Testen der API benutzen Sie am Besten die Kommandos curl or wget auf der Komandozeile. In den folgenden Beispielen verwenden wir curl.
todo4teams schränkt den Zugriff auf die API durch einen IP-filter und/oder HTTP Basic Authentication ein. IP-Filterung bedeutet, dass nur Zugriffe von einer bestimmten IP, einem Teilnetz o.Ä. erlaubt werden. Sie können die erlaubten Systeme mit der Rolle admin or superadmin in todo4teams unter dem Menüpunkt "Systeme" einstellen.
Beim Zugriff auf die REST-URLs ist es entscheidend, die richtigen HTTP-Methoden GET, POST, PUT oder DELETE für die jeweilige Aktion (abrufen, ändern, erzeugen, löschen) zu verwenden. In den nachfolgenden Beispielen wird die Methode dem curl-Befehl mittels des Parameters X übergeben. REST-Clients der gängigen Programmiersprachen bieten eine entsprechende Auswahl der HTTP-Methode.
Bitte beachten Sie, dass Sie mit den API-Aufrufen keine Workflow-Operationen (Sperren, Beenden,...) auf den Tickets ausführen können! Alle Aufrufe modifizieren die Ticket-Daten, ohne den Ticket-Status zu verändern. Die Änderungen werden augenblicklich für die betroffenen angemeldeten Benutzer sichtbar.
Beachten Sie auch, dass die Einstellungen der Systeme über einen Kartenreiter "Eintreffen-Skript" verfügen, mit dem Sie Code ablegen können, der beim Eintrefen neuer Tickets von diesem System ausgeführt werden soll.
Erzeugung neuer Ticks mittels REST
Um ein neues Ticket über die REST-API zu erzeugen, senden Sie eine HTTP POST-Anfrage mit dem folgenden Inhalt an die URL https://<yourtodoserver>/todo4teams/rest/tasks:
"addressedGroupId":17,
"attachments":[{"content": [72,101,108,108,111,32,87,111,114,108,100,34,10],"filename":"attachment.txt"}],
"description":"This is my first todo",
"minutes":60,
"ownerId":7,
"priority":0,
"title":"First"
}
Dieser JSON-Code erzeugt ein Ticket mit dem Titel "First", der Berschreibung "This is my first todo", einer Zielzeit von 60 Minuten an die Gruppe mit der ID 17 und dem Benutzer mit der ID 7 als Besitzer. Gleichzeitig wird ein Dateianhang "attachment.txt" an das Ticket angehängt.
Übergeben Sie als ownerId die 0 or lassen Sie das Attribut aus, um ein anonymes (besitzerloses) Ticket zu erzeugen.
In der Rückgabe erhalten Sie die ID des erzeugten Tickets.
Testen Sie den Aufruf, indem Sie obigen JSON-Code in eine Datei "ticket.json" speichern und folgenden Befehlt aufrufen (ersetzten Sie Gruppen- und Benutzer-IDs sowie die Server-URL passend zu Ihrem System):
oder, falls Ihre Installation eine Authentifizierung erfordert (in diesem Beispiel für den Benutzer 'apiuser' mit dem Passwort 'supersecret'):
Beachten Sie, dass der Dateiinhalt der angefügten Datei (im Attribut "content") als Array von Byte-Werten übergeben werden muss.
Das folgende Beispiel erweitert das Tickt um zwei Formulare und füllt mehrere Feldwerte. Die IDs der Formulare und die Feldnamen müssen mit den Formularen in Ihrem übereinstimmen:
"addressedGroupId":17,
"description":"This is my first todo",
"forms":[
{
"id":41,
"fields":
{"Straße_t":"",
"Name":"Meier",
"Vorname":"Max",
}
},
{
"id":42,
"fields":{
"DeviceID" : "54354325435"
}
}
],
"minutes":480,
"ownerId":7,
"priority":0,
"title":"The title!"
}
Die Zielzeit wird relativ mit dem Attribut minutes angegeben. Das direkte Setzen eine Datums oder einer Uhrzeit ist nicht möglich.
Falls Sie lieber XML als JSON-Code senden möchten, nutzen Sie das folgende Beispiel :
Hier wird ebenfalls ein Ticket mit einem aktivierten Formular gesendet.
<task>
<addressedGroupId>17</addressedGroupId>
<description>This is my first todo</description>
<forms>
<form>
<id>41</id>
<fields>
<entry>
<key>Name_t</key>
<value xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">Meier</value>
</entry>
</fields>
</form>
</forms>
<minutes>300</minutes>
<ownerId>7</ownerId>
<priority>0</priority>
<title>The XML Title</title>
</task>
Speichern Sie den XML-Code in eine Datei "ticket.xml" und senden Sie sie mit dem Kommando ab. Beachten Sie, dass hier Content-Type: application/xml gesetzt wird:
Als Rückgabe erhalten Sie einen Code wie diesen mit der ID des neuen Tickets:
<id>22232</id>
Abruf einzelner Tickets
Für den Abruf einzelner Tickets mit bekannter ID benutzen Sie URLs der Form https://yourtodoserver/todo4teams/rest/tasks/<ticketid>, zum Beispiel http://yourtodoserver/ToDoServer/rest/tasks/14515 und verwenden Sie die HTTP-GET-Methode.
Sie können diese URLs auch im Browser testen und erhalten dann eine einfache HTML-Ausgabe des Tickets.
Eine Abfrage im JSON-Format ...
könnte etwa dieses Ergebnis liefern:
"addressedGroupId": 110,
"assignedUserId": 0,
"attachments": [
{
"content": [72,101,...10],
"filename": "test.txt"
}
],
"creationDate": "2025-01-28 10:29",
"description": "hello",
"forms": [],
"id": 22217,
"minutes": -16,
"ownerId": 223,
"priority": 0,
"properties": {
"AuthUserId": "226"
},
"scheduledEndDate": "2025-01-28 14:36",
"status": 0,
"title": "TEST"
}
Für das XML-Format würde dieser Aufruf verwendet:
Das Ergebnis in XML sähe etwa so aus:
<task>
<addressedGroupId>110</addressedGroupId>
<assignedUserId>0</assignedUserId>
<attachments>
<attachment>
<content>SGVsbG8gV29ybGQhCg==</content>
<filename>test.txt</filename>
</attachment>
</attachments>
<creationDate>2025-01-28 10:29</creationDate>
<description>hello</description>
<forms />
<id>22217</id>
<minutes>234</minutes>
<ownerId>223</ownerId>
<priority>0</priority>
<properties>
<entry>
<key>AuthUserId</key>
<value>226</value>
</entry>
</properties>
<scheduledEndDate>2025-01-28 14:36</scheduledEndDate>
<status>0</status>
<title>TEST</title>
</task>
Tickets ändern
Um ein existierendes Ticket mit bekannte ID zu ändern, senden Sie die XML- oder JSON-Repräsentation als PUT-Request an die URL des Tickets, z.B. https://yourtodoserver/todo4teams/rest/tasks/22217. Setzen Sie dabei stets den entsprechenden Content-Type, wie in den folgenden Beispielen:
Dieser JSON-Datensatz soll gesendet werden und wird als Datei ticket.json gespeichert.
"addressedGroupId": 110,
"minutes": 10,
"ownerId": 0,
"priority": 2,
"title": "This ticket was updated by a REST service call."
}
Der nachfolgende Aufruf ändert Ticket 22217 mit den in ticket.json angegebenen Werten...
... bzw. mit einem entsprechenden Datensatz im XML-Format:
<task>
<addressedGroupId>110</addressedGroupId>
<description>This ticket was updated using REST.</description>
<minutes>10</minutes>
<ownerId>0</ownerId>
<priority>2</priority>
<title>The updated XML Title</title>
</task>
Bitte beachten Sie:
- Um die Zielzeit des Tickets zu setzen, verwenden Sie immer das Attribut minutes. Eine direkte Änderung von creationDate, startDate, endDate oder scheduledEndDate wird nicht unterstützt.
- Sie können Ticket unabhängig vin ihrem Status ändern (offen, gesperrt, erledigt...). Bevorzugt sollten Sie Tickets im zustand 'offen' ändern. Benutzen Sie die GET Methode (siehe oben) um den Ticket-Status vor der Änderung zu prüfen!
- Formulare und Dateianhänge werden exakt so übernommen, wie über REST gesendet: Fehlt ein Anhang in der REST-Representation bei der Änderung, dann verschwindet der Anhang vom Ticket. Gleiches gilt für Formulare.
- Lassen Sie die Attribute ownerId und addressedGroupId aus (oder weisen Sie 0 zu) wenn die Eigenschaft unverändert bleiben soll.
Löschen von Tickets
Sie können Tickets mit der HTTP-DELETE-Methode auf die URL des Tickets löschen, zum Beispiel:
Tickets suchen per REST-Aufruf
Sie haben die Möglichkeit, Tickets per REST-Aufruf mit einer flexiblen Abfrage-Syntax zu suchen. Verwenden Sie dazu die URL https://yourserverhost/todo4teams/rest/query?q=...
Sie erhalten eine Liste der passenden Ticket im JSON- oder XML-Format.
Der HTTP-Parameter q gibt dabei die "Where"-Bedingung der Suche an. Der eigentliche Such-Begriff muss dabei URL-kodiert übergeben werden.
Tickets mit "Meier" im Betreff und einer ID größer als 14.000 würden Sie mit dieser Klausel suchen: t.id>14000 and t.title like '%Meier%'
oder entsprechend URL-kodiert: t.title+like+%27%25Meier%25%27 , damit ergibt sich folgender Aufruf:
Benutzen Sie den Alias 't' für das Ticket selbst, z.B. t.id für die ID und t.title für den Titel.
Mit dem optionalen Parameter limit können Sie die Anzahl der zurückgegebenen Treffer begrenzen. Der Parameter withAttachments=true unterdrückt, dass die Dateianhänge aller Treffer mitgeliefert werden. Das ist besonders wichtig, wenn Sie lange Ticket-Listen abrufen. Ansonsten könnten u.U. Ergebnisse mit mehreren hundert Megabyte erzeugt werden.
Ein Abfrageergebnis im JSON-Format könnte so aussehen:
Abruf der Benutzer- und Gruppenliste
Sie können die Liste aller Benutzer und Gruppen über die REST-API abrufen. Benutzen Sie die URLs https://yourtodoserver/todo4teams/rest/users or https://yourtodoserver/todo4teams/rest/workgroups mit Accept-Type application/xml oder application/json wie in den folgenden Beispielen:
Abruf der Benutzerliste (es werden nur aktive Benutzer ausgegeben):
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET "https://yourtodoserver/todo4teams/rest/users"
Abruf der Gruppenliste:
curl -H "Accept: application/json" -H "Content-Type: application/json" -X GET "http://localhost:8080/ToDoServer/rest/workgroups"