Repository: keephq/keep
Pull request: docs: update enrichment.mdx
Close #2995 
added to doc

Problem statement:
[📃 Docs]: disposable and enrich alert in trigger interval or manual (from workflow page) or incident
My question is in the context of enrichment in the resolve_old_alert case
1) what does disposable true do?
2) how does the enrichment rule work if you don't have an alert in the trigger?
3) can I call subprocess in trigger interval or other with sending variables (for queried alerts in keep) ?? 

I currently have a case with zabbix, when I get data from it, but I don't know about resolving data. In an attempt to poll it again, I want to write updated data to alert for scope in trigger interval or manual (from workflow page) or incident. How I can poll and enrich using a trigger?

```
id: resolve-old-alerts
description: '-'
disabled: true
triggers:
- type: manual
- type: interval
  value: 60
consts: {}
name: resolve-old-alerts
owners: []
services: []
steps:
- name: get-alerts
  provider:
    config: '{{ providers.default-keep }}'
    type: keep
    with:
      filter: status == 'firing'
      version: 2
actions:
- foreach: ' {{ steps.get-alerts.results }} '
  if: keep.to_timestamp('{{ foreach.value.lastReceived }}') < keep.utcnowtimestamp() - 3600
  name: resolve-alerts
  provider:
    config: '{{ providers.default-mock }}'
    type: mock
    with:
      enrich_alert:
      - disposable: true
        key: status
        value: resolved
```

Hints from issue discussion:
<!-- Answer -->
1. The `disposable` attribute in an enrichment rule determines whether the enrichment is temporary and should be discarded when a new alert is received. If `disposable` is set to `True`, the enrichment is added to `disposable_enrichments` and marked with `dispose_on_new_alert=True`. This means the enrichment will not persist beyond the current alert and will be removed when a new alert is processed <sup>[[1]](https://github.com/keephq/keep/blob/main/keep/providers/base/base_provider.py)</sup><sup>[[2]](https://github.com/keephq/keep/blob/main/keep/api/bl/enrichments_bl.py)</sup>.

2. If there is no alert present in the trigger, the enrichment rule would not have an alert to apply to. The enrichment process typically requires an alert to be present to apply the specified enrichments. Without an alert, the enrichment rule would not execute as intended.

3. Regarding calling subprocesses within a trigger interval and passing variables, the documentation does not provide specific details on this capability. However, Keep's workflow system allows for manual triggers and interval-based triggers, which can be configured to perform actions like polling and enriching alerts. You might need to explore custom implementations or consult further documentation for subprocess handling and variable passing.

For your case with Zabbix, you can use the `interval` trigger to poll data at regular intervals and enrich alerts based on the retrieved data. The workflow you provided uses a manual and interval trigger to resolve old alerts by checking their status and updating them if they meet certain conditions. You can adapt this approach to poll and enrich alerts using the specified triggers.


<!-- Dosu Comment Footer -->
*To continue talking to [Dosu](https://dosu.dev), mention @dosu.*

---
<sup>Help Dosu learn! Give it feedback: [Great Response](https://app.dosu.dev/response-feedback/d2065232-4a5f-4eed-8aaf-018b5e50fd80?feedback_type=great_response) | [Irrelevant Answer](https://app.dosu.dev/response-feedback/d2065232-4a5f-4eed-8aaf-018b5e50fd80?feedback_type=irrelevant_answer) | [Incorrect Sources](https://app.dosu.dev/response-feedback/d2065232-4a5f-4eed-8aaf-018b5e50fd80?feedback_type=incorrect_sources) | [Too Verbose](https://app.dosu.dev/response-feedback/d2065232-4a5f-4eed-8aaf-018b5e50fd80?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/d2065232-4a5f-4eed-8aaf-018b5e50fd80?feedback_type=hallucination) | [Other](https://app.dosu.dev/response-feedback/d2065232-4a5f-4eed-8aaf-018b5e50fd80?feedback_type=other)</sup>

Commit message: Update enrichment.mdx

Signed-off-by: Adilbek Kangerey <adilbekq@halykbank.kz>

Patch to review:
diff --git a/docs/workflows/syntax/enrichment.mdx b/docs/workflows/syntax/enrichment.mdx
index 05231d3efb..73e1859cca 100644
--- a/docs/workflows/syntax/enrichment.mdx
+++ b/docs/workflows/syntax/enrichment.mdx
@@ -21,6 +21,7 @@ Keep workflows support **enrichment**, a powerful feature that allows you to enh
 The `enrich_alert` directive is used in actions to add or update fields in the alert. You specify a list of key-value pairs where:
 - `key` is the field name to add or update.
 - `value` is the data to assign to the field. It can be a static value or dynamically derived from steps or other parts of the workflow.
+- `disposable` is an optional attribute that determines whether the enrichment is temporary and should be discarded when a new alert is received. If disposable is set to True, the enrichment is added to disposable_enrichments and marked with dispose_on_new_alert=True.
 
 ### Example Workflow with Enrichment
 
@@ -66,7 +67,7 @@ Each enrichment is defined as a key-value pair:
 enrich_alert:
   - key: field_name
     value: field_value
-
+    disposable: true
 ```
 
 - **Static Values:** Use static strings or numbers for straightforward enrichments:
@@ -143,3 +144,134 @@ workflow:
           value: "{{ results.link }}"
 
 ```
+
+
+---
+title: "Enrichment"
+---
+Keep workflows support **enrichment**, a powerful feature that allows you to enhance alerts with additional data, making them more actionable and meaningful. Enrichments add custom fields or modify existing ones in an alert directly from your workflow.
+---
+## Why Enrich Alerts?
+- **Provide Context:** Add critical information, such as related customer data or ticket IDs.
+- **Enable Automation:** Use enriched fields in subsequent actions for dynamic processing.
+- **Improve Visibility:** Surface essential metadata for better decision-making.
+---
+## How to Enrich Alerts
+### Using the `enrich_alert` Directive
+The `enrich_alert` directive is used in actions to add or update fields in the alert. You specify a list of key-value pairs where:
+- `key` is the field name to add or update.
+- `value` is the data to assign to the field. It can be a static value or dynamically derived from steps or other parts of the workflow.
+- `disposable` is an optional attribute that determines whether the enrichment is temporary and should be discarded when a new alert is received. If `disposable` is set to `True`, the enrichment is added to `disposable_enrichments` and marked with `dispose_on_new_alert=True`.
+### Example Workflow with Enrichment
+```yaml
+workflow:
+  id: enrich-alert-example
+  description: Demonstrates enriching alerts
+  triggers:
+    - type: alert
+  steps:
+    - name: get-customer-details
+      provider:
+        type: mysql
+        config: "{{ providers.mysql-prod }}"
+        with:
+          query: "SELECT * FROM customers WHERE customer_id = '{{ alert.customer_id }}'"
+          single_row: true
+  actions:
+    - name: enrich-alert-with-customer-data
+      provider:
+        type: mock
+        with:
+          enrich_alert:
+            - key: customer_name
+              value: "{{ steps.get-customer-details.results.name }}"
+              disposable: true
+            - key: customer_tier
+              value: "{{ steps.get-customer-details.results.tier }}"
+```
+In this example:
+- The `get-customer-details` step fetches customer data based on the alert.
+- The `enrich_alert` directive adds `customer_name` and `customer_tier` to the alert.
+- The `customer_name` enrichment is marked as disposable, meaning it will be discarded when a new alert is received.
+---
+## Enrichment Syntax
+### Key-Value Pairs
+Each enrichment is defined as a key-value pair:
+```yaml
+enrich_alert:
+  - key: field_name
+    value: field_value
+    disposable: true
+```
+- **Static Values:** Use static strings or numbers for straightforward enrichments:
+```yaml
+- key: alert_source
+  value: "Monitoring System"
+```
+- **Dynamic Values:** Use values derived from steps, actions, or the alert itself:
+```yaml
+- key: severity_level
+  value: "{{ alert.severity }}"
+```
+### Conditional Enrichment
+You can combine enrichment with conditions to enrich alerts dynamically:
+```yaml
+actions:
+  - name: enrich-critical-alert
+    if: "{{ alert.severity == 'critical' }}"
+    provider:
+      type: mock
+      with:
+        enrich_alert:
+          - key: priority
+            value: high
+```
+## Advanced Use Cases
+### Enrich Alerts with Results from Actions
+Enrichments can use results from actions, allowing dynamic updates based on previous steps:
+```yaml
+enrich_alert:
+  - key: ticket_id
+    value: "{{ actions.create-ticket.results.ticket_id }}"
+  - key: ticket_url
+    value: "{{ actions.create-ticket.results.ticket_url }}"
+```
+## Enrichment Workflow Example
+This example demonstrates how to enrich an alert with ticket details from ServiceNow:
+```yaml
+workflow:
+  id: servicenow-ticket-enrichment
+  triggers:
+    - type: alert
+  steps:
+    - name: fetch-alert-details
+      provider:
+        type: keep
+        with:
+          filter: "alert_id == '{{ alert.id }}'"
+  actions:
+    - name: create-servicenow-ticket
+      provider:
+        type: servicenow
+        config: "{{ providers.servicenow }}"
+        with:
+          table_name: INCIDENT
+          payload:
+            short_description: "Alert: {{ alert.name }}"
+            description: "{{ alert.description }}"
+      enrich_alert:
+        - key: ticket_id
+          value: "{{ results.sys_id }}"
+          disposable: true
+```
+## Troubleshooting Enrichment Issues
+### Enrichment without an Alert/Incident
+If there is no alert/incident present in the trigger (for example interval trigger or manual call in workflow page), the enrichment rule would not have an alert/incident to apply to. The enrichment process typically requires an alert/incident to be present to apply the specified enrichments. Without an alert/incident, the enrichment rule would not execute as intended.
+
+### Calling subprocesses
+Regarding calling subprocesses within a trigger interval and passing variables, workflow not provide this capability. However, workflow allows for manual triggers and interval-based triggers, which can be configured to perform actions like polling and enriching alerts. You might need to explore custom implementations or consult further documentation for subprocess handling and variable passing.
+
+Some possible workarounds for calling subprocesses within a trigger interval include:
+
+* Using a separate workflow for the subprocess and triggering it manually or through an API call.
+* Consulting with Keep's support team or community forums for more information on custom implementations and best practices.


Code review comments:
diff_hunk: @@ -143,3 +144,134 @@ workflow:
           value: "{{ results.link }}"
 
 ```
+
+
+---
path: docs/workflows/syntax/enrichment.mdx
text: @user1:
This seems like a duplicate, isn’t it?

@user1:
@author once you remove this redundant part, I can merge it