# Generic SWS Alerts

LLMS index: [llms.txt](/llms.txt)

---

## Generic SWS Alerts

Generic SWS Alerts let you define alert checks in YAML using **PsoftQL** queries against whitelisted PeopleSoft records. Use these when you need a one-off check that the built-in alert types don't cover.

The scheduler runs each query on the database's checking interval and triggers alerts based on the resulting row counts.

---

## Configuration Properties

Generic alerts are configured under the `genericSWSAlerts` list, either globally under `alerts` or overridden per-database under `databases[].alerts`.

|  Property  |  Type   | Required |   Default   |                                                       Description                                                        |
| ---------- | ------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `id`       | String  | **Yes**  | -           | Unique alphanumeric identifier. The system registers the alert internally as `generic_sws_<id>`.                         |
| `name`     | String  | **Yes**  | -           | Friendly name shown on the dashboard and in reports (e.g. `Stale Admins`).                                               |
| `enabled`  | Boolean | No       | `true`      | Toggle execution of this generic alert.                                                                                  |
| `severity` | String  | No       | `warning`   | Severity of the alert when triggered: `info`, `warning`, or `critical`.                                                  |
| `alertOn`  | String  | No       | `row_found` | Condition to trigger the alert: `row_found` (trigger if row count > 0) or `no_result_found` (trigger if row count == 0). |
| `message`  | String  | **Yes**  | -           | Summary message shown on the dashboard and sent in notifications when the alert triggers.                                |
| `query`    | Object  | **Yes**  | -           | A complete PsoftQL query request payload. See [PsoftQL Query Structure](#psoftql-query-structure).                       |

---

## Whitelisting Security Requirement

> [!IMPORTANT]
> For security, the SWS client restricts query capabilities to a defined list of records. Every record/table referenced in a generic alert query **must** be whitelisted in the SWS whitelisting table (`C_SWS_REC_WL`) on the target PeopleSoft database.
> If a query references a record that is not whitelisted, the alert run will fail with a whitelisting validation error.

---

## PsoftQL Query Structure

The `query` property follows the exact structure of a psLens `PsoftQLRequest` query:

|         Property         |  Type   |                            Description                            |
| ------------------------ | ------- | ----------------------------------------------------------------- |
| `records`                | Array   | List of record configurations to query (can be nested for joins). |
| `rowLimit`               | Integer | Max rows to return (recommended to keep low, e.g. `5` or `10`).   |
| `orderBy`                | String  | SQL `ORDER BY` clause for sorting findings.                       |
| `noEffectiveDateLogic`   | Boolean | Set `true` to skip automatic `EFFDT` filtering logic.             |
| `noEffectiveStatusLogic` | Boolean | Set `true` to skip automatic `EFF_STATUS = 'A'` filtering logic.  |

### Record Configuration (`records[]`)

- `recordName` (String, Required): PeopleSoft record name (e.g., `PSOPRDEFN`).
- `sqlWhereClause` (String, Optional): Filter criteria SQL fragment (e.g., `ACCTLOCK = 1`).
- `excludeFields` (List, Optional): Field names to exclude from results.

---

## Practical Examples

### Example 1: Critical Administrative Account Access (Row Found)

This alert triggers a **Critical** warning if an administrator account has been modified recently, or if a locked/inactive operator is seen initiating processes.

```yaml
alerts:
  genericSWSAlerts:
    - id: "locked_oprid_activity"
      name: "Locked Admin Activity"
      enabled: true
      severity: "critical"
      alertOn: "row_found"
      message: "Security warning: Activity detected from locked operator accounts!"
      query:
        records:
          - recordName: "PSPRCSRQST"
            sqlWhereClause: "RUNDTTM > CAST(SYSDATE - 1 AS DATE) AND OPRID IN (SELECT OPRID FROM PSOPRDEFN WHERE ACCTLOCK = 1)"
        rowLimit: 5
```

### Example 2: Process Scheduler Daemon Down (No Result Found)

This alert triggers a **Critical** warning if no process scheduler daemon has updated its status in the last 15 minutes, indicating that the scheduler might be down.

```yaml
alerts:
  genericSWSAlerts:
    - id: "scheduler_daemon_down"
      name: "Process Scheduler Daemon Status"
      enabled: true
      severity: "critical"
      alertOn: "no_result_found"
      message: "Alert: No active process scheduler daemons detected in the last 15 minutes!"
      query:
        records:
          - recordName: "PSSERVERDEFN"
            sqlWhereClause: "LASTUPDDTTM > CAST(SYSDATE - 1/96 AS DATE)" # 15 minutes lookback
        rowLimit: 1
```

---

## Notification Routing

To route notifications for a generic SWS alert, use its registered ID (`generic_sws_<id>`) in the `alertTypes` property of your notification subscription:

```yaml
notifications:
  subscriptions:
    - id: "critical-teams-webhooks"
      enabled: true
      alertTypes:
        - "generic_sws_locked_oprid_activity"
        - "generic_sws_scheduler_daemon_down"
      databases: ["*"]
      type: "webhook"
      target: "https://hooks.slack.com/services/..."
```