getWebIServerSession

The getWebIServerSession method is called only after the ESM indicates that it possesses either a valid session or a set of valid MicroStrategy Intelligence Server user credentials (that is, when a custom implementation of the handlesAuthenticationRequest has been called and it returned COLLECT_SESSION_NOW). The getWebIServerSession method creates a session object on Intelligence Server. This method is invoked only during a custom External Security workflow; in the default workflow, MicroStrategy Web creates the session object.

There is a difference between user credentials and a user session (identified by a session ID). Credentials represent the identity of an Intelligence Server user and not a specific, previously-established session for that user. A session ID, on the other hand, represents a previously-established user session.

It is the responsibility of the custom ESM to determine how to implement the getWebIServerSession method and create the session object. Some examples of how this might be done are described below:

• If only user credentials are provided in the request, the custom ESM can use them to try to create a new session object.

• If a session ID is provided in the request, the custom ESM can try to reuse the existing session.

  • If the session is valid, the custom ESM can use the existing session.    

  • If the session is invalid, the custom ESM should try to correct the problem.

When the custom ESM creates a session object, it needs certain parameters that are controlled through preferences, such as those listed below.  

• Session flags, such as result working set size  

• Logout settings, such as how to handle inbox messages when the session is closed  

• Locale ID, used for date and number formatting and for localization of error messages from MicroStrategy Intelligence Server  

However, because the values of these preferences cannot be accessed until a physical connection has been established (which occurs only after the session object is created), it makes a calculated guess as to what these settings should be. After the actual session (that is, the connection) has been created and validated, the application checks to see if the values used to create the session are the same as the values stored in Preferences. If the preferences are different and the canReconnectSession method returns "true", the application disconnects and reconnects the session, using the actual stored values of the preferences in the process.

It is important to note that the way the session is created by the custom ESM may have repercussions on settings. For example, if the session is created externally and the request does not have sufficient information (for example, it has only the session ID), the settings in the session may not be correct. Since the canReconnectSession method can be called only if there is enough information in the request to create a session, if you provide only a session ID, preferences will not be applied because this method will not be called. As a result, the application might behave differently if the appropriate user preferences are not set correctly. For example, if the working set size is not set or not set correctly, unexpected failures result or error messages are displayed.

In prior versions of the product, when the getWebIServerSession method was used to create a new session, it had to explicitly set all of these preferences and properties that are normally set by MicroStrategy Web in the default session creation process. Click here to see a code sample that illustrates how to set the working set size (to 10, in this example) in this method.

The following information is provided to help you use this method when you create a custom ESM.

• Method signature 

• Parameters 

• Return values 

• Pre-conditions 

• Post-operations

Method signature

public WebIServerSession getWebIServerSession(RequestKeys reqKeys, ContainerServices cntSvcs)

Parameters

The following parameters are passed into the getWebIServerSession method:

• reqKeys

  This parameter allows the ESM to inspect information present in the original request. This information represents a collection of cookie, URL, and FORM data key/value pairs, together with information from session variables. 

• cntSvcs

  This parameter provides a way for the ESM to directly interact with the container to do such things as inspecting session variables and other data values not exposed through the RequestKeys object or accessing values such as headers that are not available through the RequestKeys instance.

Return Values

This method returns aWebIServerSessionobject. The default implementation of this method returns NULL.

This method is never executed during the default authentication workflow since session creation is not handled by the ESM. If you implement a custom ESM that returns COLLECT_SESSION_NOW in handlesAuthenticationRequest, you must also override this method to return a valid WebIServerSession object.

Pre-conditions

This call is not made with every request. It is called whenever:

• The handlesAuthenticationRequest method returns COLLECT_SESSION_NOW (indicating that the ESM possesses either a valid session or a set of valid Intelligence Server user credentials).

Post-operations

The following operations take place after the method call is finished.

1. The returned WebIServerSession object is validated using isAlive. 

   • If isAlive returns false, the getFailureURL method is called, passing in authentication failure as the reason. The following step does not take place. 

   • If isAlive returns true, a check is made to see whether the preferences in the session object are the same as the actual values stored in the metadata as user preferences, as described in the following step.

2. The preferences in the session object are compared to the actual values stored in the metadata as user preferences. 

   • If the preferences are the same, request processing continues. 

   • If the preferences are different and the WebIServerSession object includes a user ID and password, the canReconnectSession method is called. Depending on the value returned by this method, the session may be recreated using the actual user preference stored in the metadata. In either case, request processing continues if session creation is successful.