Assimilation

Assimilation is the process of bringing native applications into the Finsemble workspace. Assimilation allows a user to launch, move, dock, group, and save non-Finsemble windows within Finsemble. This includes applications installed on a local machine or apps bundled with your Finsemble installer. This is useful because it allows you to integrate critical legacy applications into the workflows supported by Finsemble. Through Assimilation, native applications can coexist alongside HTML5 apps in the context of a single overarching application.

To turn on Assimilation, look in configs/application/config.json for betaFeatures.assimilation and set "enabled" to true:

"betaFeatures": { 
    ...
    "assimilation": {
        "enabled": true,
        "blacklist": [],
        "whitelist": [],
        "onlySpawned": true
    }
}

Note: Only applications spawned by Finsemble will have their window state (size and location) saved by the Workspace Client.

Bundling applications with Finsemble

To bundle an application with Finsemble, you'll need to add an item to the "appAssets": array in the manifest located at: configs/openfin/manifest-local.json. For example:

{
    "src":"http://localhost:3375/hosted/example.zip",
    "alias": "AssimilationExample",
    "version": "1.0",
    "target": "example.exe",
    "args":""
}

Your application should be packed into a Zip file, whose location is set at the src element and may be hosted at any appropriate URL or bundled with Finsemble by placing them in the /hosted directory in the root of the project, which will ensure that they are served from http://localhost:3375/hosted/.

Give your application an appropriate "alias", which will be used to reference it from your components.json file later. You also need to identify the binary to execute (relative to the root of your Zip file) as the "target" and may pass in an arguments string ("args") as you would write it on the command prompt (e.g., "--mode=a b c"). You may add multiple copies of the config to "appAssets", with different "alias" and "args" settings, to create multiple components (with different launch arguments) from the same src.

To allow these applications to be spawnable, you'll also need to add them to your components.json. For example, the following config maybe used with the C# example from the RPC service tutorial.

"RPCLinkerExample": {
    "window": {
        "id": "RPCLinkerExample",
        "alias": "RPCLinkerExample",
        "native": true,
        "frame": true,
        "resizable": true,
        "autoShow": true,
        "alwaysOnTop": false,
        "showTaskbarIcon": true,
        "contextMenu": true,
        "addToWorkspace": true,
        "top": "center",
        "left": "center"
    },
    "component": {
        "inject": false,
        "mode": "native",
        "category": "system"
    },
    "foreign": {
        "services": {
            "dockingService": {
                "canGroup": true,
                "isArrangable": true
            }
        },
        "components": {
            "App Launcher": {
                "launchableByUser": true
            },
            "Window Manager": {
                "FSBLHeader": true,
                "persistWindowState": true
            },
            "Toolbar": {
                "iconURL": "$applicationRoot/assets/img/Finsemble_Taskbar_Icon.png"
            }
        }
    }
},

Note: If you use the CLI to generate your component, you'll also need to make sure your window object has two extra configs: "native":true and "alias":"your alias" (the one you set in configs/openfin/manifest-local.json).

Bringing in pre-installed applications

It's also possible to bring in other applications but not bundle them with Finsemble. By default, the betaFeatures.assimilation.onlySpawned flag is set to true in configs/application/config.json. If this is set to false, Finsemble will start including outside applications. To control which applications work with Finsemble, use the whitelist and blacklist.

whitelist is an array that lists the application titles that can be included in the Finsemble environment. If you use a partial title, any window with that partial in the title will be brought in. If this array is empty and onlySpawned is false, all windows that are not in the blacklist will be used. Also, if there is single item in this array, every window must match to be included in Finsemble.

blacklist is an array that lists the application titles that will be excluded from the Finsemble environment. If you use a partial title, any window with that partial in the title will be brought in.

A list of these, and other Assimilation options, are defined in the Config Reference.

Assimilating the RPCLinkerExample

The RPC service tutorial provides code samples of native apps that are able to communicate with with Finsemble components via the Linker. These can also be used to test out Assimilation in Finsemble.

For example to assimilate the C# example:

  • Navigate to your finsemble-rpc-linker-example\FinsembleRPCLinkerExample directory.
  • Build the example as described in the RPC service tutorial
  • Create a Zip file from the contents of the finsemble-rpc-linker-example\FinsembleRPCLinkerExample/bin/Debug directory (e.g., C_RPCLinkerExample.zip).
  • Place the Zip file in a /hosted directory at the root of your Finsemble seed projects.
  • Create a /configs/openfin/manifest-local.json entry for the new asset:

      {
          "src":"http://localhost:3375/hosted/C_RPCLinkerExample.zip",
          "alias": "RPCLinkerExample",
          "version": "1.0",
          "target": "FinsembleRPCLinkerExample.exe",
          "args":""
      }
  • If you run Finsemble (npm run dev), you should find you can access the assets locally with URL http://localhost:3375/hosted/C_RPCLinkerExample.zip.

  • Add a component configuration to your components.json file to launch the assimilated application (see Bundling applications with Finsemble above.). In particular, ensure that that "native" is set to true and "alias" matches the one you set in /configs/openfin/manifest-local.json, e.g.,
    "RPCLinkerExample": {
        "window": {
            "id": "RPCLinkerExample",
            "alias": "RPCLinkerExample",
            "native": true,
            "frame": true,
            "resizable": true,
            ...
  • Launch Finsemble (npm run dev) and you should find that you can launch the RPCLinkerExample from the Apps menu.

check   Assimilation allows a user to launch, move, dock, group, and save native components within Finsemble.
 


Further reading

  • Mind Control also deals with using third party apps in the Finsemble application. Read the Mind Control documentation here.
  • The RPC Service can be used to implement communication between native applications and other Finsemble components and is a natural partner to Assimilation. Read the RPC service documentation here.
  • Additional documentation on AppAssets is available here.