// docs

Runbooks

Chain scripts into repeatable, ordered workflows — with parameters, shared variables, and reboots that resume where they left off.

What a runbook is

A runbook is an ordered set of scripts that run as one workflow. Steps are numbered (for example 01-Prep.ps1, 02-Install.ps1, 03-Verify.ps1) and execute in order. ServerEngine ships with example runbooks — Windows Update, security audits, ISO compliance checks, bloatware removal, and more — that you can run or adapt.

Passing values between steps with $store

Every step shares one built-in variable, $store. Whatever a step assigns to $store is available to the next step — no return, no external file. It's the way to carry state through a workflow.

The robust pattern is to keep a small object in $store as compact JSON: each step reads it, validates it, adds its own result, and writes it back for the next step.

01-Collect.ps1 — start the chain
$data = @{
    host    = $env:COMPUTERNAME
    osBuild = [string](Get-CimInstance Win32_OperatingSystem).BuildNumber
    step    = 1
}

# Hand the payload to the next step
$store = $data | ConvertTo-Json -Compress
02-Augment.ps1 — read, validate, extend
# $store carries the JSON string from the previous step
if ([string]::IsNullOrWhiteSpace($store)) {
    throw "Step2: chain data from Step1 was lost!"
}
$data = $store | ConvertFrom-Json

# Guard against an out-of-sequence or cross-host payload
if ($data.step -ne 1) { throw "Step2: store out of sequence!" }
if ($data.host -ne $env:COMPUTERNAME) { throw "Step2: payload from another host!" }

# Add this step's result and pass it on
$data.step = 2
$data | Add-Member services (@(Get-Service | ? Status -eq Running).Count)
$store = $data | ConvertTo-Json -Compress

Fail fast on a lost payload

Because $storeflows one step at a time, a good step checks that it isn't empty, is in the expected sequence, and came from the same host — then throws to fail the job rather than run blind. ServerEngine ships an example runbook, TEST-5Step-Chain.runbook, that demonstrates exactly this.

Passing parameters in (the [VAR:…] format)

$store moves data between steps. To pass values into a runbook or script at run time — from the REST API, or the run dialog — use the bracketed [VAR:name,VAL:value]format. This is the API's dynamic parameter mechanism: each token in the script is replaced with your value before it executes.

parameters — passed with the job (e.g. via POST /jobs)
[VAR:xBackupPath,VAL:C:\Backup][VAR:xRetentionDays,VAL:30]

Reference the token name directly in the script and it becomes your value at run time:

PowerShell — using an injected parameter
# xBackupPath is replaced with C:\Backup before the script runs
$dest = "xBackupPath"
Write-Host "Backing up to $dest ..."

Note

Convention: prefix injected parameter names with x (e.g. xBackupPath) so they're easy to spot. See the API docs for passing them with a job.

Managed reboots with seamless resume

When a step needs a reboot, it signals ServerEngine rather than rebooting blindly. ServerEngine manages the reboot: it triggers the restart, watches the host go down and come back online, reconnects automatically, and resumes the runbook at the next step — no manual intervention, no lost progress.

PowerShell — request a managed reboot from a step
# ... do work that requires a restart ...

# Signal ServerEngine to reboot this host and resume the runbook
Write-Host "State : Reboot"

Windows reboot chaining

Managed reboot-and-resume applies to Windows hosts over WinRM. It's what makes multi-stage workflows — feature installs, domain joins, patch-and-verify — run unattended end to end.

Turn a runbook into an AI skill

Any runbook can be exposed to S.E.N.T.R.I as a callable skill, so you can trigger a whole workflow from a natural-language goal.