PowerShell operations reporting foundation

Good For

• Windows health reporting
• Patch readiness evidence
• Scheduled maintenance summaries
• Multi-host PowerShell checks
• Operator-friendly HTML report starters

How to Use It

1. Before this page is runnable, create the helper file at `.\templates\reporting\OpsReporting.Foundation.ps1` by following the linked helper-contract page. This foundation page intentionally consumes that helper rather than pretending it appears by magic.
2. Treat this page as the shared reporting contract for reusable Ops Stack reports, not just a wrapper around a helper script.
3. Use a generic target model instead of assuming every report is host-only. At minimum, a reusable row should carry TargetType, TargetName, optional TargetId, optional Host, CheckGroup, CheckName, Status, Finding, ErrorText, and DurationMs.
4. Keep the reporting grain explicit: one row represents one evaluated check against one target.
5. Write local artifacts first and delivery second. Save the HTML report, CSV export, JSON run package, and plain log before sending email, webhook, Graph, or ticket updates.
6. Use row-level and target-level summaries together so report packs can distinguish finding counts from target counts.

Execution Modes

• local-rendering

Inputs and Outputs

Inputs

• Normalized result rows
• Run context metadata
• Output folder path
• Optional artifact or export settings
• Optional delivery settings

Outputs

• html-report
• csv
• json
• log-file
• operator-notes

Command Starter

Changes system state: review before running

# ---------------------------------------------------------------------
# Prerequisite
# ---------------------------------------------------------------------
# Create this helper first by following the linked helper-contract page.
# The foundation page intentionally consumes that helper instead of hiding it.
$FoundationPath = '.\templates\reporting\OpsReporting.Foundation.ps1'
if (-not (Test-Path -Path $FoundationPath)) {
    throw "Missing reporting helper. Build it first: $FoundationPath"
}

# Load the reusable reporting functions into the current PowerShell session.
. $FoundationPath

# Fail early if the expected contract is not present.
$RequiredFunctions = @(
    'New-OpsReportRunContext',
    'Complete-OpsReportRunContext',
    'New-OpsReportResultRow',
    'New-OpsReportSummary',
    'Export-OpsReportArtifacts'
)
$RequiredFunctions | ForEach-Object { Get-Command $_ -ErrorAction Stop | Out-Null }

# ---------------------------------------------------------------------
# Sample run context and normalized result rows
# One row = one evaluated check against one target.
# ---------------------------------------------------------------------
$Run = New-OpsReportRunContext -CheckName 'SampleHealthCheck' -Environment 'production' -ExecutionMode 'remote-host-list' -InputSource 'servers.txt' -RequestedTargetCount 2

$Results = @(
    New-OpsReportResultRow -RunId $Run.RunId -TargetType 'Host' -TargetName 'server01' -Host 'server01' -CheckGroup 'Disk' -CheckName 'FreeSpace' -Status 'Pass' -Finding 'Free space above threshold.' -ErrorText '' -DurationMs 412
    New-OpsReportResultRow -RunId $Run.RunId -TargetType 'Host' -TargetName 'server02' -Host 'server02' -CheckGroup 'Reboot' -CheckName 'PendingReboot' -Status 'Warning' -Finding 'Pending reboot detected.' -ErrorText '' -DurationMs 1198
)

$CompletedRun = Complete-OpsReportRunContext -RunContext $Run
$Summary = New-OpsReportSummary -RunContext $CompletedRun -Results $Results
$Artifacts = Export-OpsReportArtifacts -OutputRoot '.\output\ops-report-sample' -RunContext $CompletedRun -Summary $Summary -Results $Results

# Show the output files so the operator knows exactly what was created locally.
$Artifacts | Format-List

Validation

• A sample run produces HTML, CSV, JSON, and log artifacts that describe the same result rows, target counts, and run metadata.
• The foundation can be reused by at least two different report types without redesigning the target schema or summary model.
• An operator can tell what target was checked, which check failed or warned, what the status vocabulary means, and where the artifacts were written without reverse-engineering the helper script.

Reporting

• Shared output pattern for HTML, CSV, JSON, and plain logs.
• Consistent row contract for free Toolchest starters and future premium report packs.
• Bridge between host health checks, patch readiness, certificate review, and later multi-target evidence packs.
• Expected helper contract: run-context builder, run completion, normalized result-row builder, summary generator, and artifact exporter.

Safety Notes

• This starter writes local report artifacts only. Review the output folder path before running it.
• Treat the run as reversible local output work: remove or archive the generated HTML, CSV, JSON, and log files if you need to undo a test run.
• Do not treat email as the system of record; always write local artifacts first.
• Do not log credentials, tokens, or secret-bearing command arguments inside HTML, CSV, JSON, or plain logs.
• If the helper file does not exist or does not expose the expected functions, stop and build/fix the helper contract before using this foundation.