Users

Status: Work in progress

Version	Date	Author	Status	Description
0.1	2024-12-19	isierra	WIP	Initial version
0.2	2025-04-03	isierra	WIP	Refactor

Tdp.Users repository

Introduction

The purpose of the users module is to manage the users of the system, their roles, and the permissions they have. The module is responsible for the following entities:

• Roles: Group of permissions that can be assigned to users
• Users: The users of the system
• UserProject: The relation between a user and a project
• UserGroup: Group of users that can be assigned to roles
• UserSession: The session of a user in the system

Role Requirements

A role is a group of permissions that can be assigned to users. The role is the entity that is assigned to a user, and the permissions are the operations that the user can perform.

Roles can be broad when including multiple permissions from multiple module, or specific when including only a few permissions from a single module. It all depends on the needs of the clients.

All roles belong to a project. All its operations are Multi-Tenant

Role Descriptions

The fields of a role corresponding to the description are:

Field	Type	Description	Contraints
DisplayName	DisplayName	The display name of the role.
Description?	string	The description of the role.

Example:

• Role: Project Manager
  • DisplayName: Project Manager
  • Description: Allows the user to manage the project definitions, like zones, gammas, BIM models, etc.

Role Access Type

A role has a single access type, that indicates the kind of permissions that can be assigned to the role.

The access type is assigned during the role creation, and it cannot be changed later. The access type is used to filter the permissions that can be assigned to the role.

The fields of a role corresponding to the access type are:

Field	Type	Description	Contraints
AccessType	enum	The access type of the role.

Role Permission Assignments

The role should have a list of permissions that are assigned to it. For each permission the assignment should indicate if the permission is allowed or denied.

The fields of a role corresponding to the permission assignments are:

Field	Type	Description	Contraints
PermissionAssignments	PermissionAssignment list	List of permissions assigned to the role.

Where a PermissionAssignment has the following fields:

Field	Type	Description	Contraints
PermissionId	ModuleElementId	The identifier of the permission.
Mode	PermissionMode	The mode of the permission.

The PermissionMode is an enum with the values: None, Allowed, Denied.

When computing the permissions of a user, the system should check all the permission assignments for roles assigned to the user, and for each permission type take the least permissive assignment. This means that if a permission is allowed in one role and denied in another, the permission should be denied, using the hierarchy as corresponding.

Role1	Assignment1	Role2	Assignment2	Permission	Result
create	Allowed ✅	x		create	Allowed ✅
building	Allowed ✅	x		create	Allowed ✅
create	Denied ❌	x		create	Denied ❌
building	Denied ❌	create	Allowed ✅	create	Denied ❌
x		update	Allowed ✅	create	Denied ❌
x		x		create	Denied ❌
building	Allowed ✅	create	Allowed ✅	create	Allowed ✅
update	Denied ❌	create	Allowed ✅	create	Allowed ✅

Legend

In this example:

• create refers to operation A:core.M:zones.R:building.O:create.
• update refers to operation A:core.M:zones.R:building.O:update.
• building refers to resource A:core.M:zones.R:building.
• x refers to no assignment given for the hierarchy of the operation.

Only permissions that are allowed for the access type of the role should be permitted to be assigned to the role.

Also, only global permissions and permissions belonging to current user’s project are allowed to be assigned to the role.

Role Visibility

The role should store a list of entities that are visible to the users that have that role. The visibility is used to filter the entities that are shown to the user in the user interface, or to third party services when using the API in behalf of the user.

Each service is responsible to interpret and apply the visibility from the user to their own entities.

The fields of a role corresponding to the visibility are:

Field	Type	Description	Contraints
Visibility	VisibilityEntity list	List of entities visible to the role.

The fields of a visibility entity are:

Field	Type	Description	Contraints
EntityType	string	The type of the entity.
EntityId	EntityId	The identifier of the entity or wildcard *.

An entity id with a wildcard * indicates that the user has access to all entities of the given type in the project.

E.g. a role could include in its visibility list the following list of entities:

EntityType	EntityId	Description
Zone	zone001	User can see zone001 in the project.
Zone	*	User can see all zones in the project.
Folder	fldr004	User can see fldr004 in the project.
Gamma	gamma005	User can see gamma005 in the project.

Role Create

An project manager can create a Role. The role should be created in the project of the current user’s session.

The creation need the following information:

• Display name: The display name of the role. This is a mandatory field.
• Description: The description of the role. This is an optional field.
• Access type: The access type of the role. This is a mandatory field.
• Permissions: The permissions that are assigned to the role. It is a list with 0 or more permissions. The permissions are filtered by the access type of the role.
• Visibility: The visibility of the role. It is a list with 0 or more entities.

Role Update

A project manager can update a Role from its project.

The update need the following information:

• Display name: The display name of the role. This is a mandatory field.
• Description: The description of the role. This is an optional field.
• Permissions: The permissions that are assigned to the role. It is a list with 0 or more permissions. The permissions are filtered by the access type of the role.
• Visibility: The visibility of the role. It is a list with 0 or more entities.

