Concepts → External Session Variable
About an external session variable
An external session variable is a tenant object that defines a SELECT command for an SQL statement to an external data source. In this regard, the adjective “external” describes a reference to the external data sources defined within a given tenant.
When a user signs in to the Analytics Service, the Analytics Service — as a web application — creates a session (HttpSession in Apache Tomcat) for the user. A session maintains state information between requests for a particular user of a web application.
The first time the user invokes an external session variable — usually by means of a calling expression such a formula expression — the Analytics Services creates an instance of the variable for the user, executes the SELECT query for the external data source, and then assigns the query result as the variable value for the given user’s session. From the results of the SELECT query, the value can be a scalar value of type String or an array of values of the type String. The value for an external session variable is mutable.
You can use the Schema Manager to create and test an external session variable. You can reference an external session variable in specific expression contexts such as a formula expression or filter expression. You can assign access rights to an external session variable.
Properties of an external session variable
The following are the properties of an external session variable:
| Property | Control | Description |
|---|---|---|
| Name | text box | Enter the name of the external session variable |
| Description | text box | Optional description of external session variable. |
| Data Source | drop down list | Select the data source to query data for use in the external session variable. |
| Query | text box | Construct the query to request data from a data source. Query result will be the external session variable value. |
Example of the Query property for an external session variable
In the following example, the WHERE clause references the $user miscellaneous system variable.
SELECT ID FROM USER WHERE LOGINNAME = $userEven though ID is of the tpye INT in this example, the external session variable stores the scalar value as string or as an array of scalar values as strings.
Access rights for an external session variable
A SuperUser (tenant administrator) or a user that belongs to a group assigned the SuperRole or the Schema Manager role can create, view, and edit the external session variables in a given tenant.
Only a SuperUser (tenant administrator) or a user that belongs to a group assigned the SuperRole can view, edit, and share all session variables, regardless of ownership.
The following are the available access rights for an external session variable:
| Property | Icon | Description |
|---|---|---|
| Can View | eye | The user can View the external session variable, for example, in the Formula Builder |
| Can Share | node tree | The user is able to Share the external session variable with other users |
| Can Edit | pen and paper | The user is able to Edit the external session variable |
Test an external session variable
If you have edit access rights to the an external session variable and belong to a group with the necessary role access permission such as Schema Manager or SuperRole, 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 external session variable is independent of the current user’s session. As such, if the external data source is updated during your session the test result will reflect the change. Your session’s captured value of the external session variable will not express this update. You will need to sign out and start a new session to have your external session variable value updated.
Steps to test an external session variable
Here are the steps to test an external session variable:
- Sign in to the Incorta Direct Data Platform.
- In the Navigation bar, select Schema.
- In the Schema Manager, select the Session Variables tab.
- In the list view, select an external session variable.
-
In the External Variable dialog, select on of the following:
- Select Test to view the result as the current user.
- Select Test As, and then select a user to view the results as that user.
- Select Cancel.
Additional considerations for an external session variable
Here are some additional considerations for working with an external session variable:
- Conversion
- Modification
- Owner of a scheduled job
Conversion
Regardless of the source data type, an external session variable stores a scalar value as a string or array of scalar values as strings. When you use an external 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.
Modification
If the owner or a user that belongs to a group with Edit access rights to the an external session variable alters the query expression for the variable object and saves the modifications, the Analytics Service deletes the session variable for all other active users. For this reason, schema developers should be wary of altering external session variables in production while not in maintenance window. When a user invokes the external session variable again, the Analytics Services creates a new instance of the variable for the user.
Owner of scheduled job
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 external session variable, the value of the variable is defined by the user session of the scheduled job owner.