Parameters	Properties	Methods	Queries	Indices	ForeignKeys	Triggers
	42	58	2

Properties
AppTimeout	Application	BrowserName	BrowserPlatform
BrowserVersion	CSPSessionCookie	CreateTime	Data
Debug	EndSession	ErrorPage	EventClass
HttpAuthorization	KeepAlive	Key	Language
LastModified	LicenseId	Namespace	NewSession
Preserve	ProcessId	RunNamespace	SecureSessionCookie
SessionId	UseSessionCookie	UserAgent	Username

Methods
%%OIDGet	%AddToSaveSet	%AddToSyncSet	%BuildIndices
%CheckUnique	%ClassIsLatestVersion	%ClassName	%ComposeOid
%ConstructClone	%Delete	%DeleteExtent	%DeleteId
%DispatchClassMethod	%DispatchGetModified	%DispatchGetProperty	%DispatchMethod
%DispatchSetModified	%DispatchSetMultidimProperty	%DispatchSetProperty	%Exists
%ExistsId	%Extends	%GUID	%GUIDSet
%GetLock	%GetParameter	%GetSwizzleObject	%Id
%IsA	%IsModified	%KillExtent	%LockExtent
%LockId	%New	%NormalizeObject	%ObjectModified
%Oid	%OnBeforeAddToSync	%OnDetermineClass	%Open
%OpenId	%OriginalNamespace	%PackageName	%PurgeIndices
%Reload	%RemoveFromSaveSet	%ResolveConcurrencyConflict	%RollBack
%Save	%SaveDirect	%SerializeObject	%SetModified
%SortBegin	%SortEnd	%SyncObjectIn	%SyncTransport
%UnlockExtent	%UnlockId	%ValidateObject	CompleteTwoFactorLogin
DebugSet	EndSessionSet	EventClassAdd	EventClassClear
EventClassExists	EventClassGet	EventClassList	EventClassRemove
EventClassSet	ExtentClose	ExtentExecute	ExtentFetch
Get	GetLinkTargets	IsDefined	Kill
Lock	Login	Logout	LogoutAll
NewSessionSet	Next	PreserveSet	RunNamespaceFind
RunNamespaceGet	RunNamespaceSet	SessionInfoClose	SessionInfoExecute
SessionInfoFetch	Set	StickyLoginGet	StickyLoginSet
Unlock	UsernameGet

• property AppTimeout as %Integer [ 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 which is set in the Cache configuration manager, this is often 900 seconds or 15 minutes.

For no timeout, set this property to 0.

• property Application as %String(MAXLEN=256);

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 BrowserName as %String(MAXLEN="");

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 BrowserPlatform as %String(MAXLEN="");

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 BrowserVersion as %String(MAXLEN="");

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 CSPSessionCookie as %String;

Used by the CSP Gateway to store the session Id on the browser. Do not alter this property.

• property CreateTime as %TimeStamp;

The data/time the session was created in UTC

• 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 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 EndSession as %Boolean [ InitialExpression = 0 ];

A flag that you set to '1' to terminate this session upon completion of this request.

• property ErrorPage as %String(MAXLEN="");

If set then use this page as the error page rather than the one obtained from the CSP application settings.

• property EventClass as %String(MAXLEN=256) [ 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 HttpAuthorization as %String(MAXLEN="");

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 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 Key as %String;

Stores the encryption key used to validate and secure the communication with the browser. This key never leaves Cache.

• 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 LastModified as %TimeStamp;

The date/time when this session was last modified in UTC

• property LicenseId as %String(MAXLEN=128);

Internal property that hold the name of the license that this session is associated with

• 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 NewSession as %Boolean [ InitialExpression = 1 ];

Indicates whether this is the first request of the session (True) or a subsequent request (False).

• 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 Cache 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 ProcessId as %String;

Process Id

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

• 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 SecureSessionCookie as %Boolean [ InitialExpression = 0 ];

Internal property to determine if we should send the 'secure' flag with the sessionId cookie

• 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 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 UserAgent as %String(MAXLEN="");

Contains the HTTP_USER_AGENT CGI variable passed in the initial session request.

• property Username as %String(MAXLEN=128) [ Calculated ];

The username this CSP session is logged in as.

• 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 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

This is a Get accessor method for the EventClass property.

• 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

• 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 Cache 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

This is a Set accessor method for the NewSession property.

• final method Next(index As %String = "") as %String

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 RunNamespaceFind(application As %String) as %String

• method RunNamespaceGet() as %String

This is a Get accessor method for the RunNamespace property.

• method RunNamespaceSet(val As %String, app As %String) as %Status

This is a Set accessor method for the RunNamespace property.

• 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 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 Cache 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 Cache 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.

• method UsernameGet() as %String

Get method for Username property.

• 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