Merge pull request #14062 from nextcloud/backport/14061/stable33

[stable33] Docs: adapt windmill docs to new integration

Author: janepie

admin_manual/windmill_workflows/images/windmill_add_trigger.png

@@ -2,56 +2,37 @@
 Windmill Workflows
 ==================
 
-Nextcloud integrates the Windmill workflow engine (https://www.windmill.dev/) to allow advanced custom workflows interacting with your Nextcloud instance.
+Nextcloud integrates the `Windmill workflow engine <https://www.windmill.dev/>` to allow advanced custom workflows interacting with your Nextcloud instance.
 
 Installation
 ------------
 
- * Install Windmill
+* Set up a Windmill instance
+   * This should be a stand-alone instance. The External App "Flow" (see :ref:`External Apps<ai-app_api>`) made it possible to have a packaged instance installed in Nextcloud, but this is deprecated since Nextcloud 33. For more information, please check out the admin manual for Nextcloud 32.
 
-   * Either as a standalone install or via the External App "Flow" in Nextcloud (see :ref:`External Apps<ai-app_api>`)
-
- * Enable the ``webhook_listeners`` app that comes with Nextcloud
+* Enable the ``webhook_listeners`` app that comes with Nextcloud
 
 .. code-block:: bash
 
    occ app:enable webhook_listeners
 
-Selecting the right Workspace
------------------------------
-
-With Windmill installed as an ExApp, the first time one visits Windmill's web interface,
-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.
-If the wrong workspace is selected on the first run, it is always possible to switch workspace later in the left sidebar.
-
-.. image:: images/windmill_initial_workspace_selection.png
-   :alt: Screenshot of the workspace selector screen when opening Windmill for the first time
-
-If you wish to change to a different workspace at a later time, you can do so via the workspace selector in the left sidebar of Windmill.
-
-.. image:: images/windmill_later_workspace_selection.png
-   :alt: Screenshot of the workspace selector when a workspace is already opened
-
-Setting up the Correct Nextcloud URL
-------------------------------------
-
-During the initial installation, the ExApp Flow will create a **Nextcloud Authentication Resource** for AppAPI.
-
-This resource includes a **baseUrl** field, which specifies the URL that Windmill scripts/apps use to reach the Nextcloud instance. In most cases, this URL will be configured correctly. However, certain configurations and network topologies may result in an incorrect URL, which you will need to adjust manually.
+* Install the `Windmill integration <https://apps.nextcloud.com/apps/integration_windmill>`_
 
-To set the correct URL, navigate to the Windmill interface, go to the **Resources** tab, locate the resource labeled ``u/admin/exapp_resource``, click the three dots on the right, and select the "Edit" button.
+* Enable :ref:`pretty_urls_label` in your Nextcloud instance
 
-Next, navigate to **Settings->Instance->Core** in Windmill and check if the **Base url** for the Windmill instance is correct.
+Setting up the workspace connection
+-----------------------------------
 
-If you are using DockerSocketProxy, the Base URL should be:
+In Windmill, you have separate workspaces available. To enable Windmill to react to events happening on your Nextcloud instance, you need to connect a workspace to your Nextcloud connection. This is only possible for workspace admins. 
 
-    `https://<your-nextcloud-base-url>/index.php/apps/app_api/proxy/flow`
+* In Windmill, open the workspace settings of the workspace you want to connect to Nextcloud via Settings -> Workspace
+* Go to the Native Triggers tab and choose Nextcloud -> Configure OAuth 
+* Follow the instructions to set up the OAuth connection
+* Click on "Connect" and accept the OAuth connection **with a Nextcloud admin account** or an account that has webhook admin privileges
+* If it shows "Connected", the workspace connection is successfully set up.
 
-If you are using HaRP (as introduced in Nextcloud 32), the Base URL should be:
+Every Flow configured in this workspace can now add Nextcloud triggers and scripts based on the credentials of the account you accepted the OAuth connection with.
 
-    `https://<your-nextcloud-base-url>/exapps/flow`
 
 Building a workflow
 -------------------
@@ -62,20 +43,17 @@ If you are not using the ExApp-packaged windmill install then you will have to r
 webhooks for your workflows manually via the webhook_listeners API:
 see https://docs.nextcloud.com/server/33/developer_manual/_static/openapi.html#/operations/webhook_listeners-webhooks-index
 
-.. TODO ON RELEASE: Update version number above on release
-
-The magic listener script
-~~~~~~~~~~~~~~~~~~~~~~~~~
+.. image:: images/windmill_add_trigger.png
+   :alt: Screenshot of adding a Nextcloud trigger in a workflow
 
-The first script (after the "Input" block) in any workflow you build that should listen to a Nextcloud webhook must have "Summary" set to the exact, literal string ``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>`.
+Now you can choose an event out of a drop-down list  of events that your flow should react to. You can additionally fill in some parameters: 
 
-You can copy the following Deno script for this:
+* *Event filters* 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 the :ref:`webhook_listeners documentation<webhook_listeners>`.
+* The *User ID filter* allows to define the user that can trigger a flow with their actions in Nextcloud. The webhook will only be called by requests from this user. Empty or null means no filtering.
+* The *Headers* field allows to define an array of headers to be sent in a webhook call, which will mostly not be needed. 
 
-.. code-block:: typescript
 
-   export async function main(events: string[], filters: object) { }
-
-The webhook data will be made available on the flow "Input" block, **not** the ``CORE:LISTEN_TO_EVENT`` block. Updates to the webhook configuration take effect only when the flow is deployed. Consider disabling any schedule for the flow, since it will be started when a webhook is received.
+You can add more than one trigger to a flow. 
 
 Nextcloud Scripts
 -----------------
@@ -84,8 +62,7 @@ Nextcloud makes available a variety of scripts to be used in Windmill for interf
 at https://hub.windmill.dev/integrations/nextcloud and https://hub.windmill.dev/integrations/nextcloud/approvals
 or in your windmill instance when selecting existing scripts for creating a new workflow.
 
-To synchronize the scripts with the ones provided by the Windmill hub,
-you can run a flow named "Synchronize Hub Resource types with instance" in the Windmill admin workspace.
+If you want to use a function that is not already represented there, you can easily write your own scripts using a skeleton script and our OCS API that provides lots of endpoints. You can check out the available endpoints in the `Nextcloud OCS API documentation <https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html>`_ or you can install our `OCS API Viewer app <https://apps.nextcloud.com/apps/ocs_api_viewer>`_ and check it out directly in your Nextcloud.
 
 You can create your own Nextcloud-related scripts by taking one of the existing ones as example.
 In a script, when sending a request to Nextcloud, make sure that the ``EX-APP-ID`` header is set to ``flow``.
@@ -94,32 +71,102 @@ Your custom scripts can make requests to any endpoint of the
 
 .. TODO ON RELEASE: Update version number above on release
 
-All the scripts we provide have a set of common input parameters:
+.. code-block:: javascript
+
+   import * as wmill from "windmill-client";
+   import createClient, { type Middleware } from "openapi-fetch";
+
+   type Nextcloud = {
+      baseUrl: string,
+      password: string,
+      username: string
+   };
+
+   export async function main(
+      nextcloud: Nextcloud,
+      $PARAMETER: $TYPE,
+      // add any input parameters you need here
+   ) {
+
+      // this part is the same for any script and should  not be changed
 
-* nextcloudResource: This should be set to the path of the Windmill resource that was automatically created and contains what is necessary to authenticate against Nextcloud with the AppAPI authentication method. For example "u/wapp_user/appapi_nextcloud". You can find this path by looking at the resource list in Windmill.
-* userId: This is the ID of the user you want the request to be authenticated as.
-* useAppApiAuth: This is a boolean to choose between using the AppAPI authentication or basic auth. More details in the next section.
+      const client = createClient<paths>({ baseUrl: nextcloud.baseUrl });
+      const authMiddleware: Middleware = {
+         async onRequest({ request, options }) {
+            // fetch token, if it doesn’t exist
+            // add Authorization header to every request
+            request.headers.set("Authorization", `Basic ${btoa(nextcloud.username + ':' + nextcloud.password)}`);
+            return request;
+         },
+      };
+      client.use(authMiddleware);
+
+      //starting here you can adapt the script
+
+      data = await client.GET("/ocs/v2.php/apps/$APP/$PATH/{$PATHPARAMETER}", {
+         params: {
+            header: {
+               "OCS-APIRequest": true,
+            },
+            query: {
+               format: "json",
+            },
+            path: {
+               $PATHPARAMETER: "$VALUE",
+            },
+
+         },
+         body: {
+            $BODYPARAMETER: $VALUE,
+         },
+      });
+
+   return data;
+   }
+
+The endpoint path you have to fill in is provided in the API documentation.
+
+OCS uses two kinds of parameters: Path parameters that are part of the endpoint URL, and body parameters that are transmitted in the request body. In the example script, you can provide both kinds in the function parameters.
+
+Remember to also adapt the HTTP method (GET, POST, PUT etc.) if needed.
+
+The :code:`data` variable receives the response of the HTTP request, so any data or error messages coming from the Nextcloud instance is available in there.
 
 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.
+All the scripts we provide one input parameter in common: *nextcloud* needs to be an object of the type "Nextcloud" and contain what is necessary to authenticate against Nextcloud:
+
+* baseUrl: the URL your instance is reachable at, e.g. :code:`https://example.cloud`
+* userId: the user id of the user the script should authenticate with
+* token: a password or token for that user
+
+We advise to either add these credentials as a resource of the Nextcloud type to your workspace and refer to the resource in your script, or use the authentication credentials that are provided in the webhook callback. 
+For every flow that is triggered by a Nextcloud event, there are 2 sets of temporary credentials included:
+
+* the credentials for the user account that is saved in the initial OAuth connection, available as :code:`flow_input.authentication.owner`
+* the credentials for the user account that triggered the event with their action, available as :code:`flow_input.authentication.trigger`
+
+These temporary authentication credentials are valid for one hour after triggering the event.
+
 
 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 the workflow input (details about the event that triggered the webhook), use the ``flow_input`` variable.
+For example, ``flow_input.event.form.hash`` will reference the hash of a form from a nextcloud Forms event. As it is a JavaScript expression and not a static value, you have to switch the parameter input with the button next to it.
+
+.. image:: images/windmill_js_expression.png
+   :alt: Screenshot of adding a Nextcloud trigger in a workflow
+
+The fields available for each event are listed in the :ref:`webhook_listeners documentation<webhook_listeners>`.
 
 Each step in a workflow is automatically assigned a letter identifier.
 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, use ``results.e.submission.answers`` to use the answers of of a form submission
-retrieved via the "Get form submission from Nextcloud Forms" script identified with the letter "e".
+retrieved via the "Get form submission from Nextcloud Forms" script identified with the letter "e". You can identify the letters in the flow overview diagram.
 
 Approval/Suspend steps
 ~~~~~~~~~~~~~~~~~~~~~~