ADVANCED TOPICS

Scripting guide

Scripts are how Overseer detects, installs, removes and configures. This page explains where a script can run, the jobs scripts do inside a deployment, how values reach them and the habits that keep them dependable.

What scripts do in Overseer

You declare what should be true on a computer, and Overseer detects where the computer differs, acts and verifies. Each of those steps is carried out by a script, and every script is PowerShell.

The Library already holds scripts for common work. Built-in items are marked Global, and yours are marked Local. You write a script, in the Script Editor, when the Library does not already do what you need.

Where a script runs

Every script runs in one place. Choose it by what the script has to reach.

Where it runs	What it is for
On the computer, as the system	Work that needs full rights over the computer: installing, removing, changing settings that apply to everyone who uses it.
On the computer, as the signed-in user	Work that belongs to one person, such as settings kept in that person's own profile.
On the Overseer server, directing the computer	Work with several steps, work that has to continue after a restart, and work that uses a secret such as an API key.

A script on the server does not touch the computer directly. It sends pieces of work to the computer, as the system or as the user, passes values in with each piece and gets the results back as objects. The secret stays on the server.

A server script can also run for a whole client instead of one computer, for settings that belong to the client.

How scripts fit a deployment

Software

Detection. Reports whether the software is present and at which version. Overseer normally reads that from the computer's list of installed programs, hidden entries included. Write a detection script only when the software leaves no entry there. It returns the version as text.
Install and uninstall. Carry out the change during Execution. Further scripts can run straight after either, or handle an upgrade.
Test. An optional check that installed software works. When it reports a failure, Overseer installs the software again.
Version and download. A script can look up the newest version and where to download it, so you do not upload each release. A download script handles sources that need authentication.

A detection script can be as small as this:

$file = Get-Item 'C:\Program Files\Example App\example.exe' -ErrorAction SilentlyContinue
if ($file) { $file.VersionInfo.FileVersion }

Custom detection costs reporting. Overseer cannot match a detection script against the inventory it already holds, so it cannot say in advance which computers have the software.

Tasks

A task has up to three jobs: read the current setting, check whether it is right, and correct it. The check answers true or false. One script can do all three.

When a task deployment is Enforced, the check runs; if it fails, the task corrects the setting and the check runs again. A check is one comparison:

$service = Get-Service -Name 'Spooler' -ErrorAction SilentlyContinue
$service -and $service.StartType -eq 'Automatic'

Other jobs

Targeting. A script can be the target of a deployment. It either answers true or false for each computer, or returns the list of computers the deployment applies to.
Preflight. Preflight scripts run at the start of every session and can hold it until a condition clears.
Inventory. Inventory scripts collect facts about a computer.

Values Overseer gives a script

Overseer sets some values before a script starts. Which ones depends on the script's job.

About the computer. Its name, its client, whether it is a portable computer, and the email address of the person who uses it most.
About the software. Its name, version and product code, the path to the installer file and its folder, and a suggested path for a log file. Write the installer's log there and Overseer shows its contents with the session.
From the deployment. A licence key or the path to a licence file, where the software is marked as needing one.

Do not set these values yourself or give your own variables similar names.

Parameters

A task can have parameters, filled in on the deployment. One task then serves many clients, each with its own values.

Files. A file parameter makes Overseer download the file and hand the script its path. A zip file is unpacked, and the script also gets the path of the unpacked folder.
Software. Attach a task to software as its configuration, and the task's parameters are passed to the install script. That suits software configured by its installer. To check the same settings later on computers that already have the software, add check and correct scripts to that task.
Choice. A script can decide which parameters a technician sees, hide the rest and set defaults.

Good practice

Look before you write. Search the existing scripts in the Script Editor first.
Write it once. Put shared logic in a function or module that other scripts reuse.
Test on a spare computer. Keep one computer for testing. Run the script with the values a real session would pass it.
Do not hard-code. Use the installer path, licence key and parameters Overseer supplies. Prefer an installer that is the same for every client, and pass what differs as a parameter.
Check your own work. Give every task a check. That is how Overseer knows whether a computer is Compliant.
Fail clearly. Use throw with a message that says what went wrong and what to do. Overseer shows that message prominently.

Next steps

Command referenceThe kinds of helper command Overseer gives your scripts. Script editorWhere you read, write and test the PowerShell behind every item. Creating and managing tasksWrite a PowerShell task that checks a setting and corrects it.

Was this article helpful?

← Deployment ordering Command reference →