Concepts → External Session Variable

About an External 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 external session variable stores a scalar value or an array of values from the result of a query to an external data source.

At the start of the user’s authenticated session, Incorta invokes all the external session variables that the user has access to. From this point on, the external session variable is immutable. During the user session, if there is an update to the external data source, the updated value is not reflected in the user’s external session variable. The user will need to sign out and start a new authenticated session.

Important

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 external session variables, the values of the external session variables are defined by the user session of the scheduled job owner.

You can reference an external session variable in specific expression contexts such as a formula expression. You can assign access rights to an external session variable.

Properties of an external session variable

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 query for external session variable

Following is an example of an SQL query that would be used to create an external session variable:

SELECT tbl.employee.employee_id

FROM tbl_employees

WHERE tbl.employee.employee_id = $user

Access permissions for an External Session Variable

You can edit the availability of an external session variable from the Share dialog.

Following are the steps to access the Share dialog:

Sign in to the Incorta Direct Data Platform.
In the Navigation bar, select Schema.
In the Sub-Navigation bar of Schema, select Session Variable.
From the menu of session variables, select the share icon (people icon)
In the Share dialog, search in the With text box for user names, emails, or groups.
Using the drop down menu from selecting the right icon, assign the user the desired share properties.
Select Share.
Select Close at the bottom of the Share dialog when finished.

Following are the share property available for an external session variable:

Property	Icon	Description
Can View	eye	The user can see the external session variable when signed in and use it within an Insight.
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 properties, such as the query, of the external session variable.

Test an external session variable

If you have edit access rights to the external 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.

Note

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.

Following are the general steps to testing an external session variable:

Steps to test an external session variable

Sign in to the Incorta Direct Data Platform.
In the Navigation bar, select Schema.
In the Action bar, select + New → Session Variable → External Session Variable.
In the External Variable dialog, specify the external 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.