Skip to main content

%CSP.Session

persistent class %CSP.Session extends %Library.Persistent

SQL Table Name: %CSP.Session

The %CSP.Session class represents a session within a CSP application.

Property Inventory

Method Inventory

Properties

property AppTimeout as %Integer (MAXVAL = 31536000, MINVAL = 0) [ InitialExpression = 900 ];
Specifies the timeout value for the session in seconds.

If no user requests are received within the specified time period, then the session will end. The default value comes from the CSP application setting for the application that the session starts in which is set in the configuration manager, this is often 900 seconds or 15 minutes. Note that if you start a session in one applicaiton and move to another application the AppTimeout will not be changed to the new applications timeout value, if you wish to modify this when the application changes you can use the session events 'OnApplicationChange' method.

For no timeout, set this property to 0.

Property methods: AppTimeoutDisplayToLogical(), AppTimeoutGet(), AppTimeoutIsValid(), AppTimeoutLogicalToDisplay(), AppTimeoutNormalize(), AppTimeoutSet()
property Application as %String);
Stored the CSP application name so we can detect when the CSP application has changed. This is required so we can revalidate the user against any security permissions the other application requires that the first application does not. This is not set until the security context for this application is validated.
Property methods: ApplicationDisplayToLogical(), ApplicationGet(), ApplicationIsValid(), ApplicationLogicalToDisplay(), ApplicationLogicalToOdbc(), ApplicationNormalize()
property BrowserName as %String);
This property contains the browser name based on parsing the HTTP_USER_AGENT CGI variable. This property is set once when the session is created. Possible values are "IE", "Mozilla", "Netscape", "Safari" and "". Not all possible browsers are suppported and the value "" is used for unknown browsers. "Mozilla" is used for all Mozilla based browsers such as Mozilla and Firefox.
Property methods: BrowserNameDisplayToLogical(), BrowserNameIsValid(), BrowserNameLogicalToDisplay(), BrowserNameLogicalToOdbc(), BrowserNameNormalize(), BrowserNameSet()
property BrowserPlatform as %String);
This property contains the browser operating system based on parsing the HTTP_USER_AGENT CGI variable. This property is set once when the session is created. Possible values are "Windows", "Macintosh", "X11" and "". Not all possible browsers are supported and the value "" is used for unknown browsers.
Property methods: BrowserPlatformDisplayToLogical(), BrowserPlatformIsValid(), BrowserPlatformLogicalToDisplay(), BrowserPlatformLogicalToOdbc(), BrowserPlatformNormalize(), BrowserPlatformSet()
property BrowserVersion as %String);
This property contains the browser version based on parsing the HTTP_USER_AGENT CGI variable. This property is set once when the session is created. The version is "" or in the format "major.minor". Not all possible browsers are supported and the value "" is used for unknown browsers.
Property methods: BrowserVersionDisplayToLogical(), BrowserVersionIsValid(), BrowserVersionLogicalToDisplay(), BrowserVersionLogicalToOdbc(), BrowserVersionNormalize(), BrowserVersionSet()
property CSPSessionCookie as %String);
Used by the CSP Gateway to store the session Id on the browser. Do not alter this property.
Property methods: CSPSessionCookieDisplayToLogical(), CSPSessionCookieGet(), CSPSessionCookieIsValid(), CSPSessionCookieLogicalToDisplay(), CSPSessionCookieLogicalToOdbc(), CSPSessionCookieNormalize(), CSPSessionCookieSet()
property CreateTime as %TimeStamp;
The data/time the session was created in UTC
Property methods: CreateTimeDisplayToLogical(), CreateTimeGet(), CreateTimeIsValid(), CreateTimeLogicalToDisplay(), CreateTimeNormalize(), CreateTimeOdbcToLogical()
property Data as %String [ MultiDimensional ];
The place users can preserve any data within a session. You can set values into this multidimensional property using:
  Set %session.Data(1,2,"string")="value"
  Write %session.Data("Key1","Key2"),!
  Merge %session.Data(5)=array
  
This is faster than using the Get() and Set()
Property methods: DataDisplayToLogical(), DataGet(), DataIsValid(), DataLogicalToDisplay(), DataLogicalToOdbc(), DataNormalize(), DataSet()
property Debug as %Boolean [ InitialExpression = 0 ];
This is true when this CSP session is being debugged, and false otherwise. It is set automatically by the CSP dispatch engine and you should not alter its value yourself.
Property methods: DebugDisplayToLogical(), DebugGet(), DebugIsValid(), DebugLogicalToDisplay(), DebugNormalize()
property EndSession as %Boolean [ InitialExpression = 0 ];
A flag that you set to '1' to terminate this session upon completion of this request.
Property methods: EndSessionDisplayToLogical(), EndSessionGet(), EndSessionIsValid(), EndSessionLogicalToDisplay(), EndSessionNormalize()
property ErrorPage as %String);
If set then use this page as the error page rather than the one obtained from the CSP application settings.
Property methods: ErrorPageDisplayToLogical(), ErrorPageGet(), ErrorPageIsValid(), ErrorPageLogicalToDisplay(), ErrorPageLogicalToOdbc(), ErrorPageNormalize(), ErrorPageSet()
property EventClass as %String) [ Calculated ];
The name of the application event class to be called in response to certain CSP events. This should be a class derived from %CSP.SessionEvents. At present the events that are fired are for creation of a new session (OnStartSession), deletion of a session (OnEndSession) and the timeout of an existing session by the CSP daemon (OnTimeout). You can set the event class for a CSP application in the CSP options of the configuration manager. Note that if you set the EventClass inside a CSP page then as the session has already been created at this point it will not fire the OnStartSession event, if the EventClass is set in the CSP application settings then it will fire the start session event as it knows which event class to call before it creates the session.
Note that this adds this event class to the list unless it is already present and will not replace any existing event class. Setting this to "" will not have any effect, if you wish to remove an EventClass then call EventClassRemove()
Property methods: EventClassDisplayToLogical(), EventClassIsValid(), EventClassLogicalToDisplay(), EventClassLogicalToOdbc(), EventClassNormalize()
property HttpAuthorization as %String);
If we are passed an 'Authorization' HTTP header the value is stored here to avoid attempting to login with this multiple times, for internal use only.
Property methods: HttpAuthorizationDisplayToLogical(), HttpAuthorizationGet(), HttpAuthorizationIsValid(), HttpAuthorizationLogicalToDisplay(), HttpAuthorizationLogicalToOdbc(), HttpAuthorizationNormalize(), HttpAuthorizationSet()
property KeepAlive as %Boolean [ InitialExpression = 1 ];
If true and the CSP gateway supports this then use the HTTP keep alive support to reuse the TCP/IP connection for any additional HTTP requests. If possible you should also supply the Content-Length header otherwise the CSP gateway will have to buffer the output in order to add the length of the message to the header. The default for this property is true to keep the connection alive where possible except for HTTP/1.0 responses where we will use the default for HTTP/1.0 which is to close the connection on each request.
Property methods: KeepAliveDisplayToLogical(), KeepAliveGet(), KeepAliveIsValid(), KeepAliveLogicalToDisplay(), KeepAliveNormalize(), KeepAliveSet()
property Key as %String;
Stores the encryption key used to validate and secure the communication with the browser. This key never leaves the server.
Property methods: KeyDisplayToLogical(), KeyGet(), KeyIsValid(), KeyLogicalToDisplay(), KeyLogicalToOdbc(), KeyNormalize()
property Language as %String;
The language (RFC 1766 format) in which pages in this CSP session are to be displayed. The %session Language attribute is used as the default language for csp:text, span and div tags if %response.Language is not set. If %session.Language is not set by the program, then it will default to the best fit with the HTTP_ ACCEPT_LANGUAGE CGI variable.
Property methods: LanguageDisplayToLogical(), LanguageGet(), LanguageIsValid(), LanguageLogicalToDisplay(), LanguageLogicalToOdbc(), LanguageNormalize(), LanguageSet()
property LastModified as %TimeStamp;
The date/time when this session was last modified in UTC
Property methods: LastModifiedDisplayToLogical(), LastModifiedGet(), LastModifiedIsValid(), LastModifiedLogicalToDisplay(), LastModifiedNormalize(), LastModifiedOdbcToLogical()
property LicenseId as %String);
Internal property that hold the name of the license that this session is associated with
Property methods: LicenseIdDisplayToLogical(), LicenseIdGet(), LicenseIdIsValid(), LicenseIdLogicalToDisplay(), LicenseIdLogicalToOdbc(), LicenseIdNormalize()
property Namespace as %String;
The namespace this session was created from. This is set automatically when the class is created to the current namespace. It is used by the session daemon so that it can swap to the right namespace to run the timeout method on applications.
Property methods: NamespaceDisplayToLogical(), NamespaceGet(), NamespaceIsValid(), NamespaceLogicalToDisplay(), NamespaceLogicalToOdbc(), NamespaceNormalize(), NamespaceSet()
property NewSession as %Boolean [ InitialExpression = 1 ];
Indicates whether this is the first request of the session (True) or a subsequent request (False).
Property methods: NewSessionDisplayToLogical(), NewSessionGet(), NewSessionIsValid(), NewSessionLogicalToDisplay(), NewSessionNormalize()
property Preserve as %Integer [ InitialExpression = 0 ];
A flag specifying the level of state preservation required by this session. You can change the value of this flag at any time.

