Workspace Environment Management

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.

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:

  1. On the Scripted Tasks page, add a scripted task.

  2. Navigate to the configuration set for which you want to enable the scripted task.

  3. On the Scripted Task Settings page of that configuration set, enable the scripted task. See Scripted Task Settings.

  4. 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:

  1. On the Scripted Task page, click Add scripted task.

  2. 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, 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 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:

  1. On the Scripted Tasks page, locate the task. If needed, use the search box to quickly search for the task.

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

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

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

  5. Click Save.

Note:

You cannot edit built-in scripted tasks.

Delete a scripted task

To delete a scripted task, perform the following steps:

  1. On the Scripted Tasks page, locate the task. If needed, use the search box to quickly search for the task.

  2. 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:

  1. On the Scripted Tasks page, locate the task. If needed, use the search box or tags to quickly find the task.

  2. 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:

  1. On the Scripted Tasks page, locate the task. If needed, use the search box or tags to quickly find the task.

  2. Click the ellipsis of the task and then select Configure task settings.

  3. Choose a configuration set in the Select configuration set wizard.

  4. 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:

Scripted Tasks