Versão: 21 BETA

Session

Os objetos de sessão são retornados pelo comando Session. 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.

Tipos de sessão

Os seguintes tipos de sessões são suportados por essa classe:

Sessões de usuário web: sessões de usuário web estão disponíveis quando sessões escaláveis estão habilitadas em seu projeto. They are used for Web connections (including and REST access), and are controlled by assigned privileges.
Desktop sessions, which include:
- Remote user sessions: In client/server applications, remote users have their own sessions managed on 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 web user sessions is actually controlled by session's privileges.

Resumo


.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 cria um novo OTP (uma senha única) para a sessão e retorna seu 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 a data e a hora de expiração do cookie de sessão
.getPrivileges() : Collection retorna uma coleção de todos os nomes de privilégios associados à sessão
.hasPrivilege( privilege : Text ) : Boolean retorna True se o privilege estiver associado à sessão e False caso contrário
.id : Text o identificador único (UUID) da sessão do usuário
.idleTimeout : Integer o tempo limite da sessão de inatividade (em minutos), após o qual a sessão é automaticamente encerrada pelo 4D
.info : Object describes the desktop or web 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 substitui a sessão do usuário da web pela sua sessão original correspondente ao token UUID
.setPrivileges( privilege : Text ) : Boolean .setPrivileges( privileges : Collection ) .setPrivileges( settings : Object ) : Boolean associa os privilégios e/ou papéis definidos no parâmetro para a sessão e retorna True se a execução foi bem sucedida
.storage : Object um objeto compartilhado que pode ser usado para armazenar informações disponíveis para todos os processos da sessão
.userName : Text o nome de usuário associado à sessão

.clearPrivileges()

História

Release	Mudanças
21	Support of remote and standalone sessions
18 R6	Adicionado

.clearPrivileges() : Boolean

Parâmetro	Tipo		Descrição
Resultados	Parâmetros	<-	True se a execução for bem-sucedida

Descrição

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

nota

This function does not remove promoted privileges from the web process, whether they are added through the roles.json file or the promote() function.

nota

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

Exemplo

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

$isOK:=Session.clearPrivileges()

.createOTP()

História

Release	Mudanças
21	Support of remote and standalone sessions
20 R9	Adicionado

.createOTP ( { lifespan : Integer } ) : Text

Parâmetro	Tipo		Descrição
lifespan	Integer	->	Session token lifespan in seconds (web sessions only)
Resultados	Text	<-	UUID of the token

Descrição

A função .createOTP() cria um novo OTP (uma senha única) para a sessão e retorna seu UUID. Esse token é exclusivo da sessão em que foi gerado.

Para mais informações sobre os tokens OTP, consulte esta seção.

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

For web sessions, you can set a custom timeout by passing a value in seconds in lifespan. Por padrão, se o parâmetro lifespan for omitido, o token será criado com o mesmo tempo de vida que o .idleTimeOut da sessão.

For desktop sessions, the token is created with a 10 seconds lifespan.

The returned token can be used in exchanges with third-party applications or websites to securely identify the session. Por exemplo, o token de sessão OTP pode ser usado com um aplicativo de pagamento.

The returned token can be used by 4D Server or 4D single-user application to identify requests coming from the web that share the session.

Exemplo

var $token : Text
$token := Session.createOTP( 60 ) //o token é válido por 1 mn

.demote()

História

Release	Mudanças
20 R10	Adicionado

.demote( promoteId : Integer )

Parâmetro	Tipo		Descrição
promoteId	Integer	->	Id returned by the `promote()` function

Descrição

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.

Exemplo

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

Veja também

.promote()

.expirationDate

História

Release	Mudanças
18 R6	Adicionado

.expirationDate : Text

Descrição

nota

Essa propriedade só está disponível com sessões de usuário da Web.

A propriedade .expirationDate contém a data e a hora de expiração do cookie de sessão. O valor é expresso como texto no formato ISO 8601: YYYY-MM-DDTHH:MM:SS.mmmZ.

Essa propriedade é somente leitura. Ele será automaticamente recalculado se o valor da propriedade .idleTimeout for modificado.

Exemplo

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

.getPrivileges()

História

Release	Mudanças
21	Support of remote and standalone sessions
20 R6	Adicionado

.getPrivileges() : Collection

Parâmetro	Tipo		Descrição
Resultados	Collection	<-	Coleção de nomes de privilégios (strings)

Descrição

A função .getPrivileges() retorna uma coleção de todos os nomes de privilégios associados à sessão.

nota

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.

nota

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

Exemplo

O seguinte arquivo roles.json foi definido:

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

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

      ]
   }
}

O papel de sessão é atribuído em uma função de datastore authentify():

  //Datastore Class

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

Assumindo que a função authentify() seja chamada com o papel "Medium":

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

Veja também

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

.hasPrivilege()

História

Release	Mudanças
21	Returns True for promoted privileges, Support of remote and standalone sessions
18 R6	Adicionado

.hasPrivilege( privilege : Text ) : Boolean

