PowerShell Scanner

If the script produces additional properties or objects on a different device—but those properties were not present during validation—they will not appear in the scanner results. To include those additional columns, you must re‑run the validation on a device where the script outputs those properties.

For best results, select a test device that is likely to return the most complete dataset, ensuring all desired columns are captured during validation before scanning additional devices.

PDQ Connect automatically detects a data type for each column. Supported types are String, Integer, Float, Boolean, and Date. Date values are formatted into a consistent, usable format for display.

Each column includes a data type selector in the UI. This doesn't affect the raw values your script returns, but it controls how PDQ Connect stores the data for use in Filters and Groups. This can be useful in situations like when PowerShell returns Boolean values as 0 or 1 and you want them treated as true/false rather than numbers.

Troubleshooting: Why Didn’t My Scanner Work?

If your PowerShell scanner produces unexpected or unusable results, check the following common issues:

Most issues can be resolved by ensuring the script outputs only structured objects.

Part 2: How the PowerShell Scanner Works (Advanced)

This section is intended for advanced users and script authors.
Most customers can successfully use PowerShell scanners without reading this section.

PowerShell scanners execute scripts in a non‑interactive context and evaluate results as data, not as console output.

To support display, filtering, and targeting in PDQ Connect, all scanner output must ultimately be converted into clean, predictable JSON. PDQ Connect performs this JSON conversion automatically on the backend to ensure consistent structure and data types.

For this reason:

• Scanner scripts should return native PowerShell objects
• Scripts should not attempt to control JSON serialization
• Formatting and console‑style output is not supported

PowerShell Scanner Wrapper

PDQ Connect uses internal logic (a “wrapper”) when running PowerShell scanners to process and normalize script output before converting it into JSON for use by the Connect application.

At a high level, the wrapper:

• Executes the user’s script
• Collects everything written to the PowerShell output stream
• Normalizes the results into a predictable, flat structure
• Converts the final output into clean JSON

If a user‑submitted script already includes a trailing ConvertTo‑Json, that portion is automatically removed before execution. This prevents double serialization and ensures PDQ Connect remains in control of how scanner results are processed and stored.

Important
Scripts should return objects only. JSON conversion is handled automatically by PDQ Connect.

Testing Scripts Locally Using the Scanner Wrapper

Some scripts work as expected in an interactive PowerShell session but behave differently when run as a scanner.

To support advanced troubleshooting, a modified version of the scanner wrapper is provided below. This version is adapted for execution in a PowerShell prompt but mirrors the same logic PDQ Connect uses on the backend when running a PowerShell scanner.

The wrapper is provided as a diagnostic aid only. Most customers do not need to use it.

Local Test Wrapper (Optional)

# Load and sanitize external script, stripping any trailing ConvertTo-Json

param (
    [Parameter(Mandatory)]
    [ValidateScript({ Test-Path $_ -PathType Leaf })]
    [string]$ScriptPath
)

$originalScript = Get-Content -Path $ScriptPath -Raw

$convertToJsonPattern = '\|\s*ConvertTo-Json\b[^\r\n]*\s*$'

$cleanedScript = [regex]::Replace(
    $originalScript.TrimEnd(),
    $convertToJsonPattern,
    '',
    'IgnoreCase'
).TrimEnd()

$scriptBlock = [scriptblock]::Create($cleanedScript)

& $scriptBlock |
ForEach-Object {
    if ($null -eq $_) { return }

    if ($_ -is [hashtable] -or $_ -is [System.Collections.Specialized.OrderedDictionary]) {
        $_ = [pscustomobject]$_
    }

    $out = [ordered]@{}
    foreach ($p in $_.PSObject.Properties) {
        $value = $p.Value
        if ($value -is [datetime]) {
            $value = $value.ToString('o')
        }
        $out[$p.Name] = $value
    }

    [pscustomobject]$out
} | ConvertTo-Json -Depth 1 -Compress