Merge pull request #2497 from port-labs/PORTN-2975-edit-automations-docs-to-fit-new-ui

Add the UI explanations for the automations docs

Author: sivanel97

docs/actions-and-automations/create-self-service-experiences/create-self-service-experiences.md

@@ -26,8 +26,8 @@ Port's action model is designed to be flexible and can be used to cover a wide r
 
 ## 💡 Common self-service actions
 
-- **Scaffold** a new service.
-- **Create** a cloud resource.
+- [**Scaffold** a new service](https://docs.port.io/guides/all/scaffold-a-new-service/).
+- [**Create** a cloud resource](https://docs.port.io/guides/all/create-cloud-resource-using-iac).
 - **Provision** a temporary developer environment.
 - **Redeploy** an image tag.
 - **Rollback** a running service.
@@ -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.
 
 <center>
 

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
 }

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
 }

docs/actions-and-automations/create-self-service-experiences/setup-the-backend/setup-the-backend.md

@@ -1,15 +1,15 @@
 ---
-title: Setup backend
+title: Set up backend
 ---
 
 import DocCardList from '@theme/DocCardList';
 import Tabs from "@theme/Tabs"
 import TabItem from "@theme/TabItem"
-import PayloadAdvancedFunctions from '/docs/actions-and-automations/templates/_payload_advanced_functions.mdx'
 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'
+import PayloadAdvancedFunctions from '/docs/actions-and-automations/templates/_payload_advanced_functions.mdx'
 
-# Setup backend
+# Set up backend
 
 <center>
 
@@ -36,16 +36,11 @@ In this section we provide information about the backend logic and its location,
 Port uses the same backend types for both self-service actions and [automations](/actions-and-automations/define-automations/).  
 For more information and examples for the available backend types, check out the [Backend types](/actions-and-automations/setup-backend/) page.
 
-Here is an example of a Github workflow backend configuration:
-
-<img src='/img/self-service-actions/setup-backend/action-form-setup-backend.png' width='55%' border='1px' />
-<br/><br/>
-
 Depending on the backend type you choose, you will need to provide different configuration parameters.  
 
-### Define the action's payload
+### Define the payload
 
-When creating a self-service action or automation, you can construct a JSON payload that will be sent to your backend upon every execution. You can use this to send data about the action that you want your backend to have. 
+When creating an automation, you can construct a JSON payload that will be sent to your backend upon every execution. You can use this to send data about the action that you want your backend to have. 
 
 Still in the `Backend` tab, scroll down to the `Configure the invocation payload` section. This is where we define the action's payload.
 
@@ -129,7 +124,7 @@ You can access any value in this structure and add it to the payload. For exampl
 
 Use the `Test JQ` button in the bottom-left corner to test your expressions against your action and ensure you are sending the correct data.
 
-:::tip Pro tip
+:::tip Inspect the Full Object in `jq`
 You can use the `jq` expression `{{ . }}` when testing to see the entire available object, and then drill down to the specific data you need.
 :::
 

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
 }

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,31 @@ Automations are comprised of two parts:
 <img src="/img/automations/architecture.jpg" width="80%" border='1px' />
 </center><br/>
 
-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. In the first tab (`Basic Details`) of the automation creation form in Port's UI:  
+      Specify your automation’s basic details: 
+
+      - `title` - The automation's title.
+      - `identifier` - The automation's unique identifier.
+      - `description`- A description that can be used to explain the automation.
+      - `icon` - The automation's icon.
+      - `active` - A toggle button indicating whether the automation is enabled or disabled. (`true` by default).
+
+  2. In the second tab (`Trigger`), set up the [trigger](/actions-and-automations/define-automations/setup-trigger). 
+
+  3. In the third tab (`Backend`), 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:
+The basic structure of an automation looks like this:
 
 ```json showLineNumbers
 {
@@ -58,10 +76,12 @@ Automations are defined in JSON format. The JSON structure looks like this:
     "type": "WEBHOOK",
     "url": "https://example.com"
   },
-  "publish": false
+  "publish": true
 }
 ```
 <br/>
+Make sure the `publish` field is set 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 |
 | --- | --- |