This can take one of the following values:

  • 0 The only state information that is preserved is the information in the %session object.
  • 1 The entire state of the session process is preserved from one request to the next. This means that you tie up this process for just this one user. As it uses the same process all local variables, locks, etc. are preserved from one request to the next.
Property methods: PreserveDisplayToLogical(), PreserveGet(), PreserveIsValid(), PreserveLogicalToDisplay(), PreserveNormalize()
property ProcessId as %String;
Process Id

If a session has Preserve=1 this contains the process id in which the session is running.>

Property methods: ProcessIdDisplayToLogical(), ProcessIdGet(), ProcessIdIsValid(), ProcessIdLogicalToDisplay(), ProcessIdLogicalToOdbc(), ProcessIdNormalize(), ProcessIdSet()
property Referrer as %String);
Original referrer when session was created, copied from the HTTP_REFERER %request value
Property methods: ReferrerDisplayToLogical(), ReferrerGet(), ReferrerIsValid(), ReferrerLogicalToDisplay(), ReferrerLogicalToOdbc(), ReferrerNormalize()
property RunNamespace as %String;
If set then run this session in the namespace given rather than the one determined by the CSP application. If the application then switches applications again it will revert to the namespace determined by the CSP application.
Property methods: RunNamespaceDisplayToLogical(), RunNamespaceIsValid(), RunNamespaceLogicalToDisplay(), RunNamespaceLogicalToOdbc(), RunNamespaceNormalize()
property SecureSessionCookie as %Boolean [ InitialExpression = 0 ];
Internal property to determine if we should send the 'secure' flag with the sessionId cookie
Property methods: SecureSessionCookieDisplayToLogical(), SecureSessionCookieGet(), SecureSessionCookieIsValid(), SecureSessionCookieLogicalToDisplay(), SecureSessionCookieNormalize(), SecureSessionCookieSet()
property SessionId as %String;
The session id value for this session.

The session id is a system-assigned unique value that identifies this session.

Property methods: SessionIdDisplayToLogical(), SessionIdGet(), SessionIdIsValid(), SessionIdLogicalToDisplay(), SessionIdLogicalToOdbc(), SessionIdNormalize(), SessionIdSet()
property SessionScope as %Integer (DISPLAYLIST = ",None,Lax,Strict", VALUELIST = ",0,1,2") [ InitialExpression = 2 ];
Property to determine how strictly to restrict the domain of the sessionId cookie. Options are None (0), Lax (1), and Strict (2), where Strict means the cookie can only be used within the current application. Defaults to the CSP application's corresponding setting. Applications default to Strict unless otherwise configured. Note that None is invalid for insecure (HTTP) connections.
Property methods: SessionScopeDisplayToLogical(), SessionScopeGet(), SessionScopeIsValid(), SessionScopeLogicalToDisplay(), SessionScopeNormalize(), SessionScopeSet()
property UseSessionCookie as %Integer [ InitialExpression = 1 ];
Indicates whether sessions should be maintained using cookies or not. There are three possible values:
  • 0 - Never use cookies. This will pass the CSPCHD parameter around in all the url links and as hidden fields in the <FORM> elements.
  • 1 - Auto detect cookie support. This will start by trying to insert a cookie into the browser, if this fails it will switch to mode 0 and never use cookies for this session. The initial page will send both cookies to the browser and it will include the CSPCHD parameter in all links and forms.
  • 2 - Always use cookies. This will only use cookies so if the browser does not accept the cookie then the session state will not be maintained.
Property methods: UseSessionCookieDisplayToLogical(), UseSessionCookieGet(), UseSessionCookieIsValid(), UseSessionCookieLogicalToDisplay(), UseSessionCookieNormalize(), UseSessionCookieSet()
property UserAgent as %String);
Contains the HTTP_USER_AGENT CGI variable passed in the initial session request.
Property methods: UserAgentDisplayToLogical(), UserAgentGet(), UserAgentIsValid(), UserAgentLogicalToDisplay(), UserAgentLogicalToOdbc(), UserAgentNormalize(), UserAgentSet()
property UserCookieScope as %Integer (DISPLAYLIST = ",None,Lax,Strict", VALUELIST = ",0,1,2") [ InitialExpression = 2 ];
Property to determine which SameSite attribute to send with user-created cookies. Options are None (0), Lax (1), and Strict (2). Defaults to the CSP application's corresponding setting. Applications default to Strict unless otherwise configured. Note that None is invalid for insecure (HTTP) connections.
Property methods: UserCookieScopeDisplayToLogical(), UserCookieScopeGet(), UserCookieScopeIsValid(), UserCookieScopeLogicalToDisplay(), UserCookieScopeNormalize(), UserCookieScopeSet()
property Username as %Library.Username [ Calculated ];
The username this CSP session is logged in as.
Property methods: UsernameDisplayToLogical(), UsernameIsValid(), UsernameLogicalToDisplay(), UsernameLogicalToOdbc(), UsernameNormalize()

Methods

method BrowserNameGet() as %String
method BrowserPlatformGet() as %String
method BrowserVersionGet() as %String
method CompleteTwoFactorLogin(EnteredToken As %String, apperr As %Status) as %Status
If this application has a Two-Factor-Authentication enabled, when this method allows you to finish the second part of the authentication. For example, a security token was sent during the initial login attempt, Login^%CSP.Session(). You must obtain this security code (an 8-character numeric string) and call CompleteToFactorLogin() to complete authencation for this user. Note: This should only be called if Login^%CSP.Session() returns a status of $$$CSPPendingTwoFactorAuthentication Returns: $$$CSPSecondFactorLoginFailed if request's application was not Two-Factor-Authentication enabled Returns: $$$OK if login was completed Returns: $$$CSPSecurityTokenMismatch is a token was found, but did not match the entered token, else returns the error code which cause the completion to fail
method DeletePersistentHeader(name As %String)
Remove a persistent header from the session Note that name is not case sensitive
method EventClassAdd(class As %String, namespace As %String) as %Status
Add an event class to the list of classes we will callback. If the class is already present we will remove it and add this at the front of the list. The namespace is optional and will default to the current namespace.
method EventClassClear() as %Status
Remove all event classes from the event class list
method EventClassExists(class As %String, namespace As %String) as %Boolean
Return true if this event class is present in the current session event list or false otherwise. The namespace is optional and will default to the current namespace.
method EventClassGet() as %String
method EventClassList(ByRef Array As %String) as %Status
Return an array of Array(namespace,classname)="" of the currently defined event classes
method EventClassRemove(class As %String, namespace As %String) as %Boolean
Remove an event class from the set of event classes we will run on session events. The namespace is optional and will default to the current namespace. Returns true if it removed the class and false if it did not. If class is null then it will remove all event classes defined in this namespace.
final method Get(index As %String, default As %String = "") as %String
Get the value of the user data at index. This is equivalent to:
  Write $Get(%session.Data(index),default)
  
It is faster to access the property directly rather than use the Get() and Set() methods. These are kept for backward compatibility.
method GetLinkTargets(link As %String, ByRef targetUsername As %String, ByRef targetAppName As %String, ByRef targetNamespace As %String) as %Integer
CheckLinkAccess determines whether the target user is permitted to view a given CSP or Zen page based on the security requirements for the relevant target Web application, the underlying page class, and any custom resources applied to the link.

Positive return values indicate that there is already enough information to determin if the link should be enabled (Target variables may be undefined.). Negative values indicate that further processing needs to be done. Checking that the Target User can be logged into the Target Application and/or checking if the link's page has target resources which the Target User must have privileges to.

Returns 0 if the link is not to a csp application. (enable)

Returns 1 if the user is permitted access to the page. (enable)

Returns 2 if could not determine Target User. Clicking on link will bring up login page. (choice: enable or disable)

Returns 3 if the user doesn't have access to the CSP application.(disable)

Returns 4 if the user doesn't have resources specific to the page.(disable)

Returns -1 if check both if the Target User can log into the Target Application and check the Page's resources if any.

Returns -2 just check for access to the link's Page's resources, if any.

  1. It is assumed the GetLinkTargets is called from a context in which %request is available, ie, from callpage in the CSP Server
  2. Definitions:
    1. Source application - application in which the current caller is being run
    2. Current user - ($Username) the user currently logged into the Source Application
    3. Target Application - the application pointed to by the link
    4. Target User - the computed username under which the user will be logged into the Target Application
    5. Target Page: the page portion of the link, e.g., /csp/app/mypage.csp: mypage.csp

This method is meant to be called from the link's containing page within the context of the CSP server. The containing page is part of a session's current application.

We must be able to detemine which target user will be used to check privileges. The target user cannot be determined if the source and target applications are different and the target is neither part of an active by-id group nor sharing-sessions with the source application.

Applications share sessions when:

  • The source and target are the same application.
  • The link to the target page contains CSPSHARE=1.
  • Source and target applications have the same Session Cookie Path.

Who is the target user?

Since this is called from with a CSP session, there are the following situations:

  1. The target application is a member of an authenticated by-id group. That group's authenticated user is the Target User.
  2. If the target application will be in the current session, the CSP server has already handled logic for determing the user.
    1. The session's user is not UnknownUser. The target user is $Username.
    2. The session's user is UnknownUser
      • If the target application is the same as the source application, the Target User is UnknownUser.
      • If the target application is different, the target user is the user from the session's Sticky-context. If the session has no sticky-context, the Target User will be UnknownUser

CheckLinkAccess Policies

  • If the Target Application is not a CSP Application, return ENABLE/UNKNOWN
  • If the Source and Target application are the same, return CHECK_RESOURCES_ONLY.
  • If the Target Application is not enabled, return NO_APP_ACCESS
  • If the Target Application is part of an authenticated By-ID group, set Target User to group's User, return CHECK_ALL
  • If the Target Application is part of an authenticated By-Session group, set Target User to group's User, return CHECK_ALL
  • If the Target Application is neither in an authenticated by-id group nor in the Source Application's session, return ENABLE/UNKNOWN
  • If an exception occurs, return NO_ACCESS_TO_RESOURCE
method GetPersistentHeader(name As %String) as %String
Return the value of the persistent session name header. Note that name is not case sensitive
method GlobalReplace(source As %String, dest As %String)
deprecated final method IsDefined(index As %String) as %Boolean
Tests if a name-value pair name is defined in the user data. This has been deprecated in favour of the faster syntax:
  Write $Data(%session.Data(index))
  
final method Kill(index As %String = "")
Remove the index from the user data Data. This has been deprecated in favour of the faster syntax:
  Kill %session.Data(index)
  ; Or if index=""
  Kill %session.Data
  
