Version: Next

Session

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

Session types

The following types of sessions are supported by this class:

Web user sessions: Web user sessions are available when scalable sessions are enabled in your project. They are used for Web connections (including REST access), and are controlled by assigned privileges.
Remote user sessions: In client/server applications, remote users have their own sessions, managed from the client and from the server.
Stored procedures sessions: Virtual user session for all stored procedures executed on the server.
Standalone sessions: Local session object returned in single-user application (useful in development and test phases of client/server applications).

About session privileges

All session types can handle privileges, but only the code executed in a web context is actually controlled by session's privileges.

Summary


.clearPrivileges() : Boolean removes all the privileges associated to the session (excluding promoted privileges) and returns True if the execution was successful
.createOTP ( { lifespan : Integer } ) : Text creates a new OTP (One Time Passcode) for the session and returns its token UUID
.demote( promoteId : Integer ) removes the promoted privilege whose id you passed in promoteId from the web process, if it was previously added by the `.promote()` function
.expirationDate : Text the expiration date and time of the session cookie
.getPrivileges() : Collection returns a collection of all the privilege names associated to the session
.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 user session
.idleTimeout : Integer the inactivity session timeout (in minutes), after which the session is automatically closed by 4D
.info : Object describes the session
.isGuest() : Boolean returns True as long as `setPrivileges()` is not called in the session or after a Qodly logout has been executed in the session
.promote( privilege : Text ) : Integer adds the privilege defined in the privilege parameter to the current process during the execution of the calling function and returns the id of the promoted privilege
.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 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

.clearPrivileges()

History

Release	Changes
21	Support of remote and standalone sessions
18 R6	Added

.clearPrivileges() : Boolean

Parameter	Type		Description
Result	Boolean	<-	True if the execution is successful

Description

The .clearPrivileges() function removes all the privileges associated to the session (excluding promoted privileges) and returns True if the execution was successful.

Notes

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.
This function does not remove promoted privileges from the web process, whether they are added through the roles.json file or the promote() function.
For security reasons, this function cannot be called from the client side of a remote user session (an error is returned).

Example

//Invalidate a web user session
var $isOK : Boolean

$isOK:=Session.clearPrivileges()

.createOTP()

History

Release	Changes
21	Support of remote and standalone sessions
20 R9	Added

.createOTP ( { lifespan : Integer } ) : Text

Parameter	Type		Description
lifespan	Integer	->	Session token lifespan in seconds
Result	Text	<-	UUID of the token

Description

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.

You can set a custom timeout by passing a value in seconds in lifespan. By default, if the lifespan parameter is omitted:

for web sessions, the token is created with the same lifespan as the .idleTimeOut of the session.
for remote user sessions, the token is created with a 10 seconds lifespan.

In web sessions, the returned token can 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.

In remote user sessions (and standalone sessions for test purposes), the returned token can be used by 4D to identify requests coming from the web that share the session.

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

If an expired token is used to restore a session, it is ignored.

Example

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

.demote()

History

Release	Changes
20 R10	Added

.demote( promoteId : Integer )

Parameter	Type		Description
promoteId	Integer	->	Id returned by the `promote()` function

Description

The .demote() function removes the promoted privilege whose id you passed in promoteId from the web process, if it was previously added by the .promote() function.

If no privilege with promoteId was promoted using .promote() in the web process, the function does nothing.

If several privileges have been added to the web process, the demote() function must be called for each one with the appropriate promoteId. Privileges are stacked in the order they have been added to the process, it is recommended to unstack privileges in a LIFO (Last In, First Out) order.

Notes

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.
This function cannot be called from the client side of a remote user session (an error is returned).

Example

exposed Function search($search : Text) : Collection
	
	var $employees : Collection
	var $promoteId1; $promoteId2 : Integer
	
	$promoteId1:=Session.promote("admin")
	$promoteId2:=Session.promote("superAdmin")
	
	$search:="@"+$search+"@"
	
	$employees:=This.query("type = :1 and lastname = :2"; "Intern"; $search).toCollection()
	
	Session.demote($promoteId2)
	Session.demote($promoteId1)
	
	return $employees

.expirationDate

History

Release	Changes
18 R6	Added

.expirationDate : Text

Description

note

This property is only available with web user sessions.

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 : Text
$expiration:=Session.expirationDate //eg "2021-11-05T17:10:42Z"

.getPrivileges()

History

Release	Changes
21	Support of remote and standalone sessions
20 R6	Added

.getPrivileges() : Collection

