Configuring Windows PowerShell Automations

This section describes how to use the automation policies, run book actions, and custom action types found in the "Windows PowerShell Automations" PowerPack.

Windows PowerShell Automation Policies

The "Windows PowerShell Automations" PowerPack includes the following automation policies:

Windows PowerShell: Run CPU & Memory Diagnostic Commands
Windows PowerShell: Run CPU Diagnostic Commands
Windows PowerShell: Run Disk I/O Diagnostic Commands
Windows PowerShell: Run Disk Usage Diagnostic Commands
Windows PowerShell: Run Memory Diagnostic Commands
Windows PowerShell: Run Print Job Error Diagnostic Commands

Each policy triggers a single run book action that collects diagnostic data within a PowerShell session, and an action that formats the output as HTML for events associated with devices in the "Windows Automation" device group, and an action that formats the output. The "Windows Automation" device group is included in this PowerPack. You will need to manually add the Windows devices you want to monitor to the "Windows Automation" device group.

All of the run book actions use the same custom action type, "Execute PowerShell Request", which is supplied in the PowerPack.

All of the automation policies are tied to included ScienceLogic SL1 events generated by the Dynamic Applications from the "Microsoft Windows Server" PowerPack.

Several of the run book actions use the substitution character feature of the "Execute PowerShell Request" custom action type. If an event variable is included in a command (such as "%Y" for the sub-entity name), the custom action type automatically replaces that variable with the value from the triggering event.

The following table shows the standard automation policies, their aligned events, and the run book actions that runs in response to the events.

The aligned events are included as part of the "Microsoft Windows Server" PowerPack and are not installed with the SL1 platform. You must install the "Microsoft Windows Server" PowerPack to obtain these events.

Automation Policy Name	Aligned Device Group	Aligned Events	Aligned Run Book Actions
Windows PowerShell: Run CPU & Memory Diagnostic Commands	Windows Automation	Minor: Microsoft: Windows Disk Transfer Time (Physical Disk) exceeded threshold	Automation Utilities: Calculate Memory Size for Each Action Windows CPU and Memory Diagnostic Commands Datacenter Automation: Format Output as HTML
Windows PowerShell: Run CPU Diagnostic Commands	Windows Automation	Minor: Microsoft: Windows CPU Utilization has exceeded the threshold Minor: Microsoft: Windows Processor Queue Length exceeded the threshold	Automation Utilities: Calculate Memory Size for Each Action Windows CPU and Memory Diagnostic Commands Datacenter Automation: Format Output as HTML
Windows PowerShell: Run Disk I/O Diagnostic Commands	Windows Automation	Minor: Microsoft: Windows % Disk Time (Logical Disk) exceeded threshold Minor: Microsoft: Windows % Disk Time (Physical Disk) exceeded threshold Minor: Microsoft: Windows Current Disk QueueLength (Physical Disk)exceeded threshold	Automation Utilities: Calculate Memory Size for Each Action Windows Disk I/O Diagnostic Commands Datacenter Automation: Format Output as HTML
Windows PowerShell: Run Disk Usage Diagnostic Commands	Windows Automation	Poller: File system usage exceeded (major) threshold Poller: File system usage exceeded (critical) threshold	Automation Utilities: Calculate Memory Size for Each Action Windows Get Largest Event Log Files Windows Get Largest Files on Disk Windows Disk I/O Diagnostic Commands Datacenter Automation: Format Output as HTML
Windows PowerShell: Run Memory Diagnostic Commands	Windows Automation	Major: Microsoft: Windows Available Memory below threshold Major: Microsoft: Windows Pages per Second has exceeded threshold Minor: Microsoft: Windows Paging File Usage has exceeded threshold	Automation Utilities: Calculate Memory Size for Each Action Windows Memory Diagnostic Commands Datacenter Automation: Format Output as HTML
Windows PowerShell: Run Print Job Error Diagnostic Commands	Windows Automation	Minor: Microsoft: Windows: PowerShell: Print Job Errors exceeded threshold	Automation Utilities: Calculate Memory Size for Each Action Windows Print Job Error Diagnostic Commands Datacenter Automation: Format Output as HTML

The following figure shows a memory event with a classification of "Major" appears on the Events page. Click the [Actions] button () for an event, and select View run book actions to see the run book (automation) actions triggered by the events.

The results shown for this event, in the Event Actions Log modal, include the automation policy that ran (shown at the top of the following figure), along with the run book actions (commands) that ran. Results for each command are also displayed. The following figure shows an example of this HTML output:

To learn more about which commands are executed by default for a given run book action, see Configuring Windows PowerShell Run Book Actions.

Although you can edit the run book actions described in this section, it is a best practice to use "Save As" to create a new run book action, rather than to customize the standard automation policies.

User-initiated Automation Policies

All Windows PowerShell automation policies have a Policy Type of "Active Events/User Initiated", which enables all of the features of the "Active Events" and the "User Initiated" policy types. As a result, these automation policies can be triggered by active events that meet the criteria in the policy, or you can manually trigger the automation.

