SuperOps Runbooks

SuperOps.ai Runbook & Script Management

Overview

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

Script Types

Type	Description	Use Case
PowerShell	Windows PowerShell scripts	Windows automation
Batch	Windows batch scripts	Simple Windows tasks
Bash	Unix shell scripts	macOS/Linux automation
Python	Python scripts	Cross-platform automation

Run As Options

Option	Description	When to Use
System	Run as SYSTEM account	Admin tasks, service management
Logged-in User	Current user context	User-specific tasks
Specific User	Custom credentials	Specific permission needs

Execution Priority

Priority	Description
Immediate	Execute as soon as possible
Normal	Standard queue priority
Low	Execute during low activity

Key Script Fields

Script Definition Fields

Field	Type	Description
scriptId	ID	Unique identifier
name	String	Script name
description	String	What the script does
type	Enum	PowerShell, Batch, Bash, Python
content	String	Script source code
parameters	[Parameter]	Input parameters
timeout	Int	Execution timeout (seconds)
osType	Enum	Windows, macOS, Linux

Execution Fields

Field	Type	Description
actionConfigId	ID	Execution instance ID
status	Enum	Pending, Running, Success, Failed
startTime	DateTime	Execution start
endTime	DateTime	Execution end
exitCode	Int	Script exit code
output	String	Script output
error	String	Error messages

GraphQL Operations

List Available Scripts

query getScriptList($input: ListInfoInput!) {
  getScriptList(input: $input) {
    scripts {
      scriptId
      name
      description
      type
      osType
      category
      parameters {
        name
        description
        type
        required
        defaultValue
      }
      createdTime
      lastModifiedTime
    }
    listInfo {
      totalCount
      hasNextPage
      endCursor
    }
  }
}

Variables - All Scripts:

{
  "input": {
    "first": 50,
    "orderBy": {
      "field": "name",
      "direction": "ASC"
    }
  }
}

Variables - Windows PowerShell Scripts:

{
  "input": {
    "filter": {
      "osType": "Windows",
      "type": "PowerShell"
    }
  }
}

Get Scripts by OS Type

query getScriptListByType($input: ScriptListByTypeInput!) {
  getScriptListByType(input: $input) {
    scripts {
      scriptId
      name
      description
      type
      parameters {
        name
        type
        required
      }
    }
    listInfo {
      totalCount
    }
  }
}

Variables:

{
  "input": {
    "osType": "Windows",
    "first": 100
  }
}

Get Script Details

query getScript($input: ScriptIdentifierInput!) {
  getScript(input: $input) {
    scriptId
    name
    description
    type
    osType
    category
    content
    timeout
    parameters {
      name
      description
      type
      required
      defaultValue
      validValues
    }
    runAs
    createdBy {
      id
      name
    }
    createdTime
    lastModifiedTime
  }
}

Variables:

{
  "input": {
    "scriptId": "script-uuid"
  }
}

Run Script on Single Asset

mutation runScriptOnAsset($input: RunScriptInput!) {
  runScriptOnAsset(input: $input) {
    actionConfigId
    script {
      scriptId
      name
    }
    asset {
      assetId
      name
    }
    arguments {
      name
      value
    }
    status
    scheduledTime
    runAs
  }
}

Variables - Immediate Execution:

{
  "input": {
    "assetId": "asset-uuid",
    "scriptId": "script-uuid",
    "runAs": "System",
    "priority": "Immediate"
  }
}

Variables - With Parameters:

{
  "input": {
    "assetId": "asset-uuid",
    "scriptId": "script-uuid",
    "arguments": [
      {
        "name": "ServiceName",
        "value": "Spooler"
      },
      {
        "name": "Action",
        "value": "Restart"
      }
    ],
    "runAs": "System",
    "priority": "Normal"
  }
}

Run Script on Multiple Assets

mutation runScriptOnAssets($input: RunScriptOnAssetsInput!) {
  runScriptOnAssets(input: $input) {
    batchId
    script {
      scriptId
      name
    }
    assetsCount
    status
    scheduledTime
  }
}

Variables:

{
  "input": {
    "assetIds": ["asset-1", "asset-2", "asset-3"],
    "scriptId": "script-uuid",
    "arguments": [
      {
        "name": "param1",
        "value": "value1"
      }
    ],
    "runAs": "System",
    "priority": "Normal"
  }
}

Schedule Script Execution

mutation scheduleScript($input: ScheduleScriptInput!) {
  scheduleScript(input: $input) {
    scheduleId
    script {
      scriptId
      name
    }
    assets {
      assetId
      name
    }
    scheduledTime
    recurrence {
      type
      interval
      daysOfWeek
    }
    status
  }
}

Variables - One-Time Schedule:

{
  "input": {
    "assetIds": ["asset-uuid"],
    "scriptId": "script-uuid",
    "scheduledTime": "2024-02-15T22:00:00Z",
    "runAs": "System"
  }
}

Variables - Recurring Schedule:

{
  "input": {
    "assetIds": ["asset-uuid"],
    "scriptId": "script-uuid",
    "scheduledTime": "2024-02-15T22:00:00Z",
    "recurrence": {
      "type": "Weekly",
      "interval": 1,
      "daysOfWeek": ["Monday", "Wednesday", "Friday"]
    },
    "runAs": "System"
  }
}

Get Script Execution Status

query getScriptExecution($input: ScriptExecutionInput!) {
  getScriptExecution(input: $input) {
    actionConfigId
    script {
      scriptId
      name
    }
    asset {
      assetId
      name
    }
    status
    startTime
    endTime
    exitCode
    output
    error
    duration
  }
}

Variables:

{
  "input": {
    "actionConfigId": "execution-uuid"
  }
}

Get Batch Execution Results

query getBatchExecution($input: BatchExecutionInput!) {
  getBatchExecution(input: $input) {
    batchId
    script {
      scriptId
      name
    }
    status
    totalAssets
    completedCount
    successCount
    failedCount
    executions {
      asset {
        assetId
        name
      }
      status
      exitCode
      output
      error
    }
  }
}

List Script Execution History

query getScriptExecutionHistory($input: ScriptExecutionHistoryInput!) {
  getScriptExecutionHistory(input: $input) {
    executions {
      actionConfigId
      script {
        scriptId
        name
      }
      asset {
        assetId
        name
        client { name }
      }
      status
      startTime
      endTime
      exitCode
      triggeredBy {
        id
        name
      }
    }
    listInfo {
      totalCount
      hasNextPage
    }
  }
}

Variables - Recent Executions:

{
  "input": {
    "first": 50,
    "orderBy": {
      "field": "startTime",
      "direction": "DESC"
    }
  }
}

Variables - By Asset:

{
  "input": {
    "filter": {
      "assetId": "asset-uuid"
    },
    "first": 20
  }
}

Common Workflows

Remediation Workflow

# 1. Check if asset is online
query checkAssetStatus {
  getAsset(input: { assetId: "asset-uuid" }) {
    status
    lastSeen
  }
}

# 2. Run remediation script
mutation runRemediation {
  runScriptOnAsset(input: {
    assetId: "asset-uuid",
    scriptId: "restart-service-script",
    arguments: [{ name: "ServiceName", value: "Spooler" }],
    runAs: "System",
    priority: "Immediate"
  }) {
    actionConfigId
    status
  }
}

# 3. Check execution result
query checkResult {
  getScriptExecution(input: { actionConfigId: "exec-uuid" }) {
    status
    exitCode
    output
    error
  }
}

Maintenance Window Automation

# Schedule maintenance scripts for multiple assets
mutation scheduleMaintenanceWindow {
  runScriptOnAssets(input: {
    assetIds: ["asset-1", "asset-2", "asset-3"],
    scriptId: "windows-update-script",
    scheduledTime: "2024-02-17T02:00:00Z",
    runAs: "System",
    priority: "Low"
  }) {
    batchId
    assetsCount
    scheduledTime
  }
}

Data Collection Workflow

# Run inventory collection across client assets
mutation collectInventory($clientId: ID!) {
  # First get all assets for client
  assets: getAssetList(input: {
    filter: {
      client: { accountId: $clientId },
      status: "Online"
    }
  }) {
    assets { assetId }
  }
}

# Then run collection script
mutation runCollection {
  runScriptOnAssets(input: {
    assetIds: ["asset-1", "asset-2"],
    scriptId: "software-inventory-script",
    runAs: "System"
  }) {
    batchId
  }
}

Error Handling

Common Errors

Error	Cause	Resolution
Script not found	Invalid script ID	Verify script exists
Asset offline	Cannot reach asset	Wait for asset to come online
Timeout exceeded	Script ran too long	Increase timeout or optimize script
Permission denied	Insufficient RunAs rights	Check execution context
Parameter missing	Required param not provided	Add required arguments
Rate limit exceeded	Over 800 req/min	Implement backoff

Exit Code Interpretation

// 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

// 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. Log script output - Capture output for troubleshooting
6. Use scheduling - Run maintenance during off-hours
7. Monitor batch executions - Track success/failure rates
8. Document scripts - Clear descriptions and parameter docs
9. Version control - Track script changes
10. 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