ConnectWise Automate Computer Management

Overview

Computers are the core managed entities in ConnectWise Automate. Each computer represents an endpoint with the Automate agent installed - workstations, servers, or network devices. This skill covers computer identification, status monitoring, inventory, patch management, and antivirus status.

Key Concepts

Computer Identifiers

Every computer has multiple identifiers:

Computer Status Values

Operating System Types

Field Reference

Core Computer Fields

interface Computer {
  // Identifiers
  ComputerID: number;           // Primary key
  Name: string;                 // Hostname
  ComputerGUID: string;         // GUID

  // Client/Location Association
  ClientID: number;             // Parent client ID
  LocationID: number;           // Location within client
  Client: {
    Name: string;               // Client name
  };
  Location: {
    Name: string;               // Location name
  };

  // Status
  Status: string;               // Online, Offline, Degraded
  LastContact: string;          // ISO datetime of last check-in
  Uptime: number;               // Uptime in seconds

  // Network
  IPAddress: string;            // Internal IP
  ExternalIP: string;           // External/public IP
  DefaultGateway: string;       // Gateway IP
  MAC: string;                  // Primary MAC address

  // Operating System
  OS: string;                   // "Windows 10 Pro"
  OSType: string;               // "Windows", "macOS", "Linux"
  OSVersion: string;            // "10.0.19045"
  SerialNumber: string;         // OS serial/product key

  // Hardware
  Manufacturer: string;         // "Dell Inc."
  Model: string;                // "OptiPlex 7090"
  TotalMemory: number;          // RAM in MB
  ProcessorName: string;        // CPU model
  ProcessorCount: number;       // Number of CPUs

  // Agent
  AgentVersion: string;         // "2023.1.0.123"
  RemoteAgentVersion: string;   // Remote agent version

  // Timestamps
  DateAdded: string;            // When computer was added
  LastInventory: string;        // Last inventory scan
  LastPatched: string;          // Last patch operation

  // Extra Data Fields (EDFs)
  ExtraData: {
    [key: string]: string;      // Custom fields
  };
}

Computer Inventory Fields

interface ComputerInventory {
  // Disk Information
  Drives: DriveInfo[];

  // Software
  Software: SoftwareItem[];

  // Hardware
  Memory: MemoryModule[];
  NetworkAdapters: NetworkAdapter[];
  Printers: Printer[];

  // Services
  Services: Service[];

  // Monitors/Displays
  Monitors: Monitor[];
}

interface DriveInfo {
  Letter: string;               // "C:"
  Type: string;                 // "Fixed", "Network", "Removable"
  FileSystem: string;           // "NTFS"
  TotalSize: number;            // Size in MB
  FreeSpace: number;            // Free space in MB
  PercentFree: number;          // Percentage free
}

interface SoftwareItem {
  Name: string;                 // Application name
  Publisher: string;            // Software publisher
  Version: string;              // Installed version
  InstallDate: string;          // When installed
}

API Patterns

List All Computers

GET /cwa/api/v1/Computers?pageSize=250
Authorization: Bearer {token}

Response:

[
  {
    "ComputerID": 12345,
    "Name": "ACME-DC01",
    "ClientID": 100,
    "LocationID": 1,
    "Status": "Online",
    "IPAddress": "192.168.1.10",
    "OS": "Windows Server 2022 Standard",
    "LastContact": "2024-02-15T10:30:00Z",
    "Client": {
      "Name": "Acme Corporation"
    },
    "Location": {
      "Name": "Main Office"
    }
  }
]

Get Single Computer

GET /cwa/api/v1/Computers/{computerID}
Authorization: Bearer {token}

Response:

{
  "ComputerID": 12345,
  "Name": "ACME-DC01",
  "ComputerGUID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "ClientID": 100,
  "LocationID": 1,
  "Status": "Online",
  "IPAddress": "192.168.1.10",
  "ExternalIP": "203.0.113.50",
  "MAC": "00:1A:2B:3C:4D:5E",
  "OS": "Windows Server 2022 Standard",
  "OSVersion": "10.0.20348",
  "Manufacturer": "Dell Inc.",
  "Model": "PowerEdge R640",
  "SerialNumber": "ABC1234567",
  "TotalMemory": 32768,
  "ProcessorName": "Intel Xeon Gold 6230",
  "AgentVersion": "2023.1.0.123",
  "LastContact": "2024-02-15T10:30:00Z",
  "Uptime": 864000,
  "DateAdded": "2023-01-15T08:00:00Z"
}

