Configuring Windows PowerShell Run Book Actions

Download this manual as a PDF file

This section describes how to customize the run book actions embedded in the "Windows PowerShell Automations" PowerPack to create run book actions to meet your organization's specific requirements.

For more information about creating automation policies using custom action types, see Configuring Windows PowerShell Automations.

Windows PowerShell Run Book Actions

The "Windows PowerShell Automations" PowerPack includes run book actions that execute the "Execute PowerShell Request" action type to request diagnostic information or remediate an issue. You can specify the host and the options in a JSON structure that you enter in the Input Parameters field in the Action Policy Editor modal.

The following automation actions that use the "Execute PowerShell Request" action type are included in the "Windows PowerShell Automations" PowerPack. Compare the commands run with the example in the image above. For more information about input parameter fields, see the table in Creating a Windows PowerShell Run Book Action.

Action Name Description Commands Run

Windows CPU and Memory Diagnostic Commands

Runs diagnostic commands for CPU and Memory events on Windows devices.
  • Get-Process | Sort CPU -descending | Select -first 20
  • Get-Process | Select-Object Name, ID, @{Name='ThreadCount';Expression ={$_.Threads.Count}}
    | Sort-Object -Property ThreadCount -Descending
    | Select -first 20
  • Get-Process | Sort WS -descending | Select -first 20
  • Get-CimInstance -Class Win32_PageFileUsage | Format-Table -Property Caption,Name,Status,Description,InstallDate,
    AllocatedBaseSize,PeakUsage,TempPageFile
  • A command that collects the memory usage of running processes, where the memory usage is aggregated across all instances of each named process. The command is not listed here for clarity.

Windows CPU Diagnostic Commands

Runs diagnostic commands for CPU-related events on Windows devices.
  • Get-Process | Sort CPU -descending
    | Select -first 20
  • Get-Process | Select-Object Name, ID, @{Name='ThreadCount';Expression ={$_.Threads.Count}}
    | Sort-Object -Property ThreadCount -Descending
    | Select -first 20

Windows Disk I/O Diagnostic Commands

Runs diagnostic commands for Disk I/O events on Windows devices.
  • A command that collects the "IO Data Bytes per second" counter for each running process. The command takes 10 samples at 1-second intervals and returns the average of all samples for each process. The command is not listed here for clarity.
  • A command that collects the "IO Data Operations per second" counter for each running process. The command takes 10 samples at 1-second intervals and returns the average of all samples for each process. The command is not listed here for clarity.

Windows Get Largest Event Log Files

Gets the 20 largest Windows Event Log files.
  • Get-ChildItem C:\Windows\System32\winevt\Logs | Sort -Descending -Property length | Select -first 20

Windows Get Largest Files on Disk

Gets the 20 largest files on the disk specified in the event.

 
  • Get-ChildItem %Y -r -erroraction 'silentlyContinue' | Sort -Descending -Property length | Select -first 20 | Select-Object FullName,@{Name='SizeMB';Expression={[math]::Round($_.Length / 1MB,2)}}

Windows Memory Diagnostic Commands

Runs diagnostic commands for Memory-related events on Windows devices.

  • Get-Process | Sort WS -descending
    | Select -first 20

  • Get-CimInstance -Class Win32_PageFileUsage
    | Format-Table -Property Caption,Name,Status,Description,InstallDate,
    AllocatedBaseSize,PeakUsage,TempPageFile
  • A command that collects the memory usage of running processes, where the memory usage is aggregated across all instances of each named process. The command is not listed here for clarity.

Windows Print Job Error Diagnostic Commands

Runs diagnostic commands for Print Job Error events on Windows devices.
  • Get-Printer | Get-PrintJob | Where-Object JobStatus -like '*error*'

Authentication for Windows Devices with the Windows PowerShell Automations PowerPack

The "Execute PowerShell Request" custom action type supports hard-coded credentials where you specify the ID of a credential in the run book action. Alternately, the custom action type can dynamically determine the credential to use.

