PowerShell On-Prem plugin

Note

Currently only PowerShell v7 is supported for this plugin.

Click the following link for additional content such as blogs, videos, use cases, and more:

PowerShell

Visualize data from PowerShell scripts that run on your relay agents. Use this plugin when your scripts are stored on your own servers, or need to reach systems on your private network.

Do you need a relay agent?

This plugin runs scripts stored on a machine with a relay agent. If you don't need to reach your own servers, use the PowerShell plugin instead, and write your scripts in the data stream parameters.

An on-prem data source uses a relay agent to connect SquaredUp to a data source running on your internal network.

Relay agents allow you to securely connect to data sources inside your own network (on-prem).

A relay agent is installed on a server on your internal network, and has access to your data source.

When a plugin uses a relay agent it means that you don't need to open your firewall to allow SquaredUp access to the data source.

See Relay Agents.

Adding a data source

To add a data source, open the relevant workspace and then 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 Add data source page.

Before you start

  1. Configure the SquaredUp relay agent
  2. Configure the data source in SquaredUp

Configuring the SquaredUp relay agent

This is an on-prem plugin, meaning it uses a relay agent to connect to an on-prem data source on your private network that is not publicly accessible.

You will need to configure a relay agent before you configure this data source.

See Deploying a relay agent.

This feature is available with an Enterprise plan

Relay agents allow you to securely connect to data sources inside your own network (on-prem).

A relay agent is installed on a server on your internal network, and has access to your data source.

When a plugin uses a relay agent it means that you don't need to open your firewall to allow SquaredUp access to the data source.

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

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. Agent groups are managed from Settings > Data > Relay.

  3. Scripts directory:
    Enter the path to the directory where you store the PowerShell scripts on the machine you deployed the agent on.
    Note

    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

  4. Import script:
    Optional. If you want to use a script for importing objects into SquaredUp, you can specify the script here by entering its full file name, for example get-objects.ps1
    Note

    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.
  5. Only allow signed scripts (windows only):
    Select to only run scripts that have a valid signature. The check only runs on relay agents installed on Windows. On Linux, this setting has no effect.

  6. Restrict access to this data source:
    Optionally, enable this toggle if you only want certain users/groups to have access to the data source, or those with the permission to link it to new workspaces. See data source access control for more information.

  7. Click Add.

Testing and troubleshooting

If you encounter an error, refer to the guidance or contact our support team in-app or via SquaredUp Support

For errors on dashboard tiles see Troubleshooting tiles.

Error messages

Error
What to do
Cannot use relative path <path>
Edit the data source and enter the scripts directory as an absolute path, for example C:\Scripts\SquaredUpCloud.
Script is located outside the scripts folder
The script path in the tile points outside the scripts directory, for example by using ..\. Move the script into the scripts directory, or one of its subfolders, and update the path in the tile.
<path> is not a ps1 file
Only PowerShell script files can run. Check that the script path in the tile ends in .ps1.
Issue with script signature: <reason>
Only allow signed scripts is selected, and the script does not have a valid signature. Sign the script with a trusted certificate, or clear the setting on the data source.

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 Filter | Group | Sort and Columns tabs in the tile configuration.

Next steps

PowerShell scripts

To write the scripts this data source runs, including import scripts for adding objects, see Creating On-Prem PowerShell Scripts.

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 are named queries targeted at a data source, typically mapped to a specific API endpoint. They define how SquaredUp retrieves live data. By standardizing information from diverse formats into a simple table, data streams provide a consistent starting point regardless of the original source system.

Each plugin includes its own set of data streams. When editing a tile or exploring data, the data stream you choose acts as the entry point to the objects and records within that data source.

Scoped data streams allow you to specify which objects you want to pull data for. Global data streams return general information that is not tied to objects.

Some data streams are configurable, meaning you can configure additional settings on the Parameters tab of the tile editor to create a bespoke query.

When you're creating a tile, you can tweak data streams by grouping or aggregating specific columns.

See Data Streams for more information.

The following data streams are installed with this plugin.

Run script On-Premise

Execute a script without providing a scope

Parameters
Run script On-Premise

Execute a script, providing a scope that will be passed to the script

Parameters

Was this article helpful?

Have more questions or facing an issue?
Submit a ticket