diff --git a/docs/DATTO_RMM_DEVICE_API.md b/docs/DATTO_RMM_DEVICE_API.md new file mode 100644 index 0000000..0ccb11f --- /dev/null +++ b/docs/DATTO_RMM_DEVICE_API.md @@ -0,0 +1,201 @@ +# Datto RMM Device API Documentation + +## Overview + +This document describes the JSON payload structure returned when requesting an individual device from the Datto RMM API v2. + +## API Endpoint + +``` +GET https://concord-api.centrastage.net/api/v2/devices/{deviceId} +``` + +## Authentication + +The API uses OAuth2 authentication with Bearer tokens. See the main Datto RMM client implementation for authentication details. + +## Response Structure + +The API returns a JSON object with an `item` property containing the device data. + +### Root Response Object + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `item` | object | Yes | The device object | + +### Device Object (`item`) + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `id` | number | Yes | Unique numeric identifier for the device | +| `uid` | string | Yes | Unique string identifier for the device | +| `siteId` | number | Yes | Numeric identifier of the site this device belongs to | +| `siteUid` | string | Yes | String identifier of the site this device belongs to | +| `siteName` | string | Yes | Name of the site this device belongs to | +| `deviceType` | object | Yes | Device type classification (see below) | +| `hostname` | string | Yes | Device hostname | +| `description` | string | Yes | Device description | +| `intIpAddress` | string | Yes | Internal IP address | +| `extIpAddress` | string | Yes | External IP address | +| `macAddresses` | string[] | No | List of MAC addresses associated with the device | +| `domain` | string | Yes | Domain the device belongs to | +| `manufacturer` | string | No | Device manufacturer (e.g., 'Dell', 'HP', 'Lenovo') | +| `model` | string | No | Device model | +| `serialNumber` | string | No | Device serial number | +| `lastSeen` | number | Yes | Timestamp in milliseconds when device was last seen | +| `lastLoggedInUser` | string | No | Username of the last logged in user | +| `lastReboot` | number | No | Timestamp in milliseconds of last reboot | +| `lastAuditDate` | number | No | Timestamp in milliseconds of last audit | +| `creationDate` | number | No | Timestamp in milliseconds when device was created in RMM | +| `online` | boolean | Yes | Whether the device is currently online | +| `suspended` | boolean | Yes | Whether the device is suspended | +| `deleted` | boolean | Yes | Whether the device is marked as deleted | +| `rebootRequired` | boolean | No | Whether a reboot is required | +| `a64Bit` | boolean | No | Whether the device is 64-bit architecture | +| `operatingSystem` | string | Yes | Operating system name and version | +| `cagVersion` | string | No | Version of the Datto RMM agent (CAG) | +| `displayVersion` | string | No | Display version of the operating system | +| `memory` | number | No | Total memory in MB | +| `cpuCores` | number | No | Number of CPU cores | +| `cpuName` | string | No | CPU model name | +| `diskSize` | number | No | Total disk size in GB | +| `antivirus` | object | No | Antivirus information (see below) | +| `patchManagement` | object | No | Patch management information (see below) | +| `softwareStatus` | string | No | Software status | +| `portalUrl` | string | No | URL to the device in the Datto RMM portal | +| `webRemoteUrl` | string | No | URL for web-based remote access | +| `warrantyDate` | string\|null | No | Warranty expiration date | +| `snmpEnabled` | boolean | No | Whether SNMP is enabled on the device | +| `deviceClass` | string | No | Device class classification | +| `udf` | object | No | User-defined fields (custom fields) | + +### Device Type Object + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `category` | string | Yes | Device category (e.g., 'Server', 'Workstation', 'Laptop') | +| `type` | string | Yes | Specific device type | + +### Antivirus Object + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `antivirusProduct` | string | Yes | Name of the antivirus product | +| `antivirusStatus` | string | Yes | Status of the antivirus (e.g., 'Up to date', 'Out of date') | + +### Patch Management Object + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `patchStatus` | string | Yes | Overall patch status | +| `patchesApprovedPending` | number | Yes | Number of approved patches pending installation | +| `patchesNotApproved` | number | Yes | Number of patches not yet approved | +| `patchesInstalled` | number | Yes | Number of patches installed | + +## Example Response + +See `datto-rmm-device-example.json` for a complete example response. + +## TypeScript Type Definition + +The TypeScript interface is defined in `/lib/types/datto-rmm.ts`: + +```typescript +export interface DattoRMMDevice { + id: number; + uid: string; + siteId: number; + siteUid: string; + siteName: string; + deviceType: { + category: string; + type: string; + }; + hostname: string; + description: string; + intIpAddress: string; + extIpAddress: string; + macAddresses?: string[]; + domain: string; + manufacturer?: string; + model?: string; + serialNumber?: string; + lastSeen: number; + lastLoggedInUser?: string; + lastReboot?: number; + lastAuditDate?: number; + creationDate?: number; + online: boolean; + suspended: boolean; + deleted: boolean; + rebootRequired?: boolean; + a64Bit?: boolean; + operatingSystem: string; + cagVersion?: string; + displayVersion?: string; + memory?: number; + cpuCores?: number; + cpuName?: string; + diskSize?: number; + antivirus?: { + antivirusProduct: string; + antivirusStatus: string; + }; + patchManagement?: { + patchStatus: string; + patchesApprovedPending: number; + patchesNotApproved: number; + patchesInstalled: number; + }; + softwareStatus?: string; + portalUrl?: string; + webRemoteUrl?: string; + warrantyDate?: string | null; + snmpEnabled?: boolean; + deviceClass?: string; + udf?: Record; +} +``` + +## Usage in Code + +```typescript +import { DattoRMMClient } from '@/lib/services/datto-rmm-client'; + +const client = new DattoRMMClient({ + apiUrl: 'https://concord-api.centrastage.net/api/v2', + apiKey: 'your-api-key', + apiSecret: 'your-api-secret' +}); + +// Get a single device by ID +const device = await client.getDeviceById('12345678'); + +if (device) { + console.log(`Device: ${device.hostname}`); + console.log(`Online: ${device.online}`); + console.log(`OS: ${device.operatingSystem}`); + console.log(`Memory: ${device.memory} MB`); +} +``` + +## Notes + +- All timestamp fields are in milliseconds (Unix epoch time) +- Optional fields may not be present in the response depending on the device type and available data +- The `udf` (user-defined fields) object can contain any custom fields configured in your Datto RMM instance +- Hardware details like `manufacturer`, `model`, and `serialNumber` may require audit data to be populated +- Use the `getDeviceWithAudit()` method to fetch a device with enhanced hardware information from audit data + +## Related Files + +- **Type Definition**: `/lib/types/datto-rmm.ts` +- **Client Implementation**: `/lib/services/datto-rmm-client.ts` +- **JSON Schema**: `/docs/datto-rmm-device-schema.json` +- **Example Response**: `/docs/datto-rmm-device-example.json` + +## API Reference + +For complete Datto RMM API documentation, visit: +https://help.aem.autotask.net/en/Content/APIs/API-Home.htm diff --git a/docs/datto-rmm-device-example.json b/docs/datto-rmm-device-example.json new file mode 100644 index 0000000..cd4123b --- /dev/null +++ b/docs/datto-rmm-device-example.json @@ -0,0 +1,63 @@ +{ + "item": { + "id": 12345678, + "uid": "abc123def456", + "siteId": 98765, + "siteUid": "site-uid-123", + "siteName": "Acme Corporation", + "deviceType": { + "category": "Workstation", + "type": "Desktop" + }, + "hostname": "DESKTOP-ABC123", + "description": "John Doe's Workstation", + "intIpAddress": "192.168.1.100", + "extIpAddress": "203.0.113.45", + "macAddresses": [ + "00:1A:2B:3C:4D:5E", + "00:1A:2B:3C:4D:5F" + ], + "domain": "acme.local", + "manufacturer": "Dell Inc.", + "model": "OptiPlex 7090", + "serialNumber": "ABC123XYZ789", + "lastSeen": 1701532800000, + "lastLoggedInUser": "jdoe", + "lastReboot": 1701446400000, + "lastAuditDate": 1701518400000, + "creationDate": 1640995200000, + "online": true, + "suspended": false, + "deleted": false, + "rebootRequired": false, + "a64Bit": true, + "operatingSystem": "Windows 11 Pro", + "cagVersion": "2.5.1.123", + "displayVersion": "22H2", + "memory": 16384, + "cpuCores": 8, + "cpuName": "Intel(R) Core(TM) i7-11700 @ 2.50GHz", + "diskSize": 512, + "antivirus": { + "antivirusProduct": "Windows Defender", + "antivirusStatus": "Up to date" + }, + "patchManagement": { + "patchStatus": "Current", + "patchesApprovedPending": 2, + "patchesNotApproved": 5, + "patchesInstalled": 145 + }, + "softwareStatus": "Compliant", + "portalUrl": "https://concord.centrastage.net/csm/device/12345678", + "webRemoteUrl": "https://concord.centrastage.net/remote/12345678", + "warrantyDate": "2026-12-31", + "snmpEnabled": false, + "deviceClass": "Workstation", + "udf": { + "customField1": "Value1", + "customField2": "Value2", + "department": "Engineering" + } + } +} diff --git a/docs/datto-rmm-device-schema.json b/docs/datto-rmm-device-schema.json new file mode 100644 index 0000000..370d085 --- /dev/null +++ b/docs/datto-rmm-device-schema.json @@ -0,0 +1,242 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "Datto RMM Device Response Schema", + "description": "JSON schema for the response when requesting an individual device from Datto RMM API v2", + "type": "object", + "properties": { + "item": { + "type": "object", + "description": "The device object returned by the API", + "properties": { + "id": { + "type": "number", + "description": "Unique numeric identifier for the device" + }, + "uid": { + "type": "string", + "description": "Unique string identifier for the device" + }, + "siteId": { + "type": "number", + "description": "Numeric identifier of the site this device belongs to" + }, + "siteUid": { + "type": "string", + "description": "String identifier of the site this device belongs to" + }, + "siteName": { + "type": "string", + "description": "Name of the site this device belongs to" + }, + "deviceType": { + "type": "object", + "description": "Device type classification", + "properties": { + "category": { + "type": "string", + "description": "Device category (e.g., 'Server', 'Workstation', 'Laptop')" + }, + "type": { + "type": "string", + "description": "Specific device type" + } + }, + "required": ["category", "type"] + }, + "hostname": { + "type": "string", + "description": "Device hostname" + }, + "description": { + "type": "string", + "description": "Device description" + }, + "intIpAddress": { + "type": "string", + "description": "Internal IP address" + }, + "extIpAddress": { + "type": "string", + "description": "External IP address" + }, + "macAddresses": { + "type": "array", + "description": "List of MAC addresses associated with the device", + "items": { + "type": "string" + } + }, + "domain": { + "type": "string", + "description": "Domain the device belongs to" + }, + "manufacturer": { + "type": "string", + "description": "Device manufacturer (e.g., 'Dell', 'HP', 'Lenovo')" + }, + "model": { + "type": "string", + "description": "Device model" + }, + "serialNumber": { + "type": "string", + "description": "Device serial number" + }, + "lastSeen": { + "type": "number", + "description": "Timestamp in milliseconds when device was last seen" + }, + "lastLoggedInUser": { + "type": "string", + "description": "Username of the last logged in user" + }, + "lastReboot": { + "type": "number", + "description": "Timestamp in milliseconds of last reboot" + }, + "lastAuditDate": { + "type": "number", + "description": "Timestamp in milliseconds of last audit" + }, + "creationDate": { + "type": "number", + "description": "Timestamp in milliseconds when device was created in RMM" + }, + "online": { + "type": "boolean", + "description": "Whether the device is currently online" + }, + "suspended": { + "type": "boolean", + "description": "Whether the device is suspended" + }, + "deleted": { + "type": "boolean", + "description": "Whether the device is marked as deleted" + }, + "rebootRequired": { + "type": "boolean", + "description": "Whether a reboot is required" + }, + "a64Bit": { + "type": "boolean", + "description": "Whether the device is 64-bit architecture" + }, + "operatingSystem": { + "type": "string", + "description": "Operating system name and version" + }, + "cagVersion": { + "type": "string", + "description": "Version of the Datto RMM agent (CAG)" + }, + "displayVersion": { + "type": "string", + "description": "Display version of the operating system" + }, + "memory": { + "type": "number", + "description": "Total memory in MB" + }, + "cpuCores": { + "type": "number", + "description": "Number of CPU cores" + }, + "cpuName": { + "type": "string", + "description": "CPU model name" + }, + "diskSize": { + "type": "number", + "description": "Total disk size in GB" + }, + "antivirus": { + "type": "object", + "description": "Antivirus information", + "properties": { + "antivirusProduct": { + "type": "string", + "description": "Name of the antivirus product" + }, + "antivirusStatus": { + "type": "string", + "description": "Status of the antivirus (e.g., 'Up to date', 'Out of date')" + } + }, + "required": ["antivirusProduct", "antivirusStatus"] + }, + "patchManagement": { + "type": "object", + "description": "Patch management information", + "properties": { + "patchStatus": { + "type": "string", + "description": "Overall patch status" + }, + "patchesApprovedPending": { + "type": "number", + "description": "Number of approved patches pending installation" + }, + "patchesNotApproved": { + "type": "number", + "description": "Number of patches not yet approved" + }, + "patchesInstalled": { + "type": "number", + "description": "Number of patches installed" + } + }, + "required": ["patchStatus", "patchesApprovedPending", "patchesNotApproved", "patchesInstalled"] + }, + "softwareStatus": { + "type": "string", + "description": "Software status" + }, + "portalUrl": { + "type": "string", + "description": "URL to the device in the Datto RMM portal" + }, + "webRemoteUrl": { + "type": "string", + "description": "URL for web-based remote access" + }, + "warrantyDate": { + "type": ["string", "null"], + "description": "Warranty expiration date" + }, + "snmpEnabled": { + "type": "boolean", + "description": "Whether SNMP is enabled on the device" + }, + "deviceClass": { + "type": "string", + "description": "Device class classification" + }, + "udf": { + "type": "object", + "description": "User-defined fields (custom fields)", + "additionalProperties": true + } + }, + "required": [ + "id", + "uid", + "siteId", + "siteUid", + "siteName", + "deviceType", + "hostname", + "description", + "intIpAddress", + "extIpAddress", + "domain", + "lastSeen", + "online", + "suspended", + "deleted", + "operatingSystem" + ] + } + }, + "required": ["item"] +}