Scripted Tasks
Introduction
Tip:
Scripted tasks work at a machine level. To run tasks at a user session level, use External tasks instead.
This page lets you add scripted tasks that you customize to suit your unique environment management needs. You can then automate those tasks with Workspace Environment Management (WEM) by configuring them in the applicable configuration set.
Currently, we provide the following built-in scripted task 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 name of the service(s) 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 name of the service(s) 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 | null | true | Specifies the name of the service(s) 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, SerivceB. |
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 takes either a CTL file or a predefined category of CTL files as input to start the CDF tool process and start tracing the models in CTL files.
Parameters
| name | type | default | mandatory | Note |
|---|---|---|---|---|
traceOutputPath |
string | C:\ProgramData\Citrix\WEM\CDFLogs |
False | Specifies the output path of CDF reports. |
category
|
string
|
10
|
False
|
Specifies the predefined categories to start the trace with. Supported values are
allalways on tracingdesktop Server os vdadelivery controllerfederated authentication serviceprovisioning serviceuniversal print servercitrix directorcitrix studiosession recording administrationsession recording playercitrix workspace app for windows |
ctlFilePath |
string | null | False | Specifies the ctl file to start the trace with. |
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 directors are deleted if the FileAgeDays is less than 1 day. |
Tip:
- You can differentiate between custom and built-in scripted tasks: Custom tasks are marked with the “CUSTOM” label and built-in ones with the “CITRIX” label.
- Built-in scripted tasks always appear above custom ones. Custom scripted tasks are sorted in descending order based on the last modified time.
With this feature, you can extend the capabilities of WEM for your unique management needs. For example, the built-in scripted task Cloud Health Check lets you gauge the health of the VDAs. The task is script based. You can write your own script file. Then, you add the script file to WEM as a scripted task so you can automate the task using WEM.
Each time a scripted task runs, a corresponding report is generated for it. The report includes information about when the task runs, the task execution results, and more, thus giving you the ability to audit activities related to the task.
Scripted tasks work at a configuration set level. A general workflow to use scripted tasks is as follows:
-
On the Scripted Tasks page, add a scripted task.
-
Navigate to the configuration set for which you want to enable the scripted task.
-
On the Scripted Task Settings page of that configuration set, enable the scripted task. See Scripted Task Settings.
-
Optionally, view reports related to the scripted task. There are two ways to do that:
- Go to Monitoring > Reports and view reports there.
- Go to Scripted Tasks or the Scripted Task Settings page of a configuration set. Locate the scripted task, select the ellipsis, and then select View reports. You are then taken to the Monitoring > Reports page, with relevant filters applied automatically. You can then see related reports.
For information about scripted task reports, see Reports.
Add a scripted task
To add a scripted task, perform the following steps:
-
On the Scripted Task page, click Add scripted task.
-
In the Add scripted task wizard, configure the following settings and then click Save.
-
Task name. Specify a name for the task.
-
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 tasks in new ways. Also, they act as filters, letting you rearrange your view of tasks in Scripted Tasks 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 task.
-
File type. Select a file type for the task. 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 scripted task. 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 scripted task wizard.
-
Grant permissions. Specify the level of access that you want to grant to the scripted task. Ensure that you understand the permissions associated with each option.
- Full access. A scripted task assigned Full access has extensive local access. If selected, the scripted task is granted permissions as if it runs under the local system account.
- Limited access (with network access). A scripted task assigned Limited access (with network access) does not have extensive local access but can access network resources. If selected, the scripted task is granted permissions as if it runs under the network service account.
- Limited access (without network access). A scripted task assigned Limited access (without network access) does not have extensive local access and cannot access network resources. If selected, the scripted task is granted permissions as if it runs under the local service account.
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,
PSScriptRootis used as the default working folder. For more information aboutPSScriptRoot, 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 task 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.
Edit a scripted task
To edit a scripted task, perform the following steps:
-
On the Scripted Tasks page, locate the task. If needed, use the search box to quickly search for the task.
-
Click the ellipsis of the task and then select Edit task. The Edit scripted task wizard appears.
-
On the Task info tab, configure settings as needed.
-
On the Script content tab, view the script content.
-
Click Save.
Note:
You cannot edit built-in scripted tasks.
Delete a scripted task
To delete a scripted task, perform the following steps:
-
On the Scripted Tasks page, locate the task. If needed, use the search box to quickly search for the task.
-
Click the ellipsis of the task and then select Delete task.
Important:
- You cannot delete built-in scripted tasks.
- To delete a scripted task that is currently enabled for some configuration sets, first disable it in those configuration sets.
Clone a scripted task
To clone a scripted task, perform the following steps:
-
On the Scripted Tasks page, locate the task. If needed, use the search box or tags to quickly find the task.
-
Click the ellipsis of the task and then select Clone task.
Note:
When cloning a task, you are prompted to change the name to avoid duplicate names.
Configure task settings option
To reach the task setting quickly, perform the following steps:
-
On the Scripted Tasks page, locate the task. If needed, use the search box or tags to quickly find the task.
-
Click the ellipsis of the task and then select Configure task settings.
-
Choose a configuration set in the Select configuration set wizard.
-
Click Go to reach the filtered task in the Scripted Task Settings page, where only the chosen task is filtered out.
More information
For examples of how to use scripted tasks, see: