Operations Manager Dashboard Script Widgets
This document is part of the Operations Manager Management Pack Authoring Guide. The Microsoft System Center team has validated this procedure as of Revision #4. We will continue to review any changes and periodically provide validations on later revisions as they are made. Please feel free to make any corrections or additions to this procedure that you think would assist other users.
Introduction
Most dashboard widgets allow you to display information in a dashboard by following a simple wizard. These widgets display valuable information, but they are limited to specific data and specific formatting. PowerShell widgets allow you display virtually any information in a dashboard and have considerable control over its formatting. Instead of just following a wizard though, you will need to understand how to write a script to run inside of the widget.
The dashboard widgets in the following table run a PowerShell script. Detailed information on each widget and the concepts common to each script widget are provided in this topic.
Widget |
Description |
PowerShell Grid Widget |
Displays the results of a Windows PowerShell script in a grid. |
PowerShell Web Browser Widget |
Displays the output of a web page retrieved by a PowerShell script. |
Common Concepts
The following sections describe concepts that are common to each script widget.
ScriptContext Object
ScriptContext is a helper object providing required methods and properties to scripts used in the PowerShell widgets. The object is passed as a global variable to all PowerShell scripts that run in the context of a dashboard. Each script that you create for a dashboard will use ScriptContext to create and return the data displayed in the widget.
The ScriptContext object only exists when a script is run in the context of the dashboard, so there is no ability to test it prior to using it in the management pack. You can test your script with the lines using ScriptContext to at least ensure that it is collecting and returning proper data.
Reference information for the properties and methods of ScriptContext are provided in ScriptContext Object.
Returning Data from a Script
You return data from a script in a dashboard widget by setting a value for the ReturnCollection property of the ScriptContext object. You will use methods of ScriptContext such as CreateFromObject and CreateInstance to create the DataObject that you will add to the Return Collection. When the script completes, the widget will read the contents of ReturnCollection and format it for display in the dashboard. For a PowerShell Grid Widget, the data in ReturnCollection is formatted into a grid. A PowerShell Web Browser Widget expects the output of a web page that it will display in the dashboard.
Contextual Script Widgets
A contextual widget is one that can accept data from another widget in the dashboard. When you select an object in the first widget, the contextual widget is updated and can use data from the first widget to determine what it should display. For example, you might have a list of objects in one widget and want to display details about an object when it is selected in the first widget.
In order to make a script contextual, you add a parameter to the script called globalSelectedItems. This variable will include a collection of any objects or alerts that are selected in another widget in the dashboard. Your script can then use this variable to access information from the selected items in order to determine the information to display in the widget. If the parameter is included, then the script will run and refresh its data each time another object or alert is selected.
PowerShell Grid Widget
The PowerShell Grid Widget displays the results of a Windows PowerShell script in a grid. The script will run on the computer with the console and will typically use the Operations Manager cmdlets to retrieve information from the management group. It must then use the ScriptContext object to create a Data Object and then add that object to the ReturnCollection property.
Examples
The following sample script creates a table of numbered Windows Computer objects and displays the ID, health state, and display name for each. This script uses CreateFromObject to create the Data Object. Note that this script is not contextual because it does not use the globalSelectedItems parameter.
$class = Get-SCOMClass -Name Microsoft.Windows.Computer
$computers = Get-SCOMClassInstance -Class $class
$i=1
foreach ($computer in $computers)
{
$dataObject=$ScriptContext.CreateFromObject($computer,"Id=Id,HealthState=HealthState,DisplayName=DisplayName",$null)
$dataObject["CustomColumn"]=$i
$ScriptContext.ReturnCollection.Add($dataObject)
$i++
}
The following sample script allows you to select a computer in a widget using the previous sample script and displays the ID, health state, and display name of each of the objects related to the selected computer. Note that you can select multiple items as $globalSelectedItems will contain the collection all objects selected.
Param($globalSelectedItems)
foreach ($globalSelectedItem in $globalSelectedItems)
{
$globalSelectedItemInstance = Get-SCOMClassInstance -Id $globalSelectedItem["Id"]
foreach ($relatedItem in $globalSelectedItemInstance.GetRelatedMonitoringObjects())
{
$dataObject=$ScriptContext.CreateFromObject($relatedItem,"Id=Id,State=HealthState,DisplayName=DisplayName",$null)
$dataObject["ParentRelatedObject"] = $globalSelectedItemInstance.DisplayName
$ScriptContext.ReturnCollection.Add($dataObject)
}
}
You can download an example of a PowerShell Grid widget from SCOM Script Widgets Sample Dashboards.
PowerShell Web Browser Widget
The PowerShell Web Browser Widget displays the output of a web page requested by a Windows PowerShell script. This will typically follow one of four scenarios:
- A simple web page requiring no parameters.
- A Get request using parameters with properties of the selected object.
- A Post request passing data to a web page.
- A custom web page written to interact with the Operations Console.
Simple Web Request
In a simple web request, you are just displaying a static web page in the widget. You can pass parameters to it in the request, but they will be the same parameter values each time the page is requested.
Note that this scenario is typically a precursor to the other scenarios since you can achieve the same results without a script using the Web Browser Widget.
To create a simple web request, you start by creating a Data Object using the CreateInstance method of ScriptContext to create an instance of the Request class. You then set the BaseURL property of the Data Object before adding it to the Return Collection.
Example
The following script displays the Management Pack Authoring Guide.
$dataObject = $ScriptContext.CreateInstance("xsd://Microsoft.SystemCenter.Visualization.Component.Library!Microsoft.SystemCenter.Visualization.Component.Library.WebBrowser.Schema/Request")
$dataObject["BaseUrl"]="http://aka.ms/mpauthor"
$ScriptContext.ReturnCollection.Add($dataObject)
Get Request with Parameters
The Get Request with Parameters scenario allows you to customize a web request for any items selected in the dashboard. In this scenario, you build a web request with parameter values from one or more selected objects. This allows you to perform such actions as looking up information on a selected alert or requesting information on a selected object in another system accessible through HTTP.
To create a web request with parameters, you start with a simple web request. You then create a collection of parameters with values from the globalSelectedItems variable and add the collection to the Parameters property of the Data Object.
Example
The following script performs a Bing lookup for information on an alert selected in the dashboard. It then builds a query to be sent to www.bing.com/search. The query is specified in a parameter called q. In this case, the script builds a query with “opsmgr alert” followed by the name of the alert.
The request object created in this example is the same as the request object in the previous example for a simple web request. A parameter collection is added to this request to hold the parameter values. Note that a set of parameters is added for each selected item in case multiple items are selected.
Param($globalSelectedItems)
$dataObject = $ScriptContext.CreateInstance("xsd://Microsoft.SystemCenter.Visualization.Component.Library!Microsoft.SystemCenter.Visualization.Component.Library.WebBrowser.Schema/Request")
$dataObject["BaseUrl"]="http://www.bing.com/search ; "
$parameterCollection=$ScriptContext.CreateCollection("xsd://Microsoft.SystemCenter.Visualization.Component.Library!Microsoft.SystemCenter.Visualization.Component.Library.WebBrowser.Schema/UrlParameter[]")
foreach ($globalSelectedItem in $globalSelectedItems)
{
$parameter=$ScriptContext.CreateInstance("xsd://Microsoft.SystemCenter.Visualization.Component.Library!Microsoft.SystemCenter.Visualization.Component.Library.WebBrowser.Schema/UrlParameter")
$parameter["Name"] = "q"
$alert = Get-SCOMAlert -Id $globalSelectedItem["Id"]
$parameter["Value"] = "opsmgr alert `"" + $alert.Name + "`""
$parameterCollection.Add($parameter)
}
$dataObject["Parameters"]= $parameterCollection
$ScriptContext.ReturnCollection.Add($dataObject)
You can download an example of a Get Request with Parameters with the PowerShell Web Browser widget from SCOM Script Widgets Sample Dashboards.
Post Request with Data
The Post Request with Data is similar to a Get Request with Parameters except that the request is a Post instead of a Get. A Post request includes data that is sent to the web page.
You create a Post request by populating the PostData property of the Request object with the data to post to the web page. If this property is populated, then the widget will assume that the request is a Post instead of a Get.
The Content Type of the request is defined in the Headers property of the Request object. The default Content Type is application/json meaning the widget will submit any data as Json. If the web page that you are submitting the Post request to requires a different content type, then you must set this type in the Header property.
Example and details of formatting post request to be added shortly.
Note that this method is not supported in the Web Console because of limitations in Silverlight.
Custom Web Page
The Custom Web Page scenario allows you complete flexibility over the data that you retrieve and how it is formatted. In this scenario, you build a script to run in the Operations Manager console and a web page to be processed on a web server. The HTML that is returned to the widget can include client side JavaScript or HTML links that interact with the console providing additional functionality to the user. There are no additional components that must be installed on the web server as the web page uses standard methods to construct a script or link that is processed by the console.
A custom web page can replace the requirement for a custom widget and provides the following advantages:
- Developers can create visualizations using standard web development with minimal knowledge of Operations Manager and with less complexity than creating a custom widget.
- Processing of the widget is offloaded to a web server rather than then the console potentially improving performance.
The script can create either a Get or Post request depending on how you choose to write the web page. It will typically be a Post request with a data object created by the script. If the data is a Data Object created by ScriptContext then it is converted to JSON before it is sent to the web server.
The script creates a post request by populating the PostData property of the Request object with the Data Object. The web page accepts the data and return results back to the console in HTML. The web page can interact with the console using methods of window.external in client side scripts or using the console protocol in hyperlinks.
While ASPX is shown in this diagram, any web server capable of creating standard JavaScript and HTML can be used.
It should be noted that Post requests are not supported in the Web Console because of limitations in Silverlight.
Example
You can download an example of a custom web page with the PowerShell Web Browser widget from SCOM Script Widgets Sample Dashboards.
Interaction with the Console
When you create a custom web page to process to be displayed in a dashboard, you can provide the user with the ability to interact with the console providing an experience similar to other widgets. You have two choices to implement this interaction depending on your preferences:
- The page can include client side JavaScript using the Console Integration Scripting Object.
- The page can include links using the console protocol.
Each of these methods is described in detail in the following sections.
Console Integration Scripting Object
The Operations Manager consoles include a JavaScript environment so that any client side JavaScript delivered from the web page can be executed. The window.external object in JavaScript provides access to functionality of the environment hosting the web page. In the case of the Operations Manager consoles, this functionality is provided by the Console Integration Scripting Object. The methods of this object are run in the context of the console, so you provide the user the ability to interact with the dashboard.
The Console Integration Object has the methods in the following table.
Method |
Description |
Usage |
IsConsoleConnected |
Returns a Boolean value that specifies whether the web page is executed in the Operations Console or Web Console. |
window.external.IsConsoleConnected |
SetSelectedObjects |
Selects one or more objects in the dashboard. |
window.external. SetSelectedObjects(GUID) |
SetSelectedAlerts |
Selects one or more alerts in the dashboard. |
window.external. SetSelectedAlerts(GUID) |
OpenDashboard |
Opens a dashboard passing in one or more objects as targets for the dashboard. |
window.external. OpenDashboard(MP_ID!Dashboard_ID,GUID) |
ShowContextMenu() |
Displays the context menu in the Operations Console. |
window.external. ShowContextMenu() |
Example
For example, the following code could be used in a client side script to display the context menu for an object displayed in the widget. This function expects the ID for the selected object to be provided and then checks the IsConsoleConnected property to determine whether the page is being hosted in a console. If it isn't, then the other methods would not be available since the host of the web page wouldn't have the required object. This ensures that the page doesn't generate an error if it’s being viewed in a browser.
The SetSelectedObjects method is used with the ID of the object to set the focus of the page to that object. The ShowContextMenu method is then called in order to display the context menu for the selected object.
<script>
function ShowContextMenu(id) {
if (window.external.IsConsoleConnected) {
window.external.SetSelectedObjects(id);
window.external.ShowContextMenu();
return false;
}
return true;
}
</script>
Console Integration URLs
Rather than using JavaScript, the page can include HTML links that use the console protocol which provides functionality for interacting with Operations Manager consoles. This protocol can be used in HTML links that are displayed in an Operations Manager dashboard.
The following table lists the methods that can be used with the console links.
Method |
Description |
Usage |
SetSelectedItems |
Sets a list of selected items in the console. |
console:SetSelectedItems?ObjectId={GUID}&AlertId={GUID} |
OpenDashboard |
Opens a dashboard by dashboard type passing a list of objects as a dashboard target. |
console:OpenDashboard?ComponentType={MP_ID!ComponentType_ID}&ObjectId={GUID} |
ShowContextMenu |
Displays the console context menu. |
Console:ShowContextMenu |
Execute |
Executes an Operations Manager task or opens an Operations Manager view. You must provide one or more parameters to specify the task or view and any targets. The parameters are listed in the table below. |
console:execute?{ParameterName}={ParameterValue}&{ParameterName}={ParameterValue}… |
The following table lists that parameter names that you can use with console:execute.
Parameter |
Value |
ManagementPack |
Management Pack ID |
TaskId |
GUID of task to run |
TaskName |
ID of task to run |
TaskTarget |
Array of GUIDs of targets of task |
| ViewId | GUID of view to open |
| ViewName | ID of view to open |
| ViewTarget | Array of GUIDs of targets of view |
Example
For example, the following HTML could be included in a web page to display the name of a computer with a link that runs the task to perform a ping. In this case, the Id property of the computer is provided as a target for the task.
<a href="<%# DataBinder.Eval(Container.DataItem, "Id", "console:execute?taskname=Microsoft.Windows.OperatingSystem.PingDefault&tasktarget={0}") %>" >
<%# DataBinder.Eval(Container.DataItem, "DisplayName") %>
</a>