Incident Creation Workflows & Signal Architecture¤

# src/firefighter/incidents/signals.py

incident_created = django.dispatch.Signal()
"""Signal sent when an incident is created
Args:
    incident (Incident): The incident that was created
"""

incident_updated = django.dispatch.Signal()
"""Signal sent when an incident is updated
Args:
    sender (str): The sender identifier (e.g., "update_status", "update_roles")
    incident (Incident): The incident that was updated
    incident_update (IncidentUpdate): The incident update that was created
    updated_fields (list[str]): The fields that were updated
    old_priority (Priority, optional): The old priority if changed
"""

incident_key_events_updated = django.dispatch.Signal()
"""Signal sent when an incident's key events are updated
Args:
    incident (Incident): The incident whose key events were updated
"""

incident_closed = django.dispatch.Signal()
"""Signal sent when an incident is closed
Args:
    sender (Any): The sender identifier
    incident (Incident): The incident that was closed
"""

postmortem_created = django.dispatch.Signal()
"""Signal sent when a postmortem is created
Args:
    sender (str): The sender identifier
    incident (Incident): The incident for which postmortem was created
"""

get_invites = django.dispatch.Signal()
"""Signal sent to retrieve the list of users to invite
Args:
    incident (Incident): The incident for which to retrieve invites
Returns:
    users (list[User]): The list of users to invite
"""

create_incident_conversation = django.dispatch.Signal()
"""Signal sent to create a Slack conversation for an incident
Args:
    incident (Incident): The incident for which to create conversation
"""

# src/firefighter/slack/signals/__init__.py

incident_channel_done = django.dispatch.Signal()
"""Signal sent when Slack channel creation is complete
Args:
    incident (Incident): The incident
    channel (IncidentChannel): The created Slack channel
    **kwargs: Additional context (jira_extra_fields, impacts_data, etc.)
"""

def _trigger_critical_incident_workflow(
    self,
    creator: User,
    impacts_data: dict[str, ImpactLevel],
) -> None:
    """Create a critical incident (P1-P3) with Slack channel and roles.

    Workflow:
    1. Create Incident in database
    2. Signal: create_incident_conversation → Creates Slack channel
    3. Signal: incident_channel_done → Creates Jira ticket + setup channel
    """
    # Prepare cleaned data
    cleaned_data_copy = dict(self.cleaned_data)

    # Handle multi-environment: store all in custom_fields
    environments = cleaned_data_copy.pop("environment", [])
    if isinstance(environments, list) and environments:
        cleaned_data_copy["environment"] = environments[0]
        cleaned_data_copy.setdefault("custom_fields", {})
        cleaned_data_copy["custom_fields"]["environments"] = [env.value for env in environments]

    # Step 1: Create Incident in DB
    incident = Incident.objects.declare(created_by=creator, **cleaned_data_copy)

    # Prepare Jira extra fields (passed to signal handlers)
    jira_extra_fields = {
        "zendesk_ticket_id": self.cleaned_data.get("zendesk_ticket_id", ""),
        "seller_contract_id": self.cleaned_data.get("seller_contract_id", ""),
        "zoho_desk_ticket_id": self.cleaned_data.get("zoho_desk_ticket_id", ""),
        "is_key_account": self.cleaned_data.get("is_key_account"),
        "is_seller_in_golden_list": self.cleaned_data.get("is_seller_in_golden_list"),
        "platforms": [p.value for p in self.cleaned_data.get("platform", [])],
        "environments": [env.value for env in environments] if environments else [],
    }

    # Step 2: Signal to create Slack channel
    # This will trigger:
    # - Slack channel creation
    # - incident_channel_done signal → Jira ticket creation
    create_incident_conversation.send(
        "incident_created",
        incident=incident,
        jira_extra_fields=jira_extra_fields,
        impacts_data=impacts_data,
    )

@receiver(signal=incident_channel_done)
def create_ticket(
    sender: Any, incident: Incident, channel: IncidentChannel, **kwargs: Any
) -> JiraTicket:
    # Extract context from kwargs
    jira_extra_fields = kwargs.get("jira_extra_fields", {})
    impacts_data = kwargs.get("impacts_data", {})

    # Get Jira user
    jira_user = get_jira_user_from_user(incident.created_by)

    # Build enhanced description
    description = f"""{incident.description}

🧯 This incident has been created for a critical incident.
📦 Incident category: {incident.incident_category.name}
{incident.priority.emoji} Priority: {incident.priority.name}
"""

    # Get all environments (multi-environment support)
    environments = jira_extra_fields.get("environments") or \
                   incident.custom_fields.get("environments", []) or \
                   [incident.environment.value]

    platforms = jira_extra_fields.get("platforms", ["platform-All"])

    # Prepare Jira fields using common function
    jira_fields = prepare_jira_fields(
        title=incident.title,
        description=description,
        priority=incident.priority.value,
        reporter=jira_user.id,
        incident_category=incident.incident_category.name,
        environments=environments,
        platforms=platforms,
        impacts_data=impacts_data,
        optional_fields={
            "zendesk_ticket_id": jira_extra_fields.get("zendesk_ticket_id", ""),
            "seller_contract_id": jira_extra_fields.get("seller_contract_id", ""),
            "zoho_desk_ticket_id": jira_extra_fields.get("zoho_desk_ticket_id", ""),
            "is_key_account": jira_extra_fields.get("is_key_account"),
            "is_seller_in_golden_list": jira_extra_fields.get("is_seller_in_golden_list"),
        },
    )

    # Create Jira issue
    issue = client.create_issue(**jira_fields)

    # Add watchers and links
    client.jira.add_watcher(issue=issue_id, watcher=jira_user.id)
    client.jira.add_simple_link(issue=issue_id, object={"url": incident.status_page_url, ...})
    client.jira.add_simple_link(issue=issue_id, object={"url": channel.link, ...})

    # Create JiraTicket in DB, linked to Incident
    jira_ticket = JiraTicket.objects.create(**issue, incident=incident)

    # Add Jira bookmark to Slack channel
    channel.add_bookmark(title="Jira ticket", link=jira_ticket.url, emoji=":jira_new:")

    # Send announcement in channel
    channel.send_message_and_save(SlackMessageIncidentDeclaredAnnouncement(incident))

    return jira_ticket

@receiver(signal=incident_channel_done)
def incident_channel_done_bookmarks(
    incident: Incident, channel: IncidentChannel, **kwargs: Any
) -> None:
    """Add incident page bookmark to Slack channel"""
    channel.add_bookmark(
        title="Incident Page",
        link=incident.status_page_url + "?utm_medium=...",
        emoji=SLACK_APP_EMOJI,
    )

@receiver(incident_channel_done)
def sev1_process_reminder(
    incident: Incident, channel: IncidentChannel, **kwargs: Never
) -> None:
    """Send communication process reminder for P1 PRD incidents"""
    if incident.priority.value == 1 and incident.environment.value == "PRD":
        channel.send_message_and_save(SlackMessageIncidentComProcess(incident))

@receiver(incident_channel_done)
def send_roles_message_in_conversation(
    incident: Incident, channel: IncidentChannel, **kwargs: Any
) -> None:
    """Send initial roles message in Slack channel"""
    update_roles_message = SlackMessageIncidentRolesUpdated(
        incident=incident,
        incident_update=None,
        first_update=True,
    )
    incident.conversation.send_message_and_save(update_roles_message)

incidents_incident:
  id: 123
  title: "Production API down"
  priority: P1 (value=1)
  environment: PRD
  custom_fields: {"environments": ["PRD", "STG"]}
  ...

slack_incident_channel:
  id: 1
  incident_id: 123  # OneToOne relationship
  channel_id: "C12345"
  name: "inc-123-prd-stg-production-api-down"
  ...

raid_jiraticket:
  id: 456
  incident_id: 123  # Links to Incident
  key: "INC-789"
  url: "https://jira.example.com/browse/INC-789"
  ...

def _trigger_normal_incident_workflow(
    self,
    creator: User,
    impacts_data: dict[str, ImpactLevel],
) -> None:
    """Create a normal incident (P4-P5) with Jira ticket only.

    Workflow:
    1. Prepare Jira fields
    2. Create Jira issue via API
    3. Create JiraTicket in DB (incident=None)
    4. Send Slack notifications (DMs + raid_alert channels)

    Note: Does NOT create Incident object or Slack channel.
    """
    # Get Jira user
    jira_user = get_jira_user_from_user(creator)

    # Prepare environments and platforms
    environments = self.cleaned_data.get("environment", [])
    if isinstance(environments, list) and environments:
        environments_values = [env.value for env in environments]
    else:
        environments_values = [environments.value] if environments else []

    platforms = [p.value for p in self.cleaned_data.get("platform", [])]

    # Prepare Jira fields using common function
    jira_fields = prepare_jira_fields(
        title=self.cleaned_data["title"],
        description=self.cleaned_data["description"],
        priority=self.cleaned_data["priority"].value,
        reporter=jira_user.id,
        incident_category=self.cleaned_data["incident_category"].name,
        environments=environments_values,
        platforms=platforms,
        impacts_data=impacts_data,
        optional_fields={
            "zendesk_ticket_id": self.cleaned_data.get("zendesk_ticket_id", ""),
            "seller_contract_id": self.cleaned_data.get("seller_contract_id", ""),
            "zoho_desk_ticket_id": self.cleaned_data.get("zoho_desk_ticket_id", ""),
            "is_key_account": self.cleaned_data.get("is_key_account"),
            "is_seller_in_golden_list": self.cleaned_data.get("is_seller_in_golden_list"),
            "suggested_team_routing": self.cleaned_data.get("suggested_team_routing"),
        },
    )

    # Create Jira issue directly (no Incident object created)
    issue_data = jira_client.create_issue(**jira_fields)

    # Process Jira issue: create JiraTicket in DB (incident=None)
    process_jira_issue(
        issue_data=issue_data,
        user=creator,
        jira_user=jira_user,
        impacts_data=impacts_data,
    )

