Session Parameters
A session is the connection that the user makes with the server when viewing a mashup in a visualization. You can create session parameters to store temporary data from the current user session. For example, you can use a session parameter to store a setting for the preferred style theme for a mashup. The values of session parameters are unique for each user connected to the server, and they are stored until the session ends. The session parameter data is also maintained when a user navigates between different mashups.
A session ends when a user closes the application, logs out using the Logout function, or times out after idling on the server. The default timeout period for a platform session is 30 minutes. You can configure the default timeout using the
SetPlatformSessionTimeout administrator service. For more information, see
Administrator Services.
Best Practices
• Use a database or a Thing to store data that is required for more than a single session.
• Use mashup parameters to pass data between mashups when possible. Using too many session parameters can affect performance. For more information, see
Configuring Mashup Parameters.
Using Changed Events for Session Parameter Values
You can add session parameters within the UserManagementSubsystem, then use the Session panel in Mashup Builder to create bindings to widgets, services, or functions in a mashup. When you select the panel, the available session parameters are listed.
The Data Properties panel displays a <Parameter_Name>Changed for each parameter. These events trigger only when the value of a session parameter changes on the client side. Changing the value of a parameter using the SetGlobalSessionValues service on the server does not trigger this event. To trigger an event when the value changes on the server, use the ServiceInvokeComplete event of the service that is used to update the parameter instead.
Adding Session Parameters
You can use a Thing Shape entity with one or more properties as session parameters. To add a Data Shape to the UserManagementSubsystem entity:
1. In Composer, click Browse.
2. Under System, select Subsystems, then open the UserManagementSubsystem entity.
3. Add a Thing Shape to the subsystem in one of the following ways:
◦ On the Services tab, execute the AddSessionShape service:
a. Locate the service and click
under the
Execute column. The
Execute Service dialog box opens.
b. In the name field, select the Thing Shape that contains the session parameters, then click Execute.
c. Click Done to close the dialog box.
d. Click Save to save the changes to the subsystem.
◦ On the Configuration tab, under User Session Shape Settings, click Add. A dialog box opens.
a. Type a Thing Shape name and click Add.
b. Click Save to save your changes to the subsystem.
The Thing Shape is added to the subsystem. The properties of the Data Shape are listed as bindable session parameters when you open the Session panel.
| Using an infotable with multiple rows and columns as a session parameter may reduce performance. |
For more information, see
User Management Subsystem.
Accessing Session Parameters on the Platform Server
To retrieve the session parameter values:
1. In Composer, click Browse.
2. Under System, select Resources, then open the CurrentSessionInfo resource entity.
3. On the Services tab, execute the GetGlobalSessionValues service:
a. Locate the service on the list, then under the
Execute column, click
. The
Execute Service dialog box opens.
b. Click Execute. The parameter values for the current session are displayed on the Output pane.
c. Click Done to close the dialog box.
The available session parameters are listed on the Session panel. You can use the Data panel to add the GetGlobalSessionValues service to a mashup and bind its returned values to functions, services, or widgets.
Example: Using a Session Parameter to Store Input for a Textfield Widget
The session property value is lost after refreshing the page when a widget property is bound to a session parameter directly. To keep the value when reloading the page, you must use setter and getter services to update and retrieve the parameter value.
1. Define a session parameter by following the steps in the Adding Session Parameters section.
2. Create a helper Thing that contains a service that sets the session parameter value.
3. Add an input parameter to the setter service named input_string, then add the following JavaScript code:
Resources["CurrentSessionInfo"].SetGlobalSessionStringValue({name: "your_session_var", value: input_string});
4. Create a mashup, then add a Textbox widget, a Button widget, and a Validator function.
5. Use the Data panel to add the following services:
◦ The setter service that you created in Step 2.
◦ The GetGlobalSessionValues service from the CurrentSessionInfo resource.
6. Bind the Text property of the Textfield widget to the input_string parameter of the setter service.
7. Bind the session variable under All Data property of the GetGlobalSessionValues service to the Text property of the Textfield widget.
8. Bind the Clicked event of the Button widget to setter service.
9. Bind the ServiceInvokeCompleted event of the setter service to the Evaluate service of the Validator function. Using this even ensures that the value of the session parameter is always updated before the function is executed.
10. Edit the function and add the following code to the expression:
location.reload()
11. Save and then view the mashup.
Enter a value into the text box, then click the button to reload the page. The value persists after the page is reloaded.