From 9113651f18d300301d31ba97b87e39d74d0a950c Mon Sep 17 00:00:00 2001 From: Sivan Elkabes Date: Tue, 1 Jul 2025 16:22:02 +0300 Subject: [PATCH] Add the UI explanations for the automations docs + changed setup to set up where needed --- .../create-self-service-experiences.md | 12 +++---- .../_category_.json | 2 +- .../setup-the-backend/_category_.json | 2 +- .../setup-the-backend/setup-the-backend.md | 4 +-- .../setup-ui-for-action/_category_.json | 2 +- .../define-automations/define-automations.md | 33 ++++++++++--------- .../define-automations/setup-action.md | 7 ++-- .../define-automations/setup-trigger.md | 9 +++-- .../setup-backend/setup-backend.md | 2 +- 9 files changed, 40 insertions(+), 33 deletions(-) diff --git a/docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md b/docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md index 717680a4a3..9769f17c63 100644 --- a/docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md +++ b/docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md @@ -53,29 +53,29 @@ Port gives you no-code components to create the experience you want for your use Self-service actions are created and managed in the [Self-service](https://app.getport.io/self-serve) page of your portal. -To begin, click on the `+ New Action` button in the top right corner, then follow the steps below. +To begin, click on the `+ Action` button in the top right corner, then follow the steps below. :::tip Other supported methods Besides Port's UI, you can also create and manage self-service actions using [Port's API](/api-reference/create-an-action-automation), or [Terraform](https://registry.terraform.io/providers/port-labs/port-labs/latest/docs/resources/port_action). ::: -### Step 1 - setup the action's frontend +### Set up the action's frontend Choose the name of the action, its icon, and the inputs you would like the user to fill out when executing it. Port supports a wide variety of input types, including more advanced conditions to best fit the experience you want for your users. -See [Setup frontend](/actions-and-automations/create-self-service-experiences/setup-ui-for-action/) for instructions and examples. +See [Set up frontend](/actions-and-automations/create-self-service-experiences/setup-ui-for-action/) for instructions and examples. -### Step 2 - setup backend +### Set up backend -Setup the logic responsible to handle the action after it is executed. +Set up the logic responsible to handle the action after it is executed. In this step you can also define the payload that will be sent to your handler upon execution. The backend logic is yours, so it can do whatever you need it to do. Port supports many different backends for actions, offering a secure and compliant architecture. As part of your backend and its logic implementation, you can keep your software catalog up to date by sending API requests or ingesting new data that is tied to the performed action (for example, adding a new service entity in Port once the scaffold process has finished). -See [Setup backend](/actions-and-automations/create-self-service-experiences/setup-the-backend/) for instructions and examples. +See [Set up backend](/actions-and-automations/create-self-service-experiences/setup-the-backend/) for instructions and examples.
diff --git a/docs/actions-and-automations/create-self-service-experiences/set-self-service-actions-rbac/_category_.json b/docs/actions-and-automations/create-self-service-experiences/set-self-service-actions-rbac/_category_.json index 86b3aefa62..10373dcd47 100644 --- a/docs/actions-and-automations/create-self-service-experiences/set-self-service-actions-rbac/_category_.json +++ b/docs/actions-and-automations/create-self-service-experiences/set-self-service-actions-rbac/_category_.json @@ -1,4 +1,4 @@ { - "label": "Setup action RBAC", + "label": "Set up action RBAC", "position": 3 } diff --git a/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/_category_.json b/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/_category_.json index 7b4aced011..edf6bdd0a7 100644 --- a/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/_category_.json +++ b/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/_category_.json @@ -1,4 +1,4 @@ { - "label": "Setup backend", + "label": "Set up backend", "position": 2 } diff --git a/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/setup-the-backend.md b/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/setup-the-backend.md index 37cf11759b..46c6f42635 100644 --- a/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/setup-the-backend.md +++ b/docs/actions-and-automations/create-self-service-experiences/setup-the-backend/setup-the-backend.md @@ -1,5 +1,5 @@ --- -title: Setup backend +title: Set up backend --- import DocCardList from '@theme/DocCardList'; @@ -9,7 +9,7 @@ import PayloadAdvancedFunctions from '/docs/actions-and-automations/templates/_p import BackendTypesJson from '/docs/actions-and-automations/templates/_backend-types-json.md' import ExecuteActionLocations from '/docs/actions-and-automations/create-self-service-experiences/templates/_execute_action_locations.mdx' -# Setup backend +# Set up backend
diff --git a/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/_category_.json b/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/_category_.json index 5f9f3f9592..656dd999f5 100644 --- a/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/_category_.json +++ b/docs/actions-and-automations/create-self-service-experiences/setup-ui-for-action/_category_.json @@ -1,4 +1,4 @@ { - "label": "Setup frontend", + "label": "Set up frontend", "position": 1 } diff --git a/docs/actions-and-automations/define-automations/define-automations.md b/docs/actions-and-automations/define-automations/define-automations.md index 35ff881e55..7c774087aa 100644 --- a/docs/actions-and-automations/define-automations/define-automations.md +++ b/docs/actions-and-automations/define-automations/define-automations.md @@ -11,7 +11,7 @@ Automations in Port are triggered by events in your infrastructure, such as a ne Port uses the same backend types for both automations and [self-service actions](/actions-and-automations/create-self-service-experiences/). -## Common automations +## đź’ˇ Common automations - Create a new incident in PagerDuty when CPU usage is greater than X%. - Destroy an ephemeral environment when its TTL expires. @@ -28,13 +28,24 @@ Automations are comprised of two parts:

-When an event occurs in your software catalog, Port will automatically trigger the associated backend, given that the automation is enabled. +When an event occurs in your software catalog, Port will automatically trigger the associated backend, given that the automation is enabled. -By default, automations are disabled and can be used as drafts until ready to be activated. You can enable them by setting the `publish` field to `true` in their JSON definition. +## Define an automation + +Automations are defined in the [Automations page](https://app.getport.io/settings/automations) of your portal. +Here you can create, edit, and delete automations, as well as enable or disable them. +Click on the `+ Automation` button in the top-right corner, then follow the steps below: + + 1. Define the basic details for the automation: `title`, `identifier`, `description`, `icon`, and `active` status. + + 2. Set up the [trigger](/actions-and-automations/define-automations/setup-trigger). + + 3. Define the [backend](/actions-and-automations/define-automations/setup-action) that will be executed when the trigger event occurs, then click `Save`. ## Automation JSON structure -Automations are defined in JSON format. The JSON structure looks like this: +Automations can also be defined using a JSON format. +The JSON structure looks like this: ```json showLineNumbers { @@ -62,6 +73,8 @@ Automations are defined in JSON format. The JSON structure looks like this: } ```
+Make sure to set the `publish` field to `true` if you want to enable the automation. + The table below describes the fields in the JSON structure (fields in **bold** are required): | Field | Description | | --- | --- | @@ -73,18 +86,6 @@ The table below describes the fields in the JSON structure (fields in **bold** a | **`invocationMethod`** | An object containing data about the automation's invocation method. See [Setup action](/actions-and-automations/define-automations/setup-action) for more information. | | `publish` | A boolean value indicating whether the automation is enabled or disabled (`false` by default). | -## Define an automation - -Automations are defined in the [Automations page](https://app.getport.io/settings/automations) of your portal. Here you can create, edit, and delete automations, as well as enable or disable them. - -1. Click on the `+ New automation` button in the top-right corner. This will open a JSON form where you can define the automation's configuration. - -2. Change the JSON configuration to match your desired automation: - * Setup the [trigger](/actions-and-automations/define-automations/setup-trigger). - * Define the [backend](/actions-and-automations/define-automations/setup-action) that will be executed when the trigger event occurs. - -3. Make sure to set the `publish` field to `true` if you want to enable the automation. When finished, click `Save`. - ## Examples See some examples of automation definitions [here](/actions-and-automations/define-automations/examples). diff --git a/docs/actions-and-automations/define-automations/setup-action.md b/docs/actions-and-automations/define-automations/setup-action.md index f25da431be..04e30764d8 100644 --- a/docs/actions-and-automations/define-automations/setup-action.md +++ b/docs/actions-and-automations/define-automations/setup-action.md @@ -1,6 +1,6 @@ --- sidebar_position: 2 -title: Setup backend +title: Set up backend --- import BackendTypesJson from '/docs/actions-and-automations/templates/_backend-types-json.md' @@ -8,15 +8,16 @@ import PayloadAdvancedFunctions from '/docs/actions-and-automations/templates/_p import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" -# Setup backend +# Set up backend The automation's backend is the logic that you want to execute when a trigger event occurs. It will run on all entities tied to the blueprint specified in the automation's definition, whenever the trigger event occurs. +The automation's backend is defined under the `Backend` tab of the automation creation form in the UI. Port uses the same backend types for automations and for [self-service actions](/actions-and-automations/create-self-service-experiences/). ## Backend JSON structure -The backend is defined under the `invocationMethod` key in the automation's JSON structure: +The backend can also be edited under the `invocationMethod` key in the automation's JSON structure: ```json showLineNumbers { diff --git a/docs/actions-and-automations/define-automations/setup-trigger.md b/docs/actions-and-automations/define-automations/setup-trigger.md index 5cb7c64488..d733b71124 100644 --- a/docs/actions-and-automations/define-automations/setup-trigger.md +++ b/docs/actions-and-automations/define-automations/setup-trigger.md @@ -1,18 +1,23 @@ --- sidebar_position: 1 -title: Setup trigger +title: Set up trigger --- import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" -# Setup trigger +# Set up trigger + +After specifying your automation’s basic details including the `title`, `identifier`, `description`, `icon`, and `active` status, the next step is to choose a **trigger** for the automation. Automation triggers events in your software catalog that you want to act upon. Port supports two types of triggers: - **Entity**: Triggered when an an entity of a specified blueprint is modified. - **Action run**: Triggered when an [action run](/actions-and-automations/reflect-action-progress/) of a specified action is modified. +If you select an entity trigger, you will need to specify the relevant blueprint. +If you select an action run trigger, you will need to specify the corresponding action. + ## Available triggers The following trigger events are available for each type: diff --git a/docs/actions-and-automations/setup-backend/setup-backend.md b/docs/actions-and-automations/setup-backend/setup-backend.md index 552757035e..10425c948f 100644 --- a/docs/actions-and-automations/setup-backend/setup-backend.md +++ b/docs/actions-and-automations/setup-backend/setup-backend.md @@ -1,5 +1,5 @@ --- -title: Setup backend +title: Set up backend --- import DocCardList from '@theme/DocCardList';