Product documentation
Workspace Environment Management
Current Release Service 2507 2503 2411 2407 2402 2311 2308 2305 2303 2212 2209 2206 2203
View PDF

Scripts for scripted tasks

March 16, 2026
Contributed by: 
C

Introduction

This page lets you manage scripts that you can automate or run on your WEM agents. Scripts are organized into the following categories:

  • Built-in scripts

    Ready-to-use scripts for common VDA administration and troubleshooting needs.

  • Custom scripts

    Administrator-created scripts for environment-specific automation and operational requirements.

Note:

To configure automated tasks from a script, go to Scripted tasks in a configuration set.

Add a custom script

The Scripted Tasks page lists all built-in scripts and any custom scripts created by you or other administrators. You can add additional custom scripts as needed to meet your requirements.

Before you begin

Before you create a custom script in WEM web console:

  • Create script content

    Write a PowerShell script based on your requirements.

  • Validate and export the script content

    Use the Citrix Environment Tool Hub > Scripted Task Validator tool to run the script and review the execution results. If needed, you can export the script for later import into the WEM Web console.

    For more information, see Validate and export a scripted task.

Workflow

To add a custom script, perform the following steps:

  1. On the Scripted Tasks page, click Add script.

  2. In the Add script wizard, configure the following settings and then click Save.

    • Script name. Specify a name for the script.

    • Tags. Select from existing tags or enter tags separated by commas. A tag must be no more than 20 characters long. Tags are like keywords or labels. Using tags enables you to identify your scripts in new ways. Also, they act as filters, letting you rearrange your view of scripts depending on criteria that are important to you. You can use as many tags as you like.

    • Description. Optionally, specify additional information to help you identify the script.

    • File type. Select a file type for the script. Two types of files are supported:

      • PowerShell. Individual PowerShell script files.
      • ZIP. Multiple files bundled into a single zip file. Zip files larger than 10 MB are not supported. After uploading a zip file, specify an entry point, indicating which file to run at the beginning of the script. Keep in mind that the entry point file must be no more than three levels deep in the folder structure.

    • Upload file. Click Browse, navigate to the file, select it, and then click Open. You are returned to the Add script wizard.

      Tip:

      You can upload a script in two ways:

      • Select a .zip file that you’ve already placed on the Web Console machine.
      • After exporting a script with the Scripted Task Validator tool, the content is automatically copied to your clipboard. On the Add Script page, paste the content directly from the clipboard (<Ctrl+V>). This method avoids the need to store a .zip file on the web console machine.

    • Grant permissions. Specify the level of access that you want to grant to the script. Ensure that you understand the permissions associated with each option.

      • Full access. A script assigned Full access has extensive local access. If selected, the script is granted permissions as if it runs under the local system account.
      • Limited access (with network access). A script assigned Limited access (with network access) does not have extensive local access but can access network resources. If selected, the script is granted permissions as if it runs under the network service account.
      • Limited access (without network access). A script assigned Limited access (without network access) does not have extensive local access and cannot access network resources. If selected, the script is granted permissions as if it runs under the local service account.
      • Run as logged-on user. If selected, the script runs in the context of a logged-on user’s session and is granted the same permissions, regardless of whether the user session is active or disconnected.

      For more information, see the Microsoft documentation https://docs.microsoft.com/en-us/windows/security/identity-protection/access-control/security-identifiers#well-known-sids.

    • Working folder. Optionally, type the absolute path of the local folder on the end-user operating system. The working folder is the current folder for the file when it starts. You can build the path with environment variables (for example, %ProgramFiles%). If unspecified, PSScriptRoot is used as the default working folder. For more information about PSScriptRoot, see the Microsoft documentation https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-7.1.

    • Does this task generate output files. Choose whether the script you add generates output files.

    • Output path. Type a path relative to the folder where the file resides. The path must contain the file name and the file name extension. Example: output\report.txt.

Manage scripts

You can manage scripts to meet your needs. Available actions include:

Edit a script

To edit a script, perform the following steps:

  1. On the Scripted Tasks page, locate the script. Use the search box or tags to find it quickly if needed.

  2. Click the ellipsis of the script and then select Edit script. The Edit script wizard appears.

  3. On the Task info tab, configure settings as needed.

  4. On the Script file tab, view the script content.

  5. Click Save.

Note:

You cannot edit built-in scripts.

Delete a script

To delete a script, perform the following steps:

  1. On the Scripted Tasks page, locate the script. Use the search box or tags to find it quickly if needed.

  2. Click the ellipsis of the script and then select Delete script.

Important:

You cannot delete built-in scripts.

Clone a script

To clone a script, perform the following steps:

  1. On the Scripted Tasks page, locate the script. Use the search box or tags to find it quickly if needed.

  2. Click the ellipsis of the script and then select Clone script.

Note:

When cloning a script, you are prompted to change the name to avoid duplicate names.

Configure tasks from a script

To configure and automate tasks from a script, perform the following steps:

  1. On the Scripted Tasks page, locate the script. Use the search box or tags to find it quickly if needed.

  2. Click the ellipsis of the script and then select Configure tasks.

  3. In the Select configuration set wizard, choose the configuration set where you want to create the task.

  4. Follow the steps in Create a scripted task to complete the configuration.

Built-in scripts

Currently, we provide the following built-in scripts for you to use:

Cloud Health Check

Lets you run checks that gauge the health of Virtual Delivery Agents (VDAs). VDA health checks identify possible causes for common VDA registration and session launch issues. Cloud Health Check runs under the local system account on the agent host.

Windows Service Management

Windows service management provides frequently used features regarding Windows service, such as start, stop, restart, configure one or more Windows services.

Restart Windows Service

This script checks the status of a Windows service. If the service is not currently running and the ForceStart parameter is specified, the script starts the service. Regardless of the current state, if the service is running and does not require forceful starting, it is restarted to ensure it’s operating on the latest configuration or to recover from a stalled state.

Parameters

name type default mandatory Note
ServiceNames string BrokerAgent False Specifies the names of the services to be managed. If not provided, defaults to BrokerAgent. If you need to input more than one service, separate the service names with a comma. All spaces would be trimmed. For example, ServiceA, ServiceB.
ForceStart boolean true False Indicates whether to start the service if it’s found to be not running. It does not affect running services. Running services are always restarted for maintenance or recovery purposes.

Stop Windows Service

This script stops a list of specified Windows services. The script checks if each service is installed and attempts to force-stop the service. The script then verifies whether the service has successfully stopped and reports the status.

Parameters

name type default mandatory Note
ServiceNames string BrokerAgent False Specifies the names of the services to be managed. If not provided, defaults to BrokerAgent. If you need to input more than one service, separate the service names with a comma. All spaces would be trimmed. For example, ServiceA, ServiceB.

Configure Windows Service

This script adjusts Windows service configurations, including startup type and recovery actions.

Parameters

name type default mandatory Note
ServiceNames string BrokerAgent False Specifies the names of the services to be managed. If not provided, defaults to BrokerAgent. If you need to input more than one service, separate the service names with a comma. All spaces would be trimmed. For example, ServiceA, ServiceB.
StartupType string null False Sets the startup type of the service. Valid options are Automatic, Manual, or Disabled.
FirstFailureAction string null False Defines the action for the first failure. For example, restart/none.
SecondFailureAction string null False Defines the action for the second consecutive failure.
SubsequentFailureAction string null False Defines the action for all subsequent failures after the second.

Server Reboot

Reboot Machine

This script restarts the local machine with an optional delay and force option.

Parameters

name type default mandatory Note
Force boolean true False If specified, force an immediate restart, ignoring any unsaved data or active user sessions.
Delay int 10 False Specifies the delay in seconds before the computer is restarted. Must be between 3 and 30 seconds. Defaults to 10 seconds.

CDF Tracing Management

Start CDF Tracing

This script starts the CDF tracing process using either a single CTL file or a predefined CTL file category as input. It traces the modules defined in the selected CTL files and automatically stops cdfcontrol.exe after the duration specified by the RunMinutes parameter.

Parameters

Name Type Default Mandatory Note
traceOutputPath string C:\ProgramData\Citrix\WEM\CDFLogs False Specifies the output path of CDF reports.
category











string











all











False











