Difference between revisions of "UserManagement Core"

Latest revision as of 12:39, 5 February 2020

User Management

Introduction

User Management is a library that sits between the Liferay portal services and gCube portlets. The main functionality of the Library is to provide management of users, roles and organizations. It provides a layer of abstraction above the liferay services, hiding the configuration complexities of roles and organizations. The gcube requirement of roles in the scope of organization is achieved by creating a role with the organization name suffixed to it. The addition/removal of organization names to the role names are handled by the Library and are transparent to the application and portlets using the library.

Interfaces

The library exposes three interfaces:

• User Manager
• Role and Team* Manager
• Group Manager

(*)The notion of a Team is somewhat similar to a Role but a Role is a portal wide entity (Role exists in any VRE) while a Team is restricted to a particular VRE/VO.

These interfaces provide the functionalities necessary for CRUD operation on Users, Roles and Groups and additional functionalities that organise users into Teams and assigning/dismissal of roles.

Maven Dependency and Code repository

Add the following dependency to your maven project to use the library.

<dependency>
	<groupId>org.gcube.dvos</groupId>
	<artifactId>usermanagement-core</artifactId>
	<version>[2.0.0-SNAPSHOT, 3.0.0-SNAPSHOT)</version>
	<scope>provided</scope>
</dependency>

Please find this Java Library Open Source code at https://code-repo.d4science.org/gCubeSystem/usermanagement-core

UserManager APIs

The UserManager interface allows to create, retrieve and delete users. In order to perform such operations you need to instanciate the proper manager. See the below example.

// Instanciate the manager
UserManager userManager = new LiferayUserManager();
 
//you want to retrieve information about an existing user
GCubeUser userByMail = userManager.getUserByEmail(validUserMail);

The UserManager offers a lot of other utilities. They are reported below:

• get user information such as email, id, username, professional information, fullname and much more;
• list all the users (also by range: int start, int end);
• list users belonging to a given group (also by range: int start, int end);;
• remove users;
• remove users from groups;
• manage users' registrations and membership requests.

Listing Users by groupId and range

It is possible to define a range of all the users. Useful when paginating results and avoid to fetch them all.

LiferayUserManager#listUsersByGroup(long groupId, int start, int end) // start  is the lower bound of the range of users, while end is the upper bound of the range of users (not inclusive). Returns the range of users
 
LiferayUserManager#getGroupUsersCount(long groupId) //returns the total number of users in the given group / VRE

Search Users by groupId and keywords

It is possible to search all the users of a given groupId by the keywords (space separated), which may occur in the user's first name, middle name, last name, username, or email address. Useful when you are building an interface where a number of user accounts have to be selected (e.g. workspace share folder with).

LiferayUserManager#searchUsersByGroup(String keywords, long groupId) //all the users who match the keywords ordered by username (Ascendent order)

Reading User Custom Attributes

It is possible to define User's custom attributes and to Read and Update them. To do so the following methods should be used:

LiferayUserManager#readCustomAttr(long userId, String attributeKey) //which returns a java.io.Serializable
 
LiferayUserManager#saveCustomAttr(long userId, String attributeKey, Serializable value)

GroupManager APIs

The GroupManager interface allows to manage VRE, VO and ROOT VO of the gCube Infrastructure that are mapped on the Liferay's Site objects. It offers the APIs to create, delete and modify them. A gCube group is represented by a GCubeGroup class object. In order to perform such operations you need to instanciate the proper manager. See the below example.

// Instanciate the manager
GroupManager groupManager = new LiferayGroupManager();
 
// you can now retrieve the list of VREs, VOs or get the Root VO
GCubeGroup rootVO = groupManager.getRootVO();
 
// you can create a new VO (child of the root VO)
GCubeGroup newVO = groupManager.createVO("newVoName", rootVO.getGroupId(), "VO description goes here");
 
// you can now create a VRE (child of the just created VO)
 
....
 
// retrieve the groups to whom a given user belongs (given the user identifier)
List<GCubeGroup> listOfGroups = groupManager.listGroupsByUser(userId);

Among the other available functions, you can:

• check if a given group is a VRE, VO or root VO;
• retrieve the scope of the group;
• retrieve the infrastructure scope;
• manage virtual groups (i.e., a collection of groups).

RoleManager APIs

The RoleManager interface defines the manager that manipulates Roles and Teams in the gCube Portals. Both Roles and Teams are assigned to people, but a Role is inter-VREs (so it needs to be created once but assigned to users on any VRE you wish that role to be used), whereas a Team is restricted to a VRE or VO.

In other words the notion of a Team is somewhat similar to a Role but a Role is a portal wide entity (Role exists in any Site/VRE or VO) while a Team is restricted to a particular Site/VRE or VO.

The library uses two different classes to abstract them: GCubeRole and GCubeTeam respectively.

See the below example.

// instanciate the interface
RoleManager roleManager = new LiferayRoleManager();
 
// create a role
boolean created = roleManager.createRole("role name", "role description");
 
// retrieve the role's id by name
long roleId = roleManager.getRoleIdByName("role name");
 
// retrieve the object
GCubeRole role = roleManager.getRole(roleId);
 
// now you can assign this role to someone in a group (the group is necessary because that role must be assigned somewhere)
roleManager.assignRoleToUser(userId, groupId, roleId);
 
// list all roles
List<GCubeRole> roles = roleManager.listAllRoles();
 
// list roles by group (i.e., roles assigned to someone that belongs to that group)
List<GCubeRoles> rolesByGroup = roleManager.listAllRolesByGroup(groupId);
 
// list teams
List<GCubeTeam> teams = roleManager.listAllTeams();
 
// list teams by group
List<GCubeTeam> teamsByGroup = roleManager.listAllTeamsByGroup(groupId);
 
// assign a team to someone. There is no groupId here, because the teamId directly determines the group in which it was defined
roleManager.assignTeamToUser(userId, teamId);

You can also:

• delete teams/roles;
• remove a certain team/role to a user in a group;
• update team/role definitions.