Skip to main content
Universal Policy Administrator Documentation
< All Topics
Print

UPA PowerShell Cmdlets

Applies to: UPA 3.6.3 and higher, with the UPA PowerShell Tools

The UPA PowerShell Tools let you automate Universal Policy tasks from Windows PowerShell. They include 188 cmdlets: for Universal Policies and their workflow, GPOs, OUs and delegation, administrative templates, events and reports. They also include ready-made scripts for migrating from Microsoft AGPM and NetIQ GPA.

Install the UPA PowerShell Tools

Ask your FullArmor contact for the UPA PowerShell Tools installer (upa powershell tools.msi) that matches your UPA version, and run it on the machine you’ll automate from. It installs to:

C:\Program Files\FullArmor\AD Bridge\Powershell Snapin
IN THAT FOLDERWHAT IT IS
HAPI.ProviderPowershellSnapin.dllThe UPA cmdlets
Import-AGPM-GPOs.ps1Migrates GPOs and their history from Microsoft AGPM
Import-GPA-GPOs.ps1Migrates GPOs and their history from NetIQ Group Policy Administrator
Migration-Shared.psm1Shared code for the two migration scripts, including their HTML report
Import-ADM-Files.ps1Adds administrative templates (ADMX/ADML) from your designated folder
Export-UPA-AuditEvents.ps1Exports UPA’s audit events

The migration scripts and adding templates each have their own guide; ask FullArmor support for them.

Use Windows PowerShell 5.1, not PowerShell 7: the UPA cmdlets and scripts are built for Windows PowerShell. Open Windows PowerShell as an administrator.

Load the cmdlets

Use either of these; they load the same cmdlets.

$tools = "C:\Program Files\FullArmor\AD Bridge\Powershell Snapin"
Import-Module "$tools\HAPI.ProviderPowershellSnapin.dll"
Add-PSSnapin UPA.Management

Import-Module shows a warning that some cmdlet names use unapproved verbs. It’s harmless: some UPA cmdlets use verbs such as Checkout, Approve and Deploy, which aren’t on PowerShell’s standard list.

To list the cmdlets, and to read the help for any of them:

Get-Command -Module HAPI.ProviderPowershellSnapin
Get-Help Get-UniversalPolicy -Full
Connect to UPA

Every session starts by connecting to your UPA server. Pass a credential to Get-HAPIConnection together with your UPA address:

$cred = Get-Credential -Message "UPA sign-in (DOMAIN\user or user@domain)"
$cred | Get-HAPIConnection -Url "https://upa.contoso.com/"
  • -Url is your UPA site address (it’s an alias of -HAPIServerUrl).
  • -SkipSslCertificateVerification: add it only if your UPA server uses a certificate this machine doesn’t trust.
  • SAML sign-in: use Get-HAPIConnection -SAMLProvider <name> -Url <address> instead of a credential.

Connect at the top level of your script. A connection opened inside a function ends when the function returns, and the next cmdlet then fails with “Value does not fall within the expected range”.

Don’t put passwords in scripts. Use Get-Credential, or a credential saved securely with Export-Clixml, which only the same user on the same machine can read.

Examples

Each example assumes you’ve loaded the cmdlets and connected, as above. All were tested on UPA 3.6.3.

1. List your Universal Policies

$tools = "C:\Program Files\FullArmor\AD Bridge\Powershell Snapin"
Import-Module "$tools\HAPI.ProviderPowershellSnapin.dll"

$cred = Get-Credential -Message "UPA sign-in (DOMAIN\user or user@domain)"
$cred | Get-HAPIConnection -Url "https://upa.contoso.com/"

Get-UniversalPolicy | Select-Object Name, GlobalPolicyId, LastModified

2. Get the details of one Universal Policy

Look the policy up by name, then ask for its full details. You can also copy a policy’s ID from the console: select the policy, then Advanced.

$up = Get-UniversalPolicy | Where-Object Name -eq "Workstation Security Baseline"
$details = Get-UniversalPolicy -AllDetails -UPId $up.GlobalPolicyId
$details | Select-Object Name, DomainName, Version,
    @{ n = 'Status'; e = { $_.Status.CurrentStatus } }, CreationDate, LastModified
Name         : Workstation Security Baseline
DomainName   : contoso.com
Version      : 1
Status       : Approved
CreationDate : 10/9/2026 7:00:47 PM
LastModified : 10/9/2026 7:00:48 PM

3. List the Universal Policies waiting for approval

Get-UniversalPolicy |
    Where-Object { $_.Status.CurrentStatus -eq 'WaitingForApproval' } |
    Sort-Object Name |
    Select-Object Name, GlobalPolicyId, LastModified |
    Format-Table -AutoSize

A Universal Policy’s status is one of:

STATUSNUMBERSHOWN IN THE CONSOLE AS
CheckedOut1Checked Out
CheckedIn2Checked In
WaitingForApproval3Pending Approval
Approved4Approved
Unapproved5Unapproved

4. Check that UPA is healthy

Test-GatewayHealth and Test-GatekeeperHealth each return the response time and a rating.

$url = "https://upa.contoso.com/"
foreach ($test in 'Test-GatewayHealth', 'Test-GatekeeperHealth') {
    $result = & $test -Url $url
    [pscustomobject]@{
        Component    = $test -replace '^Test-|Health$'
        ResponseTime = $result[0]
        Rating       = $result[1]
    }
}
Component  ResponseTime Rating
---------  ------------ ------
Gateway    10ms         Good
Gatekeeper 6ms          Good

If a component is slow or doesn’t respond:

  1. Check the UPA server’s memory, CPU and disk use.
  2. In IIS, check that the HAPI and AD Bridge Gatekeeper application pools are running.
  3. If they are, restart the Gateway and Gatekeeper sites in IIS.

5. Export a list of Universal Policies to a spreadsheet

Get-UniversalPolicy |
    Select-Object Name, DomainName, Version, LastModified,
        @{ n = 'Status'; e = { $_.Status.CurrentStatus } } |
    Export-Csv -Path "$env:USERPROFILE\Documents\UniversalPolicies.csv" -NoTypeInformation
UPA Powershell Administrator Guide

For every cmdlet, its parameters, and more examples, download the UPA PowerShell Administrator Guide:

Download the UPA PowerShell Administrator Guide (PDF)

You can also read the help for any cmdlet in PowerShell with Get-Help <cmdlet> -Full.

In This Article