Legacy version 6 documentation. View current documentation.Legacy version 6 documentation. View current documentation.
Before you can use Finsemble in your enterprise, you need to implement it and then deploy it. This is a process, and it takes some steps.
We don’t guide you through this process step by step here, but rather, we present the learnings we gathered from helping other companies with their own specific Finsemble deployments. The best practices presented here come from our experience and are field tested. We share them here to help you learn from others to navigate through this process for your company.
Deploying Finsemble will be an investment of time and resources. Therefore, it’s best to plan carefully. The advice we present here will help.
You chose to implement Finsemble. Congratulations! The first step you need to take now is to set up your Finsemble project.
You need to give your project a name early, ideally as soon as you know the project is moving forward. The name will help you talk about the project and gather support for it, so pick one that is not controversial and is easy to pronounce.
Because you will be deploying Finsemble and you probably think about the project using our product name, it’s tempting to just call it that. But we recommend that you pick a different name that is specific only to your organization for a very important reason: Finsemble the product is separate from your specific Finsemble deployment and it’s helpful to keep these two separate. The Finsemble code is aimed at various enterprises and different clients. In contrast, your specific project will be a customized internal implementation that is aimed specifically at your own organization. Therefore, we recommend that you call it something that is specific to your enterprise. Having a name that differentiates your project from our product helps the stakeholders and the developers keep this distinction in mind.
At the early stages you can use a codename, such as Triton or Denali. But later, when you’re close to deploying, it’s best to replace the codename with the official name that your org will use for the lifetime of the deployment. The best name resonates with the organization, says or hints at what the project does, and is generally recognizable as a platform name. The name Triton (or Denali, or whatever you picked as your codename) isn’t appropriate because it doesn’t indicate what the new platform does. So, rename it to something meaningful to the users, such as “Markets desktop platform”.
The bigger and more complex your organization, the more likely it is that your Finsemble deployment will need a lot of customizations. To manage them, you need a project team of various specialists. We recommend that this team is cross-functional, and consists of standard product development specialists. These include devs of course, but also UX, QA, product, and possibly others. The members of this team will become your experts on Finsemble.
This core group will:
All these tasks, when performed well in a timely manner, allow app developers from contributing teams to focus on the content, functionality, and integration of their components into the Finsemble project rather than them spending time trying to figure out how their work will fit into the overall framework. This reduces time to delivery, and makes adding new apps much easier.
Many organizations have multiple dev teams. It is likely that these teams will want to be involved, at least in developing apps that will work with Finsemble. For practical reasons it’s impossible to invite everyone to your project team, and you definitely don’t want them to change the base code of Finsemble behind your back. On the other hand, you don’t want to shut them out. So what to do?
We recommend that you communicate with them early on about the advantages that Finsemble offers, and that you show them the benefits of desktop interop. They can participate in the interop easily if all their apps follow the FDC3 standard. For very large organizations with many large dev teams, it might even be a good idea to have a company-wide learning initiative that covers interop and FDC3. One good resource is Interoperability for a financial desktop.
The project team might be distributed geographically, but they need to work together comfortably. To make sharing easier, we recommend that you use a centralized repository that will contain the main project, accessible by all members of all teams. This repository will make it easier for developers to work locally, wherever they physically are.
This repository provides the infrastructure for creating builds and installers for local deployment, staging, and testing. Here are some tips about this repository:
Now that you set up the project, you can get it started. Here are some tips on how to manage it successfully.
We provide you with a detailed up-to-date Getting started tutorial to help you get going quickly with Finsemble. We also have guidance about design, deployment, and maintenance, so take advantage of all this information.
Our documentation is by necessity general, and your Finsemble implementation will be customized to your specific needs. Therefore, it is a good idea to create your own documentation about the project that describes the decisions your project team has made and the reasons behind them. Document everything that you think might be helpful. It’s better to have too much info than too little.
As new people join the team, it will be easier for them to understand the project. It is also good to note the reasons for the decisions, as it’s easy to forget later why you chose a particular option. Finally, thorough documentation can help prevent misunderstandings between different team members, and also between the design and the implementation teams.
In our experience, the clients who document their decisions well and who provide clear instructions to the developers working on their projects are the most successful. The reason is that without proper documentation and clear communication, you risk your team coding in silos, which almost certainly will deviate from standards you have established.
Real-world example
One of our clients put their implementation-specific docs into a Confluence site that could be loaded into a component. That same client allowed test code to be used right from the documentation component (for example for sending or validating test messages).
Before you begin designing your Finsemble implementation, you need to gather requirements. Make sure you allow enough time for this step. To do so, you need to examine your use cases. We recommend this process to be thorough and iterative. We also suggest that you involve various stakeholders from different teams. Most of all, make sure that your actual smart desktop users are well represented.
As you analyze your use cases to gather requirements and analyze them, you will likely find that there is still more to learn. Follow the iterative process until you are sure you fully understand the various requirements for each workflow and each app within it. Some requirements might conflict with each other. If that happens, you need to resolve the conflict before you can move forward. Don’t forget that the best solution might not be a choice between two options, but rather a creative approach that solves the problem in a new way.
Here are some considerations:
Gathering this information early and thoroughly reviewing it for completeness and accuracy will help you not only with the coding part of your project, but also with the UX and interop decisions.
As you work through the requirements, our client success team is available to you to help with the reviewing, and the implications of your choices, in greater depth.
We at Finsemble are great proponents of reuse. After all, if you already have a component, service, or preload, you can reuse it with minimal work. This not only speeds up the development but also reduces maintenance costs.
Build services and preloads for functionality that will be used in multiple components or by multiple teams. We are here to help you with architecting and planning such a solution.
This approach uncouples the implementation of the service or other functionality from the components so they can be updated independently. In other words, there is no need to rebuild all of the components because you added something to or fixed something within a service or preload.
We will work with you early in your project implementation and help you architect your project and complete technical design, especially for:
In any complex technology, there are multiple ways of doing things. This is particularly true for Finsemble, because it is a container technology, and therefore it is more like a browser than like a web app framework. So there will be multiple options to consider, and you will choose the one that works best for you. If at any point you have trouble deciding, the client success team can help you think through your options. The ultimate decision is up to you. Don’t forget to document why you made those choices, so that down the road your team won’t have to revisit and relearn what you already did.
You will likely discover that the same or similar code will be used in multiple components. If possible, generalize this code to develop a Finsemble preload or service. This way, you don’t need to write and maintain multiple instances of similar code. Removing duplication saves time, money, and avoids maintenance headaches.
When you plan preloads and services, consider whether you can reuse them in multiple components. Look to other teams for the possibility of reuse as well. Reusing code makes the development faster and cheaper for them too.
Separating components from the service or other functionality provides you with more flexibility and makes it possible to update them separately. If you need to add or fix something in a service or a preload, you can do so without having to update and redeploy the component that relies on that service or preload.
If you’re using the same message formats in multiple components, create a test component to send and receive these formats. This way, you can simplify development and testing,
The typical functionality that can be separated this way includes:
Tip: Carefully keep track of any customizations to Finsemble built-in functionality and UI. One good way to do this is to use good code comments.
Real world example
When multiple components need to integrate with a 3rd party service or API, such as Salesforce or Google Tag Manager, and either that API changes or how you work with it changes, you would need to update the relevant code in every component that interacts with it, and redeploy each component. To avoid unnecessary work, one of our clients created a service that interacted with that API for them and, after changing providers, they were able to swap out the API for a different product, redeploy the service and effectively migrate all components that use it in a single step.
If you need help with architecting your solution, the Finsemble team can work with you to design the appropriately flexible solution.
It might be tempting to release and later to update the entire ecosystem at the same time. But we recommend that you keep your releases separate. So, release your apps when they are ready, and release your Finsemble implementation at another time, either earlier or later. This way, it is less disruptive to your enterprise. In our experience, by keeping your releases separate and independent of each other rather than commingling them you also allow for more scalability in your enterprise. Because Finsemble is config-driven, we can keep our API stable, which makes the decoupling possible.
If you have architected for reuse, you are already working towards this decoupling.
Testing your Finsemble code in a development environment is useful, but it won’t find all the issues that your users will face. That’s because a dev environment is not the same as a real life deployment. To catch real life issues before deploying Finsemble to your users you need to also test it in an environment that is as close to the real deployment environment as possible. This way, you can catch any potential issues before the users do, making the transition run much more smoothly. You will also use this testing environment later, to perform repro steps for user issues, and to test your updates before you roll them out.
It is not always possible to replicate the user setup exactly, but the closer you get to it, the more reliable your testing will be.
To create a realistic testing environment, consider these items:
Setting up a test environment could be complex, but there is help. You can bootstrap the start of a test automation framework with our free code example, which integrates the Selenium WebDriver with Finsemble. Use it as a starting point to bootstrap your own automated testing, but keep in mind that this sample is not a part of our product and is therefore not supported.
As any software, Finsemble is constantly changing, undergoing iterative improvements. You will need to upgrade at some point, and it will go a lot easier if you plan for it. To access the most recent features, and to get updates and bug fixes, we recommend that you keep your Finsemble installation current.
Like many software companies, we frequently release minor versions, and we release major versions less often. We limit breaking changes to major releases only. When we must introduce a breaking change, we provide detailed migration instructions, and we’re available to answer any questions you might have. We aim to make the updates as painless as possible. Still, it is a good idea to dedicate some time in your product build cycle to accommodate at least the major version upgrades and also the upgrades that add functionality you need.
We recommend that you nominate one person on your team to be a liaison with the Finsemble team. We affectionately refer to such a person as your “upgrade czar”. Encourage them to keep in touch with us on a regular basis to manage upgrades. This person will also receive our product release announcements so they know what’s coming and can communicate the im=nformation to your product team.
The Finsemble code changes with every release. We add new features, and sometimes we need to also remove features for various reasons. Don’t worry, we won’t surprise you with a sudden feature removal. We clearly mark the deprecated features in our documentation and list them in the changelog. We keep them around for at least one more release, often longer. If you are using such features, have a plan for when these features become obsolete and are removed from the product. Follow our guidelines to replace them with newer solutions.
For new features, we mark some of them experimental. Go ahead and use the feature, but be aware that it’s possible such a feature might not be a permanent addition to Finsemble, or it could change significantly in the future.
Important: We strongly recommend that you don’t customize or modify the Finseble source code. The reason is that such code customizations make upgrading far more difficult than it otherwise would be. Also, your customizations might make it impossible for you to follow our upgrade instructions. If you find yourself contemplating modifications to Finsemble source code, talk to the customer success team first.
We do our best to provide accurate upgrading instructions but it’s impossible for us to predict all the paths that our customers can take. If you run into a difficulty while upgrading, contact our customer success team at your earliest convenience.
We already looked at this issue in the deployment context, but it applies to upgrading as well. We strongly recommend that you decouple the releases of apps within Finsemble from the releases of Finsemble itself. By keeping these two separate, you are more in control. This approach has proven far more scalable at the enterprise than keeping these two types of releases dependent, and is one of the key benefits of web deployment and Finsemble's declarative, or config-driven, approach to assembling smart desktop applications. We keep Finsemble's APIs stable, and our preload-based approach to making those APIs available to your code is specifically designed to make such decoupling possible.
Deploying the software is one part of rolling out the project. You also want to make sure that your users are ready for a smart desktop. In addition, you might run into issues while deploying Finsemble. This section helps you with these considerations.
When you plan your first deployment, the idea of a smart desktop could be new to your users. To help them get productive quickly, you need to come up with a training plan. We have a user guide that you can customize to fit your needs. You can add this guide to your welcome component that displays text and links to training videos. This way, each user can learn at their own pace.
Some upgrades will affect end users, and many of these users hate surprises. To minimize disruption, you need to plan your communication and training, and keep your users informed both about what’s coming, and what specific changes you’ve made that affect them.
Real world example
One effective way to communicate changes is by using a “What’s new” component that automatically appears to the users after each upgrade. In our experience, sharing info this way works better than external release notes to those users, because many users don’t read them, but will read the What’s new component when it’s right there in front of them.
Ideally, you want to minimize the need for troubleshooting. The best way to do this is to work with the Finsemble Client Success team from the beginning and throughout your project. We strongly recommend that you share your deployment schedule and milestones with us. We can meet with your engineering team to help them plan the deployment. And just as importantly, we can arrange for a member of our customer success team to be available for any questions and troubleshooting in real time. This way, you get help immediately, way faster than our SLA times, at the time when you need help the most.
We hope your deployment goes well, but sometimes you might need to do some troubleshooting. Finsemble logs the issues it detects, and you can examine this info in the Central Logger. For this reason, the Central Logger is a good place to start your investigation. You might also want to integrate these messages with your internal log capture, such as Splunk or Kibana. The best way to do this is to use the Logging Service Export code example, which captures messages of specified categories and levels and transmits them to a remote API in batch.
Another way to gain insight into your deployment is to use analytics for components, buttons, or other CSS tags that users interact with. Also collect any JavaScript error reporting. To add this capability, use the Google Tag Manager recipe. We have integrated this recipe with Google Analytics, and you can also work with your favorite analytics tool.
We’re ready to help anytime you need us, at any stage of your Finsemble deployment. If you find a feature or a configuration you wish Finsemble supported but it currently doesn’t, let us know. Chances are, other customers also need it, and it might even already be available. We have examples from years of supporting clients, and for some of them we might have already found a solution for a similar problem. If we don’t have a solution yet, we’ll happily work with you to create one.
For us to be able to help you, you need to share your relevant use cases in detail. We will then use our experience to identify a solution that follows Finsemble best practices.
We strongly recommend that you don’t modify the source code from NPM modules, especially Finsemble Electron Adapter (FEA). If you think you absolutely need to make such a modification, we strongly suggest you contact us to discuss the changes you want to make. We will analyze your goals behind those changes, and in most cases we can find or create a code example or recipe that will meet your goals. If that’s not possible, we can enter it into our backlog to be prioritized.
Real-World Example One of our clients wanted to make changes to FEA to enable a PDF viewer in Finsemble and planned to modify the handling of JavaScript window.open() API calls in FEA/Electron to do so. Because they spoke with us first, we were able to supply a code example using Finsemble’s best practices and delivered it to them within 48 hours of the request. They got the functionality they needed, with quick turnaround, and without risking complications to future FEA upgrades or affecting the security of their solution.
Even if you don’t have any specific product requirements for us, we recommend that you stay in touch with us regularly. In addition to regular technical project meetings with the Finsemble client success team, you should meet with our solution architect and the chief product officer. We found that the best cadence for these meetings is at least monthly at first, and later, when you’re ready, we can meet quarterly to share roadmaps. This way, we learn about your vision, and you can give us feedback that can help shape our future product direction.
We have a strong track record of prototyping features based on client requests, which then our engineering team quickly integrates into the product.
Here are some examples:
We take product collaboration seriously. Your insights are incredibly valuable, and we truly want you to succeed. Start talking to our Client Success team early on, or at any point in your smart desktop journey. We would be happy to explore any of the deployment strategy topics.