paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

integrations: Move configs in config_options to url_options.

Browse Source 
Currently we have 2 implementations of `config_options`:

- It's used for generating optional webhook URL parameters. These
settings also come with custom UI in the "Generate integration URL"
modal.

- In `/bots` API, it's used as schema for the bots `BotConfigData`. Each
type of bots have different ways of defining their `BotConfigData`
fields. Currently, only embedded bots use `BotConfigData`, and only the
incoming webhooks use `config_options` to configure a bot's
`BotConfigData`; thus, the `config_options` remain unused.

To avoid confusion as to which implementation of `config_options` is
used by an integration, this separates the first use case -- to generate
optional webhook URL -- to a new field called `url_options`. Thus, the
`config_options` field is reserved only for the second use case.
This commit is contained in:
PieterCK
2025-06-04 18:42:43 +07:00
committed by Tim Abbott
parent 74089cf469
commit feb25b0e6b
8 changed files with 151 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

56
api_docs/incoming-webhooks-walkthrough.md
View File

@@ -210,26 +210,54 @@ tools which you can use to test your webhook - 2 command line tools and a GUI.
### Webhooks requiring custom configuration
In rare cases, it's necessary for an incoming webhook to require
additional user configuration beyond what is specified in the post
URL. The typical use case for this is APIs like the Stripe API that
require clients to do a callback to get details beyond an opaque
object ID that one would want to include in a Zulip notification.
In cases where an incoming webhook integration supports optional URL parameters,
one can use the `url_options` feature. It's a field in the `WebhookIntegration`
class that is used when [generating a URL for an integration](/help/generate-integration-url)
in the web app, which encodes the user input for each URL parameter in the
incoming webhook's URL.
These configuration options are declared as follows:
These URL options are declared as follows:
```python
WebhookIntegration('helloworld', ['misc'], display_name='Hello World',
config_options=[('HelloWorld API key', 'hw_api_key', check_string)])
WebhookIntegration(
'helloworld',
...
url_options=[
WebhookUrlOption(
name='ignore_private_repositories',
label='Exclude notifications from private repositories',
validator=check_string
),
],
)
```
`config_options` is a list describing the parameters the user should
configure:
1. A user-facing string describing the field to display to users.
2. The field name you'll use to access this from your `view.py` function.
3. A Validator, used to verify the input is valid.
`url_options` is a list describing the parameters the web app UI should offer when
generating the incoming webhook URL:
Common validators are available in `zerver/lib/validators.py`.
- `name`: The parameter name that is used to encode the user input in the
integration's webhook URL.
- `label`: A short descriptive label for this URL parameter in the web app UI.
- `validator`: A validator function, which is used to determine the input type
for this option in the UI, and to indicate how to validate the input.
Currently, the web app UI only supports these validators:
- `check_bool` for checkbox/select input.
- `check_string` for text input.
!!! warn ""
**Note**: To add support for other validators, you can update
`web/src/integration_url_modal.ts`. Common validators are available in
`zerver/lib/validator.py`.
In rare cases, it may be necessary for an incoming webhook to require
additional user configuration beyond what is specified in the POST
URL. A typical use case for this would be APIs that require clients
to do a callback to get details beyond an opaque object ID that one
would want to include in a Zulip notification message.
The `config_options` field in the `WebhookIntegration` class is reserved
for this use case.
## Step 4: Manually testing the webhook

7
api_docs/unmerged.d/ZF-f9d19d.md Normal file
View File

@@ -0,0 +1,7 @@
* [`POST /register`](/api/register-queue): Added a `url_options` object
to the `realm_incoming_webhook_bots` object for incoming webhook
integration URL parameter options. Previously, these optional URL
parameters were included in the `config_options` field (see feature
level 318 entry). The `config_options` object is now reserved for
configuration data that can be set when creating an bot user for a
specific incoming webhook integration.