Add admin docs for the windmill integration

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

admin_manual/contents.rst

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

admin_manual/windmill_workflows/index.rst

@@ -0,0 +1,9 @@
+==================
+Windmill Workflows
+==================
+
+.. toctree::
+    :maxdepth: 2
+
+    overview
+

admin_manual/windmill_workflows/overview.rst

@@ -0,0 +1,54 @@
+========
+Overview
+========
+
+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 (see below for a list). 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 CORE:LISTEN_TO_EVENT script
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The first script in any workflow you build that should listen to a nextcloud webhook must be `CORE:LISTEN_TO_EVENT`. It has two parameters that you should fill statically: a list of event IDs to listen to and a filter condition that allows more fine grained filtering for which events should be used.
+
+The filter condition is a JSON object whose properties are 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 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.
+
+Nextcloud Webhook Events
+------------------------
+The below list features the event ID and the available variables for filtering.
+
+ * OCA\\Tables\\Event\\RowAddedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, event": array{"tableId": int, "rowId": int, "previousValues": null|array<int, mixed>, "values": null|array<int, mixed>}}``
+ * OCA\\Tables\\Event\\RowDeletedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"tableId": int, "rowId": int, "previousValues": null|array<int, mixed>, "values": null|array<int, mixed>}}``
+ * OCA\\Tables\\Event\\RowUpdatedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"tableId": int, "rowId": int, "previousValues": null|array<int, mixed>, "values": null|array<int, mixed>}}``
+ * OCP\\Files\\Events\\Node\\BeforeNodeCreatedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"node": array{"id": string, "path": string}}}``
+ * OCP\\Files\\Events\\Node\\BeforeNodeWrittenEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"node": array{"id": string, "path": string}}}``
+ * OCP\\Files\\Events\\Node\\BeforeNodeDeletedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"node": array{"id": string, "path": string}}}``
+ * OCP\\Files\\Events\\Node\\BeforeNodeRenamedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"source": array{"id": string, "path": string}, "target": array{"id": string, "path": string}}}``