docs: signals and actions documentation (#6641)
## About the changes This is the initial documentation for actions and signals. Preview the changes: https://unleash-docs-git-signals-docs-unleash-team.vercel.app/ - Actions: https://unleash-docs-git-signals-docs-unleash-team.vercel.app/reference/actions - Signals: https://unleash-docs-git-signals-docs-unleash-team.vercel.app/reference/signals --------- Co-authored-by: Alvin Bryan <107407814+alvinometric@users.noreply.github.com> Co-authored-by: Nuno Góis <github@nunogois.com>
81
website/docs/reference/actions.md
Normal file
@ -0,0 +1,81 @@
|
||||
---
|
||||
title: Actions
|
||||
---
|
||||
|
||||
:::info Availability
|
||||
|
||||
Actions were introduced as a beta feature in **Unleash 5.11** and are only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in **Unleash 5.12**.
|
||||
|
||||
:::
|
||||
## Overview
|
||||
|
||||
Actions allow you to configure automated actions to be executed based on signals received from an external system.
|
||||
|
||||

|
||||
|
||||
## Creating actions
|
||||
|
||||
:::info Permissions
|
||||
|
||||
Creating actions requires the `ADMIN` permission.
|
||||
|
||||
:::
|
||||
|
||||
Actions are scoped to a project. To be able to create actions, you need to navigate to the project settings and find the **Actions** tab.
|
||||
|
||||

|
||||
|
||||
### Name and description
|
||||
When creating a new action you first need to specify a name and a description. This will help you identify your action and give it a meaningful description.
|
||||
|
||||

|
||||
|
||||
### Source and filters
|
||||
|
||||
Then you need to select a source. If you haven't created a signal endpoint yet, you can do so by using the **Create new signal endpoint** link (more information on this in the [Signals](./signals.md) section).
|
||||
|
||||
If the source you selected already received at least one signal, you'll be able to see a preview of the latest signal received. This can help you define the different filters that need to match for the action to be executed.
|
||||
|
||||
Filters work similarly to [feature flag strategy constraints](./strategy-constraints.md), where the signal payload acts as the context for the constraint evaluation.
|
||||
|
||||
Filters are completely optional, so if you don't configure any filter your action will always be executed whenever you receive a new signal on the selected source.
|
||||
|
||||

|
||||
|
||||
### Actions
|
||||
|
||||
When these actions are triggered, they will execute under the identity of a [service account](./service-accounts.md). This means that when you later check the [event log](./event-log) you will see this service account as the actor for those events. In order to execute the configured actions successfully, this service account needs to have the necessary permissions. This service account doesn't need an API token, so when creating it you can skip the token generation step and simply make sure it has the necessary permissions.
|
||||
|
||||
The actions are executed in the same order that they are defined. If a previous action fails, the following actions will not be started. You can add multiple actions to an action set and you can add multiple action sets to a project. Depending on the action you want to execute you will have to provide different parameters.
|
||||
|
||||

|
||||
|
||||
## Viewing action executions
|
||||
|
||||
Once the action is configured and you start receiving signals that match the filters you configured, you can see the action executions in the **Actions** tab.
|
||||
|
||||

|
||||
|
||||
Using the **View events** option will show you the details of the action executions (what was the payload, did they execute successfully or not, what was the error in case of an error, etc).
|
||||
|
||||
To view the action events as they are executed, select the **View events** option in the respective action row. This will show you more information about each action execution: The signal payload, whether the actions executed successfully, the error details in case of an error, and other details.
|
||||
|
||||

|
||||
|
||||
## Limits that apply
|
||||
There are some constraints on the actions feature as a measure to protect the stability of Unleash. These values can be overridden for self-hosted installations.
|
||||
|
||||
Unprocessed signals are processed in a "first in, first out" fashion, once every minute. If the number of pending signals to process exceeds the limit, it may take longer for the latest signals to be processed.
|
||||
|
||||
The limits are as follows:
|
||||
|
||||
- **Max action sets per project**: 5.
|
||||
- **Max filters per action set**: 5.
|
||||
- **Max distinct values in a filter**: 25.
|
||||
- **Max actions per action set**: 10.
|
||||
- **Max signals to process per cycle**: 10.
|
||||
|
||||
Ref: [Unleash Config](https://github.com/Unleash/unleash/blob/859fe098fedc261d646833012d9d408039491075/src/lib/create-config.ts#L577-L604)
|
||||
|
||||
## Sending signals to Unleash
|
||||
See [Signals](./signals.md)
|
79
website/docs/reference/signals.md
Normal file
@ -0,0 +1,79 @@
|
||||
---
|
||||
title: Signals
|
||||
---
|
||||
|
||||
:::info Availability
|
||||
|
||||
Signals were introduced as a beta feature in **Unleash 5.11** and are only available in Unleash Enterprise. We plan to make this feature generally available to all Enterprise users in **Unleash 5.12**.
|
||||
|
||||
:::
|
||||
|
||||
## Overview
|
||||
|
||||
Signals represent that something happened somewhere. Signal endpoints allow external systems to let Unleash know about these signals via a simple HTTP API.
|
||||
|
||||
You can then configure [actions](./actions) to automatically react to the received signals.
|
||||
|
||||

|
||||
|
||||
Depending on your use case, you can create multiple signal endpoints, one per each external source, or re-use the same endpoint across different sources, using different API tokens for each, so the source can be identified.
|
||||
|
||||
## Creating signal endpoints
|
||||
|
||||
:::info Permissions
|
||||
|
||||
Creating signal endpoints requires the `ADMIN` permission.
|
||||
|
||||
:::
|
||||
|
||||
To create a new signal endpoint, navigate to the **Admin UI** and select **Integrations** from the configure menu.
|
||||
|
||||

|
||||
|
||||
In the integrations page, select the Signals integration:
|
||||
|
||||

|
||||
|
||||
After accessing the Signals integration configuration, you can use the "New signal endpoint" button. This will open a form where you can configure your new signal endpoint.
|
||||
|
||||

|
||||
|
||||
## Using a signal endpoint
|
||||
|
||||
Using a signal endpoint is as easy as sending a POST request to the signal endpoint URL with the correct API token. The body payload is optional, but if present should be formatted as JSON.
|
||||
|
||||
```shell
|
||||
curl -X POST https://unleash.example.com/api/signal-endpoint/my-signal-endpoint \
|
||||
-H "Authorization: Bearer your_token_secret" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "my-signal",
|
||||
"data": {
|
||||
"key": "value"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Configuring an external system to use your new signal endpoint should be straightforward as there's no requirement on the payload structure. The key aspects to take into consideration is making sure the URL is correct and that the token is sent in the `Authorization` header.
|
||||
|
||||
## View signals as they arrive
|
||||
|
||||
To view the signals as they arrive, navigate to the **Signals** page in the **Admin UI** and select the **View signals** option in the respective signal endpoint row.
|
||||
|
||||

|
||||
|
||||
This can help you test that the integration is working before you send in the real signals, or diagnose any unexpected behavior.
|
||||
|
||||
|
||||
## Limits that apply
|
||||
There are some constraints on the signal endpoints API as a measure to protect the stability of Unleash. These values can be overridden for self-hosted installations.
|
||||
|
||||
- **Rate limit**: 1 request per second.
|
||||
- **Max endpoints**: 5.
|
||||
- **Max tokens per endpoint**: 5.
|
||||
- **Payload size**: 100kb (Express default).
|
||||
|
||||
Ref: [Unleash Config](https://github.com/Unleash/unleash/blob/859fe098fedc261d646833012d9d408039491075/src/lib/create-config.ts#L577-L604)
|
||||
|
||||
## Reacting to signals
|
||||
See [Actions](./actions.md)
|
@ -196,9 +196,10 @@ module.exports = {
|
||||
},
|
||||
label: 'Unleash Concepts',
|
||||
items: [
|
||||
'reference/applications',
|
||||
'reference/actions',
|
||||
'reference/activation-strategies',
|
||||
'reference/api-tokens-and-client-keys',
|
||||
'reference/applications',
|
||||
'reference/archived-toggles',
|
||||
'reference/banners',
|
||||
'reference/change-requests',
|
||||
@ -225,6 +226,7 @@ module.exports = {
|
||||
'reference/search-operators',
|
||||
'reference/segments',
|
||||
'reference/service-accounts',
|
||||
'reference/signals',
|
||||
'reference/sso',
|
||||
'reference/stickiness',
|
||||
'reference/strategy-constraints',
|
||||
|
BIN
website/static/img/actions/action-execution-log.png
Normal file
After Width: | Height: | Size: 93 KiB |
BIN
website/static/img/actions/action-execution.png
Normal file
After Width: | Height: | Size: 78 KiB |
BIN
website/static/img/actions/actions-tab.png
Normal file
After Width: | Height: | Size: 72 KiB |
BIN
website/static/img/actions/create-actions-actions.png
Normal file
After Width: | Height: | Size: 129 KiB |
After Width: | Height: | Size: 65 KiB |
BIN
website/static/img/actions/create-actions-source-and-filters.png
Normal file
After Width: | Height: | Size: 135 KiB |
BIN
website/static/img/actions/view-events.png
Normal file
After Width: | Height: | Size: 79 KiB |
BIN
website/static/img/signals/integrations.png
Normal file
After Width: | Height: | Size: 24 KiB |
BIN
website/static/img/signals/new-signal-form.png
Normal file
After Width: | Height: | Size: 75 KiB |
BIN
website/static/img/signals/signals-input.png
Normal file
After Width: | Height: | Size: 40 KiB |
BIN
website/static/img/signals/signals-option.png
Normal file
After Width: | Height: | Size: 11 KiB |
BIN
website/static/img/signals/view-signals-option.png
Normal file
After Width: | Height: | Size: 14 KiB |