This directory contains comprehensive documentation for the iTop Integration app for Nextcloud, with a focus on the Configuration Item (CI) browsing and management feature.
- PLAN_CI_BROWSING.md - Master implementation plan and project roadmap for CI browsing
- PLAN_DASHBOARD.md - Dashboard widgets implementation plan (dual-widget architecture)
- PLAN_NOTIFICATIONS.md - Notification system implementation plan (12 types, Portal + Agent)
- architecture.md - High-level app architecture and data flow diagrams
- security-auth.md - Dual-token flow, storage, permissions model, profile checks
- itop-api.md - REST endpoints, OQL queries, pagination/limits, error semantics
- API_DASHBOARD.md - Dashboard API endpoints (portal & agent), request/response formats
- class-mapping.md - CI classes, fields, preview mapping, icons, search weights
- unified-search.md - Search provider spec, response format, result limits, i18n
- smart-picker.md - Suggestion provider spec, UX, throttling, access rules
- rich-preview.md - Reference provider spec, preview templates, assets, fallbacks
- DASHBOARD_IMPLEMENTATION_SUMMARY.md - Dashboard widgets implementation summary, achievements, metrics
- NOTIFICATIONS.md - Complete notification system guide (setup, configuration, FAQ, troubleshooting)
- configuration.md - Admin and personal settings, validation, feature flags
- testing.md - OrbStack dev environment, manual and automated test scripts, QA matrix
- UX-widgets.md - Widget wireframes, states, and responsive design guidelines
- caching-performance.md - Client-side and server-side caching, ETags, TTLs
- observability.md - Logging, metrics, debug switches
- l10n.md - Translation guide, German informal/formal variants, community contributions
- changelog-notes.md - Placeholders for CHANGELOG.md entries and info.xml notes
- edge-cases.md - Timeouts, partial data, missing rights, mixed locales, error handling
Phase 1-7: Foundation through Localization ✅
- Comprehensive planning and scope definition
- Technical specifications and contracts
- Core infrastructure (ItopClient, ProfileService, PreviewMapper, CacheService)
- Rich preview widget with unified PhysicalDevice layout
- Unified search integration with profile-aware permissions
- Smart picker provider for Text, Talk, and file comments
- Configuration & settings (admin and personal)
- Full localization (280+ strings in 3 languages: EN, DE, FR)
Phase 8-9: Testing & Release ✅
- Testing and QA
- User documentation and changelog
- Release preparation
Status: Feature fully implemented and working as expected in production environments.
Status: Fully implemented dual-widget architecture
- Portal widget for all users (personal ticket queue)
- Agent widget for IT agents (team metrics, SLA tracking, changes)
- Backend API endpoints (
/dashboard,/agent-dashboard) - Conditional widget visibility based on user profile
- Comprehensive translations (35+ strings in 4 languages: EN, DE, FR formal/informal)
- API documentation (API_DASHBOARD.md)
- Implementation summary (DASHBOARD_IMPLEMENTATION_SUMMARY.md)
See PLAN_DASHBOARD.md for complete implementation details.
Status: Fully implemented intelligent notification system with 12 notification types across Portal and Agent tracks
- Admin settings: 3-state configuration (disabled/forced/user_choice) for all notification types
- Personal settings: Master toggle + granular per-type checkboxes with custom intervals
- Change detection: CMDBChangeOp-based tracking (status, agent_id, case logs)
- Background job:
CheckPortalTicketUpdatesruns every 5 minutes with per-user interval checking - Notifier extensions: Four portal notification types with localized messages
- Contact role filtering: Supports direct callers AND contacts with role_code IN ('manual', 'computed')
- Rate limiting: Max 20 notifications per user per run
- Self-notification filtering: No notifications for user's own comments
- Agent name resolution: Cached lookups (24h TTL) to minimize API calls
- Zero duplicate notifications through unique object keys and timestamp filtering
- Minimal state storage (only timestamps, no per-ticket data)
- Background job:
CheckAgentTicketUpdatesruns every 5 minutes for non-portal users - Portal-only filtering: Agent job skips users with
is_portal_only='1' - SLA warning detection: Weekend-aware crossing-time algorithm (Friday: 72h, Saturday: 48h)
- Team detection: Tracks team_id changes via CMDBChangeOp for unassigned tickets
- Escalating emoji icons: ⏰ (24h) →
⚠️ (12h) → 🟠 (4h) → 🔴 (1h) → 🚨 (breach) - Assignment tracking: Detects ticket_assigned and ticket_reassigned via agent_id changes
- Comment notifications: Both public and private log types for agents
- Priority escalation: Automatic alerts when tickets reach critical priority
- Query optimization: Up to 100% API call reduction when notification types disabled
- Comprehensive user/admin guide: NOTIFICATIONS.md (345 lines)
- Updated README.md with notification system overview
- Updated CHANGELOG.md with detailed v1.3.0 entry
- Complete translations: Added 21 new strings (EN, DE, DE_DE, FR)
- OCC test command:
itop:notifications:test-user --agent/--portal/--reset
Portal Notification Types (4):
- ticket_status_changed: Track ticket lifecycle from new to resolved
- agent_responded: New public comments from IT agents
- ticket_resolved: Resolution notifications
- agent_assigned: Agent assignment changes
Agent Notification Types (8):
- 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 in your team's queue
- ticket_tto_warning: Time To Own SLA warnings (24h/12h/4h/1h thresholds)
- ticket_ttr_warning: Time To Resolve SLA warnings (24h/12h/4h/1h thresholds)
- ticket_sla_breach: SLA deadline exceeded alerts
- ticket_priority_critical: Critical priority escalations
- ticket_comment: All comments on your tickets (public + private)
Technical Implementation:
- ItopAPIService methods:
getChangeOps(),getCaseLogChanges(),getUserTicketIds(),getAgentTicketIds(),getTicketsApproachingDeadline(),applyCrossingTimeAlgorithm(),getTeamAssignmentChanges(),resolveUserNames() - Configuration keys:
agent_notification_config,portal_notification_config,default_notification_interval(JSON) - User preferences:
disabled_agent_notifications,disabled_portal_notifications,notification_check_interval,notification_last_agent_check,notification_last_portal_check - CMDBChangeOp detection: Leverages iTop's built-in change tracking for zero external state
- Crossing-time algorithm: Detects threshold crossings without storing per-ticket state
- Weekend-aware logic: Friday expands 24h to 72h, Saturday to 48h to catch Monday/Tuesday breaches
- Deduplication: Unique object keys (
ticket_id|subject|timestamp_hash) + Nextcloud's native duplicate prevention
Architecture Highlights:
- Dual background jobs: Portal and Agent jobs run independently every 5 minutes
- Per-user intervals: Reduces API load, users only processed when their interval elapses
- Smart caching: Team memberships (30 min), agent names (24h), profile data (30 min)
- Query optimization: Early exit if all notifications disabled, selective API calls
- Rate limiting: Max 20 notifications per user per run prevents spam
Testing Results (OrbStack nextcloud-dev VM):
- ✅ Portal notifications: Status changes, agent responses, resolutions, assignments
- ✅ Agent notifications: Assignments, reassignments, team queue, SLA warnings, breaches
- ✅ Weekend-aware SLA detection works (Friday 72h, Saturday 48h thresholds)
- ✅ Crossing-time algorithm eliminates duplicate SLA warnings
- ✅ Team detection via team_id changes working correctly
- ✅ No duplicate notifications across multiple job runs
- ✅ Query optimization verified (zero API calls when all types disabled)
- ✅ Portal-only user filtering working (agents not processed by agent job)
Future Enhancement: Phase 3 (Newsroom Mirroring) - Optional broadcast notifications from iTop newsroom (see GitHub Issue #3)
Two specialized dashboard widgets with automatic visibility control:
Portal Widget - For all users:
- Personal ticket queue with status breakdown
- 4 most recent tickets (Incidents + UserRequests)
- Visual status indicators and priority badges
- Quick actions: Refresh, Create New Ticket
- Responsive design for mobile/desktop
Agent Widget - For IT agents only:
- My Work: Assigned incidents and requests
- Team Queue: Team-wide ticket distribution
- SLA Tracking: TTO/TTR warnings and breaches
- Change Management: Upcoming changes with time windows
- Real-time metrics with clickable navigation
See PLAN_DASHBOARD.md and API_DASHBOARD.md for details.
Search across Configuration Items directly from Nextcloud's global search bar. Results include CI name, organization, status, and direct links to iTop.
When composing text in Talk, Text app, or comments, get intelligent CI suggestions that insert as clickable links with rich previews.
Paste iTop CI URLs anywhere in Nextcloud to get rich previews showing key information like hardware specs, software versions, or contact details.
Portal users see only CIs they're related to, while power users get full CMDB access within their iTop permissions - all secured via dual-token architecture.
End User Devices: PC, Phone, IPPhone, MobilePhone, Tablet, Printer, Peripheral Software & Applications: PCSoftware, OtherSoftware, WebApplication
- Review the master implementation plan
- Use the existing OrbStack test environment
- Understand the security model and dual-token approach
- Study the API integration patterns and class mappings
- All changes must pass integration tests on the OrbStack dev environment
- Follow the dual-token security patterns established in the codebase
- Update relevant documentation when adding features or changing APIs
- Manual version bumps only - no automatic releases
- Security-first: User data isolation, encrypted token storage, no write operations
- Performance-aware: Aggressive caching, rate limiting, minimal API calls
- User-centric: Portal user compatibility, intuitive UX, consistent with Nextcloud patterns
- Maintainable: Clean abstractions, comprehensive testing, clear documentation
For questions or clarifications, please refer to the specific documentation files or consult the project maintainer.