Add admin docs for the windmill integration

Signed-off-by: Marcel Klehr <[email protected]>

admin_manual/contents.rst

@@ -18,6 +18,8 @@ Table of contents
     office/index
     reference/index
     ai/index
+    webhook_listeners/index
+    windmill_workflows/index
     configuration_database/index
     configuration_mimetypes/index
     maintenance/index

admin_manual/webhook_listeners/index.rst

@@ -0,0 +1,137 @@
+=================
+Webhook Listeners
+=================
+
+.. _webhook_listeners:
+
+Nextcloud supports listening to internal events via webhooks.
+
+Installation
+------------
+
+ * Enable the ``webhook_listeners`` app that comes bundled with Nextcloud
+
+.. code-block:: bash
+
+   occ app:enable webhook_listeners
+
+Listening to events
+-------------------
+
+You can use the OCS API to add webhooks for specific events: https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html#/operations/webhook_listeners-webhooks-index
+
+Filters
+~~~~~~~
+
+When registering a webhook listener, you can specify a filter parameter. The value of this parameter must be a JSON object whose properties represent filter conditions. The ``{}`` is an empty query, meaning no specific criteria, so all events are matched.
+
+If you would like to match events fired by a specific user, you can pass ``{ "user.uid": "bob" }`` to match all events fired in the context of user ``"bob"``.
+
+If you would like to enforce multiple criteria, you can simply pass multiple properties ``{ "event.tableId": 42, "event.rowId": 3 }``
+
+You can also use additional comparison operators (``$eq, $ne, $gt, $gte, $lt, $lte, $in, $nin``) as well as logical operators (``$and, $or, $not, $nor``). For example use ``{ "time" : { "$lt": 1711971024 } }`` to accept only events prior to April 1st 2024 and ``{ "time" : { "$not": { "$lt": 1711971024 } } }`` to accept events after April 1st 2024.
+
+Nextcloud Webhook Events
+------------------------
+This is a non-exhaustive list of available events. It features the event ID and the available variables for filtering.
+
+ * OCA\\Tables\\Event\\RowAddedEvent
+
+  .. code-block:: text
+
+    array{
+      "user": array {"uid": string, "displayName": string},
+      "time": int,
+      "event": array{
+        "class": string,
+        "tableId": int,
+        "rowId": int,
+        "previousValues": null|array<int, mixed>,
+        "values": null|array<int, mixed>
+      }
+    }
+
+ * OCA\\Tables\\Event\\RowDeletedEvent
+
+  .. code-block:: text
+
+     array{
+       "user": array {"uid": string, "displayName": string},
+       "time": int,
+       "event": array{
+         "class": string,
+         "tableId": int,
+         "rowId": int,
+         "previousValues": null|array<int, mixed>,
+         "values": null|array<int, mixed>
+       }
+     }
+
+ * OCA\\Tables\\Event\\RowUpdatedEvent
+
+  .. code-block:: text
+
+    array{
+      "user": array {"uid": string, "displayName": string},
+      "time": int,
+      "event": array{
+        "class": string,
+        "tableId": int,
+        "rowId": int,
+        "previousValues": null|array<int, mixed>,
+        "values": null|array<int, mixed>
+      }
+    }
+
+ * OCP\\Files\\Events\\Node\\BeforeNodeCreatedEvent
+
+  .. code-block:: text
+
+    array{
+      "user": array {"uid": string, "displayName": string},
+      "time": int,
+      "event": array{
+        "class": string,
+        "node": array{"id": string, "path": string}
+      }
+    }
+
+ * OCP\\Files\\Events\\Node\\BeforeNodeWrittenEvent
+
+  .. code-block:: text
+
+    array{
+      "user": array {"uid": string, "displayName": string},
+      "time": int,
+      "event": array{
+        "class": string,
+        "node": array{"id": string, "path": string}
+      }
+    }
+
+ * OCP\\Files\\Events\\Node\\BeforeNodeDeletedEvent
+
+  .. code-block:: text
+
+    array{
+      "user": array {"uid": string, "displayName": string},
+      "time": int,
+      "event": array{
+        "class": string,
+        "node": array{"id": string, "path": string}
+      }
+    }
+
+ * OCP\\Files\\Events\\Node\\BeforeNodeRenamedEvent
+
+  .. code-block:: text
+
+    array{
+      "user": array {"uid": string, "displayName": string},
+      "time": int,
+      "event": array{
+        "class": string,
+        "source": array{"id": string, "path": string}
+        "target": array{"id": string, "path": string}
+      }
+    }

admin_manual/windmill_workflows/index.rst

@@ -0,0 +1,34 @@
+==================
+Windmill Workflows
+==================
+
+Nextcloud integrates the Windmill workflow engine (https://www.windmill.dev/) to allow advanced custom workflows interacting with your Nextcloud instance.
+
+Installation
+------------
+
+ * Install Windmill
+
+   * Either as a standalone install or via the Windmill External App in Nextcloud (see :ref:`External Apps<ai-app_api>`)
+
+ * Enable the ``webhook_listeners`` app that comes with Nextcloud
+
+.. code-block:: bash
+
+   occ app:enable webhook_listeners
+
+Building a workflow
+-------------------
+
+Each workflow in windmill is a listener to a Nextcloud Webhook Event. If you are using the ExApp-packaged windmill, it will automatically register webhooks for the workflows you build using the following mechanism. If you are not using the ExApp-packaged windmill install then you will have to register webhooks for your workflows manually via the webhook_listeners API: see https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html#/operations/webhook_listeners-webhooks-index
+
+The magic listener script
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first script in any workflow you build that should listen to a nextcloud webhook must be ``CORE:LISTEN_TO_EVENT``. It must be an empty script with two parameters that you should fill statically: ``events``, which is a list of event IDs to listen to and ``filters`` a filter condition that allows more fine grained filtering for which events should be used. The filter condition as well as the available events with their payloads is documented in :ref:`the webhook_listeners documentation<webhook_listeners>`.
+
+Nextcloud Scripts
+-----------------
+
+Nextcloud makes available a variety of scripts to be used in Windmill for interfacing with Nextcloud apps. You can find them
+at https://hub.windmill.dev/ or in your windmill instance when selecting existing scripts for creating a new workflow.