Beobachter¶
Der @watchers
Endpoint dient dazu, für Dokumente, Aufgaben und Weiterleitungen Beobachter zu registrieren.
Diese Endpoints liefern zur Zeit sowohl referenced_users
als auch referenced_actors
zurück. referenced_users
wird in einer späteren Version jedoch nicht mehr unterstützt werden, und wird durch referenced_actors
abgelöst.
Auflistung¶
Ein Beobachter kann verschiedene Rollen haben, beispielsweise die Rollen Auftraggeber (task_issuer
), Auftragnehmer (task_responsible
) oder Beobachter (regular_watcher
). Mittels eines GET-Requests können alle Beobachter und alle Rollen eines Inhalts abgefragt werden.
Beispiel-Request:
GET /task-1/@watchers HTTP/1.1 Accept: application/json
Beispiel-Response:
HTTP/1.1 200 OK Content-Type: application/json { "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23/task-1/@watchers", "referenced_users": [ { "@id": "https://example.org/@users/peter.mueller", "id": "peter.mueller", "fullname": "Mueller Peter" }, { "@id": "https://example.org/@users/rolf.ziegler", "id": "rolf.ziegler", "fullname": "Ziegler Rolf" } ], "referenced_actors": [ { "@id": "https://example.org/@actors/peter.mueller", "identifier": "peter.mueller", }, { "@id": "https://example.org/@actors/rolf.ziegler", "identifier": "rolf.ziegler", } ], "referenced_watcher_roles": [ { "id": "regular_watcher", "title": "Beobachter" }, { "id": "task_issuer", "title": "Auftraggeber" }, { "id": "task_responsible", "title": "Auftragnehmer" }, ], "watchers_and_roles": { "peter.mueller": [ "task_issuer" ], "rolf.ziegler": [ "regular_watcher", "task_responsible" ] } }
Beobachter als erweiterbare Komponente¶
Die Beobachter können als Komponente eines Inhalts direkt über den expand
-Parameter eingebettet werden, so dass keine zusätzliche Abfrage nötig ist.
Beispiel-Request:
GET /task-1?expand=watchers HTTP/1.1 Accept: application/json
Beispiel-Response:
HTTP/1.1 200 OK Content-Type: application/json { "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23/task-1?expand=watchers", "@components": { "watchers": { "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23/task-1/@listing-stats", "referenced_users": ["..."], "referenced_actors": ["..."], "referenced_watcher_roles": ["..."], "watchers_and_roles": { "...": "..." } } }, "...": "..." }
Beobachter hinzufügen¶
Ein Benutzer kann mittels POST-Requests als Beobachter mit der Rolle regular_watcher
bei einem Inhalt registriert werden.
Beispiel-Request:
POST /task-1/@watchers HTTP/1.1 Accept: application/json { "userid": "peter.mueller" }
Beispiel-Response:
HTTP/1.1 204 No content
Beobachter entfernen¶
Mittels DELETE-Requests kann die Rolle regular_watcher
eines Beobachters von einem Inhalt wieder entfernt werden.
Beispiel-Request:
DELETE /task-1/@watchers HTTP/1.1 Accept: application/json
Beispiel-Response:
HTTP/1.1 204 No content
Liste von möglichen Beobachtern¶
Der @possible-watchers
-Endpoint liefert eine Liste von Benutzern welche als Beobachter für den aktuellen Kontext hinzugefügt werden können.
Weil es üblich ist, dass man sich selbst als Beobachter hinzufügen möchte, wird der eigene Benutzer in der Sortierreihenfolge immer zuoberst dargestellt. Alle restlichen Benutzer werden nach Name und Vorname sortiert. Der eigene Benutzer sowie alle anderen Benutzer werden nur dann angezeigt, wenn diese noch keine Beobachter-Rolle besitzen.
Beispiel-Request:
GET /task-1/@possible-watchers HTTP/1.1 Accept: application/json
Beispiel-Response:
HTTP/1.1 200 OK Content-Type: application/json { "@id": "/task-1/@possible-watchers", "items": [ { "title": "Mueller Peter (peter.mueller)", "token": "peter.mueller" }, { "title": "Ziegler Rolf (rolf.ziegler)", "token": "rolf.ziegler" }, { "...": "..." }, ], "items_total": 17 }
Resultate filtern¶
Mit dem query
-Parameter können die Resultate gefiltert werden. Es werden die Felder:
- Vorname
- Nachname
- Userid
beim filtern berücksichtigt.
Beispiel-Request:
GET /task-1/@possible-watchers?query=Peter HTTP/1.1 Accept: application/json
Beispiel-Response:
HTTP/1.1 200 OK Content-Type: application/json { "@id": "/task-1/@possible-watchers", "items": [ { "title": "Mueller Peter (peter.mueller)", "token": "peter.mueller" } ], "items_total": 1 }
Paginierung¶
Die Paginierung funktioniert gleich wie bei anderen Auflistungen auch (siehe Kapitel Paginierung).