Setting up the virtual app interop

Experimental

This feature is experimental. It might change substantially over time or it might not be supported in the future. Use at your own risk.

When a user runs a Finsemble smart desktop on their local machine, such as a work laptop, they can load and run multiple FDC3-enabled native apps that are located on and run from the same local machine. They can also run apps hosted on a remote server, such as a Citrix server. (See Citrix's product page or Wikipedia's article about Citrix Virtual Apps.) Citrix virtual apps run on the remote Citrix server, but are displayed within windows on the local desktop so that the app appears to the user to be running locally. This is akin to a remote desktop connection where the display screen is cropped to fit a single window as opposed to the full desktop view.

When virtual apps include API integration and are launched through Finsemble, they communicate with Finsemble through a Microsoft Terminal Services plug-in to participate in FDC3 Interop. A virtual app then behaves in a similar way to a local app: the user can link such an app to a channel, have it broadcast and receive context, and raise and listen for intents.

Before you begin

Before you begin configuring virtual apps to participate in FDC3 Interop within Finsemble, make sure that you:

• Run Microsoft Windows (only Windows virtual clients are supported at this point);
• Install Finsemble's Microsoft Terminal Services client plug-in (interopio.IWTSPlugin.dll). This plug-in has these requirements:
  • It must be located on the user's desktop;
  • It must be registered as a COM object within the MS Windows registry;
  • It must be listed as a Terminal Services Client Plug-in within the Windows registry.
• Configure citrix to allow the Interop.io IOPVC1 virtual channel
  • Citrix now enables virtual channel allow list policy by default. See the citrix documentation for more details
• Verify that the native app includes API integration and is configured as a virtual app. It also must meet these requirements:
  • The app must be deployed to a Citrix server and registered with an alias as a virtual app;
  • Create an entry in the public/configs/application/apps.config file for the app, which must specify type = "citrix" or hostManifests.Finsemble.window.windowType = "Citrix".
• Install Citrix Workspace on the user's desktop. The user must be given access to both the Citrix server and the virtual app.

note

Prior to version 8.10.x, Finsemble uses the CosaicRelayv2 virtual channel. We recommend upgrading to version 8.10.x or later.

Installing Finsemble's MSTS client plug-in

Finsemble's virtual app interop uses the same set of Microsoft Windows APIs that Citrix uses to connect to the remote server and display the app. You need no additional networking infrastructure to establish communication between Finsemble and the virtual app running on the server.

The Microsoft Terminal Services Client plug-in DLL enables communication between virtual apps and Finsemble. The plug-in DLL must be registered to be automatically loaded whenever Citrix makes a connection to the remote server. This involves a couple of steps. Here is the process to configure it:

1. Download and unzip the virtual app plug-in file.

note

The Citrix virtual app plug-in is not a standard part of Finsemble and you must obtain it separately. Contact your sales rep for details.

2. Copy the plug-in. Copy the files to each user's computer. The location can be anywhere you want as long as it is persistent. In other words, make sure it won't be removed by another system operation (such as when removing an application or processing an update). Also, don't place them in the same location as Finsemble unless you opt for a system level installation of Finsemble.

3. Register the plug-in. The archive contains the plug-in dll and some cmd files to assist with plug-in installation. Some of the files the archive contains are listed below:

Filename	Description
._registerUser.cmd	Registers the 32-bit version of client DLL in the user registry - doesn't require admin privileges.
._registerUserV.cmd	Same as _registerUser.cmd but verbose
._registerMachine.cmd	Registers the 32-bit version of client DLL in the machine registry - requires admin privileges.
._registerMachineV.cmd	Same as _registerMachine.cmd but verbose
.\vchan.ini	The configuration file for the client dll.
.\Win32*	A folder containing the 32-bit client DLL and PDB, and similar scripts to above.

Running the appropriate cmd file will register the interopio.IWTSPlugin.dll plug-in.

note

Pass in the --nopause flag to automatically exit after completion

note

Be sure to edit vchan.ini and add the INTEROPIO_CITRIX_NO_HANDSHAKE property set to True.

Developing Finsemble virtual apps

Any native app that includes the finsemble-dll .NET library can be launched as a virtual app. This is because when the component is configured as a virtual app, it connects to the plug-in we've configured in the previous section and sends all communication to it.

For each native app, a Citrix administrator needs to deploy it to the Citrix server, provide an alias for it, enable command line arguments, and grant users rights to launch it. Finsemble will launch the virtual app through Citrix's SelfService.exe (adding additional proprietary command line arguments that are picked up by finsemble.dll). You must configure the app within Citrix to accept dynamic arguments by setting the command line parameter to %*. See Driving the Citrix Receiver Self-Service Plug-in Programmatically (external) for details.

For more info about how to set this up, see Citrix documentation or contact your Citrix or partner representative for assistance.

