> ## Documentation Index
> Fetch the complete documentation index at: https://docs.togai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

Togai's Alerting System is designed to monitor various entities for specific conditions and trigger incidents when these conditions are met. It is composed of alert templates, alerts, and incidents. The system allows users to create alerts to define conditions and thresholds on state of a single entity or group of entities. If an alert condition is satisfied, the system will create an incident.

## Entities of Alerts module

### Alert template

An Alert Template serves as a blueprint for creating alerts that monitor specific entities for certain conditions. The purpose of an alert template is to define the logic and thresholds for triggering alerts in various scenarios. Commonly, the template blueprint has the structure resembling this: Property of the \[Entity or entities] belonging to the \[Owner] breaches the \[Condition] where condition in turn has a condition operation and threshold.

**Example:**

* **Alert template**: `credit_low_balance`

  **Entity**: Credits

  **Owner**: Account

  **Parameters**: Threshold

  **Condition**: Balance of `Entity: Credits` belonging to `Owner: Account` drops below  `Parameter: Threshold`

### Alert

An Alert can be imagined as an instance of an `alert templates` combined with a set of `parameters`. Alerts monitor data for breaches depending on the configured condition thresholds.

**Example:**

* **Alert template**: `credit_low_balance`

  **Entity**: Credits

  **Owner**: Account = Acc1

  **Parameters**: Threshold = 100\$

  **Condition**: Balance of `Entity: Credits` belonging to `Owner: Account Acc1` drops below  `Parameter: 100$`

### Incident

An Incident is created when the condition defined in an alert is met, i.e., when the threshold is breached. The incident serves as a notification or event that requires action. Each incident record includes the open and close time stamps, as well as snapshots of the data being evaluated around the time of each incident also termed as `Report Data`.

<Tip>
  **Short Summary:**

  * Alert Template + Parameters => Alert
  * Alert + Condition is breached => Incident containing Report Data
</Tip>

## Alert templates

