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 a Finsemble instance. 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 OpenFin 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 RPC service tutorial C# example.

"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/components/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). Full support for native component generation in the CLI is coming in a future release. Note: Additional OpenFin documentation on AppAssets is available here.

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 defined below.

Options

"assimilation": {
    "enabled": true,
    "blacklist": [],
    "whitelist": [],
    "onlySpawned": true
}
  • enabled (boolean) - Turns assimilation on/off.
  • whitelist (array) - A list off 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 (array) - A list of 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.
  • onlySpawned (boolean) - Only components that are spawned from Finsemble will be included in Finsemble as long as they are not in the blacklist.

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.

Planned features for Assimilation

  • Spawned applications will soon be able to save their position
  • Whitelist and blacklist will be able to use title and/or executable to filter
  • Use regex for whitelist and blacklist
  • Allow a path for spawning appAssets

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.