Power BI: Using Parameters with Narratives – JSON-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 a variation of the Expenditure Variance sample project used in the Using Drilldown with Narratives tutorial.
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. Configure the Arria add-in with the URL and API key of the published NLG Studio project.
3. Click Generate Text. You’ll see the same text you saw when previewing the narrative in Studio.
4. With the Arria add-in selected in the dashboard, click the Format icon under the Visualizations pane.
5. Click Parameter Control 1 to expand the setting.
6. 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.
The value you select in this field is assigned to the
Note: Enter the values as a comma-separated list. Parameter values can be strings or numbers.
A dropdown field named
Threshold % is created in the Arria add-in:
10 from the dropdown list.
Note: Selecting a value from the dropdown will have no effect on the narrative until you modify the Studio project to make use of the new parameter. You’ll do that in the next section.
8. Click on the settings cog icon and expand the add-in.
You see the
thresholdPercentage parameter and the value you selected in the View Dataset in JSON window:
Finally, you’ll configure the NLG Studio project to use the value selected in the Threshold % field in Power BI.
The first step is to download the modified JSON data containing information about the new parameter, so that you can upload it to your Studio project.
Download the modified JSON data
1. In Power BI, in the top-right of the add-in, click the Focus mode icon to expand it.
2. In the View Dataset in JSON section, click the download icon to download the data.
3. In the dialog, click Open. Click OK.
A file named
data.json is downloaded to your Downloads folder.
Now you’ll upload the modified JSON data to Studio and configure the
Modify the NLG Studio project
1. In NLG Studio, in the left navigation bar, click Variables to go to the Variables view.
thresholdPercentage variable, which is currently set to zero. This variable is used in the project when calculating which drivers and offsets are above the threshold percentage.
2. In the left navigation bar, click Data to view the project’s sample data.
parameters array in the JSON data, which is currently empty. This array is used to pass the parameter value you select in Power BI.
3. Click the Import new sample data icon to import the
data.json file from your Downloads folder.
4. Look at the JSON data again. The
parameters array now shows the newly created
thresholdPercentage parameter, with a value of 10.
You can now access the value passed by the
thresholdPercentage parameter and assign it to the
5. In the left navigation bar, click Variables to go back to the Variables view.
6. Click on the thresholdPercentage variable and modify it as follows:
- change the Variable Type from STRING to JSON.
- change the Source to the location of the
thresholdPercentageparameter within the JSON object.Delete the ‘0’, then drill down to the following location (or copy and paste this expression):
The Variable Type will change automatically to String.
7. Go to the Publish view and re-publish the project. The URL endpoint and the API key remain the same, so you don’t need to update anything in the Arria add-in for Power BI.
You can now use the new Parameter Control field in Power BI.
Use the new Threshold % field in Power BI
1. In Power BI, try selecting different
Threshold % values to see how the narrative changes.
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 – Table-Type Studio Projects
How to Use These Samples