Extending the Console Query interface

NightWatchman Management Center provides a Queries tab in the Clients section of the console for exploring the computers in a network that are running the 1E Agent. Using this tab NightWatchman administrators can run queries to retrieve a set of computers that match a set of requirements. The context menu can now be used to run actions against the results.

This page shows how to create user-defined actions that may be run not only from the Queries tab but also from the Organization and Location tabs. The actions are added via the console extensions file.

The console extensions file

Any actions you define must be added to the console extensions XML format file. This file is called Console.Extensions.xml and normally resides in the following folder on 64-bit OS:

C:\Program Files (x86)\1E\NightWatchman Management Center\Console

and on 32-bit OS in the following folder:

C:\Program Files\1E\NightWatchman Management Center\Console

The file is optional if it is not present then no extensions will be visible in the NightWatchman Management Center console. Likewise if there are errors in the file that make it invalid.

Access to administrator defined queries and actions

There are three main implementation modes for the console extensions file, as described in the following table:

Configuration	Description
Each installation of the NightWatchman Management Center Console uses its own console extensions file.	The default configuration is for a single console extensions file residing in one of the folders shown above. This would mean that any NightWatchman Management Console user with permissions on any of the tabs in the Clients section of the console would be able to run the actions defined in the console extensions file.
Each user of an installation of the NightWatchman Management Center Console uses their own console extensions file.	To allow each NightWatchman Management Console user, with the appropriate permissions, to have access to just their own set of actions requires the following steps: Edit the NWM.Console.exe.config file, contained in the same folder as the default Console.Extensions.xml folder. Add the following Extensions.Folder key under the appSettings section, as illustrated below, being careful not to modify any of the other keys in that section: Copy `<appSettings> ... <add key="Extensions.Folder" value="%LOCALAPPDATA%\1E\NightWatchman Management Center\Console"/> ... <appSettings>` Once this has been set each user would then be able to maintain their own copy of the extensions file.
All installations of the NightWatchman Management Center Console use a single console extensions file.	To support this scenario you point the extensions folder to a shared network drive: Edit the NWM.Console.exe.config file, contained in the same folder as the default Console.Extensions.xml folder. Add the Extensions.Folder key under the appSettings section, as illustrated below, being careful not to modify any of the other keys in that section: Copy `<appSettings> ... <add key="Extensions.Folder" value="U:\NightWatchmanConsole"/> ... <appSettings>` When this is set for a NightWatchman Management Center console it will then use the single Console.Extensions.xml file placed in the shared network drive.

Configuration

Description

Each installation of the NightWatchman Management Center Console uses its own console extensions file.

The default configuration is for a single console extensions file residing in one of the folders shown above. This would mean that any NightWatchman Management Console user with permissions on any of the tabs in the Clients section of the console would be able to run the actions defined in the console extensions file.

Each user of an installation of the NightWatchman Management Center Console uses their own console extensions file.

To allow each NightWatchman Management Console user, with the appropriate permissions, to have access to just their own set of actions requires the following steps:

Edit the NWM.Console.exe.config file, contained in the same folder as the default Console.Extensions.xml folder.
Add the following Extensions.Folder key under the appSettings section, as illustrated below, being careful not to modify any of the other keys in that section:
Copy
```
<appSettings>
...
<add key="Extensions.Folder" value="%LOCALAPPDATA%\1E\NightWatchman Management Center\Console"/>
...
<appSettings>
```
Once this has been set each user would then be able to maintain their own copy of the extensions file.

All installations of the NightWatchman Management Center Console use a single console extensions file.

To support this scenario you point the extensions folder to a shared network drive:

Edit the NWM.Console.exe.config file, contained in the same folder as the default Console.Extensions.xml folder.
Add the Extensions.Folder key under the appSettings section, as illustrated below, being careful not to modify any of the other keys in that section:
Copy
```
<appSettings>
...
<add key="Extensions.Folder" value="U:\NightWatchmanConsole"/>
...
<appSettings>
```
When this is set for a NightWatchman Management Center console it will then use the single Console.Extensions.xml file placed in the shared network drive.

Example console extensions file

An example file containing some pre-defined actions is created during installation in one of the locations described above, depending on which OS NightWatchman Management Center has been installed on. The example file is called Console.Extensions.xml.template to enable the actions in the template you only need to rename it to Console.Extensions.xml.

Adding new actions

When a NightWatchman Management Center console user browses through the hierarchies on the Location or Organization tabs or when they submit queries from the Queries tab a right-click context menu is available for any selections that have been made. Using this right-click context menu the NightWatchman Management Center console user can interact with the selection to run tasks, such as on-demand wakeups or display properties dialogs.

The context menu also supports the ability to run arbitrary actions on the selections, but these must be configured beforehand. By default the Actions sub-menu is not displayed as NightWatchman does not come with any actions defined. This section describes how to configure those actions and also shows how to enable the example console extensions file provided with the NightWatchman Management Center installation.

Security

If a NightWatchman Management Console user has permissions to view any of the tabs in the Clients section they will also be able to see the actions defined in the console extensions file. The actions displayed will depend on the context that the user has selected. When running an action the credentials of the NightWatchman Management Console user are used. This means that the user can run any action they have permissions for, basically the equivalent of that user running the command-line for the action from the Run dialog.

The anatomy of the console extensions file

The console extensions file is an XML file that contains one or more context extension definitions. The file has the following general format:

Copy

<ContextExtensions>
...
   <!-- One or more context extension definitions -->
...
</ContextExtensions>

The anatomy of an context extension

Each context extension definition defines an individual item on the context sensitive menu in the console including its name and when it should appear. The following example shows the structure of each definition:

Copy

<ContextExtension Name="My Extension" 
                      Scope="Computer" 
                      Description="The description of my extension" 
                      CommandLine=""/>

Each definition consists of the following parameters:

Parameter	Description
Name	This is the text that appears in the right-click context menu.
Description	This is the tooltip text that appears when hovering over the item in the right-click context menu.
Scope	The scope defines when the item will appear in the right-click context menu. It can be set to one of the following values: Computer: Visible when exactly one computer has been selected in the results. Tier: Visible when right-clicking on a location or organization tier. ComputerSet: Visible when one or more computers have been selected in the results.
CommandLine	This defines the command-line for the action to be executed, including any placeholders.

The attributes are case sensitive so they must be typed using the same case as used in the table. XML escape entities (e.g. " or &) should be used as appropriate. Each scope has a set of associated placeholders.

Placeholders

Placeholders can be used to enable substitutions for various parameters that get passed to the command-line. The placeholders that are available are dependent on the scope of the action.

Computer

The following table shows the placeholders supported for the Computer scope, with descriptions and some example substituted values:

Placeholder	Substituted Value	Example substituted value
{$ComputerId}	The configuration item ID (from tbAFR_Dimension_ConfigurationItem) of the selected computer	3187
{$NetbiosName}	The NetBIOS computer name of the selected computer	ACMEDVWKS127
{$DomainName}	The NetBIOS domain name of the selected computer	1E

Tier

The following table shows the placeholders supported for the Tier scope, with descriptions and some example substituted values:

Placeholder	Substituted Value	Example substituted value
{$TierId}	The tier ID (from tbAFR_Dimension_Tier) of the selected tier	18
{$TierLevelId}	The tier level ID (from tbAFR_Lookup_TierLevel) of the selected tier. In practice, these values are fixed.	1040 or 2060
{$TierType}	The type of tier	Organization or Location
{$TierName}	The name of the tier	London or Marketing or UNASSIGNED BUILDING or All Locations

ComputerSet

The following table shows the placeholders supported for the ComputerSet scope, with descriptions and some example substituted values:

Placeholder	Substituted Value	Example substituted value
{$ComputerListFileName}	A NWMC_SelectedQueryResult_{GUID}.csv file generated under the current user's temp folder. The contents of the CSV file represent the selection of machines the extension has been run against. The CSV file has three columns - ConfigurationItemId, DomainName, and NetbiosName. There is no header row.	C:\Users\<USERNAME>\AppData\Local\Temp\NWMC_SelectedQueryResult_9d94c5e8-54f4-4f9c-a5f5-b5a38487e872.csv

Placeholder

Substituted Value

Example substituted value

{$ComputerListFileName}

A NWMC_SelectedQueryResult_{GUID}.csv file generated under the current user's temp folder. The contents of the CSV file represent the selection of machines the extension has been run against.

The CSV file has three columns - ConfigurationItemId, DomainName, and NetbiosName. There is no header row.

C:\Users\<USERNAME>\AppData\Local\Temp\NWMC_SelectedQueryResult_9d94c5e8-54f4-4f9c-a5f5-b5a38487e872.csv

Examples

Computer

The following XML definition defines a right-click context menu item called Remote Desktop that will be visible when a single computer has been selected from either of the location or organization hierarchies or from the results of submitting a query. When selected the action will launch a remote desktop session using the selected computer's NetBIOS name.

Copy

  <ContextExtension Name="Remote Desktop"
                    Scope="Computer"
                    Description="Launch Remote Desktop session"
                    CommandLine="mstsc /v {$NetbiosName}" />

The next extension definition defines a right-click c ontext menu item called Manage Computer that will be visible when a single computer has been selected from either of the location or organization hierarchies or from the results of submitting a query. When selected the action will launch the Windows computer management console using the domain the computer belongs to and its NetBIOS name.

Copy

<ContextExtension Name="Manage Computer" 
                      Scope="Computer" 
                      Description="Launch Windows Computer Management Console" 
                      CommandLine="mmc.exe compmgmt.msc /computer:{$DomainName}\{$NetbiosName}" />

Tier

This extension definition creates a right-click c ontext menu item called Run "my script" that will be visible when a computer tier has been selected from either the Organization or Location tabs.

Copy

<ContextExtension Name="Run &quot;my script&quot;" 
                      Scope="Tier" 
                      Description="Run my script" 
                      CommandLine="cscript.exe C:\MyScripts\MyScript.vbs {$TierId} {$TierLevelId} {$TierType} &quot;{$TierName}&quot;"/>

See how " is used to enclose the tier name in double quotes, this is good practice as the tier name may contain spaces.

When selected this action will run a command similar to the following:

Copy

cscript.exe C:\MyScripts\MyScript.vbs 17 2012 Organization "Sales and Marketing"

ComputerSet

For the ComputerSet scope, you may use the {$ComputerListFileName} placeholder. This placeholder is translated to the full pathname of a temporary file which contains a CSV of the ComputerId, DomainName and NetbiosName of each computer in the selection. Your script should then parse this file as required and take the appropriate actions. This file will be deleted automatically after you have used it.

The following console extension definition creates a right-click context menu item called Run my complex script that will be visible when multiple computers have been selected from either of the location or organization hierarchies or from the results of submitting a query.

Copy

<ContextExtension Name="Run my complex script" 
                      Scope="ComputerSet" 
                      Description="Run my script against multiple PCs" 
                      CommandLine="cscript.exe C:\MyScripts\MyScript.vbs &quot;{$ComputerListFileName}&quot;" />

Running this action would execute MyScript.vbs, which would then contain basic parsing logic to read the CSV, for example:

Copy

' Open CSV file (passed as command-line argument)
strCsvFilename = WScript.Arguments.Item(0)
Set objFSO = CreateObject("Scripting.FileSystemObject")
Const ForReading = 1
Set objFile = objFSO.OpenTextFile(strCsvFilename, ForReading)
' Iterate for each entry
Do Until objFile.AtEndOfStream
        strLine = objFile.ReadLine
        arrFields = Split(strLine, ",")

        strComputerId = arrFields(0)
        strDomainName = arrFields(1)
        strNetbiosName = arrFields(2)
        ' TODO: Your per-machine logic might come here
Loop
' Close CSV file
objFile.Close