Skip to main content

PowerShell Job

Overview​

The PowerShell extension runs a script through Atria's Provisioning Service, either on demand or on a schedule. The Job Service sends the script name and configured variables to the Provisioning Service, which executes it and returns structured messages to the job run.

Use this for repeatable administrative tasks and reports. The script runs in the Provisioning Service's execution context, so its files, modules and access must be available on the server that executes it.

Installation​

In an administrative PowerShell session on the Provisioning Server, check and import the extension:

Get-AtriaComponent -Name PowerShell
Import-AtriaExtension -Extension PowerShell

See extension import parameters for version and restart options.

Place your script in the executing Provisioning Service's CustomScripts directory, beneath that service's application directory. Configure FileName with the script's filename. The examples below use files you place in that directory; installing the extension does not create those files.

Open Configuration > Provisioning & Debug Tools > Jobs, choose + Add, and select the Powershell task. Give the job a descriptive label and start with On Demand execution. Add configuration from an example below, save, and run it manually before enabling a schedule.

Configuration​

Parameters​

Configuration propertyPurpose
FileNameRequired. Script filename in the Provisioning Service's CustomScripts directory, or a script resource supplied by the extension.
VariablesObject containing variable names and values injected into the script session. Use names without the $ prefix.
ConfigValuesArray of Atria configuration keys to load as script variables.
EnvironmentConfigValuesArray of environment configuration keys to load as script variables.
SecretValuesArray of Atria secret keys to load as secret script variables.
EnvironmentSecretValuesArray of environment secret keys to load as secret script variables.
TimeoutInMinutesRequest timeout in minutes; defaults to 20 when omitted or set to zero or less.

The job's separate Secrets field supports a Variables object for values you want to supply directly as secrets.

Variables injected into the script session​

Atria sets the following variables in the PowerShell session before executing the script:

SourceVariable available to the scriptValue
Automatically supplied$LoggerAtria's job-run logger, with AddInfo, AddWarning, AddError, AddDebug and AddVerbose methods.
Automatically supplied$JobRunIdThe current job run identifier, as a GUID. Each execution has its own identifier.
Configuration → VariablesOne variable per object keyThe value supplied in the job configuration. For example, "ServiceNames": ["AtriaAgent"] provides $ServiceNames.
Secrets → VariablesOne variable per object keyThe secret value supplied in the job's separate Secrets field. For example, "ApiKey": "..." provides $ApiKey.
Configuration → ConfigValuesOne variable per listed keyThe value retrieved from Atria configuration using that key.
Configuration → SecretValuesOne variable per listed keyThe secret retrieved from Atria configuration using that key.
Configuration → EnvironmentConfigValuesOne variable per listed keyThe value retrieved from the executing environment's configuration using that key.
Configuration → EnvironmentSecretValuesOne variable per listed keyThe secret retrieved from the executing environment's configuration using that key.

Only $Logger and $JobRunId are automatically added by this job extension. Customer IDs, user IDs, portal credentials and an authenticated Atria PowerShell session are not automatically supplied. Load any modules and establish any connections your script needs explicitly.

Use names without the $ prefix in JSON. Variables are injected directly into the session rather than passed as command-line parameters; the examples read them without a param() block. FileName and TimeoutInMinutes control execution and are not injected as script variables.

For example, "EnvironmentConfigValues": ["ReportFolder"] retrieves the existing environment configuration value named ReportFolder and makes it available as $ReportFolder. It does not create that configuration value. For keys containing punctuation, use Get-Variable -Name 'Your.Configuration.Key' -ValueOnly to read the injected variable.

Use unique names across all variable sources, and reserve Logger and JobRunId for Atria. Do not log secret values: marking an input as secret does not prevent your script from explicitly printing it.

Logging and failures​

Use $Logger.AddInfo(), .AddWarning(), .AddError(), .AddDebug() and .AddVerbose() for messages visible in the job run. Each accepts a code, message template and optional string substitution values. Choose a job log level that includes the messages you need. Use throw for failures that must fail the script; adding an error-level log message alone does not throw an exception.

Example 1: Check Atria Windows services​

Use an on-demand or scheduled job to check whether selected Atria Windows services are running on the executing Provisioning Server. The script reports each service's state and fails the run if a service is stopped or missing. It does not restart services.

Save this as CheckAtriaServices.ps1 in CustomScripts:

$ErrorActionPreference = 'Stop'

if (@($ServiceNames).Count -eq 0) {
throw 'Supply at least one service name in Configuration > Variables > ServiceNames.'
}

$Logger.AddInfo('SVC-01', 'Checking local services. Job run: {0}', [string]$JobRunId)
$unhealthy = @()

foreach ($serviceName in $ServiceNames) {
if ([string]::IsNullOrWhiteSpace([string]$serviceName)) {
throw 'ServiceNames must not contain blank names.'
}

try {
$service = Get-Service -Name $serviceName -ErrorAction Stop
}
catch {
$Logger.AddError('SVC-02', 'Could not read service: {0}', [string]$serviceName)
$unhealthy += [string]$serviceName
continue
}

if ($service.Status -eq 'Running') {
$Logger.AddInfo('SVC-03', 'Service {0} is running.', [string]$serviceName)
}
else {
$Logger.AddError('SVC-04', 'Service {0} is {1}.',
[string]$serviceName, [string]$service.Status)
$unhealthy += [string]$serviceName
}
}

if ($unhealthy.Count -gt 0) {
throw ('Service check failed for: ' + ($unhealthy -join ', '))
}

$Logger.AddInfo('SVC-05', 'All configured services are running.')

Set the job's Configuration to the following, adjusting the Windows service names to match the executing server:

{
"FileName": "CheckAtriaServices.ps1",
"TimeoutInMinutes": 5,
"Variables": {
"ServiceNames": ["AtriaAgent", "AtriaProvisioningService"]
}
}

Run the job manually at Info log level. A healthy run contains SVC-01, one SVC-03 per service and SVC-05. A missing or stopped service produces SVC-02 or SVC-04, followed by a failed run. Once verified, */15 * * * * runs the check every 15 minutes.

This checks local services only. If the Provisioning Service or its required messaging path is unavailable, the job cannot execute this check; use external monitoring to detect those outages.

Example 2: Report on files using input variables​

Save this as ReportFiles.ps1. It reports files older than a configured number of days without changing them:

$ErrorActionPreference = 'Stop'

if (-not (Test-Path -LiteralPath $ReportFolder -PathType Container)) {
throw "Report folder does not exist: $ReportFolder"
}
if ([int]$OlderThanDays -lt 1) {
throw 'OlderThanDays must be at least 1.'
}

$cutoff = (Get-Date).AddDays(-[int]$OlderThanDays)
$files = @(Get-ChildItem -LiteralPath $ReportFolder -File |
Where-Object { $_.LastWriteTime -lt $cutoff })

$Logger.AddInfo('FILES-01', 'Found {0} files older than {1} days.',
[string]$files.Count, [string]$OlderThanDays)
foreach ($file in $files) {
$Logger.AddVerbose('FILES-02', 'File: {0}', $file.FullName)
}

Set Configuration to the following, replacing the folder with one accessible to the Provisioning Service:

{
"FileName": "ReportFiles.ps1",
"TimeoutInMinutes": 10,
"Variables": {
"ReportFolder": "C:\\AtriaReports",
"OlderThanDays": 30
}
}

The run should contain FILES-01 with the matching file count. Set the job's log level to Verbose to include individual filenames. Once verified, an example schedule is 0 6 * * * for 06:00 UTC daily.

Example 3: Supply a secret variable​

Save this as CheckSecretInput.ps1:

if ([string]::IsNullOrWhiteSpace([string]$ApiKey)) {
throw 'ApiKey is required in the job secrets.'
}

# A real integration could use $ApiKey for authentication here.
$Logger.AddInfo('SECRET-01', 'A secret was supplied for job run {0}.', [string]$JobRunId)

Set Configuration to:

{
"FileName": "CheckSecretInput.ps1",
"TimeoutInMinutes": 5
}

Set the separate Secrets field to the following, replacing the placeholder:

{
"Variables": {
"ApiKey": "replace-with-your-secret"
}
}

The run should contain SECRET-01, without displaying the secret. Do not print secret values or put them in exception messages. To load an existing environment secret instead, use "EnvironmentSecretValues": ["ApiKey"] in Configuration and omit the direct secret variable.

Check results​

Use Jobs System for scheduling, secrets and run-history controls. If execution fails, check the filename, the server's CustomScripts directory, dependencies and the Provisioning Service account's permissions. Review both the run result and script messages.