Tableau: Extending an Out-of-the-Box Narrative


Documentation for Arria NLG’s Extension for Tableau Desktop


This documentation is organized as follows:

Overview of extending a narrative

Extending an out-of-the-box narrative

Get the sample Tableau workbook
Get and modify the sample NLG Studio project

Other documentation for Arria’s extension to Tableau

 

Overview of extending a narrative

Arria NLG’s extension for Tableau 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.

 

Extending an out-of-the-box narrative

To extend Arria’s out-of-the box narratives, you configure the Tableau 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 Tableau workbook with an out-of-the-box narrative already configured (as described in Configuring Your Narrative). 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.

 

Get the sample Tableau workbook

1. Download this sample Tableau workbook.
2. In Tableau Desktop, open the workbook.
You should see a narrative like this, generated from Arria’s out-of-the-box BI option (Configure Narrative in the UI):

3. Interact with the graph and the filters 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 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 Tableau, in the sample Tableau workbook 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. Click Edit Mapping Script to expand the window, and paste the following:
var data=getData();
setDefaultNarrativeConfig(data);
updateDimensionOrMeasure(data,'Sales','entityType','currency');
updateDimensionOrMeasure(data,'Sales','unit','USD');
updateDescriptiveStats(data,1,"data",true);
updateVerbosity(data,'everything');
setData(data);

8. Configure the insights API URL you obtained from Arria. For this example, copy/paste the following:
https://jxczzc66qa.execute-api.us-east-1.amazonaws.com/prod/descriptivestats

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 Tableau

For more information, see:

Configuring a narrative
Creating a custom narrative
Further information about the Arria extension
Arria’s showcase project for Tableau – Out-of-the-Box Narrative
Arria’s showcase project for Tableau – Custom Narrative
Full documentation