Requirements
NFR1. GENERAL REQUIREMENTS
| Code | Requirement |
|---|---|
| NFR1.1 | All developed components must serve a single functionality |
| NFR1.2 | End-of-life (EOL) term (in case it is known and determined) for all technology components, platforms and third party components must exceed 3 years. |
| NFR1.3 | All technology components must be approved beforehand by Elering Development Division as well as Infrastructure Division. |
| NFR1.4 | It must be possible to run multiple instances of a service in question in parallel, without affecting the functionality of the system as a whole - both from redundancy and performance perspective. |
| NFR1.5 | Should external components (=not controlled by Elering) fail, other functionalities must remain usable. |
| NFR1.6 | Elerings software development quality management principles must be followed by both internal and external developers. |
| NFR1.7 | English language is to be used for all development artifacts (e.g source code, log messages, technical documentation). |
| NFR1.8 | All timestamps must be in ISO-8601 format. |
| NFR1.8.1 | Front-end must support customer preferred timezone. |
| NFR1.8.2 | UTC must be used as the time zone for: - web-service logs; - back-end |
| NFR1.9 | All developed components must be deployable independently from other functions and services. |
NFR2. DOCUMENTATION
Following documentation must be delivered together with the software at the latest when the software is delivered to be installed to the test environment:
NFR2.1. High-Level and Detailed Requirements and Design Documentation
The requirement and design documentation must include the following:
| Code | Requirement |
|---|---|
| NFR2.1.1 | description of who needs the system and why; |
| NFR2.1.2 | description of what the system should do; |
| NFR2.1.3 | description of how the system should do it. |
| NFR2.1.3.1 | data models, including logical data model. |
Other requirements:
| Code | Requirement |
|---|---|
| NFR2.1.4 | BPMN 2.0 should be used for business process diagrams. |
| NFR2.1.5 | UML 2 notation should be used for system design diagrams. |
NFR2.2. Architecture
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.2.1 | Logical structure with layering. |
| NFR2.2.2 | Technical descriptions (physical data model) and diagrams including: - technologies and tools used, - interfaces, - connections, - protocols - dependencies. |
NFR2.3. Software deployment (installation) guide
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.3.1 | System requirements, pre-requisites (other server software or libraries required by application – including their versions) in step-by-step format. |
| NFR2.3.2 | Upgrade guide from the latest version running on production – in step-by-step format. |
| NFR2.3.3 | Installation guide (100% install) – in step-by-step format. |
| NFR2.3.4 | External resources and configuration guide. |
NFR2.4. Update guide
NFR2.5. Configuration guide
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.5.1. | Lists containing locations for all configuration files and configuration tables. |
| NFR2.5.2 | Configuration examples. |
| NFR2.5.3 | Description of settings specific to test environment. |
NFR2.6. Backup guide - only for common products
NFR2.7. Recovery guide - only for common products
NFR2.8. Sizing/Scaling guide - only for common products
| Code | Requirement |
|---|---|
| NFR2.8.1. | Must include the following: - Estimated amount of users/requests AS IS. - Estimated growth of the amount of users / requests during predictable lifetime of the information system in question. - Possible sizing/scalability options. |
NFR2.9. Maintenance and help guide - for all products and services
| Code | Requirement |
|---|---|
| NFR2.9.1. | Must include a list of maintenance tasks. |
NFR2.10. Changelog
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.10.1. | References to all of the development requests created within the current version. |
| NFR2.10.2. | All changes in configuration (regardless of the technology that was used for those changes), for example: - changes in application configuration itself, - webserver request/response header changes, - RabbitMQ configuration application needs, - etc. |
| NFR2.10.3. | Extra steps needed for introducing a new release. |
| NFR2.10.4. | Changes in user permissions (role or privilege). |
NFR2.11. Component model (with all software components what are realizing business logic within one application).
NFR2.12. Data models
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.12.1. | Description of all the tables (including a description for every field in the table). |
| NFR2.12.2. | Logical data model with associations. |
| NFR2.12.3. | Description of OpenAPI3 schemas. |
| NFR2.12.4. | Annotation for all personally identifiable information in data models. |
NFR2.13. Deployment diagram
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.13.1. | Deployment diagram must be realized as a block diagram visualizing: - Relationships between different information systems components. - Integrations with other systems. |
| NFR2.13.2. | Logical names that describe the primary function of the unit must be used instead of actual network names when naming boxes that are used to visualize servers. |
NFR2.14. API documentation
Must include the following:
| Code | Requirement |
|---|---|
| NFR2.14.1. | API technical description; |
| NFR2.14.2. | Authentication guide; |
| NFR2.14.3. | Quickstart guide; |
| NFR2.14.4. | Endpoint definitions; |
| NFR2.14.5. | Code snippets; |
| NFR2.14.6. | Example responses. |
Additional requirements:
| Code | Requirement |
|---|---|
| NFR2.14.7. | OpenAPI 3.0 must be used; |
| NFR2.14.8. | All personally identifiable information has to be annotated in API schemas. |
| NFR2.14.9. | API documentation must include validatable object schemas for input and output. |
| NFR2.14.10. | Code must be generated from API specification. |
| NFR2.14.11. | API must meet 100% automated tests coverage |
NFR3. SECURITY
| Code | Requirement |
|---|---|
| NFR3.1. | Authentication credentials (username, password, etc.) of all interfaces must be encrypted in transit. |
| NFR3.2. | The authentication system must enable to lock and unlock user accounts manually or based on a predetermined account lockout policy. |
| NFR3.3. | User ID lock and unlock functions must be performed via dedicated UI and/or API with specific credentials. |
| NFR3.4. | All interfaces requiring authentication that are available via public Internet must use Elering's central authentication system. |
| NFR3.5. | Any executable containing business logic must not need privileged system level accounts (root, LOCALSYSTEM, etc.) or need to be granted similar permissions for its regular everyday work. |
| NFR3.6. | In case Active Directory is used, then StartTLS or LDAP over SSL must be utilized for LDAP queries. |
| NFR3.7. | System credentials in plain text must only be stored in the configuration files that are needed to start up the application. |
| NFR3.8. | Configuration files stored in repository must not contain any passwords. |
| NFR3.9. | The client session must also be ended on server side. |
| NFR3.10. | Client session timeout length must be configurable. |
| NFR3.11. | To avoid cross-site request forgery attacks, UI requests should contain verification (e.g. Bearer Token), which is validated when receiving data from user. |
| NFR3.12. | Input validation must be done via server-side validation using API description documentation (e.g. JSON Schema, OpenAPI). |
| NFR3.13. | All input data must be validated in the back-end. |
| NFR3.14. | When developing Web-based UI solutions, at least the latest version of OWASP top 10 application security risks must be mitigated. |
| NFR3.15. | All Internet-facing web interfaces must: - adhere to the latest version of OWASP Application Verification Standard Level 1 for applications that display public data; - adhere to Level 2 for applications that process confidential data and require client authentication. |
| NFR3.16. | All Internet-facing web interfaces must use HTTPS with a trusted certificate issued by a publicly accessible Certification Authority. |
| NFR3.17. | A single session must always be validated against single client (IP, Browser). |
| NFR3.18. | Authentication process must give the user all new session tokens; session tokens must not be reused. |
| NFR3.19. | If Information System allows file upload from user: - All file uploads must require prior authentication of the user. - All file types must be verified via a magic number check. - All uploaded files must be scanned using anti-malware software. - After verification, the verified files must be renamed for storage before saving them into the file system. - Maximum file size must always be set and checked by the Information System. |
| NFR3.20. | All client requests must go through server-side authentication and authorization checks before they are processed. Client-side controls must not be relied upon. |
NFR4. AVAILABILTY AND PERFORMANCE
| Code | Requirement |
|---|---|
| NFR4.1. | Page response time must be less than a second. |
| NFR4.2. | If page response time is more than a second, the system must display a loading indicator for the user. |
| NFR4.3. | For bigger datasets, pagination should be used. |
| NFR4.4. | All components must be scalable horizontally and/or vertically. |
NFR5. SERVER SOFTWARE VERSIONS AND SOFTWARE ARCHITECTURE
Note: Exact list of the supported server software versions is included in Appendix 1.
| Code | Requirement |
|---|---|
| NFR5.1. | Server process must be able to run as a service/daemon. - (Meaning that such a process must not require the operating system user to remain logged in, leave some windows open, or to send processes to the background (in Linux)). |
| NFR5.2. | Operating systems temporary directory must be used for storing temporary files. |
| NFR5.1. | All source code should be stored in Elering's repository. |
| NFR5.2. | Source code must include instructions and scripts on how to create deployment packages (e.g. war, ear, msi etc.) |
| NFR5.3. | Separate releases should be recognized by release branches. |
| NFR5.4. | All database changes not realized in liquibase must be delivered as SQL scripts, must use UTF-8 encoding and must not include ByteOrderMark. |
| NFR5.5. | It must be possible to install and upgrade MS Windows client software using central deployment tools and msi- or exe-type installers must be used on MS Windows platform and they must be executable and configurable using command line utility. It must also enable installation for all users. |
| NFR5.6. | Data maintenance scripts must be delivered together with software (for example: archiving). |
| NFR5.7. | Database deployment scripts must not be compiled. |
| NFR5.8. | Format of the deployment packages is subject to a separate agreement between developers and infrastructure group. |
| NFR5.9. | Applications should accept environment variables from the configuration files. |
| NFR5.10. | Application should not fail to start if any of external data sources are unavailable. |
| NFR5.11. | In case of any external data source failure, application should retry the failed action at a pre-configured time. |
| NFR5.12. | In case of JNDI, application should use externally configured JDBC pool. |
| NFR5.13. | All testing code must be omitted while packaging the application for production environment. |
| NFR5.14. | It must be possible to build deployment-ready packages using a single command of build script. |
| NFR5.15. | It must be possible to build the whole system in an air-gapped environment. All dependencies must be made available as part of final artifact. |
| NFR5.16. | File names must be descriptive and refer to the applicable functionality. |
| NFR5.17. | Docker multi-stage build must be used. |
| NFR5.17.1. | Released images must not contain tools and libraries needed for building the package. |
| NFR5.17.2. | Docker images provided by Elering or Official Docker images must be used. |
| NFR5.18. | All deployment and installation scripts and configuration files are part of the source code and must be stored in git, but in separate repository. |
| NFR5.19. | All environment variables must be configured in CD tool (gitlab). |
| NFR5.20. | In case AD is used, the following must be configurable: - AD connection parameters - AD group names - search base DN name |
| NFR5.21. | In case AD is used, the user group membership must be validated by searching targeted CN and search path must be configurable. |
| NFR5.22. | Paged queries (max 1000 rows at a time) must be used instead of global catalog, when doing LDAP queries. |
| NFR5.23. | CI/CD pipelines must be built using with a base provided by Elering. |
| NFR5.24. | All used external libraries and packages must be updated regularly to their latest version. |
| NFR5.25. | Codebase should use package by feature architecture and within each feature, package by layer should be used. |
NFR6. DATABASE
| Code | Requirement |
|---|---|
| NFR6.1. | All foreign keys in the database must be indexable. |
| NFR6.2. | When calling SQL code from outside the database, Parameter Binding should be used to prevent SQL cache fragmentation. |
| NFR6.3. | All tables in the database should have defined primary key, with the unique header ID. |
| NFR6.4. | If business logic does not demand otherwise, archiving data to another database should be allowed. |
| NFR6.5. | Solutions database permissions must be as minimal as possible and included in the documentation. |
| NFR6.6. | Separate system user account must be used for data model changes. |
| NFR6.7. | All databases must be with UTF-8 encoding. |
| NFR6.8. | All database tables, fields and other code (stored procedures, functions, triggers, views, user defined data types and sequences), must be commented at the same level as rest of the source code. |
| NFR6.9. | It must be possible to identify the last modification time of every database record, even without using audit trail or other similar technologies (for example: last modified field). |
| NFR6.10. | Database collation must be approved beforehand Elering infrastructure division. |
| NFR6.11. | MSSQL Databases must support Always On Availability Groups with Multi-Subnet Failover Cluster, (for faster failover, connection string must support: „MultiSubnetFailover=True“). |
NFR7. CONFIGURABILITY
| Code | Requirement |
|---|---|
| NFR7.1. | Software must be configurable using configuration objects. Objects that contain program code in addition to configuration parameters cannot be considered to be configuration files. As an alternative, the configuration can be stored in the database table. In that case, whole configuration must be located in the same table and there must not be any non-configuration related data stored on that table. Configuration must be stored in key-value format. |
| NFR7.2. | All the parameters must be described with a comment on the previous line before occurrence of the parameter, or on the separate field (in case of the database table). |
| NFR7.3. | Delivered program code must not contain passwords that have been used in development nor references to the development resources. |
| NFR7.4. | Changes in the application's configuration should not require its recompilation or re-installation. |
| NFR7.5. | There must not be the need to configure the same parameter twice under one software component. For example, if web-application connects to the database, then the database connection must be configurable only in one location. |
| NFR7.6. | Software upgrade must not overwrite application configuration - all exceptions should be agreed beforehand. |
| NFR7.7. | All the configuration on custom-made applications must be divided into two segments - admin-configuration and business-configuration. Admin-configuration must ONLY include the following: |
| NFR7.7.1. | endpoints (incl. host/user/pw), for example ftp hosts; |
| NFR7.7.2. | datasources; |
| NFR7.7.3. | local dir paths; |
| NFR7.7.4. | logging configs, for ex. log4j; |
| NFR7.7.5. | certs and Cert paths; |
| NFR7.7.6. | all other parameters that need to have environment-specific values. |
| NFR7.8. | By default, each application must have separate configuration objects. |
| NFR7.9. | Business-configuration must be part of the deployment package, while admin-configuration samples must be delivered separately and cannot be overwritten with new deployment. |
| NFR7.10. | Application must support hostnames as address configuration, application must always support hostname resolution. |
| NFR7.11. | Every application parameter must be in configuration object. |
| NFR7.12. | All configuration parameter key names should mirror their use. |
NFR8. INTEGRATIONS AND DATA TRANSFER
| Code | Requirement |
|---|---|
| NFR8.1. | If API exists, it must be used to create integrations. Any exceptions should be agree beforehand with ITAN. |
| NFR8.2. | Self-made API for third party software products must be documented and its architecture must be agreed with ITAN. |
| NFR8.3. | Every integration using database link must be agreed upon with the ITAN. |
| NFR8.4. | When using publishing/subscription model, usage of RabbitMQ is required. |
NFR9. LOGGING
NFR9.1. General requirements
| Code | Requirement |
|---|---|
| NFR9.1.1. | If logging level is not specified then all events must be logged on INFO level. |
| NFR9.1.2. | Default log levels are: |
| NFR9.1.2.1. | FATAL level - Only messages indicating stop of process must be logged on FATAL level; |
| NFR9.1.2.2. | ERROR level - Only messages that require actions taken from administrator (either to restore normal operation or to notify business users/developer) must be logged with ERROR log level; |
| NFR9.1.2.3. | WARN level - Designates potentially harmful situations; |
| NFR9.1.2.4. | INFO level - Designates informational messages that highlight the progress of the application at coarse-grained level; |
| NFR9.1.2.5. | DEBUG level - Designates fine-grained informational event data that are most useful to debug an application; |
| NFR9.1.2.6. | TRACE level - Designates finer-grained informational event data than the DEBUG with all possible technical data. |
| NFR9.1.3. | Preliminary logging configuration must be provided. |
| NFR9.1.4. | Log messages must be saved in a structured format that would make it possible to perform log-based analysis and alerting, using third party tools. |
| NFR9.1.5. | Date must be in YYYY-mm-dd format (for example 2019-02-24). |
| NFR9.1.6. | If application is conteinerized all logs should be written to stdout |
| NFR9.1.7. | Sensitive personal information must not be included in any logs. |
| NFR9.1.8. | System must never log: |
| NFR9.1.8.1. | user credentials; |
| NFR9.1.8.2. | private keys; |
| NFR9.1.9. | If system logs in to file: |
| NFR9.1.9.1. | When logging into file, every day (or even every hour) should be logged on a separate file. |
| NFR9.1.9.2. | Log file name must consist a date that this file holds records about. |
| NFR9.1.9.3. | If the configured log file does not exist and application has file system privileges for creating it, then it must be able to do so. |
| NFR9.1.9.4. | If log file is not created then application must stop. |
NFR9.2. Logging of user activities
| Code | Requirement |
|---|---|
| NFR9.2.1. | User activities must be logged from all parts of information systems handling identifiable user request. A separate log appender have to be used for such logs. |
| NFR9.2.2. | All errors displayed to user (defined and non-defined) must be logged. |
| NFR9.2.3. | Logging requirements for the back-end: |
| NFR9.2.3.1. | in the back-end all token creations must be logged with user information and users IP; |
| NFR9.2.3.2. | any request received from the front end with user information; |
| NFR9.2.3.3. | any requests published (pushed) to the front end with user information. |
| NFR9.2.4. | Logging requirements for the front-end: |
| NFR9.2.4.1. | UI must be able to log specific user activities concretely defined for each UI application separately with user information; |
| NFR9.2.4.2. | UI must log error messages including error dialogues presented to user with user information. |
NFR9.3. Application logging. Software must enable the logging of at least following events:
| Code | Requirement |
|---|---|
| NFR9.3.1. | In case login is handled by the application: |
| NFR9.3.1.1. | all successful and unsuccessful login attempts; |
| NFR9.3.1.2. | login method; |
| NFR9.3.1.3. | ending of user session, logout. |
| NFR9.3.2. | all transfer of data (input and output) between systems (on INFO level must log actions when sending or getting data, on DEBUG level detailed data must be logged. On TRACE level transfer of data between application and database with queries); |
| NFR9.3.3. | all user operations including creating, viewing, changing and deleting data; |
| NFR9.3.4. | requests processing time (for example HTTP, AMQP, JMS); |
| NFR9.3.5. | technical errors and uncaught exceptions (logged on ERROR level); |
| NFR9.3.6. | security violations with indicated user credentials (logged on ERROR level). |
| NFR9.3.7. | Log message must contain date, time and time zone. |
NFR10. MONITORING
| Code | Requirement |
|---|---|
| NFR10.1. | Every web application must provide its health status page, that displays information in machine readable format. Must contain at least all outgoing connectivity details according to component model. |
| NFR10.2. | All the checks on the page must be executed asynchronously. |
| NFR10.3. | Regular polling of the monitoring page (once per 20 seconds max) must not degrade system performance and total response time of the monitoring page must also not exceed 20 seconds (timeouts that can be configured by administrator, must be implemented for every check on the page). Every single check must be marked as failed when its configurable timeout is reached. Single check timeout must not exceed 5 seconds by default. |
| NFR10.4. | If application does not have a user interface, then separate health page should exists. |
| NFR10.5. | Headless patch processes, which is not intended to work continuously, must push it's version and state info into Prometheus push-gateway. |
| NFR10.6. | Every application must provide its info page, that displays information in machine readable format. Must contain at least version, build time and artifact ID. |
NFR11. TESTING
| Code | Requirement |
|---|---|
| NFR11.1. | Test must use a minimal number of assertions and test one logical aspect/behavior. |
| NFR11.2. | Dependencies must be isolated in unit testing using mocks and stubs. |
| NFR11.3. | The name of a test must use the following template: - The name of method being tested; - The scenario Under which it’s being tested; - The expected behavior when the scenario is invoked. |
| NFR11.4. | Minimum statement coverage for unit testing must meet 80%. |
NFR12. STACK - ARCHITECTURE REQUIREMENTS
Note: Exact list of the supported stack is included in Appendix 1.
Appendix 1 – supported software stack
| Software/Technology type | Required and supported software/technology/version |
|---|---|
| General | |
| Source code repository | Git (Gitlab) |
| Binary repository | Artifactory |
| CI/CD pipelines manager | Gitlab for image building, ArgoCD for deployment |
| Containers | Docker |
| Container orchestration | Kubernetes |
| Platform | |
| Linux | 64 bit non commercial editions, CentOS 7 is prefferred |
| Microsoft Windows Server | 2019 |
| Virtualization layer | Vmware (7.0) |
| Back-end | |
| Build script | Gradle |
| Development language | Java 11+ LSB versions |
| Java Frameworks | Spring Boot Spring Framework Spring Security |
| Authentication | Eleringi SSO (based on OpenID) |
| API | AMQP (RabbitMQ) REST |
| Front-end | |
| Development language | JavaScript Typescript(preferred) SCSS/CSS HTML |
| Frontend Framework | Angular 11+ (preferred out of three, but not mandatory) React JS 17+ Vue 2.6+ |
| Database | |
| Database | MS SQL Server 2019 or newer is prefferred Postgres MongoDB |
| Schema versioning | Liquibase |
| Object storage | |
| System | MinIO |