Export-CUQuery

Introduction

The Export-CUQuery cmdlet queries the current state of the monitor cluster and exports the results to a CSV or JSON file. The export to a file is what makes the difference between this cmdlet and the Invoke-CUQuery. Use the latter to query a small dataset. If the result set is expected to be higher than 100, as this is the limitation of the Invoke-CUQuery cmdlet, we recommend using the Export-CUQuery cmdlet to reduce the load on the monitor cluster.

Before using this cmdlet, we recommend reading the Monitor Cluster PowerShell API cmdlets article in which you can learn how to use the new PowerShell cmdlets.

Prerequisites

• ControlUp version 8.6.5 or higher
• At least one ControlUp Monitor installed
• Permissions to run scripts on the monitor machines

Syntax

Export-CUQuery
[[-OutputFolder] <string>] 
[[-Scheme] <string>] 
[-Table] <string> 
[-Fields] <string[]> 
[[-Where] <string>] 
[[-Focus] <string>] 
[[-Search] <string>] 
[[-SearchField] <string>] 
[[-TranslateEnums] <SwitchParameter>] 
[[-FileName] <string>] 
[[-FileFormat] <int>] [<CommonParameters>]

Parameters

OutputFolder

Defines the folder for the output file. If you do not use this parameter, the current directory is used.

Parameter Syntax
Type: String
Mandatory: no
Position: 1
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Scheme

Scheme is the name of the index the table is queried on. There are several indices for internal use of the cluster. The "Main" index holds all ControlUp entities. If you do not specify a scheme, the Main scheme is used per default.

Parameter Syntax
Type: String
Mandatory: no
Position: 2
Default value: Main
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Table

Tables are logical containers for ControlUp entities. This parameter is mandatory and you can find all values here.
The logic is as follows: If you are looking for data pertaining to processes, you should use -table Processes. To retrieve information about monitored sessions, use -table Sessions, etc.

Parameter Syntax
Type: String
Mandatory: yes
Position: 3
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Fields

The fields argument represents the column name of a specific table. Refer to the column reference table in the ControlUp Monitor: PowerShell Cmdlet Overview article to see which arguments you can use in the Fields parameter.

Another way to see which fields are available for a specific table is to use an asterix (*) after the Fields parameter. For example, to see all the fields of the Computers table, you can use:

(Invoke-CUQuery -Table Computers -Fields *).Data | get-member -MemberType NoteProperty

Parameter Syntax
Mandatory: yes
Position: 4
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Where

Use the Where parameters if you want to specify a filter for query results. You can use the following logical operators: OR, AND, NOT. In comparison operators, string values must be enclosed in single quotes.

Parameter Syntax
Type: String
Mandatory: no
Position: 5
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Focus

With the Focus parameter you can define a folder name in your ControlUp organization tree, to show results only from a specific folder. If no value is provided, all objects from your ControlUp organization tree are returned.

Parameter Syntax
Type: String
Mandatory: no
Position: 6
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Search

The Search parameter specifies a filter for text fields. Use an asterix (*) to match a sequence of any characters (including empty string). The Search pattern is case-insensitive.

Parameter Syntax
Type: String
Mandatory: no
Position: 7
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

SearchField

If you want to search your result set then using the Search parameters is a great way to do so. If you are using multiple selectors in the Fields parameter then using the Search parameters without SearchField might not be the right choice for your use case. A simple definition: You search for a string (Search argument) in a specific field (SpecificField argument).

Parameter Syntax
Type: String
Mandatory: no
Position: 8
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

TranslateEnums

The TranslateEnums parameter converts an enumerator into a human-readable format. In some cases the connection states are shown as integers (e.g. 0 for "Disconnected" or 1 for "Connected").

Parameter Syntax
Type: SwitchParameter
Mandatory: no
Position: 9
Default value: False
Accept pipeline input: false
Accept wildcard characters: false

FileName

Specifies the file name for the export file.

Parameter Syntax
Type: String
Mandatory: no
Position: 10
Default value:
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

FileFormat

Specifies the format of the output file. You can either use “CSV“ or “JSON”.

Parameter Syntax
Type: String
Mandatory: no
Position: 11
Default value: 0
Accept pipeline input: true (ByPropertyName)
Accept wildcard characters: false

Examples

The following examples demonstrate how to use Export-CUQuery. We extend the examples from the Invoke-CUQuery cmdlet with the three parameters specific to the Export-CUQuery cmdlet.

Example 1 - Get all monitored machines and save result set to specific folder

(Export-CUQuery -OutputFolder C:\temp -Table Computers -Fields *).Data

This command creates a CSV file that contains information about machines. The OutputFolder parameter defines the location of the exported file. The file that is created is a CSV file with the file name Table_YYYY_MM_DD_HH_mm_ss.csv.

Example 2 - Get all running monitored processes and save result to a JSON file

(Export-CUQuery -OutputFolder C:\temp -Table Processes -Fields * -FileName AllProcesses -FileFormat Json).Data

As mentioned above, the only difference between the Invoke-CUQuery and Export-CUQuery commands are the three parameters OutputFolder, FileName and FileFormat. All three are used in this example which exports information about all processes to a AllProcesses.json file in the C:\temp folder.

Example 3 - Search for a process name and export all information related to this process

Export-CUQuery -Fields * -Table Processes -FileName ProcessesInfo -Search chrome -SearchField sName

This example illustrates how to search for a string in a particular field. Here, we search for chrome in the sName field in the Processes table. The ProccessInfo.csv file contains data for the results found by this command.

Example 4 - Query all user sessions (without system sessions)

In this example, all user sessions are exported, excluding system sessions.

Export-CUQuery -Scheme Main -Table Sessions -Fields iSessionID,sUserAccount -TranslateEnums -Where "sUserAccount!=''"