SuperOps Runbooks

SuperOps.ai Runbook & Script Management

Overview

SuperOps.ai provides automation through scripts (runbooks) that execute on managed assets — maintenance tasks, remediation actions, data collection, and custom automation. This skill covers script discovery, execution, scheduling, and result monitoring.

Anti-triggers

• A written procedure or checklist — SuperOps runbooks are executable scripts, not documentation. Prose runbooks live in hudu-articles or itglue-documents.
• Running a script on an endpoint managed by another RMM — "run a script on this device" matches five other plugins here just as well. Confirm which RMM owns the endpoint, then use atera-agents, syncro-assets, immybot-script-execution, ncentral-monitoring-tasks, connectwise-automate-scripts, or datto-rmm-jobs.
• Deploying or updating an application — a script that installs software is the anti-pattern immybot-software-deployment exists to replace when the fleet is on ImmyBot.
• Choosing the targets — asset selection and online checks are superops-assets.

Key Concepts

A script is a stored definition (scriptId, type, content, parameters, timeout, osType). Executing it creates an execution instance identified by actionConfigId; running it across multiple assets creates a batch identified by batchId. Scheduling produces a scheduleId.

See references/fields.md for the complete script and execution field reference.

Common Workflows

Remediation

1. Query the asset (getAsset) and confirm status is Online — a script queued to an offline asset stays Pending until it checks in.
2. runScriptOnAsset with priority: "Immediate" and the required arguments.
3. Capture the returned actionConfigId.
4. Poll getScriptExecution until status reaches a terminal value, then read exitCode, output, and error.

Maintenance Window

Use runScriptOnAssets with an assetIds array, a future scheduledTime (UTC ISO 8601), and priority: "Low". Track the returned batchId with getBatchExecution, which reports successCount / failedCount alongside per-asset results.

Data Collection

1. getAssetList filtered by client and status: "Online" to build the asset list.
2. Feed those assetId values into runScriptOnAssets with the collection script.
3. Read results from getBatchExecution.

Recurring Schedules

scheduleScript accepts a recurrence object (type, interval, daysOfWeek) alongside scheduledTime. Omit recurrence for a one-time run.

API Patterns

Arguments are passed as an array of { name, value } objects — values are strings even for numeric parameters. runAs must be supplied per execution; it is not inherited from the script definition's runAs default unless omitted.

See references/api.md for the complete operation catalog with request/response examples and end-to-end workflow queries.

Error Handling

Exit Code Interpretation

Exit code 137 means the agent killed the script on timeout, not that the script failed on its own — check the script's timeout before assuming a logic error.

// Common exit codes
const EXIT_CODES = {
  0: 'Success',
  1: 'General error',
  2: 'Misuse of command',
  126: 'Permission denied',
  127: 'Command not found',
  128: 'Invalid exit argument',
  130: 'Script terminated (Ctrl+C)',
  137: 'Script killed (timeout)',
  255: 'Exit status out of range'
};

function interpretExitCode(code) {
  return EXIT_CODES[code] || `Unknown exit code: ${code}`;
}

Execution Status Handling

Execution is asynchronous — the mutation returns before the script runs. Poll until the status is one of Success, Failed, Timeout, or Cancelled.

// Poll for execution completion
async function waitForExecution(actionConfigId, maxWaitMs = 300000) {
  const startTime = Date.now();
  const pollInterval = 5000;

  while (Date.now() - startTime < maxWaitMs) {
    const result = await getScriptExecution({ actionConfigId });

    if (['Success', 'Failed', 'Timeout', 'Cancelled'].includes(result.status)) {
      return result;
    }

    await sleep(pollInterval);
  }

  throw new Error('Execution timed out waiting for completion');
}

Best Practices

1. Test scripts first - Test on a single asset before bulk execution
2. Use parameters - Make scripts reusable with parameters
3. Set appropriate timeouts - Prevent hung scripts
4. Handle errors in scripts - Return meaningful exit codes
5. Use scheduling - Run maintenance during off-hours
6. Monitor batch executions - Track success/failure rates
7. Document scripts - Clear descriptions and parameter docs
8. Check asset status - Verify online before running

Related Skills

• SuperOps.ai Assets - Asset details
• SuperOps.ai Alerts - Alert-triggered automation
• SuperOps.ai Tickets - Ticket-based automation
• SuperOps.ai API Patterns - GraphQL patterns