Specifies the predefined categories to start the trace with. Supported values are:
  • all
  • always on tracing
  • desktop Server os vda
  • delivery controller
  • federated authentication service
  • provisioning service
  • universal print server
  • citrix director
  • citrix studio
  • session recording administration
  • session recording player
  • citrix workspace app for windows
    		•
    ctlFilePath string null False Specifies the ctl file to start the trace with.
    RunMinutes Integer 30 False Specifies how long cdfcontrol.exe runs before it automatically stops and exits.

    Stop CDF Tracing

    This script stops the CDF tool tracing.

    CDF Logs Cleanup

    It is useful to clean up the CDF tracing logs to save storage consumption. It should provide a function to remove CDF files under the given directory.

    name type default mandatory Note
    FileAgeDays int 3 False Specifies the age threshold in days. Files and folders older than this value are deleted. The default value is 3 days and this parameter is optional. All the files or directories are deleted if the FileAgeDays is less than 1 day.

    AOT Log Collection

    This script is a comprehensive automation tool designed for collecting and processing Citrix AOT logs. It integrates with Citrix CDFControl to configure trace collection, apply filtering (default: Level=1, Class=Failure), and convert ETL (Event Trace Log) files into a readable CSV format for analysis.

    Name Type Default Mandatory Note
    StartTime [DateTime] EndTime - 30 minutes False Specifies the start time for log filtering
    EndTime [DateTime] Current date and time False Specifies the end time for log filtering

    Check DNS Settings

    This script is a comprehensive DNS health check tool designed for Citrix VDA environments. It validates DNS configuration and performs troubleshooting to identify potential DNS-related issues that might affect Citrix services.

    Name Type Default Mandatory Note
    DomainName [string] Not Applicable False Specifies the domain name to test DNS resolution (enables DNS Name Resolution test)
    FlushDNS [switch] False False Specifies whether to flush the DNS cache as a standalone action

    Check RDS License

    This script is a comprehensive Remote Desktop Services (RDS) license validation tool designed to check RDS licensing configuration and status on local computers. It is particularly useful in Citrix VDA environments, where RDS licensing compliance is essential for proper operation. Use this script to ensure licensing compliance and maintain uninterrupted multi-session user access.

    Name Type Default Mandatory Note
    DomainName [string] Not Applicable False Specifies the domain name to test DNS resolution (enables DNS Name Resolution test)
    FlushDNS [switch] False False Specifies whether to flush the DNS cache as a standalone action

    Diagnose VDA Unregistration

    This script is a comprehensive diagnostic tool designed to troubleshoot Citrix Virtual Delivery Agent (VDA) unregistration issues. It performs multiple health checks and diagnostic procedures to identify potential causes of VDA unregistration problems in Citrix environments.

    Name Type Default Mandatory Note
    StartTime [DateTime] EndTime - 30 minutes False Specifies the start time for log filtering
    EndTime [DateTime] Current date and time False Specifies the end time for log filtering

    Run Profile Management Health Check

    This script performs a comprehensive health check of your Citrix Profile Management deployment. It scans configurations for potential issues and analyzes logs to detect critical problems, such as temporary profile errors and significant time gaps during logons.

    Name Type Default Mandatory Note
    CtxSessionKey [string] null False Specifies the Citrix session key used to search for specific session logs. If not specified, the script analyzes sessions from the past 24 hours.
    LogonTime [string] null False Specifies the logon time to filter event log searches. Accepts various date and time formats. If not specified, the script filters event logs from the past 24 hours.
    StructuredOutputOnly [switch] True False Specifies whether to output structured JSON data without console logging.
    Parallel [switch] True False Specifies whether to use parallel processing for log analysis operations to improve performance.

    Set Profile Reset Trigger

    This script sets a trigger to reset a user’s profile. During the user’s next logon, the existing profile is backed up, and a new clean profile folder is created.

    Name Type Default Mandatory Note
    CtxSessionKey [string] null True Specifies the Citrix session key used to trigger a profile reset for the user’s next logon.
    FoldersToRestore [string] null False Specifies the folders to restore after a profile reset. If not specified, known folders such as Downloads, Desktop, and Pictures are restored by default.
    BackupNameSuffix [string] null False Specifies the suffix for the backup folder name during a profile reset. If not specified, the suffix defaults to upm_%CurrentTimeStamp%.

    More information

    For examples of how to use scripted tasks, see:

    Scripts for scripted tasks
    March 16, 2026
    Contributed by: 
    C
    March 16, 2026
    Contributed by: 
    C

    In this article

    Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
    © 1999- Cloud Software Group, Inc. All rights reserved.