Installation

docker pull ironmansoftware/universal
docker run --name 'PSU' -it -p 5000:5000 ironmansoftware/universal

Tags

Persistent Data

To create a Docker image that can persist the Universal data, you can create a dockerfile like the one below.

This dockerfile exposes port 5000, creates a /data volume, sets configuration environment variables to store the Universal repository and database in the volume and then sets the Universal.Server as the entry point to the container.

Linux

FROM ironmansoftware/universal:latest
LABEL description="Universal - The ultimate platform for building web-based IT Tools" 

EXPOSE 5000
VOLUME ["/data"]
ENV Data__RepositoryPath ./data/Repository
ENV Data__ConnectionString ./data/database.db
ENV UniversalDashboard__AssetsFolder ./data/UniversalDashboard 
ENV Logging__Path ./data/logs/log.txt
ENTRYPOINT ["./home/Universal/Universal.Server"]

Windows

FROM ironmansoftware/universal:1.3.1-windowsservercore-1809
LABEL description="Universal - The ultimate platform for building web-based IT Tools" 

EXPOSE 5000
VOLUME ["C:/data"]
ENV Data__RepositoryPath C:/data/Repository
ENV Data__ConnectionString C:/data/database.db
ENV UniversalDashboard__AssetsFolder C:/data/UniversalDashboard 
ENV Logging__Path C:/data/logs/log.txt
ENTRYPOINT ["C:/ProgramData/Universal/Universal.Server.exe"]

You can run a build with the build command.

docker build . --tag=universal-persistent

You can start the docker container with the run command and make sure to specify the volume to mount.

docker run --name powershelluniversal --mount source=psudata,target=/data --rm -d  -p 5000:5000/tcp universal-persistent:latest

General

The Universal application binaries can generally be upgraded without having to change the configuration or database manually. This document will cover how to upgrade the application and some caveats to be aware of in regards to configuration and data persistence.

Data Persistence

Data is persisted in a LiteDB database with a default location of %ProgramData%\UniversalAutomation\database.db. The database will not be deleted during an upgrade of any kind. Any schema updates to the database will happen the first time you start up the new version of Universal. You may wish to backup your database before performing an upgrade.

Configuration Persistence

Configuration files are stored by default in %ProgramData%\UniversalAutomation. Configuration files may be updated or transformed during an update. This will happen the first time that the new version of Universal server is started. You may wish to backup your configuration files before performing an upgrade.

If you are using git, changes to the Universal files will be synchronized after the server starts up.

appsettings.json

web.config

Dashboard Components and Frameworks

New versions of Universal may include new versions of Universal Dashboard Frameworks or Components. By default, these components and frameworks are deployed to %ProgramData%\PowerShellUniversal during startup of the Universal server. During an upgrade, these files are not deleted. This ensures that dashboards will continue to run on the previous dashboard framework and component versions.

You should have multiple versions of the dashboard frameworks and components available when you start the new version of Universal.

By default, new dashboards are set to always use the latest version of the dashboard framework. You can chose to set it to a specific version if you would like but will have to manually change the version during an upgrade.

Repository

Most of the settings for PowerShell Universal are stored within the repository folder. By default, this is in %ProgramData%\UniversalAutomation\Repository. While the upgrade should not affect these files, you may want to backup the files before upgrading.

ZIP Upgrade

When upgrading an manual ZIP file installation, you will need to stop the application, delete the entire binary folder and replace it with the new binary folder. When you start the new version of Universal, new dashboard frameworks and components will be deployed and the existing database will be loaded.

MSI Upgrade

To upgrade using the MSI, you can simply run the new version of the MSI. The MSI is setup to always perform a major upgrade. This means it will stop and remove the service, delete the entire installation directory, reinstall with the new files and then install and start the new service.

You will want to follow the guide on data and configuration persistence above to ensure all your settings are saved.

IIS Upgrade

When upgrading with IIS, you will need to first stop your application pool to ensure that the binaries used by IIS are no longer in use and then replace the binaries with the new ones. Ensure that you follow the configuration persistence recommendations above with regards to the web.config file.

LiteDB v5 Upgrade

PowerShell Universal uses LiteDB to store jobs, app tokens, identities and git sync history. The original version of LiteDB included with PSU is version 4. We will be moving to version 5 in a future version. We have added version 5 support but are not yet upgrading users databases. You can choose to upgrade your database to version 5 by adjusting your connection string to perform an upgrade on the database. We suggest backing up your database file before doing so.

In appsettings.json, you will need to change the database type to LiteDBv5 and add the upgrade parameter to the connection string.

    "Data": {
    "RepositoryPath": "%ProgramData%\\UniversalAutomation\\Repository",
    "ConnectionString": "filename=%ProgramData%\\UniversalAutomation\\database.db;upgrade=true",
    "DatabaseType": "LiteDBv5",

Install PowerShell Universal

choco install powershelluniversal

Install-Module Universal
Install-PSUServer -AddToPath
Start-PSUServer -Port 5000

Install-Module Universal
Install-PSUServer -AddToPath
Start-PSUServer -Port 5000

Open PowerShell Universal

By default, PowerShell Universal is running on port 5000 of localhost. You can access the admin console with the user name admin and any password.

PowerShell Universal Visual Studio Code Extension

You can connect to your instance of PowerShell Universal, browse and insert samples and get up and running right away.

Install the Extension

Install the extension by searching for it in the extension page and clicking Install.

Connect to PowerShell Universal

Click the PowerShell Universal icon on the left hand side and the extension will attempt to connect using the default URL and user name. The extension will notify you once it has connected.

Inserting a Sample

Learn more about the various features of PowerShell Universal

Download the latest version of PowerShell Universal.

The Ironman Software blog has articles about PowerShell Universal.

Connect with the PowerShell Universal community.

Chat with other PowerShell Universal users.

Purchase a license for the features of PowerShell Universal.

File a bug report or feature request for PowerShell Universal.

Check out video tutorials for PowerShell Universal.

PowerShell Universal is licensed per server. We provide licenses for individuals and organizations.

What's a server?

A server is a single running instance of PowerShell Universal.

Free Use Restrictions

Universal can be used forever for free with the following limitations.

Universal API

• No authentication

• No Rate Limiting

Universal Automation

• 25 jobs per day

• 2 concurrent jobs

• No Triggers

Universal Dashboard

• No authentication

• No access to diagnostic tools

Getting Started

PowerShell Module

You can use the PowerShell Universal PowerShell module to install the Universal server. To install the module, use Install-Module.

Install-Module Universal

To install the Universal server, you can use Install-PSUServer.

Install-PSUServer -LatestVersion

You can configure the path that the server is stored in by using the -Path parameter.

Install-PSUServer -Path (Join-Path $Env:AppData "PSU")

You can add the PSU server to the PATH environment variable by use the -AddToPath parameter.

Install-PSUServer -AddToPath

Once the server has been installed, you can use Start-PSUServer to start it.

Start-PSUServer -Port 8080

You can specify the path to the executable using the -ExecutablePath parameter. If you have set the location of the server to -AddToPath with Install-PSUServer, Start-PSUServer should find the executable automatically.

Start-PSUServer -Port 8080 -ExecutablePath (Join-Path $MyPath "Universal.Server.exe")

Chocolatey Package (Windows)

You can login with the "admin" user and any password.

choco install powershelluniversal

Winget (Windows)

You can install PowerShell Universal using Winget. It will run the MSI and install as a service.

winget install ironmansoftware.powershelluniversal

You can also specify the --silent flag to prevent the installer from showing and the web browser from opening at the end of the install.

winget install ironmansoftware.powershelluniversal --silent

ZIP Install

Windows

You can start Universal by unzipping the contents, unblocking the files and then executing Universal.Server.exe.

Expand-Archive -Path .\Universal.zip -DestinationPath .\Universal
Get-ChildItem .\Universal -Recurse | Unblock-File
Start-Process .\Universal\Universal.Server.exe

Linux

On Linux, start the process Universal.Server. You may need to chmod +x the file if it does not start.

Docker

MSI Install (Windows)

The MSI install will create a PowerShell Universal service and open the admin console after installation.

Properties

SUPPRESSBROWSER

Setting the SUPPRESBROWSER MSI property to true will prevent the browser from opening after installation.

Next Steps

At this point, Universal is up and running. Please consult other sections in this documentation for instructions on how to configure, secure, and start using PowerShell Universal. Happy Scripting!

PowerShell Universal can be managed with the PowerShell Universal Visual Studio Code extension. It allows you to connect to a local Universal instance and manage APIs, dashboards and scripts.

Installation

Configuration

The extension will prompt you for the URL and App Token used to connect to your PowerShell Universal instance. Follow the instructions within the extension when it starts up.

Features

The PowerShell Universal extension adds a new activity pane panel for PowerShell Universal. It has the following sections.

APIs

You can manage APIs with the extension. You will see a list of APIs. You can click the Open endpoints.ps1 button to view the endpoints file and add new endpoints. Clicking the refresh button will reload any endpoints you add. You can click the Insert Invoke-RestMethod to Console to add a call to the endpoint to the PowerShell Integrated Console.

Dashboards

You can manage dashboards with the extension. You will see a list of dashboards underneath this section. You can open the dashboards.ps1 script, open the a single dashboard's script, restart a dashboard and view dashboards. When you open a dashboard script, the dashboard modules will automatically be loaded so that IntelliSense works in VS Code.

Debug Dashboard Process

You can connect the Visual Studio debugger to the dashboard process by right clicking on the dashboard and click Debug Dashboard Process. This requires the PowerShell extension for Visual Studio Code.

After connecting the debugger, you can run commands such as Get-Runspace and Debug-Runspace to begin debugging aspects of your dashboard.

View Dashboard Logs

You can view dashboard logs by right clicking on the dashboard and clicking View Logs. They will open in a new tab.

Scripts

You can manage scripts with the extension. You will see a list of available scripts underneath this section. You can edit the scripts.ps1, edit an individual script and run scripts. When running scripts, you will receive feedback about the status of the script. Scripts with parameters are not supported in VS Code. You can still run them in PowerShell Universal.

Sample Browser

The sample browser can be used to insert samples from the PowerShell Universal Sample Repository into your PowerShell Universal instance. Just save the files it updates and your PowerShell Universal system will reflect the changes.

Windows

Linux

• PowerShell v7.0 or great

• Validated Distributions: Ubuntu 18.04

Mac OS X

Component Examples

We maintain several component libraries that you can use in your dashboards directly or as examples.

Single-File Configuration Examples

This page contains examples of PowerShell Universal configurations. All examples are built using single-file hosting and configuration. These examples assume that you have PowerShell Universal installed. To install PowerShell Universal, use the following command line.

You can login to PowerShell Universal using the username admin and any password.

Table of Contents

• Active Directory
• Hyper-V
• Image Processing
• Monitoring
• Slack

Convert JPEG to PNG

This examples accepts a JPEG file and converts to to a PNG using Universal Dashboard. To implement this example, we need to use published folders and a dashboard that uses UDForm and the UDUpload component. After converting the image, it displays it.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUPublishedFolder -Path 'C:\images' -RequestPath '/images'

    New-PSUDashboard -Name 'Convert' -BaseUrl '/' -Framework 'UniversalDashboard:Latest' -Content {
        New-UDDashboard -Title 'Convert' -Content {
            New-UDForm -Content {
                New-UDUpload -Id 'image' -Text 'Image to Convert'
            } -OnSubmit {
                $bytes = [System.Convert]::FromBase64String($EventData.image.Data)

                $Bitmap = [System.Drawing.Image]::FromStream([System.IO.MemoryStream]::new($bytes))
                $Bitmap.Save("C:\images\$($EventData.Image.Name)".Replace("jpeg", "png"), 'PNG')

                New-UDImage -Url "/images/$($EventData.Image.Name.Replace('jpeg', 'png'))"
            }
        }
    }

}

Convert JPEG to PNG API

This example is similar to the dashboard example but exposes the functionality as an API rather than a webpage. The API accepts a POST request that contains the image as a the body. We use the $Data variable which contains the byte array for the image file and then convert it use the same method. We then take advantage of the New-PSUApiResponse cmdlet to return a custom response.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUEndpoint -Url "/image" -Method POST -Endpoint {
        $Bitmap = [System.Drawing.Image]::FromStream([System.IO.MemoryStream]::new($Data))
        $Bitmap.Save("$Env:Temp\image.png", 'PNG')

        New-PSUApiResponse -Data ([IO.File]::ReadAllBytes("$Env:Temp\image.png")) -ContentType 'application\png'

        Remove-Item "$Env:Temp\image.png"
    }
}

We can invoke the API with Invoke-WebRequest. The below example posts the IMG_2260.jpeg file and converts it to an image.png file.

Invoke-WebRequest -InFile .\IMG_2260.jpeg -Uri http://localhost:8080/image -Method POST -OutFile .\image.png

Rate Limited Conversion API

This example provides the same functionality as the previous example but rate limits the number of requests to 5 per 10 minutes. We can use New-PSURateLimit to set the request limit.

Start-PSUServer -Port 8080 -Configuration {
    Set-PSULicense -Key "key"

    New-PSURateLimit -Endpoint "POST:/image" -Period ([TimeSpan]::FromMinutes(10)) -Limit 5

    New-PSUEndpoint -Url "/image" -Method POST -Endpoint {
        $Bitmap = [System.Drawing.Image]::FromStream([System.IO.MemoryStream]::new($Data))
        $Bitmap.Save("$Env:Temp\image.png", 'PNG')

        New-PSUApiResponse -Data ([IO.File]::ReadAllBytes("$Env:Temp\image.png")) -ContentType 'application\png'

        Remove-Item "$Env:Temp\image.png"
    }
}

Invoking this request most than the specified number of times will result in an error.

PS C:\Users\adamr> invoke-webrequest -InFile .\IMG_2260.jpeg -Uri http://localhost:8080/image -Method POST -OutFile .\image.png
Invoke-WebRequest: API calls quota exceeded! maximum admitted 5 per .

List Locked Accounts

Shows an example of how to list locked Active Directory accounts. This example assumes that the user running PowerShell Universal has access to the local Active Directory environment.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUScript -Name 'LockedAccounts' -ScriptBlock {
        Search-ADAccount -LockedOut
    }
}

Locked accounts will be listed on the job page's pipeline output.

You can also access the locked accounts by using the Universal PowerShell module.

$Job = Get-PSUJob -Script (Get-PSUScript -name 'LockedAccounts.ps1') -First 1 -OrderDirection Descending
Get-PSUJobPipelineOuptut -Job $Job

Reset Password

Shows an example of how to reset an Active Directory user account using PowerShell Universal Automation. This script accepts the identity of the account to reset, the password to set, whether to unlock the account and whether to require the user to change their password on logon.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUScript -Name 'Reset Password' -ScriptBlock {
        param(
            [String]$Identity,
            [String]$Password,
            [Switch]$Unlock,
            [Switch]$ChangePasswordOnLogon
        )

        $SecurePassword = ConvertTo-SecureString $Password -AsPlainText -Force

        Set-ADAccountPassword -Identity $Identity -NewPassword $SecurePassword -Reset -Server $ComputerName -Credential $Domain

        if ($Unlock)
        {
            Unlock-ADAccount –Identity $Identity -Server $ComputerName -Credential $Domain
        }

        if ($ChangePasswordOnLogon)
        {
            Set-ADUser –Identity $Identity -ChangePasswordAtLogon $true -Server $ComputerName -Credential $Domain
        }
    }
}

Restore Deleted User

