Quick Start Guide

For Users: Running the Service

Step 1: Implement Your TTS Service

Create a file my_tts_service.py:

from datetime import datetime
from dashboard.notifications.tts_api_notifier.tts_interface import TTSService, TTSTicket
import requests

class MyTTSService(TTSService):
    def __init__(self, client_config: dict, include_sids: bool) -> None:
        self.api_url = client_config["tts"]["api_url"]
        self.api_key = client_config["tts"]["api_key"]
        self.include_sids = include_sids

    def find_overlapping_ticket(self, alarm_time: datetime, services: set[str]) -> TTSTicket | None:
        # Query your TTS API for overlapping maintenance tickets
        return None

    def update_maintenance_ticket(self, ticket_id: str, message: dict) -> None:
        # Update ticket via your TTS API using the ticket_id
        pass

    def create_ticket(self, message: dict) -> TTSTicket:
        # Create ticket via your TTS API
        return TTSTicket("internal-id", "NEW-TICKET-ID", "Ticket created", None)

Step 2: Create Configuration File

See Configuration for full details on the configuration files.

Step 3: Run the Service

tts_api_notifier --client-config /etc/dashboard/client-config.json

Or with optional parameters:

tts_api_notifier --client-config /etc/dashboard/client-config.json --no-include-sids

The service will:

Initialize database connection
Connect to RabbitMQ
Start processing messages
Run until SIGTERM/SIGINT

Step 4: Monitor Logs

2026-04-02 10:15:30 - tts_api_notifier - INFO - Starting TTS API notifier service
2026-04-02 10:15:31 - tts_api_notifier - INFO - Processing thread started
2026-04-02 10:15:32 - tts_api_notifier - INFO - Created ticket TTS-12345 for alarm 67890

For Developers: Testing

Run Unit Tests

cd /path/to/dashboard-v3-python
python -m pytest test/notifications/test_tts_api_notifier.py -v

Test with Mock TTS Service

from dashboard.notifications.tts_api_notifier import start_service
from dashboard.notifications.tts_api_notifier.example_mock import MockTTSService
import json

# Load client config
with open("test-client-config.json") as f:
    client_config = json.load(f)

# Use mock service for testing
tts_service = MockTTSService(client_config, include_sids=True)

start_service(
    client_config_path="test-client-config.json",
    defaults_config_path="test-defaults-config.json",
    tts_service=tts_service
)

Integration Test Demo

python -m dashboard.notifications.tts_api_notifier.integration_test_example

Programmatic Usage (Advanced)

For testing or advanced use cases, you can also start the service programmatically:

from dashboard.notifications.tts_api_notifier import start_service
from my_tts_impl import MyTTSService

tts_service = MyTTSService(client_config, include_sids=True)
start_service(client_config, tts_service)

Implementing a TTSService

from datetime import datetime
from dashboard.notifications.tts_api_notifier.tts_interface import TTSService, TTSTicket

class MyTTSService(TTSService):
    def __init__(self, client_config: dict, include_sids: bool) -> None:
        self.api_url = client_config["tts"]["api_url"]
        self.api_key = client_config["tts"]["api_key"]
        self.include_sids = include_sids

    def find_overlapping_ticket(self, alarm_time: datetime, services: set[str]) -> TTSTicket | None:
        # Query TTS API for overlapping tickets affecting these services
        return None

    def update_maintenance_ticket(self, ticket_id: str, message: dict) -> None:
        # Update via TTS API using ticket_id
        pass

    def create_ticket(self, message: dict) -> TTSTicket:
        # Create via TTS API
        return TTSTicket("internal-id", "NEW-TICKET-123", "Ticket created", None)

Implementation Checklist

To implement a concrete TTS service:

Subclass TTSService from tts_interface.py
Implement __init__(self, client_config: dict, include_sids: bool) -> None
Implement find_overlapping_ticket(alarm_time: datetime, services: set[str]) -> TTSTicket | None
Implement update_maintenance_ticket(ticket_id: str, message: dict) -> None
Implement create_ticket(message: dict) -> TTSTicket
Handle TTS-specific credentials from client config
Call start_service() with your TTS instance

Troubleshooting

Issue: “Failed to initialize database”

Solution: Check database credentials in client-config.json

# Test DB connection
mysql -u your_db_user -p -h db.example.com your_db_name

Issue: “Failed to connect to RabbitMQ”

Solution: Check RabbitMQ credentials and connection

# Test RabbitMQ connection
rabbitmqctl status

Issue: Messages not being processed

Check logs for:

should_create_ticket returning False (messages skipped)
Exception messages (transient errors being retried)
TicketError (alarm records not found)

Issue: Service not stopping gracefully

Solution: Ensure SIGTERM/SIGINT is sent

# Send SIGTERM
kill -TERM <pid>

# Or use Ctrl+C (SIGINT)