The access type of the role cannot be changed.

Role Delete

A project manager can delete a Role from its project.

Role List

A project manager can list the roles of the user’s project.

The list operation should allow filtering by the access type and search text. The search text should be used to filter the display name and the description of the role.

The user should be able to order roles by display name, creation and modification dates, and access type.

Roles should have default pagination behavior.

Role Details

A project manager can see the details of a Role from its project.

A role details should include all information from the role, including creation and modification dates.

User Requirements

A user represents an identity in the system. It can be a person or a third party service. The user is the entity that interacts with the system, and it is the one that is assigned to roles.

The user is Single-Tenanted, because a single user could interact with multiple projects. It is the UserProject entity the one responsible for associating a given identity with a project.

Field	Type	Description	Contraints
UserId	EntityId	The identifier of the user.	prefix:usr

User Types

There are four different types of users: GlobalAdministrator, Local, Service and External.

• GlobalAdministrator is a user that has access to all the projects in the system. The global administrator is the one that creates the system and manages it. They, as local users in the fundamental, are created in the system’s Active Directory.
• Local users are users defined in the system’s Active Directory. They are the users that can log in to the system using their credentials without the need to go to an external IdP. These are the TDP administrators and any user of a client that does not use an external IdP. Local users can be global administrators, or can be associates with as many UsageLicense’s as needed.
• External users are users defined in their own IdP. They are the users that can log in to the system using their credentials from an external IdP. Those IdP’s are associated with UsageLicenses so that their external users can be associated with the projects of the system. External users cannot be global administrators.
• Service users represent third party services that interact with the system. They are used to authenticate and authorize third party services with a ClientId and a ClientSecret. Services are associated with a single UsageLicense because they are non-interactive, they cannot swap between projects. Also, they take their access level the same way as any other user, but if there is no quota for them, they will be denied access to the system. Service users cannot be global administrators.

Once created, a user cannot change its type.

User Email

Field	Type	Description	Contraints
Email	string	The email address of the user.	email

• Email: must be UNIQUE in the system.

User Descriptions

Field	Type	Description	Contraints
DisplayName	DisplayName	The display name of the user.
GivenName	DisplayName?	The given name of the user.
Surname	DisplayName?	The surname of the user.

User Contacts

Every user has a required contact Email to ensure the uniqueness of the user in the system, and as a mean to notify the user about important events.

Additionally, each user can have a list of contacts to receive notifications. Each contact have a type and a configuration.

In the notifications module, an administrator will be able to define notification channels on each project. Some are simple like Email and SMS, with no additional setup, others are more complex like WhatsApp, Slack, WebHooks, with configuration like passwords, API keys, etc.

The contact type is a notification channel identifier, and the configuration is a JSON object with the configuration needed to send notifications to that channel, like the email, phone number, Slack channel, etc.

A user will be able to configure for each notification category, priority and time calendar, which channels will be used to send notifications.

Field	Type	Description	Contraints
ContactId	string	The identifier of the contact.	prefix:cntct
DisplayName	DisplayName	The display name of the contact.
ChannelId	EntityId	Notification channel identifier.	prefix:chnl
Value	JSON	Configuration needed to send notifications to that channel.	schema:channel

The required Email is considered a built-in contact (cannot be deleted or modified) with the following values:

• ContactId: cntct<user-id>
• DisplayName: Email
• ChannelId: chnlemail (built-in channel)
• Value: { "email": "<user-email>" }

A user manages his own contacts, and can add or remove them at any time, except for the required Email contact.

The built-in channels are:

• chnlemail: Email channel. The configuration is a JSON object with the email address of the user.
• chnlphone: Phone/SMS channel. The configuration is a JSON object with the phone number of the user and the type of phone (mobile, landline, etc.).

User Contacts Examples

ContactId	DisplayName	ChannelId	Value
cntct001	Home Email	chnlemail	{ "email": "john@example.com" }
cntct002	Work Phone	chnlphone	{ "phone": "+34123456789", "type": "mobile" }
cntct003	Home Phone	chnlphone	{ "phone": "+34987654321", "type": "landline" }
cntct004	Slack Superv.	chnl012347	{ "channel": "#supervisors" }
cntct005	Slack Personal	chnl012348	{ "channel": "@john" }
cntct006	Web Hook	chnl012349	{ "url": "...", "headers": "...", ... }

User Licenses

Some users can be associated with a UsageLicense. This is the case of local users and service users. External users are associated with an IdP, and their UsageLicenses are managed by the IdP.

Field	Type	Description	Contraints
UsageLicenses	EntityId list	The list of UsageLicenses of the user.	prefix:uslic

User Active

Field	Type	Description	Contraints
IsActive	bool	Indicates if the user is active and can login
PublicReason	string	The public reason for the deactivation.
InternalReason	string	The internal reason for the deactivation.

When a user is deactivated it cannot log in to the system anymore. The deactivation must be accompanied with a public reason to communicate to the user why they are deactivated, and an internal reason to communicate to the administrators. All the sessions of a deactivated user are automatically closed.

User Global Operators Parameter

The User’s module has a parameter to indicate the list of global users that are operators of the system.

Some notifications are directed to global operators, and they use this parameter’s value to get their contacts and send notifications to them.

• Display name: Global Operators
• Description: List of users that are operators of the system.
• Parameter path: core.users.user.global_operators
• Parameter scope: System
• Parameter read/write access: Global Administrator
• Parameter type: EntityId list
• Default value: []

User Project Operators Parameter

The User’s module has a parameter to indicate the list of users that are operators of each project.

Some notifications are directed to project operators, and they use this parameter’s value to get their contacts and send notifications to them.

• Display name: Project Operators
• Description: List of users that are operators of the project.
• Parameter path: core.users.user.project_operators
• Parameter scope: Project
• Parameter read/write access: core.users.user.create
• Parameter type: EntityId list
• Default value: []

User Global Administrator Create

A global administrator can create another global administrator. The email’s domain should not be assigned to any of the existing IdP’s in the system.

There is no purge timer for global administrators, and they can log in to the system immediately. The system should send an email to the user with the credentials.

Includes:

• User Email
• User Descriptions
• User Contacts
• User Active

User Local Create

Local users are created always from the context of a project by a project manager or a global administrator having selected the project. See UserProject for more details on user-project relation.

Because the user is created in the system’s Active Directory, the email’s domain should not be assigned to any of the external IdP’s in the system.

Once the user is created, the system should send an email to the user with the credentials, and start a timer to purge the user if the user does not log in within a certain period of time (30 days by default). The system must send a reminder email to the user every 7 days until the user logs in or the timer expires. The system must be able to send a warning to a project operator 5 days before the timer expires, so he can decide to extend the timer or let it expire.

The information needed to create a local user is:

Field	Type	Description	Contraints
ExpirationDays?	int	The number of days until the user expires.	def:30

Includes:

• User Email
• User Descriptions
• User Contacts
• User Licenses
• User Active
• UserProject Security
• UserProject Visibility
• UserProject Groups
• UserProject Active

The user creating the user, must include in the UsageLicense list at least one that allows access to the current project.

The creation of a local user triggers the following actions:

• Creates a new standard user in the system with the given information.
• Creates or finds a user in the Active Directory with the given information, returning the ObjectId of the user.
• Updates the user in the system with the ObjectId of the user in the Active Directory.
• Sends an email to the user with the credentials and the expiration date.
• Starts a timer to purge the user if the user does not log in within the expiration date.
• Sends a reminder email to the user every 7 days until the user logs in or the timer expires.
• Sends a warning email to the administrator 5 days before the timer expires.

User External Create

When a user belongs to an external IdP, the user is created in the system when the user logs in for the first time. The system should create a new user with the information provided by the IdP.

The external IdP must provide in the token the following information:

• DisplayName: The display name of the user. This is a mandatory field.
• Email: The email address of the user. This is a mandatory field.
• GivenName: The given name of the user. This is an optional field.
• Surname: The surname of the user. This is an optional field.
• IdentityProvider: The identity provider of the user. This is a mandatory field.
• ObjectId: The object identifier of the user in the IdP. This is a mandatory field.

The external users never expire, cannot be global administrators, and their UsageLicenses are recovered from the IdP, which could change during the lifetime of the user.

The creation of an external user triggers the following actions:

• Creates a new external user in the system with the information given by the IdP.
• Updates the user with the IdP identifier (from projects module).

User Service Create

A global administrator can create a Service user that represents a third party service for a client that wants to access the system through the API.

The information needed to create a service user is:

Field	Type	Description	Contraints
ClientId?	string	The existing ClientId of the app registration.

Includes:

• User Email
• User Descriptions
• User Contacts
• User Licenses
• User Active

The creation of a service user triggers the following actions:

• Creates a new service user in the system with the given information.
• Creates or finds an app registration in the Active Directory with the given information, returning the ObjectId of the user.
• Updates the user in the system with the ObjectId of the user in the Active Directory.

Needs further specification

The system should take care of setting up a policy to rotate the ClientSecret of the service user. The policy should be configurable, and the system should be able to send emails to all the contacts in the list.

User First Create

When the system has no users, the first authenticated user is created and automatically assigned as a global administrator and the data from the Active Directory’s token is used to create the user. No password flow or expiration date is needed.

User Login

When a user/service logs into Active Directory, they receive a token, usually encoded as a JWT. This is received by the frontend or the third party service, and it is sent to the backend for validation and session creation.

There must be an API in the backend to request to open a session for the user. The response of this request will include the session ID, any further steps required by the user to get the session ID, or an error message.

User Login Step 1: Authentication Flow

When the user enters into a protected page in the frontend.

• The frontend checks if the user is logged in to the system, using a session cookie, token or any other mechanism.
• If the user is not logged in, the frontend redirects the user to TDP IdP (Azure Active Directory B2C)
  • The TDP IdP asks the user for his email address to find out his domain and redirect to the correct IdP, or validate the user against the local Active Directory.
• The user logs in to the IdP, and the IdP returns an identity token to the frontend. This token includes, among other things:
  • DisplayName: The display name of the user.
  • Email: The email address of the user.
  • GivenName: The given name of the user.
  • Surname: The surname of the user.
  • IdentityProvider: The identity provider of the user. It is a domain name that identifies the IdP, like client.com or mycompany.onmicrosoft.com.
  • ObjectId: The object identifier of the user in the IdP. (Azure User ID)
• At this point, the user is authenticated in the IdP, but not yet in the system.
• The frontend must request an access token to the TDP IdP to access the backend API in behalf of the user.
  • The access token must include the previous attributes of the user, so that the backend can identify the user in the system and create or update his profile.
  • The access token must be signed by the TDP IdP, so that the backend can verify its authenticity.
• The frontend sends the access token in every request to the backend API.

Request Context

The request context, depending on the service we are using it, could contain the attributes included in the access token. Only some of the attributes contained in the request token are persisted with events and projections (none of the ones included in the token), like ProjectId, SessionId, UserId (not ObjectId). For this reason, when processing events only some of the attributes are available, and the system must be able to recover the rest of the attributes if needed.

The following diagram represents the flow of information when the user logs in to the system using the frontend and the TDP IdP.

User Login Step 2: Gateway

The backend is protected by an API Gateway that validates the access token received from the frontend.

• The API Gateway checks if the access token is valid, not expired, and signed by the TDP IdP.
• The API Gateway checks if the request includes a SessionId, usually in the headers or as a query parameter.
  • If the SessionId is present, the Gateway issues an POST users/api/user-session/access request (see User session access), indicating if the session must be updated or only validated against expiration.
    • If access is granted, the resulting headers will be included in the request to the actual requested endpoint.
    • If access is denied, the Gateway will return an error message indicating that the session is not valid or has expired.
  • If the SessionId is not present, only very specific endpoints can be called, like the one to create a new session for the user.

The following diagram represents the flow of information when the user makes a request to the backend API without an access token or session ID. Only a few endpoints are allowed to be called without an access token, none for the moment, but in the future it could be extended to allow access to dashboards, anonymous forms, customized visitors, etc.

Anonymous Sessions

In the future, the system could allow anonymous sessions, where the user does not need to log in to access certain endpoints, but still have a session created for validating access.

This would allow access for anonymous visitors with a limited set of features and time span, from public links sent by email or other means, or from a public page that allows users to interact with the system without logging in.

The following diagram represents the flow of information when the user makes an authenticated request to the backend API with an access token but without a session ID. Only some endpoints are allowed to be called without a session ID, like the one to create a new session for the user.

The following diagram represents the flow of information when the user makes an authenticated request to the backend API with an access token and a session ID. This is the most common case, where the user has already logged in and has a session created.

User Login Step 3: Session Creation

The frontend, upon receiving the access token, must start a workflow to request a session for the current user.

• The frontend must send a request to the backend API to create a session for the user, including the access token received from the IdP. The request must include a Mode property to indicate the following values:
  • Interactive: The user is interacting with the system, and the session creation could require further steps to complete.
  • Immediate: The user is not interacting with the system, and the session creation should return the session ID immediately if the user is found, or an error message if the user is not found or cannot be created with given information.
• The system must find the user by its ObjectId in the access token, not by the UserId, not yet available in the request.
  • If the user is not found, the system must locate the IdP in the system from the IdentityProvider field in the token.
    • If the IdP is not found
      • The system must check if there is no user defined yet in the system.
        • If there is no user, the system must create a new global administrator and act as if the user was actually found.
        • If there is at least one user, the system must return an error message indicating that the user cannot be created because the IdP is not found.
      • Otherwise the system must return an error message indicating that the IdP is not found.
    • When the IdP is found, the user must be created using the User External Create process and act as if the user was actually found.
• After the user is found or created, we know his UserId and UserType.
  • If UserType is GlobalAdministrator, with Immediate mode, the system must create a session for the administrator with no project and return the session ID.
  • If UserType is GlobalAdministrator, with Interactive mode, the system must get the list of projects.
    • If no project is found, the system must create a session as global administrator and return the session ID.
    • If projects are found, the system must return a list of projects to select from, allowing the user to select a project to open the session, or indicate the AdminMode property to GlobalAdmin to open a session without a project.
  • If UserType is other than GlobalAdministrator, with Immediate mode, the parameters for UsageLicenseId, ProjectId and AccessType must be set in the request, and must be validated
    • If any of the indicated parameters are missing or invalid, the system must return an error message indicating that the parameters are required.
    • If a session can be created with the given parameters, the system must create a session for the user and return the session ID.
  • If UserType is other than GlobalAdministrator, with Interactive mode:
    • The system must get the list of UsageLicenses associated with the user, directly or through the IdP, if any.
      • If the combined list of UsageLicenses is empty, the system must return an error message indicating that the user cannot open a session because there are no UsageLicenses available for the user.
      • If the combined list of UsageLicenses has only one UsageLicense, the system should select it and continue with the rest of the steps.
      • If the combined list of UsageLicenses has multiple UsageLicenses, the system must return a list of UsageLicenses to select from, allowing the user to select one of them. Use the SelectLicense step to select a UsageLicense from the list.
    • The system must validate that the user has access to the selected license.
  • After a single UsageLicense is selected, the system must check if there is enough quota for the user to open a session.
    • If there is enough quota, the system must create a new session for the user and return the session ID.
    • Otherwise, the system must check whether the AccessType of the user allows other choices of AccessType to start a session. If there is any other choice, the response will include further instructions to SelectAccessType with the list of AccessTypes to select from (ID and name). Upon receiving this response, the user/client service have to issue a new request with the same token and the selected AccessType ID. The new request must include the previously selected UsageLicense ID, if any.
    • If there is no other choice, the system must return an error message indicating that the user cannot open a session due to lack of quota.

