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 that are faulty. Perform operations such as restart, disconnect, and log off. Admins can also turn on maintenance mode for faulty machines.

This template supports faulty machines only to prevent the integration from handling a potentially enormous volume of data with every synchronization. For more information about including all machines in the synchronization, see Modify endpoint to search for all machines.

For more information about microapps, see Use Citrix Virtual Apps and Desktops service microapps.

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://{customerID}.xendesktop.net/citrix/orchestration/api/techpreview/{customerID}/{siteID}/. See Determine Base URL.
  • Site ID: You need the tenant Site ID for the microapp to interact with Citrix Virtual Apps and Desktops service APIs. See Collect your Site ID.
  • 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.
  • 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.

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.

UPN configuration

Email addresses must be used for UPN (user principal name) for the identity provider associated with Workspace.

If UPNs in your identity provider are not the same as user email addresses, the Microapps will not be able to show people their Sessions or Desktops in Workspace.

For more information about identity providers, see Sign up for Citrix Cloud.

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.

Collect your Site ID

The Citrix Virtual Apps and Desktops service tenant Site ID allows the microapp to interact with Citrix Virtual Apps and Desktops service APIs. Use the PowerShell framework to collect the response, or use a REST API client to call this value. Both procedures are described below for you. Choose one.

Collect Site ID using PowerShell

You can find your Site ID using PowerShell. You need your CustomerID, Client ID, and Client Secret.

  1. Access the PowerShell script available here: https://github.com/philwiffen/get-cvads-siteid/blob/main/Get-CVADS-SiteID.ps1
  2. Download and edit the script, or paste its contents into a code editor.
  3. Enter your CustomerID, Client ID, and Client Secret between the quotation marks next to the PowerShell variables located near the top of the script. For example:

    • $customerID = "companycustomerid"
    • $clientID = "f539b28c-6f93-93c2-b526-49c48289f62e"
    • $clientSecret = "FDFLG3fgGKDKD=="
  4. Run the script in PowerShell.
  5. Copy and save the Site ID response for later use.

    Response example: c396f2fa-7824-41bc-9eed-db4d19ad1968

Collect Site ID using REST API client

Set up the REST API Request and collect Id value from the response.

  1. Open any REST API client. For example: https://insomnia.rest/download/core/.
  2. Call this endpoint replacing {customerID} with your customer ID:

    curl --request GET \
      --url
    https://{customerID}.xendesktop.net/citrix/orchestration/api/techpreview/me
    
  3. Choose OAuth2 as your authentication method.
  4. For Access Token URL, use https://api-us.cloud.com/cctrustoauth2/{customerID}/tokens/clients.
  5. Use the Client ID and Client Secret that you generated in the previous procedure.
  6. Change Credentials to In Request Body.
  7. Select Fetch Token.
  8. Select Send next to the request’s URL.
  9. The response lists your sites. If there is more than one, you must select the correct site for this integration. For example:

    {
      "UserId": "34234234234234234",
      "DisplayName": "name",
      "ExpiryTime": "11:58:20 AM",
      "RefreshExpirationTime": "10:58:20 PM",
      "VerifiedEmail": "user@citrix.com",
      "Customers": [
        {
          "Id": "customerID",
          "Name": null,
          "Sites": [
            {
              "Id": "siteID" (this is the value that you need to collect)
              "Name": "Site Name"
            }
          ]
        }
      ]
    }
    
  10. Collect and save the value Id.

Determine Base URL

The integration needs a base URL to be configured for your Citrix Virtual Apps and Desktops service API endpoints. This URL is unique to each tenant.

This is the format: https://{customerID}.xendesktop.net/citrix/orchestration/api/techpreview/{customerID}/{siteID}/

  • Replace {customerID} with your Customer ID for Citrix Cloud twice.
  • Replace {siteID} with your Site ID that you collected in the previous process.

Add the integration to Citrix Workspace Microapps

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://{customerID}.xendesktop.net/citrix/orchestration/api/techpreview/{customerID}/{siteID}/
    • Select an Icon for the integration from the Icon Library, or leave this as the default icon.

    CVADS config 1

  5. 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.

    CVADS config 2

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

    CVADS config 3

The Microapp Integrations page opens with your added integration and its microapps. 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.

Synchronize all machines

This integration template is designed to only support faulty machines. This prevents the integration from handling a potentially enormous volume of data with every synchronization.

You can make the following change to access all machines. However, synchronization performance will slow, and you must adjust the synchronization schedule accordingly.

To synchronize all machines:

  1. The Faulty Machine notification in the Admin Mode microapp must either be deleted or prevented from running automatically each synchronization.
  2. Modify the endpoint to search for all machines.

Faulty Machine notification in Admin Mode microapp change

Perform these steps to prevent subscribers to the Admin Mode microapp from receiving notifications for every machine synchronized each time a synchronization is performed.

  1. From the Microapp Integrations page, select the Citrix Virtual Apps and Desktops service integration.
  2. Select the Admin Mode microapp. Notifications view should already be visible, but if it is not, select Notifications.
  3. Either select the ellipsis option on the A Machine in a Fault State notification and select Delete to remove the notification entirely, or Edit the Notification.

    • If you deleted the notification, proceed to the next section: Modify endpoint to search for all machines.
    • If you edited the notification, disable the Automatically run this event after the integration data change toggle, then select Save.

Modify endpoint to search for all machines

Delete the SearchFilter in both the full and incremental synchronization of the Machines endpoint.

  1. From the Microapp Integrations page, select the menu next to the Citrix Virtual Apps and Desktops service integration, and then Edit. The Data Loading screen opens. If you are in the configuration screen, select Data Loading from the left side navigation column.
  2. Select the menu next to the Machines endpoint and then select Edit, or select the name of the endpoint itself: Machines.

    CVADS endpoints

  3. In the Edit Data Endpoint screen, under Full synchronization select the BODY tab and delete the SearchFilter leaving only {} in the BODY.
  4. Scroll down, and under Incremental synchronization select the BODY tab and again delete the SearchFilter leaving only {} in the BODY.

    Search filter

  5. Select Apply at the bottom of the screen and confirm to complete.

Remember to adjust the synchronization. See Synchronize data for more information.

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 faulty 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 faulty 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 faulty 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 with a Restart Desktop button that links to the Virtual Desktop Detail page.
List of Virtual Desktops page Provides a searchable list of faulty 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.
Integrate Citrix Virtual Apps and Desktops service