zitadel/docs/docs/apis/actionsv2/execution-local.md
Stefan Benz 1c5ecba42a
feat: add action v2 execution on requests and responses (#7637)
* feat: add execution of targets to grpc calls

* feat: add execution of targets to grpc calls

* feat: add execution of targets to grpc calls

* feat: add execution of targets to grpc calls

* feat: add execution of targets to grpc calls

* feat: add execution of targets to grpc calls

* feat: add execution of targets to grpc calls

* feat: split request and response logic to handle the different context information

* feat: split request and response logic to handle the different context information

* fix: integration test

* fix: import alias

* fix: refactor execution package

* fix: refactor execution interceptor integration and unit tests

* fix: refactor execution interceptor integration and unit tests

* fix: refactor execution interceptor integration and unit tests

* fix: refactor execution interceptor integration and unit tests

* fix: refactor execution interceptor integration and unit tests

* docs: basic documentation for executions and targets

* fix: change order for interceptors

* fix: merge back origin/main

* fix: change target definition command and query side (#7735)

* fix: change target definition command and query side

* fix: correct refactoring name changes

* fix: correct refactoring name changes

* fix: changing execution defintion with target list and type

* fix: changing execution definition with target list and type

* fix: add back search queries for target and include

* fix: projections change for execution with targets suffix table

* fix: projections change for execution with targets suffix table

* fix: projections change for execution with targets suffix table

* fix: projections change for execution with targets suffix table

* fix: projections change for execution with targets suffix table

* fix: projections change for execution with targets suffix table

* fix: projections change for execution with targets suffix table

* docs: add example to actions v2

* docs: add example to actions v2

* fix: correct integration tests on query for executions

* fix: add separate event for execution v2 as content changed

* fix: add separate event for execution v2 as content changed

* fix: added review comment changes

* fix: added review comment changes

* fix: added review comment changes

---------

Co-authored-by: adlerhurst <silvan.reusser@gmail.com>

* fix: added review comment changes

* fix: added review comment changes

* Update internal/api/grpc/server/middleware/execution_interceptor.go

Co-authored-by: Silvan <silvan.reusser@gmail.com>

* fix: added review comment changes

* fix: added review comment changes

* fix: added review comment changes

* fix: added review comment changes

* fix: added review comment changes

* fix: added review comment changes

---------

Co-authored-by: adlerhurst <silvan.reusser@gmail.com>
Co-authored-by: Elio Bischof <elio@zitadel.com>
2024-05-04 11:55:57 +02:00

3.7 KiB

title
Actions v2 example execution locally

In this guide, you will create a ZITADEL execution and target. After a user is created through the API, the target is called.

Prerequisites

Before you start, make sure you have everything set up correctly.

  • You need to be at least a ZITADEL IAM_OWNER
  • Your ZITADEL instance needs to have the actions feature enabled.

Start example target

To start a simple HTTP server locally, which receives the webhook call, the following code example can be used:

package main

import (
	"fmt"
	"io"
	"net/http"
)

// webhook HandleFunc to read the request body and then print out the contents
func webhook(w http.ResponseWriter, req *http.Request) {
	// read the body content
	sentBody, err := io.ReadAll(req.Body)
	if err != nil {
		// if there was an error while reading the body return an error
		http.Error(w, "error", http.StatusInternalServerError)
		return
	}
	// print out the read content
	fmt.Println(string(sentBody))
}

func main() {
	// handle the HTTP call under "/webhook"
	http.HandleFunc("/webhook", webhook)

	// start an HTTP server with the before defined function to handle the endpoint under "http://localhost:8090"
	http.ListenAndServe(":8090", nil)
}

What happens here is only a target which prints out the received request, which could also be handled with a different logic.

Create target

As you see in the example above the target is created with HTTP and port '8090' and if we want to use it as webhook, the target can be created as follows:

Create a target

curl -L -X POST 'https://$CUSTOM-DOMAIN/v3alpha/targets' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "name": "local webhook",
  "restWebhook": {
    "interruptOnError": true    
  },
  "endpoint": "http://localhost:8090/webhook",
  "timeout": "10s"
}'

Save the returned ID to set in the execution.

Set execution

To call the target just created before, with the intention to print the request used for user creation by the user V2 API, we define an execution with a method condition.

Set an execution

curl -L -X PUT 'https://$CUSTOM-DOMAIN/v3alpha/executions' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "condition": {
        "request": {
            "method": "/zitadel.user.v2beta.UserService/AddHumanUser"
        }
    },
    "targets": [
        {
            "target": "<TargetID returned>"
        }
    ]
}'

Example call

Now on every call on /zitadel.user.v2beta.UserService/AddHumanUser the local server prints out the received body of the request:

curl -L -X PUT 'https://$CUSTOM-DOMAIN/v2beta/users/human' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
    "profile": {
        "givenName": "Example_given",
        "familyName": "Example_family"
    },
    "email": {
        "email": "example@example.com"
    }
}'

Should print out something like, also described under Sent information Request:

{
  "fullMethod": "/zitadel.user.v2beta.UserService/AddHumanUser",
  "instanceID": "262851882718855632",
  "orgID": "262851882718921168",
  "projectID": "262851882719052240",
  "userID": "262851882718986704",
  "request": {
    "profile": {
      "given_name": "Example_given",
      "family_name": "Example_family"
    },
    "email": {
      "email": "example@example.com"
    }
  }
}