Parameter	Type		Description
Result	Collection	<-	Collection of privilege names (strings)

Description

The .getPrivileges() function returns a collection of all the privilege names associated to the session.

note

This function returns privileges assigned to a Session using the setPrivileges() function only. Promoted privileges are NOT returned by the function, whether they are added through the roles.json file or the promote() function.

note

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.

Example

The following roles.json has been defined:

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

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

      ]
   }
}

The session role is assigned in an authentify() datastore function:

  //Datastore Class

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

Assuming the authentify() function is called with the "Medium" role:

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

.hasPrivilege()

History

Release	Changes
21	Returns True for promoted privileges, Support of remote and standalone sessions
18 R6	Added

.hasPrivilege( privilege : Text ) : Boolean

Parameter	Type		Description
privilege	Text	->	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.

note

This function returns True for the privilege if called from a function that was promoted for this privilege (either through the roles.json file or the promote() function).

note

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.

Example

You want to check if the "CreateInvoices" privilege is associated to the web user session:

If (Session.hasPrivilege("CreateInvoices"))
	//Access to Invoice creation features
Else
	//No access to Invoice creation features 

End if

.id

History

Release	Changes
20 R5	Added

.id : Text

Description

The .id property contains the unique identifier (UUID) of the user session.

With 4D Server, this unique string is automatically assigned by the server for each session and allows you to identify its processes. It is available in both the Session on the server side and on the client side.

tip

You can use this property to get the .storage object of a session thanks to the Session storage command.

.idleTimeout

History

Release	Changes
18 R6	Added

.idleTimeout : Integer

Description

note

This property is only available with web user sessions.

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

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 if

.info

History

Release	Changes
20 R5	Added

.info : Object

Description

The .info property describes the session.

Remote user sessions and Stored procedure sessions: The .info object is the same object as the one returned in the "session" property by the Process activity command.
Standalone sessions: The .info object is the same object as the one returned by the Session info command.
Web user sessions: The .info object contains properties available for web user sessions.

The .info object contains the following properties:

Property	Type	Description
type	Text	Session type: "remote", "storedProcedure", "standalone", "rest", "web"
userName	Text	4D user name (same value as `.userName`)
machineName	Text	Remote sessions: name of the remote machine. Client sessions: name of the local machine. Stored procedures session: name of the server machine. Standalone session: name of the machine
systemUserName	Text	Remote sessions: name of the system session opened on the remote machine. Client sessions: name of the local system session
IPAddress	Text	Remote sessions: IP address of the remote machine. Client sessions: IP address of the local machine. Standalone session: "localhost"
hostType	Text	Host type: "windows", "mac", or "browser"
creationDateTime	Date ISO 8601	Date and time of session creation (standalone session: date and time of application startup)
state	Text	Session state: "active", "postponed", "sleeping"
ID	Text	Session UUID (same value as `.id`)
persistentID	Text	Remote/client sessions: Session's persistent ID

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()

History

Release	Changes
18 R6	Added

.isGuest() : Boolean

Parameter	Type		Description
Result	Boolean	<-	True if session is a Guest one, False otherwise (web sessions only)

Description

note

This function always returns False with non-web sessions.

The .isGuest() function returns True as long as setPrivileges() is not called in the session or after a Qodly logout has been executed in the session.

Compatibility

When the forcelogin mode is disabled, .isGuest() returns True if the session has no privileges.

Example

In the On Web Connection database method:

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

.promote()

History

Release	Changes
20 R10	Added

.promote( privilege : Text ) : Integer

Parameter	Type		Description
privilege	Text	->	Privilege name
Result	Integer	<-	id to use when calling the `demote()` function

Description

The .promote() function adds the privilege defined in the privilege parameter to the current process during the execution of the calling function and returns the id of the promoted privilege.

Dynamically adding privileges is useful when access rights depend on the execution context, which cannot be fully defined in the "roles.json" file. This is particularly relevant when the same function can be executed by users with different access levels. The use of .promote() ensures that only the current process is granted the necessary privileges, without affecting others.

The function does nothing and returns 0 if:

the privilege does not exist in the roles.json file,
the privilege is already assigned to the current process (using .promote() or through a static promote action declared for the calling function in the roles.json file).

You can call the promote() function several times in the same process to add different privileges.

The returned id is incremented each time a privilege is dynamically added to the process.

To remove a privilege dynamically, call the demote() function with the appropriate id.

Notes

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.
This function cannot be called from the client side of a remote user session (an error is returned).

Example

Several users connect to a single endpoint that serves different applications. A user from application #1 does not need the "super_admin" privilege because they don't create "VerySensitiveInfo". A user from application #2 needs "super_admin" privilege.

You can dynamically provide appropriate privileges in the CreateInfo function:

exposed Function createInfo($info1 : Text; $info2 : Text)
	
var $sensitive : cs.SensitiveInfoEntity
var $verySensitiveInfo : cs.VerySensitiveInfoEntity
var $status : Object
var $promoteId : Integer
	
$sensitive:=ds.SensitiveInfo.new()
$sensitive.info:=$info1
$status:=$sensitive.save()
	
If (Session.storage.role.name="userApp2")
	$promoteId:=Session.promote("super_admin")
	$verySensitiveInfo:=ds.VerySensitiveInfo.new()
	$verySensitiveInfo.info:=$info2
	$status:=$verySensitiveInfo.save()
	Session.demote($promoteId)
End if 

.restore()

History

Release	Changes
20 R9	Added

.restore ( token : Text ) : Boolean

Parameter	Type		Description
token	Text	->	Session token UUID
Result	Boolean	<-	True if the current session has been successfully replaced by the session in token

Description

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).

Notes

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.
This function cannot be called from the client side of a remote user session (an error is returned).

Example

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) 

.setPrivileges()

History

Release	Changes
21	Support of remote and standalone sessions
19 R8	Support of "roles" Settings property
18 R6	Added

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

Parameter	Type		Description
privilege	Text	->	Privilege name
privileges	Collection	->	Collection of privilege names
settings	Object	->	Object with a "privileges" property (string or collection)
Result	Boolean	<-	True if the execution is successful

Description

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:

Property	Type	Description
privileges	Text or Collection	String containing a privilege name, or Collection of strings containing privilege names
roles	Text or Collection	String containing a role, or Collection of strings containing roles
userName	Text	User name to associate to the session (optional, web sessions only). Not available in remote client sessions (ignored).

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).

Notes

Keep in mind that privileges only apply to the code executed through web accesses, whatever the session type on which this function is executed.
This function cannot be called from the client side of a remote user session (an error is returned).

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:=New object()
  $info.privileges:=New collection("WebAdmin")
  Session.setPrivileges($info)
End if

.storage

History

Release	Changes
20 R5	Support of desktop sessions
18 R6	Added

.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. This property is read only itself but it returns a read-write object.

::: note Notes

Since it is a shared object, this property will be available in the Storage object of the machine (server or client).
Like the Storage object of the machine, the .storage property is always "single": adding a shared object or a shared collection to .storage does not create a shared group.

:::

In client/server, the .storage object of the remote user session is not the same on the server and on the client.

When a remote user session and a web session are shared using an OTP, they also share the same .storage object on the server, even if the OTP was created from the session on the client side.

tip

You can get the .storage property of a session using the Session storage command.

Web session example

You want to store the client IP in the .storage property. 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

Remote session example

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

History

Release	Changes
20 R5	Support of desktop sessions
18 R6	Added

.userName : Text

Description

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

Web sessions: This property is an empty string by default. It can be set using the privileges property of the setPrivileges() function.
Remote/Stored procedure sessions: This property returns the same user name as the Current user command.
Standalone sessions: This property contains "designer" or the name set with the SET USER ALIAS command.

This property is read only for desktop sessions.

Session types​

Summary​

.clearPrivileges()​

Description​

Example​

.createOTP()​

Description​

Example​

.demote()​

Description​

Example​

See also​

.expirationDate​

Description​

Example​

.getPrivileges()​

Description​

Example​

See also​

.hasPrivilege()​

Description​

Example​

See also​

.id​

Description​

.idleTimeout​

Description​

Example​

.info​

Description​

.isGuest()​

Description​

Example​

.promote()​

Description​

Example​

See also​

.restore()​

Description​

Example​

See also​

.setPrivileges()​

Description​

Example​

See also​

.storage​

Description​

Web session example​

Remote session example​

.userName​

Description​

Session types

Summary

.clearPrivileges()

Description

Example

.createOTP()

Description

Example

.demote()

Description

Example

See also

.expirationDate

Description

Example

.getPrivileges()

Description

Example

See also

.hasPrivilege()

Description

Example

See also

.id

Description

.idleTimeout

Description

Example

.info

Description

.isGuest()

Description

Example

.promote()

Description

Example

See also

.restore()

Description

Example

See also

.setPrivileges()

Description

Example

See also

.storage

Description

Web session example

Remote session example

.userName

Description