n8n-nodes-ninjaone

Professional NinjaOne RMM integration for n8n with complete ticketing and device management capabilities.

This community node provides comprehensive integration with the NinjaOne Remote Monitoring and Management (RMM) platform, enabling automated workflows for IT service management, device monitoring, and helpdesk operations through n8n.

Installation

Follow the community node installation guide and install the package:

npm install @ev1lc0rp/n8n-nodes-ninjaone

Current Status

✅ Working Features:

• Complete OAuth2 Client Credentials authentication with regional endpoint support
• Full CRUD ticket operations with real API field mapping based on production data
• Comprehensive device management operations (get, list, activities, alerts, custom fields, etc.)
• Document template lifecycle management: list, create, update, archive/restore (single & bulk)
• All ticketing workflows: Create, Read, Update, Comment with proper field validation
• Severity levels: NONE, MINOR, MODERATE, MAJOR, CRITICAL (matches production API)
• Status management: New (1000), Open (2000), Waiting for Customer (3000), Hold (4000)
• Ticket types: PROBLEM, TASK, QUESTION support
• Time tracking and organization assignment capabilities
• Board-based ticket listing with proper POST method implementation

🚧 In Development:

• Advanced device patch management operations
• Webhook management enhancements
• Knowledge base article management
• Organization document workflows
• Asset tag management system

❌ Known Issues:

• None currently identified - all implemented features are production-ready

📋 Roadmap:

• Backup job operations and monitoring
• Advanced reporting and analytics endpoints
• Checklist template management
• Vulnerability management integration

Pending API Method Coverage Tasks

The following tasks track every documented API method that is not yet surfaced by the node. Update the corresponding test suites when implementing each item.

Ticketing Endpoints

• [ ] Expose GET /v2/ticketing/ticket/{ticketId}/log-entry for ticket history retrieval and add matching Jest coverage.
• [ ] Expose GET /v2/ticketing/attributes to surface ticket attribute metadata with schema tests.
• [ ] Add contact directory operation for GET /v2/ticketing/contact/contacts with pagination tests.
• [ ] Support GET /v2/ticketing/ticket-form/{id} for single ticket form lookups and validate required parameters in tests.
• [ ] Support GET /v2/ticketing/ticket-form for listing ticket forms with coverage mirroring board listing tests.
• [ ] Add reference data operation for GET /v2/ticketing/statuses with enumeration validation tests.
• [ ] Surface technician lookup via GET /v2/ticketing/app-user-contact and assert query parameter mapping in tests.

Policy Condition Endpoints

• [ ] Implement custom-field condition CRUD (GET/POST/PUT/DELETE under /v2/policies/{policy_id}/condition) with dedicated tests.
• [ ] Implement Windows-event condition CRUD (GET/POST/DELETE) with payload validation tests.
• [ ] Add policy listing support for GET /v2/policies and cover pagination in tests.

Device Control Endpoints

• [ ] Implement maintenance mode controls at /v2/device/{id}/maintenance (start/stop + status retrieval) with enum validation tests.
• [ ] Add Windows service control at /v2/device/{id}/windows-service/{serviceId}/control and configuration updates at /configure, both with action-mapping tests.
• [ ] Surface device reboot support via POST /v2/device/{id}/reboot/{mode} and test mode validation.
• [ ] Implement script execution (POST /v2/device/{id}/script/run) including payload and response tests.
• [ ] Support device owner management (POST/DELETE under /v2/device/{id}/owner) with ownership assignment tests.
• [ ] Add OS and software patch apply/scan endpoints with concurrency and scheduling tests.
• [ ] Expose GET /v2/device/{id}/dashboard-url and assert URL handling in tests.
• [ ] Cover device approval endpoints under /v2/devices/approval/{mode} once requirements are confirmed.

Organization Lifecycle & Installer Endpoints

• [ ] Add location listing via GET /v2/organization/{id}/locations with pagination coverage.
• [ ] Implement installer generation and retrieval endpoints (/generate-installer, /installer/{installer_type}) including binary response tests.
• [ ] Support organization updates and deletion (PUT/DELETE /v2/organization/{id}) with partial update tests.
• [ ] Implement archive/restore flows (POST /v2/organization/archive and /restore) with lifecycle tests.

Checklist Template Endpoints

• [ ] Implement checklist template CRUD and bulk operations (archive, create, update, delete, restore) with data-driven Jest tests.

Document Template Endpoints

• [ ] Implement document template CRUD and lifecycle operations (archive, restore, delete) with request/response coverage.

Tagging and Vulnerability Endpoints

• [ ] Surface vulnerability scan group endpoints (/v2/vulnerability/scan-groups and related routes) with upload/list tests.
• [ ] Implement tag CRUD and merge operations under /v2/tag with tests verifying asset associations.
• [ ] Add organization checklist promotion endpoints with workflow coverage.

Authentication

The NinjaOne API uses OAuth 2.0 Client Credentials Flow for secure server-to-server communication. This is the recommended authentication method for all API operations.

Setup Instructions

1. Create NinjaOne OAuth2 API Credentials in n8n:

   • Go to Credentials in n8n
   • Add NinjaOne OAuth2 API credential type
   • Configure your NinjaOne application credentials

