What Are Filter Parameters in Bold BI Embedding, and Why Are They Important?

Filter parameters in Bold BI embedding are configurations used to control which data is displayed on an embedded dashboard. They allow developers to set conditions that determine data visibility based on specific criteria, such as user roles, locations, or other dynamic values. These parameters are often implemented using the embed_datasource_filter within the embedding process to ensure that only authorized and relevant data is displayed to the end-user.

We need to pass the filter value in the Authorize API endpoint. This type of filtering is more secure and can pass n number of filter values. The Authorization Server Endpoint in Bold BI is a URL that handles authentication and authorization for accessing secured resources, such as dashboards and APIs. It is used to issue access tokens based on authentication credentials, enabling secure communication between clients and Bold BI services.

To pass filters to the embed_datasource_filter parameter in the Authorize API endpoint, refer to the following sample in C#(It differs based on your platform language). Here, we have to set both types of filters (Dashboard Parameter and Datasource Field Parameter) to the embed_datasource_filter property in the endpoint.

public string Authorize([FromBody] object embedQueryString)
{
   // Deserialize the request payload to access embed query parameters
   var embedClass = Newtonsoft.Json.JsonConvert.DeserializeObject<EmbedClass>(embedQueryString.ToString());
   var embedQuery = embedClass.embedQueryString;

   // Attach necessary user information and synchronization details
   embedQuery += "&embed_user_email=" + EmbedProperties.UserEmail;
   double timeStamp = (int)DateTime.UtcNow.Subtract(new DateTime(1970, 1, 1)).TotalSeconds;
   embedQuery += "&embed_server_timestamp=" + timeStamp;

   // Implement the filter parameters to manage data visibility
   embedQuery += "&embed_datasource_filter="+ "[{&&CustomerId=ANTON}]";

   // Construct the authorization URL with the query and security signature
   var embedDetailsUrl = "/embed/authorize?" + embedQuery + "&embed_signature=" + GetSignatureUrl(embedQuery);

   using (var client = new HttpClient())
   {
       client.BaseAddress = new Uri(embedClass.dashboardServerApiUrl);
       client.DefaultRequestHeaders.Accept.Clear();

       // Execute the HTTP request and retrieve the result
       var result = client.GetAsync(embedClass.dashboardServerApiUrl + embedDetailsUrl).Result;
       string resultContent = result.Content.ReadAsStringAsync().Result;

       // Return the response content to complete the authorization process
       return resultContent;
   }
} 

Here’s how to effectively employ these filters:

Filtering by a Single Field

Filtering by a single field allows you to display dashboard data based on a specific data column. For instance, if you need to display data only for ‘Alice Mutton’ in a ProductName column, you can set up a filter like this:

embedQuery += "&embed_datasource_filter="+ "[{&ProductName=Alice Mutton}]"; 

This setup ensures that only records with ‘Alice Mutton’ in the ProductName field are shown to the user, facilitating targeted data analysis.

Filtering by Multiple Field Values

When you need to apply filters based on multiple criteria, such as user role and location, you can concatenate these fields. For example, this filter restricts data to an admin user located in China:

embedQuery += "&embed_datasource_filter=" + "[{&userEmail=admin@boldbi.com&Country=China}]"; 

Using multiple field values allows you to tailor the data view precisely to meet specific user needs.

Filtering by Dashboard Parameter

Dashboard parameters offer a way to filter data using predefined criteria. This approach allows for dynamic data filtering, such as narrowing down data to one country:

embedQuery += "&embed_datasource_filter="+"[{&&CountryName=USA}]"; 

This way, you can easily switch the focus of your dashboard by changing the parameter value, offering flexibility for end-users.

Combining Field and Parameter Filtering

For a more nuanced approach, you can combine direct field filters with dashboard parameters. This dual-filtering allows complex conditions such as filtering products and countries:

embedQuery += "&embed_datasource_filter="+ "[{&ProductName=Alice Mutton&&CountryName=Switzerland}]"; 

This combination helps ensure that all displayed data meets criteria from both fields and parameters, enriching the dashboard’s interactivity and relevance.

Filtering Specific Data Source Fields

In environments with multiple data sources, you may need to apply filters specific to a data source. Prefixing the field with the data source name targets the filter accordingly:

embedQuery += "&embed_datasource_filter=" + "[{Olympics2012Dashboard_MedalsPerCapital.Country=China}]"; 

This precision ensures that filters are only applied to the necessary data source, maintaining the dashboard’s data integrity across diverse datasets.

Additional References

• User Guide Documentation: Embed DataSource Filter
• Knowledge Base Article: Handling Server-Side Filtering with Parameters in Embedding
• User Guide Documentation: Java Script Based Embedding