Nerdio Compass Citrix Export tool: overview and technical reference

Avatar
Nerdio Product Support

The Nerdio Compass Citrix Export tool allows you to export snapshots from your Citrix environment for import and analysis in Nerdio Compass. You can download the Export tool in Nerdio Compass from System > Support. 

Downloading the Export tool provides you with a single, unified PowerShell script that provides four distinct operational modes:

  • GUI mode - Interactive WPF interface for visual exports with real-time progress

  • Export mode - Headless export of Citrix configuration to JSON files

  • Anonymize mode - Replace personally identifiable information (PII) with synthetic values

  • Reverse mode - Restore original values from anonymized exports using a mapping file

System Requirements

  • PowerShell Version: 5.1 or later (both Windows PowerShell 5.1 and PowerShell 7+)

    Important

    Export mode supports PowerShell 5.1 only.

  • Citrix SDK Required: Citrix Remote PowerShell SDK (https://download.apps.cloud.com/CitrixPoshSdk.exe) for Export mode

  • Platforms Supported:

    • Windows PowerShell 5.1 Desktop edition (GUI mode)

    • PowerShell 7+ (anonymise, reverse modes)

  • Network: Connectivity to Citrix Cloud (for DaaS) or network access to CVAD delivery controllers

  • Permissions: Read access to Citrix configuration; write access to output directories

Operating Modes

1. GUI Mode (Interactive)

The default mode when running the script without parameters. Launches a WPF "Citrix Snapshot Export" window with:

  • SDK status checking and validation

  • Real-time progress logging with color-coded output

  • Light/dark theme support

  • Optional on-the-fly anonymization

  • Automatic ZIP packaging for Compass portal upload

Requirements:

  • PowerShell 5.1 Desktop edition

  • Citrix Remote PowerShell SDK installed

Example:
.\Invoke-CitrixCompassExport.ps1

For step-by-step instructions, see [TODO: link to "Use the Nerdio Compass Citrix Export tool to connect to your Citrix environment and export a snapshot"].

2. Export Mode (Headless)

Exports Citrix DaaS or CVAD configuration data to JSON files without user interaction.

Exported Resources:

  • Delivery groups

  • Access policies

  • Machine catalogs

  • MCS virtual machines

  • Machines (physical and provisioned)

  • Personal/private desktops

  • Applications

  • Hypervisor connections

  • Zones

  • Users

  • Images

  • GPO policies

  • System metadata (snapshot.json)

Requirements:

  • PowerShell 5.1 Desktop edition

  • Citrix Remote PowerShell SDK

  • Citrix Cloud credentials (for DaaS) or delivery controller access (for CVAD)

Example - Citrix Cloud:
.\Invoke-CitrixCompassExport.ps1 -Export -Path 'C:\Exports\Citrix' -CustomerId 'tfhkctx001'
Example - CVAD On-Premises:
.\Invoke-CitrixCompassExport.ps1 -Export -Cvad -Path 'C:\Exports\Citrix' -AdminAddress 'ddc.contoso.com'

3. Anonymize Mode

Replaces PII with synthetic values while maintaining referential integrity. Creates a GUID-keyed mapping file for reversal.

PII Categories Anonymized:

  • User Principal Names (UPNs) - replaced with generated user@domain.com addresses

  • Full names - replaced with random first/last name combinations

  • SAM names - replaced with sequential USER#### identifiers

  • Security Identifiers (SIDs) - replaced with synthetic S-1-5-21-... format

  • Machine names - replaced with sequential MACHINE#### identifiers

  • Active Directory groups - replaced with sequential GROUP#### identifiers

  • Azure OIDs - replaced with OID:/azuread/[guid] format

  • Tenant IDs - replaced with random GUIDs

  • Identity claims - parsed and anonymized by type

  • Email addresses (fallback) - replaced via regex matching on unmapped properties

Idempotency:

Re-running with the same mapping file produces identical results (no new mappings created).

Example:
.\Invoke-CitrixCompassExport.ps1 -Anonymise -Path 'C:\Exports\Citrix' -OutputPath 'C:\Exports\Citrix-Anon'

4. Reverse Mode

Restores original PII values in anonymized JSON files using the mapping file created during anonymization.

Example:
.\Invoke-CitrixCompassExport.ps1 -Reverse -Path 'C:\Exports\Citrix-Anon' -OutputPath 'C:\Exports\Citrix-Restored'

Parameters

Export Mode Parameters

-Export

Mandatory switch to run in headless export mode.

-Path (default: $PSScriptRoot\Export)

Directory where JSON export files are written. Directory is created if it does not exist.

-Path 'C:\Exports\Citrix'
-CustomerId

Citrix Cloud Customer ID (CCID) for DaaS authentication. Required for Citrix Cloud exports; not used with -Cvad.

-CustomerId 'tfhkctx001'
-Cvad

Switch to export from Citrix Virtual Apps and Desktops (on-premises) instead of Citrix Cloud. Omit for DaaS exports.

-Cvad
-AdminAddress (default: localhost)

Delivery controller address. Only required when not running directly on a CVAD delivery controller.

-AdminAddress 'ddc.contoso.com'
-ProgressCallback (optional)

ScriptBlock invoked with each progress message (used internally by the GUI). Signature: { param([string]$message) ... }

Anonymise Mode Parameters

-Anonymise

Mandatory switch to run in anonymization mode.

-Path

Directory containing JSON files to anonymize.

-OutputPath

Directory for anonymized output. If omitted, files are updated in place. Useful for preserving originals.

-OutputPath 'C:\Exports\Citrix-Anon'
-Domain (default: company.com)

Domain suffix for generated email/UPN replacements.

-Domain 'contoso.com'
-MappingFile (default: pii-anonymization-map.json in output directory)

Path to the GUID-keyed mapping JSON file. Loaded if present; created or updated after processing.

-MappingFile 'C:\Maps\anonymization-map-2026-09-02.json'
-Filter (default: *.json)

File name filter passed to Get-ChildItem for JSON file discovery.

-Recurse (default: $true)

When $true, searches subdirectories recursively for JSON files.

-Recurse $false

Reverse Mode Parameters

-Reverse

Mandatory switch to run in reversal mode.

-Path

Directory containing anonymized JSON files to reverse.

-OutputPath

Directory for restored output. Required (reversal never updates files in place).

-MappingFile (default: pii-anonymization-map.json in -Path)

Path to the mapping file created by anonymization. Must exist.

-Filter (default: *.json)

File name filter for JSON discovery.

-Recurse (default: $true)

When $true, searches subdirectories recursively.

Usage Examples

Example 1. GUI Export (Interactive)

.\Invoke-CitrixCompassExport.ps1

Launches the interactive WPF window for guided export configuration and real-time progress monitoring.


Example 2. Headless DaaS Export

.\Invoke-CitrixCompassExport.ps1 -Export -Path 'C:\Exports\MyCustomer' -CustomerId 'tfhkctx001'

Exports Citrix Cloud (DaaS) configuration for customer ID tfhkctx001 to C:\Exports\MyCustomer.


Example 3. CVAD On-Premises Export

.\Invoke-CitrixCompassExport.ps1 -Export -Cvad -Path 'C:\Exports\CVAD-Lab' -AdminAddress 'ddc.lab.contoso.com'

Exports on-premises CVAD configuration from the specified delivery controller.


Example 4. Anonymize with Custom Domain

.\Invoke-CitrixCompassExport.ps1 -Anonymise -Path 'C:\Exports\Citrix' -OutputPath 'C:\Exports\Citrix-Anon' -Domain 'customer.local'

Anonymizes export files, writing output to a separate directory with custom domain for generated email addresses.


Example 5. Preview Anonymization (WhatIf)

.\Invoke-CitrixCompassExport.ps1 -Anonymise -Path 'C:\Exports\Citrix' -OutputPath 'C:\Exports\Citrix-Anon' -WhatIf

Previews what anonymization would write without modifying any files. Useful for validation before processing large datasets.


Example 6. Reverse Anonymization

.\Invoke-CitrixCompassExport.ps1 -Reverse -Path 'C:\Exports\Citrix-Anon' -OutputPath 'C:\Exports\Citrix-Restored'

Restores original values using the mapping file found in C:\Exports\Citrix-Anon.


Example 7. Load Functions for Programmatic Use

.\Invoke-CitrixCompassExport.ps1 -FunctionsOnly

Defines all functions without launching GUI or export. Used internally for background runspace operations.


Output Files

Export Mode Output

JSON files created in the export directory:

File

Content

BrokerApplication.json

Published applications

BrokerCatalog.json

Machine catalogs

BrokerDesktopGroup.json

Delivery groups (desktop groups)

BrokerDesktopGroupAccessPolicy.json

Access policy rules

BrokerDesktopUsage.json

Desktop usage statistics

BrokerGpoPolicy.json

Group Policy Object policies

BrokerHypervisorConnection.json

Hypervisor connections

BrokerMachine.json

Machines (all types)

BrokerPrivateDesktop.json

Private desktops

BrokerUser.json

Citrix users

ConfigZone.json

Zones

Images.json

Image definitions and versions

PersonalDesktops.json

Personal desktops

ProvisionedVirtualMachines.json

MCS-provisioned virtual machines

snapshot.json

Metadata (source system, timestamp, version, anonymization state)

Anonymization Output

Anonymized JSON Files

Same structure as export files, with PII replaced by synthetic values.

pii-anonymization-map.json

GUID-keyed mapping file containing:

  • original - Original PII value

  • anonymized - Generated replacement

  • type - Category (upn, fullname, samname, sid, machinename, etc.)

Example mapping entry:

{
  "550e8400-e29b-41d4-a716-446655440000": {
    "original": "john.smith@contoso.com",
    "anonymized": "kwxz.pqmr@company.com",
    "type": "upn"
  }
}

Snapshot Metadata

snapshot.json contains:

{
  "schemaVersion": "1.0",
  "source": "daas" | "cvad",
  "collectedAtUtc": "2026-09-02T14:30:45.123Z",
  "scriptVersion": "2.3.0",
  "anonymised": false | true
}

The anonymised flag is set to true only when the entire anonymization pass completes successfully with no skipped files.

Advanced Usage

MaxRecordCount for Large Environments

The Citrix Remote PowerShell SDK defaults to returning 250 records per query. For environments with many machines, applications, catalogs, users, or GPO policies, the script automatically requests all records using -MaxRecordCount [Int32]::MaxValue to prevent silent truncation.

If exports are incomplete:

  1. Verify the Site database command timeout on Delivery Controllers is sufficient for large queries

  2. Monitor database performance during export

  3. Split very large environments into regional exports if necessary

Idempotent Anonymization

Running anonymization multiple times with the same mapping file produces identical output:

# First run - creates mapping
.\Invoke-CitrixCompassExport.ps1 -Anonymise -Path 'C:\Export1' -OutputPath 'C:\AnonOutput' -MappingFile 'C:\Maps\map.json'

# Second run - loads existing mapping, no new entries created
.\Invoke-CitrixCompassExport.ps1 -Anonymise -Path 'C:\Export2' -OutputPath 'C:\AnonOutput' -MappingFile 'C:\Maps\map.json'

Useful for batch processing multiple exports with consistent anonymization rules.

Partial Anonymization Status

The snapshot.json file flags anonymised: false if the anonymization pass is incomplete:

  • JSON files could not be parsed

  • User confirmed -WhatIf without writing changes

  • Non-default -Filter used

  • -Recurse disabled (nested files not processed)

This prevents partial anonymization from being misrepresented as complete.

ZIP Packaging (GUI Mode)

In GUI mode, the script can automatically ZIP exported JSON files for Compass portal upload, excluding the mapping file (which must remain for reversal capability).

Troubleshooting

Export Mode

Error: "Failed to load Citrix PowerShell snap-ins"

  • Ensure Citrix Remote PowerShell SDK is installed

  • Verify running on Windows PowerShell 5.1 Desktop edition (not ISE, not Core)

  • Check SDK version compatibility with Citrix Cloud or CVAD release

Error: "Authentication failed to Citrix Cloud"

  • Verify CustomerId is correct

  • Check network connectivity to Citrix Cloud

  • Ensure credentials in the security credential store are valid

  • Confirm the account has Citrix Cloud administrative rights

Error: "Delivery controller unreachable"

  • Verify AdminAddress is correct and resolvable

  • Check firewall rules (default Citrix port 80/443)

  • Confirm account has CVAD administrative access

Incomplete export (< expected record count)

  • Increase Site database command timeout on Delivery Controllers

  • Check Citrix logs for query timeouts

  • Try exporting specific components individually for diagnostics

  • Verify network latency to delivery controllers

Anonymization Mode

Error: "Could not parse as JSON"

  • Verify files in -Path are valid JSON

  • Check for invalid UTF-8 encoding

  • Ensure files are not locked by another process

Error: "Mapping file not found"

  • Confirm -MappingFile path exists and contains valid JSON

  • If first run, omit -MappingFile to auto-create in output directory

  • Verify the file is readable by the current user

Warning: "snapshot.json keeps 'anonymised: false'"

  • Some JSON files failed to parse or were skipped

  • Revisit -Filter and -Recurse settings

  • Check for permission issues on nested files

  • Review verbose output (-Verbose) for specific skipped files

Reversal Mode

Error: "Mapping file not found"

  • Confirm the mapping file created during anonymization still exists

  • Check file path matches exactly

  • Verify file is readable

Restored values don't match originals

  • Confirm mapping file has not been modified since anonymization

  • Ensure reverse -Path contains the exact anonymized files processed during anonymization

  • Check for manual edits to anonymized JSON (breaks reversal)

Performance Notes

  • Large Environments: Export time depends on environment size, network latency, and Delivery Controller database performance

  • Anonymization: Scales linearly with total JSON file size; processing speed ~50-100 MB/minute

  • Reversal: Typically faster than anonymization (direct lookup vs. collision checking)

  • Memory: Script loads entire JSON objects into memory; for very large exports (>1 GB), consider splitting into regions

Security Considerations

  • Mapping File Protection: The mapping file is the sole reversal key. Protect it as confidential material

  • In-Place Anonymization: When omitting -OutputPath, original files are overwritten; commit to version control first if reversal may be needed

  • Secure Transfer: When sharing anonymized exports, use encrypted channels (SFTP, HTTPS)

  • Metadata Leakage: snapshot.json contains non-sensitive provenance (version, timestamp); no PII is included

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Related articles

Comments (0 comments)

Article is closed for comments.