Merge branch 'main' into PORTN-3230-aggregation-by-path

Author: sivanel97

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

@@ -165,4 +165,189 @@ The basic structure of a self-service action looks like this (see key descriptio
 
 ## Examples
 
-For complete examples of self-service actions using GitHub as the backend, check out the [guides section](/guides?tags=GitHub&tags=Actions).
+For complete examples of self-service actions using GitHub as the backend, check out the [guides section](/guides?tags=GitHub&tags=Actions).
+
+## Track self-service actions
+
+To gain visibility into how your self-service actions are being used and their performance, you can set up tracking for action runs. This allows you to monitor execution patterns, track success rates, and maintain audit trails to follow what actions were executed and when. 
+
+The following tracking system works by creating a dedicated blueprint for action runs and setting up an automation that captures execution details whenever a specific self-service action is triggered as well as an automation that updates the action run's status.
+
+<h3>Set up data model</h3>
+
+Create a blueprint for `Action run`:
+
+1. Go to the [Data model](https://app.getport.io/settings/data-model) page of your portal.
+
+2. Click on `+ Blueprint`.
+
+3. Click on the `{...} Edit JSON` button in the top right corner.
+
+4. Copy and paste the following JSON schema, then click `Save`.
+
+    <details>
+    <summary><b>Action run blueprint (click to expand)</b></summary>
+
+    ``` json
+    {
+      "identifier": "action_run",
+      "title": "Action run",
+      "icon": "Microservice",
+      "schema": {
+        "properties": {
+          "status": {
+            "icon": "DefaultProperty",
+            "title": "Status",
+            "type": "string",
+            "enum": [
+              "SUCCESS",
+              "FAILURE",
+              "IN_PROGRESS",
+              "WAITING_FOR_APPROVAL",
+              "DECLINED"
+            ],
+            "enumColors": {
+              "SUCCESS": "green",
+              "FAILURE": "red",
+              "IN_PROGRESS": "lightGray",
+              "WAITING_FOR_APPROVAL": "yellow",
+              "DECLINED": "red"
+            }
+          },
+          "created_at": {
+            "type": "string",
+            "title": "Created At",
+            "format": "date-time"
+          },
+          "run_id": {
+            "type": "string",
+            "title": "Run ID"
+          },
+          "run_url": {
+            "type": "string",
+            "title": "Run URL",
+            "format": "url"
+          },
+          "updated_at": {
+            "type": "string",
+            "title": "Updated At",
+            "format": "date-time"
+          },
+          "action": {
+            "type": "string",
+            "title": "Action"
+          }
+        },
+        "required": []
+      },
+      "mirrorProperties": {},
+      "calculationProperties": {},
+      "aggregationProperties": {},
+      "relations": {}
+    }
+    ```
+    </details>
+
+
+<h3>Define the automation</h3>
+
+The following automation updates the `Action run` entity with information regarding this run.  
+To add it, follow these steps:
+
+1. Go to the [Automations](https://app.getport.io/settings/automations) page of your portal.
+
+2. Click on the `+ Automation` button.
+
+3. Click on the `{...} Edit JSON` button in the top right corner.
+
+4. Copy and paste the following JSON configuration into the editor, then click `Save`.
+
+    <details>
+    <summary><b>Update `Action run` automation definition (click to expand)</b></summary>
+
+    ``` json 
+    {
+      "identifier": "update_action_run",
+      "title": "Update Action Run",
+      "description": "",
+      "trigger": {
+        "type": "automation",
+        "event": {
+          "type": "ANY_RUN_CHANGE",
+          "actionIdentifier": "<THE_ACTION_IDENTIFIER>"
+        },
+        "condition": {
+          "type": "JQ",
+          "expressions": [],
+          "combinator": "and"
+        }
+      },
+      "invocationMethod": {
+        "type": "UPSERT_ENTITY",
+        "blueprintIdentifier": "action_run",
+        "mapping": {
+          "identifier": "{{.event.diff.after.id}}",
+          "title": "{{.event.diff.after.id}}",
+          "properties": {
+            "run_id": "{{.event.diff.after.id}}",
+            "run_url": "https://app.port.io/organization/run?runId={{.event.diff.after.id}}",
+            "status": "{{.event.diff.after.status}}",
+            "created_at": "{{.event.diff.after.createdAt}}",
+            "updated_at": "{{.event.diff.after.updatedAt}}",
+            "action": "{{.event.diff.after.action.title}}"
+          },
+          "relations": {}
+        }
+      },
+      "publish": true
+    }
+    ```
+    </details>
+
+Once implemented, you can track your self-service action runs and see how they are progressing.  
+
+For example, you can create the following widget to vizualize how `Action runs` are distributed by status for a specific `Action` over the past month:
+
+1. Click **`+ Widget`** and select **Pie chart**.
+
+2. Give the widget a `title` and a `description`.
+
+3. Choose the `Action run` blueprint.
+
+4. Under `Breakdown by property`, select the **status** property.
+
+5. Under `Additional filters` you can choose to filter by:
+   - `Action runs` that were created in the past month.
+   - `Action runs` of a specific self-service action.  
+
+    Click on `filters`, then on `{...} Edit JSON`, and add the following snippet with your action title and relevant time frame.  
+    Below is a JSON example for `Create s3 bucket` self-service action in the past month:
+
+    <details>
+    <summary><b>filters JSON example (click to expand)</b></summary>
+      ``` json showLineNumbers
+      {
+        "combinator": "and",
+        "rules": [
+          {
+            "property": "created_at",
+            "operator": "between",
+            "value": {
+              "preset": "lastMonth"
+            }
+          },
+          {
+            "property": "action",
+            "operator": "=",
+            "value": "Create s3 bucket" // Change the value to your action name
+          }
+        ]
+      }
+      ```
+    </details>
+
+6. Click `Save`.
+
+This will result in a widget similar to the following:  
+
+<img src='/img/self-service-actions/actionRunsPieChartExample.png' width='70%' border='1px' />

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

@@ -57,6 +57,10 @@ For example, say we have an action with one user input that is the user's name.
 }
 ```
 
+:::info `.run` available values
+When the action is triggered, the `.run` object includes only the 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 in Port from your backend.  
 
 Now you might be thinking - *how do I know what data is available to me when constructing the payload?*  

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

@@ -46,7 +46,11 @@ Here is an example for an automation payload:
 }
 ```
 
-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.  
+:::info `.run` available values
+When the automation is triggered, the `.run` object includes only the run `id`.
+:::
+
+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 automation run in Port from your backend.  
 
 Now you might be thinking - *how do I know what data is available to me when constructing the payload?*  
 Enter `trigger data`.

docs/search-and-query/comparison-operators.md

@@ -249,39 +249,15 @@ The `notBetween` operator checks datetime values and returns entities whose rele
 
 ### contains
 
-The `contains` operator compares string properties based on the target property type:
-
-<Tabs values={[
-{label: "String property", value: "stringProp"},
-{label: "Array property", value: "arrayProp"}
-]}>
-
-<TabItem value="stringProp">
-When used on a string property, the operator will check if the value is contained inside the property:
+The `contains` operator checks if the specified value exists within a string property:
 
 ```json showLineNumbers
 {
   "property": "myStringProperty",
-  "operator": "myStringProperty",
-  "value": "mySubString"
-}
-```
-
-</TabItem>
-
-<TabItem value="arrayProp">
-When used on a string array property, the operator will check if the value is equal to one of the strings in the array:
-
-```json showLineNumbers
-{
-  "property": "myStringArrayProp",
   "operator": "contains",
-  "value": "myString"
+  "value": "mySubString"
 }
 ```
-</TabItem>
-
-</Tabs>
 
 ### doesNotContains
 
@@ -297,7 +273,7 @@ The `contains` operator checks if the specified value **does not** exists in the
 
 ### containsAny
 
-The `containsAny` operator checks if **any** of the specified strings exist in the target array:
+The `containsAny` operator checks if **any** of the specified strings exist in the target **array**:
 
 ```json showLineNumbers
 {
@@ -309,7 +285,7 @@ The `containsAny` operator checks if **any** of the specified strings exist in t
 
 ### beginsWith
 
-The `beginsWith` operator checks if the specified property starts with the specified value**
+The `beginsWith` operator checks if the specified property starts with the specified value:
 
 ```json showLineNumbers
 {
@@ -321,7 +297,7 @@ The `beginsWith` operator checks if the specified property starts with the speci
 
 ### doesNotBeginsWith
 
-The `doesNotBeginsWith` operator checks if the specified property **does not** start with the specified value
+The `doesNotBeginsWith` operator checks if the specified property **does not** start with the specified value:
 
 ```json showLineNumbers
 {
@@ -333,7 +309,7 @@ The `doesNotBeginsWith` operator checks if the specified property **does not** s
 
 ### endsWith
 
-The `endsWith` operator checks if the specified property ends with the specified value
+The `endsWith` operator checks if the specified property ends with the specified value:
 
 ```json showLineNumbers
 {
@@ -345,7 +321,7 @@ The `endsWith` operator checks if the specified property ends with the specified
 
 ### doesNotEndsWith
 
-The `doesNotEndsWith` operator checks if the specified property **does not** end with the specified value
+The `doesNotEndsWith` operator checks if the specified property **does not** end with the specified value:
 
 ```json showLineNumbers
 {
@@ -357,7 +333,7 @@ The `doesNotEndsWith` operator checks if the specified property **does not** end
 
 ### in
 
-The `in` operator checks if a `string` property is equal to one or more specified `string` values
+The `in` operator checks if a `string` property is equal to one or more specified `string` values:
 
 <Tabs values={[
 {label: "Standard", value: "array"},
@@ -378,7 +354,7 @@ The `in` operator checks if a `string` property is equal to one or more specifie
 
 <TabItem value="myTeamsDynamicFilter">
 
-In order to filter entities that **belong to one or more of your teams** you can use the special `My Teams` filter.
+In order to filter entities that **belong to one or more of your teams** you can use the special `My Teams` filter:
 
 ```json showLineNumbers
 {
@@ -398,7 +374,7 @@ You can also use the `My Teams` filter in the UI:
 
 ### notIn
 
-The `notIn` operator checks if a `string` property is **not equal** to all of the specified `string` values
+The `notIn` operator checks if a `string` property is **not equal** to all of the specified `string` values:
 
 ```json showLineNumbers
 {