Upgrading Finsemble

Should you upgrade?

If you’re considering whether to upgrade, the answer is yes. In fact, the earlier version you have, the more important it is to upgrade. There are several reasons for this recommendation:

  • New features. The later versions often have features you need but currently don’t have.
  • Bug fixes. An upgrade can contain bug fixes.
  • Security vulnerabilities. It is critical that you address any known security vulnerabilities as soon as possible.
  • Security and bug fixes for Electron. Finsemble upgrades almost always include a newer Electron version, which contains security and bug fixes for chromium, node.js, and Electron itself.

The other important question is when to upgrade. That depends on what version of Finsemble you’re running. The earlier your version, the longer it takes to upgrade. We strive to make the upgrade as easy as possible, but realistically, it does take some time. For this reason, we recommend that you set aside some time for performing the upgrade. For patch releases, it will go faster. For minor releases, it’s a medium effort. Upgrading to a major release could be complex. If you highly customized your installation, it might take more work to upgrade. As always, following the industry standard practices makes it easier to perform upgrades.

The upgrade process

Each upgrade depends heavily on the Finsemble version immediately before it. For this reason, there is no direct path that spans multiple upgrades at one step. For example, you can’t go directly from 5.3 to 6.0. The correct way is to first upgrade from 5.3 to 5.4 and then from 5.4 to 6.0. In general, we recommend that you upgrade in steps, applying each set of instructions in turn. This way, you can be sure you upgraded correctly and didn’t miss anything.

Make your next upgrade easier

There will be more upgrades in the future. If you make some changes now, this and any future upgrades will be easier. Here are our best tips.

Separate business logic and styles

In general, it is a good practice to keep the logic and the styles separate from each other and from the Finsemble code. This way, you don’t have to touch everything when you upgrade Finsemble. Here are the specifics.

  1. Where possible, use the whiteLabel CSS files to modify styles. In particular, the ThemeWhitelabel.css file should do almost everything you need.
  2. UI customizations can cause conflicts when you update to the latest Finsemble seed version, particularly if the modifications are extensive. Hence, you should do any major modifications to built-in Finsemble components in /src-built-in by copying the folder to /src and making the changes there. This will prevent merge conflicts on update. E.g. copy toolbar from src-built-in/toolbar to src/toolbar* * Don’t forget to update the relevant config entries in /configs/application/presentationComponents.json to point to your new version in /src
  3. Although we include a full build system for components, services, and preloads for your convenience, you don’t have to use it. In fact, separating your business components into a different repository and build can significantly simplify your project.
    • We recommend that you build and host components, services, etc. independently of Finsemble. You only need to integrate their configuration. For example, you can add them to /configs/applications/components.json in Finsemble 5.4 or earlier, or to /configs/applications/appD.json in Finsemble 6.0 or later. You can also import a config file, or use dynamic configuration.
    • You can also use Create React App, Nx.Js, or similar bootstrapping tools, to set up and prototype new components. For an example of using create-react-app, see React applications.

Updating dependencies

Always keep Finsemble, Finsemble-electron-adapter, and the Seed project in sync. In other words, they all should have the same major and minor version numbers. For example, for version 3.12.x the first two digits of each package's version number should be 3.12.

Some variation in patch version numbers is to be expected. For example, during a finsemble startup you could see in the console:

Using: @chartiq/finsemble @Version 3.12.0. Using: @chartiq/finsemble-cli @Version 3.3.1. Using: @chartiq/finsemble-react-controls @Version 3.12.0. Using: @chartiq/finsemble-electron-adapter @Version 3.12.1.

The Finsemble team strives to keep the versions of dependencies of the various Finsemble libraries up to date and regularly audits them. We strongly recommend that you don’t update those dependencies independently of a FInsemble release. If you do so, you could experience issues if that combination of Finsemble version and dependency versions hasn’t been tested.

Deprecated features

When API and other features become deprecated, you need to update the code in the seed project accordingly. Although the deprecated features still work, they might go away in the next version. It’s best to take the time and remove them now so that your next upgrade will be easier.

If you run into trouble

Each installation of Finsemble is unique, and the instructions here might not work for you. In this case, contact support@finsemble.io for help.

Upgrading from 5.4 to 6.0