A session request could include some of these selections from the beginning (in the case of a service user), or it could be an interactive process (in the case of a user).

The session includes information about the user, their selections of UsageLicense and AccessType, and the project they are associated with.

Once a session is created, a user could issue a new session request for a different UsageLicense or AccessType, and have them open simultaneously. Each open session will consume its own quota, and the user will be able to use them independently. An administrator will be able to log out an individual session, or all sessions for a given user.

When an external user logs in for the first time in one of his assigned projects (through the IdP’s UsageLicense), the system will create a UserProject resource for the user in that project, and assign the roles and visibility as specified in the UsageLicense extension implemented in current service (PENDING to be documented but already developed).

When a local user or service logs in, its assignment to a UsageLicense already implies the creation of the UserProject resource in the system, so that resource already exists.

When a global administrator logs in, no UserProject resource is created, as the administrator has access to all resources in the selected project.

The following diagrams represent the starting flow of information when the user requests a new session in the system, either immediately or interactively.

The following diagram represents the flow of information when the user is a global administrator.

Needs more diagrams

Missing diagrams for normal users.

User Impersonation

A global administrator will be able to select a user to impersonate, to solve any issue the user may have. The impersonation will be done by opening a session in behalf of the user, and the administrator will be able to see all the information of the user. No administrative operations will be allowed while impersonating a user, and the administrator will be able to log out or switch session at any time.

Needs further specification

User Import

TBD

Import users from MantTest.

User Update

Who can update what to whom?

Who	To whom	Descriptions	Contacts	Usage Licenses	Active
Global	Local	✅	❌	✅	✅
Global	Service	✅	✅	✅	✅
Global	External	❌	❌	❌	✅
Manager	Local	✅	❌	✅	✅
Manager	Service	❌	❌	❌	❌
Manager	External	❌	❌	❌	✅
Local	Him-self	✅	✅	❌	❌
External	Him-self	❌	✅	❌	❌
Service	It-self	❌	❌	❌	❌

User Delete

A user can be soft-deleted from the system by a global administrator or manager. Its information will be kept in the system for auditing purposes, but the user will not be able to log in to the system anymore.

Some restrictions apply to the deletion of a user:

• A user cannot delete itself.
• All sessions of a deleted user are closed.

User Details

An administrator can see the details of a user. The details should include all information from the user.

User List

A global administrator can list all global users in the system. To check the users of a project, the administrator should open a session in the project.

Field	Shown	Filterable	Sortable	Text Search
DisplayName	✅	✅	✅	✅
Email	✅	✅	✅	✅
UserType	✅	✅	✅
IsActive	✅	✅	✅
LastLoginDate	✅	✅	✅

UserProject Requirements

User-project specific data is stored into the UserProject entity.

UserProject Security

The user’s security inside a project is indicated through role assignments.

Field	Type	Description	Contraints
Roles	EntityId list	List of roles assigned to the user in the project.	prefix:rol
AccessType	enum	Access type of the user in the project, calculated from the roles.

UserProject Visibility

The user’s visibility inside a project is indicated through the Visibility field. The visibility is used to filter the entities that are shown to the user in the user interface, or to third party services when using the API in behalf of the user.

A VisibilityManager is a global service, implemented in some module of the system, that is responsible for managing part of the visibility of a Role/UserProject. They take some entity types as input and return some other entity types as output. Multiple visibility managers can be enabled for a Role/UserProject at the same time, but the order in which they declared in the list is important.

Field	Type	Description	Contraints
Visibility	VisibilityEntity list	List of entities visible to the user in the project.
VisibilityManagers	EntityId list	Indicate how to interpret the visibility of the user in the project.

• See Role Visibility for more details.

Suggestion

There must be an API to compute the final visibility of a user given its roles, user-defined visibility and the visibility managers. The UI must show the result, together with the source that were used to compute each entry (role, user, manager), so that an administrator can understand how the visibility is computed. As this process is better defined, more information can be included in the computation, like the source entity that produced the visibility.

