Skip to main content

Managing Sessions

A session represents a series of requests from a particular client to a particular application over a certain period of time. InterSystems IRIS® provides session tracking automatically. Within your CSP-based web application, you can access information about the current session by examining the %session object, which is an instance of %CSP.SessionOpens in a new tab.

For information on sharing authentication sessions or data among applications, see Authentication Sharing Strategies. Also see Ending Sessions.

Session Creation

A session starts when an HTTP client makes its first request to a web application. The InterSystems IRIS server then does the following:

  1. Creates a new session ID number.

  2. Performs licensing checks, as appropriate.

  3. Creates the %session object (which is persistent).

  4. Calls the OnStartSession() method of the session event class (if present).

  5. Creates a session cookie in order to track subsequent requests from the HTTP client during the course of the session. If the client browser has disabled cookies, InterSystems IRIS automatically uses URL rewriting (placing a special value into every URL) in order to track sessions.

Basic Properties

For the first request of a session, the NewSession property of the %session object is set to 1. For all subsequent requests it is set to 0:

 If (%session.NewSession = 1) {
    // this is a new session

The SessionId property of the %session object contains the unique identifier of the session.

Managing Session Data

The %session object provides an easy way to save application-specific data across the session without using cookies or URL parameters. In particular, the Data property of this object is a multidimensional array property for use by your code. For example, suppose that you want to save the following set of key/value pairs:

Key Value
product "widgets"
quantity 100
unitofmeasure "cases"

To do this, you can save values in the Data property as follows:

 set %session.Data("product")="widgets"
 set %session.Data("quantity")=100
 set %session.Data("unitofmeasure")="cases"

Similarly, perhaps on a different page of the application, you can retrieve the values:

 set productodisplay=$GET(%session.Data("product"))
 set quantityodisplay=$GET(%session.Data("quantity"))
 set uomtodisplay=$GET(%session.Data("unitofmeasure"))

Note that this example uses $GET to prevent an error in the case when a particular subscript is not defined. It is best practice to use $GET (or $DATA) to protect against such an error.

Also note that this technique allows you to store only literal data (not object references) and each value in the array must be shorter than the long string limit.

Deleting Session Data

To remove data from the Data property, use the ObjectScript Kill command:

 Kill %session.Data("MyData")

Customizing Session Handling (Event Class)

To customize what happens when various session events occur:

  1. Define a session event class, which must be a subclass of %CSP.SessionEventsOpens in a new tab.

  2. In that class, implement the callback or callbacks to customize what the application does when the session starts, times out, or when other events occur.

    The callback methods include the following:

    • OnStartSession() — controls what happens when a session starts.

    • OnSessionEnd() — controls what happens when a session ends. Called for all session endings.

    • OnTimeout() — controls what happens when a session timeout occurs. Called only in case of timeout.

    • OnApplicationChange() — controls what happens when the user moves from one application to another within a session. (In such a case, you may want to update the session timeout value).

    For details, see %CSP.SessionEventsOpens in a new tab.

  3. Configure the web application to use this session event class.

    Or, within your application code, programmatically specify the session event class by setting the EventClass property of the %session object.

Preserving Context

By default, the only processing context preserved by the CSP server from one request to the next is held within the %session object. The CSP server provides a mechanism for preserving the entire processing context variables, instantiated objects, database locks, open devices between requests. This is referred to as context preserving mode. You can turn context preservation on or off within a CSP application at any time by setting the value of the Preserve property of the %session object. Note that tying a process to one session results in a lack of scalability and that it is very uncommon to use this option.

FeedbackOpens in a new tab