Add Mattermost on-call shift notification support:

- Introduced personal Mattermost notifications for on-call shift starts with configurable preferences.
- Added deduplication table `OnCallShiftMattermostNotification` and migration scripts.
- Extended Mattermost notifier to handle direct message notifications via bot API.
- Updated user preferences UI to include Mattermost notifications.
- Enhanced SSO workflows to support team roles in mapping configurations.
- Adjusted related models, API endpoints, and templates to support Mattermost integration.
- Incremented service version to `1.0.28-beta`.

Author: Aidaho12

app/api/openapi/endpoints/sso.py

@@ -1,4 +1,4 @@
-from app.api.schemas.roles import GROUP_ROLE_VALUES, GROUP_VIEWER_ROLE
+from app.api.schemas.roles import GROUP_ROLE_VALUES, GROUP_VIEWER_ROLE, TEAM_ROLE_VALUES, TEAM_VIEWER_ROLE
 
 
 def path_param(name, description):
@@ -168,6 +168,16 @@ def response(description, schema=None):
             "default": GROUP_VIEWER_ROLE,
             "example": "viewer",
         },
+        "team_id": {"type": "integer", "nullable": True, "minimum": 1, "example": 10},
+        "team_slug": {"type": "string", "nullable": True, "readOnly": True, "example": "cloud-api"},
+        "team_name": {"type": "string", "nullable": True, "readOnly": True, "example": "Cloud API"},
+        "team_role": {
+            "type": "string",
+            "nullable": True,
+            "enum": list(TEAM_ROLE_VALUES),
+            "default": TEAM_VIEWER_ROLE,
+            "example": "responder",
+        },
         "active": {"type": "boolean", "default": True},
         "priority": {"type": "integer", "default": 100, "minimum": 0, "maximum": 100000},
         "created_at": {"type": "string", "format": "date-time", "readOnly": True},

app/api/schemas/profile.py

@@ -41,6 +41,7 @@ class ProfileUpdateSchema(ApiModel):
     )
     notify_oncall_shift_start_email: bool | None = None
     notify_oncall_shift_end_email: bool | None = None
+    notify_oncall_shift_start_mattermost: bool | None = None
 
     @field_validator("phone")
     @classmethod

app/api/schemas/sso.py

@@ -1,7 +1,14 @@
 from pydantic import Field, field_validator, model_validator
 
 from app.api.schemas.base import ApiModel
