Finsemble Seed for io.Connect Desktop 🌱

The polyfill continues to support the legacy Finsemble container (FEA). With this seed version you can run your Finsemble project against either container.

Customers wishing to work directly with iocd instead of finsemble-seed should read IOCD quickstart

io.CD Version

The current seed and finsemble-core package are compatible with io.Connect Desktop version 10.

The current recommended version is v10.2.0 release.

Installing

1) If upgrading from existing Finsemble seed, follow these steps, otherwise simply clone this repository

a. Delete your yarn.lock or package-lock.json file (important!)

b. Change `@finsemble/finsemble-core` entry to match the version in this branch.

c. Copy the `setup-iocd`, `iocd` and `dev-iocd` package.json scripts from this branch.

d. Add below entries to your package.json as dev dependencies:
```
    "devDependencies": {
        "@electron-forge/core": "latest",
        "@electron-forge/maker-dmg": "latest",
        "@electron-forge/maker-squirrel": "latest",
        "@electron-forge/maker-zip": "latest"
    }
```

e. If you override system.json via project.json, see the updated schema in [Overriding iocd](#overriding-iocd).

f. In previous versions there are various keys to set iocd overrides in finsemble configuration: `io-connect`, `io.Connect`, `iocd`. They are now unified to `iocd`, please make the change if you see deprecated warnings in your project.

2) Run yarn install

3) Add the license key which we provided to you: > This can be set in installer.clientKey in project.json. > > Alternatively, you can set the environment variable IOCD_LICENSE_KEY to your license key text. This can be accomplished by creating a .env file at the seed's root which contains IOCD_LICENSE_KEY="<your license>".

4) Run yarn setup-iocd, it creates (or updates) the iocd seed config for your project and downloads iocd executable components:
> During the config creation (or update), fields from your project.json will be read and applied to the /configs and /assets folders. > > If you get an error about downloading components, your corporate security may be preventing downloads from github. Proceed to section Using custom iocd store instead. > > This command supports arguments --skip-install, --skip-config and --skip-assets. For instance, run yarn setup-iocd --skip-install to update configs without re-downloading iocd component.

Usage Caveats

1) The setup generates these folders in your project: ".iocd-cli", "assets", "components", "config", "modifications", "temp". They only serve your local runs, be sure to add them to .gitignore.

2) Set components-> usePrereleases: true in <project>/config/iocd.cli.config.json for the system to install early releases. These pre-releases are not official! Only use this when you are sure you need an early release.

Using custom iocd store (mirroring)

By default, running yarn setup-iocd attempts to download the iocd component from the interop.io CDN.
If it is blocked in your organization, you need to maintain your own copy.

1) Manually download the iocd-v{version}.win32-x64.zip specified in section io.CD Version.

2) Add a field installer.iocdInstaller in your project.json file. > Alternatively, you can set the environment variable IOCD_INSTALLER to your url or path. This can be accomplished by creating a .env file at project root which contains IOCD_INSTALLER="xxx".

a. if your zip is in local file system:
```
"installer": {
    // Set the path relative to your project root, or use absolute path
    "iocdInstaller": "./iocd-v10.0.4.win32-x64.zip"
}
```

b. if your zip is hosted on remote url:
```
"installer": {
    // For HTTP basic auth, you can set "https://username:token@yours/iocd-v10.0.4.win32-x64.zip"
    "iocdInstaller": "https://yours/iocd-v10.0.4.win32-x64.zip"
}
```

c. if you need to install multiple components:
```
"installer": {
    "iocdInstaller": {
        "iocd": "https://yours/iocd-v10.0.4.win32-x64.zip",
        "bbg": "https://yours/bbg-v3.0.8.zip"
    }
}
```
or with environment variable `IOCD_INSTALLER='{"iocd":"https://yours/iocd-v10.0.4.win32-x64.zip","bbg":"https://yours/bbg-v3.0.8.zip"}'`

3) Run yarn setup-iocd to finish setup. It will now pick your zip and generate the corresponding iocd.cli.config.

Running your project

Use yarn iocd, yarn start-iocd, or yarn start --iocd to launch your project using the io.Connect Desktop (iocd) container.

...or...

Use yarn dev-iocd or yarn dev --iocd to build and launch your project.

Note: You can continue to use the legacy commands yarn start and yarn dev to launch or build your project using the legacy FEA container.

Building deployable installers for your end users

Run yarn makeInstaller-iocd

The makeInstaller command generates a build in the output directory, which by default is <project>/pkg. For example, the Windows zip bundle will be generated in <project>/pkg/zip/win32/x64.

Note: Running makeInstaller-iocd will automatically trigger setup-iocd, this is to ensure that the build uses the latest project.json.
In case you wish to skip some setup, this command also supports arguments --skip-install, --skip-config and --skip-assets.

Specify your installer types

By default Finsemble cli uses below makers, so iocd build will generate several kinds of bundle:

makers: [
    {
        name: '@electron-forge/maker-squirrel',
        config: { loadingGif: "assets/install.gif" }
    },
    { name: '@electron-forge/maker-zip' },
    { name: '@electron-forge/maker-dmg' },
]

If you encounter problems with the ones you do not need, specify your target maker in project.json:

"installer": {
    "iocdBuildMakers": [
        { "name": "@electron-forge/maker-zip" }
    ],
    ...
}

Using auto-update

io.Connect Desktop, like Finsemble, uses Squirrel to manage auto-updates. If you specify updateUrl in the project.json installer config, the polyfill CLI converts this into io.Connect config for "StaticStorage". The updateUrl should point to the location of the RELEASES and .nupkg files. For example, if you specify the installer.outputDirectory in the project.json to be ./public/updates, you would then need to set the updateUrl to be /updates/squirrel.windows/x64. The updateUrl only needs to point to the folder where the RELEASES and .nupkg files are located. Run yarn makeInstaller-iocd to generate the installer EXE, RELEASES and .nupkg files. When Finsemble on io.CD starts, it checks the updateUrl, reads the RELEASES file, and determines which .nupkg file should be downloaded and applied. If there is an update, it is downloaded and applied, and the user will be notified to restart their application to start using the update.

Documentation

io.Connect Desktop Documentation

Finsemble Documentation

Terminology changes

"Workspaces" -> "Layouts" - In iocd, a "global layout" refers to the arrangement of windows and their data context which may be saved/restored and saved by name. The term "workspace" now refers to aggregated groups of windows, a new feature.

"Toolbar" ~= "Launcher" - In iocd, toolbars are sometimes referred to as launchers. The latest Finsemble Toolbar is fully compatible with iocd. This is sometimes also referred to as a "shell" in iocd terminology.

Usage

• FSBL API is fully functional.
• The io.Connect Desktop API is fully functional. You can import * from "@interopio/desktop" in your apps, or you can use the iop global.
• FDC3 is fully functional (window.fdc3 object).
• Toolbar, dialogs, and system tray are fully functional. If you've customized these components then your customizations should be functional (WindowTitleBar is not compatible. See below.)
• Window operations such as tabbing and grouping operate slightly differently (better) than Finsemble
• Apps specified in apps.json or loaded using any FSBL API will work as expected. iocd config values may be used by placing an "iocd" hostManifest in the entries.
• Authentication (SSO) should be fully functional, including "dynamic config" (loading apps based on user login)
• Your theming/CSS customization should be fully functional.
• Generating installers is fully functional.
• For .NET, use the latest finsemble.dll with "iocd" tag. With this new DLL, your .NET apps will automatically be compatible with both the new platform and with legacy Finsemble. (They will attempt to connect to iocd first, and if they cannot connect within 5 seconds then they will instead connect to any running Finsemble instance.)
• Workspaces and preferences in storage adapters will work seamlessly with the polyfill.

Java

Java has a new Maven deployed artifact, finsemble-10.0.0-jar-with-dependencies.jar (actual version name may change), which contains all required dependencies in one large JAR file. This is ideal for a drop-in replacement to include all dependencies, including the Glue classes.

This is a list of Java methods available for use in an IOCD environment. - AuthenticationClient - getCurrentCredentials(CallbackListener callbackListener) - publishAuthorization(String user, JSONObject credentials) - LoggerClient - Full functionality - RouterClient - addResponder(String responderChannel, QueryCallbackListener queryCallbackListener) - removeResponder(String responderChannel) - query(String responderChannel, JSONObject queryEvent, JSONObject params, CallbackListener responseEventHandler) - query(String responderChannel, String queryEvent, JSONObject params, CallbackListener responseEventHandler) - query(String responderChannel, JSONArray queryEvent, JSONObject params, CallbackListener responseEventHandler) - addListener(String channel, CallbackListener eventHandler) - removeListener(String channel, CallbackListener eventHandler) - transmit(String channel, JSONObject event) - transmit(String channel, JSONArray event) - onReady(CallbackListener cb)

What will you need to change?

• Finsemble's NotificationsCenter and NotificationsToasts components will no longer be supported under iocd. To customize notifications, enable the single component "IOCDNotifications" (yarn template IOCDNotifications) which will enable a single app that renders both toasts and panel. You can then re-implement any customizations using iocd's "extending notifications" capabilities.
• The WindowTitleBar component will no longer be supported under iocd (which uses a different windowing paradigm than Finsemble). If you've customized the WindowTitleBar then you will need to re-implement those changes using the new DecoratorWindow template (yarn template DecoratorWindow). This uses iocd's "extensible web groups".
• If you customized Finsemble Intents Resolver UI, it is not compatible with io.CD. It needs to be reimplemented using the Resolver template (yarn template IOCDIntentsResolver). The template inherits the default io.CD resolver, details can be found in Data Sharing - Intents.
• If you wish to customize the io.CD Download Manager UI, use the Download Manager template (yarn template IOCDDownloadManager). The template uses the IODownloadManager components from @interopio/components-react, allowing you to override individual sub-components such as Header, Item, Settings, etc. See Rebranding io.Connect UI for details.
• If you wish to customize the io.CD Channel Selector UI, use the Channel Selector template (yarn template IOCDChannelSelector). The template uses the IOChannelSelector components from @interopio/components-react. The channel selector supports multiple variant modes including single, multi, and directional. See Channels Overview for details.
• The advanced app launcher is functional but if you've customized any of the underlying code then it may need to be re-implemented. Please check and let us know if you find anything not functioning.
• Your splash screen image may be smaller on io.CD than it was on Finsemble. This is due to how the two systems interpret screen resolution. You'll need to create a larger image if this is a concern. Please note that io.CD now supports interactive splash screens. You can see an example of this behavior when you run the copy of io.CD that we provided. see installer section below
• Your installed icon may be rendered smaller than expected. To solve this problem you can create a 128x128 icon and save it as io-connect/installer/assets/icon.ico. see installer section below
• io.CD does not support moving images on the installer dialog. You may need to create a static image and you may need to resize that image in order to have the best appearance. You can save such an image to io-connect/installer/assets/banner.gif which will