Microapps

Integrate Citrix Virtual Apps and Desktops service

Deploy the Citrix Virtual Apps and Desktops service (CVADs) integration to search for and perform self-service actions from your Citrix Workspace. Users can check the status of their associated machines. Perform operations such as restart, disconnect, and log off. Admins can also turn on maintenance mode for machines.

For more information about microapps, see Use Citrix Virtual Apps and Desktops service microapps. For more information about upgrading this Citrix Virtual Apps and Desktops service integration, see Upgrade your integration.

Review prerequisites

To set up this integration, you must have Citrix Workspace with Microapps and Citrix Virtual Apps and Desktops service enabled. This integration is not compatible with on-premises CVAD. However this integration template supports on-premises VDAs if you use Citrix Virtual Apps and Desktops service for brokering.

These are the values that you enter in Citrix Workspace Microapps:

  • Base URL: https://api.cloud.com/cvadapis/. For more information, see Citrix Virtual Apps and Desktops REST APIs
  • Customer ID: The customer ID used in the Rest APIs and is required to access all Rest APIs. Your customer ID is found in Citrix Cloud. To find your customer ID, see Generating the customer ID.
  • Token URL: https://api-us.cloud.com/cctrustoauth2/{customerID}/tokens/clients. See API Proxy.
  • Client ID: The clientID created on the Citrix Cloud Identity and Access Management website. This is required to obtain the bearer token needed for authentication for all Rest APIs. See Generate Client ID and Client Secret.
  • Client Secret: The secret key created on the Citrix Cloud Identity and Access Management website. This is required to obtain the bearer token needed for authentication for all Rest APIs.
  • Header prefix: This value is prefilled: CwsAuth bearer=

Permissions

When creating the Secure Client from Identity and Access Management, the account you are logged in with when generating the Secure Client must have the following Citrix Virtual Apps and Desktops service permissions:

  • Read-only Administrator, All - To pull data from Citrix Virtual Apps and Desktops service.
  • Session Administrator, All - To perform log off and restart actions.
  • Help Desk Administrator, All - To enable and disable maintenance mode.

The Secure Client credentials inherit the permissions of the logged in user. If the permissions of the user that was logged in when the Secure Client was created change, then those new permissions apply to the Integration, too.

API Proxy

Citrix provides API proxies in multiple regions. Choose a proxy closest to the region that your Citrix Cloud instance resides in:

  • Production (US) https://api-us.cloud.com/cctrustoauth2/{CUSTOMER_ID}/tokens/clients
  • Production (EU) https://api-eu.cloud.com/cctrustoauth2/{CUSTOMER_ID}/tokens/clients
  • Production (AP-S) https://api-ap-s.cloud.com/cctrustoauth2/{CUSTOMER_ID}/tokens/clients

Generate Client ID and Client Secret

Client ID and Client Secret (Secure Client) are required to obtain the bearer token needed for authentication for all Rest APIs. Create these on the Citrix Cloud Identity and Access Management page. For more information see Generating the customer ID, client ID, and secret key.

Add the integration

Add the Citrix Virtual Apps and Desktops service integration to Citrix Workspace Microapps. The authentication options are preselected. Ensure that these options are selected as you complete the process. This delivers out-of-the-box microapps with pre-configured notifications and actions which are ready to use within your Workspace.

Follow these steps:

  1. From the Microapp Integrations page, select Add New Integration, and Add a new integration from Citrix-provided templates.
  2. Choose the Citrix Virtual Apps and Desktops service tile.
  3. Enter an Integration name for the integration.
  4. Enter Connector parameters.
    • Enter the instance Base URL: https://api.cloud.com/cvadapis/
    • Select an Icon for the integration from the Icon Library, or leave this as the default icon.
  5. Enter your Customer ID. The customer ID used in the Rest APIs and is required to access all Rest APIs. Your customer ID is found in Citrix Cloud. To find your customer ID, see Generating the customer ID. CVADS config 1

  6. Under Service authentication, select OAuth 2.0 from the Authentication method menu and complete the authentication details. The authentication options are preselected. Ensure that these options are selected as you complete the process. Use the OAuth 2.0 security protocol to generate request/authorization tokens for delegated access. It is recommended that you always use OAuth 2.0 as your service authentication method where available. OAuth 2.0 ensures that your integration meets the maximum security compliance with your configured microapp.

    1. Select Client credentials from the Grant type flow menu.
    2. Enter client_credentials in the Grant type value field.
    3. Select Request body from the Token authorization menu.
    4. Select URL encoded form from the Token content type menu.
    5. Confirm the Token URL field. This value is prefilled: https://api-us.cloud.com/cctrustoauth2/{customerID}/tokens/clients
    6. Enter your Client ID. The client ID is the string representing client registration information unique to the authorization server.
    7. Enter your Client secret. The client secret is a unique string issued with the Client ID.
    8. Header prefix is prefilled: CwsAuth bearer=

    CVADS config 2

  7. In the Request rate limiting field, enter 120.
  8. (Optional) Enable Logging toggle to keep 24 hours of logging for support purposes.
  9. Select Save to proceed.

    CVADS config 3

You are now ready to set and run your first data synchronization. For complete information about synchronization rules, synchronization that does not meet its schedule and veto rules, see Synchronize data.

For more details of API endpoints and table entities, see Citrix Virtual Apps and Desktops service connector specifications.

Use CVADs microapps

The Citrix Virtual Apps and Desktops service integration comes with out-of-the-box microapps. Start with these microapps and customize them for your needs.

My Desktops: Search for your Citrix Virtual Desktops, and perform self-service actions from Citrix Workspace such as restarting.

Notification or Page Use-case workflows
Virtual Desktop Detail page Provides a page with desktop details, and options to Restart Desktop and Force Restart Desktop.
Virtual Desktops page Provides a searchable list of Citrix Virtual Desktops associated with the user, with a link to the Virtual Desktop Detail page.

My Sessions: Search for your Citrix Virtual sessions, and perform self-service actions from Citrix Workspace such as logging off and disconnecting.

Notification or Page Use-case workflows
List of Sessions page Provides a searchable list of Virtual Desktop sessions associated with the user, with a link to the Session Detail page.
Session Detail page Provides a page with Virtual Desktop session and machine details, and options to Log Off Session and Disconnect Session.

Virtual Desktops (Admin Mode): Enables from Citrix Workspace CVAD Administrators to lookup machines, view their details, put machines into maintenance mode, and restart the machines.

Notification or Page Use-case workflows
A Machine in a Fault State notification When there’s a new record of a machine reporting a faulty state, all subscribers receive a notification that links to the Virtual Desktop Detail page.
List of Virtual Desktops page Provides a searchable list of Citrix Virtual Desktops with a link to the Virtual Desktop Detail page. You can search by machine or user.
Virtual Desktop Detail page Provides a page with desktop details, and options to Restart Desktop, Force Restart Desktop, Enable Maintenance Mode, and Disable Maintenance Mode.

Upgrade your integration

If you are already using the Citrix Virtual Apps and Desktops integration, use this process to upgrade to the latest version. With this process you avoid having to resubscribe all your users.

Enhancements include:

  • Site ID is obtained automatically.
  • Not limited to faulty machines.
  • Incremental synchronization runs faster. Synchronization does not delete Deleted Sessions. Also, synchronization does not update Machines, rather only Sessions.
  • Added updates after actions that delete Sessions after logging off, updates Sessions after disconnecting, and sets restarting state for Machines.
  • Added option to update information for details on Machines and Sessions so that users can ensure that what’s seen is the same as in Citrix Virtual Apps and Desktops service.

Follow these steps:

  1. Download and add this script into the Scripting tab of your old Citrix Virtual Apps and Desktops service integration.
    1. From the integration configuration screen of the integration, select Scripting from the left-hand navigation.
    2. Download this script: Upgrade Citrix-Virtual-Apps-and-Desktops-service
    3. Select Upload script. Alternatively, you can input your script directly into the text area by selecting Edit.
    4. Drag your script onto the import pop-up. Select Import.
  2. Add the new Citrix Virtual Apps and Desktops service integration from the catalog of Citrix-provided templates, but do not configure the integration.
  3. After adding the integrations, export each microapp individually. For each microapp, select the menu next to the microapp and select Export. Perform this procedure for all three microapps.
  4. In the old integration (that is the integration you are currently using), import the files you just exported.
    1. Select the menu next to the microapp and select Import new version.
    2. Drag and drop or browse your computer to add the files, each for the corresponding microapp.
    3. Enable the Delete existing feed cards toggle to replace the original microapp.
    4. Select Import at the bottom of the screen.
  5. Delete all data endpoints except the scripted endpoints.
    1. Select Edit next to the integration.
    2. On the Data loading page select the menu next to an integration that is not scripted, select Delete, and confirm.
  6. Update the integration configuration. Specifically, the Base URL, Customer ID, and Header prefix according to the instructions in Add the integration. Remember to select Save to complete the procedure

You upgraded the Citrix Virtual Apps and Desktops integration.

Integrate Citrix Virtual Apps and Desktops service