-from app.api.schemas.roles import GROUP_VIEWER_ROLE, GROUP_EDITOR_ROLE, GROUP_USER_ADMIN_ROLE, SSO_GLOBAL_ADMIN_ROLE
+from app.api.schemas.roles import (
+    GROUP_VIEWER_ROLE,
+    GROUP_EDITOR_ROLE,
+    GROUP_USER_ADMIN_ROLE,
+    SSO_GLOBAL_ADMIN_ROLE,
+    TEAM_ROLE_VALUES,
+    TEAM_VIEWER_ROLE,
+)
 from app.modules.sso.saml_security import SsoExtraConfig
 
 SSO_MAPPING_ROLES = {
@@ -166,6 +173,8 @@ class SsoGroupMappingCreateSchema(ApiModel):
     external_group: str = Field(min_length=1, max_length=100)
     group_id: int = Field(ge=1)
     group_role: str = Field(default=GROUP_VIEWER_ROLE, max_length=32)
+    team_id: int | None = Field(default=None, ge=1)
+    team_role: str | None = Field(default=TEAM_VIEWER_ROLE, max_length=32)
     active: bool = True
     priority: int = Field(default=100, ge=0, le=10000)
 
@@ -180,6 +189,14 @@ def validate_mapping(self):
         if not self.group_id:
             raise ValueError("incidentrelay_group_id is required")
 
+        if self.team_id and (self.team_role or TEAM_VIEWER_ROLE) not in TEAM_ROLE_VALUES:
+            raise ValueError("team_role must be viewer, responder or manager")
+
+        if not self.team_id:
+            self.team_role = None
+        elif not self.team_role:
+            self.team_role = TEAM_VIEWER_ROLE
+
         return self
 
 

app/migrations/20260702000001_oncall_shift_mattermost_notifications.py

@@ -0,0 +1,23 @@
+"""Add dedup table for personal Mattermost on-call shift notifications."""
+
+from app.db import init_database
+from app.modules.db.models import OnCallShiftMattermostNotification
+
+
+db = init_database()
+
+
+def upgrade():
+    """Create Mattermost shift notification dedup table."""
+    db.create_tables(
+        [OnCallShiftMattermostNotification],
+        safe=True,
+    )
+
+
+def downgrade():
+    """Drop Mattermost shift notification dedup table."""
+    db.drop_tables(
+        [OnCallShiftMattermostNotification],
+        safe=True,
+    )

app/migrations/20260702000002_oncall_shift_mattermost_profile_preference.py

@@ -0,0 +1,48 @@
+"""Add personal preference for Mattermost on-call shift notifications."""
+
+from peewee import BooleanField
+from playhouse.migrate import migrate
+
+from app.db import init_database
+from app.modules.db.migrator import get_migrator
+from app.modules.db.models import User
+
+
+db = init_database()
+migrator = get_migrator(db)
+
+
+def table_has_column(table_name, column_name):
+    """Return True if table already has column."""
+    return any(column.name == column_name for column in db.get_columns(table_name))
+
+
+def upgrade():
+    """Add Mattermost shift start notification preference to users."""
+    user_table = User._meta.table_name
+
+    if table_has_column(user_table, "notify_oncall_shift_start_mattermost"):
+        return
+
+    migrate(
+        migrator.add_column(
+            user_table,
+            "notify_oncall_shift_start_mattermost",
+            BooleanField(default=True),
+        )
+    )
+
+
+def downgrade():
+    """Remove Mattermost shift start notification preference from users."""
+    user_table = User._meta.table_name
+
+    if not table_has_column(user_table, "notify_oncall_shift_start_mattermost"):
+        return
+
+    migrate(
+        migrator.drop_column(
+            user_table,
+            "notify_oncall_shift_start_mattermost",
+        )
+    )

app/modules/db/models.py

@@ -140,6 +140,7 @@ class User(SoftDeleteModel):
     mattermost_user_id = CharField(null=True)
     notify_oncall_shift_start_email = BooleanField(default=True)
     notify_oncall_shift_end_email = BooleanField(default=True)
+    notify_oncall_shift_start_mattermost = BooleanField(default=True)
     password_hash = CharField(null=True)
     active = BooleanField(default=True)
     is_admin = BooleanField(default=False)
@@ -1908,6 +1909,41 @@ class Meta:
         )
 
 
+class OnCallShiftMattermostNotification(BaseModel):
+    """Deduplication log for personal Mattermost on-call shift notifications."""
+
+    id = AutoField()
+
+    user = ForeignKeyField(User, backref="oncall_shift_mattermost_notifications", on_delete="CASCADE")
+    rotation = ForeignKeyField(Rotation, backref="oncall_shift_mattermost_notifications", on_delete="CASCADE")
+
+    event_type = CharField(index=True)  # shift_start
+
+    slot_start_at = DateTimeField(index=True)
+    slot_end_at = DateTimeField(index=True)
+
+    layer_id = IntegerField(null=True)
+    override_id = IntegerField(null=True)
+
+    mattermost_user_id = CharField(index=True)
+    fingerprint = CharField(unique=True, index=True)
+
+    status = CharField(default="pending", index=True)  # pending | sent | failed | skipped
+    last_error = TextField(null=True)
+
+    created_at = DateTimeField(default=datetime.utcnow)
+    sent_at = DateTimeField(null=True)
+    updated_at = DateTimeField(default=datetime.utcnow)
+
+    class Meta:
+        table_name = "oncall_shift_mattermost_notification"
+        indexes = (
+            (("user", "event_type", "slot_start_at", "slot_end_at"), False),
+            (("rotation", "event_type", "slot_start_at"), False),
+            (("mattermost_user_id", "event_type", "slot_start_at"), False),
+        )
+
+
 class Silence(SoftDeleteModel):
     """Alert silence rule for a team."""
 
@@ -2033,7 +2069,7 @@ class Meta:
 
 
 class SsoGroupMapping(BaseModel):
-    """Map external SSO group value to IncidentRelay group role."""
+    """Map external SSO group value to IncidentRelay group and optional team role."""
 
     id = AutoField()
     provider = ForeignKeyField(SsoProvider, backref="group_mappings", on_delete="CASCADE")
@@ -2046,6 +2082,13 @@ class SsoGroupMapping(BaseModel):
     )
 
     group_role = CharField(default="viewer")
