# 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](https://docs.n8n.io/integrations/community-nodes/installation/) and install the package:

```bash
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.)
- 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. Note: if you upgraded from a version that defaulted the Base URL to `api.ninjaone.com`, update your credential to your real regional host (see Authentication).

📋 **Roadmap:**
- Backup job operations and monitoring
- Advanced reporting and analytics endpoints
- Checklist template management
- Document template operations
- 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. **Which flow you need depends on what you want to do:**

| Grant Type | NinjaOne app type | Can do | Cannot do |
| --- | --- | --- | --- |
| **Authorization Code** (default) | "Web" | Everything, **including create/update tickets and add comments** | — |
| **Client Credentials** | "API Services (machine-to-machine)" | Read/monitoring, device management | ❌ Ticket writes (API returns **HTTP 405**) |

> ⚠️ **Ticket Create/Update/Comment require the Authorization Code flow.** NinjaOne rejects these write operations with `405 Method Not Allowed` when you authenticate with Client Credentials. If you only read data or manage devices, Client Credentials is fine.

### Setup Instructions

1. **Create NinjaOne OAuth2 API Credentials** in n8n:
   - Go to **Credentials** in n8n
   - Add **NinjaOne OAuth2 API** credential type
   - Choose the **Grant Type** that matches your use case (Authorization Code for ticketing)
   - For the Authorization Code flow, register a **Web** app in NinjaOne and set its **Redirect URI** to `<YOUR_N8N_URL>/rest/oauth2-credential/callback`, then click **Connect** in n8n to authorize

2. **Regional Endpoint Configuration**:
   - **Base URL**: The host you use to log in to NinjaOne, with no trailing slash. The API and OAuth token endpoint share this host.
     - North America: `https://app.ninjaone.com` (or `https://us2.ninjaone.com`)
     - Europe: `https://eu.ninjaone.com`
     - Oceania: `https://oc.ninjaone.com`
     - Canada: `https://ca.ninjaone.com`
   - **Access Token URL**: `<Base URL>/ws/oauth/token` — must be on the **same host** as the Base URL (e.g. `https://eu.ninjaone.com/ws/oauth/token`).
   - **Client ID**: Your NinjaOne application client ID
   - **Client Secret**: Your NinjaOne application client secret
   - **Scope**: `monitoring management` (required for full API access)

   > ⚠️ There is no `api.ninjaone.com` host. Earlier versions defaulted to that, which caused every request (including ticket updates) to fail. Make sure the Base URL matches your dashboard host.

3. **Obtain Application Credentials**:
   - Log in to your NinjaOne account
   - Navigate to **Administration > Apps > API > Client App IDs**
   - Click **Add** and choose **API Services (machine-to-machine)**
   - Select the scopes you need and enable the **Client Credentials** grant type
   - Copy the Client ID and Client Secret to n8n
   - Use the **Test** button on the credential to confirm authentication works

## Ticket Management

### Complete CRUD Operations

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

#### Update Tickets
Updates are **partial** — only the fields you add under **Update Fields** are sent, so existing ticket data is never overwritten with defaults. Supported fields include:
- 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
- Version (optional, for instances that enforce optimistic locking — supply the value from a prior **Get**)

#### 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

## 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

### Regional Endpoint Support

The integration supports all NinjaOne regional deployments. Set the **Base URL** to the host you log in with:
- North America: `https://app.ninjaone.com` (or `https://us2.ninjaone.com`)
- Europe: `https://eu.ninjaone.com`
- Oceania: `https://oc.ninjaone.com`
- Canada: `https://ca.ninjaone.com`

The OAuth token endpoint must be on the same host (`<Base URL>/ws/oauth/token`).

## 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/](docs/api-reference/) - Complete NinjaOne API documentation
- **Usage Examples**: [docs/examples/](docs/examples/) - Real-world implementation examples  
- **Development Guide**: [docs/development/](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. Make sure the **Base URL** and **Access Token URL** are on the same regional host. Use the credential **Test** button to verify the Client Credentials flow before running the node.

**405 Method Not Allowed**
: Most commonly seen on **ticket Create/Update/Comment** — these require the **Authorization Code** grant type. NinjaOne rejects ticket writes made with Client Credentials. Switch your credential's Grant Type to Authorization Code (using a NinjaOne "Web" app) and reconnect. Also ensure you're on the latest version, which fixed 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/](docs/development/) for detailed contribution guidelines.

## License

MIT License - see [LICENSE.md](LICENSE.md) for details.

## Support

- **GitHub Issues**: [Report bugs and request features](https://github.com/ai-Ev1lC0rP/n8n-nodes-ninjaone/issues)
- **n8n Community**: [Get help from the community](https://community.n8n.io/)
- **NinjaOne API Documentation**: [Official API reference](https://resources.ninjarmm.com)

---

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