Webactions

Eine Webaktion wird von einer Drittanwendung in GEVER registriert. Mit Webaktionen können Knöpfe, Links und Icons direkt an gewissen Stellen in GEVER platziert werden, mit welchen der Benutzer dann Aktionen in einer Drittanwendung auslösen kann.

Registrierte Webaktionen anzeigen (GET)

Webaktionen werden im @actions-Endpoint in einer eigenen Kategorie webactions angezeigt, sofern diese für den aktuellen Kontext und Benutzer verfügbar sind.

Request:

GET /@actions HTTP/1.1
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "object_buttons": ["..."],
  "user": ["..."],
  "webactions": [
    {
      "action_id": 0,
      "title": "Open in ExternalApp",
      "target_url": "http://example.org/endpoint",
      "mode": "self",
      "display": "actions-menu"
    }
  ]
}

Weitere Informationen über die Verwendung des @actions-Endpoints befinden sich in der plone.restapi Dokumentation.

Webactions verwalten

Der /@webactions Endpoint auf dem Root des Mandanten ermöglicht das Verwalten von sogenannten WebActions in GEVER.

Solche Webaktionen können z.B. für oder von Drittanwendungen (mit den nötigen Berechtigungen) registriert werden, um eine möglichst nahtlose Integration in GEVER zu erreichen. Mit Webaktionen können Knöpfe, Links und Icons direkt an gewissen Stellen in GEVER platziert werden, mit welchen der Benutzer dann Aktionen in der Drittanwendung auslösen kann.

Berechtigungen für das Verwalten von Webaktionen

Für das Verwalten von Webaktionen über die REST API wird die permission opengever.webactions: Manage own WebActions benötigt. Diese ist in GEVER standardmässig der Rolle WebActionManager zugewiesen.

Benutzer mit dieser Berechtigungen dürfen neue Webaktionen erstellen, und solche die sie selbst erstellt haben verwalten (auflisten, aktualisieren, löschen).

Erstellen (POST)

POST /@webactions

Erstellt eine neue Webaktion mit den im Body (JSON) angegebenen Daten.

Request:

POST /@webactions HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "title": "Open in ExternalApp",
  "target_url": "http://example.org/endpoint",
  "display": "actions-menu",
  "mode": "self",
  "order": 0,
  "scope": "global"
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: http://demo.onegovgever.ch/@webactions/0

{
  "@id": "http://demo.onegovgever.ch/@webactions/0",
  "action_id": 0,
  "title": "Open in ExternalApp",
  "target_url": "http://example.org/endpoint",
  "display": "actions-menu",
  "mode": "self",
  "order": 0,
  "scope": "global",
  "created": "2019-12-31T17:45:00",
  "modified": "2019-12-31T17:45:00",
  "owner": "webaction.manager"
}
Status Code Beschreibung
201 Created WebAction erfolgreich erstellt. Repräsentation im Response-Body, URL der erstellten Action im Location Header.
400 Bad Request Fehler bei der Schema-Validierung, oder anderer Client-seitiger Fehler. Details im Response-Body.
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.

Dieses Beispiel beschreibt die minimalen Angaben um eine Webaktion zu erstellen. Für Details über alle unterstützten Felder, siehe Eigenschaften von Webaktionen.

Die Response enthält die Repräsentation der Webaktion im Body, inklusive der vom Server bei der Erstellung vergebenen Metadaten (siehe Vom Server vergebene Metadaten).

Der Location Header enthält die kanonische URL der soeben erstellen Webaktion, welche für weitere Requests verwendet werden kann.

Auslesen (GET)

GET /@webactions/(action_id)

Liest die Webaktion mit der entsprechenden action_id aus.

Request:

GET /@webactions/0 HTTP/1.1
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://demo.onegovgever.ch/@webactions/0",
  "action_id": 0,
  "title": "Open in ExternalApp",
  "target_url": "http://example.org/endpoint",
  "display": "actions-menu",
  "mode": "self",
  "order": 0,
  "scope": "global",
  "created": "2019-12-31T17:45:00",
  "modified": "2019-12-31T17:45:00",
  "owner": "webaction.manager"
}
Status Code Beschreibung
200 OK Request erfolgreich beantwortet
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.
404 Not Found WebAction mit dieser action_id konnte nicht gefunden werden.

