Proactive Plugin Failure Notification System (MVP)(Evergreen)

Epic: Proactive Plugin Failure Notification System (MVP)

This epic focuses on providing immediate, actionable alerts to both customers and internal teams when a custom plugin fails after an upgrade, ensuring swift resolution and proactive support.

User Stories:

dotCMS Administrator responsible for my organization's site, I want to receive an immediate email notification when one of my custom plugins fails to start after a dotCMS update, so that I can begin troubleshooting the issue right away to minimize downtime and impact on my business operations.

member of the dotCMS Customer Experience team (Support/CSM/Cloud), I want to receive a proactive Slack notification when a customer's plugin fails to start after an automated upgrade, so that my team is aware of the potential issue before the customer contacts us, allowing us to prepare for a support ticket and understand the health of our customer base at a glance.

Acceptance Criteria (MVP):

• A plugin "failure" is defined as a plugin that throws an unhandled exception during its startup process and does not reach an ACTIVEOSGi state.To satisfy the Customer Administrator's need, an email notification is sent to all users on that instance who hold the "Administrator" role.To satisfy the dotCMS CX Team's need, a Slack notification is sent to a single, globally-configured internal webhook.
• The notification message must contain:
  *Customer/Site Name and URL
  • Failing Plugin Name & Version *dotCMS Version the instance was just upgraded to. *Timestamp` of the failure (in UTC).
    *The core exception/error message that caused the startup failure.
• A "Mute Failure Notifications" toggle switch must be available for each plugin within the Plugins portlet, allowing the Customer Administrator to manage alert fatigue.If a plugin's notification is muted, no emails or Slack messages are sent for that specific plugin's failures until it is un-muted.The system automatically prevents sending duplicate notifications for the same failure on the same version, even if the server restarts multiple times.

Technical Tasks

• Backend: Core Failure Detection. Hook into the OSGi BundleListenerto specifically catch exceptions during the startup sequence and identify bundles that fail to transition to the ACTIVEstate.
• Backend: Notification Recipient Logic.
  • For internal alerts, read a single Slack webhook URL from dotmarketing-config.properties.
  • For customer alerts, implement a query to fetch all users with the "Administrator" role and retrieve their email addresses from the user_table.
• Backend: Mute Functionality. Add a new field (e.g., notify_on_failureboolean) to the database entity that tracks plugins. This will store the mute state.Frontend: Mute Toggle UI. In the existing Plugins portlet UI (/dotAdmin/#/c/plugins), add a toggle switch to the display for each plugin that allows an Administrator to set the "Mute Failure Notifications" state.Backend: Notification Dispatcher. Build the service that, upon detecting a failure, checks the mute status. If not muted, it fetches the recipient lists (internal Slack, external Admin emails) and sends the formatted notifications. All generated timestamps must be in UTC.Backend: De-duplication Cache. Implement a simple in-memory cache (e.g., using Guava Cache or Caffeine) to store a key like (siteId, pluginSymbolicName)for recently sent notifications to prevent storms during a flap cycle. The cache can expire after a few hours.Docs: Update the manual! Document the new automatic notification feature and, more importantly, how an admin can mute notifications for a specific plugin using the new toggle in the Plugins portlet.

Start by locating the OSGi BundleListener startup path, the plugin-tracking database entity, and the Plugins portlet at /dotAdmin/#/c/plugins; also inspect dotmarketing-config.properties and the user_ table. Trace how plugin state, administrator recipients, and configuration are represented before splitting the notification, mute, and de-duplication work. Done means the specified email and Slack alerts, per-plugin mute toggle, duplicate suppression, UTC details, and manual documentation are covered.