Merge feature/notification-system: Release v1.3.0

Merges complete notification system implementation with 12 notification types.

Features:
- Portal Notifications (4 types) - ticket updates for all users
- Agent Notifications (8 types) - SLA warnings, assignments, team queue
- Weekend-aware SLA detection (Friday 72h, Saturday 48h)
- Crossing-time algorithm (no duplicate warnings)
- 3-state admin configuration (disabled/forced/user_choice)
- Query optimization and rate limiting
- Complete documentation and translations (EN, DE, FR)

See CHANGELOG.md for detailed release notes.

Author: LexioJ

CHANGELOG.md

@@ -7,6 +7,157 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.0] - 2025-11-08
+
+### ✨ Major New Feature: Agent Notifications System
+
+Version 1.3.0 introduces a comprehensive notification system with **12 notification types** across two independent tracks: Portal (4 types) and Agent (8 types). The system provides smart, event-driven notifications with weekend-aware SLA warnings and zero duplicate detection.
+
+### Added
+
+#### Agent Notification System (8 Types)
+- **Ticket Assignment Tracking**:
+  - `ticket_assigned`: New tickets assigned to you from unassigned state
+  - `ticket_reassigned`: Tickets reassigned to you from another agent
+  - `team_unassigned_new`: New unassigned tickets appearing in your team's queue
+
+- **SLA Management**:
+  - `ticket_tto_warning`: Time To Own SLA warnings with escalating urgency (⏰ 24h → ⚠️ 12h → 🟠 4h → 🔴 1h)
+  - `ticket_ttr_warning`: Time To Resolve SLA warnings with same escalation pattern
+  - `ticket_sla_breach`: SLA deadline exceeded alerts (🚨 icon)
+  - **Weekend-Aware Logic**: Friday uses 72h threshold, Saturday uses 48h threshold to catch Monday/Tuesday breaches
+
+- **Priority & Comments**:
+  - `ticket_priority_critical`: Automatic alerts when tickets escalate to critical priority (🔴 icon)
+  - `ticket_comment`: New comments on your tickets (both public and private log types)
+
+#### Portal Notification Enhancements
+- Portal notifications (from v1.2.2) now fully integrated with agent system:
+  - `ticket_status_changed`: Status transitions
+  - `agent_responded`: Public comments from agents
+  - `ticket_resolved`: Resolution notifications
+  - `agent_assigned`: Agent assignment changes
+
+#### Background Job Infrastructure
+- **CheckAgentTicketUpdates**: New background job running every 5 minutes
+  - Processes all 8 agent notification types
+  - Portal-only filtering (skips users with `is_portal_only='1'`)
+  - Per-user interval checking (5-1440 minutes configurable)
+  - Query optimization (skips API calls when notification types disabled)
+  - Rate limiting (max 20 notifications per user per run)
+
+- **CheckPortalTicketUpdates**: Existing job (enhanced)
+  - Improved query optimization
+  - Better timestamp handling
+  - Contact role filtering support
+
+#### Admin Configuration
+- **3-State Notification Control**: Configure each notification type independently
+  - **Disabled**: Not available to users (hidden)
+  - **Forced**: Mandatory for all users (no opt-out)
+  - **User Choice**: Enabled by default, users can opt-out
+
+- **Default Configuration**:
+  - Portal: All 4 types set to "User Choice"
+  - Agent: 6 types "User Choice", 2 types "Forced" (SLA breach, priority critical)
+
+- **Configurable Intervals**:
+  - Admin default: 5-1440 minutes (recommended: 15 minutes)
+  - Per-user override available in personal settings
+
+#### OCC Commands
+- **Enhanced `itop:notifications:test-user`**:
+  - New `--agent` flag for testing agent notifications
+  - New `--portal` flag for testing portal notifications (default)
+  - `--reset` flag to clear timestamps and force full re-check
+  - Displays user configuration, enabled notifications, and next execution time
+
+#### API & Services
+- **New ItopAPIService Methods**:
+  - `getAgentTicketIds()`: Get tickets assigned to agent
+  - `getTicketsApproachingDeadline()`: SLA warning detection with crossing-time algorithm
+  - `getTeamAssignmentChanges()`: Detect new unassigned team tickets
+  - `applyCrossingTimeAlgorithm()`: Weekend-aware threshold calculation (private)
+
+- **Team Detection**:
+  - Leverages existing `getUserTeams()` method
+  - Tracks `team_id` changes via CMDBChangeOp
+  - Verifies tickets remain unassigned (`agent_id = NULL/0`)
+
+#### Documentation
+- **New docs/NOTIFICATIONS.md**: Comprehensive 345-line user & admin guide
+  - Complete notification type reference with examples
+  - Setup instructions for users and administrators
+  - Troubleshooting section with common issues
+  - FAQ with 12 frequently asked questions
+  - Technical architecture details
+
+### Changed
+
+#### Notification Algorithm Improvements
+- **SLA Crossing-Time Algorithm**: Detects threshold crossings without storing per-ticket state
+  - Eliminates duplicate warnings for same SLA level
+  - Dynamically calculates when each threshold (24h/12h/4h/1h) will be crossed
+  - Only notifies most urgent level if multiple thresholds crossed
+  - Weekend expansion: Friday (72h), Saturday (48h) for 24h threshold
+
+- **Notification Deduplication**:
+  - Unique object keys: `ticket_id|subject|timestamp_hash`
+  - Timestamp filtering prevents re-processing old changes
+  - Leverages Nextcloud's native duplicate prevention
+
+#### User Experience
+- **Personal Settings UI**: Agent notifications section (only visible to non-portal users)
+  - Master toggle for agent notifications
+  - Granular per-type checkboxes (only "User Choice" types shown)
+  - Info box listing "Forced" notifications that cannot be disabled
+  - Integrated with existing portal notification settings
+
+- **Notification Display**:
+  - Escalating emoji icons based on urgency (SLA warnings)
+  - Clear differentiation between public and private comments
+  - Team name included in team ticket notifications
+  - Clickable links route to appropriate iTop interface (portal vs admin UI)
+
+### Technical Details
+
+#### New Configuration Keys (oc_appconfig)
+- `agent_notification_config`: JSON map of notification type → state (disabled/forced/user_choice)
+- `default_notification_interval`: Default check interval for all users (minutes, default: 15)
+
+#### New User Preferences (oc_preferences)
+- `notification_last_agent_check`: Unix timestamp of last agent notification check
+- `disabled_agent_notifications`: JSON array of disabled notification types OR "all"
+- `notification_check_interval`: Per-user custom interval (minutes)
+
+#### Architecture Highlights
+- **Dual Background Jobs**: Portal and Agent jobs run independently
+- **CMDBChangeOp Detection**: Leverages iTop's built-in change tracking (no external state)
+- **Minimal State Storage**: Only timestamps per user (no per-ticket data)
+- **Query Optimization**: Early exit if all notifications disabled, selective API calls
+- **Portal-Only Filtering**: Agent job automatically skips portal-only users
+
+#### Performance
+- **Per-User Intervals**: Users only processed when their interval elapses (reduces API load)
+- **Query Optimization**: Up to 100% reduction in API calls when notification types disabled
+- **Rate Limiting**: Max 20 notifications per user per run prevents spam
+- **Smart Caching**: Team memberships cached for 30 minutes, agent names for 24 hours
+
+#### Translation Updates
+- Updated en.json, de.json, de_DE.json, fr.json with agent notification types
+
+### Breaking Changes
+None - Existing portal notifications continue working without changes.
+
+### Migration Notes
+- **No user action required**: Portal notifications work as before
+- **Agent detection automatic**: Users with `is_portal_only='0'` gain agent notification access
+
+### See Also
+- [Complete Notification Guide](docs/NOTIFICATIONS.md)
+
+---
+
 ## [1.2.2] - 2025-11-02
 
 ### Changed

