Version: 20 R5 BETA

Session

Session objects are returned by the Session command. These objects provide the developer with an interface allowing to manage the current user session and execute actions such as store contextual data, share information between session processes, launch session-related preemptive processes, or (web only) manage privileges.

Types de sessions

Trois types de sessions sont pris en charge par cette classe :

Web user sessions: Web user sessions are available when scalable sessions are enabled in your project. Elles sont utilisées pour les connexions Web et REST, et peuvent se voir attribuer des privilèges.
Remote client user sessions: In client/server applications, remote users have their own sessions managed on the server.
Stored procedures session: All stored procedures executed on the server share the same virtual user session.

note

The availability of properties and functions in the Session object depend on the session type.

Sommaire


.clearPrivileges() : Boolean removes all the privileges associated to the session and returns True if the execution was successful
.expirationDate : Text the expiration date and time of the session cookie
.hasPrivilege( privilege : Text ) : Boolean returns True if the privilege is associated to the session, and False otherwise
.id : Text the unique identifier (UUID) of the session on the server
.idleTimeout : Integer the inactivity session timeout (in minutes), after which the session is automatically closed by 4D
.info : Object describes the remote client or stored procedure session on the server
.isGuest() : Boolean returns True if the session is a Guest session (i.e. it has no privileges)
.setPrivileges( privilege : Text ) : Boolean .setPrivileges( privileges : Collection ) .setPrivileges( settings : Object ) : Boolean associates the privilege(s) and/or role(s) defined in the parameter to the session and returns True if the execution was successful
.storage : Object a shared object that can be used to store information available to all processes of the session
.userName : Text the user name associated to the session

Session

Historique

Release	Modifications
20 R5	Prise en charge des sessions utilisateurs distants et procédures stockées
18 R6	Ajout

Session : 4D.Session

Paramètres	Type		Description
Résultat	4D.Session	<-	Objet session

Description

The Session command returns the Session object corresponding to the current user session.

Selon le process à partir duquel la commande est appelée, la session utilisateur courante peut être :

a web session (when scalable sessions are enabled),
une session de client distant,
la session des procédures stockées.

For more information, see the Session types paragraph.

If the command is called from a non supported context (single-user application, scalable sessions disabled...), it returns Null.

Sessions Web

The Session object of web sessions is available from any web process:

On Web Authentication, On Web Connection, and On REST Authentication database methods,
code traité par les balises 4D dans les pages semi-dynamiques (4DTEXT, 4DHTML, 4DEVAL, 4DSCRIPT/, 4DCODE)
méthodes projet avec l'attribut "Disponible via balises HTML et URLs 4D (4DACTION...)" et appelées via les urls 4DACTION/
On Mobile App Authentication and On Mobile App Action database methods for mobile requests,
ORDA functions called with REST requests.

For more information on web user sessions, please refer to the Web Server Sessions section.

Sessions clients distants

The Session object of remote client sessions is available from:

Project methods that have the Execute on Server attribute (they are executed in the "twinned" process of the client process),
Les Triggers,
On Server Open Connection and On Server Shutdown Connection database methods.

For more information on remote user sessions, please refer to the Remote client user sessions paragraph.

Session des procédures stockées

Tous les process des procédures stockées partagent la même session d'utilisateur virtuel. The Session object of stored procedures is available from:

methods called with the Execute on server command,
On Server Startup, On Server Shutdown, On Backup Startup, On Backup Shutdown, and On System event database methods

For information on stored procedures virtual user session, please refer to the 4D Server and the 4D Language page.

Exemple

You have defined the action_Session method with attribute "Available through 4D tags and URLs". Vous appelez la méthode en saisissant l'URL suivant dans votre navigateur :

IP:port/4DACTION/action_Session

  //action_Session method
 Case of
    :(Session#Null)
       If(Session.hasPrivilege("WebAdmin")) //calling the hasPrivilege function
          WEB SEND TEXT("4DACTION --> Session is WebAdmin")
       Else
          WEB SEND TEXT("4DACTION --> Session is not WebAdmin")
       End if
    Else
       WEB SEND TEXT("4DACTION --> Session is null")
 End case

.clearPrivileges()

Historique

Release	Modifications
18 R6	Ajout

.clearPrivileges() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	True si l'exécution est réussie

Description

note

Since privileges are only supported in web user sessions, this function does nothing and always returns False in other session types.

The .clearPrivileges() function removes all the privileges associated to the session and returns True if the execution was successful. En résultat, la session devient automatiquement une session Guest.

Exemple

//Invalider une session
var $isGuest : Boolean
var $isOK : Boolean

$isOK:=Session.clearPrivileges()
$isGuest:=Session.isGuest() //$isGuest est True

.expirationDate

Historique

Release	Modifications
18 R6	Ajout

.expirationDate : Text

Description

note

Cette propriété est uniquement disponible avec les sessions web.

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.

Cette propriété est en lecture seule. It is automatically recomputed if the .idleTimeout property value is modified.

Exemple

var $expiration : Text
$expiration:=Session.expirationDate //ex : "2021-11-05T17:10:42Z"

.hasPrivilege()

Historique

Release	Modifications
18 R6	Ajout

.hasPrivilege( privilege : Text ) : Boolean

Paramètres	Type		Description
privilege	Text	<-	Nom du privilège à vérifier
Résultat	Boolean	<-	True if session has privilege, False otherwise

Description

note

Since privileges are only supported in web user sessions, this function does nothing and always returns False in other session types.

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

Exemple

Vous voulez vérifier si le privilège "WebAdmin" est associé à la session :

If (Session.hasPrivilege("WebAdmin"))
    //Access is granted, do nothing
Else
    //Display an authentication page

End if

.id

Historique

Release	Modifications
20 R5	Ajout

.id : Text

Description

The .id property contains the unique identifier (UUID) of the session on the server. Cette chaîne unique est automatiquement attribuée par le serveur à chaque session et vous permet d'identifier ses process.

.idleTimeout

Historique

Release	Modifications
18 R6	Ajout

.idleTimeout : Integer

Description

note

Cette propriété est uniquement disponible avec les sessions web.

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

Si cette propriété n'est pas définie, sa valeur par défaut est 60 (1h).

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

La valeur ne peut pas être < 60 ; si une valeur inférieure est définie, le timeout est élevé à 60.

This property is read write.

Exemple

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 if

.info

Historique

Release	Modifications
20 R5	Ajout

.info : Object

Description

note

Cette propriété est uniquement disponible avec les sessions des procédures stockées et des client distants.

The .info property describes the remote client or stored procedure session on the server.

The .info object is the same object as the one returned by the Get process activity command for remote client and stored procedure sessions.

The .info object contains the following properties:

Propriété	Type	Description
type	Text	Type de session : "remote" ou "storedProcedure"
userName	Text	4D user name (same value as `.userName`)
machineName	Text	Sessions distantes : nom de la machine distante. Session des procédures stockées : nom de la machine serveur
systemUserName	Text	Sessions distantes : nom de la session système ouverte sur la machine distante.
IPAddress	Text	Adresse IP de la machine distante
hostType	Text	Type d'hôte : "windows" ou "mac"
creationDateTime	Date ISO 8601	Date et heure de création de la session
state	Text	État de la session : "active", "postponed", "sleeping"
ID	Text	Session UUID (same value as `.id`)
persistentID	Text	ID persistant de la session

note

Since .info is a computed property, it is recommended to call it once and then to store it in a local variable if you want to do some processing on its properties.

.isGuest()

Historique

Release	Modifications
18 R6	Ajout

.isGuest() : Boolean

Paramètres	Type		Description
Résultat	Boolean	<-	Vrai s'il s'agit d'une session Guest, sinon Faux

Description

note

This function always returns True with remote client and stored procedure sessions.

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

Exemple

In the On Web Connection database method:

If (Session.isGuest())
    //Do something for Guest user
End if

.setPrivileges()

Historique

Release	Modifications
19 R8	Prise en charge de la propriété "roles" dans settings
18 R6	Ajout

.setPrivileges( privilege : Text ) : Boolean
.setPrivileges( privileges : Collection )
.setPrivileges( settings : Object ) : Boolean

Paramètres	Type		Description
privilege	Text	->	Nom de privilège
privileges	Collection	->	Collection de noms de privilèges
settings	Object	->	Objet contenant une propriété "privileges" (texte ou collection)
Résultat	Boolean	<-	True si l'exécution est réussie

Description

note

Since privileges are only supported in web user sessions, this function does nothing and always returns False in other session types.

The .setPrivileges() function associates the privilege(s) and/or role(s) defined in the parameter to the session and returns True if the execution was successful.

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:

Propriété	Type	Description
privileges	Text ou Collection	String containing a privilege name, or Collection of strings containing privilege names
roles	Text ou Collection	String containing a role, or Collection of strings containing roles
userName	Text	Nom d'utilisateur à associer à la session (optionnel)

note

Privileges and roles are defined in roles.json file of the project. For more information, please refer to the Privileges section.

If the privileges or roles property contains a name that is not declared in the roles.json file, 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).

