PowerShell plugin

Currently only PowerShell v7 is supported for this plugin.

Run custom PowerShell scripts to retrieve and enhance data. This is useful for accessing third-party APIs and non-trivially manipulating the data you retrieve, beyond the capability of the Web API plugin.

Use cases for choosing the PowerShell plugin over Web API include:

  • Making requests to third-party APIs that require the timeframe variable a format different to ISO 8601 or Unix, you can manipulate the start and end times of the timeframe so that it matches the expected format.
  • Making calls to multiple third-party APIs and then combining the results.

Hybrid plugin

The PowerShell plugin is a "hybrid" plugin, meaning it is available in SquaredUp as both a cloud and an on-prem plugin.

  • Use the cloud plugin to visualize data from PowerShell scripts entered directly into SquaredUp when creating a tile. You do not need to configure a relay agent.
  • Use the on-prem plugin to a run user-created PowerShell scripts stored in a folder on your device, which can be selected when creating a tile.

Adding a data source

To add a data source click on the + next to Data Sources on the left-hand menu in SquaredUp. Search for the data source and click on it to open the Configure data source page.

Before you start

If you are adding a plugin marked as On-Prem, you will need a relay agent that can access the server hosting your on-prem data source. You do not need a relay agent for cloud plugins.

If you have already created a relay agent in SquaredUp that can access this data source, then you can skip this step and choose the agent group you want to use while Configuring the data source.

You can install an agent on either Windows or Linux:

Creating PowerShell scripts

If you are adding the cloud version of the plugin then you can simply enter your PowerShell scripts into the data stream parameters when editing a data tile. Additionally, when configuring the data source you can choose to define Variables to use in your scripts. See Creating Cloud PowerShell Scripts.

If you are adding the on-prem version, your scripts are stored locally and you must specify their location when configuring the data source. Additionally, you can create an import script if you want to import new objects into SquaredUp. See Creating On-Prem PowerShell Scripts.

Configuring the data source

  1. Display name:
    Enter a name for your data source. This helps you to identify this data source in the list of your data sources.

  2. Agent group :
    Select the Agent Group that contains the agent(s) you want to use.

  3. Variables :
    Optionally, click Add new variable to create a variable that can be added into your PowerShell data stream scripts. Variables are created as key value pairs and can be encrypted by clicking the padlock icon next to the entry field. Additional variables can be created by clicking Add another variable.
    See Configuring variables for more information.
  4. Scripts Directory :
    Enter the path to the directory where you store the PowerShell scripts on the machine you deployed the agent on.

    The path must be written as an absolute path, for example
    C:\Scripts\SquaredUpCloud
    or, if you are using a network share,
    \\fs01\Scripts\SquaredUpCloud

  5. Import Script :
    Optional. If you want to use a script for importing objects into SquaredUp, you can specify that script here by entering its full file name, for example get-objects.ps

    The import script must be stored in the same directory you defined above.

    See creating on-prem PowerShell scripts for detailed information on creating import scripts.

  6. (Optional) Restrict access to this data source:
    You can enable this option if you only want certain users or groups to have access to the data source, or the permission to link it to new workspaces. See data source access control for more information.

  7. Install dashboards :
    Select whether you would like to install pre-built dashboards and perspectives with the data source. By default, this is set to on.
  8. Click Add.

Testing and troubleshooting

If you encounter an error, please refer to the guidance provided below or contact [email protected] with as much detail as possible for assistance.

Why isn’t my script returning expected data?

We always recommend ensuring that any scripts will successfully run outside of SquaredUp in the first case, and that data is formatted and returned correctly. If everything looks okay, you may wish to review how the columns are being used in the shaping and columns tabs in the tile configuration.

Next steps

Dashboards

When configuring the cloud version of the data source, you have the option to install a pre-built dashboard. This option is recommended, as it provides a great starting point to understand how we expect data to be formatted to be compatible with the visualizations in SquaredUp.

The tiles calls an endpoint with static dummy data, so you can experiment and modify the queries as you see fit. Once you’re ready, you can adapt this to retrieve your own data from endpoints where SquaredUp doesn’t currently have built in data sources for.

Data streams

You can use these data streams to create new tiles to show data, or if there are preconfigured dashboards installed you can copy or edit those.

Data streams standardize data from all the different shapes and formats your tools use into a straightforward tabular format.

While creating a tile you can tweak data streams by grouping or aggregating specific columns.

Depending on the kind of data, SquaredUp will automatically suggest how to visualize the result, for example as a table or line graph.

Data streams can be either global or scoped:

  • Global data streams are unscoped and return information of a general nature (e.g. "Get the current number of unused hosts").
  • A scoped data stream gets information relevant to the specific set objects supplied in the tile scope (e.g. "Get the current session count for these hosts").

See Data Streams for more information.

The following data streams are installed with this plugin.

Cloud

Data stream
Description
Parameters
Run Script
This data stream allows you to enter and run custom PowerShell scripts via the Parameters.
See Creating Cloud PowerShell Scripts for instructions and examples.
  1. Script:
    Enter or paste your PowerShell script into this field. You can use the variables you defined when configuring the data source by entering $variable.variableName. For example, $variable.apiKey or $variable.password.
  2. JSON Depth:
    Enter the number of nested object levels required in the return payload. This option is useful if the return payload contains a significantly large number of nested objects.
  3. Click Test to execute the script. The Result box will show an example of the resulting payload.

On-prem

Data stream
Description
Parameters
Run Script On-Prem
This data stream allows you to enter and run custom PowerShell scripts stored on a device hosting a Relay Agent. Available in both a global version and a version that scopes to specified Data Source(s).
See Creating On-Prem PowerShell Scripts for instructions and examples.
  1. Script Path:
    Select a script to use. This dropdown displays the scripts you have configured in your scripts folder.
  2. Script Arguments:
    Optionally, enter any arguments required by the selected script. These are custom arguments set by the script author in the script itself.

    If the script is not expecting these parameters, including them will cause the stream to fail.

    Arguments are expressed as a JSON object, where the property name is the name of the parameter, and the value is what should be passed to the script. For example:
    { "TopN": 10, "filter": ["**/Bin", "*.zip"] }

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket