PowerShell Module Overview

The adTempus PowerShell module provides cmdlets for running and monitoring jobs, retrieving job history, and exporting and importing adTempus data. The cmdlets follow PowerShell conventions and work together in pipelines. For example, you can find jobs with Get-AdtJob and pipe them to Start-AdtJob to run them.

The Start-AdtJob command can be used instead of the adtexec command-line utility; see Migrating from adtexec for more information.

Requirements

The module works in both editions of PowerShell:

Edition	Version
Windows PowerShell	5.1
PowerShell	7.6 or later

The module can connect to adTempus servers running the same or an earlier version of adTempus.

Installation

The adTempus server and Console installers install the module to the standard location for modules available to all users, C:\Program Files\WindowsPowerShell\Modules\adTempus\<version>. Windows PowerShell and PowerShell 7 both look for modules there, so the cmdlets are available in new PowerShell sessions without any setup.

To install the PowerShell module alone (without the server or the Console) use adTempusPowerShellModule.msi, which can be found in the "packages" folder in the adTempus setup source or downloaded separately.

PowerShell loads the module automatically the first time you use one of its cmdlets. To load it explicitly, use Import-Module adTempus.

Connecting to a server

All of the cmdlets work through a connection to an adTempus server. If you haven't connected to a server, the first cmdlet you run connects to the adTempus server on the local computer using your Windows identity, and that connection is used for the rest of the session.

To connect to another server or use different credentials, use Connect-AdtServer. The new connection becomes the default connection for the session, and Connect-AdtServer returns it:

# connect to a remote server using the current Windows identity
Connect-AdtServer -Server sched01

# connect using an adTempus user ID and password, saving the connection in a variable
$connection = Connect-AdtServer -Server sched01 -Credential (Get-Credential) -AuthenticationType Password

In a script or function that doesn't use the returned connection, use $null = Connect-AdtServer ... so the connection isn't included in the output.

If you're moving from scripts that use the client API, Connect-AdtServer takes the place of [ArcanaDevelopment.adTempus.Client.Scheduler]::Connect. The connection's Scheduler property is the client API Scheduler object.

Every cmdlet also has -Connection, -Server, and -Credential parameters for working with more than one server in the same session. Objects returned by the cmdlets stay linked to the connection that fetched them, so when you pipe objects to another cmdlet, that cmdlet uses the same connection automatically.

Examples

Run all the jobs in a group and wait for them to finish:

Get-AdtJob 'Nightly\*' | Start-AdtJob -Wait -Timeout 01:00:00

Run a job with job variables, displaying its log messages while it runs:

Start-AdtJob 'Finance\Load' -Variable @{ Region = 'East'; Source = 'PowerShell' } -Wait -ShowMessages

Stop the running instances of some jobs:

Get-AdtJob 'Load*' | Get-AdtJobInstance -Active | Stop-AdtJobInstance -Reason 'Maintenance' -Wait

Export a job group, protecting sensitive data with a password:

Get-AdtJobGroup Finance | Export-AdtData C:\export\finance -IncludeSensitiveData -Password (Read-Host -AsSecureString)

Preview an import, then import only the jobs from the file:

$file = 'C:\export\finance.adtexport6'
Get-AdtImportItem $file
Get-AdtImportItem $file | Where-Object ClassID -eq 'Job' | Import-AdtData $file -WhatIf
Get-AdtImportItem $file | Where-Object ClassID -eq 'Job' | Import-AdtData $file -HoldJobs

Delete the objects listed in a CSV file that has Type and Name columns:

Import-Csv C:\export\deletions.csv | Remove-AdtObject -WhatIf

Handling errors

When an operation fails, the cmdlets write an error record whose error ID identifies the problem. In scripts, use -ErrorAction Stop with try/catch, or check $?, to detect failures.