By default, the automation actions in this PowerPack use the dynamic method, which uses the default value of "credential_id": 0 in the Input Parameters for the run book actions aligned with the "Execute PowerShell Request" custom action type.

The dynamic method uses the first credential that matches the following rules:

  • If the "Microsoft: Windows Server Configuration Cache" Dynamic Application (from the "Microsoft: Windows Server" PowerPack) is aligned to the device associated with the triggering event, the credential aligned to that Dynamic Application is used.
  • If the "Microsoft: Windows Server Performance Cache" Dynamic Application (from the "Microsoft: Windows Server" PowerPack) is aligned to the device associated with the triggering event, the credential aligned to that Dynamic Application is used.
  • If the "Microsoft: Windows Server OS Configuration" Dynamic Application (from the "Microsoft: Windows Server" PowerPack) is aligned to the device associated with the triggering event, the credential aligned to that Dynamic Application is used.
  • If none of the listed Dynamic Applications are aligned to the device associated with the triggering event, the first available credential aligned to the device as a secondary credential is used.

Creating a Custom Run Book Action Policy

You can use the "Execute PowerShell Request" action type included with the "Windows PowerShell Automations" PowerPack to create custom automation actions that you can then use to build custom automation policies.

To create a custom action policy using the "Execute PowerShell Request (2.0)" action type:

  • Navigate to the Action Policy Manager page (Registry > Run Book > Actions).
  • In the Action Policy Manager page, click the Create button. The Action Policy Editor modal appears.
  • In the Action Policy Editor page, supply a value in each field.

  • Action Name. Specify the name for the action policy.
  • Action State. Specifies whether the policy can be executed by an automation policy (enabled) or cannot be executed (disabled).
  • Description. Allows you to enter a detailed description of the action.
  • Organization. Organization to associate with the action policy.
  • Action Type. Type of action that will be executed. Select the "Execute PowerShell Request (2.0)" action type.
  • Execution Environment. Select from the list of available Execution Environments. The default execution environment is System.
  • Action Run Context. Select Database or Collector as the context in which the action policy will run.
  • Input Parameters. A JSON structure that specifies each input parameter. Each parameter definition includes its name, data type, and whether the input is optional or required for this Custom Action Type. For more information about the available input parameters, see the table in Creating a Windows PowerShell Run Book Action.

Input parameters must be defined as a JSON structure.

  • Click [Save]. If you are modifying an existing action policy, click Save As. Supply a new value in the Action Name field, and save the current action policy, including any edits, as a new policy.

For more information about substitution variables, see Appendix A: Run Book Variables.

Creating a Windows PowerShell Run Book Action

You can create a new run book action that runs remote PowerShell requests using the "Execute PowerShell Request" custom action type. To do this, select "Execute PowerShell Request" in the Action Type drop-down list when you create a new run book action. You can also use the existing run book actions in the PowerPack as a template by using the [Save As] option.

The Windows PowerShell run book actions accept the following parameters in JSON:

Parameter Input type Description

commands

string

Specifies a single command or a list of commands, in JSON format, to execute. You can use substitution variables in the commands.

request_key

string

(Optional field)

Default value: empty

The unique key for each instance (row) returned by the request. This unique key must be a property name, and the request must include that property (column) and return values from that property name (column).

Example: Suppose you want to get the ID, number of cores, name, and maximum clock speed of every CPU installed on a Windows system, run the following command, where "DeviceID" is the request key.

Get-WmiObject -Class Win32_Processor -Property DeviceID, NumberOfCores, Name, MaxClockSpeed | Format-List DeviceID, NumberOfCores, Name, MaxClockSpeed

credential_id

integer

Default value: 0

Specifies the credential_id to use for the connection.

  • If set to 0 (false), the custom action type will dynamically determine the credential.
  • If set to an ID number, it maps to the credential ID specified. You can find credential IDs by going to System > Manage > Credentials.

Using Substitution Values. The commands input can contain substitution values that match the keys in EM7_VALUES.

For more information about substitution variables, see Appendix A: Run Book Variables.

For a description of all options that are available in Automation Policies, see the Run Book Automation section.