Using Deeplinks

Owned by Jay Crouch (Unlicensed)
Last updated: Mar 22, 2024 by Mike Piska
5 min read

Deep links can be used for launching catalogs, scenarios, the contact list, or a call to a specific user. The Deep link URL can be retrieved from CMS and then used to launch the app with the appropriate action.

In addition to performing the actions for that deep link, users can add additional data from a third-party system by adding extra parameters to the URL.

In this article

Deep links are essentially special URLs that can be used to launch the Worklink App from a device:

worklink://resource?action=fetch_catalog&catalog=123456

This is an example of a catalog deep link. Other types of deep links would have different action parameters and supporting parameters for that action.

Lets break it down:

  • worklink:// - The first part of the Deep link is the scheme. This worklink scheme refers to the Worklink App. Devices with the Worklink App installed recognize that URLs with this scheme will mean that the device should launch the Worklink App when this URL is clicked on, instead of going to a new web page. For links that will also work when the app is not installed see

  • resource - This is the domain and is required for all URLs. In this case, it used to ensure that the URL is structured correctly and recognizable to the Worklink App.

  • ? - Everything after the ? question mark are called query parameters and will be used by the Worklink App to do different things.

  • action=fetch_catalog - The Worklink App will need an action query parameter present to perform actions. The values of this parameter can be changed to perform that action. In this example, it will be fetching a catalog to display in the Worklink App. There are other actions that can be taken and will explained in the next section.

  • & - The & ampersand symbol is used to delineate different query parameters. This could also appear as %3D when it is URL encoded.

  • catalog=123456 - Each defined action would require additional query parameters in order for the Worklink App to correctly perform the action. In the case of fetch_catalog , the Worklink App needs the id of the catalog to retrieve. In this example, the catalog id is set to 123456.

Fetch Catalog

Will open a catalog in the Worklink App. Any additional query parameters added to this Deep link will be treated as external data and attached to any scenario sessions that are created from the opened catalog.

Query Parameter Values

  • Action: fetch_catalog

  • Resource Key: catalog

  • Resource Value: The ID of the catalog.

Example: worklink://resource?action=fetch_catalog&catalog=123456

Fetch Company Contact

Used to display the company contacts in the Worklink App. Any additional query parameters added to this Deep link will be treated as external data and attached to any call sessions created from this contact list.

Query Parameter Values

  • Action: fetch_company_contacts

  • Resource Key: company_contacts

  • Resource Value: The permalink of the company.

Example: worklink://resource?action=fetch_company_contacts&company_contacts=jedi_order

Fetch User

Used to initiate a call session in the Worklink App. Additional query parameters will be added as external data to the call session that is created.

Query Parameter Values

  • Action: fetch_user

  • Resource Key: user

  • Resource Value: The username of the user to be contacted

Example: worklink://resource?action=fetch_user&user=lukeskywalker

Fetch Scenario

Used to create a new scenario session in the Worklink App. Additional query parameters will be added as external data to the scenario session that is created.

If the Deep link’s targeted Scenario is a Persisted Session type, it will open the active session if the user has already created a session for that Scenario, rather than create a new session.

Query Parameter Values

  • Action: fetch_scenario

  • Resource Key: scenario

  • Resource ID: The ID of the scenario.

Example: worklink://resource?action=fetch_scenario&scenario=123456

Adding External Data

Deep links accept an arbitrary number of extra query parameters which can be used to link data in customer (or 3rd party) systems with ScopeAR data.

The ScopeAR platform stores extra parameters received as key-value pairs in a JSON Hash attribute on Scenario Sessions or Call Sessions created by the Worklink app.

We call these parameters “external data”, as it is data supplied by the external customers.

Example #1

All properly encoded query parameters are accepted, e.g.:

worklink://resource?action=fetch_catalog&asset=42&workorder=89&assigneduser=joe_smith

becomes ScenarioSession.externalData = { “workorder”: “89”, “assigneduser”: “joe_smith” }

Example #2

Even nested query parameters are accepted, e.g.:

worklink://resource?action=fetch_catalog&asset=42&anything=you_want&even%5Bdeeply2%5D%5Bnested%5D=arguments

becomes ScenarioSession.externalData =

While the deep link format above can be used to directly launch WorkLink on a device that already has WorkLink installed, the more common and more flexible usage of deep links is to use a deferred deep link.

A deferred deep link has an expanded format that prepends “https://getworklink.com/deferred/fallback?deep_link=” to the deep links above which then redirects the deep link through the getworklink web service.

An example of a deferred deep link would look like this:

https://getworklink.com/deferred/fallback?deep_link=worklink://resource?action=fetch_catalog&catalog=123456

A deferred deep link that includes external data would look like this:

https://getworklink.com/deferred/fallback?deep_link=worklink://resource?action=fetch_catalog&asset=42&workorder=89&assigneduser=joe_smith

Deferred deep links go through the web service which will then display a web page that allows the user to select how to launch WorkLink. This can be used to install Worklink before launching the deep link or to relaunch the deep link on other devices.

Deferred deep links to specific resources have been turned into shortcodes for your convenience within the CMS. These shortened deep links are called shortcode deferred deep links. A shortcode deferred deep link will look like the following:

For scenarios and catalogs, this shortcode has also been turned into a QR code that you can download and use.

Fetch Catalog

The Fetch Catalog Deferred Deep link can be found on a catalog page:

Fetch User

The Fetch User Deferred Deep link can be found on a user profile page:

Fetch Scenario

The Fetch Scenario Deferred Deep link is found on a scenario page:

 

Fetch Contact List

The Fetch Contact List Deferred Deep link is found on the company page under the settings tab:

The External Data section above describes how to add external data parameters to deep links. In the same way, external data parameters can be added to either a deferred deep link or its shortcode equivalent.

An example of this would look like:

https://getworklink.com/3n7B&workorder=89&assigneduser=joe_smith

When this link is used, it would then become the deferred deep link URL:

https://getworklink.com/deferred/fallback?deep_link=worklink://resource?action=fetch_scenario&scenario=123456&workorder=89&assigneduser=joe_smith

When auto-creating deep links in a 3rd party application for integration purposes, typically the easiest thing to do is to append the external data to the shortcode link for the resource that you want to use. This will then be expanded to the full deferred deep link format when launched.

Querying Records

To query for records that have external data populated by a Deep link, refer to this article on how to do GraphQL queries with external data: https://scopearcloud.atlassian.net/wiki/spaces/API/pages/2325315585