+    incidentrelay_team = ForeignKeyField(
+        Team,
+        null=True,
+        backref="sso_group_mappings",
+        on_delete="CASCADE",
+    )
+    team_role = CharField(null=True)
     active = BooleanField(default=True)
     priority = IntegerField(default=100)
 
@@ -2055,7 +2098,7 @@ class SsoGroupMapping(BaseModel):
     class Meta:
         table_name = "sso_group_mapping"
         indexes = (
-            (("provider", "external_group", "incidentrelay_group"), True),
+            (("provider", "external_group", "incidentrelay_group", "incidentrelay_team"), True),
         )
 
 

app/modules/db/sso_repo.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 
-from app.modules.db.models import Group, SsoGroupMapping, SsoIdentity, SsoProvider
+from app.modules.db.models import Group, SsoGroupMapping, SsoIdentity, SsoProvider, Team
 from app.modules.sso.crypto import encrypt_secret
 from app.modules.sso.saml_security import normalize_sso_extra_config
 
@@ -197,13 +197,32 @@ def get_group_mapping(mapping_id):
     return SsoGroupMapping.get_by_id(mapping_id)
 
 
+def _validate_group_mapping_team(data):
+    """Validate that optional SSO team mapping belongs to the selected group."""
+    team_id = data.get("team_id")
+
+    if not team_id:
+        return None
+
+    team = Team.get_by_id(team_id)
+
+    if int(team.group_id) != int(data["group_id"]):
+        raise ValueError("team_id must belong to the selected IncidentRelay group")
+
+    return team
+
+
 def create_group_mapping(provider_id, data):
     """Create SSO group mapping."""
+    team = _validate_group_mapping_team(data)
+
     return SsoGroupMapping.create(
         provider=provider_id,
         external_group=data["external_group"],
         incidentrelay_group=data["group_id"],
         group_role=data["group_role"],
+        incidentrelay_team=team.id if team else None,
+        team_role=data.get("team_role") if team else None,
         active=data.get("active", True),
         priority=data.get("priority", 100),
     )
@@ -212,10 +231,13 @@ def create_group_mapping(provider_id, data):
 def update_group_mapping(mapping_id, data):
     """Update SSO group mapping."""
     mapping = get_group_mapping(mapping_id)
+    team = _validate_group_mapping_team(data)
 
     mapping.external_group = data["external_group"]
     mapping.incidentrelay_group = data["group_id"]
     mapping.group_role = data["group_role"]
+    mapping.incidentrelay_team = team.id if team else None
+    mapping.team_role = data.get("team_role") if team else None
     mapping.active = data.get("active", True)
     mapping.priority = data.get("priority", 100)
     mapping.updated_at = datetime.utcnow()

app/modules/db/users_repo.py

@@ -244,6 +244,7 @@ def update_user(user_id, data):
         "mattermost_user_id",
         "notify_oncall_shift_start_email",
         "notify_oncall_shift_end_email",
+        "notify_oncall_shift_start_mattermost",
         "active",
         "is_admin",
         "password_hash",

app/modules/sso/sso_login.py

@@ -7,7 +7,7 @@
 
 from app.db import database_proxy as db
 from app.login import create_access_token
-from app.modules.db import groups_repo, users_repo
+from app.modules.db import groups_repo, teams_repo, users_repo
 from app.modules.db.models import SsoGroupMapping, SsoIdentity, User, UserGroup
 from app.settings import Config
 from app.api.schemas.limits import normalize_phone
@@ -344,6 +344,20 @@ def _effective_group_role(mapping_role: str) -> str:
     return mapping_role
 
 
+def _sync_team_membership_from_mapping(user, mapping):
+    """Sync optional IncidentRelay team membership from a matched SSO mapping."""
+    team_id = getattr(mapping, "incidentrelay_team_id", None)
+
+    if not team_id:
+        return
+
+    teams_repo.add_user_to_team(
+        team_id=team_id,
+        user_id=user.id,
+        role=mapping.team_role or "viewer",
+    )
+
+
 def _sync_group_memberships(user, provider, claims):
     """Sync IncidentRelay group memberships from SSO group mappings."""
     if not provider.sync_group_memberships:
@@ -400,6 +414,8 @@ def _sync_group_memberships(user, provider, claims):
             role=_effective_group_role(mapping.group_role),
         )
 
+        _sync_team_membership_from_mapping(user, mapping)
+
         matched_group_ids.append(group_id)
 
     if provider.remove_missing_group_memberships and provider_group_ids: