Powershell Runbook
A Powershell runbook runs a PowerShell script on a Windows host over WinRM and parses the output back into values on the result screen.
When to Use
Use Powershell for anything that needs the Windows management stack: services, event logs, performance counters, WMI, registry, disk health, scheduled tasks, Active Directory cmdlets.
Fields
| Field | What to enter |
|---|---|
| Runbook Name | A short, unique name. |
| Description | One line on what the runbook returns. |
| Runbook Category | Diagnostics, Performance Monitoring, Troubleshooting, System Management, Log Collection, Network Config, or Integration. |
| Monitor | Pick by Group, Tag, IP/Host, or Monitors. |
| Credential Profile | The WinRM credential. Click Create Credential Profile if none fits. |
| Port | WinRM port. Defaults to the credential profile's port (5985 for HTTP, 5986 for HTTPS). |
| Timeout | Seconds to wait before marking the run Failed. |
| Powershell Script | The PowerShell command or script the agent runs over WinRM. |
| Script Language | GO or Python, for the parsing script. |
| Parsing Script | Turns the raw PowerShell output into the result values. |
| Add Variable | Prompts the user for a value at run time. Reference it as $$$variable.name$$$ in both scripts. |
The right-side Sample Parsing Script > Powershell Availability panel shows a working parser you can copy and adjust.
Steps
- Open Settings > Plugin Library > Runbook and click Create Runbook Plugin.
- Pick Powershell from the top menu.
- Fill in the fields above.
- Click Test to run the Powershell script against the chosen monitor and show the parsed values.
- Click Save.
note
The Windows credential must have the permissions the script requires. For service start or stop, that is Service Control permission. For event log reads, that is Event Log Reader permission.