Power BI: Using Parameters with Narratives – Table-Type Studio Projects
Documentation for Arria NLG’s Add-in for Power BI Desktop
This documentation is organized as follows:
Parameters are another way of configuring a narrative from the Arria add-in for Power BI. They allow dashboard users to change the narrative according to which numerical or text value they select from a dropdown field in the visualization.
You can create up to three parameters in the Parameter Control of the Arria add-in, and configure your NLG Studio project to use them in a multitude of ways. The value selected for each parameter will be passed to your published Studio project when you click Generate Text.
For example, you may wish to include different or more detailed information in a narrative designed for account managers than in one designed for senior management. You can create appropriate narratives for each by creating a Target Audience parameter with text values such as CEO, Account Manager, and Client, and then selecting the appropriate value when you generate the narrative.
Or, you may have a dataset containing expenditure data and a narrative describing the expenditure variance between this year and last. You may wish to configure your report to include information on only those drivers and offsets with a value above a certain threshold percentage.
We use the latter example in the following tutorial. You’ll create a parameter named thresholdPercentage in the Parameter Control field of the Arria add-in, and define a list of numerical values that can be assigned to it. You’ll then modify a Studio project so that it changes the drivers and offsets it describes in your narrative depending on which value you select in the add-in.
Note: To learn about creating NLG Studio projects from scratch and writing your own scripts, see the Arria NLG Studio documentation and tutorials.
This tutorial uses an Expenditure Variance sample project.
The project has already been partially configured to use parameters: a variable named
thresholdPercentage has been created and is used to determine which drivers and offsets are described in the narrative, depending on whether their value is above or below the threshold percentage. The variable is initialized to zero, and since all drivers and offsets represent more than zero percent of the overall expenditure, they will all be described in the narrative.
Later in the tutorial you’ll configure the variable to use the value selected in the Parameter Control field in your Power BI dashboard instead.
1. Download the Using Parameters with Narratives sample NLG Studio project and extract the .JSON file from within the .ZIP file.
2. In NLG Studio, import and open the project.
3. Click Compose to go to the starter scripts provided.
In the Main script you can see that the project is already configured to use the
4. Click Preview to view the script’s output.
thresholdPercentage parameter is currently set to zero, the narrative describes all drivers and offsets contained in the dataset.
5. Publish the project to an API endpoint, secured by an API key, so that you can call it from Power BI.
- In your NLG Studio project, click Publish in the left navigation ribbon to go to the Publish view.
- In the Publish > API tab, click the Publish button.
- Make a note of the project URL. (From inside the URL box, you can click the copy icon to copy the URL to your clipboard. Paste it to a notepad.)
- In the API Key section, click the Generate API Key button.
- Make note of the API key generated. (Again, you can copy it to your clipboard from inside the box with the key. Paste it to a notepad.)
Now you’ll create and configure a parameter named
thresholdParameter using the Parameter Control feature of Arria’s add-in. It allows dashboard users to dynamically select the threshold percentage above which drivers and offsets will be included in the narrative.
1. Download the Using Parameter Controls sample Power BI report and open it in Power BI.
2. Set the Studio Project Type to Describe a Table.
3. Configure the Arria add-in with the URL and API key of the published NLG Studio project.
4. Click Generate Text. You’ll see the same text you saw when previewing the narrative in Studio.
5. With the Arria add-in selected in the dashboard, click the Format icon under the Visualizations pane.
6. Click Parameter Control 1 to expand the setting.
7. Configure it as follows:
- In the Key field, enter
thresholdPercentage. This is the name of the parameter that will be passed to Studio API via the JSON data object.
- In the Label field, enter
Threshold %. This is the name of the Parameter Control field that will appear in the Arria add-in.
- In the Values field, enter
0, 10, 20, 30. These are the values that will be available to select from the dropdown list.
Note: Enter the values as a comma-separated list. Parameter values can be strings or numbers.The value you select in this field is assigned to the
A dropdown field named
Threshold % is created in the Arria add-in:
8. Select different values from the
Threshold % field and notice how it affects the generated narrative.
The value you select in this field is assigned to the
thresholdPercentage parameter and embedded in the CSV payload data passed to the API.
9. Click on the settings cog icon and expand the add-in. You see the
thresholdPercentage parameter and the value you selected in the View CSV Payload window:
For more information, see:
Configuring Your Narrative
Extending Your Narrative
Creating a Custom Narrative – JSON-Type Studio Projects
Creating a Custom Narrative – Table-Type Studio Projects
Using Drilldown with Narratives
Using Parameters with Narratives – JSON-Type Studio Projects
How to Use These Samples