Parâmetro	Tipo		Descrição
privilege	Text	->	Nome do privilegio a verificar
Resultados	Parâmetros	<-	True se a sessão tiver privilege, False caso contrário

Descrição

A função .hasPrivilege() retorna True se o privilege estiver associado à sessão e False caso contrário.

nota

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

nota

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

Exemplo

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

Veja também

Restrict data according to privileges or information saved in session storage (blog post)

.id

História

Release	Mudanças
20 R5	Adicionado

.id : Text

Descrição

A propriedade .id contém o identificador único (UUID) da sessão do usuário. Com o 4D Server, essa string exclusiva é atribuída automaticamente pelo servidor para cada sessão e permite que você identifique seus processos.

tip

Você pode usar essa propriedade para obter o objeto .storage de uma sessão graças ao comando storage.

.idleTimeout

História

Release	Mudanças
18 R6	Adicionado

.idleTimeout : Integer

Descrição

nota

Essa propriedade só está disponível com sessões de usuário da Web.

A propriedade .idleTimeout contém o tempo limite da sessão de inatividade (em minutos), após o qual a sessão é automaticamente encerrada pelo 4D.

Se não se definir esta propriedade, o valor padrão é 60 (1h).

Quando essa propriedade é definida, a propriedade .expirationDate é atualizada de acordo.

O valor não pode ser inferior a 60: se definir um valor inferior, o tempo de espera se eleva até 60.

Essa propriedade é leitura escrita.

Exemplo

If (Session.isGuest())
		// Uma sessão de convidado será fechada após 60 minutos de inatividade
	Session.idleTimeout:=60
Else
		// Outras sessões serão fechadas após 120 minutos de inatividade
	Session.idleTimeout:=120
End if

.info

História

Release	Mudanças
20 R5	Adicionado

.info : Object

Descrição

The .info property describes the desktop or web session.

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

O objeto .info contém as seguintes propriedades:

Propriedade	Tipo	Descrição
type	Text	Session type: "remote", "storedProcedure", "standalone", "rest", "web"
userName	Text	Nome de usuário 4D (o mesmo valor que `.userName`)
machineName	Text	Sessões remotas: nome da máquina remota. Sessão de procedimentos armazenados: nome da máquina do servidor. Sessão autônoma: nome da máquina
systemUserName	Text	Sessões remotas: nome da sessão do sistema aberta na máquina remota.
IPAddress	Text	Endereço IP da máquina remota
hostType	Text	Tipo de host: "windows" ou "mac"
creationDateTime	Date ISO 8601	Data e hora de criação da sessão. Sessão autônoma: data e hora da inicialização do aplicativo
state	Text	Estado da sessão: "ativa", "adiada", "em espera"
ID	Text	UUID da sessão (mesmo valor que `.id`)
persistentID	Text	Sessões remotas: ID persistente da sessão

nota

Desde . nfo é uma propriedade computada, é recomendável chamá-lo uma vez e então armazená-lo em uma variável local se você quiser fazer algum processamento em suas propriedades.

.isGuest()

História

Release	Mudanças
18 R6	Adicionado

.isGuest() : Boolean

Parâmetro	Tipo		Descrição
Resultados	Parâmetros	<-	True if session is a Guest one, False otherwise (web sessions only)

Descrição

nota

This function always returns False with desktop 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.

Compatibidade

In a REST session when the Force login mode is not enabled, .isGuest() returns True if the session has no privileges.

Exemplo

No método base On Web Connection:

If (Session.isGuest())
	//Fazer algo para o usuário convidado
End if

.promote()

História

Release	Mudanças
20 R10	Adicionado

.promote( privilege : Text ) : Integer

Parâmetro	Tipo		Descrição
privilege	Text	->	Nome do privilégio
Resultados	Integer	<-	id to use when calling the `demote()` function

Descrição

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.

nota

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

Exemplo

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 

Veja também

.demote()
hasPrivilege()

.restore()

História

Release	Mudanças
20 R9	Adicionado

.restore ( token : Text ) : Boolean

Parâmetro	Tipo		Descrição
token	Text	->	UUID do token de sessão
Resultados	Parâmetros	<-	True se a sessão atual tiver sido substituída com êxito pela sessão no token

Descrição

A função .restore() substitui a sessão do usuário da web pela sua sessão original correspondente ao token UUID. O armazenamento e os privilégios da sessão são restaurados.

Se a sessão original do usuário tiver sido restaurada corretamente, a função retornará true.

A função retorna false se:

o token de sessão já foi usado,
o token de sessão expirou,
o token de sessão não existe,
a própria sessão original expirou.

Nesse caso, a sessão atual do usuário da Web não é alterada (nenhuma sessão é restaurada).

Exemplo

Em um singleton chamado por um manipulador de solicitação HTTP personalizado:

shared singleton Class constructor()

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

Veja também

.createOTP()

.setPrivileges()

História

Release	Mudanças
21	Support of remote and standalone sessions
19 R8	Suporte da propriedade "roles" das Settings
18 R6	Adicionado

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

Parâmetro	Tipo		Descrição
privilege	Text	->	Nome do privilégio
privileges	Collection	->	Collection de nomes de privilégios
settings	Object	->	Objetos com as propriedades "privilégios" (string ou collection)
Resultados	Parâmetros	<-	True se a execução for bem-sucedida

Descrição

A função .setPrivileges() associa os privilégios e/ou papéis definidos no parâmetro para a sessão e retorna True se a execução foi bem sucedida .

No parâmetro privilege, passe uma cadeia de caracteres contendo um nome de privilégio (ou vários nomes de privilégio separados por vírgula).
No parâmetro privileges, passe uma coleção de cadeias de caracteres contendo nomes de privilégios.
No parâmetro settings, passe um objeto que contenha as seguintes propriedades:

Propriedade	Tipo	Descrição
privileges	Text ou Collection	String contendo um nome de privilégio, ou Coleção de cadeias de caracteres contendo nomes de privilégios
roles	Text ou Collection	String que contém uma função, ou Coleção de cadeias de caracteres contendo funções
userName	Text	User name to associate to the session (optional, web sessions only). Not available in remote client sessions (ignored).

nota

Os privilégios e as funções são definidos no arquivo roles.json do projeto. Para obter mais informações, consulte a seção Privilégios.

Se a propriedade privileges ou roles tiverem um nome que não seja declarado no arquivo roles.json, ele será ignorado.

Como padrão quando não houver um privilégio associado à sessão, a sessão é uma Sessão de convidados.

A propriedade userName está disponível no nível do objeto de sessão (somente leitura).

nota

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

Exemplo

Em um método de autenticação personalizado, deve estabecer o privilégio "WebAdmin" ao usuário:

var $userOK : Boolean

... //Autenticar o usuário

If ($userOK) //O usuário foi aprovado
  var $info : Object
  $info:=New object()
  $info.privileges:=New collection("WebAdmin")
  Session.setPrivileges($info)
End if

Veja também

.getPrivileges()

.storage

História

Release	Mudanças
20 R5	Support of desktop sessions
18 R6	Adicionado

.storage : Object

Descrição

A propriedade .storage contém um objeto compartilhado que pode ser usado para armazenar informações disponíveis para todos os processos da sessão.

Quando um objeto Session é criado, a propriedade .storage está vazia. Como se trata de um objeto compartilhado, essa propriedade estará disponível no objeto Storage do servidor.

Como o objeto Storage do servidor, a propriedade .storage é sempre "single": adicionar um objeto compartilhado ou uma coleção compartilhada a .storage não cria um grupo compartilhado.

Essa propriedade é apenas de leitura, mas retorna um objeto de leitura e gravação.

tip

Você pode obter a propriedade .storage de uma sessão usando o comando Session storage.

When a desktop session and a web session are shared using an OTP, they also share the same .storage object.

Exemplo de sessão na web

Você deseja armazenar o IP do cliente na propriedade .storage. Você pode escrever no método de banco de dados 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

Exemplo de sessão remota

Você deseja compartilhar dados entre processos na mesma sessão:

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

.userName

História

Release	Mudanças
20 R5	Support of desktop sessions
18 R6	Adicionado

.userName : Text

Descrição

A propriedade .userName contém o nome de usuário associado à sessão. Pode usá-la para identificar o usuário dentro de seu código.

Web sessions: This property is an empty string by default. Ele pode ser definido usando a propriedade privileges da função setPrivileges().
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.

Tipos de sessão​

Resumo​

.clearPrivileges()​

Descrição​

Exemplo​

.createOTP()​

Descrição​

Exemplo​

.demote()​

Descrição​

Exemplo​

Veja também​

.expirationDate​

Descrição​

Exemplo​

.getPrivileges()​

Descrição​

Exemplo​

Veja também​

.hasPrivilege()​

Descrição​

Exemplo​

Veja também​

.id​

Descrição​

.idleTimeout​

Descrição​

Exemplo​

.info​

Descrição​

.isGuest()​

Descrição​

Exemplo​

.promote()​

Descrição​

Exemplo​

Veja também​

.restore()​

Descrição​

Exemplo​

Veja também​

.setPrivileges()​

Descrição​

Exemplo​

Veja também​

.storage​

Descrição​

Exemplo de sessão na web​

Exemplo de sessão remota​

.userName​

Descrição​

Tipos de sessão

Resumo

.clearPrivileges()

Descrição

Exemplo

.createOTP()

Descrição

Exemplo

.demote()

Descrição

Exemplo

Veja também

.expirationDate

Descrição

Exemplo

.getPrivileges()

Descrição

Exemplo

Veja também

.hasPrivilege()

Descrição

Exemplo

Veja também

.id

Descrição

.idleTimeout

Descrição

Exemplo

.info

Descrição

.isGuest()

Descrição

Exemplo

.promote()

Descrição

Exemplo

Veja também

.restore()

Descrição

Exemplo

Veja também

.setPrivileges()

Descrição

Exemplo

Veja também

.storage

Descrição

Exemplo de sessão na web

Exemplo de sessão remota

.userName

Descrição