Concepts → Internal Session Variable
Incorta creates a user session when a user signs in and authenticates. The session persists until the user signs out or the session expires. A session variable stores in-memory a scalar value or an array of values for a user session.
An internal session variable stores a scalar value or an array of value as a string from the result of an internal query expression.
Using the Formula Builder, you can define an internal query expression. An internal query expression typically queries a physical schema table or runtime business view. In this regard, the adjective “internal” references physical schemas and business schemas within a given tenant.
At the start of the user’s authenticated session, Incorta invokes all the internal session variables that the user has access to. From this point on, the internal session variable is immutable. During the user session, if there is an update to the source physical schema table and the table is loaded into memory, the updated value is not reflected in the user’s internal session variable. The user will need to sign out and start a new authenticated session.
You can use the Schema Manager to create and test an internal session variable. You use the Formula Builder to specify the query expression. You can reference an internal session variable in specific expression contexts such as a formula expression. You can assign access rights to an internal session variable.
Regardless of the source data type, an internal session variable stores a scalar or array of scalar values that are of the type string. When you use an internal session variable in a formula expression or filter expression, you may need to convert the string value to another data type using a built-in conversion function.
Here is an example of an internal session variable that queries the value of the
yearAgo date system variable.
query( formatDate( if( mod(year($yearAgo),4) = 0, addDays($yearAgo,-366), addDays($yearAgo,-365) ), "yyyy-MM-dd" ) )
In the above example, the internal session variable stores the date as a string. Even though the
formatDate() builtin function returns a scalar date, the internal session variable always store the value as a string.
Here are the properties of an internal session variable.
|Name||text box||Enter the name of the internal session variable|
|Description||text box||Optional description of internal session variable.|
|Query||Formula Builder||Construct an internal query expression using the Formula Builder. The internal query expression result is the value of the internal session variable.|
Following are the available access rights for an internal session variable:
|Can View||eye||The user can see the internal session variable when signed in and use it within an Insight.|
|Can Share||node tree||The user is able to share the internal session variable with other users.|
|Can Edit||pen and paper||The user is able to edit the properties, such as the query, of the internal session variable.|
If you have edit access rights to the internal session variable and belong to a group with the Schema Manager role, you can test the variable. There are two forms of testing a session variable:
Test: The result of the variable for the current user.
Test As: You can select a different user to test how the variable will display information for that user. This is useful when testing if permissions are configured properly or the output of the variable is dependent on the user.
The result of a test on an internal session variable is independent of the current user’s session. As such, if the internal query expression’s source schema is updated during your session the test result will reflect the change. Your session’s captured value of the internal session variable will not express this update. You will need to sign out and start a new session to have your internal session variable value updated.
Following are the general steps to testing an internal session variable:
- Sign in to the Incorta Direct Data Platform.
- In the Navigation bar, select Schema.
- In the Action bar, select + New → Session Variable → Internal Session Variable.
- In the Internal Variable dialog, specify the internal session variable properties.
Select Test to ensure the correct data is captured in the constructed query.
- Test As can be used to confirm the data output of the variable to different users based on their permissions settings.
- Select Add.
The owner of a scheduled job for the email delivery of a dashboard defines the user session for the emailed dashboard. If the dashboard or dashboard insights contain references to an internal session variable, the value of the internal session variable is defined by the user session of the scheduled job owner.