Deep Linking and the Thick Client
Tuesday, September 22, 2020 2:21 PM


FocalScope thick client v2 provides workflow/automation capability via so named deep linking. "Deep linking" is a usage of a custom URL scheme to navigate to a specific page/window or to execute a certain action within the thick client.


The thick client associates itself with the focalscopeclient: protocol.


By launching URL that begins with this protocol you instruct the thick client to do an action on behalf of the logged user. This means the deep linking works only when an user starts the program and log into own FocalScope account. Otherwise launching URL just starts the program and does nothing.

How to launch an URL

Launching URL can be done programmatically by calling a function from following families

ShellExecute...() family on Windows or
NSWorkspace.open(_ url: ...) family on macOS.

Look into a runtime API of your programming language to find how to do this.

Also you can launch URL from a command line via

-   start "" "focalscopeclient://..." in cmd.exe on Windows or

-   Start-Process "focalscopeclient://..." in powershell on Windows or
-   open "focalscopeclient://..." in the shell on macOS.

As the last resort you can run the client executable directly with --xurl parameter like:

-   "C:\Program Files\FocalScopeDesktop2\FocalScopeDesktop2.exe" --xurl "focalscopeclient:..." on Windows or

-   /Applications/FocalScopeDesktop2.app/Contents/MacOS/FocalScope --xurl "focalscopeclient:..." on macOS.

Format of a deep link URL

The deep link URL is divided on two parts: instance selector and action with parameters.

focalscopeclient://instance-domain/instance-path/action-path?parameter0=...&parameterN=...

Instance selector

Instance selector consists of instance domain and instance path; the instance path can be empty. The selector chooses an instance which URL equals to the instance-domain/instance-path part (without `http[s]://` prefix). You can see the instances URLs in the client "Options" page.

For example:

-   focalscopeclient://fstest.focalscope.com/emm/... matches https://fstest.focalscope.com/emm instance

-   focalscopeclient://acme.focalscope.com/... matches https://acme.focalscope.com instance

But for most cases you should use a default instance selector. It consists of the single-word "default":

focalscopeclient://default/action-path?parameter0=...&parameterN=...

The default selector chooses the default instance. The default instance is an instance with dot mark on the left in the list of instances at the "Options" page. You can change default instance via the "vertical dots" popup menu in the corresponding row.

If the default instance is not defined and the instances list contains only a single instance then the default selector chooses this single instance.

Action

Action consists of an action path that has the action name and an URL query that represents the action parameters. Meaning of parameters depends of the action.

Supported actions

/quick-search

This action does a quick search like the quick search control on the toolbar.

.../quick-search?nCId=<search-type>&varVal=<search-value>

Here is table that defines search types and the meaning of search value

Search typenCIdvarVal
ticket #1205ticket number
email body1202text to search in the email bodies
email note1253text to search in the email notes
email #1248email number
email address1250email address
live chat #1252live chat number
global notes1209text to search in the global notes
dial1207number to dial


Examples:

  • dialing to '999777' in the instance 'test.focalscope.com'

    focalscopeclient://test.focalscope.com/quick-search?nCId=1207&varVal=999777
    
    
  • searching for a ticket '60783' in the default instance

    focalscopeclient://default/quick-search?nCId=1205&varVal=60783
    
    
  • searching for emails with note containing text "happy pdfs" in the instance "acme.focalscope.com"
    focalscopeclient://acme.focalscope.com/quick-search?nCId=1253&varVal=happy%20pdfs
    ​