Custom PowerShell plugin

Visit our website to see the data that you can access if you use this plugin to add the data source to SquaredUp:

Run user-created PowerShell scripts on Relay Agents.

Note: This data source is an on-premises data source.

How to add a Custom PowerShell data source

Configure and deploy an agent

If you have already created an agent in SquaredUp that you can use for this data source, you can skip this step and choose the agent group you want to use while adding the data source.

Deploying an agent

Create a unique API key for your agent and add the agent to an agent group in SquaredUp.
You create an API key by creating an agent in SquaredUp:
1. Go to Settings > Relay and add an Agent.
2. Give the new agent a name and a description that helps you identify where the agent is installed. For example:
  Name: server1.domain.local
  Description: Test server in production domain
3. Choose the Agent Group for this agent:
  1. If you already have agent groups, assign it to an existing group and click create.
  2. If you don't have any agent groups yet or want to assign the new agent to a new group, leave the Agent Groups field empty and click create. Then create the agent group by clicking on Add Agent Group and select the new agent in the Agents field for the new group.
4. After you created the agent, the API key for this agent will be shown to you. Copy the key and store it until you inserted the key into the configuration of the agent you want to deploy on your machine.
  The API key will only be displayed to you once. If you lose this API key, you need to generate a new one (by creating a new agent) and any references to the old API key in the configuration of the agent you deployed on your machine will need to be updated.
5. The agent status will show as gray until the next stage of configuring the service is completed successfully.

Deploy the agent on a machine that has access to the service the data source connects to.

Download the latest release of the SquaredUp agent zip file, by clicking the download icon under Options next to the agent you have just added.
Prerequisites for agents
- The agent needs to run on a Windows machine that has access to the entry point for the on-premises data source
- Make sure the agent is able to make outbound connections on port 443 (no inbound required) to SquaredUp, *.amazonaws.com and Microsoft APIs (Azure Relay).
- Optional DNS-based restrictions: *.servicebus.windows.net
- For information about Relay Agent versions see Release Notes - Relay Agent
On a Windows machine, with access to the entry point your data source needs to use, extract the downloaded zip file.

In the folder of the extracted zip file, open PowerShell as an administrator and run the following command:

Copy

./Install-SQUPAgent.ps1 -ApiKey "key" -AsService -ServiceSuffix "name" -ServiceAccount domain\username

Parameters to replace:

`-ApiKey "key"`	Mandatory	Replace `key` with the API key you created for the agent in SquaredUp
`-AsService`	Recommended	Run the agent as a service on the machine
`-ServiceSuffix "name"`	Optional	To change the default service name of squpagent replace `name` with your new service name.
`-ServiceAccount domain\username`	Optional	To run the agent as a domain service account (for example, for the SCOM data source), provide the username as `domain\username` and it will prompt for the password when it sets up the service
`-InstallPath`	Optional	Specify a folder location for where the agent will be installed. If this is not specified then the agent will be installed in the folder where the zip file is extracted.

Consider restricting access to the folder where the agent is installed to prevent anyone from updating or viewing the configuration files.

Adjust any permissions for the service and start the service.
How to start the agent service
You can start the agent service from Services > SquaredUp Cloud Agent, or using PowerShell using either:
Start-Service -Name <ServiceName>
Where <ServiceName> should be replaced with the service name shown in brackets in the upgrade script output (or Properties of the service).
For example:
Start-Service -Name squpagent
or
Start-Service -DisplayName <DisplayName>
Where <DisplayName> should be replaced with the service name shown before the brackets in the upgrade script output (or Properties of the service).
How to find the agent folder location or Service name in Properties
Look at the Properties of the SquaredUp Cloud Agent service:
On the server running the agent, open Services
Scroll down to the SquaredUp Cloud Agent in the list
Right-click on the SquaredUp Cloud Agent service and then Properties
Here you can see the Service name, Display name and Path to the agent folder.
You can also start or stop the service from here.
Check the agent status in SquaredUp Settings > Relay

For more information see Configuring an agent for on-premises data sources

Create the PowerShell scripts and store the files on the machine in a folder readable by the agent

Your PowerShell scripts can serve two different functions:

Import script: In case you need to import new objects into SquaredUp, you need an import script. This script contains the definitions for objects and their links in the Knowledge Graph. There can only be one import script per Custom PowerShell data source. Tip: You can add more Custom PowerShell data sources to SquaredUp if you want to use different import scripts, and they can all use the same folder.

Data Stream script: All other scripts are Data Stream scripts. Those scripts contain the different Data Streams you want to use when you are creating tiles for a dashboard.

Format of import scripts

Import scripts return objects to SquaredUp using the following format:

Import scripts write objects to SquaredUp in the following format:

Copy

@{
vertices = @()
edges = @()
}

Example import script

Information about parameters in the script:

Vertex (vertices create objects in SquaredUp)

`name`	string – the name of the vertex
`sourceId`	string – a unique ID identifying the vertex
`type`	string – the high-level type of the vertex Note: A lot of types are already pre-defined in SquaredUp, which means they will be displayed properly with an icon etc. To make sure the type you're using matches with a pre-defined one, use lowercase only, one word without hypens, and the singular form (for example loadbalancer, apidomain, dnsrecord). If your type isn't recognized, you can add it as a custom type, see Types and Custom Types.
`sourceType`	string – a type for the vertex pertinent to your specific use-case
other properties	You can use any other properties of use in your specific use-case

Edges (edges create links between objects in SquaredUp):

`label`	string – the type of edge
`inV`	string – the sourceId value of the vertex the edge enters
`outV`	string – the sourceId value of the vertex the edge leaves

Copy

get-objects.ps1:
@{
    vertices = @(Get-CimInstance -Class Win32_LogicalDisk |
        ? { $_.DriveType -eq 3 } |
    %{
        [PSCustomObject]@{
            name = ('{0} {1}' -f $_.SystemName,$_.Name)
            sourceId = ('\\{0}\root\cimv2:Win32_LogicalDisk.DeviceID="{1}" ({2})' -f $_.SystemName,$_.Name,$_.VolumeSerialNumber)
            type="storage"
            sourceType="volume"
            FileSystem = $_.FileSystem
            Compressed = $_.Compressed
            Size = $_.Size
        }
    })
    edges = @()
}

Format of Data Stream scripts

Data Stream scripts return objects to SquaredUp using the following format:

Data Stream scripts return data as a simple array of objects:

Copy

@()

Example Data Stream script

Note: To be able to use the Data Stream script you also need to create a custom Data Stream that calls your Data Stream script. This is done from Settings > Advanced > Data Streams. The format of the result objects of your script needs to match the columns you've defined in the custom Data Stream.

Copy

get-diskFreeSpace.ps1:
Param(
    [Parameter(Mandatory=$true)]
    $scope
)

$targetObjectsBySourceId = @{}
foreach ($targetObject in $scope) {
    $targetObjectsBySourceId[$targetObject.sourceId[0]] = $targetObject
}

$results = (Get-CimInstance -Class Win32_LogicalDisk |
    ? { $_.DriveType -eq 3 } |
%{
    $sourceId = '\\{0}\root\cimv2:Win32_LogicalDisk.DeviceID="{1}" ({2})' -f
        $_.SystemName,$_.Name,$_.VolumeSerialNumber
    if ($targetObjectsBySourceId.ContainsKey($sourceId)) {
        [PSCustomObject]@{
            name = ('{0} {1}' -f $_.SystemName,$_.Name)
            Size = $_.Size
            FreeSpace = $_.FreeSpace
        }
    }
})

return $results

Add a custom PowerShell data source in SquaredUp

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.
Display Name:
Enter a name for your data source. This helps you to identify this data source in the list of your data sources.
Agent Group:
Select the Agent Group that contains the agent(s) you want to use.
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
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
Note: The import script must be stored in the same directory you defined above.
“Only allow signed scripts” check-box:
If you check this box, no unsigned PowerShell scripts will be executed. This applies to all scripts run by the data source, not just the import script.

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

Click Add.
You can also add a data source from Settings > Data Sources > Add data source, but sample dashboards are not added when using this method.
If you defined an import script, it will run shortly and the objects will subsequently appear in the dashboard in the new workspace.

4. Add one or more custom Data Streams in SquaredUp.

To be able to use the return data from your PowerShell Data Stream scripts in tiles on dashboards, you need to create custom Data Streams.

Go to Settings > Advanced > Data Streams.

Add a new Data Stream with the following settings:

Display Name This name will be displayed when you are creating tiles on a dashboard and can pick Data Streams.

Data source Choose the Custom PowerShell data source.

Entry point

You can either use a scope of objects (list scope) or not limit the scope to specific objects (no scope).

If you use the list scope, the Data Stream will only be visible when creating a tile that has those objects in its scope. Which objects are included is defined by the matches parameter in the Data Stream JSON.

You can use all parameters you used for defining vertices in the import script as criteria for which objects to include (e.g. a specific type of object).

Enter the JSON for the Data Stream in the code box.

Format of the JSON for the Data Stream

Information about parameters in the script:

dataSourceConfig.scriptPath Defines which script is run by this Data Stream

matches

If you selected the entry point "list scope", here you define for which objects the Data Stream will be visible when creating a tile.

You can use all parameters you used for defining vertices in the import script as criteria for which objects to include (e.g. a specific type of object).

metadata

Allows you to customize how the results are displayed in SquaredUp. You can modify which columns are shown as well as their format, for example currencies, dates, and storage units. You can also specify which columns are the label and which are the value for the visualization.

Copy

{
  "name": "diskSpace",
  "dataSourceConfig": {
    "scriptPath": "get-diskFreeSpace.ps1"
  },
  "matches": {
    "sourceType.0": {
      "type": "equals",
      "value": "volume"
    }
  },
  "rowPath": [
    "results"
  ],
  "metadata": [
    {
      "name": "results.name",
      "displayName": "Name",
      "shape": "string"
    },
    {
      "name": "results.size",
      "displayName": "Disk Size",
      "shape": "bytes"
    },
    {
      "name": "results.freeSpace",
      "displayName": "Free Space",
      "shape": "bytes"
    }
  ]
}

Cloud KB LIVE.10.log-183548538.zip
4 KB Download

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.