MicroStrategy: Extending an Out-of-the-Box Narrative
Documentation for Arria NLG’s Add-in for MicroStrategy Desktop
This documentation is organized as follows:
Arria NLG’s add-in for MicroStrategy 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 MicroStrategy 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 MicroStrategy dashboard 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 MicroStrategy dashboard (.MSTR file).
2. In MicroStrategy Desktop, open the sample dashboard. 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 graphs 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 for Studio and extract the contents of the ZIP file.
2. Log in to NLG Studio.
3. In NLG Studio, click the Import a Project icon to upload the Descriptive Statistics project to your Studio 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.
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 MicroStrategy, in the sample MicroStrategy dashboard 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 Studio project URL. Under the instructions to Call your NLG Service to create a narrative from selected data, paste the URL from your published Studio project.
5. In the second line (below the URL you pasted in), paste the API key from your published Studio project.
6. Configure the mapping script. Click Edit Mapping Script to expand the window, and paste the following:
7. Configure the insights API URL you obtained from Arria. Click Insights URL to expand the window. For this example, copy/paste the following:
8. 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 7 and 8 above, the Insights URL window should look like this:
9. Click Generate Text. Now you should see the text with the modified title.
For more information, see: