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.
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.
You can also add a data source by clicking Add data source on the Settings > Data Sources page, but pre-built dashboards are not added when using this method.
Display name: Enter a name for your data source. This helps you to identify this data source in the list of your data sources.
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.
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.
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.
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.
When configuring the Powershell data source, you have the option to Install a pre-built dashboard. This is recommended to help provide a great starting point to understand how we expect data to be formatted to be compatible with the visualizations in SquaredUp.
The tiles are calling an endpoint with some static dummy data so feel free to experiment and modify the query’s as you see fit. Once you’re ready, you may wish to adapt this to retrieve your own data from endpoints where SquaredUp doesn’t currently have built in data sources for.
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").
The following data streams are installed with this plugin.
Run Script
This data stream allows you to enter and run custom PoweShell scripts. This is the only data stream installed with the plugin.
Select the Run Script data stream. Click Next to go to the Query tab.
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.
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.
Click Test to execute the script. The Result box will show an example of the resulting payload.
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:
The dashboard timeframe setting lets you choose the time span that a dashboard displays data for. For example, instead of showing data from the last 12 hours, you can choose to show data from the last 7 days.
Tiles on a dashboard inherit that dashboard's timeframe by default, meaning that the tile data shown changes whenever you change the dashboard timeframe. However, you can instead choose to set a fixed timeframe for a tile via its timeframe setting.
Fixed-timeframe tiles display their set timeframe in a bubble next to their title and the tile data does not change when the dashboard timeframe is changed.If all the tiles on a dashboard use a fixed timeframe then the timeframe dropdown is disabled. Likewise, if a specific timeframe is unsupported then it is disabled in the dropdown.
You should indicate if a tile's timeframe can be changed in the name of a tile. For example, naming a tile Performance during the last week indicated that the tile always displays data for the last week.
As well as determining the period for the data that displays, the dashboard timeframe also controls the cache refresh frequency of that data. In other words, the timeframe you pick also affects how "fresh" that data is.
Dashboard timeframe
Cache expiry
1 hour
1 minute
12 hours
5 minutes
24 hours
15 minutes
7 days
6 hours
30 days
12 hours
Up to 6 months
24 hours
Over 6 months
7 days
$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.