Configuring virtual apps in Finsemble

After you configure the remote Citrix environment and you have the virtual app available in your Citrix Workspace app launcher, you can launch the app within Finsemble by adding an AppD entry for the remote app which contains these additional parameters:

• hostManifests.Finsemble.window.windowType: "Citrix"
• hostManifests.Finsemble.window.alias: the Citrix alias / name of the virtual app
• hostManifests.Finsemble.window.arguments: Any additional command line arguments, separated by & (e.g. param1=value1&param2=value2)

For example, an AppD record to launch a remotely-hosted app with name of "WPF App Alias" can look like this:

{
    ...
    "apps": [
        ...
        {
            "appId": "Remotely-hosted FDC3 WPF App",
            "name": "Remotely-hosted FDC3 WPF App",
            "type": "citrix",
            "details": {
                "alias": "WPF App Alias",
                "arguments": "param1=value1&param2=value2"
            },
            "hostManifests" : {
                "Finsemble": {
                    "window": {
                        "windowType": "Citrix"
                    },
                    "foreign": {
                        "components": {
                            "App Launcher": {
                               "launchableByUser": true
                            }
                        }
                    }
                }
            }
        }
    ]
}  

Pitfalls and troubleshooting

Where are my MSTS plug-ins logged?

If the virtual app loads successfully, you will find all the app logs within the Central Logger. If it doesn't, the interopio.IWTSPlugin.dll logs initialization and connection attempts to the user's TEMP directory by default, %TEMP%\interopio.IWTSPlugin.log.

I can't find the interopio.IWTSPlugin.log?

The interopio.IWTSPlugin.dll logs initialization and connection attempts are logged to the user's TEMP directory by default, %TEMP%\interopio.IWTSPlugin.log.

If the Citrix Workspace is running under a different user, the directory could be located in that other user's TEMP directory.

If it's in neither of these places, the interopio.IWTSPlugin.dll can be configured to store logs in a custom location. Check vchan.ini for the custom log location.

If no interopio.IWTSPlugin.log file exists in any of these locations, you many not have installed the plug-in correctly.

How can I verify I have installed the plug-in correctly?

The client side dll code gets executed on when a connection to Citrix is established, meaning that simply logging into a citrix box will create the log file. If there is no log, it's possible that the client side dll is not installed correctly. Ensure the steps outline above have been done correctly.

This should've added a registry key under Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Terminal Server Client\Default\AddIns\interopio.IWTSPlugin. Ensure this exists.

In the vchan.ini file set INTEROPIO_CITRIX_SHOW_MESSAGEBOX=true and attempt to connect to citrix box and spawn a virtual app from Finsemble. You should see a dialog like the one below:

Why doesn't my virtual app participate in data interop?

The most likely cause is that you didn't launch the app from Finsemble. If you launch a virtual app standalone from the Citrix Workspace app storefront, the virtual app won't communicate with Finsemble and it won't participate in data interop. Virtual apps must be configured within Finsemble as described in Configuring virtual apps in Finsemble and then launched directly from the app launcher if you want the app to participate in data interop with other Finsemble apps.

Why aren't my virtual apps opening or closing when I expect?

Finsemble can launch Citrix virtual apps and allow them to connect to the inter-application communication in order to participate in data interop, but such apps cannot be included in Finsemble's workspaces. This means that users must explicitly open and close virtual apps because these apps aren't affected by workspace switches.

Why don't my virtual apps snap, group, or auto-arrange?

Virtual apps are not included under window management. The size and position of virtual app windows is dictated by Citrix and the underlying server. As a result, virtual apps don't snap, group, or auto-arrange with other, locally-running, Finsemble apps.

Why is my app unresponsive when I lose connectivity?

The connectivity and responsiveness of your virtual app is the responsibility of Citrix, not of Finsemble. When you experience network connectivity issues, Citrix uses its own logic for handling virtual apps. By default, if you lose network connection with the Citrix server while using a virtual app, the app remains open in an unresponsive state on your desktop for up to 5 minutes. After this time has elapsed, if the connection can't be re-established Citrix closes all the unresponsive virtual apps. This is controlled via Citrix, so if you want to adjust this behavior, you must contact your own Citrix admin.

Can I use virtual apps on a Mac?

No. Virtual app interop is only supported in full Windows environments, meaning both the local Finsemble desktop and the Citrix server must be running Windows. If your local Finsemble desktop is running on a Mac, you won't be able to participate in data interop with virtual apps.

Can I use virtual app interop for Java or web-based apps?

No. Virtual app interop is supported only for .NET-based projects. Apps that implement Finsemble's interop API via the .NET-based Finsemble.DLL are supported by Virtual App Interop. Java or web-based apps that are hosted virtually can't participate in virtual data interop.

See also

Integrating native apps