Projects
Status: Work in progress
| Version | Date | Author | Status | Description |
|---|---|---|---|---|
| 0.1 | 2025-01-03 | isierra | WIP | Initial version |
Introduction
The Projects module belongs to the core domain of the system and is responsible for managing modules, projects, licenses, contracts, etc.
The purpose of the projects module is to manage the projects of the system, their clients, licenses, and other entities and processes. The module is responsible for the following entities:
- Module: Represents a module of functionality on the system that can be enabled or disabled for a given project.
- Cultures: Represents the different cultures that can be used in the system, defining the language, the date format, and other cultural data.
- Project: Represents a project, which is a set of resources that belong to a given client and they need to manage them as a cohesive unit.
- Module License: Represents a license that allows a project to use a module, defining the different parameters that limit the use of the module.
- Usage License: Represents a license that allows to specify the number of users that can access the project, the number of users that can access the project at the same time, and other parameters that limit the use of the project.
Module Requirements
A module represents a set of features on the system that can be used as a cohesive unit. The module can be enabled or disabled for a given project, and it can have different configurations depending on the project that is using it.
A module has to indicate different configurable parameters that can be used to customize the behavior of the module for a given project. These parameters can be used to enable or disable features, change the behavior of the module, or customize the appearance of the module.
A module has to indicate a set of autorizable operations in the form of permission descriptions. These descriptions can be used to define the permissions that a user needs to have to perform a given operation on the module.
Module Definition
The creation of the modules is a task that is performed by the system itself, as it is not expected that a user will create a new module. Each service that implements the system has to define the modules that it provides, and communicate its configuration to the projects module.
This should be an internal API accessible to the rest of the services in the platform. Each service is responsible for periodically updating the modules that it provides.
Each module has to define the following information:
- Module Code: A unique code that identifies the module. Can be used in domain names, URLs, and other places where a short code is needed.
- Display Name: A human-readable name that identifies the module. It can be used in the UI as titles, in e-mails as the module name, and other places where a human-readable name is needed.
- Module Version: A version number that identifies the version of the module.
- Description: An optional text that describes the module, its purpose, and other relevant information.
- Change Log: A list of changes that have been made to the module in each version. This list is used to inform the users of the changes that have been made to the module.
- Configurable Parameters: A list of parameters that can be used to customize the behavior of the module for a given project.
- Permissions: A list of permission descriptions that define the permissions that a user needs to have to perform a given operation on the module.
- DependsOnModules: A list of modules that this module depends on. This list is used to define the order in which the modules are initialized when a project is created.
- Active by default: A boolean that indicates if the module is active by default when a project is created. If this is set to false, the module has to be enabled manually by the project administrator.
Module List
This is a global list of all the modules in the system.
Only platform administrators and internal services should be able to perform this operation.
The list operation should show the following information:
| Field | Visible | Text Search | Filter | Sort |
|---|---|---|---|---|
| Module Code | ✅ | ✅ | ✅ | ✅ |
| Display Name | ✅ | ✅ | ✅ | ✅ |
| Description | ✅ | |||
| Active by default | ✅ | ✅ | ✅ |
Module Details
The module details should be accessible to the system administrators and the project administrators. The module details should show all the information relevant to the module, like the display name, the description, the configurable parameters, and the permissions.
There is no option to update the module from the UI, as this is a task that is performed by the system itself. The module details should be read-only, and the user should not be able to modify any information.
Module Permissions
A permission is an entity representing an operation that can be performed on a resource type
The following examples show some permissions over a resource type called Meeting Room:
- Can create a Meeting Room: This would be a permission that allows a user to create a meeting room, defining all its properties and relationships
- Can view details of a Meeting Room: This would be a permission that allows a user to view the details of a meeting room, but not to modify them
- Can modify a Meeting Room: This would be a permission that allows a user to modify the properties of a meeting room
- Can delete a Meeting Room: This would be a permission that allows a user to delete a meeting room
- Can list all Meeting Rooms: This would be a permission that allows a user to list all the meeting rooms in the system
- Can show security code of a Meeting Room: This would be a permission that allows a user to show the security code of a meeting room
Module Permissions hierarchy
Permissions should be grouped by the resource they are related to and the area of the application they belong to. This will help to organize the permissions and make it easier to find.
This hierarchy of permissions is proposed by each service on the system, and will not change without creating a breaking change in the system.
The hierarchy could be expressed with a hierarchical identifier, like a path, where each part of the path represents a level of the hierarchy.
Each permission should have an order in it’s own group, to make explicit the importance of the permission or group in its context. Like putting the most common operations first, or the most important resources first. For permissions of the same order, they should be ordered alphabetically.
The module code should be used as the root of the hierarchy.
Module Operation permissions
Permissions associated to operations are the only ones that can be assigned to a role. The grouping of permissions is only for organization purposes in the user interface.
The operation part of the permissions indicate the kind of operations. Most operations will be of a known type, like read, create, modify, delete, but some other specific operations could be defined like approve, print, etc. The known operation types will be used in the user interface to group the permissions in columns.
The known operation types are: Read, Create, Modify, Delete.
The permission should store the operation type and the hierarchical identifier of the permission in different fields, to make it easier to filter and group the permissions.
Module Permissions descriptions
Each permissions should be easy to understand with a simple caption in a default human language. Also a longer description should be provided to give more context about the operation, in case the user needs more information.
Example:
- Permission: Can create a Meeting Room
- Display name: Create Meeting Room
- Description: Allows the user to define a new meeting room in the system
Module Permissions Access Types
Permissions should indicate the type of access that a role must have to be able to assign that permission to a user. The access types are:
- Manager: They can work on the project definition, like creating rooms, updating users, etc.
- Worker: They can work on the project execution, like creating work orders, responding support tickets, etc.
- Reader: They can check project status, like indicators, reports, read data, etc.
- EndUser: They can interact with the project, like creating support tickets, modifying meetings, controlling devices, etc.
Typically, there is a partial ordering of the access types, indicated by the following diagram:
Each operation permission should indicate for each access type if it is allowed or not.
Module Global permissions
Some operations are only carried by the system administrators, like managing users, roles, projects, licenses, etc. These operations should not have permissions associated to them, because permissions and roles are associated to client users.
Module Configurable Parameters
The configurable parameters of a module are a set parameter definitions to describe which parameters can be configured for a given project. Each parameter definition should have the following information:
- Parameter Code: A unique code that identifies the parameter. Can be used in domain names, URLs, and other places where a short code is needed.
- Display Name: A human-readable name that identifies the parameter. It can be used in the UI as titles, in e-mails as the parameter name, and other places where a human-readable name is needed.
- Description: An optional text that describes the parameter, its purpose, and other relevant information.
- Data Type: The type of data that the parameter can store. It can be a string, a number, a date, a boolean, or other data types.
- Default Value: The default value of the parameter. This value is used when the parameter is not configured for a given project, or to reset the parameter to its default value.
Examples of configurable parameters are:
- Project Module:
- Enable Import/Export Projects: Whether the import/export functionality should be enabled
- Zones Module:
- Maximum number of BIM Models: The maximum number of BIM models that can be uploaded to the system
- Enable BIM: Whether the BIM functionality should be enabled
- Enable GIS: Whether the GIS functionality should be enabled
- Installations Module:
- Update Definitions: Whether the definitions of the installations should be updated automatically
- Warehouse Module:
- Enable Import/Export Inventory: Whether the import/export functionality should be enabled
- Indicators Module:
- Enable Infrastructure Indicators: Whether the infrastructure indicators should be enabled
Culture Requirements
The culture represents the different cultures that can be used in the system, defining the language, the date format, and other cultural data. The culture can be used to customize the behavior of the system for a given project, like the language of the UI, the date format, and other cultural data.
We are going to use the DotNet culture codes to represent the cultures, like en-US, es-ES, fr-FR, etc. Any format related to the culture should be compatible with the DotNet culture codes.
Culture Definition
The creation of the cultures is a task that is performed by the system itself, as it is not expected that a user will create a new culture. The list of cultures will be defined as a configuration on the system.
The following information should be defined for each culture:
- Culture Code: A unique code that identifies the culture. It should be the ISO 639-1 language code followed by the ISO 3166-1 alpha-2 country code, like
en-US,es-ES,fr-FR, etc. - English Name: The name of the culture in English. This name is used to identify the culture in the UI, in e-mails, and other places where a human-readable name is needed.
- Native Name: The name of the culture in its native language. This name is used to identify the culture in the UI, in e-mails, and other places where a human-readable name is needed.
Culture List
This is a global list of all the cultures in the system.
Only platform administrators should be able to perform this operation.
The list operation should show the following information:
| Field | Visible | Text Search | Filter | Sort |
|---|---|---|---|---|
| Culture Code | ✅ | ✅ | ✅ | |
| English Name | ✅ | ✅ | ✅ | |
| Native Name | ✅ | ✅ | ✅ |
No pagination should be allowed, because the number of cultures should be limited and the user should be able to see all of them.
Identity Provider Requirements
An identity provider is a service that authenticates users and provides information about them, like their name, e-mail, and other attributes. The identity provider can be used to authenticate users in the system, and to provide information about the users to the system.
Two types of identity providers are considered:
- SAML 2.0: A service that authenticates users using the SAML 2.0 protocol
- OAuth 2.0: A service that authenticates users using the OAuth 2.0 protocol
The system should be able to integrate with different identity providers, and to authenticate users using the identity provider that is configured for the project.
Project Requirements
The project is a significant entity in the system, as it groups all the resources that a client needs to manage. The project has a status that defines its lifecycle, and preferences that can be used to customize the behavior of the system for the project.
An administrator of the platform will be able to create a project to assign it to a client together with a renewable license that will specify the modules and the number of users that can access the project.
Project Creation
An administrator of the platform will be able to create a project by providing the following information:
- Project Code: A unique code that identifies the project. Can be used in domain names, URLs, and other places where a short code is needed.
- Display Name: A human-readable name that identifies the project. It can be used in the UI as titles, in e-mails as the project name, and other places where a human-readable name is needed.
- Description: An optional text that describes the project, its purpose, and other relevant information.
- Default culture: The culture that will be used by default in the project.
- Modules: A list of modules that are available for the project and their configurations.
The project will be created in the Creating status as long as this process is not finished. The creation process will notify the administrator that created the project when it is ready to be used, or any interaction needed to complete the creation process.
During creation, all modules will have a chance to initialize any data that is needed for the project, like seed data, configuration data, etc.
Project Status and Access Level
The project can be in different status depending on its lifecycle:
- Creating: The project is being created. Implied access level: Administrator
- Active: The project is actively being used by the client that created it. Implied access level: Open
- Maintenance: The project is being prepared or updated. Implied access level: Manager
- Inactive: The project cannot be used by the client, for the time being. Implied access level: Administrator
A typical workflow for the status project is:
The project can have different access levels depending on its status:
- Administrator: Only global administrators can access the project
- Manager: Only global administrators and client managers can access the project
- Reader: All but client end-users and workers can access the project (???)
- Open: All users can access the project
The authorization mechanism will consider this access level to allow or deny access to the project for any given user or operation he/she wants to perform.
Project Inaccessible Message
When a user tries to access a project that is not accessible to him/her, the system should show a message that explains the reason why the project is not accessible. The message should be clear and concise, and should not reveal any sensitive information about the project.
Project List
The list of projects should be globally accessible by platform administrators.
The list should show the following information:
| Field | Visible | Text Search | Filter | Sort |
|---|---|---|---|---|
| Project Code | ✅ | ✅ | ✅ | ✅ |
| Display Name | ✅ | ✅ | ✅ | ✅ |
| Description | ✅ | |||
| Status | ✅ | ✅ | ✅ |
Pagination should be allowed, because the number of projects could be large and the user should be able to see a subset of them.
Project Details
The project details should be accessible to the system administrators and the project administrators. The project details should show all the information relevant to the project, like the display name, the description, the status, the access level, the default culture, and the modules.
Project Modification
An administrator of the platform will be able to modify a project by any of its attributes, except the project code.
Project Cloning
An administrator of the platform will be able to clone a project to create a new project with the same attributes as the original project. The new project will have a new project code, and the same attributes as the original project. Other attributes like the display name, status and access level can be modified during the cloning process.
The configuration should allow an administrator to select the modules that will be cloned to the new project, and the configurable parameters of the modules should be copied to the new project.
The cloning could share some features with the project export/import process, but it should be a simpler operation that does not require the encryption of the data.
This operation is not very urgent, but it is a good feature to have in the future.
Project Export and Import
An administrator of the platform will be able to export a project to a file, and import a project from a file. The export and import operations should include all the attributes of the project, including the modules and their configurations.
The configuration should allow an administrator to select the modules that will be cloned to the new project, and the configurable parameters of the modules should be copied to the new project.
The export and import operations should be used to backup and restore a project, or to move a project from one system to another.
An encryption key should be used to encrypt the exported file, and the same key should be used to decrypt the imported file. The encryption key should be stored securely by the exporting party so that no unauthorized access can be made to the exported file.
This operation is not very urgent, but it is a good feature to have in the future.
Usage License Requirements
A usage license is a statement of how many users of each type can access simultaneously the project, as well as information about the associated client, contacts, etc. Operations in the system will be measured against the license associated to each corresponding user, so that computing costs and billing can be done correctly.
Each project can have multiple usage licenses, each one associated to a different client, and each one with different costs and billing information.
Usage License Descriptions
Each usage license contains the following descriptive parameters that are set when creating or updating the license:
- Client Name: The required name of the client that is associated with the license
- Client culture: The culture that will be used to communicate with the client. it is a free text field, but it should be a valid .NET culture code.
- Client contacts: A list of contacts that are associated with the client. The system could send notifications to these contacts when the license is about to expire.
- Responsible for renewals: A list of contacts that are responsible for renewing the license. The system could send notifications to these contacts when the license is about to expire.
- Petition Required: Its a boolean that indicates if a petition is required to renew the license
- Non-billable license: Indicates if the license is non-billable. If it is non-billable, the license should not have new contracts associated with it.
Usage License Identity Provider
Each usage license can be associated with an external identity provider. When an external user use an IdP to log in, the licenses associated to that IdP will be offered to the user to select the project he/she wants to access.
| Field | Type | Description | Contraints |
|---|---|---|---|
IdentityProviderId? | EntityId | The unique identifier of the identity provider |
Usage License Contracts
Each license have a list of contracts that represent a payment agreement between the client and the system. Licenses set as Non-billable should not have new contracts associated. Any pre-existing contracts previously created should remain associated to the license.
Each contract has the following parameters:
- Start Date: The required date when the contract starts
- End Date: Indicates the last day the contract is valid.
- Amount: The required amount of the contract
- Amount Unit: The currency of the amount, which is a free text field and EUR by default
- Periodicity: The periodicity of the payment. It should be monthly, quarterly, semi-annually, or annually, but open to other values
- Payment Moment: The moment when the payment is done. It should be in advance or first month, second month or third month, but open to other values
- Proposal Path: The required path to the proposal that originated the license. It is a free text field.
- Notes: A free text field to add any additional information about the license
- External Project Code: The code that identifies the project in an external system, like NetSuite. It is a free text field.
The contract can be in any of the following statuses:
- Sent: The contract has been sent to the client
- Received: The contract has been received from the client
- In contract: The contract is in force
- Expired: The contract has expired automatically. A user cannot set this status manually or move a contract out of this status without changing the end date.
- Cancelled: The contract has been cancelled by the client or the system. When in this state, the contract should not be considered in the economic data calculations.
Usage License Economic Data
For each license, the system will register the costs and billing information, so that the system can calculate the total cost of the project, and bill the client accordingly.
- Contracted Amount: The total amount of the current contracts associated with the license. Only contracts in the status In contract should be considered.
- Contracted Amount Unit: The currency of the contracted amount. If more than one unit is found, indicate a Mixed unit.
- Status: Computed from the status of the different contracts. Can have the following values:
- Sent: If at least one contract is in the status Sent
- Received: If at least one contract is in the status Received and none in the status Sent
- In contract: If at least one contract is in the status In contract and none in the status Sent or Received
- Pending: If no contract is in the status In contract, Received or Sent
Status examples:
| Contract 1 | Contract 2 | Contract 3 | License Status |
|---|---|---|---|
| Sent | Sent | ||
| Received | Received | ||
| In contract | In contract | ||
| Sent | Received | In contract | Sent |
| Sent | In contract | Expired | Sent |
| Received | In contract | Expired | Received |
| In contract | In contract | Expired | In contract |
| Expired | In contract | In contract | |
| Expired | Expired | Pending |
Importance order: Sent > Received > In contract > Expired > Cancelled
License status update table: License + Contract => License
| Lic.\Contract | Sent | Received | In contract | Expired | Cancelled |
|---|---|---|---|---|---|
| Sent | Sent | Sent | Sent | Sent | Sent |
| Received | Sent | Received | Received | Received | Received |
| In contract | Sent | Received | In contract | In contract | In contract |
| Expired | Sent | Received | In contract | Pending | Pending |
| Cancelled | Sent | Received | In contract | Pending | Pending |
Project Economic Data
For each project, the system will compute the following economic data:
- Contracted Amount: The total amount of the current contracts associated with the project. Only contracts in the status In contract should be considered.
- Contracted Amount Unit: The currency of the contracted amount. If more than one unit is found, indicate a Mixed unit.
- Economic Status:
- Non-billable: If all licenses are non-billable
- Pending: If all licenses are in the status Pending
- In contract: If all licenses are in the status In contract
- Sent: If all licenses are in the status Sent
- Received: If all licenses are in the status Received
- Partially pending: If at least one license is in the status Pending and the rest are in the status In contract
- Partially sent: If at least one license is in the status Sent and the rest are in the status In contract or Received
- Partially received: If at least one license is in the status Received and the rest are in the status In contract or Sent
Status examples:
| License 1 | License 2 | License 3 | Project Status |
|---|---|---|---|
| Pending | Pending | Pending | Pending |
| In contract | In contract | In contract | In contract |
| Sent | Sent | Sent | Sent |
| Received | Received | Received | Received |
| Pending | In contract | Pending | Partially pending |
| Sent | In contract | Received | Partially sent |
| Received | In contract | Pending | Partially received |
Project status update table: Project + License => Project
| Project \ License | Sent | Received | In contract | Pending |
|---|---|---|---|---|
| Non-billable | Sent | Received | In contract | Pending |
| Sent | Sent | Partially Sent | Partially Sent | Partially Sent |
| Partially Sent | Partially Sent | Partially Sent | Partially Sent | Partially Sent |
| Received | Partially Sent | Received | Partially Received | Partially Received |
| Partially Received | Partially Sent | Partially Received | Partially Received | Partially Received |
| Pending | Partially Sent | Partially Received | Partially Pending | Pending |
| Partially Pending | Partially Sent | Partially Received | Partially Pending | Partially Pending |
| In contract | Partially Sent | Partially Received | In contract | Partially Pending |
Usage License Simultaneous Users
Each usage license will have the following parameters to define the number of users that can access the project at the same time:
- Managers: The number of managers that can access the project at the same time
- Workers: The number of workers that can access the project at the same time
- Reader: The number of Reader users that can access the project at the same time
- End-users: The number of end-users that can access the project at the same time
Usage License Calculations
All the statuses and economic data must be up-to-date, with at most 24 hours of delay. The system should calculate the status and economic data of the licenses and projects periodically, and update the data in the database.
Usage License List
The list of usage licenses should be globally accessible by platform administrators.
The list should show the following information:
| Field | Visible | Text Search | Filter | Sort |
|---|---|---|---|---|
| Project Name | ✅ | ✅ | ✅ | ✅ |
| Client Name | ✅ | ✅ | ✅ | ✅ |
| Non-billable license | ✅ | ✅ | ✅ | |
| Status | ✅ | ✅ | ✅ | |
| Contracted Amount | ✅ | ✅ | ✅ |
This list requires pagination, as the number of licenses can be large.
Usage License Details
The details of a usage license should be accessible by platform administrators and project administrators.
The details should show all the information of the license, including the contracts associated with the license.
Usage License Creation and Modification
The creation and modification of a usage license should be accessible by platform administrators.
The creation and modification should allow the administrator to set all the parameters of the license, including the contracts associated with the license.
Once created, the project cannot be modified, but the contracts can be modified to change the amount, the periodicity, the payment moment, etc.
Module License Requirements
The module license is a statement, per project, on whether a given module is enabled or disabled, and the values for the parameters of the module.
When a module is enabled on a project, a module license is created, where the administrator can set the values of the configurable parameters of the module. All modules that current modules depend on should be enabled first.
Module License Activation
When a module is enabled on a project, the system should create a module license for the project, with the default values of the configurable parameters of the module.
The user interface should indicate to the user all the modules that need to be activated before activating the current module, as well as the already activated modules. Also the parameters of all the activating modules should be shown during the activation of the current module.
- Module Code: The code of the module that is being activated
- Project Id: The id of the project where the module is being activated
- Parameters: The values of the configurable parameters of the module
- Notes: A free text field to add any additional information about the parameter.
Module License Modification
At any time, a platform administrator can update the parameter values and notes of any of the active modules in a single UI.
Module License Details
All services should be able to access the values of the parameters of the active modules of a project, to customize the behavior of the service for the project.