Applications

Quick Guide #

XOAP’s Application Management module supports PSADT packages in both v3 and v4 formats. The only prerequisite for uploading custom packages is that they must be provided as a ZIP archive prior to upload.

Upload a new Application #

1. In the upper-right corner, click Upload Applications.
2. Click to upload your application or drag and drop (supported format .zip).
3. Toggle on or leave off Allow overwrite if already exists.
4. Click Edit details to select/add tags.
5. Optional: After upload, click + Create group or Add to group and then clickSave.
6. Click Skip and finish (if no group selected).

Edit an Application #

1. Click the Action menu (⋮) and select Details.
2. View specific package parameters (as shown in the details view) or update Tags.
3. Click Save to apply any changes.

Delete an Application #

1. Click the Action menu (⋮) and select Delete.
2. Confirm the deletion by clicking on Delete.

Additional useful information #

Download: #

You can download applications by opening the action menu and selecting Download.

Upload: #

You can upload packages to XOAP if they use the standard PSADT toolkit configuration. To upload an application package to XOAP, the PSAppDeployToolkit (PSADT) package must be provided as a ZIP archive with the toolkit files located at the root of the ZIP (no additional top-level folder).

Installation: #

The main dashboard provides an overview of the installation status and access to the log files. To install applications, you must use an Application Group or Application Roles.

PSADT packages: #

You can use the XOAP Package Wizard to create your own PSADT v3 packages.

Technical documentation #

XOAP’s Application Management module supports PSADT packages in both v3 and v4 formats. The only prerequisite for uploading custom packages is that they are provided as a ZIP archive prior to upload.

Importing applications into XOAP is a straightforward process. Packages are uploaded through the Application Management area. Navigate to Applications, click Upload Application in the upper-right corner, and follow the steps.

If they do not already existing inside the PSADT deployment script , the following variables and functions are added to each package during the upload process automatically:

1. Variables in Deploy-Application.ps1 (PSADT v3)
   • [string]$appTargetOS
   • [string]$packageType
   • [string]$packageName
2. Variables in Invoke-AppDeployToolkit.ps1 (PSADT v4) in $adtSession
   • PackageType
   • TargetOS
   • PackageName
3. Functions added to both PSADT v3 and PSADT v4
   • Register-Installation in the post-install area
   • Unregister-Installation in the post-uninstallation area

The application name in XOAP is constructed from the package variables values, regardless of how the ZIP file is named. The naming logic is:

packageType_appVendor_appName_appVersion_appTargetOS_appArch_appLang

Example:

APP_MicrosoftCorporation_Orca_101261007175_Any_Any_EN

The additional register functions are used to report installation status back to XOAP from the client (this is achieved through adding the variables to the registry of each system, where the application is installed).

The implementation differs between PSADT v3 and PSADT v4 packages, even if the functions have the same names.

For PSADT v3, the functions are added to AppDeployToolkitExtensions.ps1:

Function Register-Installation
{
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'IsInstalled' -Value 1 -Type DWord
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptName' -Value "$appName" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptVendor' -Value "$appVendor" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptVersion' -Value "$appVersion" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptArch' -Value "$appArch" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptLanguage' -Value "$appLang" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptRevision' -Value "$appRevision" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptVersion' -Value "$appScriptVersion" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptDate' -Value "$appScriptDate" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'ScriptAuthor' -Value "$appScriptAuthor" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'PSADTVersion' -Value "$appDeployMainScriptVersion" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'InstallationDateTime' -Value "$currentDateTime" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'InstallationTimeZone' -Value "$currentTimeZoneBias" -Type String
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'InstallationSource' -Value "$scriptParentPath" -Type String
    $logFile = "{0}{1}" -f $logDirectory, $logName
    Set-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName" -Name 'LogFile' -Value "$logFile" -Type String
}

Function Unregister-Installation
{
    Remove-RegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName"
}

For PSADTv4 functions are added to PSAppDeployToolkitExtensions.psm1:

function Register-Installation
{
    
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $false)]
        [System.String]$PackageName
    )

    begin
    {
        # Initialize function.
        Initialize-ADTFunction -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
    }

    process
    {
        try
        {
            try
            {
                # Get the current ADT session
                $adtSession = Get-ADTSession
                
                # Use provided PackageName or derive from session
                if (-not $PackageName)
                {
                    $PackageName = if ($adtSession.PackageName) { $adtSession.PackageName } else { "$($adtSession.AppVendor)_$($adtSession.AppName)_$($adtSession.AppVersion)" }
                }

                # Get current date/time information
                $currentDateTime = Get-Date -Format 'yyyy-MM-dd HH:mm:ss'
                $currentTimeZoneBias = (Get-TimeZone).BaseUtcOffset.ToString()
                
                # Registry base key
                $baseKey = "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName"
                
                # Register installation metadata
                Set-ADTRegistryKey -Key $baseKey -Name 'IsInstalled' -Value 1 -Type DWord
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptName' -Value $adtSession.AppName -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptVendor' -Value $adtSession.AppVendor -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptVersion' -Value $adtSession.AppVersion -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptArch' -Value $adtSession.AppArch -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptLanguage' -Value $adtSession.AppLang -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptRevision' -Value $adtSession.AppRevision -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptScriptVersion' -Value $adtSession.AppScriptVersion -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptDate' -Value $adtSession.AppScriptDate -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'ScriptAuthor' -Value $adtSession.AppScriptAuthor -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'PSADTVersion' -Value $adtSession.DeployAppScriptVersion -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'InstallationDateTime' -Value $currentDateTime -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'InstallationTimeZone' -Value $currentTimeZoneBias -Type String
                Set-ADTRegistryKey -Key $baseKey -Name 'InstallationSource' -Value $PSScriptRoot -Type String
                
                # Register log file path if available
                if ($adtSession.LogPath)
                {
                    Set-ADTRegistryKey -Key $baseKey -Name 'LogFile' -Value $adtSession.LogPath -Type String
                }
                
                Write-ADTLogEntry -Message "Successfully registered installation for package [$PackageName]" -Severity 1
            }
            catch
            {
                # Re-writing the ErrorRecord with Write-Error ensures the correct PositionMessage is used.
                Write-Error -ErrorRecord $_
            }
        }
        catch
        {
            # Process the caught error, log it and throw depending on the specified ErrorAction.
            Invoke-ADTFunctionErrorHandler -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState -ErrorRecord $_
        }
    }

    end
    {
        # Finalize function.
        Complete-ADTFunction -Cmdlet $PSCmdlet
    }
}

function Unregister-Installation
{
    [CmdletBinding()]
    param
    (
        [Parameter(Mandatory = $false)]
        [System.String]$PackageName
    )

    begin
    {
        # Initialize function.
        Initialize-ADTFunction -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState
    }

    process
    {
        try
        {
            try
            {
                # Get the current ADT session
                $adtSession = Get-ADTSession
                
                # Use provided PackageName or derive from session
                if (-not $PackageName)
                {
                    $PackageName = if ($adtSession.PackageName) { $adtSession.PackageName } else { "$($adtSession.AppVendor)_$($adtSession.AppName)_$($adtSession.AppVersion)" }
                }

                # Remove the registry key entirely
                Remove-ADTRegistryKey -Key "HKEY_LOCAL_MACHINE\SOFTWARE\PSADT\InstalledApps\$PackageName"
                
                Write-ADTLogEntry -Message "Successfully unregistered installation for package [$PackageName]" -Severity 1
            }
            catch
            {
                # Re-writing the ErrorRecord with Write-Error ensures the correct PositionMessage is used.
                Write-Error -ErrorRecord $_
            }
        }
        catch
        {
            # Process the caught error, log it and throw depending on the specified ErrorAction.
            Invoke-ADTFunctionErrorHandler -Cmdlet $PSCmdlet -SessionState $ExecutionContext.SessionState -ErrorRecord $_
        }
    }

    end
    {
        # Finalize function.
        Complete-ADTFunction -Cmdlet $PSCmdlet
    }
}