README.md

@@ -2,7 +2,7 @@
 
 🎟️ **Complete iTop ITSM & CMDB Integration** - Seamlessly access tickets, incidents, and Configuration Items from your Nextcloud environment
 
-[![Version](https://img.shields.io/badge/version-1.2.0-blue)](https://github.com/lexioj/integration_itop/releases)
+[![Version](https://img.shields.io/badge/version-1.3.0-blue)](https://github.com/lexioj/integration_itop/releases)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-green)](LICENSE)
 [![Nextcloud](https://img.shields.io/badge/Nextcloud-30+-blue)](https://nextcloud.com)
 
@@ -17,7 +17,7 @@ A comprehensive Nextcloud integration that brings iTop IT Service Management and
 - 🔗 **Rich Previews** - Paste iTop links anywhere for interactive previews
 - 💬 **Smart Suggestions** - Get CI/ticket recommendations while typing in Talk or Text
 - 📊 **Dashboard Widgets** - Portal widget for personal tickets + Agent widget for operational metrics
-- 🔔 **Notifications** - Get alerted when tickets are assigned to you
+- 🔔 **Smart Notifications** - 12 notification types with weekend-aware SLA warnings (Portal + Agent tracks)
 
 ### **For IT Teams**
 - 🏗️ **CMDB Access** - Browse Configuration Items (PCs, phones, printers, software)
@@ -140,6 +140,32 @@ Quick access to tickets and CIs when creating documents or chatting.
 - **Power Users**: Full CMDB access within iTop ACL permissions
 - **Configurable**: Admins control which CI classes are searchable
 
+### 🔔 Intelligent Notification System
+**NEW in v1.3.0** - Comprehensive notification system with 12 types across Portal and Agent tracks.
+
+**Portal Notifications** (4 types for all users):
+- `ticket_status_changed` - Track ticket lifecycle from new to resolved
+- `ticket_resolved` - Resolution notifications
+- `agent_assigned` - When an agent is assigned to your ticket
+- `agent_responded` - New public comments from IT agents
+
+**Agent Notifications** (8 types for IT staff):
+- `team_unassigned_new` - New unassigned tickets in your team's queue
+- `ticket_assigned` / `ticket_reassigned` - Ticket assignment changes
+- `ticket_tto_warning` / `ticket_ttr_warning` - SLA warnings with escalating urgency (⏰ 24h → ⚠️ 12h → 🟠 4h → 🔴 1h)
+- `ticket_sla_breach` - SLA deadline exceeded alerts
+- `ticket_priority_critical` - Critical priority escalations
+- `ticket_comment` - All comments on your tickets (public + private)
+
+**Smart Features:**
+- **Weekend-Aware**: Friday uses 72h threshold, Saturday 48h to catch Monday/Tuesday breaches
+- **Zero Duplicates**: Crossing-time algorithm prevents repeated warnings for same SLA level
+- **Configurable Intervals**: Check frequency from 5-1440 minutes (default: 15 min)
+- **3-State Control**: Admin can set notifications as Disabled/Forced/User Choice
+- **Profile-Based**: Portal users see only portal notifications; agents get both tracks
+
+See [docs/NOTIFICATIONS.md](docs/NOTIFICATIONS.md) for complete setup and troubleshooting guide.
+
 ### ⚙️ Personal Settings Dashboard
 Professional user configuration with real-time status monitoring.
 
@@ -150,7 +176,8 @@ Professional user configuration with real-time status monitoring.
 - **User Profile**: See your iTop identity (name, email, organization, profiles)
 - **Ticket Counter**: Open incidents and user requests at a glance
 - **Secure Setup**: Token-based authentication with one-time personal token validation
-- **Feature Toggles**: Enable/disable search and notifications individually
+- **Feature Toggles**: Enable/disable search, portal notifications, and agent notifications individually
+- **Granular Control**: Per-notification-type toggles for User Choice notifications
 - **Clean Interface**: Professional theme-aware design
 
 ### 🛠️ Admin Configuration Panel
@@ -159,13 +186,18 @@ Comprehensive administration interface for system-wide configuration.
 ![Admin Settings - Connection Status](docs/images/admin-settings1.png)
 ![Admin Settings - Connection Configurations](docs/images/admin-settings2.png)
 ![Admin Settings - Class Configurations](docs/images/admin-settings3.png)
-![Admin Settings - Cache Settings](docs/images/admin-settings4.png)
+![Admin Settings - Notification Configurations](docs/images/admin-settings4.png)
+![Admin Settings - Cache Settings](docs/images/admin-settings5.png)
 **Administrative Features:**
 - **Connection Management**: iTop URL, display name, application token (encrypted)
 - **CI Class Configuration**: Enable/disable CI classes with 3-state control:
   - **Disabled**: CI class hidden from all users
   - **Forced**: Enabled for all users (no opt-out)
   - **User Choice**: Enabled but users can opt-out in personal settings
+- **Notification Configuration**: Enable/disable Notifications with 3-state control:
+  - **Disabled**: Notification is hidden from all users
+  - **Forced**: Enabled for all users (no opt-out)
+  - **User Choice**: Enabled but users can opt-out in personal settings
 - **Cache Performance Tuning**: Configurable TTLs for all cache types
   - CI Preview Cache: 10s-1h (default: 60s)
   - Ticket Info Cache: 10s-1h (default: 60s)
@@ -304,8 +336,11 @@ lib/
 ├── Settings/
 │   ├── Admin.php                    # Admin configuration panel
 │   └── Personal.php                 # User settings interface
-└── Notification/
-    └── Notifier.php                 # Notification system
+├── Notification/
+│   └── Notifier.php                 # Notification system (12 types)
+└── BackgroundJob/
+    ├── CheckPortalTicketUpdates.php # Portal notification processor
+    └── CheckAgentTicketUpdates.php  # Agent notification processor
 
 src/
 └── views/
@@ -383,24 +418,36 @@ Adjust cache TTLs in **Admin Settings → Cache & Performance**:
 
 ---
 
-## 📋 What's New in v1.2.0
+## 📋 What's New in v1.3.0
 
-**Major New Feature: Dual Dashboard System** 🎉
+**Major New Feature: Intelligent Notification System** 🎉
 
 ### Added
-- **Portal Widget**: Personal ticket tracking for all users with status overview, recent ticket feed, and quick actions
-- **Agent Widget**: Comprehensive operational dashboard for IT agents with workload metrics, SLA tracking, and change management
-- **Profile-Based Display**: Automatic widget selection based on iTop user profiles (Portal vs Agent)
-- **Enhanced Ticket Display**: State-specific SVG icons, status/priority emojis, and rich hover details
-- **Dashboard Backend**: New API endpoints for SLA warnings, team queue, and change management
-- **Mobile Optimization**: Responsive design with adaptive layouts for all screen sizes
-- **Dashboard Caching**: Separate cache layer for dashboard data (default: 2min TTL)
+- **12 Notification Types**: 4 Portal + 8 Agent notification types for comprehensive ticket tracking
+- **Weekend-Aware SLA Warnings**: Friday uses 72h, Saturday 48h thresholds to prevent Monday breach surprises
+- **Crossing-Time Algorithm**: Zero duplicate warnings with smart threshold detection (24h/12h/4h/1h)
+- **Dual Background Jobs**: Independent Portal and Agent notification processors (5-min intervals)
+- **3-State Admin Control**: Configure each notification type as Disabled/Forced/User Choice
+- **Granular User Control**: Per-type toggles in personal settings with master enable/disable
+- **Team Queue Detection**: Agent notifications for new unassigned tickets in team queues
+- **SLA Breach Alerts**: Critical alerts when TTO/TTR deadlines exceeded
+- **Priority Escalation**: Automatic notifications when tickets reach critical priority
+- **OCC Testing**: Enhanced `itop:notifications:test-user` with --agent/--portal/--reset flags
+- **Comprehensive Documentation**: New [docs/NOTIFICATIONS.md](docs/NOTIFICATIONS.md) with setup, FAQ, and troubleshooting
 
 ### Changed
-- **Dashboard Performance**: Optimized OQL queries for faster dashboard loading
-- **Visual Hierarchy**: Improved status differentiation and metric indicators
-- **Error Handling**: Graceful fallback when API unavailable
-- **Translation Coverage**: Added 45 new strings for dashboard widgets in all supported languages
+- **Notification Display**: Escalating emoji icons based on urgency (⏰ → ⚠️ → 🟠 → 🔴 → 🚨)
+- **Personal Settings**: Agent notification section (only visible to non-portal users)
+- **Query Optimization**: Up to 100% API call reduction when notification types disabled
+- **Rate Limiting**: Max 20 notifications per user per run prevents notification spam
+- **Translation Coverage**: Added 16 new strings for agent notifications in all supported languages
+
+### Previous Release: v1.2.0 - Dual Dashboard System
+
+**Highlights:**
+- Portal Widget for personal ticket tracking
+- Agent Widget with SLA tracking and change management
+- Profile-based display with mobile optimization
 
 ### Previous Release: v1.1.0 - Configuration Item (CI) Browsing
 
@@ -434,6 +481,12 @@ See [CHANGELOG.md](CHANGELOG.md) for complete details.
 - ✅ Verify search is enabled in personal settings
 - ✅ Check CI classes are enabled in admin settings
 
+**Notifications not working**
+- ✅ Initialize background jobs after app installation (see [docs/NOTIFICATIONS.md](docs/NOTIFICATIONS.md))
+- ✅ Verify cron.php is running every 5 minutes
+- ✅ Check notification types are not disabled in admin settings
+- ✅ Ensure personal settings have notifications enabled
+
 **Links not previewing**
 - ✅ Clear browser cache and Nextcloud cache
 - ✅ Verify URL matches iTop instance configured
@@ -473,14 +526,19 @@ curl -X POST https://itop.company.com/webservices/rest.php \
 - [x] Dual dashboard system (Portal + Agent widgets)
 - [x] SLA tracking and team metrics
 
-### v1.3.0 (Next Release)
+### v1.3.0 (Released 2025-11-08) ✅
+- [x] Notification system with 12 types (Portal + Agent)
+- [x] Weekend-aware SLA warnings
+- [x] Background jobs for automated notification delivery
+
+### v1.4.0 (Next Release)
 - [ ] Advanced search filters (date ranges, custom fields)
-- [ ] Notification system
+- [ ] Newsroom mirroring for broadcast notifications
 
 ### Future
 - [ ] Ticket creation from Nextcloud
 - [ ] CI relationship browser (dependencies, impacts)
-- [ ] Enhanced notification system with email digest
+- [ ] Email digest for notifications
 - [ ] Additional CI classes (Server, VirtualMachine, Network Device)
 - [ ] API rate limiting improvements
 - [ ] More languages (Spanish, Italian, Dutch, Portuguese)

appinfo/info.xml

@@ -109,9 +109,14 @@ Seamlessly connect your Nextcloud collaboration platform with iTop IT Service Ma
 	</dependencies>
 
 	<background-jobs>
-		<job>OCA\Itop\BackgroundJob\CheckOpenTickets</job>
+		<job>OCA\Itop\BackgroundJob\CheckPortalTicketUpdates</job>
+		<job>OCA\Itop\BackgroundJob\CheckAgentTicketUpdates</job>
 	</background-jobs>
 
+	<commands>
+		<command>OCA\Itop\Command\NotificationsTestUser</command>
+	</commands>
+
 	<settings>
 		<admin>OCA\Itop\Settings\Admin</admin>
 		<admin-section>OCA\Itop\Settings\AdminSection</admin-section>

appinfo/routes.php

@@ -9,6 +9,8 @@
 		['name' => 'config#setAdminConfig', 'url' => '/admin-config', 'verb' => 'PUT'],
 		['name' => 'config#testAdminConnection', 'url' => '/admin-config/test', 'verb' => 'POST'],
 		['name' => 'config#testApplicationToken', 'url' => '/admin-config/test-token', 'verb' => 'POST'],
+		['name' => 'config#saveNotificationSettings', 'url' => '/notification-settings', 'verb' => 'POST'],
+		['name' => 'config#saveNotificationConfig', 'url' => '/notification-config', 'verb' => 'POST'],
 		['name' => 'config#saveCacheSettings', 'url' => '/cache-settings', 'verb' => 'POST'],
 		['name' => 'config#clearAllCache', 'url' => '/clear-cache', 'verb' => 'POST'],
 		['name' => 'config#saveCIClassConfig', 'url' => '/ci-class-config', 'verb' => 'POST'],