feat: SIP-209 Improved Alerts & Reports

[Vitor-Avila]

SUMMARY

Implements SIP-209 with per-schedule execution identities and runtime Alerts & Reports configuration.

With the new ALERT_REPORT_DYNAMIC_EXECUTOR FF off, existing execution behavior is mostly unchanged (fully backwards compatible). When enabled, Run as field controls content generation, including RLS and database OAuth2 credentials. Alerts can separately set Run alert query as for the SQL condition execution, or inherit Run as.

The one behavioral change: Instances with ALERTS_ATTACH_REPORTS disabled will stop sending table charts embedded in the alert content (ReportDataFormat.TEXT). The reasoning behind is that if attachments are disabled, the entire data querying logic should be skipped, to focus entirely on delivering the notification. This change is called out in the UPDATING.md doc.

Admins can choose a specific user or Application default, which uses ALERT_REPORTS_EXECUTORS. New schedules default to their creator, and existing schedules retain the application default until changed.
Non-admins can only select themselves. When editing a schedule that runs under another identity, they can change metadata but must switch execution to their own account before changing content or recipients.

The new Alerts & Reports configuration modal lets admins manage alert attachments, minimum alert and report intervals, email-subject date formatting, and recipient restrictions. All these configs fall back to the existing FF/config until a value is saved.

The migration adds nullable executor references to report schedules and the configurations live in a versioned document under a fixed UUID in the existing key_value table. It does not backfill or change existing schedules.

A custom tooltip message can also be displayed next to the Run As field via the ALERT_REPORTS_RUN_AS_TOOLTIP config.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

Screen.Recording.2026-10-06.at.3.22.57.PM.mov

TESTING INSTRUCTIONS

1. Apply superset db upgrade and keep ALERT_REPORT_DYNAMIC_EXECUTOR off. Run an existing alert and report to confirm they still use ALERT_REPORTS_EXECUTORS.
2. Enable the flag and edit an existing schedule. Confirm Application default preserves its behavior. Create a schedule and confirm it defaults to the creator. As an admin, select a different Run as user; for an alert, choose a separate Run alert query as user and verify both identities are used during execution.
3. As a non-admin editor of a schedule using another identity, confirm metadata edits are allowed and content/recipient edits require Execute using my permissions. Confirm the user picker is unavailable.
4. Change each global setting in the configuration modal. Try a shorter-than-allowed interval and recipients excluded by the users-only and domain policies, including both policies together. Confirm conflicting existing schedules are listed and disallowed delivery is blocked.
5. Turn off Include attachment for an alert and save it without an asset; then turn it on and confirm an asset and attachment settings are required. Put a strftime placeholder in an email subject and verify the date-format setting controls rendering.

ADDITIONAL INFORMATION

• Has associated issue: [SIP-209] Improved Alerts & Reports #39642.
• Required feature flags: ALERT_REPORT_DYNAMIC_EXECUTOR for per-schedule executors.
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API: GET/PUT /api/v1/report/configuration/
• Removes existing feature or API

[netlify]

✅ Deploy Preview for superset-docs-preview ready!

Name	Link
🔨 Latest commit	7ef30e7
🔍 Latest deploy log	https://app.netlify.com/projects/superset-docs-preview/deploys/6ac80e35e5df210008e8cc63
😎 Deploy Preview	https://deploy-preview-44992--superset-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[bito-code-review]

The issue is valid. When report_format is set to NONE, the requires_attachment() method returns False, causing the validation logic to bypass dashboard resolution and access checks, which leads to the test failures. To resolve this, the test assertions should be updated to account for this early return path when report_format is NONE.

I have checked the available context and there are no other comments on this PR to address. Would you like me to implement the fix for this test case?

[villebro]

Feature looks great, but I would still ask to reconsider intorucing a generic config table instead of a dedicated Alerts & Reports one. WDYT?

[villebro]

Chatted with Vitor offline: I'm stamping this to unblock and he'll generify the config table before merging.

[Vitor-Avila]