The two built-in manager are:

• Manual: Is a default non-existing manager that allows the user to define any visibility for the user. The administrator can add specific entity instances using the entity selector, or he can use the wildcard for the entity, which when finally saved, will remove any other entry for that entity type. The user will be able to also check a global administrator option, to set the wildcard to all entity types. The UI must also provide a way to clear all instances from an entity type.

Examples of other visibility managers:

• ZoneManager: Defined in the Resources module, has zones as input entities and resources as output entities in shared mode. It computes which resources the user can see in the project from the zones assigned to the user.
• ResourceManager: Defined in the Resources module, has resources as input entities and zones as output entities in shared mode. It computes which zones the user can see in the project from the resources assigned to the user.
• ContractManager: Defined in the Resources module, has contracts as input entities and resources and zones as output entities in shared mode. It computes which resources and zones the user can see in the project from the contracts assigned to the user.

Each manager should have an abundant documentation to explain how it works, and how to use it.

UserProject Groups

Groups are used to make users aware of activity in their groups. When a user belongs to a default group, some of their activity adds the group identifier to the related resources so that other users from the same group can interact with those resources.

Field	Type	Description	Contraints
GroupAssignments	GroupAssignment list	List of group assignments.
DefaultGroup?	EntityId	Default group assigned to the user in the project.	prefix:usrgrp

A group assignments has the following fields:

Field	Type	Description	Contraints
GroupId	EntityId	The identifier of the group.	prefix:usrgrp
AllowReading	bool	Indicates if the user can list/read resources in the group.
AllowWriting	bool	Indicates if the user can modify resources in the group.

Example:

• There is a resource Ticket in a different module that works with user groups.
• User Alice is the manager of the Sales Department group. AllowReading and AllowWriting are set to true.
• User Bob is the secretary of the Sales Department group. AllowReading is set to true.
• User Charlie and David are members of the Sales Department group. No permissions are set.
• When any of those users create a ticket, the ticket is assigned to the Sales Department group and to the user that created the ticket.
• When Charlie lists the tickets, he can see the tickets assigned to himself, because he has no extra permissions on the group.
• When Bob lists the tickets, he can see the tickets assigned to himself and to the Sales Department group, because he has AllowReading permission on the group.
• When Bob wants to modify a ticket, he can only modify the tickets assigned to himself, because he has no AllowWriting permission on the group.
• When Alice lists the tickets, she can see all the tickets assigned to herself and to the Sales Department group, because she has AllowReading and AllowWriting permissions on the group. She can also modify any ticket assigned to the group.

UserProject Active

A user can be active or inactive in a project. The user can log into a project only if he is active both in the system and in the project.

Field	Type	Description	Contraints
IsActive	bool	Indicates if the user is active in the project.
PublicReason	string	The public reason for the deactivation.
InternalReason	string	The internal reason for the deactivation.

UserProject Create

See User Local Create for a complete definition of this operation.

UserProject Update

An project manager can update a UserProject from its own project.

See User Update for more information of this operation.

Includes:

• User Descriptions
• Only if current user is editing himself
  • User Contacts
• Only if current user is global administrator and target user is local or service.
  • User Licenses
  • User Active
• Only if user is project manager
  • UserProject Security
  • UserProject Visibility
  • UserProject Groups
  • UserProject Active

UserProject Delete

Because the UserProject is generated automatically from a UsageLicense, it cannot be explicitly deleted. The user can be deactivated, the UsageLicense can be removed for the user (if it is local or service), or from the IdP (if it is external, but it affects all the users from the IdP). When the UsageLicense is removed, the UserProject is deleted automatically. If the UsageLicense is restored later, the same UserProject is restored.

UserProject Details

All information from the user is available in the UserProject entity. The details should include all information from the user and the project. Depending on the current user and the target user, some fields may not be available (see User Update for more information).

UserProject List

LastLoginDate is the last date the user logged into the project. This field is updated every time the user logs into the project. The global LastLoginDate in the User is also updated when the user logs into the project.

UserGroup Requirements

A user group is a collection of users that belong to a business related group, like a department, a team, etc. It allows som members of the group to list, read and modify some specific end-user’s related resources, like tickets, room bookings, etc. in behalf of the group.

All groups belong to a single project.

The members of a group are described from the UserProject entity, but there must be an API to allow editing the members of a group from the UserGroup entity.

UserGroup Descriptions

A user group has a display name and a description.

Field	Type	Description	Contraints
DisplayName	DisplayName	The display name of the group.
Description	Description	The description of the group.

User Group Create

A user group can be created by a project manager.

User Group Update

A user group can be updated by a project manager.

User Group Delete

A user group can be deleted by a project manager. A subscription must update any user that was assigned to the group, removing the group from the user.

UserSession Requirements

A user session is a representation of a user logged into the system. It is created when a user logs into the system, and it is used to track the user’s selections of UsageLicense and AccessType, as well as the project they are associated with.

UserSession Create

Any user with a JWT token must request a session creation in order to access the resources in a project.

