External Tasks
Controls the execution of external tasks. External tasks include running scripts and applications as long as the agent host has the corresponding programs to run them. Commonly used scripts include: .vbs and .cmd scripts.
With the external tasks feature, you can specify when to run an external task. Doing so lets you more effectively manage user environments.
Tip:
You can use dynamic tokens to extend Workspace Environment Management actions to make them more powerful.
External task list
A list of your existing external tasks. You can use Find to filter the list.
To add an external task
- Use the context menu Add command.
- Enter details in the New External Task dialog tabs and then click OK.
Fields and controls
Name. Lets you specify the display name of the external task, which appears in the external task list.
Description. Lets you specify additional information about the external task.
Path. Lets you specify the path to the external task. The path resolves in the user environment. Make sure that:
- The path you specified here is consistent with the agent host.
- The agent host has the corresponding program to run the task.
Arguments. Lets you specify launch parameters or arguments. You can type a string. The string contains arguments to pass to the target script or application. For examples to use the Path and Arguments fields, see External task examples.
External Task State. Controls whether the external task is enabled or disabled. When disabled, the agent does not process the task even if the task is assigned to users.
Run Hidden. If selected, the task runs in the background and is not displayed to users.
Run Once. If selected, WEM runs the task only once regardless of which options you select on the Triggers tab and regardless of whether agents restart. By default, this option is selected.
Execution Order. Lets you specify the running order of each task. The option can be useful when you have multiple tasks assigned to users and some of those tasks rely on others to run successfully. By default, the value is 0. Tasks with an execution order value of 0 (zero) run first, then those with a value of 1, then those with a value of 2, and so on.
Wait for Task Completion. Lets you specify how long the agent waits for the task to complete. By default, the Wait Timeout value is 30 seconds.
Action Type. Describes what type of action the external task is.
User session triggers. This feature lets you configure the following session activities as triggers for external tasks:
-
Refresh. Controls whether to run the external task when users refresh the agent. By default, the option is selected.
-
Reconnect. Controls whether to run the external task when a user reconnects to a machine on which the agent is running. By default, the option is selected. If the WEM agent is installed on a physical Windows device, this option is not applicable.
-
Logon. Controls whether to run the external task when users log on. By default, the option is selected.
-
Logoff. Controls whether to run the external task when users log off. This option does not work unless Citrix User Logon Service is running. By default, the option is not selected.
-
Disconnect. Controls whether to run the external task when a user disconnects from a machine where the agent is running. By default, the option is not selected.
-
Lock. Controls whether to run the external task when a user locks a machine where the agent is running. By default, the option is not selected.
-
Unlock. Controls whether to run the external task when a user unlocks a machine where the agent is running. By default, the option is not selected.
When using disconnect, lock, and unlock options, consider the following constraints:
-
The implementation of these options is based on Windows events. In some environments, these options might not work as expected. For example, in desktops running on Windows 10 or Windows 11 single-session VDAs, the disconnect option does not work. Instead, use the lock option. (In this scenario, the action we receive is “lock.”)
-
We recommend that you use these options with the UI agent. Two reasons:
- When you use the options with the CMD agent, the agent starts in the user environment each time the corresponding event occurs, to check whether the external task runs.
- The CMD agent might not work optimally in concurrent task scenarios.
User process triggers. This feature lets you configure user processes as triggers for external tasks. Using this feature, you can define external tasks to supply resources only when certain processes are running and to revoke those resources when the processes end. Using processes as triggers for external tasks lets you manage your user environments more precisely compared with processing external tasks on logon or logoff.
-
Before you use this feature, verify that the following prerequisites are met:
- The WEM agent launches and runs in UI mode.
- The specified processes run in the same user session as the logged-on user.
- To keep the configured external tasks up to date, be sure to select Enable Automatic Refresh on the Advanced Settings > Configuration > Advanced Options tab.
-
Run when processes start. Controls whether to run the external task when specified processes start.
-
Run when processes end. Controls whether to run the external task when specified processes end.
Troubleshooting
After you enable the feature, the WEM agent creates a log file named Citrix WEM Agent Logoff.log the first time a user logs off. The log file is located in a user’s profile root folder. The WEM agent writes information to the log file every time the user logs off. The information helps you monitor and troubleshoot issues related to external tasks.
External task examples
For a script (for example, PowerShell script):
- If neither the folder path nor the script name contains blank spaces:
- In the Path field, type the following:
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe. - In the Arguments field, type the following:
C:\<folder path>\<script name>.ps1.
Alternatively, you can type the path to the script file directly in the Path field. For example:
C:\<folder path>\<script name>.ps1. In the Arguments field, specify arguments if needed. However, whether the script file is run or opens with a different program depends on file type associations configured in the user environment. For information about file type associations, see File Associations. - In the Path field, type the following:
- If the folder path or the script name contains blank spaces:
- In the Path field, type the following:
C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe. - In the Arguments field, type the following:
-file C:\<folder path>\<script name>.ps1.
- In the Path field, type the following:
For an application (for example, iexplore.exe):
- In the Path field, type the following:
C:\Program Files\"Internet Explorer"\iexplore.exe. - In the Arguments field, type the URL of the website to open:
https://docs.citrix.com/.