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.

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.

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.

The initializeDeepLinkingTask service gets the protocol string passed through to Finsemble and logs it to the Central Logger. FSBL.System.getProtocolString() will always return the protocol string that was passed through on Finsemble's startup.

FSBL.System.getProtocolString((data) => {
	Logger.system.debug(`initializeDeepLinkingTask startup ${data}`);
});

This is the first task that starts in the microkernel stage. This is the proper place to perform startup tasks for your protocol handler.

Listening for protocol events when Finsemble is running

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

FSBL.System.addEventListener("protocol-handler-triggered", (data) => {
	console.log(data.url);
});

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

Further reading

More information about Finsemble's lifecycle events can be useful for understanding startup.