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:

• PowerShell plugin: Visualize data from PowerShell scripts (cloud only).
• PowerShell On-Premise plugin: Run user-created PowerShell scripts on Relay Agents.

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

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

3. Optionally, select whether you would like to restrict access to this data source instance. By default, restricted access is set to off.

   Restrict access to this data source

   The term data source here really means data source instance. For example, a user may configure two instances of the AWS data source, one for their development environment and one for production. In that case, each data source instance has its own access control settings.

   By default, Restrict access to this data source is set to off. The data source can be viewed, edited and administered by anyone. If you would like to control who has access to this data source, switch Restrict access to this data source to on.

   Use the Restrict access to this data source dropdown to control who has access to the workspace:

   • By default, the user setting the permissions for the data source will be given Full Control and the Everyone group will be given Link to workspace permissions.
   • Tailor access to the data source, as required, by selecting individual users or user groups from the dropdown and giving them Link to workspace or Full Control permissions.
   • If the user is not available from the dropdown, you are able to invite them to the data source by typing in their email address and then clicking Add. The new user will then receive an email inviting them to create an account on SquaredUp. Once the account has been created, they will gain access to the organization.
   • At least one user or group must be given Full Control.
   • Admin users can edit the configuration, modify the Access Control List (ACL) and delete the data source, regardless of the ACL chosen.

   Data source access levels

   Access Level:

   Link to workspace	User can link the data source to any workspace they have at least Editor permissions for. Data from the data source can then be viewed by anyone with any access to the workspace. User can share the data source data with anyone they want. User cannot configure the data source in any way, or delete it.
   Full Control	User can change the data source configuration, ACL, and delete the data source.

   See Access control for more information.

4. Click Add.

Using the PowerShell data streams

Data streams

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.

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.

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:
  Copy

  {
    "unixStart": 1697375649,
    "start": "2023-10-15T13:14:09Z",
    "unixEnd": 1697462049,
    "end": "2023-10-16T13:14:09Z",
    "enum": "last24hours",
    "interval": "PT15M"
  }

  What is the dashboard timeframe?

  The dashboard timeframe is the current timeframe setting for a dashboard. Users can change the dashboard timeframe to see data for a different time span, for example, instead of showing data from "the last 12 hours" it can be changed to show data from "the last 7 days".

  Tiles can be configured to:

  • Use dashboard timeframe (default). For these tiles the data shown will change when the user changes the dashboard timeframe.
  • Use a fixed timeframe from the options available. These tiles show a clock icon and hovering shows the fixed timeframe configured. The data will not change when the dashboard timeframe is changed.

  If the dashboard timeframe is unavailable, such as when all the tiles on that dashboard are using a fixed timeframe, then the button is disabled. Likewise, if a specific timeframe is unsupported then it is disabled in the timeframe picker.

  Set a default dashboard timeframe

  To set the default dashboard timeframe, click the pin icon

  when using the dashboard timeframe picker. This sets the initial timeframe for all viewers of the dashboard, including shared dashboards.

  Tip: Indicate with the name of a tile if the tile's timeframe can be changed. For example, naming a tile "Performance during the last week" tells users that this tile always shows data for the last week. Naming a tile just "Performance" indicates to users that changing the dashboard timeframe will change the data.

• $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.