PowerShell plugin

For more information about what this plugin does and the data streams it retrieves, see:

PowerShell

This plugin is one of two available for PowerShell. Make sure to choose the correct version depending on your requirements:

Currently only PowerShell v7 is supported for these plugins

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.

How to add a PowerShell data source

  1. 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.

  2. Display Name:

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

  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 the value can be encrypted (for example, when creating a variable for an API key) by clicking the padlock icon next to the entry field. Additional variables can be created by clicking Add another variable.
    See Using the PowerShell data streams for more information on using PowerShell variables.
  4. Optionally, select whether you would like to restrict access to this data source instance. By default, restricted access is set to off.

  5. Click Add.

Using the PowerShell data streams

The Run Script data stream is installed with the data source.

Run Script

This data stream allows you to enter and run custom PoweShell scripts. This is the only data stream installed with the plugin.

  1. Select the Run Script data stream. Click Next to go to the Query tab.
  2. Script:
    Enter or paste your PowerShell script into this field. You can use the variables you defined when adding the data source (see How to add a PowerShell data source) by entering $variable.variableName. For example, $variable.apiKey or $variable.password.
  3. 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.
  4. Click Test to execute the script. The Result box will show an example of the resulting payload.
  5. Click Save.

Tips for using the PowerShell data stream

The only data stream installed with this plugin is Run Script, which provides an expansive toolkit to interact with the data you retrieve. Here you'll find tips and ideas for using the data stream to enhance and display the data you're interested in.

Benefits

This plugin enables you to go beyond simple web requests provided by 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.

Special variables

The following special variables are available when entering scripts in the Run Script data stream:

  • $variable: A dictionary of the variables entered in the plugin configuration (see How to add a PowerShell data source). For example, to access the value of a variable entered there named foo, you must enter $variable['foo'] or $variable.foo.
  • $timeframe: An object containing properties about the dashboard timeframe in force, for example:
    {
      "unixStart": 1697375649,
      "start": "2023-10-15T13:14:09Z",
      "unixEnd": 1697462049,
      "end": "2023-10-16T13:14:09Z",
      "enum": "last24hours",
      "interval": "PT15M"
    }

  • $targetNodes: The objects from the knowledge graph in scope. Intended for advanced users.

Returning data to tiles

Typically, PowerShell scripts supplied to this plugin are used to call third-party APIs to retrieve data, which can then be enhanced for visualization.

If the data returned from the script is a primitive scalar, it is only suitable for use with the Scalar visualization.

Otherwise, if the data is structured, it can always be used with the table visualization. Other visualizations will also be suitable if appropriate columns (object properties) are present.

Was this article helpful?


Have more questions or facing an issue?