Using Session Client Data in ServiceNow - ben-vargas/servicenow-wiki GitHub Wiki

Overview:
Session Client Data allows you to store and retrieve named key-value pairs that persist throughout a user’s session. By setting these values on the server side when a session is established and then accessing them on the client side, developers can avoid unnecessary AJAX calls, improving performance and user experience. This approach enables faster data retrieval in client scripts by leveraging the data stored in the g_user object created during form load.

What Is Session Client Data?

Session client data is a collection of named strings sent from the server to the client at the start of a session. Once established, these values are readily available to client scripts on forms and lists, eliminating the need for additional server calls to fetch user-related or session-specific details. This feature ensures more efficient form loading and a smoother user experience.

Key Benefits

  • Performance Optimization:
    Accessing pre-loaded session data avoids round-trip queries (AJAX calls) to the server.

  • Flexibility:
    Developers can store arbitrary data (such as user groups or roles) and easily retrieve it on the client side.

  • Enhanced User Experience:
    Users benefit from faster page loads and responsive UI interactions.

Setting Session Client Data on the Server

When a session is established, a session.established event triggers on the server. You can respond to this event with a Script Action that sets session client data using the GlideSession API.

Steps to Set Session Client Data:

  1. Create a Script Action:

    • Navigate to System Policy > Events > Script Actions.
    • Create a new Script Action:
      • Name: Set session client values
      • Event name: session.established
      • Active: Checked
      • Synchronous: Checked (You may need to configure the form to see this field)

  2. Script Example:

    gs.getSession().putClientData('test1', 'value1');
gs.getSession().putClientData('test2', 'value2');

What This Does:

  • On session establishment, test1=value1 and test2=value2 are stored in the user’s session data.
  • These values become available to the client without requiring additional server calls.

Retrieving Session Client Data on the Client

When the user loads a form or list, ServiceNow constructs the g_user object on the client side, incorporating all previously set session client data. Client scripts can then access these values directly.

Example Client Script:

var v = g_user.getClientData('test1');
gs.addInfoMessage('Value of test1: ' + v);

Result:
The variable v contains the string 'value1' set during the session.established event.

GlideSession API Methods

The GlideSession API provides methods to manipulate session client data on the server side:

  • putClientData(name, value): Store a named value in the session.
  • getClientData(name): Retrieve a named value from the session.
  • clearClientData(name): Remove a named value from the session.

Use Cases

  • User Role/Group Lookup:
    Store user roles and group memberships at session start. Client scripts on various forms can quickly access these details for conditional logic (e.g., showing/hiding fields based on roles) without an AJAX call.

  • Session-Based Configuration:
    Pre-fetch user preferences, settings, or frequently accessed data. Allow client scripts to immediately use these values for customization.

  • Performance Optimization:
    Reduce form load times by avoiding multiple server calls, particularly in complex environments or heavily customized interfaces.

Additional Resources

Conclusion

By leveraging Session Client Data, developers can significantly improve performance and efficiency in ServiceNow applications. Setting values on the server during session establishment and retrieving them on the client avoids costly round-trip queries. This leads to faster page loading, smoother user interactions, and more scalable solutions.