Filter Computers by Client

GET /cwa/api/v1/Computers?condition=ClientID = 100&pageSize=250
Authorization: Bearer {token}

Filter Computers by Status

GET /cwa/api/v1/Computers?condition=Status = 'Online'&pageSize=250
Authorization: Bearer {token}

Filter by OS Type

GET /cwa/api/v1/Computers?condition=OS contains 'Windows Server'&pageSize=250
Authorization: Bearer {token}

Get Computer Drives

GET /cwa/api/v1/Computers/{computerID}/Drives
Authorization: Bearer {token}

Response:

[
  {
    "DriveID": 1,
    "Letter": "C:",
    "Type": "Fixed",
    "FileSystem": "NTFS",
    "TotalSize": 500000,
    "FreeSpace": 150000,
    "PercentFree": 30
  }
]

Get Computer Software

GET /cwa/api/v1/Computers/{computerID}/Software
Authorization: Bearer {token}

Get Patch Status

GET /cwa/api/v1/Computers/{computerID}/Patches
Authorization: Bearer {token}

Response:

{
  "Installed": 145,
  "Missing": 3,
  "Pending": 2,
  "Failed": 0,
  "Patches": [
    {
      "KBID": "KB5034441",
      "Title": "2024-01 Security Update",
      "Status": "Missing",
      "Severity": "Critical",
      "ReleaseDate": "2024-01-09T00:00:00Z"
    }
  ]
}

Get Antivirus Status

GET /cwa/api/v1/Computers/{computerID}/Antivirus
Authorization: Bearer {token}

Response:

{
  "Product": "Windows Defender",
  "Version": "4.18.2401.7",
  "DefinitionVersion": "1.405.123.0",
  "DefinitionDate": "2024-02-15T00:00:00Z",
  "RealTimeProtection": true,
  "LastScan": "2024-02-15T03:00:00Z",
  "ScanType": "Quick",
  "ThreatsFound": 0
}

Workflows

Computer Lookup by Hostname

async function findComputerByHostname(client, hostname) {
  const computers = await client.request(
    `/Computers?condition=Name contains '${hostname}'&pageSize=100`
  );

  if (computers.length === 0) {
    return { found: false, suggestions: [] };
  }

  if (computers.length === 1) {
    return { found: true, computer: computers[0] };
  }

  return {
    found: false,
    ambiguous: true,
    suggestions: computers.map(c => ({
      name: c.Name,
      id: c.ComputerID,
      client: c.Client?.Name,
      status: c.Status
    }))
  };
}

Computer Lookup by IP Address

async function findComputerByIP(client, ipAddress) {
  const computers = await client.request(
    `/Computers?condition=IPAddress = '${ipAddress}' or ExternalIP = '${ipAddress}'`
  );

  return computers[0] || null;
}

Offline Computer Report

async function getOfflineComputers(client, options = {}) {
  const { clientId, offlineMinutes = 30 } = options;

  let condition = "Status = 'Offline'";
  if (clientId) {
    condition += ` and ClientID = ${clientId}`;
  }

  const computers = await client.request(
    `/Computers?condition=${encodeURIComponent(condition)}&pageSize=500`
  );

  const now = new Date();

  return computers.map(computer => ({
    name: computer.Name,
    id: computer.ComputerID,
    client: computer.Client?.Name,
    location: computer.Location?.Name,
    lastContact: computer.LastContact,
    offlineMinutes: Math.floor(
      (now - new Date(computer.LastContact)) / 60000
    )
  }));
}

Disk Space Report

async function getLowDiskSpaceComputers(client, threshold = 10) {
  // Get all computers
  const computers = await client.request('/Computers?pageSize=500');
  const lowDiskComputers = [];

  for (const computer of computers) {
    const drives = await client.request(
      `/Computers/${computer.ComputerID}/Drives`
    );

    const lowDrives = drives.filter(d =>
      d.Type === 'Fixed' && d.PercentFree < threshold
    );

    if (lowDrives.length > 0) {
      lowDiskComputers.push({
        computer: computer.Name,
        client: computer.Client?.Name,
        drives: lowDrives.map(d => ({
          letter: d.Letter,
          percentFree: d.PercentFree,
          freeGB: Math.round(d.FreeSpace / 1024)
        }))
      });
    }

    // Respect rate limits
    await sleep(100);
  }

  return lowDiskComputers;
}

