This tutorial provides a holistic overview of techniques that will allow you to quickly iterate with Finsemble. If you are in need of targeted support, check out Troubleshooting.
If you're encountering any bugs, please first make certain that you're using the latest version of Finsemble. You can ascertain this through package.json in ../node_modules/@chartiq/finsemble/package.json.
To update the underlying Finsemble framework, run the following commands from your local repository directory:
npm update @chartiq/finsemble
To update the Finsemble CLI, run the following commands from your local repository directory:
npm update -g @chartiq/finsemble-cli
Due to a bug with Gulp 4.0,
npm update will not update Gulp correctly. If you need to update the entire package you will need to follow this procedure:
rmdir /S node_modules npm cache clean npm install npm install -g @chartiq/finsemble-cli
Finsemble runs on top of a Chromium container system. Chromium contains the same debugging tools that you are used to in Chrome. Press CTRL+SHIFT+I to pop up Chromium's debug tools in a new window. You can also hit CTRL+ALT+D on any window to open the debugger.
An alternative debugging method is to open a browser and navigate to http://localhost:9090. Each window in your application is listed on that page. Click on the window you wish to debug and a Chromium debugger will be launched for that window. There are some limitations (e.g., you can't evaluate code in the console in a remote session), but it largely acts as you would expect.
When you open your component code in the debugger, you will see that it has been wrapped in a containing function. Finsemble uses Webpack as part of its build process. This provides automatic isolation of modules, automatic building of React modules, etc. For the purpose of debugging, you can simply ignore this wrapper. Place your breakpoints inside your code and it should behave as expected.
You can modify the Webpack config files, if necessary, for your own component and service code (for instance, if you are using a framework other than React). For more about the build process, see the Build Process tutorial.
The Finsemble Library (
FSBL.js) is automatically injected into Chromium using OpenFin's "preview" capability. This conveniently allows you to use Finsemble on any page without having to explicitly include the library. Chromium can be persnickety about debugging inside of such files (VM files). To get around this, you can manually include FSBL.js with a script tag:
It isn't necessary to completely quit the application between program iterations. The dev runner automatically watches for code changes and repackages on the fly. Once you make a change and save your code, simply reload the component by right-clicking in the component and choosing "Reload." You can also press CTRL+ALT+R to reload the window that you're focused on.
As you work on your test application, the application state will be saved to the
activeWorkspace. If you need to start from scratch, you can delete this workspace. By default, workspaces are stored in Chromium's
localStorage. To delete
localStorage.clear() in the console. If you prefer a more surgical approach, follow the steps below:
localStorageentries that begin with "Finsemble_". This will include
Finsemble_linker. You can delete these by highlighting the entry and then pressing the "X" in the debugger's footer.
Be sure to quit your application without changing the location of any windows! You want to be sure that a new workspace isn't saved before you quit.
For super fast clearing of
localStorage.clear()from the debugger console. Be careful though, because this will clear everything, including
localStoragefor other Finsemble or OpenFin apps on your computer.
You can delete the OpenFin cache to reset the state of your application.
Note: This will also delete the
localStorage for all of your Finsemble applications!
Hitting CTRL+C in your command prompt on your npm run process kills the application immediately. If this action is taken, it's possible that Finsemble may not have had time to save recent workspace changes. In general, choosing Quit in the toolbar will avoid state issues.
npm run devdoes nothing
npm run dev does nothing and the runtime is hung, it may be because you have zombie OpenFin processes. This can occur, for instance, if you kill off the dev runner before the application has properly started.
To get back to a good state, open your Windows Task Manager and kill any "OpenFin" processes, found under "Details," that are running. You will need to stop AssimilationMain.exe as well. You should then be able to start the dev runner again. You may also delete your OpenFin cache (see above) to solve this issue.
OpenFin has a bug where content cannot be hosted from different ports on the same domain, which prevents
fin) from being injected. We use localhost:3375 to host the content for the Finsemble seed project environment. If you are hosting other content from localhost through a different port, Finsemble's window title bar will not appear. To solve this issue, use an alias for localhost (127.0.0.1) or an address for the computer that will resolve.
If the toolbar is up, you can use the Central Logger to view the complete manifest containing Finsemble's configuration. First, bring up the Central Logger and ensure all service and component logging is visible by clicking on "Toggle All." Next, enter "processed manifest" into the "Filter Log" box (as opposed to the "Filter Client List" input box). The filtered log entry includes the complete run-time manifest with Finsemble's complete configuration under the
For this case, the data shown is after configuration has been fully processed on startup (e.g., macro's expanded, configuration files imported) but dynamic configuration changes haven't taken place yet. To see configuration after dynamic configuration changes, filter logs using "revised manifest" to get the revised configuration object.
In this scenario, Case 1 instructions might be useful; however that data may or may not exist depending on where start-up failed. Therefore, a third log filter, "initial manifest," is available to show the bootstrap configuration, which is the minimal initial configuration pulled from the manifest and Finsemble's core configuration in order to start the essential Finsemble services.
If neither the toolbar or the Central Logger are available, configuration can be seen using the Chromium console through http://localhost:9090. If the Config Service exists, it's console's output can be filtered using "processed manifest". However, that data may or may not exist depending on where start-up failed.
A more reliable option is to go into the "ServiceManager" window using http://localhost:9090. Click on the
Central Logger entry and enter the command
showConsole(). Filter on "initial manifest" to see the bootstrap configuration.
For all cases above, OpenFin console's or Central Logger's log should also be inspected for configuration-related error messages (by turning off filtering and enabling only error messages).
If field support is needed with debugging, see the Troubleshooting tutorial.
The Central Logger is a great tool for diagnosing problems across multiple windows. Check out the Central Logger.