2. Regional Endpoint Configuration:

   • Base URL: Set to your regional endpoint (e.g., https://api.ninjaone.com)
   • Client ID: Your NinjaOne application client ID
   • Client Secret: Your NinjaOne application client secret
   • Scope: monitoring management offline_access (required for full API access and refresh tokens)

3. Obtain Application Credentials:

   • Log in to your NinjaOne account
   • Navigate to Administration > API
   • Click Add New Application
   • Enable refresh tokens (Refresh Token grant) for longer-lived sessions
   • Configure required permissions for your use case
   • Copy the Client ID and Client Secret to n8n

Ticket Management

Complete CRUD Operations

Create Tickets

{
  "clientId": 1,
  "ticketFormId": 1,
  "summary": "Server maintenance required",
  "description": "Scheduled maintenance for production server",
  "severity": "MODERATE",
  "priority": "HIGH",
  "type": "TASK",
  "status": "1000"
}

Update Tickets

Full field support including:

• Summary, status, severity, priority, type
• Organization assignment and time tracking
• CC lists (UIDs and email addresses)
• Tags, attributes, and custom fields
• Parent ticket relationships for sub-tickets

Comment System

• Add public/private comments to tickets
• Time tracking integration for billable hours
• Support for HTML formatted content

Board-Based Listing

• Retrieve tickets by ticketing board ID
• Pagination and filtering support
• Sorting and search capabilities
• Custom column selection

Field Mapping Accuracy

All ticket operations use field mappings verified against real NinjaOne API responses:

• Severity Levels: NONE, MINOR, MODERATE, MAJOR, CRITICAL
• Status IDs: 1000 (New), 2000 (Open), 3000 (Waiting for Customer), 4000 (Hold)
• Ticket Types: PROBLEM, TASK, QUESTION
• Summary Field: Uses 'summary' (not 'subject') to match API response structure
• Organization Assignment: Department/team assignment support
• Time Tracking: Seconds-based time tracking for accurate billing

Device Management

Available Operations

• Get Device – Retrieve detailed device information by ID
• List Devices – Get all devices with filtering and pagination
• Device Activities – Monitor device activity logs and events
• Device Alerts – Access critical alerts and notifications
• Custom Fields – Read and update device custom field data
• Hardware Inventory – Disks, processors, network interfaces, volumes
• Software Management – Installed software, patches, and updates
• System Information – OS details, Windows services, last logged user
• Policy Management – Policy overrides and compliance status

Document Template Management

• List Templates – Query /v2/document-templates with field selection, pagination, and archived filters.
• Create & Update – Send complete template payloads to /v2/document-templates and /v2/document-templates/{id}.
• Archive & Restore – Toggle template availability individually or in bulk via the archive/restore endpoints.
• Delete Templates – Remove unused templates with DELETE /v2/document-templates/{id} when they are no longer needed.

API Coverage

Implemented Endpoints

Ticketing Operations:

• POST /v2/ticketing/ticket - Create tickets
• GET /v2/ticketing/ticket/{id} - Get ticket details
• PUT /v2/ticketing/ticket/{id} - Update tickets
• POST /v2/ticketing/ticket/{id}/comment - Add comments
• GET /v2/ticketing/trigger/boards - List ticketing boards
• POST /v2/ticketing/trigger/board/{id}/run - Get tickets by board

Device Operations:

• GET /v2/device/{id} - Device details
• GET /v2/devices - List devices
• GET /v2/device/{id}/activities - Device activities
• GET /v2/device/{id}/alerts - Device alerts
• Plus 15+ additional device management endpoints

Document Template Operations:

• GET /v2/document-templates - List templates with field selection
• POST /v2/document-templates - Create template
• GET /v2/document-templates/{id} - Retrieve template details
• PUT /v2/document-templates/{id} - Update template
• DELETE /v2/document-templates/{id} - Delete template
• POST /v2/document-templates/{id}/archive - Archive template
• POST /v2/document-templates/{id}/restore - Restore template
• POST /v2/document-templates/archive - Archive multiple templates
• POST /v2/document-templates/restore - Restore multiple templates

Regional Endpoint Support

The integration supports all NinjaOne regional deployments:

• North America: https://api.ninjaone.com
• Europe: https://eu-api.ninjaone.com
• Other regions: Configure your specific regional endpoint

Usage Examples

Basic Ticket Workflow

1. List Ticketing Boards to identify available boards
2. Get Tickets by Board to retrieve current tickets
3. Create Ticket for new issues or tasks
4. Update Ticket to modify status, priority, or assignment
5. Add Comments for progress updates and communication

Device Monitoring Workflow

1. List Devices to get inventory overview
2. Get Device Alerts to identify issues requiring attention
3. Get Device Activities to review recent events
4. Create Tickets automatically for critical alerts
5. Update Custom Fields to track remediation status

Documentation

• API Reference: docs/api-reference/ - Complete NinjaOne API documentation
• Usage Examples: docs/examples/ - Real-world implementation examples
• Development Guide: docs/development/ - Development and contribution guidelines

Troubleshooting

400 Bad Request : Verify all required fields are provided for the operation. Check that the Base URL matches your regional endpoint and doesn't contain trailing slashes.

401 Unauthorized
: Confirm OAuth2 credentials are correct and have appropriate scopes. Verify the Client Credentials Flow is configured properly.

405 Method Not Allowed : Ensure you're using the latest version - older versions had incorrect HTTP methods for some operations.

TLS/SSL Errors : Verify the Base URL uses https and matches your actual NinjaOne regional domain. Check network connectivity and proxy settings.

Version History

Version 0.3.0 - Current Release

Major Enhancements:

• Complete ticket field mapping overhaul based on production API data
• Enhanced Create and Update operations with all available fields
• Fixed Get Tickets by Board operation (GET → POST method)
• Added comprehensive Comment operations with time tracking
• Updated severity levels to match real API: MINOR, MODERATE, MAJOR
• Implemented proper status ID mapping for accurate state management
• Repository reorganization and professional documentation structure

Technical Improvements:

• All field names match actual API responses ('summary' vs 'subject')
• TypeScript compilation and ESLint compliance maintained
• Comprehensive testing against live NinjaOne API endpoints
• Optimized icon and branding throughout the package

Contributing

This project follows standard n8n community node development practices. See docs/development/ for detailed contribution guidelines.

License

MIT License - see LICENSE.md for details.

Support

• GitHub Issues: Report bugs and request features
• n8n Community: Get help from the community
• NinjaOne API Documentation: Official API reference

Professional NinjaOne integration for n8n - Automate your IT service management workflows with confidence.