feat: add information about orchestration gateway and Budibase

Signed-off-by: Jana Peper <jana.peper@nextcloud.com>

Author: janepie

admin_manual/webhook_listeners/budibase_workflows.rst

@@ -0,0 +1,39 @@
+==================
+Budibase workflows
+==================
+
+
+Budibase can easily be connected to Nextcloud and start automations reacting to Nextcloud events.
+
+
+Using a Nextcloud webhook as automation trigger
+-----------------------------------------------
+
+When creating a new automation in Budibase, you can choose "Webhook" as trigger.
+
+.. image:: images/new_automation.png
+   :alt: Budibase for creating a new automation, with highlighted "Webhook" button
+
+Budibase shows a schema request URL you can use to send the expected payload schema in advance.
+
+The easiest way to to this is to go to the Orchestration Gateway admin settings and click "Register new Budibase webhook":
+
+.. image:: images/new_budibase.png
+   :alt: Orchestration Gateway dialog for registering a Budibase webhook
+
+Here you can fill in the event you want your automation to be started by and the schema URL, and then send the schema. Budibase will show 4 detected bindings upon successful sending. You can then fill in the trigger URL provided by Budibase, all needed filters and the authentication tokens that should be included in the callback, and save.
+As soon as you have your automation deployed, it will now be triggered every time your chosen event happens in Nextcloud.
+
+
+
+Use payload information in bindings
+-----------------------------------
+
+For every event, there are 4 bindings registered in Budibase:
+
+* ``user``: the user that triggered the Nextcloud event
+* ``time``: a timestamp for the triggering
+* ``event``: an array containing additional information about the event (see the :ref:`list of webhook events<webhook_events>` for details)
+* ``authentication``: the requested authentication tokens
+
+These bindings can be used in any step of your automation to use the information given by the callback.

admin_manual/webhook_listeners/images/list_webhooks.png

@@ -36,17 +36,33 @@ Enable the ``webhook_listeners`` app that comes bundled with Nextcloud - e.g.
 
    occ app:enable webhook_listeners
 
-Listening to events
--------------------
+Managing webhooks
+-----------------
 
-You can use the OCS API to add webhooks for specific events. See:
+You can either use the OCS API to manage your webhooks or install the additional ``orchestration_gateway`` app to have a graphical user interface for adding, changing and deleting webhooks.
+
+the Orchestration Gateway adds an administration settings page listing your registered webhooks and making it easy to configure them.
+
+.. image:: images/list_webhooks.png
+   :alt: Orchestration Gateway settings showing a list of registered webhooks
+
+To add a new one, you can choose between a generic new webhook or a Budibase-specific one.
+
+
+.. image:: images/new_webhook.png
+   :alt: Orchestration Gateway dialog for adding a new webhook
+
+
+If you want to use the OCS API to add webhooks for specific events, see:
 `Register a new webhook <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
-use must have administrator rights or delegated administrator rights.
+.. note::
+
+  When authenticating with the OCS API to register webhooks, the account you use must have administrator rights or delegated administrator rights. To delegate the webhook registration to non-admin users, they have to be in a group that gets administration privileges for "Webhooks" granted. To use the Orchestration Gateway UI, they need *additional* privileges for "Orchestration Gateway".
 
-Listing registered webhooks
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Listing registered webhooks via occ
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 You can list all currently registered webhook listeners from the command line:
 
@@ -203,6 +219,8 @@ The complete logs of the workers can be checked with (replace 1 with the worker
 
 It is recommended to restart this worker at least once a day to make sure code changes are effective and avoid memory leaks, in this example the service restarts every 60 seconds.
 
+.. _webhook_events:
+
 Nextcloud Webhook Events
 ------------------------
 
@@ -672,3 +690,9 @@ When the optional ``mail`` app is installed:
 
    For filtering or automation, always check the actual payload you receive, as it matches
    the JSON examples above, not PHPDoc or internal PHP array type style.
+
+
+.. toctree::
+    :maxdepth: 2
+
+    budibase_workflows