iTop Integration for Nextcloud

🎟️ Complete iTop ITSM & CMDB Integration - Seamlessly access tickets, incidents, and Configuration Items from your Nextcloud environment

A comprehensive Nextcloud integration that brings iTop IT Service Management and CMDB functionality directly into your collaboration platform. Users can search tickets, browse configuration items, and insert rich previews—all without leaving Nextcloud.

✨ Why Choose This Integration?

For End Users

🔍 Instant Search - Find tickets and CIs from Nextcloud's search bar
🔗 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

For IT Teams

🏗️ CMDB Access - Browse Configuration Items (PCs, phones, printers, software)
👥 Profile-Aware - Portal users see only their assets; power users get full access
🔐 Enterprise Security - Dual-token architecture with encrypted storage
⚡ High Performance - Configurable caching (10s-1h TTLs)
🌍 Multi-Language - English, German (Du/Sie), French

For Administrators

⚙️ Granular Control - Enable/disable CI classes per user or globally
📈 Scalable - Distributed caching for high-traffic deployments
🛡️ Secure by Design - Personal tokens never stored, Person ID filtering
🎨 Professional UI - Clean interface matching Nextcloud design standards

🚀 Key Features

📊 Interactive Dashboard Widgets

Get comprehensive overviews of your ticket queue directly on your Nextcloud dashboard. The integration provides two specialized widgets that adapt to your user profile:

🎫 Portal Widget - "iTop"

For All Users - Track your personal tickets at a glance

Features:

Compact Status Overview: See total tickets with badge breakdown (open, escalated, pending, resolved)
Recent Ticket Feed: Display 4 most recent tickets sorted by last update
Visual Status Indicators: State-specific SVG icons (new, escalated, deadline, closed) for both Incidents and UserRequests
Inline Metadata: Status emoji (🆕👥⏳⚠️✅☑️❌), priority emoji (🔴🟠🟡🟢), and relative timestamps with tooltips
Rich Hover Details: Comprehensive ticket information on hover including reference, dates, and sanitized description
One-Click Access: Click any ticket to open directly in iTop
Quick Actions: Refresh dashboard and create new tickets without leaving Nextcloud
Responsive Design: Mobile-optimized layout adapts to all screen sizes

👨‍💼 Agent Widget - "iTop - Agent Dashboard"

For Agent Users Only - Comprehensive operational dashboard

Features:

My Work: Count of assigned incidents and requests
Team Queue: Team-wide ticket counts (incidents and requests)
SLA Tracking:
- SLA Warnings (TTO/TTR approaching)
- SLA Breaches (TTO/TTR exceeded)
Change Management:
- Upcoming changes with time windows
- Emergency/Normal/Routine change types
- Current and planned change status
Quick Navigation: Click metrics to jump to filtered iTop views
Real-Time Counts: Live ticket counts with visual indicators (info, warning, error)
Responsive Grid: 2x2 metrics layout adapting to screen size

Widget Visibility:

Portal Users (is_portal_only = true): See only Portal Widget
Agent Users (is_portal_only = false): See both Portal Widget and Agent Widget
Automatically controlled by iTop user profiles

Perfect for:

Portal Widget: End users tracking their personal requests
Agent Widget: IT agents managing workload, SLA compliance, and team coordination
Both: Managers needing both personal and operational views

🔗 Dynamic Reference Provider

Transform iTop links into rich, interactive previews across Nextcloud apps (Talk, Deck, Text, Collectives).

What You Get:

Tickets: Status, priority, assignee, caller, description, timestamps
Configuration Items: Hardware specs (CPU, RAM), software details, contact count
Smart Icons: State-specific ticket icons (closed, escalated, deadline)
CI Icons: Class-specific icons for all 11 CI types (PC, phone, printer, etc.)
Universal Support: Works across all Nextcloud apps supporting rich content

🔍 Unified Search Integration

Search your iTop tickets and Configuration Items directly from Nextcloud's unified search bar.

Search Capabilities:

Tickets: UserRequest, Incident - by title, description, reference number
Configuration Items: PC, Phone, Tablet, Printer, Software, WebApplication
Smart Ranking: Exact matches first, then class weighting, then recency
Profile-Aware: Portal users see only related CIs; power users get full CMDB
Real-Time Status: Live priority badges and status indicators
Performance: Results cached (30s default) for instant response

🎯 Smart Picker Integration

Quick access to tickets and CIs when creating documents or chatting.

Features:

Context-Aware Suggestions: Recent tickets and CIs based on your work
Dual Search: Find both tickets and Configuration Items
Rich Insertion: Insert links that automatically become interactive previews
Talk/Text Integration: Works seamlessly in chat and document editing
Debounced Queries: Performance-optimized with intelligent caching

📊 Configuration Item (CI) Browsing

NEW in v1.1.0 - Complete CMDB integration with 11 supported CI classes:

End User Devices

PC - Desktops and laptops with hardware specs (CPU, RAM, OS)
Phone/IPPhone/MobilePhone - Telephony devices with phone numbers and IMEI
Tablet - Mobile tablet devices
Printer - Network and local printers
Peripheral - Monitors, keyboards, mice, and other peripherals

Software & Applications

PCSoftware - Desktop/server software with version and license info
OtherSoftware - Miscellaneous software installations
WebApplication - Web-based applications with URLs

Profile-Based Permissions:

Portal Users: See only CIs where they are listed as contacts (strict filtering)
Power Users: Full CMDB access within iTop ACL permissions
Configurable: Admins control which CI classes are searchable

⚙️ Personal Settings Dashboard

Professional user configuration with real-time status monitoring.

Your Control Panel:

Connection Status: Real-time indicator with connectivity testing
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
Clean Interface: Professional theme-aware design

🛠️ Admin Configuration Panel

Comprehensive administration interface for system-wide configuration.

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
Cache Performance Tuning: Configurable TTLs for all cache types
- CI Preview Cache: 10s-1h (default: 60s)
- Ticket Info Cache: 10s-1h (default: 60s)
- Search Results Cache: 10s-5min (default: 30s)
- Smart Picker Cache: 10s-5min (default: 60s)
- Profile Cache: 10s-1h (default: 30min)
Cache Management: Clear all cache button for immediate refresh
Connection Testing: Real-time validation of server connectivity
User Monitoring: See how many users are connected
Professional UI: Clean, theme-aware interface

🔐 Security Architecture

Dual-Token Approach

Maximum security with user convenience:

Application Token (Admin-configured)

Administrator-level token stored encrypted
Used for all iTop API queries
Never exposed to end users
Rotatable without disrupting user sessions

Personal Token (User-provided)

Provided once during setup for identity verification
Never stored - discarded immediately after validation
Maps Nextcloud user to iTop Person ID
Supports Portal users via iTop Portal Personal Tokens Extension

Data Isolation

Person ID Filtering: All queries filtered by user's Person ID
Profile-Based Access: Portal vs power user detection with caching
No Data Leakage: Users only see their own tickets and permitted CIs
Encrypted Storage: Application token encrypted with Nextcloud ICrypto
Audit Trail: All API calls logged with user context

📦 Installation

Prerequisites

Nextcloud: 30.0 or higher
iTop Server: 3.0+ with REST API enabled
PHP: 8.1 or higher
Optional: iTop Portal Personal Tokens Extension (for Portal user support)

Quick Setup

Step 1: Install the App

# Place in apps directory
cd /path/to/nextcloud/apps
git clone https://github.com/lexioj/integration_itop.git
cd integration_itop

# Install dependencies and build
composer install --no-dev
npm install
npm run build

# Enable the app
sudo -u www-data php /path/to/nextcloud/occ app:enable integration_itop

Step 2: Admin Configuration

Navigate to Settings → Administration → iTop Integration
Create Application Token in iTop:
- Login as Administrator
- Go to Admin Tools → User Accounts → + New... → Application Token
- Configure:
  - Person: Select admin user
  - Profiles: ✅ Administrator + ✅ REST Services User
  - Remote Application: "Nextcloud Integration"
  - Scope: ✅ REST/JSON
- Save and copy the generated token (shown only once!)
Configure in Nextcloud:
- iTop Server URL: https://itop.company.com
- Application Token: Paste the token from step 2
- User-Facing Name: Customize display name (default: "iTop")
- Click Test Connection to verify
Configure CI Classes (optional):
- Enable/disable specific CI classes
- Set access levels (disabled/forced/user_choice)
Tune Performance (optional):
- Adjust cache TTLs based on your environment
- Default values work for most deployments

Step 3: User Setup

Each user must create a personal token for identity verification:

For Portal Users (requires Portal Personal Tokens Extension):

Login to iTop Portal
Go to My Profile → Personal Tokens
Create token with REST/JSON scope
Copy token immediately

For Regular Users:

Login to iTop
Go to My Account → Personal Tokens
Create token:
- Scope: ✅ REST/JSON
- Expiration: Never or set expiration
Copy token immediately

In Nextcloud:

Go to Settings → Personal → iTop Integration
Paste your personal token
Click Save - token validates your identity and is discarded
View your dashboard with real-time status

🏗️ Technical Architecture

Core Components

lib/
├── AppInfo/
│   └── Application.php              # App bootstrap, CI class configuration
├── Controller/
│   ├── ConfigController.php         # Settings, validation, cache management
│   └── ItopAPIController.php        # REST endpoints for tickets/CIs
├── Service/
│   ├── ItopAPIService.php           # Core iTop REST API integration
│   ├── ProfileService.php           # Portal vs power user detection (cached)
│   ├── PreviewMapper.php            # Transform iTop objects → preview DTOs
│   └── CacheService.php             # Distributed caching layer
├── Reference/
│   └── ItopReferenceProvider.php    # Rich link previews (tickets + CIs)
├── Search/
│   └── ItopSearchProvider.php       # Unified search (tickets + CIs)
├── Dashboard/
│   └── ItopWidget.php               # Dashboard widget
├── Settings/
│   ├── Admin.php                    # Admin configuration panel
│   └── Personal.php                 # User settings interface
└── Notification/
    └── Notifier.php                 # Notification system

src/
└── views/
    └── ReferenceItopWidget.vue      # Rich preview Vue component

API Integration

REST API Version: 1.3+
Authentication: Token-based (Auth-Token header)
Query Method: POST with form-encoded JSON data
Response Format: JSON with object arrays
Security: All queries filtered by Person ID
Caching: Multi-layer with configurable TTLs

Supported iTop Objects

Tickets: UserRequest, Incident
Configuration Items: PC, Phone, IPPhone, MobilePhone, Tablet, Printer, Peripheral, PCSoftware, OtherSoftware, WebApplication, Software
Persons: User profile information
Organizations: Company/department info

🌍 Internationalization (l10n)

280 translatable strings across the entire application:

Supported Languages

English (en) - Base language
German Informal (de) - Du-form for casual environments
German Formal (de_DE) - Sie-form for professional environments
French (fr) - Formal vous-form

Translation Coverage

Admin settings (all labels, hints, errors)
Personal settings (status messages, forms)
Search results and previews
Error messages and validation
Cache settings and CI classes
Time formats and relative dates

Contributing Translations

See docs/l10n.md for translation guidelines and process.

🔧 Performance Tuning

Cache Configuration

Adjust cache TTLs in Admin Settings → Cache & Performance:

Development/Testing (frequent changes):

CI Preview: 10s
Search Results: 10s
Profile Cache: 60s

Production (stable) (balance):

CI Preview: 60s (default)
Search Results: 30s (default)
Profile Cache: 30min (default)

High-Traffic (performance priority):

CI Preview: 1h
Search Results: 5min
Profile Cache: 1h

Shared CMDB (freshness priority):

CI Preview: 10s
Search Results: 10s
Profile Cache: 5min

Recommended Settings

Small Deployments (<100 users): Use defaults
Medium Deployments (100-1000 users): Increase CI/Profile cache to 5-15min
Large Deployments (>1000 users): Max out cache TTLs, use dedicated Redis

📋 What's New in v1.2.0

Major New Feature: Dual Dashboard 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)

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

Previous Release: v1.1.0 - Configuration Item (CI) Browsing

Highlights:

CI Support in Search, Smart Picker, and Rich Previews (11 CI classes)
Profile Service with automatic Portal vs Power user detection
Admin CI Configuration with 3-state control
Multi-language support: French, German (Du/Sie)
60-80% reduction in API calls with multi-layer caching