In this example, we use Universal Dashboard to create a dashboard that displays a table that includes all the deleted user accounts for the domain. It creates a custom column with a button that includes a Restore button that executes a script to restore the specified account. This example assumes that the identity running the script is capable of accessing Active Directory.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUScript -Name 'Restore User.ps1' -ScriptBlock {
        param($DistinguishedName)

        Restore-ADObject -Identity $DistinguishedName
    }

    New-PSUDashboard -Name 'Restore User' -BaseUrl '/' -Framework 'UniversalDashboard:Latest' -Content {
        New-UDDashboard -Title 'Restore User' -Content {
            $Columns = @(
                New-UDTableColumn -Property Name -Title "Name"
                New-UDTableColumn -Property DistinguishedName -Title "Distinguished Name"
                New-UDTableColumn -Property Restore -Title Restore -Render {
                    $Item = $EventData
                    New-UDButton -Id "btn$($Item.ObjectGuid)" -Text "Restore" -OnClick { 
                        Show-UDToast -Message "Restoring user $($Item.Name)" -Duration 5000

                        Invoke-UAScript -Name 'Restore User.ps1' -DistinguishedName $Item.DistinguishedName | Tee-Object -Variable job | Wait-UAJob

                        $Job = Get-UAJob -Id $Job.Id 
                        if ($Job.Status -eq 'Completed')
                        {
                            Show-UDToast -Message "Restored user $($Item.Name)" -Duration 5000
                        }
                        else 
                        {
                            $Output = Get-UAJobOutput -JobId $Job.Id | Select-Object -Expand Message
                            Show-UDToast -Message "Failed to restore user. $($Output -join "`n")" -BackgroundColor red -MessageColor white -Duration 5000
                        }
                    }
                }
            )

            $DeletedUsers = Get-ADObject -Filter 'IsDeleted -eq $true -and objectClass -eq "user"' -IncludeDeletedObjects | ForEach-Object {
                @{
                    distinguishedname = $_.DistinguishedName
                    name = $_.Name
                }
            }
            New-UDTable -Data $DeletedUsers -Columns $Columns
        }
    }
}

Virtual Machine Creator

This example can be used to create virtual machines on a Hyper-V host. This dashboard assumes it's being run on the host in question. You could adjust the dashboard script to run on a remote host.

Retro Dashboard

This retro looking dashboard displays the top 10 CPU and memory using processes, disk usage, and live CPU and network usage. It also demonstrates how to use themes to custom the backcolor, text color and font family.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUDashboard -Name 'Hacker Dash' -BaseUrl '/' -Component 'UniversalDashboard.Charts:1.3.1' -Framework 'UniversalDashboard:Latest' -Content {

    $Green =  '#4bdd35'

    $Theme = @{
        palette = @{
            primary = @{
                main = $Green
            }
            background = @{
                default = 'black'
                paper = 'black'
            }
            text = @{
                primary = $Green
            }
        }
        typography = @{
            fontFamily = "Consolas"
        }
    }

    $Pages = @()
    $Pages += New-UDPage -Name 'Hacker Dash' -Content {

        New-UDRow -Columns {
            New-UDColumn -LargeSize 4 -Content {
                    New-UDCard -Title 'Top CPU Usage Processes' -Content {
                        New-UDElement -Tag 'pre' -Content {
                            (Get-Process | Sort-Object -Property Cpu -Descending | Select-Object -First 10 | Out-String)
                        }
                    } 

            }
            New-UDColumn -LargeSize 4 -Content {
                $Data = Get-CimInstance -Class CIM_LogicalDisk | Select-Object @{Name="Size";Expression={$_.size/1gb}}, @{Name="FreeSpace";Expression={$_.freespace/1gb}}, @{Name="Free (%)";Expression={"{0,6:P0}" -f(($_.freespace/1gb) / ($_.size/1gb))}}, DeviceID, DriveType | Where-Object DriveType -EQ '3'

                $SizeDs = New-UDChartJSDataset -DataProperty Size -Label Size -BackgroundColor $Green
                $MemoryDs = New-UDChartJSDataset -DataProperty FreeSpace -Label 'Free Space' -BackgroundColor $Green


                $Options = @{
                    Type = 'bar'
                    Data = $Data
                    Dataset = @($SizeDs, $MemoryDs)
                    LabelProperty = "DeviceId"
                }

                New-UDChartJS @Options
            }
            New-UDColumn -LargeSize 4 -Content {
                New-UDChartJSMonitor -LoadData {
                     Get-CimInstance Win32_Processor | Measure-Object -Property LoadPercentage -Average | Select -Expand Average | Out-UDChartJSMonitorData
                } -Labels "CPU" -ChartBackgroundColor 'black' -ChartBorderColor $Green -RefreshInterval 1
            }
        }

        New-UDRow -Columns {
            New-UDColumn -LargeSize 4 -Content {
                    New-UDCard -Title 'Top Memory Usage Processes' -Content {
                        New-UDElement -Tag 'pre' -Content {
                            (Get-Process | Sort-Object -Property WorkingSet64 -Descending | Select-Object -First 10 | Out-String)
                        }
                    } 
            }
            New-UDColumn -LargeSize 4 -Content {
                New-UDChartJSMonitor -LoadData {
                     (Get-NetAdapterStatistics -Name 'Wi-Fi').SentBytes | Out-UDChartJSMonitorData
                } -Labels "Send Bytes" -ChartBackgroundColor 'black' -ChartBorderColor $Green -RefreshInterval 1
            }
            New-UDColumn -LargeSize 4 -Content {
                New-UDChartJSMonitor -LoadData {
                     (Get-NetAdapterStatistics -Name 'Wi-Fi').ReceivedBytes | Out-UDChartJSMonitorData
                } -Labels "Received Bytes" -ChartBackgroundColor 'black' -ChartBorderColor $Green -RefreshInterval 1
            }
        }



    } 

    New-UDDashboard -Title "Hello, World!" -Pages $Pages -Theme $Theme
    }
}

Windows Performance Counter Charts

In this example, we take advantage of Universal Dashboard scheduled endpoints, the in-memory cache and the UDMonitor component. We update the counter sets to use in the cache and load each of the counters' value in the set into an array to use in the dashboard. We then create a dashboard that dynamically creates UDMonitor charts within the page. Each monitor will update every 3 seconds with new data.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUDashboard -Name 'Performance' -BaseUrl '/' -Framework 'UniversalDashboard:Latest' -Content {

        $Schedule = New-UDEndpointSchedule -Every 5 -Second
        New-UDEndpoint -Schedule $Schedule -Endpoint {
            if (-not $Cache:CounterSets)
            {
                $Cache:CounterSets = Get-Counter -ListSet * | Select-Object -ExpandProperty 'CounterSetName'
                $Cache:CurrentSets = @( "IPv4")
            }

            $Cache:Data = @()
            foreach($set in $Cache:CurrentSets)
            {
                $Data = @{
                    Set = $set
                    Counters = @()
                }

                $Counters = (Get-Counter -ListSet $set).Paths
                foreach($Counter in $Counters)
                {

                    $Value = 0 
                    try {
                        $Value = (Get-Counter -Counter $Counter -ErrorAction SilentlyContinue).CounterSamples[0].CookedValue
                    } catch {}

                    $Data.Counters += @{ Name = $Counter; Value = $Value }
                }

                $Cache:Data += $Data
            }
        } | Out-Null

        New-UDDashboard -Title 'Performance' -Content {
            foreach($Data in $Cache:Data)
            {
                New-UDTypography -Text $Data.Set -Variant h4
                New-UDRow -Columns {
                    foreach($Counter in $Data.Counters)
                    {
                        New-UDColumn -Size 4 -LargeSize 3 -Content {
                            New-UDTypography -Text $Counter.Name
                            New-UDChartJSMonitor -LoadData {
                                $Set = $Cache:Data | Where-Object Set -eq $Data.Set
                                $Value = ($Set.Counters | Where-Object Name -eq $Counter.Name).Value
                                if (-not $Value)
                                {
                                    $Value = 0
                                }
                                $Value | Out-UDChartJSMonitorData
                            } -Labels "Value" -ChartBackgroundColor "#297741" -RefreshInterval 3 -DataPointHistory 10
                        } 
                    }
                }
            }
        }
    } -Component @("UniversalDashboard.Charts:1.3.0")
}

Display Log Messages in PowerShell Universal

This example configures PowerShell Protect to send log messages to a PowerShell Universal instance. It sends HTTP POST requests to the configured server.

PowerShell Protect Configuration

This configuration checks to see if the user has included the string \\corp\human-resources anywhere in their script. If they do, it sends an HTTP POST to the URL http://localhost:8080/protect

The body of the HTTP request will contain the computer name and user name separated by a comma.

$Condition = New-PSPCondition -Property "script" -Contains -Value "\\corp\human-resources"
$Block = New-PSPAction -Http -Address "http://localhost:8080/protect" -Format "{computerName},{userName}" -Name 'Universal'
$Rule = New-PSPRule -Action $Block -Condition $Condition -Name "HR Share"
$Config = New-PSPConfiguration -Rule $Rule -Action $Block -License "<License></License>"

Set-PSPConfiguration -Configuration $Config -FileSystem

PowerShell Universal Configuration

This PSU configuration defines an endpoint to accept the POST data from PowerShell Protect. It then saves the data to a file. It also defines a dashboard that will read the data and display it in a table. This assumes that you have installed the PowerShell Universal module and server.

Start-PSUServer -Port 8080 -Configuration {    
    New-PSUEndpoint -Url "/protect" -Method POST -Endpoint {
       $Data = "$Env:Temp\data.csv"        
       if (-not (Test-Path $Data))        
       {            
          "computer,user" | Out-File $Data        
       }        
       $Body | Out-File $Data    
    }​    
    New-PSUDashboard -Name "Protect" -Content {        
       New-UDDashboard -Title 'Protect' -Content {            
          $Data = Import-Csv -Path "$Env:Temp\data.csv"            
          New-UDTable -Data $Data        
       }    
    }
 }

Send Message to Slack

This example uses a custom Slack webhook to send a message from a Universal API.

You can invoke this API by calling Invoke-RestMethod

The following message will show up in Slack.

Send Slack Message on Failed Job

This example takes advantage of triggers to send a message to Slack when a job fails within PowerShell Universal. We define two scripts. The first script simply throws and error and is set to fail by using the -ErrorAction Stop setting. The second script receives the job that failed and sends a message to the team's Slack channel.

When the failing script is running, it will report failure in the UI.

Due to the failure, the trigger will execute and send a message to Slack.

Universal is a cross-platform solution for developing web-based tools with PowerShell. It currently provides three main features which include APIs, Automation and Dashboards.

Universal provides an Administrator console, management REST API, PowerShell cmdlets and a idempotent configuration system using PowerShell scripts.

APIs

• Build REST endpoints with PowerShell

• Accept common HTTP verbs

• Process request bodies

• Build dynamic URLs with route parameters and query strings

Automation

• Run scripts and view output, pipeline output, and parameters

• Respond to feedback from cmdlets like Read-Host

• Schedule scripts with CRON or one-time schedules

• Automatically build input forms based on param blocks

• Set variables and secrets that can be used throughout scripts

Dashboard

• Build web pages with PowerShell script

• Include input forms, charts and tables

• Build interactive websites with buttons, message boxes and more

Platform

• Cross-platform and supported on Windows and Linux

• Git integration for configuration files, scripts and dashboards

• Built-in authentication and authorization

• Support for Windows PowerShell as well as PowerShell

Licensing

Free to Use

Universal offers a lot of functionality for free. Below is a list of the features that require a paid license.

API

You can run as many APIs are you want for free. You will need to purchase a license if you would like to enable authentication, authorization and rate limiting.

Automation

Dashboard

With the free version of dashboard, you can run unauthenticated dashboards. You will not have access to the diagnostics or console pages.

Universal uses a variety of modern web frameworks and can have issues with older browsers such as Internet Explorer.

Endpoints are defined by their URI and HTTP method. Calls made to the Universal server that match the API endpoint and method that you define will execute the API endpoint script.

To invoke the above method, you could use Invoke-RestMethod.

Variable URL

URLs can contain variable segments. You can denote a variable segment using a colon (:). For example, the following URL would provide a variable for the ID of the user. The $Id variable will be defined within the endpoint when it is executed. Variables must be unique in the same endpoint URL.

To call this API and specify the ID, you would do the following.

Query String Parameters

Query string parameters are automatically passed into endpoints as variables that you can then access. For example, if you had an endpoint that expected an $Id variable, it could be provided via the query string.

The resulting Invoke-RestMethod call must then include the query string parameter.

Body

To access a request body, you will simply access the $Body variable. Universal $Body variable will be a string. If you expect JSON, you should use ConvertFrom-Json.

To call the above endpoint, you would have to specify the body of Invoke-RestMethod.

Form Data

You can pass data to an endpoint as form data. Form data will be passed into your endpoint as parameters.

You can then use a hashtable with Invoke-RestMethod to pass form data.

Param Block

You can use a param block within your script to enforce mandatory parameters and provide default values for optional parameters such as query string parameters. Variables such as $Body, $Headers and $User are provided automatically.

In the below example, the $Name parameter is mandatory and the $Role parameter has a default value of Default.

Returning Data

Data returned from endpoints will be assumed to be JSON data. If you return an object from the endpoint script block, it will be automatically serialized to JSON. If you want to return another type of data, you can return a string formatted however you chose.

Processing Files

Uploading Files

You can process uploaded files by using the $Data parameter to access the byte array of data uploaded to the endpoint.

You could also save the file into a directory.

Downloading Files

You can send files down using the New-PSUApiResponse cmdlet.

Returning Custom Responses

You can return custom responses from endpoints by using the New-PSUApiResponse cmdlet in your endpoint. This cmdlet allows you to set the status code, content type and even specify the byte[] data for the content to be returned.

You can also return custom body data by using the -Body parameter of New-PSUApiResponse.

Invoking the REST method will return the custom error code.

You can control the content type of the data that is returned by using the -ContentType parameter.

Persistent Runspaces

Persistent runspaces allow you to maintain runspace state between API calls. This is important for users that perform some sort of initialization within their endpoints that they do not want to execute on subsequent API calls.

By default, runspaces will be reset after each execution. This will cause variables, modules and functions defined during the execution of the API to be removed.

You can then assign the API environment in the settings.ps1 script.

Related Cmdlets

Server-side SQL Table

This example uses Universal Dashboard.

This example takes advantage of a SQL server and the New-UDTable cmdlet to create a table that retrieves data from a database table. The filtering, sorting and paging take place within the database.

This example assumes that we have a database called podcasts running in the local MS SQL Server. It has a table called shows that includes a column called host and a column called name.

Start-PSUServer -Port 8080 -Configuration {
    New-PSUDashboard -Name 'SQL' -BaseUrl "/" -Framework 'UniversalDashboard:Latest' -Content {
        New-UDDashboard -Title 'SQL' -Content {
            New-UDTable -Title 'Shows' -LoadData {
                $TableData = ConvertFrom-Json $Body

                $OrderBy = $TableData.orderBy.field
                if ($OrderBy -eq $null)
                {
                    $OrderBy = "name"
                }

                $OrderDirection = $TableData.OrderDirection
                if ($OrderDirection -eq $null)
                {
                    $OrderDirection = 'asc'
                }

                $Where = ""
                if ($TableData.Filters) 
                {
                    $Where = "WHERE "

                    foreach($filter in $TableData.Filters)
                    {
                        $Where += $filter.column.field + " LIKE '%" + $filter.value + "%' AND "
                    }

                    $Where += " 1 = 1"
                }

                $PageSize = $TableData.PageSize 
                # Calculate the number of rows to skip
                $Offset = $TableData.Page * $PageSize
                $Count = Invoke-DbaQuery -SqlInstance localhost\MSSQLSERVER -Database 'podcasts' -Query "SELECT COUNT(*) as count FROM shows $Where"

                $Data = Invoke-DbaQuery -SqlInstance localhost\MSSQLSERVER -Database 'podcasts' -Query "SELECT * FROM shows $Where ORDER BY $orderBy $orderdirection OFFSET $Offset ROWS FETCH NEXT $PageSize ROWS ONLY" | ForEach-Object {
                    @{ 
                        name = $_.name 
                        host = $_.host
                    }
                } 
                $Data | Out-UDTableData -Page $TableData.page -TotalCount $Count.Count -Properties $TableData.properties
            } -Columns @(
                New-UDTableColumn -Property 'name' -Sort $true -Filter $true
                New-UDTableColumn -Property 'host' -Sort $true -Filter $true
            ) -Sort -Filter
        }
    }
}

Features

• Simple Background Jobs - Universal Automation provides the ability to run simple background jobs in Windows PowerShell and PowerShell 7. Jobs can be scheduled to run with simple CRON expressions.

• Runs anywhere - Built on .NET to support multi-platform, docker, raspberry pi, and just about anything!

• Persistence - Universal Automation job status is automatically backed by database persistence to allow for easy reporting of job results and data.

• PowerShell First - Build from the ground up for Administrators/Developers/DevOps professionals familiar with PowerShell. UA integrates with Write-Progress, the pipeline, and user input, like Read-Host, to allow users to interact with scripts via the UA dashboard.

Developing APIs

You can add APIs by using the admin console or through the editor in Visual Studio Code.

To add an API in the Admin Console, you can visit http://localhost:5000/admin/apis and click Add Endpoint.

Once an endpoints.ps1 file has been created, you can click the Open Endpoints.ps1 button within the API tree view to view the configuration file for APIs.

The configuration file uses the Universal PowerShell cmdlets to define the endpoints within Universal.

If you created a blank endpoint, it would look something like this.

New-PSUEndpoint -Url "/test" -Endpoint { 
    # Enter your script to process requests.
}

If you edit the endpoints.ps1 file, it will update the API automatically. For example, if I added a new API, it would then appear in the admin console.

New-PSUEndpoint -Url "/test" -Endpoint { 
 "hello"
}

New-PSUEndpoint -Url "/test2" -Endpoint { 
    # Enter your script to process requests.
}

Universal provides the ability to define REST API endpoints using PowerShell. When the endpoints are executed by a compatible HTTP client, the PowerShell script will execute and return the result to the end user.

Execution Environment

The REST API execution environment runs in your default PowerShell version. Unlike Automation jobs, which can also be run via the Universal management API, APIs that you define are run in a single PowerShell process. Because the PowerShell process is not started and stopped for each call to the endpoint, the API is much faster.

Set-PSUSetting -ApiEnvironment '7.1'

Performance

Performance is relative to the hardware and network conditions that you are running Universal on. That said, in ideal conditions you can expect the Universal APIs to service about 500 requests per second. This is with an entirely empty endpoint so any script that you add to that endpoint will reduce the throughput. The reduction of throughput will depend on the cmdlets and script executed within the API endpoint.

Variables

There are a set of predefined variables that are available in API endpoints. You'll be able to use these variables in your scripts.

Related Cmdlets

REST API authentication requires a Universal API license. Once enabled, you will be able to enforce authentication and authorization on your endpoints.

Defining Secure Endpoints

You can define secure endpoints in the UI by enabling authentication.

You can also define secure endpoints using the .universal/endpoints.ps1 file or the Management API using New-PSUEndpoint.

New-PSUEndpoint -Url '/endpoint' -Method 'GET' -Endpoint {
   "Hello, world!"
} -Authentication

When authentication is enabled, it will enforce the use of one of the configured authentication methods. APIs support the following methods.

• JWT App Tokens

• Windows Authentication

• Cookie Authentication

Accessing Secure Endpoints

Once you have defined a secure endpoint, you will need to provide authentication and authorization to access the endpoint.

Authenticating with tokens

To authenticate with tokens, first, you need generate a new app token for use. You can use the Grant-PSUAppToken cmdlet to do so remotely or you can create an app token in the UI using the Settings Security AppTokens tab.

Click Grant App Token to create a new one.

Once you have created your app token, you can now use it to authenticate against the secure endpoint. To do so, pass the Authorization header along with the request.

Invoke-RestMethod http://localhost:5000/auth -Headers @{ Authorization = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMWUyY2IzNzAtMmMyNS00ZDU5LTk4YzgtMzc5MTFjMDAyZmI5Iiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmYiOjE2MDU2NjEyNTUsImV4cCI6MTYzNzM2NzI1OCwiaXNzIjoiSXJvbm1hblNvZnR3YXJlIiwiYXVkIjoiUG" }

Authenticating with Windows Authentication

Invoke-RestMethod http://localhost:5000/auth -UseDefaultCredentials

Authenticating with Cookies

To authenticate with cookies, you will first need to call the login API to receive a valid cookie from the system. You can use Invoke-WebRequest to do so. Pass the user name and password as the body. Specify the -SessionVariable parameter to establish a session.

Invoke-WebRequest http://localhost:5000/api/v1/signin -Body (@{ 
    UserName = "Admin"
    Password = "Any"
} | ConvertTo-Json) -ContentType 'application/json' -SessionVariable mySession -Method POST

Once you have successfully authenticated, you can use your $mySession variable to call secure endpoints.

 Invoke-WebRequest http://localhost:5000/auth -WebSession $mySession

Enforcing Roles

In addition to creating endpoints that require authentication, you can also enforce roles by define a role in the New-PSUEndpoint cmdlet or by selecting one in the UI. If a role is selected, it's possess the role.

Windows and Cookie authentication will assign roles based on the Identity of the user and the role policies as they are applied.

JWT app tokens will use the role that was defined when they were generated.

Related Cmdlets

Parameters

Jobs support automatically generating forms with parameters based on your script's param block. The type of control will change based on the type you define in the block. Parameters that are mandatory will also be required by the UI.

Basic Parameters

Parameters can be simply defined without any type of parameter attribute and they will show up as text boxes in the UI.

param($Test)

$Test

Type Parameters

UA supports various types of parameters. You can use String, String[], Int, DateTime, Boolean, Switch and Enum types.

String

You can define string parameters by specifying the [String] type of by not specifying a type at all. Strings will generate a textbox.

param(
    [String]$Textbox,
    $Textbox2
)

String Arrays

You can specify string arrays by using the [String[]] type specifier. String arrays will generate a multi-tag select box.

param([String[]]$Array)

Date and Time

You can use the [DateTime] type specifier to create a date and time selector.

param([DateTime]$DateTime)

Boolean

You can use a [Bool] type selector to create a switch.

param([Bool]$Switch)

Integer

You can define a number selector by using the [Int] type specifier.

param([Int]$Number)

Switch Parameter

You can define a switch parameter using the [Switch] type specifier to create a switch.

param([Switch]$Switch)

Enumerations

You can use System.Enum values to create select boxes. For example, you could use the System.DayOrWeek to create a day of the week selection box.

param([System.DayOfWeek]$DayOfWeek)

Help Messages

You can define help messages for your parameters by using the HelpMessage property of the Parameter attribute.

param(
    [Parameter(HelpMessage = "Class you want to enroll in")]
    [string]$Class
)

Required Parameters

You can use the Parameter attribute to define required parameters.

param(
    [Parameter(Mandatory)]
    $RequiredParameter
)

$RequiredParameter

Passing Parameters from PowerShell

You can pass parameters from PowerShell using the Invoke-UAJob cmdlet. This cmdlet supports dynamic parameters. If you have a param block on your script, these parameters will automatically be added to Invoke-UAJob.

For example, I had a script named Script1.ps1 and the contents were are follows.

param($MyParameter)

$MyParameter

I could then invoke that script using this syntax.

Invoke-UAScript -Name 'Script.ps1' -MyParameter "Hello"

The result would be that Hello was output in the job log and pipeline.

By default, endpoints will return a 200 OK message even if there are errors. If an error occurs, you will get a blank response from the endpoint. This document demonstrates different ways to handle errors within APIs.

Automatically Returning Errors

To automatically return errors from APIs, you can change the default behavior by setting the -ErrorAction parameter of New-PSUEndpoint to Stop. Any errors will cause an 500 Internal Server Error to be returned with a list of the errors and stack trace.

Terminating errors will always return a 500 Internal Server Error.

New-PSUEndpoint -Url "/error" -Endpoint { 
   throw "Uh oh!"
} -ErrorAction stop

New-PSUEndpoint -Url /error2 -Endpoint {
    Write-Error "Whoa!"
} -ErrorAction Stop

You will notice different behavior in Windows PowerShell and PowerShell 7 when calling REST APIs that return errors. In Windows PowerShell, you will receive a generic error that doesn't return the error message.

PS C:\Users\adamr> invoke-restmethod http://localhost:5000/error2
invoke-restmethod : The remote server returned an error: (500) Internal Server Error.
At line:1 char:1
+ invoke-restmethod http://localhost:5000/error2
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], Web
   Exception
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

In PowerShell 7, when an error is returned, you will see the error message returned.

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error 

Invoke-RestMethod: Uh oh!
at , : line 2
at , : line 1

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/error2

Invoke-RestMethod: Whoa
at , : line 2
at , : line 1

You can retrieve the error message in Windows PowerShell, by using the following syntax.

PS C:\Users\adamr> try { invoke-restmethod http://localhost:5000/error2 } catch { [System.IO.StreamReader]::new($_.Exception.Response.GetResponseStream()).ReadToEnd()}
Whoa!
at <ScriptBlock>, <No file>: line 2
at <ScriptBlock>, <No file>: line 1

Manually Returning Errors

To manually return errors, you need to use the New-PSUApiResponse cmdlet. This cmdlet allows you to define the status code and body for the response.

In this example, we are returning a 404 error code from the endpoint.

New-PSUEndpoint -Url /broken -Endpoint {
    New-PSUApiResponse -StatusCode 404 -Body 'Failed!'
}

Similar to the automatic error codes, error codes returned manually will as display better in PowerShell 7. Here's an example of calling the endpoint.

PS C:\Users\adamr\Desktop> invoke-restmethod http://localhost:5000/broken

Invoke-RestMethod: Failed!

If called from Windows PowerShell, you will receive an error similar to the one returned automatically.

PS C:\Users\adamr> invoke-restmethod http://localhost:5000/broken
invoke-restmethod : The remote server returned an error: (404) Not Found.
At line:1 char:1
+ invoke-restmethod http://localhost:5000/broken
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
    + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-RestMethod], Web
   Exception
    + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeRestMethodCommand

You can choose to return error codes if certain conditions are met by using your PowerShell script within the endpoint.

New-PSUEndpoint -Url /user/:name -Endpoint {
    if ($Name -eq 'User')
    {
        @{ UserName = "Adam" }
    }
    else
    {
        New-PSUApiResponse -StatusCode 404 -Body 'Unknown user!'    
    }

}

Related Cmdlets

Jobs are the result of running a script. Jobs are retained based on the script and server level settings.

Viewing Jobs

Jobs can be viewed by clicking the Automation / Jobs page. Click the View button to navigate to the job. Jobs in progress can also bee cancelled.

View Job Output

Standard job output is shown on the Output Tab of the job page. This should contain text from various PowerShell streams.

View Job Pipeline Output

Pipeline output for jobs are also stored within UA. Any object that is written to the pipeline is stored as CliXml and available for view within the Pipeline Output tab.

You can expand the tree view to see the objects and properties from the pipeline.

Viewing Errors

Any errors written to the error stream will be available on the Error tab within the job page.

Feedback

Some jobs will require feedback. Any script that contains a Read-Host call will wait until there is user interaction with that job. The job will be in a Waiting for Feedback state and you can respond to that feedback by click the Response to Feedback button on the job page.

Invoking Jobs from PowerShell

Invoke-UAScript -Script 'Script1.ps1' -RequiredParameter 'Hello'

Call Scripts from Scripts

You can also call UA scripts from UA scripts. When running a job in UA, you don't need to define an app token or the computer name manually. These will be defined for you. You can just call Invoke-UAScript within your script to start another script. Both jobs will be shown in the UI. If you want to wait for the script to finish, use Wait-UAJob.

Waiting for a Script to Finished

You can use the Wait-UAJob cmdlet to wait for a job to finish. Pipe the return value of Invoke-UAScript to Wait-UAJob to wait for the job to complete. Wait-UAJob will wait indefinitely unless the -Timeout parameter is specified.

Invoke-UAScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Wait-UAJob

Return Pipeline Data

You can use the Get-PSUJobPipelineOutput cmdlet to return the pipeline output that was produced by a job. This pipeline output will be deserialized objects that were written to the pipeline during the job. You can access this data from where you have access to the PowerShell Universal Management API.

Get-PSUJobPipelineOutput -JobId 10

Returning the last job's output

It may be required to return the output from a script's last job run. In order to do this, you will need to use a combination of cmdlets to retrieve the script, the last job's ID and then return the pipeline or host output.

$Job = Get-UAScript -Name 'Script.ps1' | Get-UAJob -OrderDirection Descending -First 1
Get-UAJobPipelineOutput -Job $Job
Get-UAJobOutput -Job $Job

Invoke a Script and Wait for Output

The following example invokes a script, stores the job object in a $job variable, waits for the job to complete and then returns the pipeline and host output.

Invoke-UAScript -Script 'Script1.ps1' -RequiredParameter 'Hello' | Tee-Object -Variable job | Wait-UAJob

$Pipeline = Get-UAJobPipelineOutput -Job $Job
$HostOutput = Get-UAJobOutput -Job $Job

Invoking Jobs with REST

You can call jobs over REST using the management API for PowerShell Universal. You will need a valid app token to invoke jobs.

Call Scripts with REST

To call a script, you call an HTTP POST to the script endpoint with the ID of the script you wish to execute.

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body "" -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Providing Parameters

To provide parameters to scripts, you will need to define the parameters are part of the body. Currently the value is required to be a CLIXML string.

$JobContext = @{
    JobParameters = @(
        @{ Name = "parameter1"; Value = '<Objs Version="1.1.0.1" xmlns="http://schemas.microsoft.com/powershell/2004/04">
          <S>String</S>
        </Objs>' },
    )
} | ConvertTo-Json -Depth 5

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

To generate CLIXML, you can use the PSSerializer class in PowerShell. You can pass any object into the serialize method.

If you want to pass a credential you will need to pass in the parameter as a variable. You do not need to serialize the variable name.

$JobContext = @{
    JobParameters = @(
        @{ Name = "parameter1"; Value = "myCredential"; IsVariable = $true },
    )
} | ConvertTo-Json -Depth 5

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Setting the Environment

You can set the environment by pass in the environment property to the job context. The property must be the name of an environment defined within your PSU instance.

$JobContext = @{
    Environment = "PowerShell 7"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Setting the Run As account

You can set the run as account by passing in the name of a PSCredential variable to the Credential property.

$JobContext = @{
    Credential = "MyUser"
} | ConvertTo-Json

Invoke-RestMethod http://localhost:5000/api/v1/script/7 -Method POST -Body $JobContext -Headers @{ Authorization = "Bearer appToken" } -ContentType 'application/json'

Variables Defined in Jobs

There are several built-in variables that are defined when a job is run. You can use these variables in your scripts to retrieve information about the current job.

Retrieving the user that started a script

You can retrieve the name of the user that started the script by using the UAJob variable

$UAJob.Identity.Name

Triggers allow for automation jobs to be started when certain events happen within PowerShell Universal. For example, this allows you to take action when jobs complete, the server starts or dashboards stop. Triggers are useful for assigning global error handling or sending notifications when certain things happen.

Trigger Events

The following types of events can be assigned a trigger.

• Job Started

• Job Completed

• Job Requesting Feedback

• Job Failed

• Dashboard Started

• Dashboard Stopped

• Server Started

• Server Stopping

Global Triggers

Global triggers will start the assigned script whenever the event type is invoked.

For example, the Script.ps1 will be run whenever any job is run.

New-PSUTrigger -Name 'Trigger' -EventType JobStarted -TriggerScript Script.ps1

Resource Triggers

Resource triggers will start the assigned script when the event takes place on the selected resource.

For example, the Script.ps1 will be run whenever the Dashboard is stopped.

New-PSUTrigger -Name 'Trigger' -EventType DashboardStopped -TriggerScript Script.ps1 -Dashboard 'Dashboard'

Event Metadata

Whenever a job is started from a trigger, it will be provided with metadata about object that caused the event to trigger.

Triggers related to jobs will be provided a $Job parameter.

param($Job)

$Job

Triggers related to dashboards will be provided a $Dashboard parameter.

param($Dashboard)

$Dashboard

Triggers related to the server status will not receive a parameter.

Related Cmdlets

Dashboards are individual websites created with Universal Dashboard. You can define settings for a dashboard and start and stop the dashboard from within the Universal administrative interface.

Adding a Dashboard

Dashboards can be added to Universal using the Add Dashboard button from the Dashboard / Dashboards page.

Name

Name is displayed throughout the UI and returned from the Universal cmdlets.

Base URL

The base URL is the URL that you will access to view this dashboard. This URL needs to be unique within this instance. You can specify the / root URL if you wish. You will have to visit /admin to login to the administrative page if you set the dashboard to the root URL.

File Name

The full file name to the dashboard file. This file needs to return a dashboard using New-UDDashboard.

Framework

The framework that the dashboard was designed for. By default, Universal Dashboard v2.9 and v3.0 are supported.

Environment

Auth

Enables authentication for the dashboard.

Role

Defines the role that is required to access the dashboard.

AutoStart

Determines whether the dashboard should start (or restart) when the server starts or changes are made to the dashboard files.

Starting and Stopping Dashboards

Similar to jobs, dashboards run in separate PowerShell processes. You can start and stop a dashboard process by clicking the Start or Stop button from the Dashboards page.

Viewing Diagnostic Information

You can view diagnostic information for a dashboard by clicking the Info button on the Dashboards page. This will show your start information for the dashboard as well as any error that were encountered when starting the dashboard.

Viewing the Dashboard

You can view the dashboard by clicking the View button. This will take you to the Base URL for the dashboard.

Executing Commands with the Dashboard

On the dashboard information page, click on the Console tab to view the UD console. The console allows you to run scripts from within the UD runspace so you can better debug the state of your script. You can evaluate variables and run commands that are available to the dashboard. You will be running in the context of your user in regards to the runspace but the process will be running as the service account user.

Adding Custom Component Libraries

Custom component libraries provide additional components to dashboards. There are three built in component libraries that are not automatically imported into your dashboards.

• UniversalDashboard.Charts

• UniversalDashboard.Map

• UniversalDashboard.CodeEditor

To add these components to your dashboard, you can use the dashboard UI.

Click the info button on the dashboard page.

Next, click the components button in the top right of your dashboard.

Finally, check the component library you'd like added to your dashboard.

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -Component @("UniversalDashboard.Charts:1.3.0")

Persistent Runspaces

Persistent runspaces allow you to maintain runspace state within your dashboard endpoints. This is important for users that perform some sort of initialization within their endpoints that they do not want to execute on subsequent calls.

By default, runspaces will be reset after each execution. This will cause variables, modules and functions defined during the execution of an endpoint.

New-PSUEnvironment -Name 'Env' -Path 'powershell.exe' -PersistentRunspace

You will need to ensure that the environment is used by the dashboard.

Automatically Granting App Tokens

You can automatically grant app tokens to users that visit dashboards. This is useful if you want to invoke the management API for PowerShell Universal from within a dashboard. Your dashboard will need to have authentication enabled and you will have to use the -GrantAppToken switch parameter on New-PSUDashboard.

New-PSUDashboard -Name 'Dashboard' -BaseUrl '/' -Framework "UniversalDashboard:Latest" -Authenticated -GrantAppToken

From within your dashboard, you can now invoke the management API without having to worry about app token management. The API will be invoked in the context of the user that is visiting the dashboard.

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDButton -Text 'Job' -OnClick {
        Invoke-UAScript -Name 'Test.ps1'
    }
}

Schedules can be assigned to scripts and allow you to define frequency and other parameters for a script such as run as credentials.

Scheduling a Job

To schedule a job, you can do so from the Automation / Schedules page and by clicking the New Schedule button. You can also schedule a script by click the Schedule option from the script's page.

Schedules can be defined based on simple selections like Every Minute or Every Hour or you can define CRON expressions yourself for more configurable schedules. You can also run One Time schedules that run once at a later date.

You can also define which user the scheduled job will run under as well as which PowerShell version to use.

Simple Schedules

Simple schedules are really just helpers for various standard CRON schedules. When you select one, it will define a CRON schedule for your.

CRON

One Time

One time schedules will run once in the future. You can select the time and day of when they will run.

Continuous

Continuous schedules will run over and over again. You can define a delay between each scheduled job run.

Parameters

Schedules support setting parameters for scripts. For example, if you have a script that accepts a parameter, you can choose to pass a value to the parameter during the schedule.

param($UserName)

$UserName

Within the modal for defining the schedule, you will have the option to set the parameter value.

When editing schedules from PowerShell, you can define the parameters on the New-PSUSchedule cmdlet. This cmdlet accepts dynamic parameters so that you can pass the values in for your schedule.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -UserName 'adam'

Environments

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -Environment '7.1'

Run As

You can define a Run As user in a script by using the -Credential parameter. The value should be the name of the variable that contains your credential.

New-PSUSchedule -Script "MyScript.ps1" -Cron '* * * * *' -Credential 'MyUser'

PowerShell Universal provides the ability to rate limit requests made to the web server. Rate limiting can be configured on a per endpoint and per period. By default, the client IP address is used to rate limit clients.

Configuration data for rate limits are stored in the ratelimits.ps1 file.

Configuring Rate Limiting

To configure rate limiting, you can visit the APIs / Rate Limiting page. Click the Add button and define a new rate limit rule.

Method

The Method is the HTTP method to for this rule. If you use * , all HTTP methods will be affected by this rule. You can also select a single method by picking it from the drop down.

Endpoint

The endpoint is the URL that you are rate limiting. You can rate limit all URLs by using a *. You can define specific URLs by define the relative path: /api/user.

Limit

The number of request in the time frame before rate limiting kicks in.

Period

The period over which the rate limit is counted. For example, if you select a period of 10 minutes and a limit of 100, then up to 100 requests can be made to the method and endpoint you have selected.

Allow Lists

To disable rate limiting for particular IP Addresses, clients and endpoints you can add them to the rate limiting allow lists. You will find these by clicking the settings button.

Related Cmdlets

Scripts are the basic entity within Universal Automation. Scripts are just PowerShell scripts. They are stored on disk and also persisted to a local or remote Git repository.

Add a New Script

To add a new script, you can click the New Script button within the Automation / Scripts page. There are various settings you can provide for the script.

Name

Name of the script as shown in Universal Automation. This will also be the name used to persist the script to disk. This setting needs to be unique within the current folder.

Description

A description of the script. This is shown in various places within the UA UI and also returned by the Universal cmdlets.

Disable Manual Invocation

Prevents a script from being run manually. This is enforced in the UI as well as the web server and cmdlets.

Manual Time

This setting is used to track the amount of time saved.

Max Job History

Defaults to 100. It defines the amount of jobs that are stored when running this script. Jobs are also cleaned up based on the server-wide job retention duration setting from within the Settings / General page.

Error Action

Changes how the script reacts when there is an error within the script. By default, terminating and non-terminating errors are ignored and the script will always be successful. You can change this setting to stop to cause scripts to fail immediately when an error is encountered.

PowerShell Version

Allows you to define the required PowerShell version for the script. By default, it uses the server-wide default PowerShell version. PowerShell versions are automatically located the first the Universal Server starts up. You can also add PowerShell Versions on the Settings / General page.

Timeout

The number of minutes before the script will timeout. The default value of 0 means the script will run forever. Once a script reaches it's time out, it will be cancelled.

Concurrent Jobs

Defines the maximum concurrent jobs the script can be run. Defaults to 100.

New-PSUScript -Name Script.ps1 -Path Script.Ps1 -ConcurrentJobs 1

Running a Script

You can run a script in the UI by click the Run button the Automation / Scripts page or by clicking View and then Run. In each case, you will be presented with the Run Dialog that allows you to select various settings for the job.

Running a Script With Parameters

Universal Automation automatically determines the parameters as defined within your scripts. It takes advantage of static code analysis to determine the type, default values and some validation that is then presented within the UI.

For example, you may have a script with the following parameters.

param(
    $Test,
    [DateTime]$Time, 
    [int]$Number,
    [PSCredential]$Credential,
    [System.ConsoleColor]$Color
)

The result is a set of input options that are based on the types of parameters.

Running a Script as Another User

To run as another user, simply add or import a PSCredential variable. From there, you can select the credential from within the run dialog.

Remoting

Note that you can use PowerShell remoting by taking advantage of Invoke-Command . We do not support the use of Enter-PSSession or Import-PSSession.

Related Cmdlets

Developing Scripts

To add scripts to the Universal platform, you can do it via the admin console or the file system. The Visual Studio Code extension also provides integration for managing the scripts.ps1 configuration file.

The Scripts tree view will provide access to each of your scripts, the admin console the scripts.ps1 file.

To add a new script to the Universal platform, you can create the PS1 file on the file system and then add the script to the scripts.ps1. The file name is relative to the repository folder. You can also use fully qualified file paths.

To edit a script in VS Code, click the Edit Script button.

The script will open in the VS Code editor.

Running Scripts

You can start scripts by clicking the Run Script button. This will start a Universal Automation job. You'll get notifications of the job's progress in VS Code.

Developing Schedules

You can edit schedules for scripts by editing the schedules.ps1 file. A link to the file is available in the configuration tree view.

Schedules are defined using New-PSUSchedule cmdlet.

Build interactive user interfaces and dashboards with PowerShell script. Integrate with your existing PowerShell modules and functions to bring data in from anywhere.

• Build tools for your help desk users

• Report on data in interactive visualizations like charts, calendars, maps and more

• Provide role-based access controls to pages and even individual components

When building dashboards, you will pick one of the two built in dashboard frameworks. The components that are available for that framework will different. You can find examples of each of the frameworks at the below links.

Dashboards can contain one or more pages. The simplest dashboard will contain a single page with some content. You can call any PowerShell cmdlet that is available on your machine to populate your dashboard.

Here's an example of simple dashboard that displays some text.

Components

Components are the individual widgets that you can place on you dashboard. There are components for displaying data, taking user input, adding text and images and more. Components can be downloaded as PowerShell modules and added to your dashboard.

Components are be caused using the standard verb-name syntax for any PowerShell cmdlet.

Pages

You can specify multiple pages within a dashboard. Each page defines a route. As for v3, all pages are dynamic. PowerShell will execute on each page load to render the new page. Since UD is a single page application, the web browser does not need to refresh the entire web page when navigating between the different dashboard pages.

Built-in Variables

There are several built-in variables that are available in dashboards.

Debugging

When building a dashboard you will likely run into issues with cmdlet calls or syntax. Dashboards will auto reload as you make changes to the dashboard files. If a dashboard fails to start, you can navigate to the admin page, click Dashboards and click the Info button next to your dashboard.

The Log tab will show all the logging coming from the PowerShell execution from within in your dashboard. This should allow you to easily see errors and warnings coming from your dashboard.

You can use Write-Debug to add additional log messages to your dashboard. To enable debug logging, you will have to set the $DebugPreference variable at the top of your dashboard script.

PowerShell Universal Dashboard v2.9 is a PowerShell module that allows you to create dashboard with PowerShell script. It is the predecessor to PowerShell Universal. The technology the enabled UD has been migrated into PowerShell Universal. You should be able to run the same PowerShell scripts in PowerShell Universal that you would in Universal Dashboard with some minor modifications.

Migrating from Universal dashboard to PowerShell Universal

No need to call Start-UDDashboard

In Universal, all you need to do is return the result of New-UDDashboard from your script. There is no need to call Start-UDDashboard. The configuration of the webserver is taken place using the PSU appsetting.json file.

No need to call New-UDEndpointInitialization

This cmdlet has been removed from Universal Dashboard. There is no longer a need to call it.

Scheduled Endpoints

You do not need to pass the value of a scheduled endpoint to anything. You can just call New-UDEndpoint with a endpoint schedule and it will automatically be registered with PSU.

REST APIs

Authentication and Authorization

Authentication and authorization are now handled by PSU and there is no need to configure UD login pages. Authentication and authorization are configured with the PSU appsettings.json file. Dashboard's themselves can be either authenticated or not authenticated. A license is required to enable authenticated dashboards.

To enable role-based access controls, you can assign roles to pages and use the automatic $Roles variable to check which roles the user is a part of. The $User variable will provide the name of the user.

Authorization Policies

Authorizations policies in Universal work very similar to the ones in Universal Dashboard, you will define them using the New-PSURole cmdlet. When you define the role, you have the option to define a policy that will assign that role automatically to a user.

For example, let's adjust a claims policy from Universal Dashboard for Universal.

Universal Dashboard

Universal

Enforcing Roles

Much like the Get-UDAuthorizationPolicy cmdlet in Universal Dashboard, you also have access to the assigned roles for users in Universal. Simply check the $Roles variable to see which roles the user has.

Published Folders

Migrating to Universal Dashboard v3

This section contains migration information for upgrading from UDv2 to UDv3. They are vastly different frameworks and will require rewriting your dashboard. Many of the concepts are the same.

Pages

Pages have a different behavior in v3. All pages are dynamic pages. This means that you don't have to worry about whether a page will be generated at run time or doing start up. Pages are always generated during runtime.

If you have a page such as this one:

You can convert it to a v3 page by changing the syntax to:

New-UDTable (formerly UDGrid and UDTable)

Rather than having two cmdlets for tables (New-UDTable and New-UDGrid). The New-UDTable in v3 provides the ability to display data in a table, filter, page, and sort it. It supports both client and server-side processing.

New-UDDynamic

Unlike in v3, components do not have -Endpoint and -Content parameters. Each component will instead simply have a -Content parameter. To achieve dynamic sections of a page, you can instead use the New-UDDynamic cmdlet. This cmdlets let you define an entire section of a page as dynamic. It also provides auto refresh functionality so you can refresh sections of a page all at once.

New-UDGrid

New-UDGrid allows you to define a grid layout using the Material UI library. You use this single cmdlet to define rows and columns within your dashboard.

New-UDForm (formerly UDInput)

New-UDInput has been replaced by New-UDForm. The UDForm component allows far more configuration that UDInput did. You will use the standard controls like UDTextbox, UDCheckbox, and UDSelect instead of New-UDInputField. This means that there are a single set of input cmdlets to use for UD.

Navigation

Instead of using New-UDSideNav, you will now use a combination of New-UDAppbar and New-UDDrawer. When New-UDAppBar is used with the default position, it will overlay the AppBar at the top of the page. You can then specify a drawer to customize the navigation experience within your dashboard.

Nivo and Sparklines are now open source

The Nivo and sparklines controls are now open source and on the Universal Dashboard repository. You can now use them without purchasing a license.

Map is now open source

The map control is also open source and on GitHub.

Variables allow for the global definition of variables that are available within scripts. You can also import secrets that are also available within scripts or as run as credentials.

Creating a Variable

To create a variable, navigate to the Automation / Variables page. Click Add Variable to define a new variable.

Standard variables are just name \ value pairs of strings. They will be added to your scripts before they are run.

Creating a Secret Variable

Secret variables are stored within the selected vault. The value of those variables are never stored within Universal. To define a new secret variable, click Add Variable on the variables page and select the Secret tab.

From this dialog, you'll be able to define string and PSCredentials in the specified vault.

Importing Secret Variables

You can also import pre-existing secrets as variables into Universal. The variable values are not imported but will be looked up during execution. Click the Import Secret button to import secrets.

Related Cmdlets

New-UDDynamic allows you to define a dynamic region. Pages themselves are dynamic in nature. This means that every time a page is loaded, it runs the PowerShell for that page. Sometimes, you may want to reload a section of a page rather than the whole page itself. This is when you will want to use dynamic regions.

Basic Dynamic Region

This dynamic region reloads when the button is clicked.

New-UDDashboard -Title "Hello, World!" -Content {
    New-UDDynamic -Id 'date' -Content {
        New-UDTypography -Text "$(Get-Date)"
    }

    New-UDButton -Text 'Reload Date' -OnClick { Sync-UDElement -Id 'date' }
}

Auto Refresh

Dynamic regions enable the ability to auto refresh components after a certain amount of time. The entire region's script block will be run when autorefreshing.

    New-UDDynamic -Id 'date' -Content {
        New-UDTypography -Text "$(Get-Date)" -Variant h3
        New-UDTypography -Text "$(Get-Random)" -Variant h3
    } -AutoRefresh -AutoRefreshInterval 1

Loading Component

Sometimes refreshing a dynamic component may take some time. For example, if you are querying another service's REST API or a data. Dynamic regions support configuration of the component that shows when the region is reloading. By default, nothing is shown. This can be any Universal Dashboard component.

    New-UDDynamic -Content {
        Start-Sleep -Seconds 3
        New-UDTypography -Text "Done!"
    } -LoadingComponent {
        New-UDProgress -Circular
    }

API

New-UDDynamic

Defines a dynamic region on a page.

A Universal Dashboard website is composed of components. There are two frameworks that provide a set of core components that you can use within your pages. In addition to the core component, you can also extend Universal Dashboard with a large set of community created components.

External components are distributed as PowerShell modules and can be used in a dashboard by using Import-Module.

When building a dashboard, you can simply call the PowerShell cmdlets within your dashboard script to create a new component.

New-UDDashboard -Title 'Dashboard' -Content {
    New-UDTypography -Text 'Hello, world!'
}

Adding Components to Dashboards

Some components are not included automatically. You can add component modules by clicking the Components button on the Dashboard page and then adding the components. This list will also include components downloaded from the Marketplace.

Custom Variable Scopes

Universal Dashboard exposes two custom variable scopes using custom providers. These providers allow you to store your variables in scopes that make sense for a web application. The cache scope is used to store variables that can be used within any endpoint inside a dashboard. The session scope is used to store variables that can be used for a single user's session of the dashboard.

Cache Scope

Cache scope is used to store a variable that will be available in any endpoint. Cache scope is useful for storing data that make be shown in more than one control or may be time consuming to look up. This could be helpful for querying machine performance counters, Active Directory or Azure.

Just like any other scope, cache variables are defined with a prefix and a colon separator.

Once assigned, the $Cache:Computer variable is available within any endpoint.

Session Scope

Session scope is used to store a variable per session. A session is established when a user's browser first visit a dashboard. A cookie is stored in the user's browser that dictates that it is part of the session. Sessions have an idle timeout of 25 minutes.

Just like any other scope, cache variables are defined with a prefix and a colon separator.

Once assigned, the $Session:ShowChart variable is available in dashboard endpoints. Session variables are not available in REST API endpoints or scheduled endpoints.

Once a session is terminated, the session variables are cleared.

The New-UDElement cmdlet allows you to create custom React elements within your dashboard. Similar to New-UDHtml, you can define HTML elements using New-UDElement. Unlike, New-UDHtml, you can update elements, set auto refresh and take advantage of the React component system.

Create an Element

You need to specify the -Tag and -Content when creating an element. The below example creates a div tag.

You can nest components within each other to create HTML structures. For example, you could create an unordered list with the following example.

Setting Attributes

You can select attributes of an element (like HTML attributes) by using the -Attributes parameter. This parameter accepts a hashtable of attribute name and values. The below example creates red text.

Auto Refreshing Elements

You can define the -AutoRefresh, -RefreshInterval and -Endpoint parameters to create an element the refreshes on a certain interval. The below example creates an element that refreshes every second and displays the current time.

Setting Element Properties Dynamically

You can use the Set-UDElement cmdlet to set element properties and content dynamically. The following example sets the content of the element to the current time.

You can also set attributes by using the -Properties parameter of Set-UDElement. The following example sets the current time and changes the color to red.

Adding Child Elements

You can add child elements using Add-UDElement. The following example adds child list items to an unordered list.

Clearing Child Elements

You can clear the child elements of an element by using Clear-UDElement. The following example clears all the list items from an unordered list.

Forcing an Element to Reload

You can force an element to reload using Sync-UDElement. The following example causes the div to reload with the current date.

Removing an Element

You can remove an element by using Remove-UDElement.

API

Get-UDElement

Get component state.

Set-UDElement

Set component state.

Remove-UDElement

Remove a component.

Add-UDElement

Add a child component.

Clear-UDElement

Clear child components out of a component.

Sync-UDElement

Reload a component

Select-UDElement

Select a component.

Dashboard Frameworks define the PowerShell scripts and JavaScript components that are used to render the dashboard. Additional frameworks, when available, can be added through the Add Framework button from the Dashboard Frameworks page.

There are two dashboard frameworks built into PSU. Universal Dashboard v2 and Universal Dashboard v3. The intent of Universal Dashboard v2 is to enable users of PowerShell Universal Dashboard to easily run their existing dashboards within PowerShell Universal. Only bug fixes will be going into UDv2. Universal Dashboard v3 is built on a more modern framework and will be receiving feature updates going forward.

Both dashboards are open source so you can contribute to the dashboard in terms of bug fixes or features.

For an example of each framework, click on the appropriate link below.

Developing a Dashboard with VS Code

To add a new dashboard, visit the admin console and go to Dashboard Dashboards and click the Add Dashboard button.

After adding the dashboard, a dashboard PS1 file will be created and the dashboards.ps1 file will be updated. You can view your dashboard in VS Code underneath the dashboards tree view. It will show the current state of the dashboard and the framework it is using.

If you want to edit your dashboard, click the Open Dashboard File button. This will open the dashboard PS1 file in the editor and import the Universal module and Dashboard framework module so you have IntelliSense.

From here, you can begin editing your dashboard.

Your dashboard should restart automatically when you make changes. You will be able to view the dashboard in the browser by clicking the View button.

If you need to restart your dashboard manually, you can click the Restart button.

Developing a Dashboard with Single-File Configuration

You can use the Universal Dashboard PowerShell module and single-file configuration to build a dashboard directly from PowerShell.

Install the Universal Dashboard PowerShell Module. This will install both the Universal Dashboard framework module and the PowerShell Universal module.

Install the latest version of the Universal server.

Create a PS1 file for your configuration data and start the server.

Navigate to your dashboard.

Changes you make to your PS1 file will cause Universal to automatically reload your dashboard and reflect the changes.

Debugging a Dashboard

Logs

You can view the dashboard logs by right clicking on the Dashboard and clicking View Log. The log should provide information about start up issues or errors when executing sections of your dashboard.

Debugger

You can debug individual endpoints within your dashboard by using Wait-Debugger

For example, if I wanted to debug the button on my dashboard, I would add it to the OnClick event handler.

Now, I can right click on my dashboard and click Debug Dashboard Process.

This will issue an Enter-PSHostProcess command in the Integrated Terminal.

Next, you'll want to navigate to your page and click the button. Once the button is clicked, issue a Get-Runspace command in the Integrated Terminal. You'll notice that one of the runspaces is in InBreakpoint availability.

Finally, issue the Debug-Runspace command and VS Code will automatically open your endpoint in the debugger. You'll be able to step through your code, view variables and issue commands against the runspace.

Debug-PSUDashboard

Debug-PSUDashboard can be used instead of Wait-Debugger to more easily debug aspects of your dashboard. Debug-PSUDashboard requires the PowerShell Universal VS Code extension. When placed within a dashboard, this cmdlet will trigger a modal to be show with some information about connecting to the runspace that is currently running the code you are trying to debug.

You can enter the commands listed in any PowerShell host to connect to the runspace that is currently running in the dashboard.

If you have VS Code and the PowerShell Universal extension installed, you can use the Debug with VS Code button to automatically launch VS Code and connect to the runspace. You can see how that works by watching this video.