mirror of
https://github.com/nextcloud/documentation.git
synced 2026-01-02 17:59:36 +07:00
Add admin docs for the windmill integration
Signed-off-by: Marcel Klehr <mklehr@gmx.net>
This commit is contained in:
Marcel Klehr
@@ -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
|
||||
|
||||
137
admin_manual/webhook_listeners/index.rst
Normal file
137
admin_manual/webhook_listeners/index.rst
Normal file
@@ -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}
|
||||
}
|
||||
}
|
||||
34
admin_manual/windmill_workflows/index.rst
Normal file
34
admin_manual/windmill_workflows/index.rst
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user