SOAP Session Management
SOAP web services are inherently stateless and thus do not maintain sessions. However, it is often useful to maintain a session between a web client and the web service that it uses. The InterSystems IRIS® data platform SOAP support provides a way for you to do this.
Also see Specifying Custom HTTP Requests.
And see WSDL Differences for InterSystems IRIS Sessions in Details of the Generated WSDLs.
Overview of SOAP Sessions
You can maintain a session between a web client and an InterSystems IRIS web service. This support consists of the following tools:
-
Web session management (managed by InterSystems IRIS and by the InterSystems Web Gateway).
-
The InterSystems IRIS SOAP session header, which is a simple proprietary header.
The overall flow is as follows:
-
The web client sends an initial message to the web service. This message does not include the InterSystems IRIS SOAP session header.
-
The web service receives the message and starts a new web session.
-
When the web service sends its reply, it adds the InterSystems IRIS SOAP session header to the message.
-
When the web client receives the reply, it must detect the SOAP session header and extract the session cookie. Then when the web client sends another message, it must use the cookie to create a SOAP session header in that message.
Note:
-
If the client is an InterSystems IRIS web client, the session cookie is saved automatically in the SessionCookie property of web client. Also, the client instance automatically creates the SOAP session header and includes it in all messages that it sends.
-
This step also happens automatically for .NET web clients, if the same client instance is used for all SOAP messages in the session. You may need further code for other client platforms.
-
-
The web service receives the next reply, continues the web session, and includes the SOAP session header again when it responds.
It is not necessary to include a method to log out. The web session times out after a brief interval (the timeout period for the web application).
Enabling Sessions
In order to use InterSystems IRIS support for SOAP sessions, you must be using an InterSystems IRIS web service.
-
If the web client is based on InterSystems IRIS, only one step is needed to enable SOAP session support. In your web service class, set the SOAPSESSION parameter equal to 1.
-
If you are using a third-party tool to create the web client, you are responsible for detecting the InterSystems IRIS SOAP session header element in the initial response and ensuring that the web client includes this header element in all requests during the life of the session. This header element has the following format:
<csp:CSPCHD xmlns:csp="https://www.intersystems.com/SOAPheaders"><id>value of CSPCHD token</id></csp:CSPCHD>
Using Session Information
When sessions are enabled, the web service can use the variable %session, which is an instance of %CSP.SessionOpens in a new tab. Properties of this object contain system information and any information you choose to add. Some of the commonly used properties are as follows:
-
SessionID — Unique identifier of this session.
-
EndSession — Normally this equals 0. Set this property to 1 in order to end the session.
-
Data — InterSystems IRIS multidimensional array intended to hold any custom data.
-
NewSession — Equals 1 if this is new session.
-
AppTimeout — Specifies the timeout value for the session, in seconds.
The %session object provides many other properties, as well as some methods for tasks related to sessions. For further details, see the class documentation for %CSP.SessionOpens in a new tab.