Exemple

Dans une méthode d'authentification personnalisée, vous assignez le privilège "WebAdmin" à l'utilisateur :

var $userOK : Boolean

... //Authenticate the user

If ($userOK) //The user has been approved
  var $info : Object
  $info:=New object()
  $info.privileges:=New collection("WebAdmin")
  Session.setPrivileges($info)
End if

.storage

Historique

Release	Modifications
20 R5	Prise en charge des sessions utilisateurs distants et procédures stockées
18 R6	Ajout

.storage : Object

Description

The .storage property contains a shared object that can be used to store information available to all processes of the session.

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.

Web session example
Remote session example

Vous voulez stocker l'adresse IP du client dans la propriété .storage. You can write in the On Web Authentication database method:

If (Session.storage.clientIP=Null) //first access
    Use (Session.storage)
        Session.storage.clientIP:=New shared object("value"; $clientIP)
    End use
End if

You want to share data between processes in the same session:

Use (Session.storage)
 Session.storage.settings:=New shared object("property"; $value; "property2"; $value2)
End use

.userName

Historique

Release	Modifications
20 R5	Prise en charge des sessions utilisateurs distants et procédures stockées
18 R6	Ajout

.userName : Text

Description

The .userName property contains the user name associated to the session. Vous pouvez vous en servir pour identifier l'utilisateur dans votre code.

Avec les sessions web, cette propriété est une chaîne vide par défaut. It can be set using the privileges property of the setPrivileges() function.
With remote and stored procedure sessions, this property returns the same user name as the Current user command.

This property is read only.

Types de sessions​

Sommaire​

Session​

Description​

Sessions Web​

Sessions clients distants​

Session des procédures stockées​

Exemple​

.clearPrivileges()​

Description​

Exemple​

.expirationDate​

Description​

Exemple​

.hasPrivilege()​

Description​

Exemple​

.id​

Description​

.idleTimeout​

Description​

Exemple​

.info​

Description​

.isGuest()​

Description​

Exemple​

.setPrivileges()​

Description​

Exemple​

.storage​

Description​

.userName​

Description​

Types de sessions

Sommaire

Session

Description

Sessions Web

Sessions clients distants

Session des procédures stockées

Exemple

.clearPrivileges()

Description

Exemple

.expirationDate

Description

Exemple

.hasPrivilege()

Description

Exemple

.id

Description

.idleTimeout

Description

Exemple

.info

Description

.isGuest()

Description

Exemple

.setPrivileges()

Description

Exemple

.storage

Description

.userName

Description