Power BI: Extending an Out-of-the-Box Narrative
Documentation for Arria NLG’s Add-in for Power BI Desktop
This documentation is organized as follows:
Arria NLG’s add-in for Power BI 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 add-in 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.
To extend Arria’s out-of-the box narratives, you configure the Power BI add-in on your dashboard to use Arria’s insights APIs and corresponding NLG Studio projects. In this example, you’ll begin by downloading a sample Power BI report 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.
1. Download this sample Power BI report.
2. In Power BI 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):
3. Interact with the graph and the filter to see how the narrative responds.
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 and extract the contents of the ZIP file to find the JSON file inside.
2. Log in to NLG Studio.
3. In NLG Studio, click the Import a Project icon to upload the Descriptive Statistics project (the JSON file) 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 add-in to use your published Studio project
Now you’re ready to configure the Arria add-in 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 Power BI, in the sample Power BI 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
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. In the top-right corner of the widget, click the Focus mode icon to expand the widget.
b. Click Edit Mapping Script to expand the window, and paste the following:
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 (
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.
For more information, see: