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 in dependencies. Dependencies are audited and security vulnerabilities addressed in each release.
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 path to upgrade

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.

note

There is a quick way to see what changed. To compare files in GitHub, use this URL: https://github.com/ChartIQ/finsemble-seed/compare. Choose the version that you are running (such as 6.6) and GitHub will show you all the changes.

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.

Where possible, use the whiteLabel CSS files to modify styles. In particular, the ThemeWhitelabel.css file should do almost everything you need.
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
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.

The basic upgrade process

The steps to perform for an upgrade depend on what was upgraded. We provide specific instructions for each upgrade. However, there are some steps you need to perform every time you upgrade Finsemble.

Here are the steps:

Merge files.
Update the version number of Finsemble in package.json if needed. It might be that the merge process you did in the first step has already updated the version number. If so, skip this step.
Follow the instructions specific to this upgrade, if any.
Rebuild.

Let’s look at these steps in turn.

Merge files

The upgrade process sometimes involves merging new or changed files from finsemble-seed's master branch into your existing Finsemble project. Each new release can have changes to config files, updated system components, modified build scripts, or other updated content.

Although strictly speaking only major releases require merging, as a best practice we recommend that you diff and merge the latest finsemble-seed against your project for all releases.

To see what's changed in finsemble-seed, use this url: https://github.com/ChartIQ/finsemble-seed/compare. Under base choose the tag for the current release that you are running (for example 7.1.1). Leave the compare branch set to "master" (or choose the version that you want to upgrade to). Github will immediately display a diff of all changed files.

If you have forked directly from finsemble-seed, you can merge the most recent changes. See Update your fork directly on Github for step by step instructions. Otherwise you must manually edit your project files based on the diff.

For more info about how to merge files see Git documentation.

Update the version of Finsemble within package.json

To apply a new release, you must upgrade the version of Finsemble's libraries in your package.json. If you merged changes from finsemble-seed above this should already be done. If it isn’t, you can manually update your package.json file in the root of the project with these steps:

Open the package,json file.
Change the version number for all libraries that begin with @finsemble to the latest version in finsemble-seed (or to the version you want).

For example, for upgrading to Finsemble 7.2.0 your code in package.json could look like this:

... 
"optionalDependencies": {
    "@finsemble/finsemble-cli": "7.2.0"
},
"dependencies": { 
    "@finsemble/finsemble-core": "7.2.0",
    "@finsemble/finsemble-electron-adapter": "7.2.0", 
    "@finsemble/finsemble-ui": "7.2.0",
    ...

This is also a good time to update all of your other dependencies. For more info, see Update dependencies.

Follow the instructions specific to your upgrade

Not all releases have additional instructions. If the one you are upgrading to does, follow those instructions now. See instructions for your release for details.

Rebuild

The final upgrade task is to rebuild Finsemble. Here are the steps:

Run yarn install to install the updated versions of your project's npm packages (including the “@finsemble” packages) and then run yarn build.
Verify that your build works by running yarn start on your machine. You should see Finsemble starting up without any issues.
Check the Central Logger for errors. If you find any issues there, you need to correct them before your upgrade is ready to be rolled out.

You are now ready to redeploy your upgraded Finsemble. See Updating your deployed smart desktop.

Preventive maintenance

Upgrading provides a good opportunity to perform some preventive maintenance. The tasks in this section aren't absolutely necessary, strictly speaking. But they will help your environment run more smoothly, and some will also make the next upgrade easier.

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

Check for vulnerabilities

We recommend that you check for any known vulnerabilities in dependencies each time you do an upgrade. One way to do this is to run this command:

yarn run do-audit

The result is a list of packages that have vulnerabilities rated high (8) or critical (16). You can run this in your normal CI workflow. We recommend that as a part of your upgrade process you resolve any issues you find. To resolve the issues you can use any of your normal methods to upgrade. One such method is yarn upgrade-interactive.

Verify your apps

There is one final step that we recommend you do periodically. It isn’t strictly about upgrading, but upgrading provides you a good opportunity to review all your apps to verify that you still need them. If there are apps on your apps menu that nobody uses and likely never will, remove them to reduce the complexity of your smart desktop.

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 7.2 to 7.3

To upgrade from Finsemble 7.2 to 7.3, follow the instructions in the Basic upgrade process section earlier in this topic.

One thing to consider is title bars.

Finsemble supports 2 types of titlebars in its app windows:

injected - The React component that forms the Finsemble title bar is injected into the page and its contents are pushed down by the height of the title bar to accommodate it.
browserview - A view separate from the title bar is created to contain the window's web contents.

In general, in Finsemble the default for window title bars is browserview. However, if you are upgrading from Finsemble 7.1 or 7.2, in those two versions we used the default of injected.

In addition, in Finsemble 7.0 we added a new config that allows you to set this mode system-wide (by specifyingfinsemble.["Window Manager"].titlebarType) or on a per-component basis (by specifyingforeign.components.["Window Manager"].titlebarType).

The safest way to mitigate these necessary default values changes is to set the appropriate titlebarType configurations. This way your Finsemble will continue to work normally. If you have been using the default values for your window title bars and you want to ensure you keep the same values, we recommend that you compare the default value of version you are currently on with the default value you are upgrading to, and update the config of your components or system-wide config accordingly.

note

If you configured the windowTitleBarUrl for a component when browserview was the default (such as "windowTitleBarUrl": "$applicationRoot/components/customWindowTitleBar/customWindowTitleBar.html" ) and then you upgraded to a version with injected, the component won't have a title bar. To remedy this, you need to specifically configure that component to have foreign.components.["Window Manager"].titlebarType = "browserview"

Upgrading from 7.1 to 7.2

To upgrade from Finsemble 7.1 to 7.2, follow the instructions in the Basic upgrade process section earlier in this topic.

Update your manifest to the latest Assimilation file. Finsemble Assimilation has been updated to Assimilation version 7.2.0.

Upgrading from 7.0 to 7.1

To upgrade from Finsemble 7.0 to 7.1, open package.json and change the version number of Finsemble packages from "7.0.0" to "7.1.0". Then run yarn install and yarn build .

There are some small changes in these files and we recommend that you merge them:

gulpfile.js
public/configs/application/UIComponents.json
webpack/webpack.components.js
webpack/defaultWebpackConfig.js
the affected CSS files

Upgrading from 6.6 to 7.0

Important

If you are running a version earlier than 6.6 and want to upgrade to 7.0, we recommend that you upgrade to each version in turn, rather than skipping a version.

To upgrade from Finsemble 6.6 to 7.0, you need to upgrade the version of all @finsemble packages in your package.json to 7.0.0. You will also need to merge these files:

Moving from custom services to app services

If you don’t use custom services, skip this step. Otherwise, we recommend that you migrate your custom services to the new app services.

App services have several advantages over custom services:

Less boilerplate code needed to initialize a service
Finsemble API is injected and initialized by default
Easier to write
Access to FDC3 API
Same features and capabilities as any normal app.

For example, app services will have access to the SelectConnect feature. SelectConnect allows you to control the information flow and which app, component and other services can communicate with your app service.

Code changes

The main difference between app services and custom services is that custom services required you to import and initialize API clients that you needed to use. App services already import and initialize Finsemble API clients for you so migration involves simplifying your code.

If you previously imported all Finsemble API clients and initialized the ones you used, it might look similar to this:

const Finsemble = require("@finsemble/finsemble-core"); 

Finsemble.Clients.Logger.start();
Finsemble.Clients.Logger.log("customService Service starting up"); 

// Add and initialize any other clients you need to use (services are initialized by the system, clients are not):
Finsemble.Clients.LauncherClient.initialize();

You can remove this code and replace all references to Finsemble.Clients.<Client> with FSBL.Clients.<Client> as you would use in a normal app or component.

If you imported and used single clients, for example:

const Finsemble = require("@finsemble/finsemble-core");
const { Logger, WorkspaceClient } = Finsemble.Clients;
Logger.start();
WorkspaceClient.initialize();

you can again remove this code and instead set up a reference to the copy of the client injected for you:

const Logger = FSBL.Clients.Logger;
const WorkspaceClient = FSBL.Clients.WorkspaceClient;

or simply replace the references to those clients.

Finally, there is no need to extend the Finsemble BaseService, declare startupDependencies or implement a handler for onBaseServiceReady and any such code can be removed. If you do need to implement dependencies on your other app services (rather than Finsemble services), see the App services for instructions.

Configuration changes

To migrate your existing services configuration to an appD record, let's assume you have this service configuration in your services.json file:

"myCustomAppService": { 
    "bootParams": {     
        "stage": "preuser", 
            "dependencies": []  
    },  
    "name": "myCustomAppService",
    "html": "$applicationRoot/services/myCustomAppService/MyCustomAppService.html"  
}

This translates to this appD record:

"myCustomAppService": { 
    "appId": "myCustomAppService", 
    "name": "myCustomAppService", 
    "manifest": {   
        "bootParams": {  
            "stage": "preuser", 
            "stopOnFailure": true,      
            "autoStart": true   
        },       
        "appService": true,   
        "waitForInitialization": true,   
        "window": {      
            "url": "$applicationRoot/services/myCustomAppService/MyCustomAppService.html" 
        }   
    }  
}

Process management

If you don’t customize process management settings in your smart desktop, you don’t need to do anything here. In Electron 14, the app.allowRendererProcessReuse flag and affinity argument to BrowserWindow were removed as part of work to align Electron with Chromium's process models (see the Electron changelog for details) and, as a result, to improve the security and maintainability of Electron.

The Finsemble team has implemented a replacement for process affinity that achieves virtually the same effect as affinity in Electron, but remains within the bounds of Chromium process models and site isolation security measures. Hence, Finsemble supports the same config that it currently does for controlling affinity, with a few minor changes:

We've deprecated the manifest.window.windowType: "application" setting, which is currently used to disable affinity. To achieve the same effect in Finsemble 7.0, set manifest.window.affinity: false.
We've added a new setting to control the default affinity applied to apps: finsemble.servicesConfig.launcher.defaultComponentAffinity: "affinityName". Setting this value to false disables using affinity by default. You can override this behavior for an individual app by setting manifest.window.affinity in its appD configuration.

The one other difference is that previously you could use process affinity to combine render threads for apps served from different sites. (For the purposes of site isolation, a site is defined by a domain name and protocol, Port numbers and sub-domains are ignored. For more information about site isolation see Chomium's security documentation.) Combining render threads from different sites is no longer possible for security reasons.

Hence, as a developer working in Finsemble you shouldn't need to make any major changes to your app configurations or implementations to use the new process affinity implementation. We still recommend a quick scan to replace the deprecated config we’ve just looked at. However, you might also be able to achieve a lower overall memory footprint by combining the finsemble UI with the affinities used by business apps. See Process management for more detail.

Configuring title bar

Finsemble includes two different ways of providing a title bar to web apps: a browserview title bar (where an Electron browserview is added to the window with a separate DOM) and an injected title bar (where the title bar is injected into the same DOM as your app, without a separate browserview). To improve process management and to reduce the memory footprint of your desktop, we've switched the default title bar type from browserview to injected. Improved accessibility is an additional benefit of using injected title bars.

Because of a limitation in the Electron Browserview APIs, windows with browerview title bars can't be combined with apps into the same render thread. Hence, injected title bars have a lower memory footprint and provide better support for process management than browserview ones do.

If you don’t want the new default setting you can restore the previous behavior. You can override the default title bar type for all applications by setting finsemble.Window Manager.titlebarType = "browserview" or for an individual app by setting manifest.foreign.components.Window Manager.titlebarType = "browserview" in its appD configuration.

On some rare occasions you might run into a) display issue caused by an injected title bar. If this happens, either switch the component to a browserview title bar or explore the options available for adjusting your page's CSS automatically via the manifest.foreign.components.Window Manager.FSBLHeader configuration settings (see adjustContentHeights and bumpElements).

Upgrading from 6.5 to 6.6

To upgrade from Finsemble 6.5 to 6.6, in the Seed's package.json, change the 4 entries beginning with @finsemble to reference the new version, "6.6.0".

Because we updated Assimilation with this particular release, you need to merge in the changes from the 6.6.0 release's manifest-local.json into your own config. Open the manifest-local.json config and locate the config for Assimilation underneath the "appAssets" header. Update the "src" and "version" fields appropriately:

"src": "https://assets.finsemble.com/releases/6.6.0/assimilation/assimilation.zip"
"version": "6.6.0.0" Notice an extra zero at the end. That's intentional because that’s how Assimilation versioning works.

Upgrading from 6.4 to 6.5

To upgrade from Finsemble 6.4 to 6.5, you need to upgrade the package.json and rebuild. If you are running a version earlier than 6.4 and want to upgrade to 6.5, we recommend that you upgrade to each version in turn, rather than skipping a version.

Upgrading from 6.3 to 6.4

At the minimum, you need to upgrade the package.json dependency versions and rebuild your Finsemble.

In addition, there are optional changes you should consider. We modified some JavaScript files and converted them to TypeScript. As a result, you might optionally want to merge these files into your project:

localStorageAdapter.ts, formerly localStorageAdapter.js
indexedDBAdapter.ts, formerly indexedDBAdapter.js
webpack.adapters.entries.json, now modified to reflect that these two file were renamed

caution

Don't do a piecemeal merge. Either merge all these files, or none at all.

For all of the project-side changes between 6.3 and 6.4, see https://github.com/ChartIQ/finsemble-seed/compare/release/6.3.0...release/6.4.0-beta.2)

Issues you might run into

We’ve deprecated the ShareButton as deprecated in the WindowTitlebar. As a result you could see a log message like this one in your Central Logger:

The ShareButton component is deprecated. It will be removed in a future Finsemble version.

To get rid of this message, remove ShareButton from WindowTitleBar.tsx.

WindowTitleBar.tsx has changed. You don’t need to merge this change into your seed yet, but this functionality has been deprecated and will be removed in the future. We recommend you start planning for the removal ahead of time.

Upgrading from 6.2 to 6.3

Upgrading from 6.2 to 6.3 involves merging in the changes from the new package.json that we include in the release into your own package.json. You will also need to copy the changes from the Seed's webpack directory into the webpack directory for your own project, in order to take advantage of the vendor bundling size optimizations included with this release.

Upgrading from 6.1 to 6.2

Upgrading from 6.1 to 6.2 involves merging in the changes from the new package.json that we include in the release into your own package.json.

There are no breaking changes in this release. However, there are some dependencies that will give you a warning in your build output if you don’t upgrade them. None of these are critical, but because there are several of them, you will see quite a few of these warnings. Seeing these warnings every time you build can be confusing and irritating. For this reason, we strongly recommend that you upgrade these dependencies at this time.

For your information, here is the complete list of dependency version changes from package.json as part of this release:

Optional dependencies

@finsemble/finsemble-cli: 6.1.3 --> 6.2.0

Dependencies

@finsemble/finsemble-core: 6.1.3 --> 6.2.0
@finsemble/finsemble-electron-adapter: 6.1.3 --> 6.2.0
@finsemble/finsemble-ui: 6.1.3 --> 6.2.0
async: 3.2.0 --> 3.2.1

Dev dependencies

@babel/core: 7.14.6 --> 7.15.0
@babel/plugin-transform-modules-commonjs: 7.14.5 --> 7.15.0
@babel/plugin-transform-runtime: 7.14.5 --> 7.15.0
@babel/preset-env: 7.14.7 --> 7.15.0
@babel/runtime: 7.14.8 --> 7.15.3
chalk: 4.1.1 --> 4.1.2
react-syntax-highlighter: 15.4.3 --> 15.4.4
ts-loader: 9.2.3 --> 9.2.5
webpack: 5.45.1 --> 5.51.1
webpack-cli: 4.7.2 --> 4.8.0

You can also compare branches.

Upgrading from 6.0 to 6.1

To upgrade from 6.0 to 6.1 you need to make sure you have node.js v14.17.4.

Important

We support the latest LTS version of node.js. If you use the later version, Finsemble might not work.

Finsemble's seed project has been upgraded to use Webpack 5 and Typescript 4. Because of these upgrades and because some of the features were renamed, we’ve made some changes in the Seed repo. The seed's webpack directory, package.json, and tsconfig.json files have been updated, and these changes need to be merged when upgrading.In this release, @finsemble/ui's new <FinsembleIcon> component depends on an additional Webpack Loader for SVG files (@svgr/webpack), which is pre-configured in the default Webpack configuration rules (defaultWebpackConfig.js).

We recommend that you merge in the latest seed changes into your own desktop project when you upgrade. For a full list of necessary changes, see the 6.0.0 to 6.1.0 comparison on GitHub.

If you are on v6.0, we recommend that you check out the new v6.1 release branch and merge it into your current v6.0 branch. Depending on the level of customizations you’ve made, you might encounter some conflicts (mainly in the package.json and JSON config files) which need to be resolved. All other v6.1 changes should be automatically merged (if you have made build customizations you will also get some conflicts that need to be dealt with on the webpack folder).

Upgrading from 5.4 to 6.0

note

Finsemble 6.0 requires Node.js version 12 and yarn. If you run into permission issues, check out the advice in Installing.

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
- The json and img files previously located in /configs and img files located in /assets have moved into /public
/build/webpack moved to /webpack
- gulp-extensions was importing ./build/webpack, changed to ./webpack
Updates to .gitIgnore

Updates to .md files

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

Updates to the package.json file
- package.json had over 40 conflicts due to changing from spaces to tabs.
- We added several packages and many packages had their version updated.

Config changes
- You might need to manually merge config in manifest-local.json and components.json
- Finsemble 6.0 automatically calculates the values of the config macro variable (e.g. $applicationRoot, $moduleRoot). So, you don’t need to set these in your manifest file if you switch to the new Finsemble directory structure. If you need to customize the macros, see [Using manifest macros][./deployingYourSmartDesktop.md#Using manifest macros to optimize complex deployments]
- Config files are no longer stored under $applicationRoot. Use the $configRoot variable for specifying paths to config files instead.

Depending on your customizations, you might 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.

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.
Copy build/webpack/webpack.component.entries.json from the old project to the webpack directory in the new project.
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.
If there is a gulpfile-extensions.json file, copy those to the root directory of the new project.
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.
We eliminated the server folder. If you were using the Seed project's built-in server, you will need to use a gulpfile-extensions.js file to replace the existing startServer gulp task. Copy that task into /gulpfileextensions.js and customize it.
note
The app that is returned from FEA.Server.start() is an express server that can be amended as needed.
Copy the contents of your /assets folder from the old project to the /public/assets directory in the new project.
The config folder has moved to the /public/configs.
- In earlier versions of Finsemble (before 6.0), the $applicationRoot config macro gave the URL to the root of your Finsemble deployment. Finsemble 6.0 revises the deployed directory structure and separates static assets (such as images, config files etc.) from built files.
  - A new macro represents the root of your deployment, $documentRoot.
  - $applicationRoot points to built files and defaults to $documentRoot/build.
  - The config folder is no longer located under $applicationRoot. A new config macro, $configRoot, provides the path to the config folder and defaults to $documentRoot/configs.
- Config macros (such as $applicationRoot , $moduleRoot, and $configRoot) are calculated automatically from the manifest file path and don’t need to be specified in your manifest. This calculation assumes you’re using the default folder structure for Finsemble 6.0.
  - If you need to override the default macros, see [Using manifest macros][/docs/managing-and-administrating/deployingYourSmartDesktop#using-manifest-macros-to-optimize-complex-deployments].
  - If you need to create your own custom macros you can do so by adding them to the finsemble.custom section of your manifest.
- Reapply changes that you made to the default config files.
  - Use a diff tool such as windiff or meld to simplify this task.
  - We modified manifest-local.json and removed the config macros. Finsemble now calculates them automatically.
  - Before running a diff on config.json, replace spaces with tabs.
    - In VSCode press Crtl+P and then pick Convert Indentation to Tabs from the dropdown menu.
    - When reapplying changes, verify the frequently changed configurations:
      - Tabbing and tiling config
      - Logger config
      - importConfig. You might need to change the macro $applicationRoot to $configRoot. For example, $applicationRoot/configs/application/components.json is now $configRoot/application/
  - UIComponents.json - 6.0 adds the FDC3 Resolver
We modified the contents of the /src directory, mostly adjusting links and imports for the new location of css and assets. If you’ve customized Finsemble’s built-in UI components, you need to copy your src files into this directory and reapply any changes you've made. The most important files are:
- /src/toolbar/src/Toolbar.tsx,
- /src/toolbar/src/FileMenu.tsx, and
- /src/windowTitleBar/WindowTitleBar.tsx

When you’re done, build with yarn dev. You can also copy the content back to your original project and check it into your revision control.

Moving from Linker to Interop (FDC3)

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
`subscribe`	`addContextListener`
`publish`	`broadcast`
	`addIntentListener`
`getAllChannels`	`getSystemChannels`
	`getOrCreateChannel`
`getLinkedComponents`	`N/A`
`getLinkedWindows`	`N/A`
`getState`	`getCurrentChannel`
`linkToChannel`	`joinChannel`
`onStateChange`	`N/A`
`openLinkerWindow`	`N/A`
`removeEventListener`	`N/A`
`unsubscribe`	`addContextListener.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 (that is 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.

Specifically, here are the changes:

The /public/config/application/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:
npx finsemble-cli migrate
You can also add new apps to appd.json using the new CLI command: npx finsemble-cli add app <appname>
Finsemble 6.0 supports all Finsemble config if you specified them in the manifest property of an app definition within the appd.json file.
FSBL.Clients.ConfigClient.processAndSet() still functions as expected and you can use it to add applications to Finsemble's appd configuration.
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.

For more info about configuration, see Configuration reference

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

caution

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);

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 <AppLauncherMenu /> with <RenamedAppLauncherMenu enableQuickComponents={true} /> 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:

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.
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.
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 can 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.
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
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 smaller 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:

$ finsemble.exe --silent

For more information about deployment, see Deploying your smart desktop.

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:

Find the packages.json file and open it.
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",

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.

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:

Browse to https://github.com/ChartIQ/finsemble-seed/

Pick the release branch that you want: (Release branches are always prefixed with "release/")

Click Compare

Pick your current release version:

Now you can see the changes for the release. Apply all the changes.

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.

Upgrading Finsemble

Should you upgrade?​

The path to upgrade​

Make your next upgrade easier​

Separate business logic and styles​

The basic upgrade process​

Merge files​

Update the version of Finsemble within package.json​

Follow the instructions specific to your upgrade​

Rebuild​

Preventive maintenance​

Update dependencies​

Deprecated features​

Check for vulnerabilities​

Verify your apps​

If you run into trouble​

Upgrading from 7.2 to 7.3​

Upgrading from 7.1 to 7.2​

Upgrading from 7.0 to 7.1​

Upgrading from 6.6 to 7.0​

Moving from custom services to app services​

Code changes​

Configuration changes​

Process management​

Configuring title bar​

Upgrading from 6.5 to 6.6​

Upgrading from 6.4 to 6.5​

Upgrading from 6.3 to 6.4​

Issues you might run into​

Upgrading from 6.2 to 6.3​

Upgrading from 6.1 to 6.2​

Upgrading from 6.0 to 6.1​

Upgrading from 5.4 to 6.0​

Manual upgrade From 5.4 to 6.0​

Moving from Linker to Interop (FDC3)​

Linker APIs vs Interop APIs​

Upgrading from components.json to appd.json​

A component defined in components.json​

An app defined in appd.json​

Migrating using the CLI​

Dynamic configuration​

Dynamic configuration in the toolbar​

.NET changes​

Continuing to use Quick Components​

Deploying your upgrade​

Alternative deployment procedure​

Upgrading from 5.x to 5.4​

Upgrading packages​

Upgrading assimilation​

Updating seed​

Upgrading the seed from 5.0 to 5.x​

Upgrading from 4.x​

Should you upgrade?

The path to upgrade

Make your next upgrade easier

Separate business logic and styles

The basic upgrade process

Merge files

Update the version of Finsemble within package.json

Follow the instructions specific to your upgrade

Rebuild

Preventive maintenance

Update dependencies

Deprecated features

Check for vulnerabilities

Verify your apps

If you run into trouble

Upgrading from 7.2 to 7.3

Upgrading from 7.1 to 7.2

Upgrading from 7.0 to 7.1

Upgrading from 6.6 to 7.0

Moving from custom services to app services

Code changes

Configuration changes

Process management

Configuring title bar

Upgrading from 6.5 to 6.6

Upgrading from 6.4 to 6.5

Upgrading from 6.3 to 6.4

Issues you might run into

Upgrading from 6.2 to 6.3

Upgrading from 6.1 to 6.2

Upgrading from 6.0 to 6.1

Upgrading from 5.4 to 6.0

Manual upgrade From 5.4 to 6.0

Moving from Linker to Interop (FDC3)

Linker APIs vs Interop APIs

Upgrading from components.json to appd.json

A component defined in components.json

An app defined in appd.json

Migrating using the CLI

Dynamic configuration

Dynamic configuration in the toolbar

.NET changes

Continuing to use Quick Components

Deploying your upgrade

Alternative deployment procedure

Upgrading from 5.x to 5.4

Upgrading packages

Upgrading assimilation

Updating seed

Upgrading the seed from 5.0 to 5.x

Upgrading from 4.x