In the previous blog in this series, we learned about the Navigation Utility function. In this blog, let us take a closer look at passing filter parameters to Story.
* * *
Navigation Utility function openStory() has an optional argument where you can pass URL parameters to Story. This URL parameter can be of three types – display, filter and variable. Here we are specifically exploring the option to pass filters.
There are six types of parameters that can be passed via URL to any Story when you want to create a Story Filter. The following list shows the type of parameter, syntax and whether it is optional or required.
- Model ID (Syntax: f<XX>Model, Required)
- Dimension ID (Syntax: f<XX>Dim, Required)
- Hierarchy Name (Syntax: f<XX>Hierarchy, Optional)
- Include / Exclude (Syntax: f<XX>Op, Optional)
- Unbooked (Syntax: f<XX>Unbooked, Optional)
- Filter Value (Syntax: f<XX>Val, Required)
In the syntax mentioned above <XX> can be any natural number less than or equal to 99. This is used when you want to create several Story filters. The parameters with the same number will act as a single set.
One important information to note is that every filter passed to a Story act as a Story Filter. Page-Level Filters or other selections like Input Control cannot be passed. If there is any existing Story Filter for the dimension that you pass in URL, then the value is overwritten.
Finding the IDs
Before appending the parameters in the Navigation utility function, let us see how to find the required IDs. Model ID should be in the format <package_name>:<object_name>. You can find the object_name of the model in the browser URL when you open a model. To find the whole model ID, you can visit the URL – https://<TENANT>/api/v1/stories?include=models where <TENANT> should be replaced with your SAC tenant URL. This URL will show all the Stories and the Model IDs used in them.
Here you can search for the Story or the object_name and then find the whole ID of the model including the package_name.
IDs of Dimensions can be found within Model Summary when you open a model or when you hover over the dimension within Builder panel while creating a Story. Similarly, you can find the Key value of a member within dimension details when you open a model or when you enable display settings to show member ID while creating a Story.
Now that you know about different parameters and how to find the required IDs, let us see how to append various parameters in Navigation Utility function. Filter parameters need to be appended as an array and then passed as an argument i.e. URL parameter. In the example below, 01 is the unique number that replaces <XX>.
- ‘f01Model’ is the parameter name for model ID and ‘t.T.CB3ZK1MOW2R6KAME6HRNTDE4N4:CB3ZK1MOW2R6KAME6HRNTDE4N4’ is the ID of the model (in format <package_name>:<object_name>).
- ‘f01Dim’ is the parameter name for dimension ID and ‘Segment’ is the ID of Dimension.
- ‘f01Val’ is the parameter name for filter value and ‘Consumer’ is the ID of the member to be filtered.
- ‘f01Op’ is the parameter name that mentions whether to include (‘in’) or exclude (‘notIn’) the filter value.
The above function opens an existing Story and creates a Story Filter for Dimension Segment by only including the member Consumer.
Combining URL Parameters
You can combine multiple URL parameters when using the openStory() function. The following example combines the display and filter parameter. Filter Parameter includes multiple Story filters passed as two different sets identified using the natural numbers 01 and 02.
The above example passes a display parameter that mentions the Story to be opened in the present mode. The first Story Filter is passed to create a filter on Segment by only including ‘Consumer’. The second Story Filter is passed to exclude the Cities – Dallas and Newark. The last argument false mentions that the Story should be opened in the same browser tab.
Analytics Designer automatically URL encodes the parameter values. The generated URL is shown below for reference.
You can see the above example in action below.
Apart from using Navigation Utility function, you can also use the same URL parameter format when you embed a Story within an HTML page or even within an Analytic Application when you use the Web Page widget.
In the next blog, we will discuss in detail about Data Analyzer.