-
Notifications
You must be signed in to change notification settings - Fork 1.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add admin docs for the windmill integration #12153
Merged
+427
−0
Merged
Changes from 4 commits
Commits
Show all changes
11 commits
Select commit
Hold shift + click to select a range
b2e8b3b
Add admin docs for the windmill integration
marcelklehr 690ac45
Admin docs for the windmill integration: Add notes about auth
marcelklehr 3246209
Admin docs: More additions to windmill docs
marcelklehr da7a914
Admin docs: More additions to windmill docs
marcelklehr ee4ce53
Apply suggestions from code review
marcelklehr 8091416
Update admin_manual/windmill_workflows/index.rst
marcelklehr d939cb4
Admin docs: More additions to windmill docs
marcelklehr 8364ffa
Admin docs: More additions to windmill docs
marcelklehr 129f81e
Admin docs: Make list of webhook events exhausitve
marcelklehr 3e4ad44
Admin docs: Make list of webhook events exhausitve
marcelklehr f9798b1
Admin docs: More additions for windmill and webhooks
marcelklehr File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,140 @@ | ||
================= | ||
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 | ||
|
||
Note: When authenticating with the OCS API to register webhooks the account you authenticate as must have administrator rights or delegated administrator rights. | ||
|
||
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. | ||
marcelklehr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
* 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} | ||
} | ||
} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,60 @@ | ||
================== | ||
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 | ||
|
||
Selecting the right Workspace | ||
----------------------------- | ||
|
||
When installing Windmill as an ExApp make sure to select the right workspace on the first run: Only the pre-existing "nextcloud" workspace is hooked up to nextcloud's internal event system, all other workspaces will need manual webhook setups for each workflow. | ||
marcelklehr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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 | ||
marcelklehr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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>`. | ||
marcelklehr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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. | ||
marcelklehr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Authentication | ||
~~~~~~~~~~~~~~ | ||
|
||
All bricks have the option to use "AppAPI Authentication" or normal authentication using a Nextcloud resource in Windmill. When using normal authentication you will need to provide the correct password or app password of the user on behalf of whom you want to execute the script. When using "AppAPI Authentication" you can impersonate any Nextcloud user. This will only work when using the ExApp-packaged version of windmill. | ||
|
||
Passing values between blocks | ||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
When specifying script inputs you can either fill the parameters with static values or make references to the workflow input and the previous workflow steps. | ||
|
||
In order to reference the workflow input, use the ``flow_input`` variable. For example, ``flow_input.event.form.hash`` will reference the hash of a form from a nextcloud Forms event. | ||
|
||
In order to reference results from previous steps in your parameters, use the ``results`` variable with the id of the step to reference as a sub property. For example, ``results.e.submission.answers`` to use the answers of of a form submission retrieved via the "Get form submission from Nextcloud Forms" script. | ||
marcelklehr marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Approval/Suspend steps | ||
~~~~~~~~~~~~~~~~~~~~~~ | ||
|
||
Windmill allows using so-called approval steps, which are essentially asynchronous scripts that wait for the call to an additional webhook URL. The most prominent use case for this are approval workflows where you get automated input from somewhere which needs to be approved by a human. Once the human approves or disapproves by triggering the webhook URL the workflow will resume. | ||
|
||
Using the scripts provided for Nextcloud, you can send approval links to the humans in charge of approving via Nextcloud Talk or a simple notification in Nextcloud. Of course, you may also use any of the other scripts for sending messages available in the Windmill hub. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Maybe this needs more details like mentioning the approve_links app, talk about the branching if the approval is rejected (once we have tested it properly). |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@marcelklehr could you please try to find a workaround for the failing spell check? This line causes red CI for all new PRs. Thanks