ConnectWise Automate Script Management

Overview

Scripts in ConnectWise Automate are automation routines that run on managed endpoints. They can be PowerShell, batch files, VBScript, or Automate's native scripting language. This skill covers script listing, execution, parameters, and result retrieval.

Key Concepts

Script Types

Script Execution Modes

Script Status

Field Reference

Script Fields

interface Script {
  // Identifiers
  ScriptID: number;             // Primary key
  ScriptGUID: string;           // Global unique ID
  Name: string;                 // Script name

  // Organization
  FolderID: number;             // Folder ID
  FolderPath: string;           // Full folder path

  // Script Content
  ScriptType: ScriptType;       // Type of script
  ScriptVersion: number;        // Version number
  Description: string;          // Script description

  // Permissions
  ClientID: number;             // 0 for global, or specific client
  LocationID: number;           // 0 for all locations

  // Parameters
  Parameters: ScriptParameter[];

  // Metadata
  DateCreated: string;          // Creation date
  DateModified: string;         // Last modified
  ModifiedBy: string;           // Last editor
  Enabled: boolean;             // Is active
}

type ScriptType = 'Automate' | 'PowerShell' | 'Batch' | 'VBScript' | 'Shell';

interface ScriptParameter {
  Name: string;                 // Parameter name
  Type: ParameterType;          // Data type
  Required: boolean;            // Is required
  DefaultValue: string;         // Default if not provided
  Description: string;          // Parameter help
  Options: string[];            // For dropdown types
}

type ParameterType = 'String' | 'Number' | 'Boolean' | 'Dropdown' | 'Computer' | 'Client';

Script Execution Fields

interface ScriptExecution {
  // Identifiers
  ExecutionID: number;          // Unique execution ID
  ScriptID: number;             // Script that ran
  ComputerID: number;           // Target computer

  // Status
  Status: ExecutionStatus;      // Current status
  ExitCode: number;             // Process exit code
  StartTime: string;            // When started
  EndTime: string;              // When finished
  Duration: number;             // Seconds elapsed

  // Results
  Output: string;               // Script stdout
  ErrorOutput: string;          // Script stderr
  LogOutput: string;            // Automate log entries

  // Context
  TriggeredBy: string;          // Who/what initiated
  Parameters: Record<string, string>;  // Passed parameters
}

type ExecutionStatus = 'Pending' | 'Running' | 'Completed' | 'Failed' | 'Timeout' | 'Cancelled';

API Patterns

List All Scripts

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

Response:

[
  {
    "ScriptID": 1001,
    "Name": "Clear Temp Files",
    "FolderPath": "Maintenance/Disk Cleanup",
    "ScriptType": "PowerShell",
    "Description": "Clears Windows temporary directories",
    "Enabled": true,
    "Parameters": [
      {
        "Name": "days",
        "Type": "Number",
        "Required": false,
        "DefaultValue": "7",
        "Description": "Delete files older than X days"
      }
    ]
  }
]

Get Script Details

GET /cwa/api/v1/Scripts/{scriptID}
Authorization: Bearer {token}

List Scripts by Folder

GET /cwa/api/v1/Scripts?condition=FolderID = 5&pageSize=100
Authorization: Bearer {token}

Search Scripts by Name

GET /cwa/api/v1/Scripts?condition=Name contains 'cleanup'&pageSize=50
Authorization: Bearer {token}

Execute Script on Computer

POST /cwa/api/v1/Computers/{computerID}/Scripts/{scriptID}/Execute
Authorization: Bearer {token}
Content-Type: application/json

{
  "Parameters": {
    "days": "30",
    "path": "C:\\Temp"
  }
}

Response:

{
  "ExecutionID": 98765,
  "Status": "Pending",
  "ComputerID": 12345,
  "ScriptID": 1001,
  "StartTime": "2024-02-15T10:45:00Z"
}

Get Execution Status

GET /cwa/api/v1/Scripts/Executions/{executionID}
Authorization: Bearer {token}

Response (Running):

{
  "ExecutionID": 98765,
  "Status": "Running",
  "StartTime": "2024-02-15T10:45:00Z",
  "Duration": 30
}

Response (Completed):

{
  "ExecutionID": 98765,
  "Status": "Completed",
  "ExitCode": 0,
  "StartTime": "2024-02-15T10:45:00Z",
  "EndTime": "2024-02-15T10:46:30Z",
  "Duration": 90,
  "Output": "Deleted 156 files totaling 2.3 GB",
  "ErrorOutput": ""
}

Execute Script on Multiple Computers

POST /cwa/api/v1/Scripts/{scriptID}/Execute
Authorization: Bearer {token}
Content-Type: application/json

{
  "ComputerIDs": [12345, 12346, 12347],
  "Parameters": {
    "days": "30"
  }
}

Response:

{
  "Executions": [
    { "ExecutionID": 98765, "ComputerID": 12345, "Status": "Pending" },
    { "ExecutionID": 98766, "ComputerID": 12346, "Status": "Pending" },
    { "ExecutionID": 98767, "ComputerID": 12347, "Status": "Pending" }
  ]
}

Get Execution History for Computer

GET /cwa/api/v1/Computers/{computerID}/Scripts/Executions?pageSize=50
Authorization: Bearer {token}

Get Execution History for Script

GET /cwa/api/v1/Scripts/{scriptID}/Executions?pageSize=50
Authorization: Bearer {token}

Workflows

Find Script by Name

async function findScriptByName(client, name) {
  const scripts = await client.request(
    `/Scripts?condition=Name contains '${name}'&pageSize=50`
  );

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

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

  return {
    found: false,
    ambiguous: true,
    suggestions: scripts.map(s => ({
      name: s.Name,
      id: s.ScriptID,
      folder: s.FolderPath,
      description: s.Description
    }))
  };
}

Execute Script and Wait for Completion

async function runScriptAndWait(client, computerId, scriptId, params = {}, options = {}) {
  const { timeoutMs = 300000, pollIntervalMs = 5000 } = options;

  // Start the script
  const execution = await client.request(
    `/Computers/${computerId}/Scripts/${scriptId}/Execute`,
    {
      method: 'POST',
      body: JSON.stringify({ Parameters: params })
    }
  );

  const startTime = Date.now();

  // Poll for completion
  while (true) {
    const status = await client.request(
      `/Scripts/Executions/${execution.ExecutionID}`
    );

    if (['Completed', 'Failed', 'Timeout', 'Cancelled'].includes(status.Status)) {
      return {
        success: status.Status === 'Completed' && status.ExitCode === 0,
        execution: status
      };
    }

    // Check timeout
    if (Date.now() - startTime > timeoutMs) {
      return {
        success: false,
        execution: status,
        error: 'Polling timeout exceeded'
      };
    }

    await sleep(pollIntervalMs);
  }
}

Validate Scrip