KACE Desktop Authority 11.1 - ExpertAssist User Guide

System Monitoring

Use the System Monitoring page under Scheduling & Alerts object in the tree to make changes and create new rules.

A rule has the following structure:

<rule name> (delay)
{ <condition> { <action1> } else { <action2> } }

The action can consist of several statements – they have to be separated with a semicolon.

Such as:

MemUsageAboveFor(70%, 20m)
{
SendMail(“administrator@company.com”,“Memory usage on [MACHINE]”,“High memory utilization!\n” “(Max: [MAX_USAGE])”);
SendMessage(“administrator”,“High memory utilization on [MACHINE]!\n” “(Max: [MAX_USAGE])”);
}

You can enable or disable certain rules right on the System Monitoring page.

The Edit rules button lets you edit the monitoring rules in your browser.

For example:

"Check Memory Usage" (10m)
{
MemUsageAboveFor(70%, 20m)
{
SendMail("administrator@company.com","Memory usage on [MACHINE]","High memory utilization!\n""(Max: [MAX_USAGE])");
}
else
{
SendMail("administrator@company.com","Memory usage back to normal","See topic.");
}
}

The above rule executes every 10 minutes (delay), and checks the condition MemUsageAboveFor. In the above scenario, if the memory utilization is above 70% for 20 minutes or more, the condition becomes true, and action1 is executed.

The action, in this case, will send an email to administrator@company.com describing what has happened. The rule will keep checking the condition every 10 minutes after the condition has become true. If it’s still true, it does nothing – but if it becomes false (that is, the emergency situation is resolved) it executes action2. In that case, ExpertAssist will email the administrator to let him know that the problem has been resolved.

The monitoring script runs like a trigger. If it invokes the PowerShell script, it first initializes the $POWERSHELL_RES variable to 0. This state is then handled as the ‘previous state’. Then the ExpertAssist monitoring script engine compares this state to the state known as the ‘current state’ that is set when execution of the PowerShell script is finished. If executing the PowerShell script changes the state and the current state is different to the previous state, monitoring script triggers and executes the branch depending on the trigger value. The trigger in this case is the value of the $POWERSHELL_RES variable. If executing the PowerShell script returned the $POWERSHELL_RES variable set to 1, the monitoring script condition (main script branch) is executed following the monitoring script function declaration. If executing the PowerShell script returned the $POWERSHELL_RES variable set to 1, the monitoring script ELSE condition (else script branch) is executed. Thus, if the previous state has the $POWERSHELL_RES of 0 and executing the script returned the $POWERSHELL_RES set to 0, monitoring script will not trigger. If executing the script returned $POWERSHELL_RES set to 1, it indicates a trigger and the main script branch is executed since the variable value is 1. The table below shows the value of the $POWERSHELL_RES variable on a particular state and the script branch that will be executed within the monitoring script.

Table 4: The $POWERSHELL_RES variable.

Email Alerts

When log entries matching a certain criteria are entered into any of the event logs you can have ExpertAssist send you email alerts to an email address of your choice.

Email alerts will not work until you configure your SMTP server under Preferences > Network.

Once you've set that up, you can configure email alerts according to the following criteria:

Enabled

Enables/Disables the event alert

Event Log Name

The event log to watch.

Event Type

Can be Error, Warning, Error & Warning, Information, Audit Success, Audit Failure, or All types.

Event Source

Type in the source of the message you want to be alerted on. For example, Security, Disk, etc. This field is optional.

Event Category

Type in the category of the message as it would appear in the event log. This field is optional.

Event ID

Type in the event code as it would appear in the event log. This field is optional.

Email

The email address the notifications are sent out to. You can only specify a single email address per entry, so if you want several people to receive these messages you should specify a group alias here.

Task Scheduler

The Task Scheduler gives you a simple interface to NT’s Scheduler. In order to be able to view, add and delete tasks, the Schedule service must also be running.

On the main page, you can see a list of all currently scheduled tasks. The table shows you the following:

• The name of the task;
• The command to be executed;
• The time of the day the command is to be run;
• Whether the last run of the job ended successfully.

To remove a task from the list:

Select it and click on the Delete button in the toolbar.

To add a new scheduled task:

Click on the Create new task button.

To view/modify the attributes of your existing tasks:

1. Double click a task. The page with task attributes will open.
   Or,
   Use the Change attributes button in the toolbar.
2. Use the attributes organized under three tabs, with the headings Task, Settings and Schedule.

To download a CSV file containing the currently displayed table of scheduled tasks available on the remote computer:

Click the Export button.

Scripting

Scripts

This page in ExpertAssist provides an extension interface in which you can create custom PowerShell scripts that interact with the remote system, ExpertAssist and the remote user.

ExpertAssist comes shipped with a set of scripts that allow you to perform some typical administrative tasks on the remote computer. You may use them as a basis for your custom scripts, or you may create your own scripts from scratch as well.

Table 5: Pre-defined scripts description.

There are three kinds of scripts you can create:

• Interactive
• Quiet
• Hybrid

Interactive scripts display their output on HTML pages, returning script output back to your right within the ExpertAssist’s Scripts page. An example for an interactive script is the File.ps1 script, which is installed with ExpertAssist. These scripts do not have to return a value from their main function. They communicate with the user via the htmlBeginOutptut(), htmlEndOutput().

A Quiet script is one that is usually called from the System Monitoring script. It does not display output. A return value is required at the end of the main function.

A skeleton example for a Quiet script is here:

& {$POWERSHELL_RES = 1;}

This script does not do anything useful. It simply sets the $POWERSHELL_RES variable to 1, meaning that a problem has occurred.

By default, PowerShell is initialized with the $POWERSHELL_RES variable set to 0. When using PowerShell scripts in monitoring scripting, setting $POWERSHELL_RES to something other than 0 allows the ExpertAssist to automatically execute the action followed by the monitoring script function declaration.

In the example above setting the $POWERSHELL_RES variable to 1 will indicate to the ExpertAssist built-in monitoring script compiler that the PowerShell interpreter has failed executing the script. This enables the monitoring script compiler invoking the PowerShell script to trigger and execute the ‘else’ branch of the monitoring script.

Hybrid scripts, on the other hand, are executable interactively and also return a value at the end of their main function. Hybrid scripts check the return value of the htmlBeginOutput() function, and if it’s a zero value, the script is run in non-interactive mode.

These PowerShell scripts can be invoked from the System Monitoring scripts via the PowerShell() function call. This function takes the name of the PowerShell script name you want to invoke for monitoring as an input parameter. For example, if you want to regularly send notifications to your inbox, you can invoke the Email script written in PowerShell right from the monitoring script. This can be done by passing the PowerShell script name to the PowerShell() function:

PowerShell(Email)

See the MonitoringScript.txt file in the ExpertAssist program folder for an example.

For the PowerShell scripting language reference, please see the Owner’s Manual available for downloading at http://www.microsoft.com/technet/scriptcenter/topics/winpsh/manual/default.mspx.

To run a script:

Click the script's Run icon to execute it immediately. ExpertAssist will show the notification message on the Scripting page during the script runtime to indicate that the script is being executed on the remote computer.

Figure 14: The script is being executed.

The Length column shows the size of the PowerShell script.

To edit and save changes made to the PowerShell source code of the script:

1. Click the Edit button in the Edit column in the row for a particular script.
2. When opened, make changes to your script just as you do it within the PowerShell ISE / shell.
3. Click Save to commit changes. Or click Cancel to discard changes made to the script during editing and return back to the script list page.

The Delete command removes the script. Confirm script deletion by clicking OK in the message box or click Cancel to skip deleting the script.

Deleting the script will permanently delete the script *.ps1 file from the remote computer!

To create a new script, enter its desired name in the Name field and click the New script button.

Script creation example

Suppose, you want to create a script that will check to see the printer drivers available on the remote computer to help you troubleshoot printing errors. Of course, you would like to have this script output the results back to you elegantly wrapped in a table.

1. In the Name field type something like Get-PrinterDrivers.
1. Click the New script button, and ExpertAssist will automatically open the new blank script file for you.

   Figure 15: The new blank script file.

   

   Note: It is recommended that you use PowerShell naming convention when defining cmdlet verb names http://msdn.microsoft.com/en-us/library/ms714428.aspx. Please make sure to not use spaces for script names. You can use spaces in commentary headers within the scripts though.

   The time stamp is given in the UTC.

3. Put the cursor at the beginning of the #<Script code here> line, press Shift+End and start typing the script. Since we want to create an interactive script, we want ExpertAssist to automatically wrap the output into a table. To do that, we need to load ExpertAssist built-in functions preparing formatted output into the runtime. This is done by declaring the dainclude.ps1 file:

   . .\dainclude

   Note: Make sure to have two dots and space between (. .) before the backslash (\). You may use slash (/) as well.

4. Next, we want the output table to have its title. The dainclude file contains the function htmlBeginOutput that indicates the start of the output data and creates the title. Let us name it according to the script name.

   htmlBeginOutput -title "Printer Drivers";

5. Following this line we want to prepare table columns. To query printer drivers on the remote compute we will use the Win32_PrinterDriver WMI class. We have to open MSDN or use the Get-Member cmdlet to retrieve the class properties. When done, we can select ones that fit our needs. For out test purposes, let’s select the following ones:

   Name

   Driver Path

   Configuration File

   Data File

   Dependent Files

   Help File

   Supported Platform

   To prepare the columns, we invoke the htmlBeginTable function and pass the properties that we want to check on the remote computer.

   htmlBeginTable "Name" "Driver Path" "Configuration File"`

   "Data File" "Dependent Files" "Help File" "Supported Platform";

   Note: You can use the backtick (`) to denote escape sequence and indicate line continuation. Please see Get-Help about_escape_character for more information.

6. Once we formed the table header, we can start to retrieve the data from the WMI. TO work with WMI we will use the Get-WMIObject cmdlet or its GWMI alias. Since the querying the Win32_PrinterDriver class returns an array, we will need to walk though it to select each of the desired properties passing the output to the ForEach-Object cmdlet via the pipe (|). Type the following on a new line:

   Gwmi Win32_PrinterDriver | ForEach-Object {

7. Now we need to form the table row. To do that, type:

   write-host "<tr>"

8. This is where we start to feed the table row with data using the <td> tag and selecting the properties found in the Win32_PrinterDriver class. Add the following line by line:

   write-host "<td>" $_.Name "</td>"

   write-host "<td>" $_.DriverPath"</td>"

   write-host "<td>" $_.ConfigFile "</td>"

   write-host "<td>" $_.DataFile "</td>"

   write-host "<td>" $_.DependentFiles "</td>"

   write-host "<td>" $_.HelpFile"</td>"

   write-host "<td>" $_.SupportedPlatform"</td>"

9. Once all the properties are selected, we have to close the row and end the loop by adding a line:

   write-host "</tr>"

   }

10. That is almost it and we are a couple of lines before finishing. All is left to do is to finish the table by invoking the htmlEndTable function (which is available in the dainclude.ps1) and terminate the output using the htmlEndOutput:

    htmlEndTable

    htmlEndOutput

    If we sum up, we will get this script:

    #

    # Printer Drivers

    #

    # ExpertAssist PowerShell Script

    # Created by PM\Gluon at 2009-06-10 18:33:54

    #

    . .\dainclude

     

    htmlBeginOutput -title "Printer Drivers";

    htmlBeginTable "Name" "Driver Path" "Configuration File" "Data File" "Dependent Files" "Help File" "Supported Platform";

     

    Gwmi Win32_PrinterDriver | ForEach-Object {

        write-host "<tr>"

        write-host "<td>" $_.Name "</td>"

        write-host "<td>" $_.DriverPath"</td>"

        write-host "<td>" $_.ConfigFile "</td>"

        write-host "<td>" $_.DataFile "</td>"

        write-host "<td>" $_.DependentFiles "</td>"

        write-host "<td>" $_.HelpFile"</td>"

        write-host "<td>" $_.SupportedPlatform"</td>"

        write-host "</tr>"

    }

     

    htmlEndTable

    htmlEndOutput

11. Click the Save button to create the script.

12. Locate the newly created script in the script table on the Scripts page and click the Printer Drivers script name for ExpertAssist to execute it.
13. When finished, ExpertAssist will return a neat table listing all the printer drivers found on the remote computer and their details.