Skip to content

Desktop Policies and Script Execution via Policy Engine

The Desktop Policy feature is introduced in HyWorks Controller v3.4-SP2, enabling administrators to create and manage desktop policies. These policies enable the configuration of user and computer settings for remote desktop connections.

HyWorks v3.6+ has changes in the desktop policy feature for better functional coverage, better architecture. Below is the direct comparison between the old and new Desktop Policy features:

Desktop Policy v1.0 - HyWorks v3.4-SP2 Desktop Policy v2.0 - HyWorks v3.6
Policy evaluation and distribution by HyWorks Controller on the connect call. Policy evaluation and distribution by Policy Engine directly to the desktop agents.
Support for desktop policies .pol created using PolicyPlus App Support for desktop policies .pol created using PolicyPlus App and Script distribution and execution on session events, e.g., post-connect event or post-logout events.
Supported with shared hosted desktops only. Supported with single-session virtual desktops and shared hosted desktops.

Prerequisites and Version Compatibility

  • HyWorks Controller: v3.6 or later.

  • Platform Support: Windows only (Feature is not supported with Linux platforms currently).

    • Supported Single-session OS Versions: Windows 10, 11.

    • Supported Multi-session OS Versions: Windows Server 2025, 2022, 2019, 2016.

  • Supported DVM Tools/Session Host Versions:

    • DVM Tools v3.6.0.1336 or later.

    • Session Host v3.6.0.157 or later.

  • Policy Engine: v20250819T1700 or later.

  • Software Prerequisites:

    • Dot Net 4.5 or above for policy plus application

    • PolicyPlus application: This open-source utility is required to export the necessary group policy. To download it, visit the PolicyPlus page on GitHub and scroll down to find the link to the latest downloadable version.

Additional Network Port Requirements

From To Port Number Purpose
HyWorks Controller Nodes Policy Engine 38901 Accessing Policy Management API endpoint.
Desktop Virtual Machines Policy Engine 38901 Accessing Policy Management API endpoint.
Policy Engine Node RabbitMQ Servers 5671 (SSL)
5672 (Non-SSL)		 For HyWorks Controller HA notifications.
Policy Engine Node HyWorks Controller Servers 38866 Communication with HyWorks Controller.
Policy Engine Node SQL Servers 1433 (Default) Reading Policy and associated data.

Single API endpoint utilized by the HyWorks Management Console, DVM agents, and others to interact with the OPAL Policy Engine. By default, this API is externally exposed on port 38901 using SSL, configured through nginx.

Desktop Policy Configuration Workflow

  1. Create a Desktop Policy Entity with required configurations, i.e., desktop policy in .pol format and/ or Session Event Scripts.

  2. Create a Resource Policy with a desktop policy created in step# 1 and an entitlement filter for users/user groups/OUs/desktop pool(s)/server team(s).

  3. When the user logs in to VDI, the HyWorks controller sends a JWT token to the desktop agent.

  4. The desktop agent will invoke Policy Engine API using the JWT token received from the HyWorks controller to fetch the Desktop Policy rule applicable for the logged-in user.

  5. After receiving the Desktop Policy rule, the DVM agent will optionally download desktop policy or script files from the Policy Engine API and subsequently apply the same to VDI.

Steps to Configure Desktop Policies

For end-user environment configuration or customization using event scripts or desktop policies following steps can be followed:

  1. Installation and Configuration of Policy Engine.

  2. Creating a PolicyPlus.Pol file or create a PowerShell/ batch script** to be executed post-session events.

  3. Creating a Policy Entity (Desktop Policy).

  4. Creating a Desktop Policy Assignment Rule.

Installation and Configuration of Policy Engine

  1. The Policy Engine installation process is defined in detail in the installation section. Please refer Policy Engine Installation guide for a step-by-step process to install Policy Engine.

  2. HyWorks Controller configuration to use Policy Engine: Once Policy Engine is correctly installed and configured, the next step is to configure Policy Engine URI in HyWorks Controller:

    1. Log in to the HyWorks Controller Management Console with user credentials having super-administrator privileges.

    2. Navigate to Settings > General > Advance Settings > Apply Tag Filter Policy Manager.

      1. Locate the flag Is Policy Engine Configured, and set it to True.

      2. Search for the flag Policy Manager Endpoint and set the value with the policy engine address in the format: https://OPALServerIP:38901, e.g., https://192.168.1.1:38901. 38901 is the default port for the Policy Engine manager.

    3. Save the value and update the Advance Settings.

    4. HyWorks Controller configuration is completed, and HyWorks Controller will start pushing policy engine URI to the desktop agents with tokens.

