mpt-extension-contrib-custom-notifications

Shared notification channels for SoftwareONE MPT extensions built on the Extension SDK. Extensions report to a channel (Microsoft Teams or AWS SES email) through one registry — ctx.notifications — instead of re-implementing a sender per extension.

Channels are pluggable: each is gated by an optional-dependency extra and self-registers through an entry point, so a base install pulls no channel dependencies and only the channels you install and configure are exposed.

It consolidates the per-extension notification code previously re-implemented in the AWS (swo/notifications/teams.py) and Adobe (adobe_vipm/notifications.py) extensions.

See AGENTS.md for the module documentation map.

Install

pip install "mpt-extension-contrib-custom-notifications[teams,ses]"

The base distribution has no channel dependencies. Each channel is an extra:

Public API

mpt_extension_contrib.custom_notifications exposes the core; channel implementations live under mpt_extension_contrib.custom_notifications.channels.<name>.

Teams channel — mpt_extension_contrib.custom_notifications.channels.teams (extra teams):

Async Teams channel — mpt_extension_contrib.custom_notifications.channels.teams_async (channel teams_async, extra teams):

SES channel — mpt_extension_contrib.custom_notifications.channels.ses (extra ses):

Async SES channel — mpt_extension_contrib.custom_notifications.channels.ses_async (channel aws_ses_async, extra ses):

Usage

Make the extension settings satisfy each installed channel's settings protocol (inherit it so the contract is type-checked), then mix NotificationsContextMixin into the context — it reads the standard ext_settings, so no extra wiring:

from dataclasses import dataclass

from mpt_extension_sdk.settings.extension import BaseExtensionSettings

from mpt_extension_contrib.custom_notifications import NotificationsContextMixin
from mpt_extension_contrib.custom_notifications.channels.teams import TeamsSettings


@dataclass(frozen=True)
class ExtensionSettings(BaseExtensionSettings, TeamsSettings):
    # MSTEAMS_WEBHOOK_URL is read from the extension configuration.
    teams_webhook_url: str | None = None


class OrderContext(NotificationsContextMixin, SdkOrderContext): ...

Then resolve a channel and send. get(NotifierProtocol) returns the registered channel that satisfies the protocol, typed as that protocol:

from mpt_extension_contrib.custom_notifications.channels.teams import (
    Button,
    FactsSection,
    TeamsNotifier,
)

teams = ctx.notifications.get(TeamsNotifier)
teams.send_error(
    "Agreement sync failed",
    str(exc),
    button=Button(label="Open agreement", url=agreement_url),
    facts=FactsSection(title="Context", entries={"Agreement": agreement_id}),
)

A channel appears in the registry only when both its extra is installed and its enable flag (teams_notifications_enabled / email_notifications_enabled) is on. get(...) on a channel that is not registered raises KeyError. Enabling a channel without its required fields (teams_webhook_url / aws_ses_sender) makes build_registry raise a clear ValueError, so a misconfiguration fails loudly instead of silently disabling notifications.

Custom channels

A custom implementation inherits the channel Protocol (the registry matches by inheritance); register it under any key (use override=True to replace a built-in):

class MyTeamsNotifications(TeamsNotifier): ...


ctx.notifications.register("teams", MyTeamsNotifications(...), override=True)

To make a custom channel discoverable across extensions, ship it as its own distribution that advertises a mpt_extension_contrib.custom_notifications.channels entry point exposing a NotificationChannel.

Documentation

• Usage — install, configure, send, and write your own channel
• Architecture
• Contributing
• Testing
• Releases