Auflisten (GET)

GET /@webactions

Listet die von diesem Benutzer erstellten Webaktionen auf.

Request:

GET /@webactions HTTP/1.1
Accept: application/json

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@id": "http://demo.onegovgever.ch/@webactions",
  "items": [
    {
      "@id": "http://demo.onegovgever.ch/@webactions/0",
      "action_id": 0,
      "title": "Open in ExternalApp 0",
      "target_url": "http://example.org/endpoint0",
      "display": "actions-menu",
      "mode": "self",
      "order": 0,
      "scope": "global",
      "created": "2019-12-31T17:45:00",
      "modified": "2019-12-31T17:45:00",
      "owner": "some.user",
    },
    {
      "@id": "http://demo.onegovgever.ch/@webactions/1",
      "action_id": 1,
      "title": "Open in ExternalApp 1",
      "target_url": "http://example.org/endpoint1",
      "display": "title-buttons",
      "mode": "self",
      "order": 0,
      "scope": "global",
      "created": "2019-12-31T17:46:00",
      "modified": "2019-12-31T17:46:00",
      "owner": "webaction.manager",
    }
  ]
}
Status Code Beschreibung
200 OK Request erfolgreich beantwortet
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.

Aktualisieren (PATCH)

PATCH /@webactions/(action_id)

Aktualisiert die durch action_id identifizierte Webaktion mit den im Body (JSON) mitgegebenen Daten.

Request:

PATCH /@webactions/0 HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "title": "New title"
}

Response:

HTTP/1.1 204 No Content
Content-Type: application/json
Status Code Beschreibung
204 No Content WebAction erfolgreich aktualisiert.
400 Bad Request Fehler bei der Schema-Validierung, oder anderer Client-seitiger Fehler. Details im Response-Body.
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.
404 Not Found WebAction mit dieser action_id konnte nicht gefunden werden.

Löschen (DELETE)

DELETE /@webactions/(action_id)

Löscht die durch die action_id identifizierte Webaktion.

Request:

DELETE /@webactions/0 HTTP/1.1
Accept: application/json

Response:

HTTP/1.1 204 No Content
Content-Type: application/json
Status Code Beschreibung
204 No Content WebAction erfolgreich gelöscht.
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.
404 Not Found WebAction mit dieser action_id konnte nicht gefunden werden.

Webaktion aktivieren (POST)

Webaktionen mit dem scope context müssen zuerst auf dem Objekt, auf dem sie angezeigt werden sollen, aktiviert werden.

POST /context/@webactions/(action_id)

Aktiviert die durch die action_id identifizierte Webaktion auf dem Kontext.

Request:

POST /context/@webactions/0 HTTP/1.1
Accept: application/json

Response:

HTTP/1.1 204 No Content
Content-Type: application/json
Status Code Beschreibung
204 No Content WebAction erfolgreich aktiviert.
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.
404 Not Found WebAction mit dieser action_id konnte nicht gefunden werden.

Webaktion deaktivieren (DELETE)

Aktivierte Webaktionen können auch wieder deaktiviert werden.

DELETE /context/@webactions/(action_id)

Deaktiviert die durch die action_id identifizierte Webaktion auf dem Kontext.

Request:

DELETE /context/@webactions/0 HTTP/1.1
Accept: application/json

Response:

HTTP/1.1 204 No Content
Content-Type: application/json
Status Code Beschreibung
204 No Content WebAction erfolgreich deaktiviert.
400 Bad Request Webaction war nicht aktiviert.
401 Unauthorized Authentisierung oder Autorisierung fehlgeschlagen.
404 Not Found WebAction mit dieser action_id konnte nicht gefunden werden.

Eigenschaften von Webaktionen

Folgend ist eine Auflistung aller von Webaktionen unterstützten Felder und deren Typ und Bedeutung.