| alertTemplateId                    | Entity        | Owner Details | Parameters                                                          | Report Data                                                                  | Auto Resolvable |
| ---------------------------------- | ------------- | ------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------- | --------------- |
| **`unprocessed_events`**           | `N/A`         | `N/A`         | [*unprocessedEventParams*](#unprocessedevent-params)                | [*unprocessedEventReportData*](#unprocessedevent-report-data)                | `FALSE`         |
| **`usage_breach`**                 | `USAGE_METER` | `ACCOUNT`     | [*usageBreachParams*](#usagebreach-params)                          | [*usageBreachReportData*](#usagebreach-report-data)                          | `FALSE`         |
| **`credit_low_balance`**           | `CREDIT`      | `ACCOUNT`     | [*lowBalanceParams*](#lowbalance-params)                            | [*lowBalanceReportData*](#lowbalance-report-data)                            | `TRUE`          |
| **`wallet_low_balance`**           | `WALLET`      | `ACCOUNT`     | [*lowBalanceParams*](#lowbalance-params)                            | [*lowBalanceReportData*](#lowbalance-report-data)                            | `TRUE`          |
| **`entitlement_low_balance`**      | `FEATURE`     | `ACCOUNT`     | [*lowBalanceParams*](#lowbalance-params)                            | [*lowBalanceReportData*](#lowbalance-report-data)                            | `TRUE`          |
| **`invoice_due_breach`**           | `INVOICE`     | `ACCOUNT`     | [*invoiceDueBreachParams*](#invoiceduebreach-params)                | [*invoiceDueBreachReportData*](#invoiceduebreach-report-data)                | `FALSE`         |
| **`invoice_overdue_breach`**       | `INVOICE`     | `ACCOUNT`     | [*invoiceDueBreachParams*](#invoiceduebreach-params)                | [*invoiceDueBreachReportData*](#invoiceduebreach-report-data)                | `FALSE`         |
| **`unpaid_invoice_amount_breach`** | `null`        | `ACCOUNT`     | [*unpaidInvoiceAmtBreachParams*](#unpaidinvoiceamountbreach-params) | [*unpaidInvoiceAmtBreachReportData*](#unpaidinvoiceamountbreach-report-data) | `TRUE`          |

## Parameter Schema

#### UnprocessedEvent Params

<Expandable defaultOpen>
  <ParamField body="window" type="integer">
    This is the last window number of minutes from alert interval time that will be considered for generating the alert
  </ParamField>

  <ParamField body="threshold" type="integer" required>
    Threshold limit above which incidents are created
  </ParamField>

  <ParamField body="schemaName" type="integer">
    Name of the event schema for which unprocessed events count is required
  </ParamField>
</Expandable>

#### UsageBreach Params

<Expandable defaultOpen>
  <ParamField body="threshold" type="integer" required>
    Threshold limit for a given aggregation period above which alerts are generated.
  </ParamField>

  <ParamField body="aggregation" type="enum">
    Allowed Values: `DAY`, `WEEK`, `MONTH`, `PRICING_CYCLE`. Defaults to `PRICING_CYCLE`
  </ParamField>
</Expandable>

#### LowBalance Params

<Expandable defaultOpen>
  <ParamField body="minThreshold" type="integer" required>
    Minimum threshold limit below which incidents are created
  </ParamField>
</Expandable>

#### InvoiceDueBreach Params

<Expandable defaultOpen>
  <ParamField body="thresholdDays" type="integer" required>
    Threshold limit for days above which incidents are created
  </ParamField>

  <ParamField body="thresholdSum" type="integer">
    Threshold limit for invoice sum above which incidents are created
  </ParamField>
</Expandable>

#### UnpaidInvoiceAmountBreach Params

<Expandable defaultOpen>
  <ParamField body="thresholdSum" type="integer" required>
    Threshold limit for unpaid invoice sum above which incidents are created
  </ParamField>
</Expandable>

## Report Data Schema

#### UnprocessedEvent Report Data

<Expandable defaultOpen>
  <ParamField body="count" type="integer" required>
    Count of the unprocessed events
  </ParamField>
</Expandable>

#### UsageBreach Report Data

<Expandable defaultOpen>
  <ParamField body="usage" type="integer" required>
    Usage units
  </ParamField>
</Expandable>

#### LowBalance Report Data

<Expandable defaultOpen>
  <ParamField body="balance" type="integer" required>
    Remaining balance of credits for an account
  </ParamField>

  <ParamField body="totalGrantedUnits" type="integer">
    Total granted units of credits for an account
  </ParamField>

  <ParamField body="accountId" type="string">
    accountId corresponding to the alert
  </ParamField>
</Expandable>

#### InvoiceDueBreach Report Data

<Expandable defaultOpen>
  <ParamField body="count" type="integer" required>
    Sum of all invoices that are due / overdue after threshold number of days
  </ParamField>

  <ParamField body="sum" type="integer">
    Count of invoices that are due / overdue after threshold number of days"
  </ParamField>

  <ParamField body="accountId" type="string">
    accountId corresponding to the alert
  </ParamField>
</Expandable>

#### UnpaidInvoiceAmountBreach Report Data

<Expandable defaultOpen>
  <ParamField body="sum" type="number" required>
    Sum of the total unpaid amount
  </ParamField>

  <ParamField body="accountId" type="string" required>
    accountId corresponding to the alert
  </ParamField>

  <ParamField body="sumOfDueInvoices" type="number" required>
    Sum of the due invoices contributing to the outstanding sum
  </ParamField>

  <ParamField body="sumOfDraftInvoices" type="number" required>
    Sum of the draft invoices contributing to the outstanding sum
  </ParamField>

  <ParamField body="numberOfDueInvoices" type="integer" required>
    Number of due invoices contributing to the outstanding sum
  </ParamField>

  <ParamField body="numberOfDraftInvoices" type="integer" required>
    Number of draft invoices contributing to the outstanding sum
  </ParamField>

  <ParamField body="sumOfPartiallyPaidInvoices" type="number" required>
    Sum of the partially paid invoices contributing to the outstanding sum
  </ParamField>

  <ParamField body="numberOfPartiallyPaidInvoices" type="integer" required>
    Number of partially paid invoices contributing to the outstanding sum
  </ParamField>
</Expandable>