Skip to main content
Version: Next

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.

Session types

The following types of sessions are supported by this class:

note

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

Summary

.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
.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 remote client or stored procedure session on the server, or the standalone session
.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

.clearPrivileges()

History
ReleaseChanges
18 R6Added

.clearPrivileges() : Boolean

ParameterTypeDescription
ResultBoolean<-True if the execution is successful

Description

note

This function does nothing and always returns True with remote client, stored procedure, and standalone sessions.

The .clearPrivileges() function removes all the privileges associated to the session and returns True if the execution was successful. As a result, the session automatically becomes a Guest session.

Example

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

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

.expirationDate

History
ReleaseChanges
18 R6Added

.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
ReleaseChanges
20 R6Added

.getPrivileges() : Collection

ParameterTypeDescription
ResultCollection<-Collection of privilege names (strings)

Description

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

With remote client, stored procedure and standalone sessions, this function returns a collection only containing "WebAdmin".

info

Privileges are assigned to a Session using the setPrivileges() function.

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"]

See also

.setPrivileges()
Permissions – Inspect the privileges in the session for an easy debugging (blog post)

.hasPrivilege()

History
ReleaseChanges
18 R6Added

.hasPrivilege( privilege : Text ) : Boolean

ParameterTypeDescription
privilegeText->Name of the privilege to verify
ResultBoolean<-True if session has privilege, False otherwise

Description

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

With remote client, stored procedure and standalone sessions, this function always returns True, whatever the privilege.

Example

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

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

End if

.id

History
ReleaseChanges
20 R5Added

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

tip

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

.idleTimeout

History
ReleaseChanges

|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
ReleaseChanges
20 R5Added

.info : Object

Description

note

This property is only available with remote client, stored procedure, and standalone sessions.

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

note
  • The .info object is the same object as the one returned in the "session" property by the Process activity command for remote client and stored procedure sessions.
  • The .info object is the same object as the one returned by the Session info command for a standalone session.

The .info object contains the following properties:

PropertyTypeDescription
typeTextSession type: "remote", "storedProcedure", "standalone"
userNameText4D user name (same value as .userName)
machineNameTextRemote sessions: name of the remote machine. Stored procedures session: name of the server machine. Standalone session: name of the machine
systemUserNameTextRemote sessions: name of the system session opened on the remote machine.
IPAddressTextIP address of the remote machine
hostTypeTextHost type: "windows" or "mac"
creationDateTimeDate ISO 8601Date and time of session creation. Standalone session: date and time of application startup
stateTextSession state: "active", "postponed", "sleeping"
IDTextSession UUID (same value as .id)
persistentIDTextRemote 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
ReleaseChanges
18 R6Added

.isGuest() : Boolean

ParameterTypeDescription
ResultBoolean<-True if session is a Guest one, False otherwise

Description

note

This function always returns False with remote client, stored procedure, and standalone sessions.

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

Example

In the On Web Connection database method:

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

.setPrivileges()

History
ReleaseChanges
19 R8Support of "roles" Settings property
18 R6Added

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

ParameterTypeDescription
privilegeText->Privilege name
privilegesCollection->Collection of privilege names
settingsObject->Object with a "privileges" property (string or collection)
ResultBoolean<-True if the execution is successful

Description

note

This function does nothing and always returns False with remote client, stored procedure, and standalone sessions.

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:

PropertyTypeDescription
privilegesText or Collection
  • String containing a privilege name, or
  • Collection of strings containing privilege names
  • rolesText or Collection
  • String containing a role, or
  • Collection of strings containing roles
  • userNameTextUser name to associate to the session (optional)
    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).

    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

    See also

    .getPrivileges()

    .storage

    History
    ReleaseChanges
    20 R5Support of remote client and stored procedure sessions
    18 R6Added

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

    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
    ReleaseChanges
    20 R5Support of remote client and stored procedure sessions
    18 R6Added

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

    • With web sessions, this property is an empty string by default. 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.
    • With standalone sessions, this property contains "designer" or the name set with the SET USER ALIAS command.

    This property is read only.