App Integration API

Note: STABLE.
This API is reliable and breaking changes are unlikely.

Syntax

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/

Version history

Note:

Use Qlik API Insights to see the version history for Qlik APIs and to compare API changes between versions.

Qlik API Insights

Introduced 2.2
Updated Sense February 2018

Overview

Note: As the App Integration API relies on the Qlik Sense Hub, it is not available in a QAP environment.

The App Integration API provides parameters that can be used to create an URL that returns a complete HTML page containing the embedded app. This URL can be embedded in a web page, for example by including it in an iframe.

It allows you to pass parameters to an app and to open an app with one or several selections applied.

The App Integration API is built on top of the Base URL. You can add additional parameters on top of the Base URL which defines the behavior of the App Integration API.

Base URL

The Base URL is constant and defines the location of the app.

Warning: Be aware that the Base URL might change in future releases.

Syntax: Base URL

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/

The following parameters must be defined to integrate the Qlik Sense app into your web site.

Parameter Description
machinename | servername

Specifies the path to the local machine or the server on which the app is located.

  • https://<servername>/
  • http://localhost:4848/ for Qlik Sense Desktop environment.
virtual proxy

This parameter is optional depending on server configuration for the server.

Specifies the virtual proxy to use.

appid

App id of the referenced app.

  • App name including full path for Qlik Sense Desktop environment.
sheetid Sheet id of the referenced sheet.

Retrieving the virtual proxy prefix programmatically

To get the virtual proxy prefix programmatically, you can use the following code in a browser console:

var prefix = window.location.pathname.substr( 0, window.location.pathname.toLowerCase().lastIndexOf( "/sense/app" ) + 1 );

Additional parameters

In addition to the Base URL, you can also pass parameters for bookmarks, options and selections.

Bookmarks

bookmark/{bookmarkid}

You add a bookmark definition by stating the bookmark id in addition to the Base URL.

Syntax: Base URL + bookmark

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/bookmark/{bookmarkid}

The bookmark id can be obtained by using the Single configurator.

Mashups: Obtaining app IDs and object IDs

Note: If a bookmark points to another sheet than the one you defined in the URL, you will automatically be redirected to the correct sheet.

Themes

Note: Theme support in App Integration API was added in Qlik Sense February 2018.

theme/{themename}

You add a theme definition by stating the name of the theme in addition to the Base URL. If no theme is stated, the default theme set in the Qlik Sense app will be used.

The theme name is case sensitive.

Syntax: Base URL + theme

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/theme/{themename}

Options

options/{option}

You can add option definitions in addition to the Base URL. Options will be applied before bookmarks and selections.

The following options are currently supported:

Option Description
clearselections Clears all selections (in all states) made in the app.
{state}::clearselections

Clears all selections in the defined state.

state - the name of the alternate state

Example: Clear all selections in the default state

$::clearselections

Example: Clear all selections in one state

My state::clearselections

Example: Clear all selections in multiple states

My first state::clearselections;My second state::clearselections

Syntax: Base URL + option

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/options/{option}

Selections

Select in the default state

select/{field}/{[value1;value2]} or select/{$::field}/{[value1;value2]}

Select in a defined state

select/{state::field}/{[value1;value2]}

The following parameters are part of the selection definitions you add to a base URL:

Parameter Description
state The name of the alternate state (Optional).
field The name of the field.
value The name of the value.

Selection definitions can be added to the Base URL. You can make selections in a single field or in multiple fields. Multiple values are semicolon separated.

You can also make selections in one or multiple states.

Note: For selections containing numeric values and search terms, the text representation should be added within square brackets, as in [value1].

Syntax: Base URL + selection in single field (in default state)

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{value1;value2}

Syntax: Base URL + selection in single field that has text representation of numeric values (in default state)

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{[value1];[value2]}

Syntax: Base URL + selections in multiple fields (in default state)

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{field}/{value1;value2}/select/{field2}/{value1;value2}

Syntax: Base URL + selections in one state

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{state::field}/{[value1];[value2]}

Syntax: Base URL + selections in multiple states

http[s]://<machinename | servername>/{virtual proxy}/sense/app/{appid}/sheet/{sheetid}/state/analysis/select/{state1::field}/{[value1];[value2]}/select/{state2::field}/{[value1];[value2]}

Error handling

Faulty definitions of bookmarks, options or selections are ignored.

Limitations

Note: As the App Integration API relies on the Qlik Sense Hub, it is not available in a QAP environment.

Solutions created with App Integration API may not work when the URL length is too long. You can increase the max length of the URL segment by adjusting one key in the Windows registry:

  • HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters\UrlSegmentMaxLength

Set it to a suitable length. Max length is 32766 and 0 means no limit.

Warning: We recommend that you investigate the impact to other programs on the machine, as changing these settings is a system-wide change.
Note: Selections containing numeric values and search terms cannot be selected in alternate states.

Did this information help you?

Thanks for letting us know. Is there anything you'd like to tell us about this topic?

Can you tell us why it did not help you and how we can improve it?