As described in User Login, the session creation process can include the selection of a UsageLicense and an AccessType, as well as the project they are associated with. In case those selections are missing, the system will return further instructions to select them.

The fields of the session creation are:

Field	Type	Description	Contraints
JWT (1)	string	The implicit JWT token of the user.
Mode	SessionMode	The mode of the session creation.
AdminMode?	AdminMode	The admin mode of the session.
UsageLicenseId?	EntityId	The selected UsageLicense ID.	prefix:uslic
ProjectId?	EntityId	The selected project ID.	prefix:proj
AccessType?	AccessType	The selected AccessType.

(1) The JWT token is the one received from the IdP (AAD B2C in our case), and it is used to identify the user in the system. It must be sent in the request header as Authorization, like in every other request to the API. It is indicated here for clarity, but it is not a field of the session creation request body. See User Login Step 1: Authentication Flow for more details on the information contained in the JWT token.

The Mode field indicates how the session creation should be handled:

• Interactive: The session creation process may require further steps to complete, like selecting a UsageLicense, a Project or an AccessType.
• Immediate: The session creation process should return the session ID immediately if the user is found, or an error message if the user is not found or cannot be created with given information. This mode is used for service users that already have all the necessary information to create a session without any interaction.

The AdminMode field indicates if the session is created in admin mode, allowing the user to access the global space or a project without a UsageLicense. The possible values are:

• GlobalAdmin: The session is created in global admin mode, allowing the user to access the global space without a UsageLicense or a ProjectId. The user will be able to manage projects, licenses, users, etc. in the global space. No further selections are needed, and no quota is consumed.
• ProjectManager: The session is created in project manager mode, allowing the user to access a project without a UsageLicense. The user will be able to manage/read the project resources, like zones, users in projects, user groups, rooms, calendars, etc. The UsageLicense is not needed in this case, and no quota is consumed, as the global admin is not associated with any UsageLicense. The AccessType is set to Manager and cannot be changed, as the user is a project manager. No further selections are needed.
• Impersonator: This is a future mode, where a global administrator can impersonate another user from a project. The administrator will be able to select a user from the selected project, and then enter as that user, even in the session creation process, but keeping the administrator ID for all operations performed during the impersonation. The administrator will be able to log out or switch session at any time, and the impersonation will not affect the user’s sessions or operations. This kind of session, even when having a UsageLicense and AccessType, will not consume any quota, as it is only used for investigation purposes. NOTHING TO DO FOR NOW THOUGH, JUST A FUTURE FEATURE.

As a response, the system will return the session ID, or further instructions to select a UsageLicense, a Project or an AccessType:

Field	Type	Description
Status	SessionCreationStatus	The status of the session creation request.
SessionId?	EntityId	The ID of the created session, if successful.
ErrorMessage?	string	An error message, if any.
ErrorCode?	string	An error code, if any.
UsageLicenses?	UsageLicenseDesc list	The list of UsageLicenses to select from, if needed.
Projects?	ProjectDesc list	The list of Projects to select from, if needed.
AccessTypes?	AccessTypeDesc list	The list of AccessTypes to select from, if needed.

The SessionCreationStatus enum have the following values:

• Success: The session was created successfully, and the response includes the session ID.
• SelectLicense: The user must select a UsageLicense from the list provided in the response. The response includes the list of UsageLicenses to select from (ID, client name and project alias/display name).
• SelectProject: The user must select a Project from the list provided in the response. The response includes the list of Projects to select from (ID and alias/display name).
• SelectAccessType: The user must select an AccessType from the list provided in the response. The response includes the list of AccessTypes to select from (ID and name).
• Error: An error occurred during the session creation process. The response includes an error message.

Important

Only a global administrator can receive a SelectProject response, as they are not associated with any UsageLicense. They can select a project to open a session without needing a UsageLicense.

The UsageLicenseDesc describes a license and associated project that a user can use to open a session. It includes the following fields:

Field	Type	Description
UsageLicenseId	EntityId	The identifier of the UsageLicense.
ClientName	string	The name of the client associated with the license.
ProjectId	EntityId	The identifier of the UsageLicense.
ProjectAlias	string	The alias of the project associated with the license.

The ProjectDesc describes a project that a user can use to open a session. It includes the following fields:

Field	Type	Description
ProjectId	EntityId	The identifier of the Project.
ProjectAlias	string	The alias of the project.

The AccessTypeDesc describes an access type that a user can use to open a session. It includes the following fields:

Field	Type	Description
AccessType	AccessType	The identifier of the AccessType.
DisplayName	string	The name of the AccessType.

Important

A global administrator must select the session settings from the first session request, because they can enter the global space or a project.

For example, if a global admin requests a session without any additional setting, the system will create a session for the global space with no UsageLicense, no ProjectId and no AccessType. In such case, they will be able to manage projects, licenses, users, etc. in the global space, but they will not be able to access any project resources until they open a session in a project.