def process_jira_issue(
    issue_data: JiraObject,
    user: User,
    jira_user: JiraUser,
    impacts_data: dict[str, ImpactLevel],
    *args: Never,
    **kwargs: Never,
) -> None:
    """Process a Jira issue for P4-P5 incidents.

    Creates JiraTicket in DB without linking to an Incident.
    Sends Slack notifications via DM and raid_alert channels.
    """
    # Create JiraTicket in DB (incident=None)
    jira_ticket = JiraTicket.objects.create(**issue_data)

    # Save impact levels
    impacts_form = SelectImpactForm(impacts_data)
    impacts_form.save(incident=jira_ticket)

    # Set up Jira watchers
    set_jira_ticket_watchers_raid(jira_ticket)

    # Send Slack alerts (DM to creator + raid_alert channels)
    alert_slack_new_jira_ticket(jira_ticket)

def alert_slack_new_jira_ticket(
    jira_ticket: JiraTicket,
    reporter_user: User | None = None,
    reporter_email: str | None = None,
) -> None:
    """Send Slack notifications for new P4-P5 Jira tickets.

    - Sends DM to reporter (if they have Slack enabled)
    - Posts in raid_alert channels based on priority and domain
    """
    # Validation: this is only for P4-P5 (no incident)
    if hasattr(jira_ticket, "incident") and jira_ticket.incident:
        raise ValueError("This is a critical incident, not a raid incident.")

    reporter_user = reporter_user or jira_ticket.reporter.user
    reporter_email = reporter_email or reporter_user.email
    user_domain = get_domain_from_email(reporter_email)

    # Create Slack message
    message = SlackMessageRaidCreatedIssue(jira_ticket, reporter_user=reporter_user)

    # Send DM to reporter
    if reporter_user.slack_user and reporter_user.slack_user.slack_id:
        reporter_user.slack_user.send_private_message(message, unfurl_links=False)

    # Get alert channels based on priority and domain
    channels = get_internal_alert_conversations(jira_ticket)
    if user_domain:
        channels.union(get_partner_alert_conversations(user_domain))

    # Post in all raid_alert channels
    for channel in channels:
        channel.send_message_and_save(message)

incidents_incident:
  (empty - no record created)

slack_incident_channel:
  (empty - no channel created)

raid_jiraticket:
  id: 789
  incident_id: NULL  # ❌ Not linked to any Incident
  key: "SBI-123"
  url: "https://jira.example.com/browse/SBI-123"
  ...

@receiver(signal=incident_updated, sender="update_status")
def incident_updated_update_status_handler(...) -> None:
    # Skip Slack operations for incidents without channels (e.g., P4-P5)
    if not hasattr(incident, "conversation"):
        logger.debug(f"Skipping Slack channel update for incident {incident.id} (no conversation)")
        return

    # Proceed with Slack operations...
    incident.conversation.rename_if_needed()
    incident.conversation.set_incident_channel_topic()
    # ...

def save(self, creator: User, impacts_data: dict[str, ImpactLevel]) -> Incident:
    """Unified workflow for all priorities."""
    # Step 1: Always create Incident in DB (ALL priorities)
    cleaned_data_copy = dict(self.cleaned_data)

    # Handle multi-environment
    environments = cleaned_data_copy.pop("environment", [])
    if isinstance(environments, list) and environments:
        cleaned_data_copy["environment"] = environments[0]
        cleaned_data_copy.setdefault("custom_fields", {})
        cleaned_data_copy["custom_fields"]["environments"] = [env.value for env in environments]

    incident = Incident.objects.declare(created_by=creator, **cleaned_data_copy)

    # Step 2: Conditionally create Slack channel (P1-P3 only)
    if self.should_create_slack_channel():
        self._create_slack_channel(incident, impacts_data)

    # Step 3: Always create Jira ticket (ALL priorities) - UNIFIED
    self._create_jira_ticket(incident, creator, impacts_data)

    return incident