See CHANGELOG.md for complete details.

🆘 Support & Troubleshooting

Common Issues

Connection failed

✅ Verify iTop server URL is correct and accessible
✅ Check application token has Administrator + REST Services User profiles
✅ Ensure iTop REST API is enabled (allow_rest_services_via_tokens)

User not configured

✅ Create personal token with REST/JSON scope
✅ Verify token was saved successfully in personal settings
✅ Check Nextcloud logs for validation errors

Search not working

✅ Ensure person_id is configured (check personal settings)
✅ Verify search is enabled in personal settings
✅ Check CI classes are enabled in admin settings

Links not previewing

✅ Clear browser cache and Nextcloud cache
✅ Verify URL matches iTop instance configured
✅ Check if user has permission to view the ticket/CI

Portal users can't see CIs

✅ Portal users only see CIs where they are listed as contacts
✅ Verify contact assignments in iTop
✅ Check ProfileService cache hasn't expired

Debugging

# Check Nextcloud logs
tail -f /path/to/nextcloud/data/nextcloud.log | grep itop

# Clear application cache
sudo -u www-data php occ config:app:delete integration_itop cache_ttl_ci_preview

# Test iTop API connectivity
curl -X POST https://itop.company.com/webservices/rest.php \
  -H "Auth-Token: YOUR_TOKEN" \
  -d "json_data={\"operation\":\"list_operations\"}"

Getting Help

📖 Documentation: docs/
🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: See CONTRIBUTING.md

🗺️ Roadmap

v1.2.0 (Released 2025-11-01) ✅

Enhanced Dashboard Widget with charts and filters
Dual dashboard system (Portal + Agent widgets)
SLA tracking and team metrics

v1.3.0 (Next Release)

Advanced search filters (date ranges, custom fields)
Notification system

Future

Ticket creation from Nextcloud
CI relationship browser (dependencies, impacts)
Enhanced notification system with email digest
Additional CI classes (Server, VirtualMachine, Network Device)
API rate limiting improvements
More languages (Spanish, Italian, Dutch, Portuguese)

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/lexioj/integration_itop.git
cd integration_itop

# Install dependencies
composer install
npm install

# Start development build (watch mode)
npm run dev

# Run tests
composer test
npm run test

Translation Contributions

We especially welcome translations! See docs/l10n.md for the complete translation guide.

📄 License

This project is licensed under the AGPL v3 License - see the LICENSE file for details.

🙏 Acknowledgments

Nextcloud Community for the amazing collaboration platform
iTop/Combodo for the powerful ITSM solution
Contributors who helped with translations, testing, and feedback

Transform your ITSM workflow • Made with ❤️ for the Nextcloud and iTop communities

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

iTop Integration for Nextcloud

✨ Why Choose This Integration?

For End Users

For IT Teams

For Administrators

🚀 Key Features

📊 Interactive Dashboard Widgets

🎫 Portal Widget - "iTop"

👨‍💼 Agent Widget - "iTop - Agent Dashboard"

🔗 Dynamic Reference Provider

🔍 Unified Search Integration

🎯 Smart Picker Integration

📊 Configuration Item (CI) Browsing

End User Devices

Software & Applications

⚙️ Personal Settings Dashboard

🛠️ Admin Configuration Panel

🔐 Security Architecture

Dual-Token Approach

Data Isolation

📦 Installation

Prerequisites

Quick Setup

Step 1: Install the App

Step 2: Admin Configuration

Step 3: User Setup

🏗️ Technical Architecture

Core Components

API Integration

Supported iTop Objects

🌍 Internationalization (l10n)

Supported Languages

Translation Coverage

Contributing Translations

🔧 Performance Tuning

Cache Configuration

Recommended Settings

📋 What's New in v1.2.0

Added

Changed

Previous Release: v1.1.0 - Configuration Item (CI) Browsing

🆘 Support & Troubleshooting

Common Issues

Debugging

Getting Help

🗺️ Roadmap

v1.2.0 (Released 2025-11-01) ✅

v1.3.0 (Next Release)

Future

🤝 Contributing

Development Setup

Translation Contributions

📄 License

🙏 Acknowledgments