Basics of Writing your own Blueprint

Basics of Writing Your Own Blueprint

The Blueprints architecture is open: you can deploy custom software, apply settings, and do almost any work on PC Assets. Blueprints are written in PowerShell and run as Modifiers against Assets.

Before You Start

• There are many Blueprints already written — search the Public Library first to see if yours exists.
• Keep Blueprints atomic: each should do one specific thing. Write several focused Blueprints rather than one master Blueprint.
• Existing Blueprints are open — review their PowerShell source for examples that make writing your own much easier.

The Four Parts of a Blueprint

• Properties — a configurable block of variables set when a Modifier is built.
• Validator — a PowerShell script that decides whether the work is already done.
• Worker — a PowerShell script that performs the work.
• Payload — an optional file downloaded and made available to the Worker.

Payload Details

Many Blueprints include a Payload: a single downloadable file (MSI, EXE, ZIP, or any type) at a fixed, credential-free URL. A Payload has three parts:

• Payload Filename — the local filename the download is saved as (e.g. payload.zip, chrome.msi), useful for referencing it in the Worker.
• Payload URL — a complete HTTP/HTTPS URL, including the protocol, that is publicly accessible without credentials.
• Payload Checksum — the expected SHA2 (SHA-256) checksum of the downloaded file. If the runtime checksum doesn’t match, the Worker won’t run. Enter the correct checksum or machines will never validate the payload.

Predefined Constants

Several constants are available in Validators and Workers:

Configurable Properties

Properties are variables the Blueprint exposes to the Modifier, in the form $key=value or $key=“String Value”, with # comments describing each. Only expose variables that should be customizable per Modifier — do not expose internal, Blueprint-specific values, as that adds complexity and risk. Example:

# Name users will see in the print dialog
$printercommonname=“HP Enterprise M553”
# Printer IP address
$PrinterIPAddress=“10.0.0.60”

Validator

The Validator decides how much work a machine needs to do, both before the Worker runs (should it run?) and after (did it succeed?). It must produce exactly one output:

• $VALIDATED_WORK_DONE — already complete; the Worker is skipped.
• $VALIDATED_WORK_NEEDED — the Worker should run.
• $VALIDATED_WORK_INDETERMINATE (the default) — can’t determine; the Worker is skipped.
• $VALIDATED_RUN_ALWAYS — run every poll (use carefully to avoid overwork).

If the output is blank or unrecognized, it’s treated as INDETERMINATE. Avoid any stray console output or non-squelched errors in the Validator — that’s the most common reason a Validator unintentionally returns INDETERMINATE and the Worker never runs. In your Validator, Write-Output the appropriate constant for each case (for example, check the registry to see whether software is already installed).

Worker

The Worker does the actual work. Running with Local Administrator rights, it can install software, change configuration, delete files, and more. It has access to the Properties and to the Payload. Workers run in a temporary working directory (where the Payload is downloaded) that is deleted afterward. Example install line:

msiexec /i GoogleChromeStandaloneEnterprise64.msi /qn

The Worker’s STDOUT becomes the report sent back to the cloud and visible to anyone who can view the Asset (Reporter and above) — so never output anything sensitive. Reports are truncated to 2000 characters.

Asset Connectors: A Special Worker Output

Any Blueprint can act as an Asset Connector by having the Worker emit a special line. Every report line beginning with ##ASSETCONNECTOR## is parsed as a connector:

##ASSETCONNECTOR##[ ][ ]

This is useful when you need code on the machine to build the connector URL (for example a Splashtop or RustDesk link).

A Word of Caution

Validators and Workers run as an elevated service with Local Administrator rights, so they can do real harm. This power is necessary for installing software and changing configuration — use it responsibly. For reference, they execute as 32-bit PowerShell via C:\Windows\sysnative\WindowsPowerShell\v1.0\powershell.exe.

Common Questions

What language are Blueprints written in?
PowerShell.

My Worker never runs — why?
Most often the Validator returned INDETERMINATE because of stray console output or an error. Squelch output and return one explicit constant.

What checksum does the Payload use?
SHA2 (SHA-256) of the downloaded file. A mismatch stops the Worker.

Where can the Payload be hosted?
At a fixed, public HTTP/HTTPS URL that needs no credentials.

Can a report contain sensitive data?
It shouldn’t — the Worker’s STDOUT is visible to anyone who can view the Asset, and is truncated to 2000 characters.