def should_create_slack_channel(self) -> bool:
    """Determine if incident needs Slack channel based on priority."""
    priority = self.cleaned_data.get("priority")
    return priority and priority.value < 4  # P1-P3 only

def _create_slack_channel(
    self,
    incident: Incident,
    impacts_data: dict[str, ImpactLevel]
) -> None:
    """Create Slack channel for P1-P3 incidents."""
    # Signal to create Slack channel (triggers bookmarks, roles message, etc.)
    create_incident_conversation.send(
        "incident_created",
        incident=incident,
        impacts_data=impacts_data,
    )

def _create_jira_ticket(
    self,
    incident: Incident,
    creator: User,
    impacts_data: dict[str, ImpactLevel],
) -> JiraTicket:
    """Create Jira ticket for ALL priorities - UNIFIED method."""
    # Get Jira user
    jira_user = get_jira_user_from_user(creator)

    # Prepare environments and platforms
    environments = self.cleaned_data.get("environment", [])
    if isinstance(environments, list) and environments:
        environments_values = [env.value for env in environments]
    else:
        environments_values = [environments.value] if environments else []

    platforms = [p.value for p in self.cleaned_data.get("platform", [])]

    # Build description (enhanced for P1-P3, simple for P4-P5)
    if hasattr(incident, "conversation"):
        # P1-P3: Enhanced description with links
        description = f"""{incident.description}

🧯 This incident has been created for a critical incident.
📦 Incident category: {incident.incident_category.name}
{incident.priority.emoji} Priority: {incident.priority.name}
"""
    else:
        # P4-P5: Simple description
        description = incident.description

    # Prepare Jira fields using common function (UNIFIED for all priorities)
    jira_fields = prepare_jira_fields(
        title=incident.title,
        description=description,
        priority=incident.priority.value,
        reporter=jira_user.id,
        incident_category=incident.incident_category.name,
        environments=environments_values,
        platforms=platforms,
        impacts_data=impacts_data,
        optional_fields={
            "zendesk_ticket_id": self.cleaned_data.get("zendesk_ticket_id", ""),
            "seller_contract_id": self.cleaned_data.get("seller_contract_id", ""),
            "zoho_desk_ticket_id": self.cleaned_data.get("zoho_desk_ticket_id", ""),
            "is_key_account": self.cleaned_data.get("is_key_account"),
            "is_seller_in_golden_list": self.cleaned_data.get("is_seller_in_golden_list"),
            "suggested_team_routing": self.cleaned_data.get("suggested_team_routing"),
        },
    )

    # Create Jira issue via API (UNIFIED)
    issue_data = jira_client.create_issue(**jira_fields)

    # Create JiraTicket in DB, linked to Incident (UNIFIED)
    jira_ticket = JiraTicket.objects.create(**issue_data, incident=incident)

    # Save impact levels
    impacts_form = SelectImpactForm(impacts_data)
    impacts_form.save(incident=jira_ticket)

    # Set up Jira watchers
    set_jira_ticket_watchers(jira_ticket, jira_user)

    # Add Jira links
    add_jira_links(jira_ticket, incident)

    # Send Slack notifications based on channel presence
    if hasattr(incident, "conversation"):
        # P1-P3: Add bookmark and send announcement in channel
        incident.conversation.add_bookmark(
            title="Jira ticket",
            link=jira_ticket.url,
            emoji=":jira_new:",
        )
        incident.conversation.send_message_and_save(
            SlackMessageIncidentDeclaredAnnouncement(incident)
        )
    else:
        # P4-P5: Send DM and raid_alert notifications
        alert_slack_new_jira_ticket(jira_ticket)

    return jira_ticket

# ❌ DELETE: src/firefighter/raid/signals/incident_created.py
# The entire signal handler can be removed since Jira creation
# is now unified in UnifiedIncidentForm._create_jira_ticket()

@receiver(signal=incident_channel_done)  # ❌ No longer needed
def create_ticket(...) -> JiraTicket:
    # This entire handler can be deleted
    pass

# ⚠️ OPTION 1: Remove entirely (recommended)
# All logic moved to UnifiedIncidentForm._create_jira_ticket()

# ⚠️ OPTION 2: Keep only for Jira webhook processing
def process_jira_issue_from_webhook(
    issue_data: JiraObject,
    user: User,
    impacts_data: dict[str, ImpactLevel],
) -> JiraTicket:
    """Process Jira issue updates from webhooks only."""
    # Minimal logic for webhook-triggered updates
    pass