You can run these automation policies as needed from the Devices page, the Events page, and the Service Investigator page. If there is an event policy specified in the automation policy, that event must be active for the policy to be run manually, and the policy can only be run on that event type. The same applies for the device groups list.

For these automation policies to be visible from the Tools panel in the Device Summary modal , the following three bullets must be true between the event and the automation policy configuration:

Organization. The organization associated with the event must match the organization configured in the automation policy. Policies in the "System" organization match all organizations.
Aligned Devices. The device for which the event is triggered must be configured as a Aligned Device in the automation policy.
Aligned Event. The event must match one of the Aligned Events configured in the automation policy.

In most situations, you would run a user-initiated automation in response to an event that just occurred. If you have Automation PowerPacks installed on your SL1 system, the Event Actions Log window for that event might contain diagnostic information from other automations that have already run, including information that helps you determine which user-initiated automation you should run next to address the cause of the event.

To run a user-initiated automation policy, click the open icon () to open the Device Summary modal for the event and click in the Tools section. Any available user-initiated automation policy will be listed there, available to run on-demand.

Creating and Customizing Automation Policies

You can use the default run book automation policies in this PowerPack, or you can create and customize the policies as needed.

You might need to configure a run book action policy before you can add it to the automation policy. For more information, see Customizing Windows PowerShell Run Book Actions.

Before you create an automation policy using the run book actions in this PowerPack, you must determine:

Which set of commands you want to run on a monitored device when an event occurs. There are ten run book actions in the PowerPack that run the "Execute PowerShell Request" action type with different commands. You can also create your own run book actions using the custom action type supplied in the PowerPack.
What event criteria you want to use to determine when the run book actions will trigger, or the set of rules that an event must match before the automation is executed. This can include matching only specific event policies, event severity, associated devices, and so on. For a description of all the options that are available in Automation Policies, see the Run Book Automation section.

To create or customize an automation policy that uses the run book actions in the "Windows PowerShell Automations" PowerPack:

Go to the Automation Policy Manager page (Registry > Run Book > Automation).
Click the Create button to create an automation policy, or search for an existing automation policy that you want to edit and click the wrench icon () for that policy. The Automation Policy Editor page appears:

Complete the following fields:

Policy Name. Enter a name for the automation policy.
Policy Type. Select whether the automation policy will match events that are active, match when events are cleared, or run on a scheduled basis. Typically, you would select Active Events in this field.
Policy State. Specifies whether the policy will be evaluated against the events in the system. If you want this policy to begin matching events immediately, select Enabled. The default is Disabled.
Policy Priority. Specifies whether the policy is high-priority or default priority. These options determine how the policy is queued.
Organization. Select one or more organizations to associate with the automation policy. The automation policy will execute only for devices in the selected organizations (that also match the other criteria in the policy). To configure a policy to execute for all organizations, select System without specifying individual devices to align to.
Align With. Select Device Groups.
Aligned Device Groups. The "Windows Automation" device group needs to be aligned. To add the device group to the Aligned Device Groups field, select the "Windows Automation" device group in the Available Device Groups field and click the right arrow (>>).
Aligned Actions. This field includes the actions from the "Windows PowerShell Automations" PowerPack. To add an action to the Aligned Actions field, select the action in the Available Actions field and click the right arrow (>>). To re-order the actions in the Aligned Actions field, select an action and use the up arrow or down arrow buttons to change that action's position in the sequence.

You must have at least two Aligned Actions: one that runs the run book action and one that provides the output format. The actions providing the output formats are contained in the "Datacenter Automation Utilities" PowerPack, which is a prerequisite for running automations in this PowerPack.

If you are selecting multiple collection actions that use the "Execute Shell Commands" action type, you may want to include the "Calculate Memory Size for Each Action" run book action, found in the "Datacenter Automation Utilities" PowerPack, in your automation policy.

Optionally, supply values in the other fields on this page to refine when the automation will trigger.
Click Save for a new policy, or click Save As if you are customizing an existing policy. If you modify one of the included automation policies and save it with the original name, any customizations you made to that policy will be overwritten when you upgrade the PowerPack.

Removing an Automation Policy from a PowerPack

If you have customized an automation policy from the PowerPack, you might want to remove that policy from that PowerPack to prevent your changes from being overwritten if you update the PowerPack later. If you have the license key with author's privileges for a PowerPack or if you have owner or administrator privileges with your license key, you can remove content from a PowerPack.

To remove content from a PowerPack:

Go to the PowerPack Manager page (System > Manage > PowerPacks).
Find the "Windows PowerShell Automations" PowerPack. Click its wrench icon ().
In the PowerPack Properties page, in the navigation bar on the left side, click Run Book Policies.
In the Embedded Run Book Polices pane, locate the policy you updated, and click the bomb icon () for that policy. The policy will be removed from the PowerPack and will now appear in the bottom pane.