Merge from finsemble-seed/. When merging Finsemble 6.0 from a remote origin into a new branch of your project, the merge will show conflicts that you need to resolve. These conflicts include:

  • Name changes related to the addition of the public directory

  • /dist moved to /public/build

  • /config and /assets moved into the /public directory

  • /build/webpack moved to /webpack

  • Updates to .gitIgnore

  • Updates to .md files

  • Changes to the GulpFile because of changes to paths and the new folder structure

  • package.json had over 40 conflicts due to changing from spaces to tabs.

  • We added several packages and many packages had their version changed.img

  • The json and img files previously located in /configs and img files located in /assets have moved into into /public

  • gulp-extensions was importing ./build/webpack, changed to ./webpack

  • Lots of manually merging config in manifest-local and components.json

  • Custom config macro variables now support relative paths

Depending on your customizations, you could find other conflicts that you need to resolve.

Manual upgrade From 5.4 to 6.0

Use this strategy if you haven't forked from the seed or are running into difficulty using the merge steps.

  1. Clone the latest 6.0 seed into a new directory. It will be easier to move files into the new seed than the other way around. You can copy files back after the merge.
  2. Copy build/webpack/webpack.component.entries.json from the old project to the webpack directory in the new project.
  3. Because of the new folder structure in 6.0, gulpfile.js has changed. An example is the constant configPath. It now references the new webpack directory. If you made any custom changes, you need to port them to the new file.
  4. If there are any gulpfile-extension files, copy those to the root directory of the new project.
  5. Reapply any changes made to the original package.json to the new package.json. Use a diff tool such as windiff or meld to identify these changes.
  6. We eliminated the server folder. If you were using the Seed project's built-in server, you will now need to write a gulp extension that replaces the existing startServer gulp task. Copy that task into your gulp extension. The "app" that is returned from FEA.Server.start() is an express server that can be amended as needed.
  7. Copy the assets folder from the old project to the public directory in the new project.
  8. The config folder is now located in the /public folder. Reapply any changes made to config files. Use a diff tool such as windiff or meld to simplify this task.
    • Manifest-local.json has been modified to use relative subfolders.
    • Components.json can be copied over.
    • Config.json : Before running a diff, replace spaces with tabs. You can do this in VSCode by hitting Crtl+Shift+p and then typing Convert Indentation to Tabs. When reapplying changes, pay special attention to the configurations listed here as these are commonly changed when customizing a desktop:
      • Tabbing and tiling config
      • Logger config
      • importConfig. The macro $applicationRoot has changed to $configRoot. For example, $applicationRoot/configs/application/components.json is now $configRoot/application/UIComponents.json
      • dashboard is now dashbarConfig
      • UIComponents.json - 6.0 adds the FDC3 Resolver
  9. We modified the contents of src, mostly adjusting links and imports for the new location of css and assets. Copy your src files into this directory and reapply any changes you've made to Finsemble's built in components. The most important files areToolbarFilemenuWindowTitleBar tsx files

When you’re done, build with yarn dev and/or copy back to your original project.

Moving from Linker to Interop

Although the Linker Service and Interop Service provide similar functionality, there isn't a 1 to 1 correlation between APIs. Some use cases, such as publishing data from 1-to-many apps, are straightforward. You can replace publish() with broadcast(). In other cases, like getLinkedWindows(), this functionality is no longer supported.

When you transition from Linker APIs to Interop APIs, remember that not only have the functions and signatures changed, but so has the structure of the data being passed.

Take this example of an object being passed to FSBL.Clients.LinkerClient.publish(). It’s a simple object with dataType and data properties. Any app on the same channel listening for a topic “symbol” receives the update.

FSBL.Clients.LinkerClient.publish({
	dataType: "symbol",
	data: "AAPL",
});

The same can be achieved using the Interop Service’s broadcast function with an FDC3 context object.

fdc3.broadcast({
	type: "symbol",
	symbol: "AAPL",
});

Context objects can contain any fields. The only requirement is that they contain a field called type which other apps listening on the same channel can use. To learn more about FDC3 context objects and the FDC3 standard, see the spec.**

Linker APIs vs Interop APIs

Here is a basic reference of Linker APIs, and possible replacements within the Interop Service.

Replace the Linker Client APIs With this Interop Client
addContextListener addContextListener
addIntentListener
getAllChannels getCurrentChannel
getSystemChannels
getOrCreateChannel
getLinkedComponents N/A
getLinkedWindows N/A
getState getCurrentChannel
getSystemChannels
getOrCreateChannel
linkToChannel joinChannel
onStateChange N/A
openLinkerWindow N/A
publish broadcast
raiseIntent
raiseIntentForContext
removeEventListener N/A
subscribe addContextListener
addIntentListener
unsubscribe addContextListener.unsubscribe
addIntentListener.unsubscribe
unLinkFromChannel leaveCurrentChannel

Notes

  • If you’re using the FDC3 extension in the existing implementation, removing the extension should be as simple as deleting the preload from component config, then removing the custom service and client from the project.
  • To use your own fdc3, you need to override window.fdc3 (which Finsemble injects). You could do this in code or with a preload.
  • Apps that use the Linker Service don’t interoperate with apps that use the Interop Service. We recommend that you migrate apps based upon common interop needs.
  • Linker channel names, colors, and the number of channels are no longer customizable.
  • There is no longer a way for a window to identify the other windows to which it is linked. The reason is that this is not currently supported in the FDC3 standard. Rather than extending the standard, we made a product decision to stick to the standard to steer developers away from low level (i.e., imperative) coding.

More about Interop Documentation.

Upgrading from components.json to appd.json

The appd.json file, located at ..\public\configs\application\appd.json, follows FDC3’s AppD schema. When you configure your app in this way, you make it easier to port it, and to implement AppD Servers and custom app catalogs.

Specifically, here are the changes. You don’t need to take any action, this is only for your information:

  • An appd.json file is new to the Seed Project’s configs and sets this config entry point.
  • You can port apps configured in components.json to the appd.json using a new CLI command.
  • Finsemble 6.0 supports all Finsemble config if you specified them in the manifest property of an app definition within the appd.json file.
  • Internally, appd.json configuration is converted at runtime to Finsemble's internal component format within Finsemble’s Launcher subsystem.
  • FSBL.Clients.ConfigClient.processAndSet() still functions as expected
  • The launcher subsystem gives the apps loaded from the appd.json file two additional fields. These are temporary helpers to drive transitionary logic.
    • appDConfig contains the original AppD configuration
    • isAnApp is set to true.

More about Configuration Documentation

A component defined in components.json

Consider this example component definition from an earlier version of Finsemble.

"components": {
    "Welcome Component": {
      "window": {...},
      "component": {
        "displayName": "Welcome Component",
        "spawnOnStartup": false,
        "preload": "$applicationRoot/preloads/zoom.js"
      },
      "foreign": {
        "services": {...},
        "components": {...}
        }
      }
    }}

An app defined in appd.json

Notice the configuration starting with the manifest. Finsemble configuration from components.json is now nested under the manifest property in the app definition.

"appd": {
    "Welcome Component": {
      "appId": "Finsemble Welcome Component",
      "name": "Finsemble Welcome Component",
      "description": "Have a friendly welcome when you start your Finsemble experience.",
      "manifest": {
        "window": {...},
        "component": {...},
        "foreign": {
          "services": {...},
          "components": {...}
        },
        "interop": {}
      },
      "version": "1.0.0",
      "tooltip": "Welcome to Finsemble",
      "images": [],
      "contactEmail": "info@cosaic.io",
      "supportEmail": "support@finsemble.com",
      "publisher": "Cosaic",
      "icons": [],
      "intents": []
    }

Migrating using the CLI

A migration script moves apps from components.json to appd.json (and changes the format to AppD).

npx finsemble-cli migrate

Careful: This script overwrites appd.json. It is meant to be used one time only.

Notes:

  • Make sure you are using the Finsemble 6.0 version of the CLI.
  • Only visible apps (that is, components with foreign.components.App Launcher.launchableByUser set to true) get migrated from components.json to appd.json. Hidden apps will not be migrated.

Dynamic configuration

Per the Dynamic Configuration tutorial, you need to make a few changes to enable the same functionality with apps in appd.json. Instead of accessing components from finsemble.components, apps in appd.json are accessed from finsemble.appd.

This example shows a listener and handler written to respond to changes to component.type.

Before

function configChanged(err, newConfig) {
	// Do what you need to do here with newConfig
}

// Get component type of current component
var componentType = FSBL.Clients.WindowClient.options.customData.component.type;

// Add listener
FSBL.Clients.ConfigClient.addListener({ field: "finsemble.components." + componentType }, configChanged);

After After you configure apps in appd.json, rewrite the listener to respond to changes in app.name. Note that component.type and app name property share the same purpose. Also, appD config is accessed via the appDConfig property from the WindowClient.

function configChanged(err, newConfig) {
	// Do what you need to do here with newConfig
}

// Get component type of current component
let appName = FSBL.Clients.WindowClient.options.customData.appDConfig.name;

// Add listener
FSBL.Clients.ConfigClient.addListener({ field: "finsemble.appd." + appName }, configChanged);

Dynamic configuration in the toolbar

Instead of a component property and setter, access apps from an apps property and setter after getting the finsemble config from the ConfigClient.

const [apps, setApps] = useState([] as any[]);
useEffect(() => {
		FSBL.Clients.ConfigClient.getValue("finsemble", (err: any, config: any) => {
			const menuConfig = config.menus;
			const apps = config.appd;
			if (Array.isArray(menuConfig)) {
				setDynamicMenus(
					menuConfig.filter((menu) => menu.menuType === "App Launcher" || menu.menuType === "Advanced App Launcher"),
				);
				setApps(
					apps
				);
			}
		});
	}, []);

.NET changes

The introduction of .NET Core 5 support introduces several changes to the structure of Finsemble DLL. You need to add multiple dlls based on your choice of UI Framework in .NET. Most of the Finsemble API is available via Finsemble.Core.DLL and anything UI specific is available via Finsemble.WPF.Dll and Finsemble.Winforms.DLL.

Continuing to use Quick Components

If you want to continue using the Quick Component in the App Launcher (not to be confused with the Advanced App Launcher), we suggest these steps:

Copy a previous version of the appLauncher component from the 5.x finsemble-ui package npm package.

Rename it and move the renamed version to the location where you keep client UI components.

Replace with in Toolbar.tsx.

Copy the quickComponentForm component from the 5.x or 6.0 finsemble-ui npm package.

Rename it and move the renamed version into the location where you keep client UI components.

Update packages\seed\src\components\quickComponentForm\QuickComponentForm.tsx to reference the renamed quick component form.

This assumes that the quick component form already exists in the seed, and is referenced in the UIComponents.json config. If you don’t have one, copy it from the previous version of Finsemble.

Deploying your upgrade

After you complete your update, you need to deploy it to your users. Here are the steps:

  1. To expedite the update, set finsemble.waitForUpdate: true within your 5.x manifest-local.json config. This will force Finsemble to retrieve and install any available updates for the container, Finsemble Electron Adapter, before starting up. If not set, Finsemble will start up normally on your existing version, download updates in the background and prompt the user to restart to apply the update when it is ready.

  2. Build and deploy 6.0 assets, including the manifest, to a new host URL. Don’t use the old location for this step. You need to deploy to a new location because, during the update, you need both versions to coexist. You need the old version to be able to load on the old directory structure so that it can run and update the user to 6.0. The two versions can coexist on the same server, but need to be on separate paths.

  3. Set the serverConfig URL in the public/configs/other/server-environment-startup.json file in your 6.x version to the location of the new manifest file. You may use the same updateUrl as configured for your 5.x version or set a new one, to be used for future updates, at your discretion.

  4. Build your 6.0 installer, as explained in Deploying your smart desktop. This process creates several new files:

    • Installer .exe file
    • Delta .nupkg file (created if you retained your previous installer files)
    • Full .nupkg file
    • RELEASES
  5. You must deploy all of the files created for the Electron upgrade to work. The Delta files contain only the difference between the previous and current installer files and allow for a small update download.. The RELEASES file contains info about the available updates. Finsemble retrieves it first to determine if there is an update that needs to be applied.

    Copy the full, delta (if created) .nupkg files, and RELEASES files to the location that is referenced by your updateUrl, configured in your configs/other/server-environment-startup.json file in your 5.x version. You can also deploy the installer .exe file to the same location, or another URL, for new users to download.

    The next time your users launch Finsemble, they will be automatically upgraded to the new version.

    Note: You must specify updateUrl when building the installers for both 5.x and 6.x to enable updates. See Deploying your smart desktop for details.

Important: You have deployed your 6.0 assets to a new URL. This results in you having deployments of both 5.x and 6.0 Running an upgraded 6.0 executable that is targeting a 5.x environment doesn’t work. Neither will an old 5.x executable run on an upgraded 6.0 environment.

You can remove the old version after all the users have upgraded to 6.x.

Alternative deployment procedure

If you haven’t configured auto-update or used a deployment system to install FInsemble for your users, you can run the full installer .exe file to overwrite a 5.x installation with a 6.0 version. To do so, follow steps 1-4 above to create a 6.0 deployment and build an installer for it. You can then either distribute the installer .exe file for your users to run, or you can apply it for them.

Note: Finsemble is normally started automatically after installation. To instead execute a silent install of Finsemble use the command line and add the --silent flag after the path to the installer .exe file, e.g.

$ finsemble.exe --silent

Upgrading from 5.x to 5.4

The upgrade process includes:

  • Packages
  • Assimilation, unless you disabled it
  • Seed

Let’s look at each in turn.

Upgrading packages

Most of Finsemble's updates consist of packages you add to your own Finsemble build. Update your Finsemble packages in the packages.json. The specific packages you need to update depend on the update. Finsemble includes these packages:

  • @finsemble/finsemble-core,
  • @finsemble/finsemble-electron-adapter
  • @finsemble/finsemble-ui
  • @finsemble/finsemble-cli

Major and. minor releases usually update all of these packages, but patches might update one or more of these.

You also need to update your version number. Here is what you need to:

  1. Find the packages.json file and open it.
  2. Find the lines where the old version number is stored. For example, you might see something like this:
"license": "SEE LICENSE IN LICENSE",  
   "optionalDependencies": {	
      "@finsemble/finsemble-cli": "5.3.*"
   },
   "dependencies": {
   "@finsemble/finsemble-core": "5.3.*",
   "@finsemble/finsemble-electron-adapter": "5.3.*",
   "@finsemble/finsemble-ui": "5.3.*",
   "async": "3.2.0",
   "compression": "1.7.3",
   "express": "4.16.4",
  1. Replace the old version number with the new one. Your screen should look similar to this:
"license": "SEE LICENSE IN LICENSE",
   "optionalDependencies": {
      "@finsemble/finsemble-cli": "5.4.*"	
   },
   "dependencies": {
      "@finsemble/finsemble-core": "5.4.*",
      "@finsemble/finsemble-electron-adapter": "5.4.*",
      "@finsemble/finsemble-ui": "5.4.*",
      "async": "3.2.0",
      "compression": "1.7.3",
      "express": "4.16.4",
      ...

Notice that in our example the version changed from 5.3 to 5.4 in multiple places.

  1. Run yarn install or npm install to bring in the new packages.

Upgrading assimilation

If you have assimilation enabled, you want to incorporate updates to it into your upgrade. The assimilation version is updated at runtime. To upgrade assimilation, find the latest version on https://github.com/ChartIQ/finsemble-seed/releases and download the .zip file. On your local machine, open the file configs/application/manifest-local.json. In the appAssets object, find the assimilation version for your release.

Replace the Assimilation object in your own config with the one in the repo. For example, the config would change from this:

"appAssets": [
               {
                  "src": "https://assets.finsemble.com/assimilation/assimilation_5.0.1.0.zip",
                  "version": "5.0.1.0",
                  "alias": "assimilation",
                  "target": "AssimilationMain.exe"
                }
             ],

to this:

"appAssets": [
               {
                  "src": "https://assets.finsemble.com/assimilation/assimilation_5.1.0.0.zip",
                  "version": "5.1.0.0",
                  "alias": "assimilation",
                  "target": "AssimilationMain.exe"
               }
             ],

Note: Version 5.2.0 doesn’t have an upgrade from version 5.1.0. There is work underway to incorporate assimilation into one of the packages in the section above.

Updating seed

If there are changes to the seed, we publish them to the seed repository. See https://github.com/ChartIQ/finsemble-seed/releases for details.

We usually provide seed releases when we introduce new UI components, a new version of assimilation, a new configuration, or in some cases bug fixes or improvements to the build.

Depending on the level of changes to your project and the changes in the seed, you may be able to merge in the seed branch with minimal changes. Ideally, you should keep seed changes to a minimum. This way, any changes to the seed won’t affect your customizations.

To see the new features available, we recommend that you diff your current version against the version you want to upgrade to. You can do this on GitHub:

  1. Browse to https://github.com/ChartIQ/finsemble-seed/
  2. Pick the release branch that you want: (Release branches are always prefixed with "release/")
Finding the branch in GitHub
  1. Click Compare

    Comparing branches
    1. Pick your current release version:

      Picking a branch
    2. Now you can see the changes for the release. Apply all the changes.

    Viewing changes in GitHub

Upgrading the seed from 5.0 to 5.x

Skip this section if you started from anything other than 5.0.0.

The 5.0.0 seed has different naming conventions and its commit history is separate from the rest of the releases. Therefore, for updating the seed from version 5.0.0 on branch release-5.0.0 you must use a merge assist branch.

Important: the 5.0 release doesn’t follow the release/ prefix convention.

There are currently the 5.0.0-5.1.1-merge-assist and 5.0.0-5.2.0-merge-assist branches. To update from 5.0.0, follow the same procedure outlined in the previous section for updating the seed, but use these merge assist branches. Most of the changes will be white space changes. After you complete this process once, you won’t need any further merge assist branches.

Upgrading from 4.x

If you’re running a very early version of Finsemble, we don’t recommend that you upgrade it by yourself. Contact support@finsemble.io and we’ll be happy to help.