Fall back to StoreFront

Fall back to StoreFront is a resiliency feature that provides temporary access to Citrix Virtual Apps and Desktops through your StoreFront instance during a Workspace outage. You can use any valid URL to access Citrix Virtual Apps and Desktops, but Citrix recommends that you use one of the following to fall back to StoreFront:

  • A single internal URL or list of URLs that resolve to StoreFront servers inside your corporate network.
  • A single external URL or list of external URLs that resolve to Citrix Gateway with StoreFront deployed behind it.
  • A GSLB URL, which resolves to a GSLB layer of multiple Citrix Gateways with StoreFront behind them.

The Fall back to StoreFront feature is configured using PowerShell, which performs authenticated REST API calls to your Citrix Cloud customer. The PowerShell cmdlets are provided within a standalone PowerShell module, which can be downloaded and run from any computer with internet access.

Note:

The downloaded PowerShell module is a different SDK from the RemotePowerShell SDK that is used to configure the Citrix Virtual Apps and Desktops service.

Configure fall back to StoreFront

Fall back to StoreFront configuration with PowerShell involves the following tasks:

  1. Download the PowerShell module.
  2. Create and store a Citrix Cloud API client and secret.
  3. Identify the URLs of your GSLB, Gateway, or StoreFront instances.
  4. Import the PowerShell module and configure one or more StoreFront fall back URLs.
  5. Verify that your StoreFront fall back URL has been configured correctly.

Download the PowerShell module

Before you configure Fall back to StoreFront, download and unpack the Citrix-provided PowerShell module from GitHub. The file includes Citrix.Workspace.FallbackConfiguration.psm1 and Citrix.Workspace.FallbackConfiguration.psd1

Important:

The PowerShell script provided is designed for customers in the EU, US, and AP-S regions. Citrix Cloud customers in the Japan region must use a .json configuration file to target the REST API calls to Citrix Cloud for Japan. If your customer is in Citrix Cloud Commercial EU, US, and AP-S, you can ignore this step and remove references to the $env:CTXSWSPOSHSETTINGS variable from the script.

Citrix Cloud customers in the Japan region must also download the jp-production.json.

Required configuration details

To configure Fall back to StoreFront, you need the following:

  • The URLs of your GSLB, Gateway, or StoreFront instances.
  • A Citrix Cloud API client and secret.

If you don’t already have a Citrix Cloud API client and secret, you can create one by following this article: https://developer.cloud.com/explore-more-apis-and-sdk/cloud-services-platform/citrix-cloud-api-overview/docs/get-started-with-citrix-cloud-apis. Store these credentials safely and treat them as sensitive data.

Configure StoreFront fall back URLs

  1. Unzip the FallbackPowershellModule.zip file to a suitable directory from where you want to run the PowerShell, such as your current user’s desktop.
  2. Open the PowerShell ISE and select New* in the File menu.
  3. Copy the example script into the interactive PowerShell window so that you can modify and run it against your own Citrix Cloud customer.
  4. Set the $STFFallbackPath variable to the path of the directory that you unzipped the FallbackPowershellModule.zip file into.
  5. Configure the $YourCustomerAPIKey, $YourCustomerSecretKey, and $YourCustomerURL variables in your PowerShell script with the information that you prepared in the Required configuration details step.

    $YourCustomerAPIKey = " "
    $YourCustomerSecretKey = " "
    $YourCustomerURL = "https://<yourcustomer>.cloud.com"
    <!--NeedCopy-->
    
  6. Import the PowerShell module

    if(Test-Path -Path "$STFFallbackPath\Citrix.Workspace.FallbackConfiguration.psm1")
    {
        Write-Host "Importing STF Fallback Powershell Module..." -ForegroundColor "Green"
        Import-Module -Name "$STFFallbackPath\Citrix.Workspace.FallbackConfiguration.psm1" -verbose
    }
    else
    {
        Write-Host "STF Fallback Powershell Module not found inside $STFFallbackPath" -ForegroundColor "Red"
    }
    <!--NeedCopy-->
    
  7. Configure one or more StoreFront fall back URLs by updating the ServiceTitle and StoreWebAddress parameters. ServiceTitle is the meaningful name you want your subscribers to see such as “StoreFront EU”. StoreWebAddress is the full path to Receiver for Web or a Gateway URL. The following example includes three StoreFront fall back URLs:

    Set-WorkspaceFallbackConfiguration -WorkspaceUrl $YourCustomerURL `
                                    -ClientId $YourCustomerAPIKey `
                                    -ClientSecret $YourCustomerSecretKey `
                                    -Configuration @{ "ServiceTitle" = "StoreFront EU"; "StoreWebAddress" = "https://storefront-eu.example.com/Citrix/StoreWeb/"}, `
                                    @{ "ServiceTitle" = "StoreFront US"; "StoreWebAddress" = "https://storefront-us.domain.com/Citrix/StoreWeb/" }, `
                                    @{ "ServiceTitle" = "StoreFront APAC"; "StoreWebAddress" = "https://storefront-apac.domain.com/Citrix/StoreWeb/" }
    <!--NeedCopy-->
    
  8. To verify that your StoreFront fall back URL has been configured correctly, follow the instructions under View StoreFront fall back URLs.

View StoreFront fall back URLs

To see the StoreFront fall back URLs that you’ve configured, run the Get-WorkspaceFallbackConfiguration cmdlet.

Get-WorkspaceFallbackConfiguration -WorkspaceUrl $YourCustomerURL `
                                   -ClientId $YourCustomerAPIKey `
                                   -ClientSecret $YourCustomerAPIKey `
                                   -Verbose
<!--NeedCopy-->

Remove StoreFront fall back URLs

To remove the StoreFront fall back URLs that you’ve configured, run the Remove-WorkspaceFallbackConfiguration cmdlet. All URLs are removed when you use this cmdlet.

Remove-WorkspaceFallbackConfiguration -WorkspaceUrl $YourCustomerURL `
                                      -ClientId $YourCustomerAPIKey `
                                      -ClientSecret $YourCustomerSecretKey `
                                      -Verbose
<!--NeedCopy-->

Example script

The example script includes commands that you might need for adding, viewing, and removing the StoreFront fall back URLs. You don’t need to run all commands to perform any single function. For the script to run, always include lines 1–27. If your Citrix Cloud customer is in Japan, also uncomment and run lines 29–43. Afterward, you can include only the commands for the functions you want to perform.

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12;

# Your credentials from Citrix Cloud Identity and Access Management
[string]$YourCustomerAPIKey = " "
[string]$YourCustomerSecretKey = " "

# Commercial US, EU or AP-S
[string]$YourCustomerURL = "https://<yourcustomer>.cloud.com"

# OR
# JP region
# [string]$YourCustomerURL = "https://<yourcustomer>.citrixcloud.jp"

# Unpack the .ZIP file containing the PowerShell module to a folder
# Point Import-Module to the same path where the Citrix.Workspace.FallbackConfiguration.psm1 file is
$STFFallbackPath = "$Env:UserProfile\Desktop\Fallback"

if(Test-Path -Path "$STFFallbackPath\Citrix.Workspace.FallbackConfiguration.psm1")
{
    Write-Host "Importing STF Fallback Powershell Module..." -ForegroundColor "Green"
    Import-Module -Name "$STFFallbackPath\Citrix.Workspace.FallbackConfiguration.psm1" -verbose
}
else
{
    Write-Host "STF Fallback Powershell Module not found inside $STFFallbackPath" -ForegroundColor "Red"
}

<# Uncomment lines 29 - 43 if your Citrix Cloud customer is in Japan

# Uses jp-production.json file to configure the $env:CTXSWSPOSHSETTINGS variable
$EnvironmentConfigFile = "jp-production.json"
if(Test-Path -Path "$STFFallbackPath\$EnvironmentConfigFile")
{
    Write-Host "Setting STF Fallback Environment Variables using $EnvironmentConfigFile..." -ForegroundColor "Green"
    $env:CTXSWSPOSHSETTINGS = "$STFFallbackPath\$EnvironmentConfigFile"
}
else
{
    Write-Host "Path to $EnvironmentConfigFile config file not found." -ForegroundColor "Red"
}

#>

# Display detailed PowerShell help for the Fallback cmdlets
Get-Help Get-WorkspaceFallbackConfiguration -full
Get-Help Set-WorkspaceFallbackConfiguration -full
Get-Help Remove-WorkspaceFallbackConfiguration -full

# Perform Fallback admin tasks
# Get your existing configuration
Get-WorkspaceFallbackConfiguration -WorkspaceUrl $YourCustomerURL `
                                   -ClientId $YourCustomerAPIKey `
                                   -ClientSecret $YourCustomerAPIKey `
                                   -Verbose

# Add a new or overwrite/update the existing fallback config
Set-WorkspaceFallbackConfiguration -WorkspaceUrl $YourCustomerURL `
                                   -ClientId $YourCustomerAPIKey `
                                   -ClientSecret $YourCustomerSecretKey `
                                   -Configuration @{ "ServiceTitle" = "StoreFront EU"; "StoreWebAddress" = "https://storefront-eu.example.com/Citrix/StoreWeb/"}, `
                                   @{ "ServiceTitle" = "StoreFront US"; "StoreWebAddress" = "https://storefront-us.domain.com/Citrix/StoreWeb/" }, `
                                   @{ "ServiceTitle" = "StoreFront APAC"; "StoreWebAddress" = "https://storefront-apac.domain.com/Citrix/StoreWeb/" }

# Remove the existing Fallback configuration
Remove-WorkspaceFallbackConfiguration -WorkspaceUrl $YourCustomerURL `
                                      -ClientId $YourCustomerAPIKey `
                                      -ClientSecret $YourCustomerSecretKey `
                                      -Verbose
<!--NeedCopy-->

Additional help and support

For troubleshooting help or questions, contact your Citrix sales representative or Citrix Support.

Fall back to StoreFront