Session

Session objects are returned by the Session command. The Session object is automatically created and maintained by the Qodly web server to control the session of a web client (e.g. a browser). This object provides the web developer with an interface to the user session, allowing to manage privileges, store contextual data, share information between processes, and launch session-related preemptive processes.

Functions and properties

.clearPrivileges()    removes all the privileges associated to the session
.expirationDate : string    the expiration date and time of the session cookie
.hasPrivilege( privilege : string ) : boolean    returns true if the privilege is associated to the session, and false otherwise
.idleTimeout : integer    the inactivity session timeout (in minutes), after which the session is automatically closed by Qodly
.isGuest() : boolean    returns true if the session is a Guest session (i.e. it has no privileges)
.setPrivileges( privilege : string ) .setPrivileges( privileges : collection ) .setPrivileges( settings : object )    associates the privilege(s) and/or role(s) defined in the parameter to the session
.storage : object    a shared object that can be used to store information available to all requests of the web client
.userName : string    the user name associated to the session

.clearPrivileges()

.clearPrivileges()

Parameter	Type		Description
			Does not require any parameters

Description

The .clearPrivileges() function removes all the privileges associated to the session. As a result, the session automatically becomes a Guest session.

Example

//Invalidate a session
var isGuest : boolean  

session.clearPrivileges()
isGuest = session.isGuest() //isGuest is True

.expirationDate

.expirationDate : string

Description

The .expirationDate property contains the expiration date and time of the session cookie. The value is expressed as text in the ISO 8601 format: YYYY-MM-DDTHH:MM:SS.mmmZ.

This property is read-only. It is automatically recomputed if the .idleTimeout property value is modified.

Example

var expiration : string
expiration = session.expirationDate //eg "2021-11-05T17:10:42Z"

.hasPrivilege()

.hasPrivilege( privilege : string ) : boolean

Parameter	Type		Description
privilege	string	<-	Name of the privilege to verify
Result	boolean	<-	True if session has privilege, false otherwise

Description

The .hasPrivilege() function returns true if the privilege is associated to the session, and false otherwise.

Example

You want to check if the "WebAdmin" privilege is associated to the session:

if (session.hasPrivilege("WebAdmin"))
    //Access is granted, do nothing
else
    //Display an authentication page

end

.idleTimeout

.idleTimeout : integer

Description

The .idleTimeout property contains the inactivity session timeout (in minutes), after which the session is automatically closed by Qodly.

If this property is not set, the default value is 60 (1h).

When this property is set, the .expirationDate property is updated accordingly.

The value cannot be less than 60: if a lower value is set, the timeout is raised up to 60.

This property is read write.

Example

if (session.isGuest())
        // A Guest session will close after 60 minutes of inactivity
    session.idleTimeout = 60
else
        // Other sessions will close after 120 minutes of inactivity
    session.idleTimeout = 120
end

.isGuest()

.isGuest() : boolean

Parameter	Type		Description
Result	boolean	<-	True if session is a Guest one, false otherwise

Description

The .isGuest() function returns true if the session is a Guest session (i.e. it has no privileges).

Example

if (session.isGuest())
    //Do something for Guest user
end

.setPrivileges()

.setPrivileges( privilege : string )
.setPrivileges( privileges : collection )
.setPrivileges( settings : object )

Parameter	Type		Description
privilege	string	->	Privilege name
privileges	collection	->	Collection of privilege names
settings	Object	->	object with a "privileges" property (string or collection)

Description

The .setPrivileges() function associates the privilege(s) and/or role(s) defined in the parameter to the session.

• In the privilege parameter, pass a string containing a privilege name (or several comma-separated privilege names).

• In the privileges parameter, pass a collection of strings containing privilege names.

• In the settings parameter, pass an object containing the following properties:

Property	Type	Description
privileges	string or collection	String containing a privilege name, or Collection of strings containing privilege names
roles	string or collection	String containing a role, or Collection of strings containing roles
userName	string	User name to associate to the session (optional)

info

For more information, please refer to the Privileges section.

If the privileges or roles property contains a name that is not declared, it is ignored.

By default when no privilege or role is associated to the session, the session is a Guest session.

The userName property is available at session object level (read-only).

Example

In a custom authentication method, you set the "WebAdmin" privilege to the user:

var userOK : boolean

... //Authenticate the user

if (userOK) //The user has been approved
  var info : object
  info = newObject
  info.privileges = newCollection("WebAdmin")
  session.setPrivileges(info)
end

.storage

.storage : object

Description

The .storage property contains a shared object that can be used to store information available to all requests of the web client.

When a session object is created, the .storage property is empty. Since it is a shared object, this property will be available in the storage object of the server.

Like the storage object of the server, the .storage property is always "single": adding a shared object or a shared collection to .storage does not create a shared group.

This property is read only itself but it returns a read-write object.

Example

You want to store the client IP in the .storage property:

if (session.storage.clientIP == null) //first access
    use (session.storage)
        session.storage.clientIP = newSharedObject("value", clientIP)
    end
end

.userName

.userName : string

Description

The .userName property contains the user name associated to the session. You can use it to identify the user within your code.

This property is an empty string by default. It can be set using the privileges property of the setPrivileges() function.

This property is read only.