diff --git a/docs/docs/concepts/features/actions_v2.md b/docs/docs/concepts/features/actions_v2.md index 161708122..8620ccc56 100644 --- a/docs/docs/concepts/features/actions_v2.md +++ b/docs/docs/concepts/features/actions_v2.md @@ -3,45 +3,43 @@ title: ZITADEL Actions v2 sidebar_label: Actions v2 --- -By using ZITADEL actions V2, you can manipulate ZITADELs behavior on specific API calls, events or functions. -This is useful when you have special business requirements that ZITADEL doesn't support out-of-the-box. +By using ZITADEL Actions v2, you can modify ZITADEL's behavior on specific API calls, events, or functions. This is useful when you have special business requirements that ZITADEL does not support out-of-the-box. :::info -We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you see how we are planning to expand and improve it. Please tell us about your needs and help us prioritize further fixes and features. +We're working on Actions continuously. In the [roadmap](https://zitadel.com/roadmap), you can see how we plan to expand and improve this feature. Please tell us about your needs to help us prioritize further improvements and features. ::: :::warning -To use Actions v2 activate the feature flag "Actions" [feature flag](/docs/apis/resources/feature_service_v2/feature-service-set-instance-features), to be able to manage the related resources. +To use Actions v2, activate the "Actions" [feature flag](/docs/apis/resources/feature_service_v2/feature-service-set-instance-features) in order to manage the related resources. -The Actions v2 will always be executed if available, even if the feature flag is switched off, to remove any Actions v2 the related Execution has to be removed. +Actions v2 will always be executed if available, even if the feature flag is switched off. To remove any Actions v2, the related Execution must be removed. ::: -## Why actions? -ZITADEL can't anticipate and solve every possible business rule and integration requirements from all ZITADEL users. Here are some examples: -- A business requires domain specific data validation before a user can be created or authenticated. -- A business needs to automate tasks. Roles should be assigned to users based on their ADFS 2016+ groups. -- A business needs to store metadata on a user that is used for integrating applications. -- A business needs to restrict the users who are allowed to register to a certain organization by their email domains. +## Why Actions? +ZITADEL can't anticipate or solve every possible business rule and integration requirement for all users. Here are some examples: +- A business requires domain-specific data validation before a user can be created or authenticated. +- A business needs to automate tasks, such as assigning roles to users based on their ADFS 2016+ groups. +- A business needs to store metadata on a user, which is used for integrating applications. +- A business needs to restrict which users are allowed to register to a certain organization by their email domains. -With actions, ZITADEL provides a way to solve such problems. +With Actions, ZITADEL provides a way to address such scenarios. ## How it works -There are 3 components necessary: -- Endpoint, an external endpoint with the desired logic, can be whatever is necessary as long as it can receive an HTTP Post request. -- Target, a resource in ZITADEL with all necessary information how to trigger an endpoint -- Execution, a resource in ZITADEL with the information when to trigger which targets +There are three necessary components: +- **Endpoint:** An external endpoint with the desired logic. It can be anything, as long as it can receive an HTTP POST request. +- **Target:** A resource in ZITADEL containing all the necessary information about how to trigger an endpoint. +- **Execution:** A resource in ZITADEL specifying when to trigger which targets. -The process is that ZITADEL decides at certain points that with a defined Execution a call to the defined Target(s) is triggered, -so that everybody can implement their custom behaviour for as many processes as possible. +The process is that, at certain points, ZITADEL executes a defined Execution, which then calls the defined Target(s). This allows everyone to implement custom behavior for as many processes as needed. Possible conditions for the Execution: -- Request, to react to or manipulate requests to ZITADEL, for example add information to newly created users -- Response, to react to or manipulate responses to ZITADEL, for example to provision newly created users to other systems -- Function, to react to different functionality in ZITADEL, replaces [Actions](/concepts/features/actions). -- Event, to create to different events which get created in ZITADEL, for example to inform somebody if a user gets locked +- **Request:** Reacts to or manipulates requests to ZITADEL, for example, by adding information to newly created users. +- **Response:** Reacts to or manipulates responses from ZITADEL, for example, provisioning newly created users to other systems. +- **Function:** Reacts to various functions in ZITADEL, replacing [Actions](/concepts/features/actions). +- **Event:** Reacts to different events created in ZITADEL, for example, to inform someone if a user gets locked. :::info -Currently, the defined Actions v2 will be executed additionally to the defined [Actions](/concepts/features/actions). +Currently, defined Actions v2 will be executed in addition to [Actions](/concepts/features/actions). ::: ## Migration @@ -58,4 +56,9 @@ Currently, the defined Actions v2 will be executed additionally to the defined [ - [Actions v2 example execution for response manipulation](/guides/integrate/actions/testing-response-manipulation) - [Actions v2 example execution for function](/guides/integrate/actions/testing-function) - [Actions v2 example execution for function manipulation](/guides/integrate/actions/testing-function-manipulation) -- [Actions v2 example execution for event](/guides/integrate/actions/testing-event) \ No newline at end of file +- [Actions v2 example execution for event](/guides/integrate/actions/testing-event) + +## Example use cases: +The following repository contains various examples demonstrating how to use Actions v2 in different scenarios. It also includes a deployment script for testing the examples with Cloudflare Workers: + +- [Actions v2 examples](https://github.com/zitadel/actions/tree/main/actions-v2-cloudflare-workers)