The Protocol Handler

Protocols are a way for a link to "raise their hand" and ask for help from another application. Finsemble registers as a protocol handler using fsbl://. When a user clicks on this deep link, Finsemble will open and handle that link. For example, an end user can launch a Finsemble component from a link in an email or chat message.

The protocol fsbl:// is registered with the Windows operating system each time Finsemble is started and points to the version of the application that was last started. You can see the currently registered Finsemble version in the Windows registry under Computer\HKEY_CLASSES_ROOT\fsbl\shell\open\command.

Whenever a link that starts with fsbl:// is clicked—from email, chat, desktop shortcut, or other method—the operating system will start Finsemble and pass this data to Finsemble's main process. If Finsemble is already running the protocol handler URL is passed to the running instance, which will generate an event you can listen for.

Getting started

Whenever a user clicks a link that starts with fsbl://—from email, chat, desktop shortcut, or other method—the operating system will start Finsemble (if it's not already running) and pass this data to Finsemble's main process. For a simple example, let's just open Finsemble using the protocol handler.

First, if you haven't run Finsemble on your machine before, install it and run it once. Finsemble must have run on the machine, so that it can register the fsbl:// protocol. Quit out of Finsemble to continue this example.

In a browser, go to fsbl://custom/. This is the equivalent of clicking Finsemble's .exe file, and you will see Finsemble come up. You don't even need a browser; you can use a file browser (Windows Explorer or Finder), Window's Run dialog, or CURL to call this protocol.

Now that you've seen Finsemble's protocol handling in action, let's see how apps can handle deep links to perform custom actions.

Using the protocol handler

Finsemble URLs adhere to the URI generic syntax. Finsemble URLs that you define must be specified with "fsbl" in the scheme field and "//custom" in the "authority" field, as shown in the following example.

 fsbl://custom/pathA/pathB?name=doc7#section4 
 \__/   \____/ \_________/ \_______/ \______/ 
scheme authority  path       query   fragment

You define the rest of the URL (i.e., the path, query, and fragment) to meet your own specific business requirements.

Correct:

fsbl://custom/channelData?group1={symbol:APPL}
fsbl://custom/myAwesomeTestString

As long as the URL adheres to the basic format fsbl://custom, the rest of the URL can be defined however you want.

Incorrect:

fsbl://workspace/
fsbl://custom.myco.com/

The authority field must only be custom. No action will occur with either of these examples since it does adhere to this schema.

Note: A custom service, that starts in the microkernel stage or later, is the proper place to perform startup tasks for your protocol handler.

Listening for protocol events when Finsemble is not running

A packaged installation of Finsemble provides a mechanism for running Finsemble to handle a protocol event. If Finsemble has been installed and has started at least once, when an end user clicks a fsbl:// link, Finsemble can start and handle the protocol event.

FSBL.System.getProtocolString() (in an app or component) or Finsemble.System.getProtocolString() (if you imported @finsemble/finsemble-core as Finsemble in a custom service) will always return the protocol string that was passed through on Finsemble's startup, or an empty string if Finsemble was not started via teh protocol handler.

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

...

Finsemble.System.getProtocolString((protocolUrl) => {
	Logger.log(`Protocol handler URL received on startup: ${protocolUrl}`);
});

Note: The initializeDeepLinkingTask service gets the protocol string passed through to Finsemble and logs it to the Central Logger for debugging purposes.

Listening for protocol events when Finsemble is running

If Finsemble is already running, to receive the protocol handler URL you will need to add a listener for the protocol-handler-triggered event. This will allow your smart desktop to listen to and react to protocol events.

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

...

Finsemble.System.addEventListener("protocol-handler-triggered", (protocolEvent) => {
	Logger.log(`Protocol handler URL received on while running: ${protocolEvent.url}`);
});

Finsemble registers as a protocol handler and will open and handle deep links in this format: fsbl://custom/pathA/pathB?name=doc7#section4.

What to look out for

Finsemble only registers protocol handlers after it's been installed and run. If you're working as a developer within a seed version of Finsemble, calling the protocol may result in no action, or an error message. If you find yourself in that situation, build and run an installer for your seed project.