Today, we will explore an exciting addition in the latest release, 2023.2.1, for the Stimulsoft BI Server product: user parameters. Contrary to the name, this powerful feature extends beyond individual users, encompassing user roles and even all users within a workspace. Before diving into the specifics, let's begin by understanding the concept of user parameters.
User parameters can accept various types of values, including strings, numbers, booleans, dates, images, and expressions. Additionally, user data, such as first name, last name, username, role, parent folder name, and workspace name, can be passed through user parameter expressions. You should know that user parameters serve purposes beyond data filtering; filtering is just a special case. For instance, you can also display the name of the user who is currently working with the report.
There is one important point to note, which is a subtle distinction between a user parameter and a report variable. A report variable is a variable that is associated with a template, whereas a user parameter is a variable that belongs to a specific user. As of the current version, it is not possible to overwrite a report variable when using user options. The process involves clearing the list of parameters from the previous user before loading the report into the designer or viewer, and then adding the parameters specific to the current user.
Now, the question arises: how can we filter the same request by different users? It's simple - you need to add parameters to users with the same name but different values. In the template itself, in the query to the data source, you need to add a parameter with the expression type. Then, specify the name of the user parameter as the expression. Consequently, when viewing a report, a custom value will be passed to the query for data filtering. The data will be filtered accordingly, and only the necessary information will be displayed in the report.
Background information
Stimulsoft BI Server involves teamwork with reports and dashboards. A group of users can view and edit the same template, for example. Let's imagine a scenario where it is necessary to filter the data based on specific criteria for certain users or user groups. In other words, administrators would see one set of data while managers would see another. Creating separate templates for each user or group is one option, where the data can be filtered within the template using the data source. However, as the number of users increases, the number of templates will also grow. The approach of using links, which we discussed in detail in the article, is not suitable in this case. The links refer to the original template, and it is not possible to filter data for a specific link. If we consider having more than one template for each user, the situation becomes critical, as each template would need to be configured for every user or user group. Consequently, as the number of users grows, administration will become increasingly challenging.User Parameters
The issue of filtering data for a specific user can be resolved by passing a parameter to the report and utilizing it in a query to select the relevant data for filtering. In this manner, when the user views the report, they will only see the necessary data. This approach can be implemented within a single template. Later on, we will delve into a comprehensive illustration of an example regarding data filtering. But for now, let's address the primary question.What is a user parameter?
Essentially, this involves a local user variable that is incorporated into the template as a report variable when a particular user works with it. When another user interacts with the template, the variables from the previous user are cleared, and the parameters of the current user are added to the template.User parameters can accept various types of values, including strings, numbers, booleans, dates, images, and expressions. Additionally, user data, such as first name, last name, username, role, parent folder name, and workspace name, can be passed through user parameter expressions. You should know that user parameters serve purposes beyond data filtering; filtering is just a special case. For instance, you can also display the name of the user who is currently working with the report.
How to create a user parameter?
Parameters are created using the Add User Parameter command on the Users tab in the Navigator. Depending on the selected context - workspace, role, or user - the option will be added for all users of the workspace, for all users of a specific role, or for a specific user. In the menu for creating a new parameter, you must specify the name, type, and value of the parameter. Then, click the OK button in this menu. After that, the parameter will be added and displayed in the user hierarchy. By the way, any user parameter that has been created can be changed or deleted on this tab using the Change and Delete commands.Using user parameters in a report
As mentioned earlier, the user parameter will be added to the template as a report variable and will be displayed in the list of data dictionary elements. When editing a report, user parameters can be utilized as report variables. For instance, they can be used to filter a data source, display information in a report, and more. Important!There is one important point to note, which is a subtle distinction between a user parameter and a report variable. A report variable is a variable that is associated with a template, whereas a user parameter is a variable that belongs to a specific user. As of the current version, it is not possible to overwrite a report variable when using user options. The process involves clearing the list of parameters from the previous user before loading the report into the designer or viewer, and then adding the parameters specific to the current user.
Use case
Let's revisit our example with filtering, but first, let's summarize and give us a little break. You can add a parameter for a specific user. This parameter will be included as a report variable in the template. Consequently, you can work with a user parameter just like a report variable, including using it in a query to filter data. However, when the template is loaded into the designer or viewer, the list of parameters from the previous user is cleared, and the parameters of the current user are added.Now, the question arises: how can we filter the same request by different users? It's simple - you need to add parameters to users with the same name but different values. In the template itself, in the query to the data source, you need to add a parameter with the expression type. Then, specify the name of the user parameter as the expression. Consequently, when viewing a report, a custom value will be passed to the query for data filtering. The data will be filtered accordingly, and only the necessary information will be displayed in the report.
In summary, user parameters significantly enhance the possibilities of collaborative work with reports and dashboards in Stimulsoft BI Server.