From 264b6b1f801503bd2c7744cdf987942e07bc9efd Mon Sep 17 00:00:00 2001 From: Marcel Klehr Date: Mon, 2 Sep 2024 13:43:35 +0200 Subject: [PATCH] Add admin docs for the windmill integration Signed-off-by: Marcel Klehr --- admin_manual/contents.rst | 1 + admin_manual/windmill_workflows/index.rst | 9 ++++ admin_manual/windmill_workflows/overview.rst | 54 ++++++++++++++++++++ 3 files changed, 64 insertions(+) create mode 100644 admin_manual/windmill_workflows/index.rst create mode 100644 admin_manual/windmill_workflows/overview.rst diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index 000434abe92..906e29a63e6 100644 --- a/admin_manual/contents.rst +++ b/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 diff --git a/admin_manual/windmill_workflows/index.rst b/admin_manual/windmill_workflows/index.rst new file mode 100644 index 00000000000..97dbeb943f9 --- /dev/null +++ b/admin_manual/windmill_workflows/index.rst @@ -0,0 +1,9 @@ +================== +Windmill Workflows +================== + +.. toctree:: + :maxdepth: 2 + + overview + diff --git a/admin_manual/windmill_workflows/overview.rst b/admin_manual/windmill_workflows/overview.rst new file mode 100644 index 00000000000..73151fa81e6 --- /dev/null +++ b/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`) + + * 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, "values": null|array}}`` + * OCA\\Tables\\Event\\RowDeletedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"tableId": int, "rowId": int, "previousValues": null|array, "values": null|array}}`` + * OCA\\Tables\\Event\\RowUpdatedEvent ``array{ "user": array {"uid": string, "displayName": string}, time: int, "event": array{"tableId": int, "rowId": int, "previousValues": null|array, "values": null|array}}`` + * 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}}}``