How to write on-prem PowerShell scripts

Some data never leaves your network, and some of it only a script can reach. The on-prem PowerShell data source runs the scripts in your Scripts directory on a Relay Agent inside your network: data stream scripts feed tiles, and an optional import script adds objects to SquaredUp.

Import scripts

An import script adds objects, and the links between them, to the knowledge graph. Set its path, relative to the scripts directory, in the Import script field when configuring the data source. Import scripts don't receive any parameters.

Each data source takes one import script. To run more than one, add another PowerShell On-Prem data source that points at the same folder.

Import script format

An import script outputs a hashtable with two arrays:

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

Vertices

Each vertex is an object to import:

Edges

Each edge links two vertices:

Example import script

This import script, get-objects.ps1, imports each fixed disk on the machine as a volume object:

@{
    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)
            sourceType="volume"
            FileSystem = $_.FileSystem
            Compressed = $_.Compressed
            Size = $_.Size
        }
    })
    edges = @()
}

Data stream scripts

Every other .ps1 file in the scripts directory, including subfolders, is a data stream script. Choose one in the Script path field of the Run script On-Premise data stream.

If Only allow signed scripts is enabled on the data source, a script needs a valid signature to run. This only applies on Windows.

Data stream script format

Output an array of objects. Each property becomes a column in the tile.

@()

Script parameters

SquaredUp passes these to any script that declares a parameter with the same name:

• scope: The objects in scope. Only passed when the tile has objects in scope.
• timeframe: The dashboard timeframe.
• paging: Lets a script output its data over several runs. See Paging below.

Values in Script arguments are passed as parameters too. For example, { "TopN": 10 } sets $TopN to 10.

Example data stream script

This script, get-diskFreeSpace.ps1, outputs the size and free space of each disk in scope. It declares scope as mandatory, so it only runs on a tile with objects in scope.

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

Paging

To output data over several runs, declare a paging parameter in your script. SquaredUp runs the script once for each page and combines the pages into one result for the tile.

• $paging.context: The value that identifies the page being read. On the first page it's $null.
• $paging.next: Set this to request another page. SquaredUp passes the value back as $paging.context on the next run. To end paging, leave it unset on the last page.

param($paging)

$offset = if ($paging.context) { $paging.context.offset } else { 0 }
$all = 1..25 | ForEach-Object { [PSCustomObject]@{ id = $_ } }
$all | Select-Object -Skip $offset -First 10
if ($offset + 10 -lt $all.Count) { $paging.next = @{ offset = $offset + 10 } }

SquaredUp stops requesting pages after about 12 seconds, and the tile shows "The request timed out. The tile may not display all available data."

Was this article helpful?