Workspace Environment Management

Automatically back up configuration sets using WEM APIs and Windows PowerShell

As a Workspace Environment Management (WEM) administrator, you might need to back up your configuration sets on a regular basis to prevent settings from getting lost. You might want to trigger the backup, for example, every 12 hours, and manage the backup files locally and automatically. Using WEM public APIs and Windows PowerShell, you can accomplish that goal.

A general workflow is as follows:

  1. Apply for a Citrix Cloud API client
  2. Write a PowerShell script to back up your configuration sets
  3. Configure a scheduled task to run the script

Prerequisites

Before you start, make sure that you know your Citrix customer ID and the related API base URLs.

Sign in to Citrix Cloud, navigate to Identity and Access Management > API Access, and find your Citrix customer ID.

Citrix Customer ID

The API base URLs, including Citrix Auth API base URL and WEM API base URL, are related to the region of Citrix Cloud you’re connecting to. The region is determined when you onboard to Citrix Cloud. You can also query your region in Account Settings.

Region

You can find the API base URLs by checking the table below.

Region Citrix Auth API base URL WEM API base URL
United States (US) api-us.cloud.com api.wem.cloud.com
European Union (EU) api-eu.cloud.com eu-api.wem.cloud.com
Asia Pacific South (AP-S) api-ap-s.cloud.com aps-api.wem.cloud.com
Japan (JP) api.citrixcloud.jp jp-api.wem.citrixcloud.jp

For more information about the API base URLs, see Get Started With Citrix Cloud APIs and WEM API overview.

Apply for a Citrix Cloud API client

Navigate to Identity and Access Management > API Access. Type the name of your secure client, click Create Client, and save the secure client ID and client secret locally.

API secure client

Write a PowerShell script to back up your configuration sets

Use the following PowerShell script and save it as Invoke-WEMConfigSetBackupAPI.ps1. Be sure to replace the variables at the beginning of the script.


# replace the variables before running the script

$CitrixCustomerId = 'your-citrix-customer-id'
$CitrixAuthAPIBaseURL = 'api-us.cloud.com'
$CitrixWEMAPIBaseURL = 'api.wem.cloud.com'
$ClientId = 'your-api-client-id'
$ClientSecret = 'your-api-client-secret'

$ConfigSetsToBackUp = @('Default Site', 'MyConfigSet') # leave it empty if you want to back up all configuration sets
$FolderToSaveBackup = 'C:\ProgramData'

# get bearer token

$ErrorActionPreference = 'Stop'

$URL = "https://${CitrixAuthAPIBaseURL}/cctrustoauth2/${CitrixCustomerId}/tokens/clients"
$Body = "grant_type=client_credentials&client_id=${ClientId}&client_secret=${ClientSecret}"
$Response = Invoke-RestMethod -Method 'Post' -Uri $URL -Body $Body -ContentType 'application/x-www-form-urlencoded'

$BearerToken = $Response.access_token

if ([string]::IsNullOrEmpty($BearerToken))
{
    throw 'Cannot retrieve bearer token.'
}

Write-Host "Retrieved bearer token successfully."

# back up WEM configuration sets

if (-not (Test-Path -Path $FolderToSaveBackup -PathType 'Container'))
{
    throw 'The folder to save backup not exists.'
}

$Headers = @{
    'Citrix-CustomerId' = $CitrixCustomerId
    'Accept' = 'application/json'
    'Authorization' = "CWSAUTH bearer=${BearerToken}"
}

if ($ConfigSetsToBackUp.Count -eq 0 -or $ConfigSetsToBackUp -eq $null)
{
    $URL = "https://${CitrixWEMAPIBaseURL}/services/wem/sites"
    $Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
    $ConfigSetsToBackUp = $Response.items |% { $_.name }
}

$ConfigSetsToBackUp | ForEach-Object {
    Write-Host "Backing up configuration set ""$_"""
    $URL = "https://${CitrixWEMAPIBaseURL}/services/wem/sites/%24export?name=$_"
    Write-Host "GET $URL"
    $Response = Invoke-RestMethod -Method 'Get' -Uri $URL -Headers $Headers
    $Timestamp = Get-Date -Format "yyyyMMddHHmmss"
    $Response | ConvertTo-Json -Depth 10 | Out-File (Join-Path $FolderToSaveBackup "${_}-${Timestamp}.json")
}

<!--NeedCopy-->

For more information about bearer tokens, see Get Started With Citrix Cloud APIs.

For more information about using the WEM API to back up configuration set, see Exporting WEM configuration set API.

Note:

Each bearer token expires after an hour. To avoid frequently invoking the Citrix Cloud auth APIs and WEM APIs, cache the bearer token and reuse it if the backup duration takes less than an hour.

Configure a scheduled task to run the script

On a machine with access to Citrix Cloud, start Task Scheduler from the Windows Start menu or start taskschd.msc from the Windows command prompt.

You can create a folder named WEM scheduled task.

In the folder, create a task named launch Invoke-WEMConfigSetBackupAPI.ps1. Add a new trigger “repeat every 12 hours for a duration of 1 day” and add a new action of starting script Invoke-WEMConfigSetBackupAPI.ps1.

Task Scheduler

Automatically back up configuration sets using WEM APIs and Windows PowerShell