Dashboard Variables: Difference between revisions

From QPR ProcessAnalyzer Wiki
Jump to navigation Jump to search
(Created page with "'''Variables''' in QPR UI are for storing session time information and communicating between different user interface elements, such as views, panels and presentation objects....")
 
 
(50 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Variables''' in QPR UI are for storing session time information and communicating between different user interface elements, such as views, panels and presentation objects. Variables can only contain textual (string) values. If other types of values are provided, they are converted into strings.
'''Variables''' are for storing session time information and interacting between UI elements, such as charts. Variables can contain textual (string) values. If other types of data can be stored by converting them into JSON.


__TOC__
__TOC__


== Variable Behaviors ==
== Dashboard Variables ==
Variables can be defined for '''views''', '''panels''' and '''presentation objects''' (called '''UI elements''') which form a '''scope''' for the defined variables. Variables are visible and accessible in the scope where they have been defined and also in all '''sub scopes''' in the hierarchy of UI elements. For example, a variable defined in a view scope is visible in all panels and presentation objects in the view. Also a variable defined in a panel is visible in all presentation objects in the panel, but not in presentation objects in other panels. In addition to UI elements (view, panel and presentation object), variables can exist in '''session''' scope. The session scope is visible in all views, i.e. session variables are preserved when opening another view. Thus the visibility hierarchy for variables is (starting from the top):
Dashboard variables can be defined for dashboards, and the variables in the below table have a special meaning. Variables can be set by opening a dashboard, clicking the dots menu on top right, clicking '''Dashboard Properties''' and opening tab '''Variables'''.
* Session
{| class="wikitable"
* View
!'''Variable name'''
* Panel
! '''Description'''
* Presentation object
|-
||SortOrder
||Defines an order in which dashboards are shown in the [[Navigation_Menu|navigation menu]]. The variable value needs to be defined as a number. By default, dashboards are shown in the alphabetical order by name. Dashboards with a custom order defined (sort ascending by the order number) are shown before dashboards without the custom order (and they sort by dashboard name).
|-
||HiddenInNavigation
||Dashboards can be hidden from the navigation menu by defining this variable value to ''true''. A hidden dashboard is still shown in the navigation menu when the dashboard is currently open. For example, details dashboards, which are only opened from other dashboards, can be hidden in the navigation menu.
|-
||DashboardFilter
||Hidden filter rules that are applied to the charts/flowcharts in the dashboard. Unlike the filter rules in the ''Filter'' variable, the rules in the ''DashboardFilter'' variable are not directly visible in the dashboard. Filter rules in the ''DashboardFilter'' variable are applied before the ''Filter'' variable.
 
Contents of the ''DashboardFilter'' variable is defined using the [[Filtering_in_QPR_ProcessAnalyzer_Queries|JSON format]].
 
For an easy setup, create a stored filter first, and copy its value from the ''Filter'' variable to the ''DashboardFilter'' variable.
|-
||Filter
||Visible filter rules that are applied to the charts/flowcharts in the dashboard. The visible filter rules changed when making drilldown in the dashboard or changing between stored filters.
 
Contents of the ''Filter'' variable is defined using the [[Filtering_in_QPR_ProcessAnalyzer_Queries|JSON format]].
|-
||FilterId
||Id of the selected saved filter. When empty, the selected filter rules don't belong to any saved filter, When -1, there are no filter rules selected (i.e., ''All cases'' is selected).
|-
||ModelId
||Id of the model, for which charts/flowcharts in the dashboard are run. The model is also visible in the dashboard header.
|-
||Comparison
||Similar to the ''Filter'' variable, the ''Comparison'' variable stores the comparison rules that are used by the root causes analyses in the dashboard. The comparison rules are also visible and editable in the header.
 
Contents of the ''Comparison'' variable is defined using the [[Filtering_in_QPR_ProcessAnalyzer_Queries|JSON format]].
|-
||FilterSelection
||Filter rules for the yet unconfirmed selection made in chart/flowchart. Chart/flowchart in which the selection is made, is not yet filtered using the these rules. When the filter rules are confirmed, the rules are moved from ''FilterSelection'' variable to the ''Filter'' variable.
 
Contents of the ''FilterSelection'' variable is defined using the [[Filtering_in_QPR_ProcessAnalyzer_Queries|JSON format]].
|-
||SelectedPresentationObject
||Selected chart/flowchart id.
|-
||designModel
||BPMN model stored to the dashboard.
|}


When setting or getting variable values and two variables with same names exist in different scopes, the variable in the lower scope takes priority over the variable in the upper scope, i.e. the lower scope variable hides the upper scope variable within the scope of the lower scope variable.
== Dashboard Variable Behaviors ==
Variables can exist in '''user session''' and '''dashboard'''. The dashboard variables are available within that dashboard only, and they are defined in the ''Dashboard Properties''. The user session variables (shown in the '''Session Variables''') can be used to pass information between dashboards, because depending on the dashboard variable behavior, the dashboard variables may get initial values from the session variables. Note also that if there is no dashboard variable with the same name, the session variable is visible for the dashboard.


Each defined variable have a '''behavior''' which determine how the variables work when setting and getting their values. The following behaviors are available:
Dashboard variables have a '''behavior''' which determine how the variables work when set and get their values. The following behaviors are available:


{| class="wikitable"
{| class="wikitable"
Line 19: Line 60:
|-
|-
||Local variable
||Local variable
||Local variables are visible in the scope where the variable is defined and also in all its sub scopes. When initialized, the local variable gets a value that is set in its definition (in the Context tab). When a local variable value is changed by logic in a presentation object (e.g. data grid action), the change is made to the variable in the nearest scope of the presentation object in the UI element hierarchy where the variable has been defined as Local variable.
||Local variables are visible only in the dashboard. The initial value of local variables is defined in the ''Variables'' tab. When a local variable value is changed, its new value only exists as long as the dashboard is open.
|-
||Stored variable
||Stored variables work like Local variables, except that when the dashboard is saved, the current value of the Stored variable is saved to the dashboard.
|-
|-
||Optional parameter
||Optional parameter
||Optional parameters work like the local variables, except that the optional parameters get their initial values from the upper scope when the variables are initialized. For example, optional parameters in view scope get their values from the session scope when a view is opened, and optional parameters in the panel scope get their values from the view scope when the panel is initialized. If a variable having the same name doesn't exist in any of the upper scope, the optional parameter will have the value that is set in its definition (in the Context tab). After the optional parameter value is initialized, any changes in the upper scope variables don't affect the optional parameter value.
||Optional parameters work like the local variables, except that the optional parameters get their initial value from the user session when dashboard is opened. If a variable with the same name doesn't exist in the user session, the optional parameter will have the value that is set in its definition (in the Variables tab).
|-
||Stored variable
||Stored variables work like Local variables, except that when the view is saved, the current value of the Stored variable is saved to the view at the level where the Stored variable is defined.
|-
|-
||Default value
||Default value
||Unlike local variables and optional parameters, Default value variables are not independent variables but they are just default values for non-existing variables. Thus, if a variable with the same name exists in the upper scope, the defined default value variable doesn't have any effect. Only if no upper scope variable exists, the value defined for the default value variable (in the Context tab) is used in the default value variables' scope when referring to a variable with that name. Default value variable values cannot be set by presentation objects, so when trying to set an default value variable value, the value is set to the session scope variable.
||Unlike local variables and optional parameters, Default value variables are not independent variables but they are just default values for non-existing variables. Thus, if a variable with the same name exists in the user session, the variable with Default value behavior doesn't have any effect. Only if no user session variable exists, the value defined for the Default value variable (in the Variables tab) is applied. When setting a variable value, the value is set to the user session.
|}
|}


Note that variables in the session scope cannot be defined like the UI element variables, but session scope variables are created when they are set for the first time during a user session.
Variables in the session cannot be defined like the dashboard variables, because session variables are created when they are set for the first time during a user session.
 
When presentation objects set variable values, either the nearest UI element scope variable or the session scope variable can be set. In a [[Data_Grid_Properties#Data_Grid_Click_and_Popup_Menu_Events|data grid actions]] the setting is called '''scope''' with alternatives ''local'' and ''global'', and in [[HTML_Properties#Setting_Variables_in_JavaScript|HTML presentation object functions]], it's done using a parameter named '''presentation object runtime id'''. When setting a UI element variable, always the nearest variable value in the hierarchy is set. For example, when setting a value from a data grid, the data grid presentation object is the nearest scope, the panel is the next and the view scope is after the panel. If there is no variable in any UI element scope defined, the value is set to the session scope.
 
When creating bookmarks, currently only the session scope variables are stored to the bookmark.


== Setting Variable Values in URL ==
== Set Variables in URL ==
It's possible to set variable values in the url pointing to QPR UI. To do this, for each variable add "'''&<variable name>=<variable value>'''" in the end of the URL. For example: <nowiki>http(s)://SERVERNAME/ui/#/dashboard?sys:dashboard=24026&myvariable1=myvalue1&myvariable2=myvalue2</nowiki>
It's possible to set variables in the url when opening QPR ProcessAnalyzer. For each variable add "'''&<variable name>=<variable value>'''" in the end of the URL. For example:
<pre>
https://SERVERNAME/ui/#/dashboard?sys:dashboard=1234&myvariable1=myvalue1&myvariable2=myvalue2
</pre>
To handle special characters, the variable values in the url need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).


Note that when using variables a url, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).
Variables set in the URL will go to the user session ('''Session variable''' in the dots menu). If the variables need to be available in the dashboard, the variable behavior ''Optional parameter'' or ''Default value'' needs to be used. If the dashboard variable behavior is ''Local'' or ''Stored'', the variable doesn't have any interaction with the user session variables. No also that if there is no variable defined in the dashboard, the session variable is applied in the dashboard level.


== System Variables ==
== System Variables ==
QPR UI has the '''system variables''' defined in the table below. System variables have a special functionality in the system. All system variables start with '''sys:''' prefix, and thus it's a good practice not to name other variables to start with that to avoid accidental use of system variables.
QPR ProcessAnalyzer has the '''system variables''' defined in the table below. System variables have a special functionality in the system. All system variables start with '''sys:''' prefix, and thus it's a good practice not to name other variables to start with that to avoid accidental use of system variables.


When using variables a url pointing to QPR UI, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).
When using variables in the QPR ProcessAnalyzer url, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).


{| class="wikitable"
{| class="wikitable"
Line 52: Line 93:
|-
|-
||sys:dashboard
||sys:dashboard
||Id of the currently open view. Another view can be opened by changing this variable value.
||Id of the currently open dashboard. Other dashboard can be opened by changing this variable (alternatively sys:dashboardIdentifier can be used).
|-
|-
||sys:dashboardIdentifier
||sys:dashboardIdentifier
||Use this variable when you want to open another view using a '''path''' the target view. The path can be defined as:
||Use this variable when you want to open a dashboard by a path defined by the textual identifiers. The path can be defined as:
* '''Absolute path''' where the path starts from the folders hierarchy root. The absolute path always points to the view defined by the path. Example: ''/Folder/Sub folder/ViewIdentifier''.
* '''Absolute path''' where the path starts from the projects hierarchy root. The absolute path always points to the dashboard defined by the path. Example: ''/Project/Sub project/DashboardIdentifier''.
* '''Relative path''' where the path starts from the folder where the currently opened view is located. Relative paths can be used to link between views within a folder branch and the links remain, even if the branch is moved to other folder. Example: ''Folder/Sub folder/viewidentifier''.
* '''Relative path''' where the path starts from the project where the currently opened dashboard is located. Relative paths can be used to link between dashboards within a project branch and the links remain, even if the branch is moved to other project. Example: ''Project/Sub project/Dashboardidentifier''.


Absolute paths always starts with the slash ('''/'''), whereas relative paths don't start with slash.
Absolute paths always starts with the slash ('''/'''), whereas relative paths don't start with slash.


sys:dashboardIdentifier variable can only be used in the session context. Setting the sys:dashboardIdentifier variable value will automatically set the corresponding value to sys:dashboard variable. sys:dashboardIdentifier will be removed automatically after.
sys:dashboardIdentifier variable can only be used in the session variables. Setting the sys:dashboardIdentifier variable value will automatically set the corresponding value to sys:dashboard variable. sys:dashboardIdentifier will be removed automatically after. When both sys:dashboard and sys:dashboardIdentifier are defined, sys:dashboardIdentifier has the priority.
|-
|-
||sys:hideViewHeader
||sys:hideViewHeader
||Defines whether the top main toolbar in the view is hidden ('''true''') or visible ('''false''').
||Defines whether the top main toolbar in the dashboard is hidden ('''true''') or visible ('''false''').
|-
|-
||sys:mobileModeThreshold
||sys:username
||The width in pixels to use as the breakpoint for mobile mode of locked QPR UI views. When a screen width is smaller than the threshold, the view is shown in mobile mode. In the mobile mode, panels are stacked vertically and each panel's height equals the screen height. Supported values are integers. Default value is 800 pixels, which is used if this variable isn't defined or an invalid value is defined. Defining "0" as the value will disable the mobile mode. Note that sys:mobileModeThreshold has only effect in the view's effective context.
||Use this parameter to provide username to login automatically to QPR ProcessAnalyzer without visiting the login screen. To be able to authenticate, you also need to provide the ''sys:password'' parameter. sys:username and sys:password parameters are removed from the URL after the login, and so that they won't be stored as QPR ProcessAnalyzer variables. Note however, that the username and password can be stored in the browser history. sys:username and sys:password parameters only work when authenticating using QPR ProcessAnalyzer built-in authentication, so credentials for the federated authentication identity provider cannot be used here.
|-
||sys:password
||Use this parameter to provide password to login automatically to QPR UI without going to the login screen. You also need to provide the sys:username parameter. sys:username and sys:password parameters are removed from the URL after the login, and thus they won't be stored as QPR UI variables. Note however, that the username and password can be stored in the browser history. See url examples in the description of the sys:username parameter.
|-
||sys:sessionId
||QPR UI user session id. Can be used to pass the session id to other QPR Suite product to use it in [[Common QPR Authentication|common QPR Authentication]]. The variable value is readonly. The session id is accepted by the '''xsession''' parameter in all QPR products.
|-
||sys:settingsPanel
||View level variable defining whether the right side settings page is open and which tab in the pane is active. sys:settingsPanel is defined as a JSON object with following properties:
* isOpen: '''true''' (settings pane is open) or '''false''' (settings pane is closed)
* activePage: '''model''' or '''settings'''


Example: '''{"isOpen":true,"activePage":"settings"}'''
If the sys:username and/or sys:password are incorrect, user is directed to the login screen for authenticating with correct credentials.
|-
||sys:username
||Use this parameter to provide username to login automatically to QPR UI without visiting the login screen. To be able to authenticate, you also need to provide the ''sys:password'' parameter. sys:username and sys:password parameters are removed from the URL after the login, and so that they won't be stored as QPR UI variables. Note however, that the username and password can be stored in the browser history. sys:username and sys:password parameters only work when authenticating using QPR Suite or QPR ProcessAnalyzer; credentials for the federated authentication identity provider cannot be used here.


Example url's:
Example url's:
* <nowiki>https://localhost:8080/ui/#/dashboard?sys:dashboard=24026&sys:username=qpr&sys:password=demo</nowiki>
* <nowiki>https://localhost/QPRPA/ui/#/dashboard?sys:dashboard=24026&sys:username=qpr&sys:password=demo</nowiki>
* <nowiki>http://localhost:8080/ui/#/login?sys:username=qpr&sys:password=demo</nowiki>
* <nowiki>http://localhost/QPRPA/ui/#/login?sys:username=qpr&sys:password=demo</nowiki>
 
|-
Note that for path <nowiki>http://localhost:8080/ui/#/home/</nowiki> the login with the sys:password parameter doesn't work.
||sys:password
||Use this parameter to provide password to login automatically to QPR ProcessAnalyzer without going to the login screen. You also need to provide the sys:username parameter. sys:username and sys:password parameters are removed from the URL after the login, and thus they won't be stored. Note however, that the username and password can be stored in the browser history. Note also, that passing a password in a url is a considerable security risk. When using this method, it's very important to use encrypted (https) connection. See url examples in the description of the sys:username parameter.
|}
|}
== Context Variables and Web Browser History ==
Any time the '''session context''' is modified, a new browser history entry is created. The preceding values in the session context can be restored via the browser's '''Back''' button. Left-clicking the Back button will restore the previous session context values, whereas right-clicking the Back button will show a list of session context changes to select from. Selecting an entry on the list will restore the session context from that entry.
<br>
[[File:BrowserHistory.png]]
{{MDBTutorialViewPropertiesAndContext}}


[[Category: QPR ProcessAnalyzer]]
[[Category: QPR ProcessAnalyzer]]

Latest revision as of 11:38, 12 January 2024

Variables are for storing session time information and interacting between UI elements, such as charts. Variables can contain textual (string) values. If other types of data can be stored by converting them into JSON.

Dashboard Variables

Dashboard variables can be defined for dashboards, and the variables in the below table have a special meaning. Variables can be set by opening a dashboard, clicking the dots menu on top right, clicking Dashboard Properties and opening tab Variables.

Variable name Description
SortOrder Defines an order in which dashboards are shown in the navigation menu. The variable value needs to be defined as a number. By default, dashboards are shown in the alphabetical order by name. Dashboards with a custom order defined (sort ascending by the order number) are shown before dashboards without the custom order (and they sort by dashboard name).
HiddenInNavigation Dashboards can be hidden from the navigation menu by defining this variable value to true. A hidden dashboard is still shown in the navigation menu when the dashboard is currently open. For example, details dashboards, which are only opened from other dashboards, can be hidden in the navigation menu.
DashboardFilter Hidden filter rules that are applied to the charts/flowcharts in the dashboard. Unlike the filter rules in the Filter variable, the rules in the DashboardFilter variable are not directly visible in the dashboard. Filter rules in the DashboardFilter variable are applied before the Filter variable.

Contents of the DashboardFilter variable is defined using the JSON format.

For an easy setup, create a stored filter first, and copy its value from the Filter variable to the DashboardFilter variable.

Filter Visible filter rules that are applied to the charts/flowcharts in the dashboard. The visible filter rules changed when making drilldown in the dashboard or changing between stored filters.

Contents of the Filter variable is defined using the JSON format.

FilterId Id of the selected saved filter. When empty, the selected filter rules don't belong to any saved filter, When -1, there are no filter rules selected (i.e., All cases is selected).
ModelId Id of the model, for which charts/flowcharts in the dashboard are run. The model is also visible in the dashboard header.
Comparison Similar to the Filter variable, the Comparison variable stores the comparison rules that are used by the root causes analyses in the dashboard. The comparison rules are also visible and editable in the header.

Contents of the Comparison variable is defined using the JSON format.

FilterSelection Filter rules for the yet unconfirmed selection made in chart/flowchart. Chart/flowchart in which the selection is made, is not yet filtered using the these rules. When the filter rules are confirmed, the rules are moved from FilterSelection variable to the Filter variable.

Contents of the FilterSelection variable is defined using the JSON format.

SelectedPresentationObject Selected chart/flowchart id.
designModel BPMN model stored to the dashboard.

Dashboard Variable Behaviors

Variables can exist in user session and dashboard. The dashboard variables are available within that dashboard only, and they are defined in the Dashboard Properties. The user session variables (shown in the Session Variables) can be used to pass information between dashboards, because depending on the dashboard variable behavior, the dashboard variables may get initial values from the session variables. Note also that if there is no dashboard variable with the same name, the session variable is visible for the dashboard.

Dashboard variables have a behavior which determine how the variables work when set and get their values. The following behaviors are available:

Variable behavior Description
Local variable Local variables are visible only in the dashboard. The initial value of local variables is defined in the Variables tab. When a local variable value is changed, its new value only exists as long as the dashboard is open.
Stored variable Stored variables work like Local variables, except that when the dashboard is saved, the current value of the Stored variable is saved to the dashboard.
Optional parameter Optional parameters work like the local variables, except that the optional parameters get their initial value from the user session when dashboard is opened. If a variable with the same name doesn't exist in the user session, the optional parameter will have the value that is set in its definition (in the Variables tab).
Default value Unlike local variables and optional parameters, Default value variables are not independent variables but they are just default values for non-existing variables. Thus, if a variable with the same name exists in the user session, the variable with Default value behavior doesn't have any effect. Only if no user session variable exists, the value defined for the Default value variable (in the Variables tab) is applied. When setting a variable value, the value is set to the user session.

Variables in the session cannot be defined like the dashboard variables, because session variables are created when they are set for the first time during a user session.

Set Variables in URL

It's possible to set variables in the url when opening QPR ProcessAnalyzer. For each variable add "&<variable name>=<variable value>" in the end of the URL. For example: 

https://SERVERNAME/ui/#/dashboard?sys:dashboard=1234&myvariable1=myvalue1&myvariable2=myvalue2

To handle special characters, the variable values in the url need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).

Variables set in the URL will go to the user session (Session variable in the dots menu). If the variables need to be available in the dashboard, the variable behavior Optional parameter or Default value needs to be used. If the dashboard variable behavior is Local or Stored, the variable doesn't have any interaction with the user session variables. No also that if there is no variable defined in the dashboard, the session variable is applied in the dashboard level.

System Variables

QPR ProcessAnalyzer has the system variables defined in the table below. System variables have a special functionality in the system. All system variables start with sys: prefix, and thus it's a good practice not to name other variables to start with that to avoid accidental use of system variables.

When using variables in the QPR ProcessAnalyzer url, variable values need to be url encoded (more information: https://www.w3schools.com/tags/ref_urlencode.asp).

Variable name Description
sys:dashboard Id of the currently open dashboard. Other dashboard can be opened by changing this variable (alternatively sys:dashboardIdentifier can be used).
sys:dashboardIdentifier Use this variable when you want to open a dashboard by a path defined by the textual identifiers. The path can be defined as:
  • Absolute path where the path starts from the projects hierarchy root. The absolute path always points to the dashboard defined by the path. Example: /Project/Sub project/DashboardIdentifier.
  • Relative path where the path starts from the project where the currently opened dashboard is located. Relative paths can be used to link between dashboards within a project branch and the links remain, even if the branch is moved to other project. Example: Project/Sub project/Dashboardidentifier.

Absolute paths always starts with the slash (/), whereas relative paths don't start with slash.

sys:dashboardIdentifier variable can only be used in the session variables. Setting the sys:dashboardIdentifier variable value will automatically set the corresponding value to sys:dashboard variable. sys:dashboardIdentifier will be removed automatically after. When both sys:dashboard and sys:dashboardIdentifier are defined, sys:dashboardIdentifier has the priority.

sys:hideViewHeader Defines whether the top main toolbar in the dashboard is hidden (true) or visible (false).
sys:username Use this parameter to provide username to login automatically to QPR ProcessAnalyzer without visiting the login screen. To be able to authenticate, you also need to provide the sys:password parameter. sys:username and sys:password parameters are removed from the URL after the login, and so that they won't be stored as QPR ProcessAnalyzer variables. Note however, that the username and password can be stored in the browser history. sys:username and sys:password parameters only work when authenticating using QPR ProcessAnalyzer built-in authentication, so credentials for the federated authentication identity provider cannot be used here.

If the sys:username and/or sys:password are incorrect, user is directed to the login screen for authenticating with correct credentials.

Example url's:

  • https://localhost/QPRPA/ui/#/dashboard?sys:dashboard=24026&sys:username=qpr&sys:password=demo
  • http://localhost/QPRPA/ui/#/login?sys:username=qpr&sys:password=demo
sys:password Use this parameter to provide password to login automatically to QPR ProcessAnalyzer without going to the login screen. You also need to provide the sys:username parameter. sys:username and sys:password parameters are removed from the URL after the login, and thus they won't be stored. Note however, that the username and password can be stored in the browser history. Note also, that passing a password in a url is a considerable security risk. When using this method, it's very important to use encrypted (https) connection. See url examples in the description of the sys:username parameter.
Retrieved from "https://wiki.onqpr.com/pa/index.php?title=Dashboard_Variables&oldid=24194"