The ENABLE_FACTORY_RESET_COMMAND clears the key_value table. Updated the logic to preserve these configs (as the command typically wouldn't impact them).

I included KeyValueEntry.uuid.is_(None) just because technically UUID is nullable=False, so in the event there are entries without a UUID value, it would be deleted before, so deleting it here for consistency.

[villebro]

Minor nit, other than that looks good!

[sadpandajoe]

On master the embedded table for a TEXT alert with a chart was built regardless of the attachments setting, but with this gate a deployment running with attachments disabled (ALERTS_ATTACH_REPORTS off) silently stops receiving that table after upgrade, even with ALERT_REPORT_DYNAMIC_EXECUTOR off. The PR description says flag-off behavior is unchanged, so is dropping the embedded data for those existing alerts intended, or should this branch stay ungated?

[Vitor-Avila]

Called this out in UPDATING.md now. Expected change Skip attachments means no data query, and just focus on the notification. Including the chart as a text would still fire a chart query that could affect the notification.

[Antonio-RiveroMartnez]

Review — 1 blocker, 2 improvements

Verdict: The executor and permission model looks solid to me. The only thing I'd want resolved before merge is a silent change to TEXT-alert content that lands even with ALERT_REPORT_DYNAMIC_EXECUTOR off.

Blockers

1. TEXT alerts with a chart lose their embedded table when alert attachments are off. superset/commands/report/execute.py:1599-1604
   On master (execute.py:1544-1548), a chart-backed TEXT schedule always called _get_embedded_data(). This PR adds a self._attachments_enabled() check in front of that. For alerts, the check (execute.py:483-488) requires alerts_attach_reports_enabled(), which falls back to ALERTS_ATTACH_REPORTS.
   So after upgrading, any deployment that runs with ALERTS_ATTACH_REPORTS = False, or that saves "Enable attachments for alerts" as off, stops sending the table in TEXT alerts. That happens with the new FF off and with no configuration saved. The PR description says FF-off behavior is unchanged. Neither UPDATING.md nor alerts-reports.mdx:29 says the inline text table is affected; the docs only mention PNG/PDF/CSV/XLSX. This matches @sadpandajoe's unanswered comment on that line.
   Either exempt ReportDataFormat.TEXT from the global gate, or, if this is intended, say so explicitly in UPDATING.md and the docs.

Improvements

1. Config save is a read-merge-write with no lock, and it fails if the stored row is missing. superset/daos/report.py:508-525
   I know this was deferred in feat: SIP-209 Improved Alerts & Reports #44992 (comment). I'm raising it once more because the fix is very small, and it would also fix a second problem in the same code.
   • Lost updates. upsert() reads the document without a lock, merges the submitted keys, and overwrites the whole document. If two admins save at the same time, one change is lost. If the lost change is allowed_email_domains or limit_recipients_to_users, recipient delivery is unrestricted again without anyone noticing. Unlike the single-value shared_entries.py store, this is the first key_value entry that holds several settings merged into one document. The lock is already available: KeyValueDAO.get_entry(..., for_update=True) (daos/key_value.py:42-54), as used in commands/distributed_lock/release.py:112.
   • Missing row. The write goes through KeyValueDAO.update_entry, which raises KeyValueUpdateFailedError when the row isn't there (daos/key_value.py:184). Reads tolerate a missing row (daos/report.py:459-460), so the config can be read but never saved on a database without the migration seed (e.g. create_all, test fixtures, or a deleted row). It also returns a 500, not the intended 422: on_error only translates SQLAlchemyError (utils/decorators.py:236), and KeyValueUpdateFailedError is an UpdateFailedError with status = 500.
   • Suggested fix. In one transaction: a locking read, then update the row if it exists or create it if it doesn't.
2. Factory reset can fail on the retained config row's audit FK. superset/commands/security/reset.py:66-83
   Reset keeps the ALERT_REPORT_CONFIG key_value row but deletes every non-Admin user. KeyValueEntry.changed_by_fk is a plain FK to ab_user.id with no ON DELETE SET NULL (key_value/models.py:40).
   This is a narrow case: someone saves the config while they're an Admin, later loses the Admin role, and then a reset runs. On a database that enforces FKs, deleting that user fails. Nulling created_by_fk / changed_by_fk on the retained row before deleting users would avoid it.

Nits

• superset/reports/schemas.py:133: run_as_description is missing a space ("...Only" "honored..."), so the OpenAPI text reads "Onlyhonored".

Considered and dropped

• Migration conflict bot warning. Dropped: down_revision = "00fab727cd0a" matches master's current head, and nothing else on master revises it.
• sharded-jest-tests (2) failure. Dropped as unrelated: the failing test is in src/dashboard/components/gridComponents/Chart/Chart.test.tsx ("Export to full Excel"), and this PR touches nothing under src/dashboard.
• Non-admin escalation through Run as. I checked these paths and found no gap:
  • selecting another user (commands/report/base.py:493-495)
  • clearing the query executor so it inherits another identity (update.py:302-323)
  • changing content or recipients while another identity is still in place (update.py:275-300)
  • subscription recipient rewriting, which happens before the protected-field comparison (update.py:389-419)
  • deleted or inactive executors, which fail closed rather than falling back to defaults (reports/utils.py:77-81, execute.py:147-180)

[sadpandajoe]

With the flag on, an admin editing an existing report always re-sends the stored run_as/run_as_type (and the query executor just below) even if nothing about the executor changed. validate_run_as then re-validates that user, so if the stored executor has since been deactivated, an admin who only renames the report or changes its schedule gets "User does not exist or is inactive" and can't save, while the same PUT without the executor fields would succeed. Could these fields be sent only when the admin actually changed the selection, so unrelated edits keep the stored value?

[Vitor-Avila]

I'd say this is expected: most other flows in Superset are like that (PUT including all payload). Also, the error will flag to the admin right away this schedule needs fixing.