Version: Next

Session

Les objets de session sont retournés par la commande Session. Ces objets fournissent au développeur une interface permettant de gérer la session utilisateur courante et d'exécuter des actions telles que le stockage de données contextuelles, le partage d'informations entre les process de la session, le lancement de process préemptifs liés à la session ou (uniquement pour le web) la gestion des privilèges.

Types de sessions

Les types de sessions suivants sont pris en charge par cette classe :

Session utilisateur Web : Les sessions utilisateur Web sont disponibles lorsque les sessions évolutives (scalable sessions) sont activées dans votre projet. Elles sont utilisées pour les connexions Web et REST, et peuvent se voir attribuer des privilèges.
Session utilisateur client distant : Dans les applications client/serveur, les utilisateurs distants ont leurs propres sessions gérées sur le serveur.
Stored procedures session: All stored procedures executed on the server share the same virtual user session.
Session autonome : objet session local retourné dans une application mono-utilisateur (utile dans les phases de développement et de test des applications client/serveur).

note

La disponibilité des propriétés et des fonctions de l'objet Session dépend du type de session.

Sommaire


.clearPrivileges() : Boolean supprime tous les privilèges associés à la session et retourne True si l'exécution a réussi
.createOTP ( { lifespan : Integer } ) : Text creates a new OTP (One Time Passcode) for the session and returns its token UUID
.expirationDate : Text la date et l'heure d'expiration du cookie de session
.getPrivileges() : Collection renvoie une collection contenant tous les noms de privilèges associés à la session
.hasPrivilege( privilege : Text ) : Boolean renvoie True si le privilege est associé à la session, et False sinon
.id : Text l'identifiant unique (UUID) de la session utilisateur
.idleTimeout : Integer le délai maximal d'inactivité de session (en minutes), au-delà duquel la session est automatiquement fermée par 4D
.info : Object décrit le client distant ou la session de procédure stockée sur le serveur, ou la session autonome
.isGuest() : Boolean renvoie True si la session est une session Guest (c'est-à-dire qu'elle n'a aucun privilège)
.restore ( token : Text ) : Boolean replaces the current web user session with their original session corresponding to the token UUID
.setPrivileges( privilege : Text ) : Boolean .setPrivileges( privileges : Collection ) .setPrivileges( settings : Object ) : Boolean associe le ou les privilège(s) et/ou rôle(s) défini(s) en paramètre à la session et renvoie True si l'exécution a réussi
.storage : Object un objet partagé qui peut être utilisé pour stocker des informations disponibles pour tous les process de la session
.userName : Text le nom d'utilisateur associé à la session

.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

Cette fonction ne fait rien et retourne toujours True avec les sessions client distants, procédure stockée et autonomes.

La fonction .clearPrivileges() supprime tous les privilèges associés à la session et retourne True si l'exécution a réussi. En résultat, la session devient automatiquement une session Guest.

Exemple

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

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

.createOTP()

Historique

Release	Modifications
20 R9	Ajout

.createOTP ( { lifespan : Integer } ) : Text

Paramètres	Type		Description
lifespan	Integer	->	Session token lifespan in seconds
Résultat	Text	<-	UUID of the session

Description

note

This function is only available with web user sessions. It returns an empty string in other contexts.

The .createOTP() function creates a new OTP (One Time Passcode) for the session and returns its token UUID. This token is unique to the session in which it was generated.

For more information about the OTP tokens, please refer to this section.

By default, if the lifespan parameter is omitted, the token is created with the same lifespan as the .idleTimeOut of the session. You can set a custom timeout by passing a value in seconds in lifespan (the minimum value is 10 seconds, lifespan is reset to 10 if a smaller value is passed). If an expired token is used to restore a web user session, it is ignored.

The returned token can then be used in exchanges with third-party applications or websites to securely identify the session. For example, the session OTP token can be used with a payment application.

Exemple

var $token : Text
$token := Session.createOTP( 60 ) //the token is valid for 1 mn

.expirationDate

Historique

Release	Modifications
18 R6	Ajout

.expirationDate : Text

Description

note

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

La propriété .expirationDate contient la date et l'heure d'expiration du cookie de session. La valeur est exprimée sous forme de texte au format ISO 8601 : YYYY-MM-DDTHH:MM:SS.mmmZ.

Cette propriété est en lecture seule. Elle est automatiquement recalculée si la valeur de la propriété .idleTimeout est modifiée.

Exemple

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

.getPrivileges()

Historique

Release	Modifications
20 R6	Ajout

.getPrivileges() : Collection

Paramètres	Type		Description
Résultat	Collection	<-	Collection de noms de privilèges (chaînes)

Description

La fonction .getPrivileges() renvoie une collection contenant tous les noms de privilèges associés à la session.

Avec les sessions client distant, procédures stockées et autonomes, cette fonction retourne une collection contenant uniquement "WebAdmin".

info

Les privilèges sont assignés à une Session en utilisant la fonction setPrivileges().

Exemple

Les rôles suivants roles.json ont été définis :

{
   "privileges":[
      {
         "privilege":"simple",
         "includes":[

         ]
      },
      {
         "privilege":"medium",
         "includes":[
            "simple"
         ]
      }
   ],
   "roles":[
      {
         "role":"Medium",
         "privileges":[
            "medium"
         ]
      }
   ],
   "permissions":{
      "allowed":[

      ]
   }
}

Le rôle de la session est attribué dans une fonction de datastore authentify() :

  //Datastore Class

exposed Function authentify($role : Text) : Text
	Session.clearPrivileges()
	Session.setPrivileges({roles: $role})

En supposant que la fonction authentify() soit appelée avec le rôle "Medium" :

var $privileges : Collection
$privileges := Session.getPrivileges()
//$privileges: ["simple","medium"]

Voir également

.setPrivileges()
Permissions : Inspecter les privilèges de la session pour faciliter le débogage (article de blog)

.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	<-	Vrai si la session dispose du privilege, sinon Faux

Description

La fonction .hasPrivilege() renvoie True si le privilege est associé à la session, et False sinon.

Avec les sessions client distant, procédures stockées et autonomes, cette fonction retourne toujours True, quel que soit le privilege.

Exemple

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

If (Session.hasPrivilege("WebAdmin"))
	//Accès accordé, ne rien faire
Else
	//Afficher une page d'authentification

End if

.id

Historique

Release	Modifications
20 R5	Ajout

.id : Text

Description

La propriété .id contient l'identifiant unique (UUID) de la session utilisateur. Avec 4D Server, cette chaîne unique est automatiquement assignée par le serveur à chaque session et vous permet d'identifier ses process.

tip

Vous pouvez utiliser cette propriété pour obtenir l'objet .storage d'une session grâce à la commande Session storage .

.idleTimeout

Historique

Release	Modifications

|18 R6|Added|

.idleTimeout : Integer

Description

note

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

La propriété .idleTimeout contient le délai maximal d'inactivité de session (en minutes), au-delà duquel la session est automatiquement fermée par 4D.

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

Lorsque cette propriété est définie, la propriété .expirationDate est mise à jour en conséquence.

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

Cette propriété est en lecture-écriture.

Exemple

If (Session.isGuest())
		// La session Guest se ferme après 60 minutes d'inactivité
	Session.idleTimeout:=60
Else
		// Les autres sessions se ferment après 120 minutes d'inactivité
	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 clients distants, procédures stockées et autonomes.

La propriété .info décrit le client distant ou la session de procédure stockée sur le serveur, ou la session autonome.

note

L'objet .info est le même objet que celui retourné dans la propriété "session" par la commande Process activity pour les sessions de clients distants et procédures stockées.
L'objet .info est le même objet que celui retourné par la commande Session info pour une session autonome.

L'objet .info contient les propriétés suivantes:

Propriété	Type	Description
type	Text	Type de session : "remote", "storedProcedure", "standalone"
userName	Text	Nom d'utilisateur 4D (même valeur que `.userName`)
machineName	Text	Sessions distantes : nom de la machine distante. Session procédures stockées : nom de la machine serveur. Session autonome : nom de la machine
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. Session autonome : date et heure de démarrage de l'application
state	Text	État de la session : "active", "postponed", "sleeping"
ID	Text	UUID de session (même valeur que `.id`)
persistentID	Text	Sessions distantes : ID persistant de la session

note

.info étant une propriété calculée, il est recommandé de l'appeler une fois et de la stocker dans une variable locale si vous souhaitez effectuer un traitement sur ses propriétés.

.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

Cette fonction retourne toujours False avec les sessions clients distants, procédures stockées et autonomes.

La fonction .isGuest() renvoie True si la session est une session Guest (c'est-à-dire qu'elle n'a aucun privilège).

Exemple

Dans la méthode base On Web Connection :

If (Session.isGuest())
 //Faire quelque chose pour l'utilisateur invité
End if

.restore()

Historique

Release	Modifications
20 R9	Ajout

.restore ( token : Text ) : Boolean

Paramètres	Type		Description
token	Text	->	Session token UUID
Résultat	Boolean	<-	True if the current session has been successfully replaced by the session in token

Description

note

This function is only available with web user sessions. It returns False in other contexts.

The .restore() function replaces the current web user session with their original session corresponding to the token UUID. Session's storage and privileges are restored.

If the original user session has been correctly restored, the function returns true.

The function returns false if:

the session token has already been used,
the session token has expired,
the session token does not exist,
the original session itself has expired.

In this case, the current web user session is left untouched (no session is restored).

Exemple

In a singleton called by a custom HTTP Request handler:

shared singleton Class constructor()

Function callback($request : 4D.IncomingMessage) : 4D.OutgoingMessage
   Session.restore($request.urlQuery.state) 

Voir également

.createOTP()

.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

Cette fonction ne fait rien et retourne toujours False avec les sessions client distants, procédures stockées et autonomes.

La fonction .setPrivileges() associe le ou les privilège(s) et/ou rôle(s) défini(s) en paramètre à la session et renvoie True si l'exécution a réussi.

Dans le paramètre privilege, passez une chaîne contenant un nom de privilège (ou plusieurs noms de privilèges séparés par des virgules).
Dans le paramètre privileges, passez une collection de chaînes contenant des noms de privilèges.
Dans le paramètre settings, passez un objet contenant les propriétés suivantes :

Propriété	Type	Description
privileges	Text ou Collection	Chaîne contenant un nom de privilège, ou Collection de chaînes contenant des noms de privilèges
roles	Text ou Collection	Chaîne contenant un rôle, ou Collection de chaînes contenant des rôles
userName	Text	Nom d'utilisateur à associer à la session (optionnel)

note

Les privilèges et les rôles sont définis dans le fichier roles.json du projet. Pour plus d'informations, veuillez vous reporter à la section Privileges.

Si la propriété privileges ou roles contient un nom qui n'est pas déclaré dans le fichier roles.json, il est ignoré.

Par défaut lorsqu'aucun privilège ou rôle n'est associé à la session, la session est une session Guest.

La propriété userName est accessible au niveau de l'objet session (lecture seulement).

Exemple

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

var $userOK : Boolean

... //Authentifier l'utilisateur

If ($userOK) //L'utilisateur a été approuvé
  var $info : Object
  $info:=New object()
  $info.privileges:=New collection("WebAdmin")
  Session.setPrivileges($info)
End if

Voir également

.getPrivileges()

.storage

Historique

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

.storage : Object

Description

La propriété .storage contient un objet partagé qui peut être utilisé pour stocker des informations disponibles pour tous les process de la session.

Lorsqu'un objet Session est créé, la propriété .storage est vide. Puisqu'il s'agit d'un objet partagé, cette propriété sera disponible dans l'objet Storage du serveur.

Tout comme l'objet Storage du serveur, la propriété .storage est toujours "single" : l'ajout d'un objet partagé ou d'une collection partagée à .storage ne crée pas de groupe partagé.

Cette propriété est elle-même en lecture seulement mais elle retourne un objet en lecture-écriture.

tip

Vous pouvez obtenir la propriété .storage d'une session en utilisant la commande Session storage.

Exemple de session Web

Vous voulez stocker l'adresse IP du client dans la propriété .storage. Vous pouvez écrire dans la méthode base On Web Authentication :

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

Exemple de session distante

Vous voulez partager des données entre les process de la même 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

La propriété .userName contient le nom d'utilisateur associé à la 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. Elle peut être définie via la propriété privileges de la fonction setPrivileges().
Avec les sessions clients distants et procédures stockées, cette propriété retourne le même nom d'utilisateur que la commande Current user.
Avec les sessions autonomes, cette propriété contient "designer" ou le nom défini avec la commande SET USER ALIAS.

Cette propriété est en lecture seule.

Types de sessions​

Sommaire​

.clearPrivileges()​

Description​

Exemple​

.createOTP()​

Description​

Exemple​

.expirationDate​

Description​

Exemple​

.getPrivileges()​

Description​

Exemple​

Voir également​

.hasPrivilege()​

Description​

Exemple​

.id​

Description​

.idleTimeout​

Description​

Exemple​

.info​

Description​

.isGuest()​

Description​

Exemple​

.restore()​

Description​

Exemple​

Voir également​

.setPrivileges()​

Description​

Exemple​

Voir également​

.storage​

Description​

Exemple de session Web​

Exemple de session distante​

.userName​

Description​

Types de sessions

Sommaire

.clearPrivileges()

Description

Exemple

.createOTP()

Description

Exemple

.expirationDate

Description

Exemple

.getPrivileges()

Description

Exemple

Voir également

.hasPrivilege()

Description

Exemple

.id

Description

.idleTimeout

Description

Exemple

.info

Description

.isGuest()

Description

Exemple

.restore()

Description

Exemple

Voir également

.setPrivileges()

Description

Exemple

Voir également

.storage

Description

Exemple de session Web

Exemple de session distante

.userName

Description