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
| Type | Extension | Use Case | |------|-----------|----------| | Automate Script | Internal | Built-in functions, agent commands | | PowerShell | .ps1 | Windows automation, complex logic | | Batch | .bat/.cmd | Simple Windows tasks | | VBScript | .vbs | Legacy Windows automation | | Shell | .sh | Linux/macOS automation |
Script Execution Modes
| Mode | Description | Use Case | |------|-------------|----------| | Immediate | Run now on target | Ad-hoc tasks | | Scheduled | Run at specific time | Maintenance | | On Event | Triggered by alert/monitor | Automated remediation | | Login/Logout | Run at user session events | User setup |
Script Status
| Status | Description | |--------|-------------| | Running | Currently executing | | Completed | Finished successfully | | Failed | Execution error | | Pending | Queued for execution | | Timeout | Exceeded time limit | | Cancelled | Manually stopped |
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);
}
}