This serves as an introduction to Application Management, outlining its purpose, advantages and important features.

The Application Management module is the source for all installation packages and it integrates deeply into the Image Management and Configuration Management module.

It supports PowerShell App Deployment Toolkit (PSADT) packages at the time of this documentation. While we deliver some base applications, you have the freedom to create your own PSADT installation packages and upload them to your account for further usage.

For this purpose, we’re also delivering a free PSADT Package Wizard that helps to create standardized installation packages.

: Watch our YouTube video for a visual walkthrough

Key features

• Manage your application installers
• Download application, group and role installation scripts and use them with any ESD product
• Use it as fully extensible with parameterized packages and functions

Use cases

• Manage your PSADT packages, create groups and roles and assign them to Image Management or Configuration Management hosts or groups
• Outsource your packaging with the benefit of using defined packaging standards
• Create application configurations without the need to write a single line of code

Top benefits

• Create application installations with our free no-code PSADT Package Wizard
• Use created applications in any of the available ESD products in the market

Additional resources

PowerShell App Deployment Toolkit
Set-StrictMode

The post About Application Management appeared first on XOAP.

Application Management

To use Application Management you need to have network access to api.xoap.io over port 443 and custom packages must be provided as a ZIP archive prior to upload.

Within your XOAP workspace, you can already find a wide selection of:

• Applications
• Application Groups
• Application Roles

This means you’re ready to begin installing applications immediately.

Creating packages

XOAP’s Application Management supports PSADT packages in both v3 and v4 formats. Our current Package Wizard supports package creation in v3 format. If you plan to create your own application packages, we recommend installing it on your packaging machine. The easiest way to do this is directly from your XOAP Workspace.

1. Navigate to Application Management → Application Roles
2. Locate the Role: PSADT Packaging Baseline
3. Open the three-dot menu next to the role and choose Copy installation command
4. On the machine where you want to install the wizard, open PowerShell as Administrator. Paste and execute the copied command.

Alternatively, you can download the installation script or copy the installation command, copy it manually to the target system, and then run it through PowerShell as Administrator.

Once completed, the Package Wizard will be fully installed and configured. You can find the shortcut on your desktop.

The post Prerequisites appeared first on XOAP.

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
    }
}

The post Applications appeared first on XOAP.

Quick guide

Application Groups allow you to orchestrate the installation of applications and define installation parameters.

Create a new Application Group

1. In the upper-right corner, click + Create Group.
2. Enter the Group name and select/add Tags.
3. Toggle Continue on error or Reboot (after installation) if needed.
4. Click + Assign applications to add packages to the list.
5. Click Create to finish.

Edit an Application Group

1. Click the Action menu (⋮) and select Details.
2. Update the parameters or modify the list of assigned applications.
3. Click Save to apply any changes.

 Delete an Application Group

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

Additional useful information

Action menu:

From the Action menu, you can duplicate an Application Group. This is useful for creating similar groups for different scenarios. You can also create an Application Role. This is useful when combining Application Management with Configuration Management.

Download:

Applications are downloaded to the system during the installation process and reside there in C:\Windows\Temp as a cached package.

Technical documentation

Application Groups allow you to orchestrate the installation of applications and define installation parameters. Available installation parameters are read from the application’s PSADT Parameter block.

You can specify these parameters during application assignment to the group or by editing already assigned applications.

When assigning an application to the group, use the slide-out application list and click the eye icon to view details.

This opens the installation parameters for the selected application, where you can modify the installation settings.

When editing a group, use the Assigned Applications table and click the eye icon to update installation parameters for applications already assigned.

Two additional settings can be configured at the group level: Continue on error and Force Restart.

• Continue on error: By default, the installation process stops if any application fails. Enabling Continue on error overrides this behavior.
• Force Restart: The client is restarted after all applications have been installed.

Important: When combining Application Management with Configuration Management, the applied Configuration Management policy must allow restarts for Force Restart to work.

You can also change the installation order of applications within a group by rearranging them in the Assigned Applications table.

Install an Application Group on a single machine

Get Installation Command or Script

1. Open PowerShell as Administrator and run the command or script on the machine.
2. Click the Action menu (⋮).
3. Select Copy installation command for a CLI command or Download installation script for a standalone file.

The post Groups appeared first on XOAP.

Quick guide

Roles are used to combine multiple application groups. This allows you to reuse the same groups with the same application settings across different roles.

Add a new Application Role

1. In the upper-right corner, click + Create Role.
2. Enter the Role name and select/add Tags.
3. Toggle Continue on error or Reboot (after installation) if needed.
4. Click + Assign groups to add Application Groups to the list.
5. Click Create to finish.

Edit an Application Role

1. Click the Action menu (⋮) and select Details.
2. Update the parameters or modify the list of assigned groups.
3. Click Save to apply any changes.

Delete an Application Role

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

Additional useful information

Action menu:

From the Action menu, you can duplicate an Application Role. This is useful for creating similar groups for different scenarios.

Download:

Applications are downloaded to the system during the installation process and reside there in C:\Windows\Temp as a cached package.

Technical documentation

Roles are used to combine multiple application groups. This allows you to reuse the same groups with the same application settings across different roles.

Two additional settings can be configured at the role level: Continue on error and Force Restart.

• Continue on error: By default, the installation process stops if any application fails. Enabling Continue on error overrides this behavior.
• Force Restart: The client is restarted after all installations have completed.

Important: When combining Application Management with Configuration Management, the applied Configuration Management policy must allow restarts for Force Restart to work.

You can also change the installation order within a role by rearranging the assigned Application Groups in the role’s assignment table.

Install an Application Role on a single machine

Get Installation Command or Script

• Click the Action menu (⋮).
• Select Copy installation command for a CLI command or Download installation script for a standalone file.
• Open PowerShell as Administrator and run the command or script on the machine.

An Application Role is the highest-level construct for deploying applications. It is also required if you want to combine Application Management with Configuration Management for full client management.

The post Roles appeared first on XOAP.

If you are using Strict Mode for PowerShell in your environment, you need to test the application packages thoroughly before you can use them in production.

We made some basic tests with PSADT packages and Strict Mode and it seems to work fine. Read more about it here.

Parameters and secrets

Parameters and secrets you assign to your applications are stored encrypted in our backend and injected into the packages during runtime.

The post Security appeared first on XOAP.

This area describes common mistakes that can be made during application package creation.

Use single quotes instead of double quotes

Wrong:

[Parameter(Mandatory)]
[ValidateSer("Splunk","Elasticsearch")]
[string]$Backend,

Correct:

[Parameter(Mandatory)]
[ValidateSer('Splunk','Elasticsearch')]
[string]$Backend,

Space between validation options

Wrong:

[Parameter(Mandatory)]
[ValidateSer('TCP', 'HTTP', 'Console')]
[string]$Protocol,

Correct:

[Parameter(Mandatory)]
[ValidateSer('TCP','HTTP','Console')]
[string]$Protocol,

Set comma after the last parameter

Wrong:

Param (
    [Parameter(Mandatory=$false)]
    [ValidateSet('Install','Uninstall')]
    [string]$DeploymentType = 'Install',
    [Parameter(Mandatory=$false)]
    [ValidateSet('Interactive','Silent','NonInteractive')]
    [string]$DeployMode = 'Interactive',
    [Parameter(Mandatory=$false)]
    [switch]$AllowRebootPassThru = $false,
    [Parameter(Mandatory=$false)]
    [switch]$TerminalServerMode = $false,
    [Parameter(Mandatory=$false)]
    [switch]$DisableLogging = $false,
)

Correct:

Param (
    [Parameter(Mandatory=$false)]
    [ValidateSet('Install','Uninstall')]
    [string]$DeploymentType = 'Install',
    [Parameter(Mandatory=$false)]
    [ValidateSet('Interactive','Silent','NonInteractive')]
    [string]$DeployMode = 'Interactive',
    [Parameter(Mandatory=$false)]
    [switch]$AllowRebootPassThru = $false,
    [Parameter(Mandatory=$false)]
    [switch]$TerminalServerMode = $false,
    [Parameter(Mandatory=$false)]
    [switch]$DisableLogging = $false
)

The post Best practices appeared first on XOAP.