If the global admin selects a project and an AccessType (Manager by default), the system will create a session for that project with the selected AccessType, and they will be able to manage/read the project resources, like zones, users in projects, user groups, rooms, calendars, etc. The UsageLicense is not needed in this case, and no quota is consumed, as the global admin is not associated with any UsageLicense.

Reminder

In the future, a global administrator will be able to enter the system as another user, with the same session creation process, but selecting the user to impersonate. This will allow the administrator to see the system as the user sees it, and to solve any issue the user may have.

The session will record the user that the administrator is impersonating, but the administrator ID will be used for all operations performed during the impersonation. The administrator will be able to log out or switch session at any time, and the impersonation will not affect the user’s sessions or operations. This kind of session, even when having a UsageLicense and AccessType, will not consume any quota, as it is only used for investigation purposes.

UserSession List

A global administrator can list all user sessions in the system. To check the sessions of a project, the administrator should open a session in the project.

Field	Shown	Filterable	Sortable	Text Search
SessionId	✅	✅	✅
UserId	✅	✅	✅
UserIsAdmin	✅	✅	✅
UserDisplayName	✅	✅	✅	✅
UserEmail	✅	✅	✅	✅
UsageLicenseId?	✅	✅	✅
ClientName?	✅	✅	✅	✅
ProjectId?	✅	✅	✅
ProjectAlias?	✅	✅	✅	✅
AccessType?	✅	✅	✅
StartDate	✅	✅	✅
LastAccessDate	✅	✅	✅
ClosedAt	✅	✅	✅
Duration	✅
IsOpen	✅	✅	✅

Important

A user with a current session assigned to a project can only see the sessions of that project, and not the global sessions.

A global admin with a current session assigned to no project can see all sessions in the system, including the global sessions and the sessions of all projects.

Suggestion

The values for the derived fields UserDisplayName, UserEmail, ClientName, and ProjectAlias are obtained from the corresponding entities in the system at the moment of creation of the session. They are not updated if the user or project information changes later.

Suggestion

The Duration field is calculated from the StartDate to the ClosedAt or now, if the session is still open. It is a TimeSpan value that indicates how long the session has been open. This could make the filtering/sorting of the sessions more complex, so it is not included in the filterable or sortable fields.

UserSession Details

A user session has the following fields:

Field	Type	Description
SessionId	EntityId	The identifier of the session.
UserId	EntityId	The identifier of the user associated with the session.
UsageLicenseId?	EntityId	The identifier of the UsageLicense selected by the user to open the session.
AccessType?	AccessType	The AccessType selected by the user to open the session.
ProjectId?	EntityId	The identifier of the project associated with the session.
StartDate	DateTime	The date and time when the session was started.
LastAccessDate	DateTime	The date and time when the session was last accessed.
ClosedAt	DateTime?	The date and time when the session was closed, if applicable.
Duration	TimeSpan	The duration of the session, calculated from StartDate to ClosedAt or now.
IsOpen	bool	Indicates if the session is open or closed.

Suggestion

The Duration field is calculated from the StartDate to the ClosedAt or now, if the session is still open. It is a TimeSpan value that indicates how long the session has been open. It’s value is only stored in the database when the session is closed, but it can be calculated on the fly when the session is open.

UserSession Access

The access command to a session is a special operation that is called for every request with a session in a system. It is used to check if the session is still open, and to update the LastAccessDate field of the session.

The access command have the following fields:

Field	Type	Description	Contraints
UpdateLastAccess	bool	Indicates if the LastAccessDate should be updated.

The successful result of the access command returns the following fields:

Field	Type	Description
UserType	UserType	The type of the user associated with the session.
UserId	EntityId	The identifier of the user associated with the session.
ProjectId?	EntityId	The identifier of the project associated with the session.
UsageLicenseId?	EntityId	The identifier of the UsageLicense selected by the user to open the session.
AccessType?	AccessType	The AccessType selected by the user to open the session.
UserProjectId?	EntityId	The identifier of the UserProject associated with the session.
AdminMode?	GlobalAdminMode	The mode of the session, if the user is a global administrator.
StartDate	DateTime	The date and time when the session was started.
UsesQuota	bool	Indicates if the session consumes quota.

The conflicted result of the access command returns the following fields:

Field	Type	Description
Reason	string	The reason why the session is not open or has expired.

The reason could be one of the following:

• UserLoggedOut: The user has logged out of the session.
• SessionExpired: The session has expired due to inactivity.
• SessionClosed: The session has been closed by a project manager or by a global administrator, with a specific reason.

UserSession Close

A user session can be closed by the user or by a global administrator. When a session is closed, the ClosedAt field is set to the current date and time, and the IsOpen field is set to false.

When a User or UserProject is deleted or deactivated, all sessions associated with that user are closed automatically. The ClosedAt field is set to the current date and time, and the IsOpen field is set to false.

The following fields are used to close a session:

Field	Type	Description	Contraints
Reason	string	The reason for closing the session.

UserSession Delete

The system must delete all sessions that are closed more than a year ago. The deletion is done automatically by a background job that runs periodically.