diff --git a/admin_manual/contents.rst b/admin_manual/contents.rst index 000434abe92..08a1fb9c56f 100644 --- a/admin_manual/contents.rst +++ b/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 diff --git a/admin_manual/webhook_listeners/index.rst b/admin_manual/webhook_listeners/index.rst new file mode 100644 index 00000000000..cc5ee3c3a83 --- /dev/null +++ b/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, + "values": null|array + } + } + + * 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, + "values": null|array + } + } + + * 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, + "values": null|array + } + } + + * 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} + } + } diff --git a/admin_manual/windmill_workflows/index.rst b/admin_manual/windmill_workflows/index.rst new file mode 100644 index 00000000000..543a2b4b04d --- /dev/null +++ b/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`) + + * 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`. + +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.