method Lock(timeout As %Integer) as %Status
Lock the ^%cspSession global to prevent other InterSystems IRIS processes accessing this objects storage. By default the ^%cspSession global is locked so you only need to call this in rare cases where you use the Unlock() and you wish to reaquire the lock afterwards.
method Login(username As %String, password As %String = "", type As %Integer = 0, oldpassword As %String, apperr As %Status) as %Status
Login with this username and password, returns a status code to show if it worked or not. This method also trades license units at the same time so this CSP session will be logged in as a named user. If you pass type=1 then this will trade licenses only and not login as this user. After the login completes it also updates the property Username to match the $username value this session is logged in as. The property LicenseId is also updated to be the license identifier that this session is logged in with.
If a login fails then the property Username and property LicenseId will remain at their previous values. If you pass oldpassword then this will attempt to change the password of username from oldpassword to password and login as this user. Note new status return values: CSP applications can be two-factor-enabled. If the current application is one such, then if Login() successfully authenticates the username/password, it does not return $$$OK, but rather $$$CSPPendingTwoFactorAuthentication. During Two-Factor Authentication, an 8-character numeric security string will be sent to the user's cellphone. You must obtain this string from the user and call CompleteTwoFactorLogin^%CSP.Session() to complete authentication of this user. Also note that if the login SUCCEEDS (status returned will be $$$OK), but you were unable to secure a license, the new apperr parameter will have the value of $$$CSPErrorTradeLicense. In such a case, you may have to call the Login function again to trade a license. If you are calling merely to trade a license (type=1), then if the license trade fails, Login will return a status of $$$CSPErrorTradeLicense.
method Logout(force As %Integer = 0)
This call logs out the current session. The EndSession is not set to 1. This call uses the stored security context from the Event Class Context to call "OnLogout" Event Class callbacks, so the caller of Logout() must have sufficient privileges to call $System.Security.Users.ImportSecurityContext() if callbacks exist. The OnLogout callback may set EndSession to 1, if desired. The Session is logged out only if there are no callbacks, the "OnLogout" callbacks return $$$OK, or 'force' is true. If the caller has the %All role, the login cookie will also be destroyed and any pending second factor tokens for this session will be deleted. Note: Caller must do a %SaveData() on the session instance
method LogoutAll(username As %String = "")
Logout all CSP sessions for the indicated user. Callbacks can't stop logout The login cookie and any pending-second-factor logins are cancelled. Note: username="" implies username=$username. Note: $Roles must have "%All" to call this Note: LogoutAll calls %SaveData on the changed sessions.
method NewSessionSet(val As %Boolean) as %Status
Return the next index in the user data Data. This has been deprecated in favour of the faster syntax:
  Write $Order(%session.Data(index))
  
method ReferrerSet(val As %String) as %Status
method RunNamespaceFind(application As %String) as %String
method RunNamespaceGet() as %String
method RunNamespaceSet(val As %String, app As %String) as %Status
final method Set(index As %String, value As %String)
Set the value of the user data at index to value. This is equivalent to:
  Set %session.Data(index)=value
  
It is faster to access the property directly rather than use the Get() and Set() methods. These are kept for backward compatibility.
method SetPersistentHeader(name As %String, value As %String)
Set a persistent HTTP header values in the %session object so it will be output for every response from this session. If there is already a header with this name then this will overwrite this prioir header.
method Unlock(save As %Boolean = 1) as %Status
Unlock the ^%cspSession global so that another process can access this objects storage at the same time. Normally all accesss to the session object is serialised so that only one process can modify the session object at any time. So if you are using frames for example the same CSP user will make requests to get all frames at once, but these will be serialised on the application server side. If you know that a frame will take a while to generate but you do not wish this to hold up the generation of the other frames and you do not need to modify the session object you can call Unlock to unlock this session object so other processors can access it. This should be used with care. The save is for internal use only, by default when you call Unlock if the session is modified we will save the changes before unlocking the session.
method UsernameGet() as %String
Get method for Username property.

Queries

query Extent()
Selects ID As %String
Standard extent query
query SessionInfo()
Selects ID As %String, Username As %String, Preserve As %Integer, Application As %String, Timeout As %TimeStamp, LicenseId As %String, SesProcessId As %String, AllowEndSession
Standard extent query

Indexes

index (IDKEY on ) [IdKey, Type = key];
Index methods: IDKEYCheck(), IDKEYDelete(), IDKEYExists(), IDKEYOpen(), IDKEYSQLCheckUnique(), IDKEYSQLExists(), IDKEYSQLFindPKeyByConstraint(), IDKEYSQLFindRowIDByConstraint()

Inherited Members

Inherited Methods

FeedbackOpens in a new tab