Qlik Sense: Extending an Out-of-the-Box Narrative

Documentation for Arria NLG’s Extension for Qlik Sense Desktop

This documentation is organized as follows:


Get the sample Qlik Sense report

Get and modify the sample NLG Studio project

Configure the Arria extension to use your published Studio project

Other documentation for Arria’s extension to Qlik Sense




Arria NLG’s extension for Qlik Sense allows you to not only use the out-of-the-box narratives generated from Core Insights, but also extend or modify those narratives to fit your domain’s terminology and any preferences you may have for phrasing, ordering of information, formatting, and so on.

The Arria extension takes the data behind your dashboard and sends a request to Arria’s Insights API, which then delivers messages to the Custom Narrative service for use in NLG Studio, as shown above. The messages are the interface between data-side and language-side processing. Messages are derived from the data analysis and interpretation stage of Arria’s insights APIs and used in the narrative services. Put another way, the messages are enhanced information, containing insights, for Studio to work with in its generation of narratives.


Get the sample Qlik Sense Report

To extend Arria’s out-of-the box narratives, you configure the Qlik Sense extension on your dashboard to use Arria’s insights APIs and corresponding NLG Studio projects. In this example you’ll begin by downloading a sample Qlik Sense report with an out-of-the-box narrative already configured. Next, you’ll download a sample NLG Studio project containing the code for that narrative. Then, you’ll make some modifications and publish the project to see your changes in the new, extended narrative.

1. Download the Arria Qlik Sense extension.
2. Extract the ZIP file.
3. Copy the extracted folder (ArriaQlikSense2.0) to the Extensions folder in your Qlik Sense installation folder (\Qlik\Sense\Extensions).
4. Download our sample Qlik Sense report for extending narratives and copy it to \Qlik\Sense\Apps.
5. In Qlik Sense Desktop, open the report. You should see a narrative like this, generated from Arria’s out-of-the-box BI option (Configure Narrative in the UI):

6. Interact with the graph and the filter to see how the narrative responds.


Get and modify the sample NLG Studio project

Now let’s assume you want to change the narrative slightly. In this example, you’ll customize the title of the narrative. (This is just a small change that demonstrates how to modify the narrative in a way that is immediately obvious. In most instances, you would probably want to make more extensive changes.)

1. Download our out-of-the-box Descriptive Statistics NLG Studio project.
2. Log in to NLG Studio.
3. In NLG Studio, click the Import a Project icon to upload the Descriptive Statistics project to your dashboard.
4. In your dashboard, click the project to open it.
5. In the left navigation ribbon, click Compose to go to the Compose view.
6. In the list of scripts, click the MeasureOverview sub-script.
7. Change the “MeasureOverview” script to modify the title, adding “- ABC Co. Ltd.”, as shown below:
[[measure.measure_name]] – ABC Co. Ltd.

8. Go back to the Main script, and click Preview to check you have introduced no errors.
9. In the left navigation ribbon, click Publish to go to the Publish view.
10. In Run Project, click Publish and make a note of the project URL.
11. Click API, then generate and make note of the API key.


Configure the Arria extension to use your published Studio project

Now you’re ready to configure the Arria extension to use your newly published Studio project. Because you are extending the out-of-the-box narratives, you must call the relevant Insights API. You must also configure mapping scripts to provide the necessary metadata to carry out the analysis and to leverage the Studio project.

1. In Qlik Sense, in the sample Qlik Sense report you downloaded above, click the cog in the Arria widget.
2. Click Create Custom Narrative.
3. In the Simple/Advanced toggle, select Advanced.
4. Now enter the project URL. In the first blank line (Enter NLG Service URL), paste the URL from your published Studio project.
5. Configure the Authorization header. In the second blank line (Key), type Authorization.
6. In the third blank line (Value), type bearer and paste in the API key from your published Studio project.
7. Configure the mapping script.

a. Expand the widget to full screen.
b. Click Edit Mapping Script to expand the window, and paste the following:
var data=getData();

8. Configure the insights API URL you obtained from Arria. For this example, copy/paste the following:

9. Configure the authorization key (x-api-key) and value (WPj9iYDMvI4thvgSQwv121Xm0h7d1RaR2fpLZpwj).
Note: This API and the authorization key are only for learning purposes; they cannot be used in production.

When you have completed Steps 8 and 9 above, the Insights URL window should look like this:

10. Click Generate Text. Now you should see the text with the modified title.


Other documentation for Arria’s extension to Qlik Sense

For more information, see:

Configuring a narrative

Creating your own narratives

Using drilldown with narratives

Arria’s showcase project for Qlik Sense