PolicyPlus: Generating a .pol File

This configuration is to be done on the PolicyPlus application.

  1. Open the PolicyPlus application.

  2. Navigate to File > Open Policy Resources. Select a location, assign a name to the file with a ".pol" extension, and click OK.

  3. All modified policies will be saved in the ".pol" file created in the previous step.

  4. Modify the required group policies.

  5. After setting all the required policies for the respective changes, navigate to Files and select Save Policies.

  6. The same files will be used when applying for the Desktop Policy feature.

Creating a Desktop Policy Entity

  1. Log in to the HyWorks Controller Management Console with user credentials having privileges to create a desktop policy entity.

  2. Navigate to Policies > Entities > Desktop Policy.

  3. Click on Add to start creating a new desktop policy entity.

    1. Primary Details:

      1. Name: Max 100 characters and Description: Max 300 characters for the entity.

    2. Desktop Policies:

      1. Upload the Computer or User policy in .pol format created using the PolicyPlus app.

    3. Session Event Scripts: Upload appropriate scripts with arguments, with timeouts (if any) and Execution flags as Run async or no.

      1. Scripts are executed only after the session events, e.g., post-connect event or disconnect event.

      2. Script Types: Batch and PowerShell scripts are supported.

      3. Supported Event Types: Connect, Disconnect, Reconnect, Logout, Lock, Unlock.

      4. Script execution context: User context or system context. E.g., opening any prompt or performing activities for the user as a logged-in user can be executed in the user context.

      5. Timeouts: Provide a timeout value for script execution. If script execution does not finish in the given time, then the desktop agent will abort the script execution.

      6. More than one script: The Run async setting determines how the scripts will be executed, with more than one script configured for one event.

        1. With Run async enabled, scripts will be running in async mode without waiting for other scripts.

        2. With Run async disabled, scripts will be executed in the same sequence, they are configured.

    4. The administrator must configure at least one type of entity, either a desktop policy or a session event script, to proceed.

    5. Click on Create Rule to save the entity.

    6. Added entity will be listed with showing Name, Description, added policies (user/ computer) status and added session event scripts status.

    7. The next step is to associate this entity with appropriate resources using a resource policy.

Creating a Desktop Policy Assignment Rule

Now that the desktop policy with appropriate configurations is available, the next step is to have correct associations for getting it applied.

Resource Policy Specifications:

Attribute or Configuration Explanation Possible Options Remarks
Name Name of the resource policy. 100 chars -
Description Logical description of the resource policy. 300 chars -
Rule Type Type of entity being associated with objects. User Experience Management
Desktop Policy		 -
Active To enable or disable this policy entity association. Policy entity will not get applied. - -
Order Decides the priority order in which the assigned policy entities will be applied when multiple policies are found for the object. 1 to 5 1 being the top priority. If there are multiple policies with the same order, the policy will be executed in alphabetical order.
Filters Filters to determine when the policy will be applied. Filters can be configured for the following objects:
- Users
- User Groups
- Organization Unit
- Desktop Pool
- Server
- Server Teams.		 It is possible to combine multiple conditions using AND, OR, and custom expressions. For custom expressions, nesting is supported up to 2 levels. E.g., ((1 AND 2) OR (3 OR 4)) is allowed, but (1 AND (2 OR (3 AND 4))) is not.
Rule Selection The entity selection for the configured type. All the entities of the selected type will be listed here. Selecting the entity will display its details.

To create a new policy rule:

  1. Log in to the HyWorks Controller Management Console using user credentials that have privileges to create a desktop policy entity.

  2. Navigate to Policies > Policies > Resource Policy.

  3. Click on Add.

  4. Provide appropriate configurations for

    1. Primary Details: Name, Description, Rule Type, Active or not, Order

    2. Filters

    3. Rule: The entities of the selected type will be listed.

  5. Select an appropriate entity, and the wizard will display the details of the selected policy entity on the same screen.

  6. Click on Create Policy to finish the resource policy creation. A new resource policy will be created and will be displayed in the list.

  7. On the next connection, policies will be applied according to the selection criteria/filters.