Feld Typ Beschreibung
title String, obligatorisch Titel der Webaktion
unique_name String, optional Eindeutiger, vom Ersteller der Webaktion kontrollierter Name (siehe Eindeutiger Name )
target_url String, obligatorisch Ziel-URL auf den Endpoint der Drittanwendung mit optionalen Platzhaltern für die Querystring-Parameter (siehe Ziel-URL )
enabled Boolean, optional Kann verwendet werden, um registrierte WebActions temporär zu deaktivieren, i.e. wenn kein Wert gesetzt ist, wird die Webaktion als aktiviert behandelt.
icon_name String, bedingt obligatorisch Font-Awesome CSS-Klasse (z.B. fa-folder)
icon_data String, bedingt obligatorisch Data URI mit Icon, Base64 codiert
display Choice, obligatorisch Darstellungsort der Webaktion.
mode Choice, obligatorisch Zielfenster: bestimmt wie der Link geöffnet wird.
order Integer, 0-100, obligatorisch Sortierhilfe um die Reihenfolge der registrieren Webaktionen bestimmen zu können. 0 bedeutet zuvorderst, 100 bedeutet zuhinterst.
scope Choice, obligatorisch Bestimmt, bei welchen Objekten die Webaktion angeboten wird. Siehe scope.
types Liste von Strings, optional Eine Liste von Inhaltstypen von Objekten, für welche die Webaktion grundsätzlich angeboten wird. Beispiel opengever.document.document, gemäss Auflistung der Inhaltstypen in der Dokumentation. Wenn keine Typen angegeben werden, treffen alle Typen zu.
groups Liste von Strings, optional Liste von Benutzergruppen (IDs, gemäss LDAP). Wenn konfiguriert muss der Benutzer mindestens in einer dieser Gruppen sein damit die Webaktion angeboten wird.
permissions Liste von Strings, optional Liste von Berechtigungen. Wenn konfiguriert muss der Benutzer mindestens eine Berechtigung haben damit die Webaktion angeboten wird. Siehe Berechtigungsabhängige Aktionen.
comment String, optional Freitext für Bemerkungen.

Zielfenster

Über das Feld mode kann gesteuert werden, wie der Link geöffnet wird.

Erlaubte Werte:

Wert Beschreibung
self Das Ziel wird direkt im Tab von GEVER geöffnet. Sinnvoll für ein Redirect-Szenario bei dem der Benutzer am Schluss wieder zurückgeleitet wird.
blank Das Ziel wird in einem neuen Tab geöffnet.
modal Noch nicht implementiert. Das Ziel wird in einem Modal geöffnet.

Scope

Über das Feld scope kann gesteuert werden, bei welchen Objekten die Webaktion angeboten wird.

Wert Beschreibung
global Die Webaktion wird grundsätzlich bei allen Objekten angeboten.
context Die Webaktion wird nur bei Objekten angezeigt, bei denen sie aktiviert wurde
recursive Noch nicht implementiert.

Vom Server vergebene Metadaten

Feld Typ Beschreibung
action_id Integer Pro Mandant eindeutige Identifikation der registrierten Webaktion
created Zeitstempel Zeitpunkt der Erstellung der Webaktion
modified Zeitstempel Zeitpunkt der letzten Modifikation der Webaktion
owner String Benutzer-ID des Erstellers der Webaktion

Darstellungsorte

Die Webaktionen können an verschiedenen Orten dargestellt werden.

Abhängig vom Darstellungsort ist die Angabe eines Icons entweder erlaubt, notwendig oder nicht erlaubt. Dies wird von der API validiert, und eine entsprechende Fehlermeldung (Im JSON-Body der Response, Status-Code 400) weist darauf hin, wenn diese Einschränkung nicht erfüllt ist.

Ein Icon kann entweder via Name (icon_name) oder einer Data URI (Base64 codiert, icon_data) angegeben werden. Falls ein Icon angegeben wird, darf aber nur eines dieser beiden Felder gesetzt sein, nicht beide.

Folgende Darstellungsorte sind als Werte für das Feld display erlaubt:

Darstellungsort Icon Beschreibung
action-buttons optional Die Webaktion wird in der Aktionenliste von Aufgaben, Dokumenten und anderen Inhalten mit einer Aktionsliste dargestellt. Dies funktioniert für Inhaltstypen die eine solche Aktionsliste darstellen (im Moment Aufgaben, Weiterleitungen, Anträge, Dokumente).
actions-menu keines Die Webaktion wird im Menu «Aktionen» angezeigt.
add-menu obligatorisch Die Webaktion wird im Menu «Hinzufügen» angezeigt.
title-buttons obligatorisch Die Webaktion wird als Icon neben der Überschrift dargestellt. Der Titel der Webaktion wird als Tooltip verwendet.
user-menu keines Die Webaktion wird im Benutzermenu dargestellt.

Berechtigungsabhängige Aktionen

Aktionen können eingeschränkt werden, so dass sie nur dann angezeigt werden, wenn der Benutzer mindestens eine der angegebenen Berechtigungen auf dem entsprechenden Kontext besitzt.

Folgende Werte können für das Feld permissions angegeben werden:

Berechtigung Beschreibung
edit Der Benutzer darf den Inhalt bearbeiten.
add:TYP Der Benutzer darf einen neuen Inhalt des angegeben Typs hinzufügen. z.B. add:opengever.dossier.businesscasedossier für das Hinzufügen eines Geschäftsdossiers. Die aktuelle Liste von Typen ist der REST-API-Dokumentation zu entnehmen
trash Der Benutzer darf Inhalt in den Papierkorb verschieben.
untrash Der Benutzer darf Inhalt aus dem Papierkorb wiederherstellen.
manage-security Der Benutzer darf anderen Benutzern Rollen verteilen.

Eindeutiger Name

Das optionale Feld unique_name kann verwendet werden, um sicherzustellen, dass eine Webaktion nicht aus versehen mehrmals erstellt wird.

Dieses Feld kann vom Client, der eine Webaktion erstellt, auf einen beliebigen String gesetzt werden der die Webaktion aus Sicht des Clients eindeutig bezeichnet. Wenn vorhanden, validiert der Server dann dass nur eine einzige Aktion mit diesem Namen existiert, und verweigert sonst das Erstellen oder Aktualisieren einer Aktion.

Im Fall dass ein unique_name angegeben wird und bereits existiert, antwortet der Server mit 400 Bad Request:

Response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "type": "BadRequest",
  "message": "[('unique_name', ActionAlreadyExists(\"An action with the unique_name u'existing-unique-name' already exists\",))]"
}

Ziel-URL

Wenn die Webaktionen an ihrem Darstellungsort in GEVER angezeigt werden, werden der Ziel-URL zwei Querystring-Parameter angehängt:

  • context: Die URL des Inhaltsobjekts, auf welchem die Webaktion angezeigt wird
  • orgunit: Die ID (Kürzel) der aktuellen Organisationseinheit

Beim Anlegen oder Aktualisieren von Webactions können in der Ziel-URL weitere Querystring-Parameter definiert werden, deren Wert als ein Platzhalter betrachtet wird, welcher bei der Anzeige der Webaktion durch die richtigen Werte ersetzt werden.

Request:

POST /@webactions HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "title": "Open in ExternalApp",
  "target_url": "http://example.org/endpoint?geverid={uid}",
  "display": "actions-menu",
  "mode": "self",
  "order": 0,
  "scope": "global"
}

Bei der Anzeige der Webaktion im Menu «Aktionen» auf dem Inhaltsobjekt http://gever/dossier1 wird der Platzhalter {uid} durch den richtigen Wert ersetzt und die standardmässigen Querystring-Parameter angehängt. Der Link der Webaction wäre in diesem Fall also http://example.org/endpoint?geverid=0d12c12a9d4f43e78eba39da93c0080c&context=http://gever/dossier1&orgunit=direktion.

Unterstützte Platzhalter (case-sensitiv):

  • {intid}: Die GEVER-interne numerische ID eines Inhaltsobjekts
  • {uid}: Die GEVER-interne UID eines Inhaltsobjekts
  • {path}: Der Pfad eines Inhaltsobjekts im GEVER-Objektbaum