@@ -71,19 +91,7 @@ The table below describes the fields in the JSON structure (fields in **bold** a
 | `description` | A description that can be used to explain the automation. |
 | **`trigger`** | An object containing data about the automation's trigger. See [Setup trigger](/actions-and-automations/define-automations/setup-trigger) for more information. |
 | **`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`.
+| `publish` | A boolean value indicating whether the automation is enabled or disabled (`true` by default). |
 
 ## Examples
 

docs/actions-and-automations/define-automations/setup-action.md

@@ -1,85 +1,55 @@
 ---
 sidebar_position: 2
-title: Setup backend
+title: Set up backend
 ---
 
 import BackendTypesJson from '/docs/actions-and-automations/templates/_backend-types-json.md'
 import PayloadAdvancedFunctions from '/docs/actions-and-automations/templates/_payload_advanced_functions.mdx'
 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.
 
 Port uses the same backend types for automations and for [self-service actions](/actions-and-automations/create-self-service-experiences/).
 
-## Backend JSON structure
+## Define the backend
 
-The backend is defined under the `invocationMethod` key in the automation's JSON structure:
+The automation's backend is defined under the `Backend` tab of the automation creation form in Port's UI.  
+Let's break the definition down to two parts:
 
-```json showLineNumbers
-{
-  "identifier": "unique_id",
-  "title": "Title",
-  "icon": "icon_identifier",
-  "description": "automation description",
-  "trigger": {
-    "type": "automation",
-    "event": {
-      "type": "event_type",
-      "blueprintIdentifier": "blueprint_id"
-    },
-    "condition": {
-      "type": "JQ",
-      "expressions": ["expression1", "expression2"],
-      "combinator": "and"
-    }
-  },
-  # highlight-start
-  "invocationMethod": {
-    "type": "WEBHOOK",
-    "url": "https://example.com",
-    "headers": {
-      "RUN_ID": "{{ .run.id }}"
-    },
-    "body": {
-      "payload_key": "{{ some-jq-value }}"
-    }
-  },
-  # highlight-end
-  "publish": false
-}
-```
+### Define your backend's type and metadata
 
-## Supported backends
+In this section we provide information about the backend logic and its location, so that Port can access and run it.  
 
-<BackendTypesJson />
+Port uses the same backend types for both automations and [self-service actions](https://docs.port.io/actions-and-automations/create-self-service-experiences/).  
+For more information and examples for the available backend types, check out the [backend types](/actions-and-automations/setup-backend/) page.
 
-To read more about each backend type, see the [backend types](/actions-and-automations/setup-backend/) page.
+Depending on the backend type you choose, you will need to provide different configuration parameters.  
 
 ### Define the payload
 
-When creating a self-service action or automation, you can construct a JSON payload that will be sent to your backend upon every execution. You can use this to send data about the automation that you want your backend to have. 
+When creating an automation, you can construct a JSON payload that will be sent to your backend upon every execution. You can use this to send data about the automation that you want your backend to have. 
 
-The payload is defined under the `invocationMethod` object in the automation's JSON structure. The key under which the payload is defined depends on the backend you are using (see the table above).
+Still in the `Backend` tab, scroll down to the `Configure the invocation payload` section. This is where we define the automation's payload.
 
 The payload is defined using JSON, and accessing your data is done using `jq`, wrapping each expression with `{{ }}`.  
 
-For example, the following payload definition will send a timestamp of when the execution was triggered:
+Here is an example for an automation payload:
 
 ```json showLineNumbers
 {
-  "execution_time": "{{ .trigger.at }}",
   "port_context": {
-    "run_id": "{{ .run.id }}"
+    "runId": "{{ .run.id }}"
   }
 }
 ```
 
-You may have noticed that the example above also sends `{{ .run.id }}`. This is a unique identifier for each execution of the action, and can be used to [interact with the action run](/actions-and-automations/reflect-action-progress/) in Port from your backend.  
+You may have noticed that the example above also sends `{{ .run.id }}`. This is a unique identifier for each execution of the automation, and can be used to interact with the autmation run in Port from your backend.  
 
-The data that is available to you when constructing the payload is detailed in the `Trigger data` section below.  
+Now you might be thinking - *how do I know what data is available to me when constructing the payload?*  
+Enter `trigger data`.
 
 #### Trigger data
 
@@ -391,4 +361,66 @@ The other trigger events have the same structure, with the following differences
 </TabItem>
 </Tabs>
 
+You can access any value in this structure and add it to the payload. For example, to add the executing user's name to the payload, you can use the following expression:
+
+```json
+{
+  "executing_user_email": "{{.trigger.by.user.email}}"
+}
+```
+
+Use the `Test JQ` button in the bottom-left corner to test your expressions against your automation and ensure you are sending the correct data.
+
+:::tip Inspect the Full Object in `jq`
+You can use the `jq` expression `{{ . }}` when testing to see the entire available object, and then drill down to the specific data you need.
+:::
+
 <PayloadAdvancedFunctions />
+
+## Backend JSON structure
+
+In some cases, you may prefer to define the backend configuration using a JSON object.  
+The backend is defined under the `invocationMethod` object in the automation's JSON structure.
+
+```json showLineNumbers
+{
+  "identifier": "unique_id",
+  "title": "Title",
+  "icon": "icon_identifier",
+  "description": "automation description",
+  "trigger": {
+    "type": "automation",
+    "event": {
+      "type": "event_type",
+      "blueprintIdentifier": "blueprint_id"
+    },
+    "condition": {
+      "type": "JQ",
+      "expressions": ["expression1", "expression2"],
+      "combinator": "and"
+    }
+  },
+  # highlight-start
+  "invocationMethod": {
+    "type": "WEBHOOK",
+    "url": "https://example.com",
+    "headers": {
+      "RUN_ID": "{{ .run.id }}"
+    },
+    "body": {
+      "payload_key": "{{ some-jq-value }}"
+    }
+  },
+  # highlight-end
+  "publish": false
+}
+```
+
+## Supported backends
+
+<BackendTypesJson />
+
+To read more about each backend type, see the [backend types](/actions-and-automations/setup-backend/) page.
+
+
+