Add email reports & Playwright PNG export

Introduce automated email reporting with SMTP support and server-side PNG exports.

- Add email configuration and scheduling (simple_org_chart/email_config.py) and sender logic (simple_org_chart/email_sender.py).
- Add Playwright-based screenshot exporter (simple_org_chart/screenshot.py) and wire PNG generation into report flows.
- Trigger scheduled/`Send Now` emails after successful syncs (data_update.py) and add API endpoints to manage/test email config (app_main.py).
- Update scheduler to mark runs as 'scheduled' so reports are only sent for scheduled syncs.
- Include Playwright dependency and adjust Dockerfile to use Ubuntu 22.04, install Python 3.10, and install Playwright browsers; add playwright to requirements.txt.
- Make runtime/config tweaks: expose APP_BASE_URL and GUNICORN_TIMEOUT in .env.template and use env timeout in gunicorn config.
- Frontend: add email report UI/README docs, add search highlight duration setting, and implement timed fading highlight behavior in static JS/CSS and configure UI.

This change enables configurable, scheduled email reports (XLSX and optional PNG attachments) and ensures server-side PNG generation works reliably in Docker.

Author: dvir001

.env.template

@@ -14,9 +14,20 @@ AZURE_CLIENT_SECRET=your-client-secret-here
 ADMIN_PASSWORD=your-admin-password-here
 SECRET_KEY=generate-a-64-character-random-string
 
+# Application Configuration
 # Optional application port (defaults to 5000)
 APP_PORT=5000
 
+# Gunicorn worker timeout in seconds (default: 600 = 10 minutes)
+# Increase if PNG screenshot generation times out on large org charts
+GUNICORN_TIMEOUT=600
+
+# Base URL for the application (required for PNG email attachments)
+# Docker: Use http://localhost (port 80 inside container) or your external URL
+# Non-Docker: Use http://localhost:5000 or http://127.0.0.1:5000
+# IMPORTANT: This is the URL accessible FROM INSIDE the container, not external port mapping
+APP_BASE_URL=http://localhost
+
 # Optional comma-separated list of origins allowed to call the API (e.g. intranet portals)
 CORS_ALLOWED_ORIGINS=https://intranet.yourcompany.com,https://another-app.yourcompany.com
 
@@ -94,4 +105,26 @@ CORS_ALLOWED_ORIGINS=https://intranet.yourcompany.com,https://another-app.yourco
 # GRAPH_API_ENDPOINT=https://graph.microsoft.com/v1.0
 
 # Graph API beta endpoint
-# GRAPH_API_BETA_ENDPOINT=https://graph.microsoft.com/beta
+# GRAPH_API_BETA_ENDPOINT=https://graph.microsoft.com/beta
+
+# ─────────────────────────────────────────────────────────────────────────────
+# SMTP Email Configuration (for automated email reports)
+# ─────────────────────────────────────────────────────────────────────────────
+
+# SMTP server hostname (e.g., smtp.gmail.com, smtp.office365.com)
+# SMTP_SERVER=smtp.gmail.com
+
+# SMTP server port (common: 587 for STARTTLS, 465 for SSL/TLS, 25 for plain)
+# SMTP_PORT=587
+
+# SMTP username (often your email address)
+# SMTP_USERNAME=your-email@example.com
+
+# SMTP password or app-specific password
+# SMTP_PASSWORD=your-smtp-password
+
+# From address for sent emails (must be authorized by SMTP server)
+# SMTP_FROM_ADDRESS=noreply@yourcompany.com
+
+# Encryption protocol: TLS (STARTTLS for port 587), SSL (SSL/TLS for port 465), or None
+# SMTP_ENCRYPTION=TLS

Dockerfile

@@ -1,5 +1,5 @@
-# Use Python 3.10 slim image as base
-FROM python:3.10-slim
+# Use Ubuntu 22.04 with Python 3.10 for better Playwright support
+FROM ubuntu:22.04
 
 # Set working directory
 WORKDIR /app
@@ -10,22 +10,35 @@ ENV PYTHONUNBUFFERED=1
 ENV FLASK_APP=app.py
 ENV FLASK_ENV=production
 ENV APP_PORT=5000
+ENV DEBIAN_FRONTEND=noninteractive
+ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
 
-# Install system dependencies and create application user
+# Install Python 3.10 and system dependencies
 RUN apt-get update && apt-get install -y \