Patch Compliance Report

async function getPatchComplianceReport(client, clientId) {
  let condition = '';
  if (clientId) {
    condition = `?condition=ClientID = ${clientId}`;
  }

  const computers = await client.request(`/Computers${condition}&pageSize=500`);
  const report = {
    total: computers.length,
    compliant: 0,
    nonCompliant: 0,
    computers: []
  };

  for (const computer of computers) {
    const patches = await client.request(
      `/Computers/${computer.ComputerID}/Patches`
    );

    const isCompliant = patches.Missing === 0 && patches.Failed === 0;

    if (isCompliant) {
      report.compliant++;
    } else {
      report.nonCompliant++;
      report.computers.push({
        name: computer.Name,
        missing: patches.Missing,
        failed: patches.Failed
      });
    }

    await sleep(100);
  }

  return report;
}

Error Handling

Common Computer API Errors

Error Response Example

{
  "error": {
    "code": "NotFound",
    "message": "Computer with ID 99999 not found"
  }
}

Computer Validation

function validateComputerQuery(params) {
  const errors = [];

  if (params.condition) {
    // Validate OData operators
    const validOperators = ['=', '!=', '<', '>', '<=', '>=', 'contains', 'startswith'];
    const hasValidOperator = validOperators.some(op =>
      params.condition.includes(op)
    );

    if (!hasValidOperator) {
      errors.push('Invalid condition operator');
    }
  }

  if (params.pageSize && (params.pageSize < 1 || params.pageSize > 1000)) {
    errors.push('pageSize must be between 1 and 1000');
  }

  return {
    valid: errors.length === 0,
    errors
  };
}

Best Practices

1. Use ComputerID for specific lookups - Faster than hostname searches
2. Filter by ClientID when possible - Reduces data transfer
3. Implement pagination - Always handle multiple pages
4. Monitor LastContact - Check for stale offline status
5. Cache inventory data - Software/hardware changes infrequently
6. Batch operations - Group requests to stay under rate limits
7. Use EDFs for custom data - Extra Data Fields for business-specific info
8. Schedule inventory scans - Keep software/hardware data current
9. Track agent versions - Plan upgrades based on version distribution
10. Document naming conventions - Consistent hostnames across clients

Computer Health Assessment

Determining Computer Health

function assessComputerHealth(computer, patches, antivirus, drives) {
  const issues = [];

  // Check online status
  if (computer.Status !== 'Online') {
    issues.push({
      severity: 'critical',
      message: `Computer is ${computer.Status}`
    });
  }

  // Check agent age
  const lastContact = new Date(computer.LastContact);
  const minutesSinceContact = (Date.now() - lastContact) / 60000;

  if (minutesSinceContact > 60) {
    issues.push({
      severity: 'warning',
      message: `No contact in ${Math.round(minutesSinceContact)} minutes`
    });
  }

  // Check patch status
  if (patches.Missing > 0) {
    const severity = patches.Missing > 10 ? 'critical' : 'warning';
    issues.push({
      severity,
      message: `${patches.Missing} missing patch(es)`
    });
  }

  // Check antivirus
  if (!antivirus.RealTimeProtection) {
    issues.push({
      severity: 'critical',
      message: 'Real-time protection disabled'
    });
  }

  const defAge = (Date.now() - new Date(antivirus.DefinitionDate)) / 86400000;
  if (defAge > 7) {
    issues.push({
      severity: 'warning',
      message: `AV definitions ${Math.round(defAge)} days old`
    });
  }

  // Check disk space
  for (const drive of drives) {
    if (drive.Type === 'Fixed' && drive.PercentFree < 10) {
      issues.push({
        severity: drive.PercentFree < 5 ? 'critical' : 'warning',
        message: `Drive ${drive.Letter} only ${drive.PercentFree}% free`
      });
    }
  }

  return {
    healthy: issues.filter(i => i.severity === 'critical').length === 0,
    issues
  };
}

Related Skills

• ConnectWise Automate Clients - Client management
• ConnectWise Automate Scripts - Script execution on computers
• ConnectWise Automate Monitors - Computer monitoring
• ConnectWise Automate Alerts - Computer alerts
• ConnectWise Automate API Patterns - Authentication and pagination