+    python3.10 \
+    python3.10-venv \
+    python3-pip \
     gcc \
     curl \
     && rm -rf /var/lib/apt/lists/* \
     && groupadd --system app \
     && useradd --system --gid app --create-home app
 
+# Create symlinks for python/pip
+RUN ln -sf /usr/bin/python3.10 /usr/bin/python && \
+    ln -sf /usr/bin/python3.10 /usr/bin/python3
+
 # Copy requirements first for better Docker layer caching
 COPY requirements.txt .
 
 # Install Python dependencies
 RUN pip install --no-cache-dir --upgrade pip && \
     pip install --no-cache-dir -r requirements.txt
 
+# Install Playwright browsers to system location and set ownership
+RUN playwright install --with-deps chromium && \
+    chown -R app:app /ms-playwright
+
 # Copy application code
 COPY . .
 

README.md

@@ -99,6 +99,18 @@ python -c "import secrets; print(secrets.token_hex(32))"
 | `GRAPH_API_ENDPOINT` | `https://graph.microsoft.com/v1.0` | Microsoft Graph API v1.0 endpoint. |
 | `GRAPH_API_BETA_ENDPOINT` | `https://graph.microsoft.com/beta` | Microsoft Graph API beta endpoint. |
 
+**SMTP Email Configuration (optional, for automated reports)**
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMTP_SERVER` | *(none)* | SMTP server hostname (e.g., `smtp.gmail.com`, `smtp.office365.com`). |
+| `SMTP_PORT` | `587` | SMTP server port (587 for STARTTLS, 465 for SSL/TLS, 25 for plain). |
+| `SMTP_USERNAME` | *(none)* | SMTP username (often your email address). |
+| `SMTP_PASSWORD` | *(none)* | SMTP password or app-specific password. |
+| `SMTP_FROM_ADDRESS` | *(none)* | From address for sent emails (must be authorized by SMTP server). |
+| `SMTP_ENCRYPTION` | `TLS` | Encryption protocol: `TLS` (STARTTLS for port 587), `SSL` (SSL/TLS for port 465), or `None`. |
+| `APP_BASE_URL` | `http://localhost:5000` | Base URL for generating PNG screenshots (required for PNG email attachments). |
+
 ## Running the Application
 
 ### Docker (recommended)
@@ -116,17 +128,86 @@ docker compose up -d
 
 - **Interactive D3 Org Chart**: Pan, zoom, and expand/collapse hierarchies with persistent hidden subtrees.
 - **Search & Discovery**: Real-time directory search, quick navigation helpers, and configurable filters for guests/disabled users.
-- **Configuration UI** (`/configure`): Adjust styling, filtering, export columns, and scheduling without editing files.
+- **Configuration UI** (`/configure`): Adjust styling, filtering, export columns, scheduling, and email reports without editing files.
 - **Admin Reports** (`/reports`):
   - Missing managers
-   - Users by last sign-in activity
-   - Employees hired in the last 365 days
-   - Users hidden by filters
+  - Users by last sign-in activity
+  - Employees hired in the last 365 days
+  - Users hidden by filters
+- **Automated Email Reports**: Schedule daily, weekly, or monthly reports sent via SMTP after data synchronization.
 - **Export Options**: SVG/PNG/PDF snapshots and XLSX exports for reports and chart data.
 - **MicroSIP Directory Feed**: Serve a MicroSIP contacts JSON at /contacts.json using cached employee data.
 - **Desk Phone Directory**: Yealink-compatible XML phonebook at /contacts.xml for T31P, T33G, T46U, and similar models.
 - **Caching & Scheduling**: JSON caches regenerate nightly; manual refresh endpoints keep data current on demand.
 
+## Automated Email Reports
+
+SimpleOrgChart can send scheduled email reports with organization chart data as attachments after each successful data synchronization. **Disabled by default.**
+
+### Prerequisites
+
+1. Configure SMTP environment variables in `.env` (see SMTP Email Configuration section above)
+2. Ensure all required SMTP settings are provided: server, port, username, password, and from address
+3. Set `APP_BASE_URL` in `.env` to the **internal** URL where the app listens:
+   - **Docker**: `http://localhost` (port 80 inside container, regardless of external port mapping)
+   - **Non-Docker**: `http://localhost:5000` (or whatever port you configured)
+4. **(Docker users)** PNG screenshots are automatically supported - Playwright is included in the Docker image
+5. **(Non-Docker users)** For PNG chart screenshots, install Playwright:
+   ```bash
+   pip install playwright
+   playwright install --with-deps chromium
+   ```
+
+### Configuration
+
+1. Navigate to `/configure` and locate the **📧 Email Reports** section
+2. Enable **Automated Email Reports** toggle
+3. Configure the following options:
+   - **Recipient Email**: Email address(es) to receive reports (comma-separated for multiple recipients)
+   - **Report Frequency**: Choose daily, weekly, or monthly
+   - **Day of Week**: For weekly schedules, select which day to send
+   - **Day of Month**: For monthly schedules, select first or last day
+   - **Attachment Types**: Select which file formats to include:
+     - **XLSX (Excel)**: Employee data spreadsheet (always available)
+     - **PNG (Chart Image)**: Visual org chart diagram (requires Playwright)
+4. Click **Send Test Email** to verify SMTP configuration
+5. Save settings
+
+### How It Works
+
+- Email reports are triggered automatically after successful data synchronization
+- The scheduler checks if an email should be sent based on the configured frequency
+- For **daily** reports: Emails are sent on the specified day of the week if at least 24 hours have passed since the last email
+- For **weekly** reports: Emails are sent on the specified day of the week if at least 7 days have passed
+- For **monthly** reports: Emails are sent on the first or last day of the month if at least 28 days have passed
+
+Email reports support two attachment types:
+
+1. **XLSX (Excel)** - Always available
+   - Complete employee directory with name, title, department, email, phone, manager, location details
+   - Server-side generation, no additional dependencies
+
+2. **PNG (Chart Image)** - Included in Docker, optional for manual installs
+   - Visual organization chart diagram
+   - Full chart view with all employees
+   - Generated via headless browser screenshot
+   - **Docker**: Automatically available (Playwright included in image)
+   - **Manual installs**: Requires `playwright install --with-deps chromium`
+
+> **Note**: SVG and PDF exports require client-side rendering and are not available for automated email reports. These formats can still be generated manually from the web interface.
+
+### Test Email
+
+Use the **Send Test Email** button to verify your SMTP configuration before enabling automated reports. Use **Manual Send Now** to immediately send a report with XLSX and/or PNG attachments based on your configuration.
+
+### SMTP Status
+
+The email reports section displays the current SMTP configuration status:
+- ✓ **SMTP configured**: Shows the server, port, and from address
+- ⚠ **SMTP not configured**: Indicates missing SMTP environment variables
+
+If SMTP is not configured, ensure all required variables are set in your `.env` file and restart the application.
+
 ## MicroSIP Directory
 
 SimpleOrgChart can publish a MicroSIP-compatible directory export. **Disabled by default.**

deploy/gunicorn.conf.py

@@ -12,7 +12,7 @@
 workers = multiprocessing.cpu_count() * 2 + 1
 worker_class = 'sync'
 worker_connections = 1000
-timeout = 30
+timeout = int(os.getenv("GUNICORN_TIMEOUT", "600"))  # Default 10 minutes for PNG screenshot generation
 keepalive = 2
 
 # Restart workers after this many requests, to help prevent memory leaks

requirements.txt

@@ -11,6 +11,7 @@ gunicorn==25.1.0
 marshmallow==4.2.2
 openpyxl==3.1.5
 Pillow==12.1.1
+playwright==1.49.1
 idna==3.11
 itsdangerous==2.2.0
 Jinja2==3.1.6

simple_org_chart/app_main.py

@@ -34,6 +34,13 @@
 
 import simple_org_chart.config as app_config
 from simple_org_chart.auth import login_required, require_auth, sanitize_next_path
+from simple_org_chart.email_config import (
+    get_smtp_config,
+    is_smtp_configured,
+    load_email_config,
+    save_email_config,
+    get_report_types,
+)
 from simple_org_chart.settings import (
     DEFAULT_SETTINGS,
     department_is_ignored,
@@ -1109,6 +1116,142 @@ def reset_all_settings():
         logger.error(f"Error resetting all settings: {e}")
         return jsonify({'error': 'Reset failed'}), 500
 
+
+@app.route('/api/email-config', methods=['GET', 'POST'])
+@require_auth
+@limiter.limit(RATE_LIMIT_SETTINGS)
+def handle_email_config():
+    """Get or update email report configuration."""
+    if request.method == 'GET':
+        try:
+            email_config = load_email_config()
+            smtp_config = get_smtp_config()
+            
+            # Return configuration with SMTP status (but not credentials)
+            return jsonify({
+                'success': True,
+                'config': email_config,
+                'smtpConfigured': is_smtp_configured(),
+                'smtpServer': smtp_config.get('server', ''),
+                'smtpPort': smtp_config.get('port', 587),
+                'smtpFromAddress': smtp_config.get('fromAddress', ''),
+                'availableReports': get_report_types(),
+            })
+        except Exception as e:
+            logger.error(f"Error loading email config: {e}")
+            return jsonify({'error': 'Failed to load email configuration'}), 500
+    
+    elif request.method == 'POST':
+        try:
+            new_config = request.json
+            if not new_config:
+                return jsonify({'error': 'No configuration provided'}), 400
+            
+            # Validate recipient email if enabled
+            if new_config.get('enabled') and not new_config.get('recipientEmail'):
+                return jsonify({'error': 'Recipient email is required when enabled'}), 400
+            
+            if save_email_config(new_config):
+                return jsonify({'success': True})
+            else:
+                return jsonify({'error': 'Failed to save email configuration'}), 500
+        except Exception as e:
+            logger.error(f"Error saving email config: {e}")
+            return jsonify({'error': 'Internal server error'}), 500
+
+
+@app.route('/api/email-config/test', methods=['POST'])
+@require_auth
+@limiter.limit('2 per minute')
+def test_email():
+    """Send a test email to verify SMTP configuration."""
+    try:
+        if not is_smtp_configured():
+            return jsonify({
+                'error': 'SMTP not configured. Please set SMTP environment variables in .env file.'
+            }), 400
+        
+        email_config = load_email_config()
+        recipient = email_config.get('recipientEmail')
+        
+        if not recipient:
+            return jsonify({'error': 'No recipient email configured'}), 400
+        
+        # Import email sender module (we'll create this next)
+        from simple_org_chart.email_sender import send_test_email
+        
+        success, message = send_test_email(recipient)
+        
+        if success:
+            return jsonify({'success': True, 'message': message})
+        else:
+            return jsonify({'error': message}), 500
+            
+    except ImportError:
+        return jsonify({'error': 'Email sender module not available'}), 500
+    except Exception as e:
+        logger.error(f"Error sending test email: {e}")
+        return jsonify({'error': str(e)}), 500
+
+
+@app.route('/api/email-config/test-with-attachments', methods=['POST'])
+@require_auth
+@limiter.limit('1 per 2 minutes')
+def test_email_with_attachments():
+    """Send an email report with attachments immediately."""
+    try:
+        if not is_smtp_configured():
+            return jsonify({
+                'error': 'SMTP not configured. Please set SMTP environment variables in .env file.'
+            }), 400
+        
+        email_config = load_email_config()
+        recipient = email_config.get('recipientEmail')
+        
+        if not recipient:
+            return jsonify({'error': 'No recipient email configured'}), 400
+        
+        file_types = email_config.get('fileTypes', [])
+        if not file_types:
+            return jsonify({'error': 'No file types selected for attachments'}), 400
+        
+        # Generate XLSX if requested
+        xlsx_content = None
+        if 'xlsx' in file_types:
+            try:
+                from simple_org_chart.data_update import _generate_xlsx_bytes
+                xlsx_content = _generate_xlsx_bytes()
+            except Exception as e:
+                logger.error(f"Failed to generate XLSX for email: {e}")
+                return jsonify({'error': f'Failed to generate XLSX: {str(e)}'}), 500
+        
+        # Get base URL for PNG generation if requested
+        base_url = None
+        if 'png' in file_types:
+            base_url = os.environ.get('APP_BASE_URL', 'http://localhost:5000')
+        
+        # Send email with attachments
+        from simple_org_chart.email_sender import send_test_email_with_attachments
+        
+        success, message = send_test_email_with_attachments(
+            recipient=recipient,
+            xlsx_content=xlsx_content,
+            base_url=base_url
+        )
+        
+        if success:
+            return jsonify({'success': True, 'message': message})
+        else:
+            return jsonify({'error': message}), 500
+            
+    except ImportError as e:
+        logger.error(f"Import error: {e}")
+        return jsonify({'error': 'Required module not available'}), 500
+    except Exception as e:
+        logger.error(f"Error sending email with attachments: {e}")
+        return jsonify({'error': str(e)}), 500
+
+
 @app.route('/api/export-xlsx')
 def export_xlsx():
     """Export organizational data to XLSX format"""