diff --git a/docs/p4samd/handbook/document-engine.md b/docs/p4samd/handbook/document-engine.md new file mode 100644 index 0000000000..d212a1d67c --- /dev/null +++ b/docs/p4samd/handbook/document-engine.md @@ -0,0 +1,110 @@ +--- +id: document_engine +title: Documentation Engine +sidebar_label: Documentation Engine +--- + +# Documentation engine + +## Overview +This module offers a centralized Documentation Engine to streamline compliance by automating the generation of regulated artifacts. +A default set of IEC 62304-compliant templates is provided to allow users a quick startup: templates can be extensively customized thanks to our editor (.markdown, .docx) and enriched by system data through provided variables and custom structure. +The documentation shaped from the templates can be generated and downloaded in the preferred format for every version of your Software System. + +![Documentation Engine Table](./img/documentation_engine_table.png) + +## Features + +### Template Management + +P4SaMD provides a default set of templates to help you start with a IEC 62304-compliant framework. +For enabled users, it is always possible customize and manage templates: +- **Creating** new templates to extend the default template set +- **Editing** a template, to align the structure to your company QMS and the deliverables required for your product. +- **Publishing** a template to make it visible in the System Version Dashboard and ready for the documentation download +- **Deleting** the templates when no more needed (the records would be archived in P4SaMD database, but not available to users) + +For each template the following informations are available: + +- **Title**: Changeable title for the template +- **Revision**: Automatic version tracking for the published templates. +- **Last Edit Date/Time**: Timestamp of the most recent modification +- **Editor**: User who performed the last edit +- **Status**: Template state indicator + - `Draft`: Template in progress + - `Published`: Template available for use +- **Actions**: Available actions per template row (based on user permissions): + - `Edit/View`: Modify or view template content + - `Download`: Export template file + - `Delete`: Remove template from system + +## Automatic Document Generation + +The Documentation Engine automatically generates compliance documents by combining published templates with real-time system data. This process eliminates manual document creation while ensuring consistency and accuracy across all regulatory deliverables. + + +### Variables and Data Interpolation +The documentation engine supports dynamic content generation using predefined variables. Possible variables are defined in the variable list: you can either copy-paste int the templates or write them manually follwing the specific syntax format `{{CATEGORY.variable_name}}`. +These variables are automatically populated with actual data when generating the documentation in a specific System Version. +**Available Categories:** +- `BUG` +- `CHANGE_REQUEST` +- `CURRENT_USER` +- `GENERAL` +- `REQUIREMENT` +- `RISK` +- `SOFTWARE_ITEM` +- `SYSTEM_VERSION` +- `TEST` +- `TEST_EXECUTION` +- `TEST_SUITE + +### Custom Lists and Tables +For data which are not unique, such as the Requirements of a System Version, custom structure are available to organized the actual data. +In Custom Lists, organize the structure of the appeareance of 1 item and it will be repeated for all the existing entities of that item. +``` +{{#each CATEGORY}} +{{variable_name}} +{{/each}} +``` +For instance, to print the list (as title) of all the requirements for a specific System Version, you need to insert in your template the related loop for requirements: +``` +{{#each REQUIREMENT}} +{{title}} +{{/each}} +``` +**NB** Some categories may have nested data, constited in list of elements related to an element available in the custom lists. Loops inside loops are allowd for those nested data. + +**Image Management:** +To include images in your document: +1. Insert a placeholder in your template where the image should appear +2. Generate and download the report +3. Manually add the downloaded image to the placeholder location + +For instance, Software Item design image can be downloaded from the System Version Dashboard and attached dinamically to the generated .markdown documnet following the previous steps. + + +### Revision Management + +The system automatically maintains revision history for each published template without requiring manual intervention. When a template is published, the revision number increments automatically with each subsequent modification and save operation. + +**Key Features:** +- Automatic version increment on save for published templates +- Complete change history tracking +- Ability to restore previous revisions + +### Error Management + +The editor includes built-in validation that alerts users to syntax errors in variables or loop structures. + + +### Report and Template Generation + +**Template Download:** +Raw templates can be downloaded directly from the template table without data interpolation. + +**Report Generation:** +Once a template is published, it becomes available in the reports list on the overview tab. Published templates can be used to generate reports with interpolated data. + +**Supported Formats:** +Both templates and reports are available in `Markdown` and `Docx` formats. diff --git a/docs/p4samd/handbook/img/documentation_engine_table.png b/docs/p4samd/handbook/img/documentation_engine_table.png new file mode 100644 index 0000000000..9ecc45c796 Binary files /dev/null and b/docs/p4samd/handbook/img/documentation_engine_table.png differ diff --git a/docs/p4samd/handbook/img/download_changelogs.png b/docs/p4samd/handbook/img/download_changelogs.png index 0a9015065e..8ec0ffd211 100644 Binary files a/docs/p4samd/handbook/img/download_changelogs.png and b/docs/p4samd/handbook/img/download_changelogs.png differ diff --git a/docs/p4samd/handbook/img/download_release_note.png b/docs/p4samd/handbook/img/download_release_note.png index a28d839748..a9123ee178 100644 Binary files a/docs/p4samd/handbook/img/download_release_note.png and b/docs/p4samd/handbook/img/download_release_note.png differ diff --git a/docs/p4samd/handbook/img/download_software_architecture_design.png b/docs/p4samd/handbook/img/download_software_architecture_design.png new file mode 100644 index 0000000000..b3e4b9a2a3 Binary files /dev/null and b/docs/p4samd/handbook/img/download_software_architecture_design.png differ diff --git a/docs/p4samd/handbook/img/download_soup_report.png b/docs/p4samd/handbook/img/download_soup_report.png index 9d66492b63..aab940274f 100644 Binary files a/docs/p4samd/handbook/img/download_soup_report.png and b/docs/p4samd/handbook/img/download_soup_report.png differ diff --git a/docs/p4samd/handbook/img/download_unit_test_report.png b/docs/p4samd/handbook/img/download_unit_test_report.png index 0022afca49..9c81eab01b 100644 Binary files a/docs/p4samd/handbook/img/download_unit_test_report.png and b/docs/p4samd/handbook/img/download_unit_test_report.png differ diff --git a/docs/p4samd/handbook/img/download_vulnerability_report.png b/docs/p4samd/handbook/img/download_vulnerability_report.png new file mode 100644 index 0000000000..b89ec273ef Binary files /dev/null and b/docs/p4samd/handbook/img/download_vulnerability_report.png differ diff --git a/docs/p4samd/handbook/img/system_version_overview.png b/docs/p4samd/handbook/img/system_version_overview.png index 92a9c85113..5323abce8d 100644 Binary files a/docs/p4samd/handbook/img/system_version_overview.png and b/docs/p4samd/handbook/img/system_version_overview.png differ diff --git a/docs/p4samd/handbook/reports.md b/docs/p4samd/handbook/reports.md index 29009ab4a0..0849bd7c9e 100644 --- a/docs/p4samd/handbook/reports.md +++ b/docs/p4samd/handbook/reports.md @@ -17,32 +17,22 @@ If ALM information are missing, incorrect or outdated, the generated documentati ::: -## Change report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------| -| PDF | System version | Overview page | - -The **Change report** contains a list of all change requests linked to a system version and can be downloaded from the [Overview page][software-system-overview]. - -![Download change report from Overview page](img/download_change_report.png) - -For each change, the following information are available: - -- **Key**: the identifier with a link to the ALM issue -- **Reporter**: the user who reported the change request -- **Assignee**: the owner of processing the change request. -- **Approval date**: when the change request was approved -- **Due date**: the deadline for the implementation of the change request, if approved -- **Affected version**: the software component affected by the change. -- **Classification**: the classification of the type, scale and impact of the change, actual values depend on the configuration of the corresponding Jira issue type and could include for example `patch`, `minor` or `major`. -- **Priority**: the level of priority (typically a positive number, where a lower value corresponds to a higher priority). -- **Description**: a summary of the change request (current behavior, proposed change, reasons for change, affected components, etc.). -- **Acceptance criteria**: The criteria to verify and validate that the change has been successfully applied. -- **Notes**: Any additional notes about the change. -- **Linked requirements**: the list of requirements related to the the change. -- **Linked risks**: the list of risks that may affect the change. -- **Software Items**: the list of software items affected by the change. +## Default templates + +- [SOUP Report](#soup-report) +- [Changelogs](#changelogs) +- [Unit Test report](#unit-test-report) +- [Vulnerability Report](#vulnerability-report) +- [Software Architecture Design](#software-architecture-design) + +## Startup package of customizable templates +- [Release Note](#release-notes) +- [Acceptance Test Report](#acceptance-test-report) +- [Verbale collaudo](#verbale-di-collaudo) +- [Traceability Matrix](#traceability-matrix) +- [Change Request Report](#change-request-report) +- [Software Architecture Description](#software-architecture-description) +- [Risk Management Report](#risk-management-report) ## Changelogs @@ -82,71 +72,6 @@ You can download it from the [Overview page][software-system-overview]. ![Download release notes from Overview page](img/download_release_note.png) -## Risk report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------| -| PDF | System version | Overview page | - -The **Risk report** contains a detailed list of all risks linked to a system version and can be downloaded from the [Overview page][software-system-overview]. - -![Download risk report from Overview page](img/download_risk_report.png) - -For each risk, the following information are available: - -- **Title**: A brief description of the identified risk and a link to the Jira Issue represented by its Key. -- **Key**: identifier of the risk in the integrated ALM -- **Type**: type of risk -- **Status**: status of the risk -- **Assignee**: owner of assessing the risk -- **Hazardous situation**: The specific scenario in which the risk could occur. -- **Sequence of events**: The conditions leading to the risk. -- **Hazard**: The nature of the risk and its potential consequences. -- **Harm**: The expected negative impact. -- **Severity**: A numerical value representing the potential impact of the risk. -- **Probability**: A numerical value indicating the likelihood of the risk occurring. -- **Risk**: A classification based on probability and severity. [Levels][risks-levels] -- **Description**: A paragraph describing the risk. -- **Software Items**: The number of software items affected by the risk (name, version). -- **Risk Control Measures (RCM)**: A list of risk control measures that mitigate the risk (key, title, link) -- **Mitigated probability**: A number indicating how much the **RCM** mitigates probability. -- **Mitigation severity**: A number indicating how much the **RCM** mitigates severity. -- **Residual Risk**: The remaining level of risk after mitigation measures are applied. [Levels][risks-levels] - -## Software Item History - -| Available formats | Available for | Download from | -|:------------------|:--------------|:--------------------------| -| JSON, PDF | Software Item | Software Item drawer menu | - -The Software Item History report contains a log of the changes performed on a software item, from the most recent to the least, and can be download from the drawer that appears when you select a row in the software items table. - -![Download software item history](img/download_swi_history.png) - -This report is available in two formats: - -- **JSON**: the machine-readable version, including all the available information and suitable for further automated processing; -- **PDF**: the readable version, including the most relevant information for regulatory and compliance purposes. - -For each history item the report includes the following information: - -- the operation performed (e.g. approval, link creation/update/removal, …); -- the user who performed the operation; -- when the operation was performed; -- additional details about the operation performed (e.g. which fields were changed, which entity was linked, …). - -## SBOM report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------------| -| Excel (.xlsx) | System version | Software Items page | - -The SBOM report contains the list of dependencies of all custom services linked to a system version and can be downloaded from the **Software Items** page. - -![Download system version SBOM](img/download_sbom.png) - -For additional information about the Software Bill of Materials (SBOM), please take a look at the [dedicated page][sbom]. - ## SOUP report | Available formats | Available for | Download from | @@ -174,32 +99,6 @@ The spreadsheet contains two tabs: - **License**: the software item license; - **Required Software and Hardware**: software and hardware requirements. -## Test report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------| -| PDF | System version | Overview page | - -The **test report** contains a list of all tests linked to a system version, including their executions, and can be downloaded from the [Overview page][software-system-overview]. - -![Download test report from Overview page](img/download_test_report.png) - -For each test, the following information are available: - -- **Title**: the unique identifier (ID or key) and title of the test; -- **Key**: the identifier of the test in the ALM; -- **Type**: the type of test, like integration or system; -- **Status**: the status of the test, based on the outcome of the last execution; -- **Assignee**: the owner of the test; -- **Execution Mode**: how the test is executed (typically automatic or manual); -- **Description**: a detailed description of the test, including the scope and procedure; -- **Requirements**: the list of requirements covered by the test, with key, title and link to the ALM issue; -- **Software Items**: the list of software items associated to the test, with name and version; -- **Test executions**: the list of test execution, from most to least recent: - - **Execution date**: when the test was executed; - - **Tester**: who executed the test; - - **Outcome**: if the test passed or failed. - ## Unit Test report | Available formats | Available for | Download from | @@ -226,10 +125,285 @@ For each test case in the test suite the following information are provided: - **Class**: description of the test case; - **Time**: how much time the test case required to finish. +## Vulnerability Report + +| Available formats | Available for | Download from | +|:------------------|:---------------|:--------------| +| Excel (.xlsx) | System version | Overview page | + +The **Vulnerability Report** contain the list of all vulnerabilities for wach software item for specific system version. +You can download it from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Summary**: The summary of software items and their Open, Exploitable, Unexploitable Exploitable With Minor Damage +- **System Vulnerabilities**: The information of all the available vulnerabilities in the specific system version, including: + - **Vulnerability ID**: unique identifier of the vulnerability (e.g. CVE-2025-27152); + - **Name**: name of the vulnerable package; + - **Repository ID**: identifier of the repository; + - **Package ID**: identifier of the package; + - **Title**: title of the vulnerability; + - **Description**: detailed description of the vulnerability; + - **Software Item**: name of the software item; + - **Software Item Version**: version of the software item; + - **Installed Version**: installed version of the package; + - **Fixed Version**: version where the vulnerability is fixed; + - **Severity**: severity level (e.g. HIGH); + - **Severity Source**: source of the severity rating; + - **Severity Score**: severity score; + - **CVSS**: CVSS score; + - **Published Date**: date when the vulnerability was published; + - **Status**: current status (e.g. OPEN); + - **Resolution**: resolution status; + - **Justification**: justification for the status; + - **Rationale**: rationale for the decision; + - **Vendor Severity**: severity assigned by the vendor; + - **Package status**: status of the package; + - **PrimaryURL**: link to the vulnerability details; + - **Approver**: who approved the vulnerability; + - **Risks**: linked risks; + - **RCM**: linked risk control measures; + - **Last Updated Date**: date of the last update. +- **Info**: The information of the system-version and the user + +## Software Architecture Design + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| svg | System version | Overview page | + +The high level architecture image of software items for the specific system version. + +## Template Release notes + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Release notes** contain the list of all requirements and the hierarchy of software items (name and version) linked to the system version. +You can download it from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **New Features**: list of requirements linked to the release, including: + - **Requirement**: key, title, and link; + - **Tasks**: list of tasks linked to the requirement (issue type, key, title, link); + - **Bugs**: list of bugs linked to the requirement (key, title, link); +- **Bugfix**: list of bugs fixed in the release (key, title, link); +- **Breaking Changes**: list of possible breaking changes; +- **Software System**: list of software items composing the system (name, version, repository link); +- **Document generation info**: user who generated the document and timestamp. + +## Acceptance Test Report + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Acceptance Test Report** contains the outcome of the acceptance testing activities and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Reference Template**: name and revision of the template used; +- **Project Name**: name of the project; +- **Requesting Company**: + - **Requester**: name of the requester; + - **Offer Code**: code of the offer; + - **Customer Company**: extended name of the customer company; + - **Customer Requester**: name of the customer requester; +- **Date**: date of the document; +- **Location**: location (e.g. Milano); +- **Client**: client company name; +- **Mia-Care Project Manager**: Product Owner name; +- **Project Contact Person for the Client**: client contact person; +- **System Description**: introduction and list of requirements; +- **Reference Documents**: Project Offer reference document name; +- **Final Release**: + - **Acceptance Test Subject**: subject of the acceptance test; + - **Outcome**: result of the test (e.g. POSITIVE); + - **Subsequent Activities**: agreement details for AMS service; +- **Signatures**: Mia-Care Project Manager and Client Manager; +- **Document generation info**: user who generated the document and timestamp. + +## Verbale di Collaudo + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Verbale di Collaudo** contains the outcome of the acceptance testing activities and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information and the template is in italian: + +- **Template di riferimento**: name and revision of the template used; +- **Nome Progetto**: name of the project; +- **Società richiedente**: + - **Richiedente**: name of the requester; + - **Codice Offerta**: code of the offer; + - **Società richiedente estesa**: extended name of the customer company; + - **Referente cliente**: name of the customer requester; +- **Data**: date of the document; +- **Luogo**: location (e.g. Milano); +- **Committente**: client company name; +- **Responsabile Progetto Mia Care**: Product Owner name; +- **Referente di progetto per il committente**: client contact person; +- **Descrizione sistema**: introduction and list of requirements; +- **Documenti di riferimento**: Project Offer reference document name; +- **Rilascio finale**: + - **Oggetto collaudo**: subject of the acceptance test; + - **Esito**: result of the test (e.g. POSITIVE); + - **Attività successive**: agreement details for AMS service; +- **Firme**: Mia-Care Project Manager and Client Manager; +- **Document generation info**: user who generated the document and timestamp. + +## Traceability Matrix + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Traceability Matrix** contains the traceability information between requirements, tests, risks, software items and change requests and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Document version**: version of the document; +- **Scope**: scope of the document; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **Matrix**: table with the following columns for each requirement: + - **Requirement key**: key of the requirement; + - **Verified by (Test)**: list of tests verifying the requirement (key); + - **Mitigates (Risk)**: list of risks mitigated by the requirement (key, title); + - **Implemented in (Software Item)**: list of software items implementing the requirement (name, version); + - **Affected by (Change Request)**: list of change requests affecting the requirement (key, title); +- **Document generation info**: user who generated the document and timestamp. + + +## Change Request Report + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Change Request Report** contains the list of change requests linked to the system version and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Scope**: scope of the document; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **Summary of Change Requests**: list of change requests (key, title); +- **Change Requests**: detailed list of change requests, including: + - **Key** and **Title**; + - **Classification**: classification of the change request; + - **Description**: detailed description; + - **Acceptance criteria**: criteria for acceptance; + - **Affected Version**: version affected by the change; + - **Approval Date**: date of approval; + - **Assignee**: person assigned to the change request; + - **Status**: current status; + - **Linked Requirements**: list of linked requirements (key, title); + - **Notes**: additional notes; +- **Conclusion**: conclusion on change requests implemented in the software system version; +- **Document generation info**: user who generated the document and timestamp. + +## Software Architecture Description + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Software Architecture Description** contains the description of the software architecture and design and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Document version**: version of the document; +- **Scope**: scope of the document; +- **Product Information**: + - **Product Name**: name of the product; + - **Product Version**: version of the software system; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; +- **Reference Documentation**: scope of the document; +- **Software Architecture Overview**: + - **Schema**: software architecture image; + - **Components**: list of software items (name, version, parent, parent type, safety class, SOUP); +- **Software Design**: description of software design (e.g. authentication, design patterns); +- **Development Tools**: list of tools used for development; +- **Development Environment**: description of development environments; +- **Software Deployment**: description of the deployment process; +- **Main Technical Decision Justifications**: rationale for main technical decisions; +- **Document generation info**: user who generated the document and timestamp. + +## Risk Management Report + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Risk Management Report** contains the risk analysis and management information and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Document version**: version of the document; +- **Scope**: scope of the document; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **Summary of Risks**: list of risks (key, title); +- **Risk Analysis**: detailed analysis for each risk: + - **Key**, **Status**, **Title**; + - **Assignee**: person assigned to the risk; + - **Hazard**: description of the hazard; + - **Sequence Of Events**: sequence of events leading to the hazardous situation; + - **Hazardous Situation**: description of the hazardous situation; + - **Harm**: description of the harm; + - **Risk Assessment**: table with Probability, Probability Notes, Severity, Risk (P*S), Probability after RCM, Severity after RCM, Residual Risk; + - **Linked Software Items**: number of linked software items; + - **Linked Risk Control Measures**: list of linked requirements (key, title); +- **Verification of Risk Control Measures**: comments on verification; +- **Conclusion**: conclusion on overall residual risk and benefit-risk analysis; +- **Document generation info**: user who generated the document and timestamp. + + [software-system-overview]: system_overview.md [changes]: changes.md [risks]: risks.md [risks-levels]: risks.md#levels [sbom]: sbom.md -[tests]: verification.md \ No newline at end of file +[tests]: verification.md diff --git a/docs/p4samd/handbook/requirements.md b/docs/p4samd/handbook/requirements.md index c1e4a28326..c5802a6f08 100644 --- a/docs/p4samd/handbook/requirements.md +++ b/docs/p4samd/handbook/requirements.md @@ -25,7 +25,7 @@ Furthermore, the user is assisted evaluating the design inputs of the project th - **Status**: the status of the requirement (opened, closed, etc.) - **Software Items**: the number of software items affected by the requirement. - **Risks**: the number of risks mitigated by the requirement. -- **Tests (test coverage)**: the number of tests verifying the requirement. +- **Tests (test coverage)**: the number of tests verifying the requirement and the coverage of the requirement, evaluated by AI. - **Changes**: the number of changes applied to the requirement. The table presents an overview of the traceability, through the count of linked entities such as software items, tests, risks and changes. @@ -92,6 +92,7 @@ Also remember that information generated by AI may be inaccurate or misleading, ::: +### Requirement Quality You can assess the conformity of a SaMD requirement by hovering on the icon under the **Quality** column in the corresponding table row and click on the `Get evaluation` button. The assessment may take a while, usually around a minute, so while we process it in the background you can keep working on P4SaMD and come back to check the progress at any time. @@ -118,5 +119,8 @@ At the top you can see a **suggested description**, which provides an example of Also, you can check how it scored on each specific criteria mentioned above, including the specific areas of strength and weakness. +### Estimated Test Coverage + +The assessment on the requirement quality provides also an AI evaluation of the test coverage: all the **linked tests** are condidered for the estimantion, and the percentage result is shown in the **Tests (test coverage)** column. Additional information and insights about the score are reported in the Requirement Deatil (drawer), inside the Traceability tab. The system suggests also test cases based on the assessed requirement, to increase the coverage and improve the overall testbook completeness. [faq-data-sharing]: ../faq.md#does-mia-care-p4samd-share-data-with-third-party-organizations diff --git a/docs/p4samd/handbook/system_overview.md b/docs/p4samd/handbook/system_overview.md index e894063145..7a245a0f09 100644 --- a/docs/p4samd/handbook/system_overview.md +++ b/docs/p4samd/handbook/system_overview.md @@ -25,15 +25,27 @@ Below the global progress bar, users will find a series of **detailed progress b These KPIs provide actionable insights, enabling teams to measure progress and focus on areas requiring immediate attention. ## Reports -Directly beneath the overall progress bar, a **select dropdown menu** enables users to generate and download reports tailored to the selected system version. The following reports are available: +Directly beneath the overall progress bar, a **select dropdown menu** enables users to generate and download reports tailored to the selected system version. +There will be some default reports that are taged as + + The following reports are available as set of `Default` templates: - **Release Note**: Summarizes the key updates, features, and resolved issues in the system version. -- **Risk Report**: Provides a detailed analysis of identified risks, their risk control measures and current statuses. -- **Test Report**: Lists all tests performed, their results, and any associated observations or issues. -- **Change Report**: Documents all approved and implemented change requests. - **SOUP Report**: Details the use of all Software of Unknown Provenance (SOUP). - **Changelogs**: A folder containing the changelogs of each custom software components. - **Unit Tests**: Presents the outcomes and coverage of unit tests performed on custom software components. - **Vulnerability Report**: Provides a summary and details of detected vulnerabilities for the specific system version. +- **Software architecture Design**: Provides the software items high level design as an image. + +The following reports are provided as startup package of customizable templates: +- **Release Note**: Summarizes the key updates, features, and resolved issues in the system version. +- **Acceptance Test Report**: Documents the results of acceptance testing to verify that the system meets specified requirements. +- **Verbale collaudo**: Provides the official test acceptance record (Italian compliance document). +- **Traceability Matrix**: Maps relationships between requirements, design elements, tests, and other artifacts to ensure full traceability. +- **Change Report**: Details all changes made to the system version, including modifications, additions, and deletions. +- **Software Architectural Design Description**: Describes the high-level software architecture, including components, interfaces. +- **Risk Management Report**: Provides a comprehensive overview of identified risks, their assessments, and mitigation strategies. +### Custom Reports +You can create additional custom reports by designing templates using the documentation engine. Once published, these templates will become accessible in the dropdown menu and can be downloaded for any system version. please take a look at the [Documentation Engin](document-engine.md) These reports ensure compliance, traceability, and readiness for audits or external reviews. diff --git a/docs/p4samd/handbook/verification.md b/docs/p4samd/handbook/verification.md index f47b0b9047..e7d7e98a58 100644 --- a/docs/p4samd/handbook/verification.md +++ b/docs/p4samd/handbook/verification.md @@ -14,11 +14,11 @@ Manual testing remains relevant, especially for usability and exploratory testin P4SaMD provides a comprehensive overview of all the tests planned for a version of the software system, organized in three main tabs: -- **All tests**: Displays the list of individual tests which are applicable for the current Software Version. The list includes all the tests associated to the current system version and the previous ones, as long as they are not deprecated. -- **Test suites**: Shows the available test suites and allows navigation into suite details. The Test Suites are collectors of tests, to facilitate the test grouping and their execution. +- **All tests**: Displays the list of individual tests which are applicable for the current Software Version. The list includes all the tests associated to the current and other system versions, as long as they are not deprecated. +- **Test suites**: Shows the available Test Suites and allows navigation into suite details. The Test Suites are collectors of tests, to facilitate the test grouping and their execution. - **Executions**: Lists all test executions with access to execution details and reports. The executions can refer to a single or multiple tests, achieved by the execution of Test Suites. -The tests originate from the integrated ALM, where they can be created, updated, and deleted. The table dynamically reflects any changes made inside the ALM. +The nominal definition of tests originates from the integrated ALM, where you can create new ones, update the information, and delete them. The P4SaMD table dynamically reflects any changes made inside the ALM. Users are assisted in evaluating the quality and compliance of the tests thanks to AI-powered evaluation features. ## All tests @@ -30,7 +30,7 @@ For each test the following information are provided: - **Quality**: the latest evaluation performed using AI, see a legend of the different icons below. - **Type**: the type of test, like integration or system; - **Execution Mode**: if the test is executed automatically or manually; -- **Test Suite**: if the test is part of an [automated test suite](#test-suites); +- **Test Suite**: if the test is part of an [automated Test Suite](#test-suites); - **Latest Execution**: details about the last text execution, including when it was performed and the outcome. The outcome can refer to the overall test (e.g. passed or failed for manual tests) or to the underneath test cases of the test (e.g. count of successful, failed or skipped test cases); - **Software Items**: the number of software items associated to the test; - **Requirements**: the number of requirements verified by the test. @@ -128,34 +128,83 @@ Also, you can check how it scored on each specific criteria mentioned above, inc ## Test Suites -In this tab, you can manage the tests though Test Suites: create, update and also delete them. The displayed Test Suites are referring to the current system version and allow to group multiple tests of the same type. In fact, Test Suites can be _automatic_ or _manual_, and the related tests must be coherent to the defined type. +In this tab, you can manage the tests through Test Suites: create, update and also delete them. The displayed Test Suites are referring to the current system version and allow to group multiple tests of the same type. In fact, Test Suites can be _automatic_ or _manual_, and the related tests must be coherent to the defined type. -For each test suite, the following information is shown: +For each Test Suite, the following information is displayed: -- **Title**: Name of the test suite. +- **Title**: Name of the Test Suite. - **Execution Mode**: Automatic or manual, strictly tied to the Execution Mode of the associated tests. - **Tests**: Number of tests included in the suite. - **Last Execution**: Status and date of the last execution. -### Actions +### Managing Test Suites -- **Add suite**: Create a new test suite. -- **Run all**: Initiate execution of all automated test suites that have an API Trigger configured. -- **View Details**: Click on a row to access the details of the selected test suite. -- **Run Test Suite**: Execute an automated test suite when its API Trigger is configured. You can also _select_ more than one Test Suite and execute multiple test suites in a single action. -- **Delete Test Suite**: Delete a specific test suite, without deleting the associated tests. -- **Edit Test Suite**: Allows users modify a specific test suite, such as the title. +#### Creating Test Suites -### Detail +- **Add suite**: Create a new Test Suite. NB. Test suites can be created for software versions that are not yet released. Each Test Suite can contain one or more tests. + +#### Running Test Suites + +- **Run all**: Initiate execution of all automated Test Suites that are configured with an External Test Executor. +- **Run Test Suite**: Execute a specific automated Test Suite when its API Trigger is configured. Multiple Test Suites can be selected and executed simultaneously. +- **Manual executions**: Must be handled in the ALM tool, where testers initiate and update execution information. + +#### Other Actions + +- **View Details**: Click on a row to access detailed information about the selected Test Suite. +- **Edit Test Suite**: Modify Test Suite properties such as the title. +- **Delete Test Suite**: Remove a specific Test Suite without deleting the associated tests. + +### Test Suite Details + +Clicking on a row displays the Test Suite details in three tabs: + +#### Tests Tab +Shows all tests included in the Test Suite with their individual properties and status. + +#### Executions Tab +Displays chronological executions of the specific Test Suite, with options to download corresponding reports when available. + +#### External Test Executor Tab +Configure the external service required for automatic test suite execution. -Clicking on a row open a new page where there's the details of the test suite. Here we have three tabs: -- **Tests**: Show all the tests related to the test suite. -- **Executions**: Displays all executions that include the test suite, with the option to download the corresponding report if available. -- **Api Trigger**: This section allow to create or edit the **Api Trigger** needed to automatically execute test suite. +**Configuration Requirements:** +- P4SaMD requires a `jobId` to trigger the executor correctly +- Include the `{{@jobId}}` placeholder in at least one of: **Endpoint URL**, **Payload**, or **Header** +- Without proper `jobId` configuration, the executor cannot run -### Test Suite Execution Flow +### Automatic Test Suite Execution -When you run a test suite, P4SaMD triggers the configured external test executor via API. The executor sends back results through a webhook to update the execution status. If the report is provided in JUnit format, P4SaMD automatically processes and displays the results in the dashboard. Otherwise, only the execution status is recorded, and the report file remains available for download. +#### Execution Flow + +1. **Initialization**: User triggers execution → new job created with assigned `JobId` +2. **Running**: `jobId` inserted into configured location → External Test Executor runs → job updates based on response +3. **Results**: External executor sends updates via webhook → execution status is updated → results are processed +4. **Reports**: JUnit format reports are automatically processed and displayed; other received formats are saved and are downloadable + +#### Configuration Prerequisites + +- External test executor must be configured +- `{{@jobId}}` placeholder must be set in test suite details +- Without proper configuration, P4SaMD cannot trigger or run test suites + +#### Webhook Integration + +External Test Executors update job status via webhook: + +``` +https://{{domain}}p4samd/webhook/update-run-test-suite/:jobId +``` + +**Supported Parameters:** + +| Name | Type | Description | +|------------|--------|------------------------------------------- | +| outcome | string | Updates the status of the job execution | +| result | string | Final test results (if report not in JUnit format) | +| message | string | Execution description | +| junitXml | string | JUnit format report (automatically processed) | +| reportFile | file | Report file (downloadable, not auto-processed) | ## Executions @@ -165,8 +214,8 @@ For each execution, the following pieces of information are available: - **Date and time**: When the execution was performed. - **Note**: Show an icon if there are some notes. -- **Test suites**: Number of test suites involved in the execution. -- **Outcome**: Result of the execution of all test suites included in that execution (passed, failed, etc.). +- **Test suites**: Number of Test Suites involved in the execution. +- **Outcome**: Result of the execution of all Test Suites included in that execution (passed, failed, etc.). - **Executed by**: User who performed the execution. - **Download report**: Download a ZIP archive containing a summary of the execution and all available individual reports from that execution. @@ -176,15 +225,12 @@ Each execution provides a downloadable ZIP archive containing: - **README.md**: A summary file with execution details, including: - Execution date and executor name - - Overview of all test suites included in the execution - - Final result for each test suite (passed, failed, etc.) - - Reference to corresponding report files when available -- **Individual Reports**: All available test suite reports from that execution - - -Clicking on a row opens the execution detail view, showing all relevant information about the selected execution. + - Overview of all Test Suites included in the execution + - Final result for each Test Suite (passed, failed, etc.) + - References to corresponding report files when available +- **Individual Reports**: All available Test Suite reports from that execution ### Detail Clicking on a row opens a new page showing the execution details. -Here you will find details including the execution date, the user who performed the execution, and any associated notes. The view also lists all test suites involved in the execution along with their related tests. You can download a comprehensive report for the test suite execution, which includes a summary file and all available individual test suite reports as attachments. +Here you will find details including the execution date, the user who performed the execution, and any associated notes. The view also lists all Test Suites involved in the execution along with their related tests. You can download a comprehensive report for the Test Suite execution, which includes a summary file and all available individual Test Suite reports as attachments. diff --git a/docs/p4samd/security/roles_permissions.md b/docs/p4samd/security/roles_permissions.md index 89a9f9de7d..71f95afdaf 100644 --- a/docs/p4samd/security/roles_permissions.md +++ b/docs/p4samd/security/roles_permissions.md @@ -39,6 +39,13 @@ All permissions starting with `console` are inherited from the Console, while th | [Evaluate test with AI](#evaluate-test-with-ai) | `p4samd.test.ai.evaluate` | | [Run test suite](#run-test-suite) | `p4samd.test.suite.run` | | [Delete test suite](#delete-test-suite) | `p4samd.test.suite.delete` | +| [Update Console project configuration](#update-console-project-configuration) | `console.company.project.configuration.update` | +| [Create document](#create-document) | `p4samd.documents.create` | +| [Delete document](#delete-document) | `p4samd.documents.delete` | +| [Download document preview](#download-document-preview) | `p4samd.documents.download.preview` | +| [Publish document](#publish-document) | `p4samd.documents.publish` | +| [Update document](#update-document) | `p4samd.documents.update` | +| [Download documentation](#download-documentation) | `p4samd.documentation.download` | This table provides the default list of the P4SaMD permissions granted to each Console role. Please contact directly Mia-Care for more info or customization. @@ -63,6 +70,12 @@ This table provides the default list of the P4SaMD permissions granted to each C | `p4samd.test.ai.evaluate` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | `p4samd.test.suite.run` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | `p4samd.test.suite.delete` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.create` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.delete` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.download.preview` | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| `p4samd.documents.publish` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.update` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documentation.download` | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ## Security policies @@ -212,6 +225,27 @@ A user must have the Console `console.company.project.configuration.update` perm Without this permission, the user is not displayed the button on the [Software Items table][software-items-table] redirecting to the *Design > Microservices* section of the Console project. +### Create document + +A user must have the `p4samd.documents.create` permission to create a new template. + +### Delete document + +A user must have the `p4samd.documents.delete` permission to delete an existing template. + +### Download document preview + +A user must have the `p4samd.documents.download.preview` permission to download a preview of a template. + +### Publish document + +A user must have the `p4samd.documents.publish` permission to change the state of a template. + +### Update document + +A user must have the `p4samd.documents.update` permission to update an existing document. + + This permission is inherited from the [Console roles and permissions][console-roles-permissions]. diff --git a/sidebars.json b/sidebars.json index 31307eecb6..a022a9ff38 100644 --- a/sidebars.json +++ b/sidebars.json @@ -74,6 +74,11 @@ "id": "p4samd/handbook/references", "label": "References", "type": "doc" + }, + { + "id": "p4samd/handbook/document_engine", + "label": "Documentation Engine", + "type": "doc" } ] }, diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/document-engine.md b/versioned_docs/version-2.3.x/p4samd/handbook/document-engine.md new file mode 100644 index 0000000000..d212a1d67c --- /dev/null +++ b/versioned_docs/version-2.3.x/p4samd/handbook/document-engine.md @@ -0,0 +1,110 @@ +--- +id: document_engine +title: Documentation Engine +sidebar_label: Documentation Engine +--- + +# Documentation engine + +## Overview +This module offers a centralized Documentation Engine to streamline compliance by automating the generation of regulated artifacts. +A default set of IEC 62304-compliant templates is provided to allow users a quick startup: templates can be extensively customized thanks to our editor (.markdown, .docx) and enriched by system data through provided variables and custom structure. +The documentation shaped from the templates can be generated and downloaded in the preferred format for every version of your Software System. + +![Documentation Engine Table](./img/documentation_engine_table.png) + +## Features + +### Template Management + +P4SaMD provides a default set of templates to help you start with a IEC 62304-compliant framework. +For enabled users, it is always possible customize and manage templates: +- **Creating** new templates to extend the default template set +- **Editing** a template, to align the structure to your company QMS and the deliverables required for your product. +- **Publishing** a template to make it visible in the System Version Dashboard and ready for the documentation download +- **Deleting** the templates when no more needed (the records would be archived in P4SaMD database, but not available to users) + +For each template the following informations are available: + +- **Title**: Changeable title for the template +- **Revision**: Automatic version tracking for the published templates. +- **Last Edit Date/Time**: Timestamp of the most recent modification +- **Editor**: User who performed the last edit +- **Status**: Template state indicator + - `Draft`: Template in progress + - `Published`: Template available for use +- **Actions**: Available actions per template row (based on user permissions): + - `Edit/View`: Modify or view template content + - `Download`: Export template file + - `Delete`: Remove template from system + +## Automatic Document Generation + +The Documentation Engine automatically generates compliance documents by combining published templates with real-time system data. This process eliminates manual document creation while ensuring consistency and accuracy across all regulatory deliverables. + + +### Variables and Data Interpolation +The documentation engine supports dynamic content generation using predefined variables. Possible variables are defined in the variable list: you can either copy-paste int the templates or write them manually follwing the specific syntax format `{{CATEGORY.variable_name}}`. +These variables are automatically populated with actual data when generating the documentation in a specific System Version. +**Available Categories:** +- `BUG` +- `CHANGE_REQUEST` +- `CURRENT_USER` +- `GENERAL` +- `REQUIREMENT` +- `RISK` +- `SOFTWARE_ITEM` +- `SYSTEM_VERSION` +- `TEST` +- `TEST_EXECUTION` +- `TEST_SUITE + +### Custom Lists and Tables +For data which are not unique, such as the Requirements of a System Version, custom structure are available to organized the actual data. +In Custom Lists, organize the structure of the appeareance of 1 item and it will be repeated for all the existing entities of that item. +``` +{{#each CATEGORY}} +{{variable_name}} +{{/each}} +``` +For instance, to print the list (as title) of all the requirements for a specific System Version, you need to insert in your template the related loop for requirements: +``` +{{#each REQUIREMENT}} +{{title}} +{{/each}} +``` +**NB** Some categories may have nested data, constited in list of elements related to an element available in the custom lists. Loops inside loops are allowd for those nested data. + +**Image Management:** +To include images in your document: +1. Insert a placeholder in your template where the image should appear +2. Generate and download the report +3. Manually add the downloaded image to the placeholder location + +For instance, Software Item design image can be downloaded from the System Version Dashboard and attached dinamically to the generated .markdown documnet following the previous steps. + + +### Revision Management + +The system automatically maintains revision history for each published template without requiring manual intervention. When a template is published, the revision number increments automatically with each subsequent modification and save operation. + +**Key Features:** +- Automatic version increment on save for published templates +- Complete change history tracking +- Ability to restore previous revisions + +### Error Management + +The editor includes built-in validation that alerts users to syntax errors in variables or loop structures. + + +### Report and Template Generation + +**Template Download:** +Raw templates can be downloaded directly from the template table without data interpolation. + +**Report Generation:** +Once a template is published, it becomes available in the reports list on the overview tab. Published templates can be used to generate reports with interpolated data. + +**Supported Formats:** +Both templates and reports are available in `Markdown` and `Docx` formats. diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/documentation_engine_table.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/documentation_engine_table.png new file mode 100644 index 0000000000..16e7c09fe9 Binary files /dev/null and b/versioned_docs/version-2.3.x/p4samd/handbook/img/documentation_engine_table.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_changelogs.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_changelogs.png index 0a9015065e..8ec0ffd211 100644 Binary files a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_changelogs.png and b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_changelogs.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_release_note.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_release_note.png index a28d839748..a9123ee178 100644 Binary files a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_release_note.png and b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_release_note.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_software_architecture_design.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_software_architecture_design.png new file mode 100644 index 0000000000..b3e4b9a2a3 Binary files /dev/null and b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_software_architecture_design.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_soup_report.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_soup_report.png index 9d66492b63..aab940274f 100644 Binary files a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_soup_report.png and b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_soup_report.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_unit_test_report.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_unit_test_report.png index 0022afca49..9c81eab01b 100644 Binary files a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_unit_test_report.png and b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_unit_test_report.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/download_vulnerability_report.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_vulnerability_report.png new file mode 100644 index 0000000000..b89ec273ef Binary files /dev/null and b/versioned_docs/version-2.3.x/p4samd/handbook/img/download_vulnerability_report.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/img/system_version_overview.png b/versioned_docs/version-2.3.x/p4samd/handbook/img/system_version_overview.png index 92a9c85113..5323abce8d 100644 Binary files a/versioned_docs/version-2.3.x/p4samd/handbook/img/system_version_overview.png and b/versioned_docs/version-2.3.x/p4samd/handbook/img/system_version_overview.png differ diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/reports.md b/versioned_docs/version-2.3.x/p4samd/handbook/reports.md index 29009ab4a0..0849bd7c9e 100644 --- a/versioned_docs/version-2.3.x/p4samd/handbook/reports.md +++ b/versioned_docs/version-2.3.x/p4samd/handbook/reports.md @@ -17,32 +17,22 @@ If ALM information are missing, incorrect or outdated, the generated documentati ::: -## Change report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------| -| PDF | System version | Overview page | - -The **Change report** contains a list of all change requests linked to a system version and can be downloaded from the [Overview page][software-system-overview]. - -![Download change report from Overview page](img/download_change_report.png) - -For each change, the following information are available: - -- **Key**: the identifier with a link to the ALM issue -- **Reporter**: the user who reported the change request -- **Assignee**: the owner of processing the change request. -- **Approval date**: when the change request was approved -- **Due date**: the deadline for the implementation of the change request, if approved -- **Affected version**: the software component affected by the change. -- **Classification**: the classification of the type, scale and impact of the change, actual values depend on the configuration of the corresponding Jira issue type and could include for example `patch`, `minor` or `major`. -- **Priority**: the level of priority (typically a positive number, where a lower value corresponds to a higher priority). -- **Description**: a summary of the change request (current behavior, proposed change, reasons for change, affected components, etc.). -- **Acceptance criteria**: The criteria to verify and validate that the change has been successfully applied. -- **Notes**: Any additional notes about the change. -- **Linked requirements**: the list of requirements related to the the change. -- **Linked risks**: the list of risks that may affect the change. -- **Software Items**: the list of software items affected by the change. +## Default templates + +- [SOUP Report](#soup-report) +- [Changelogs](#changelogs) +- [Unit Test report](#unit-test-report) +- [Vulnerability Report](#vulnerability-report) +- [Software Architecture Design](#software-architecture-design) + +## Startup package of customizable templates +- [Release Note](#release-notes) +- [Acceptance Test Report](#acceptance-test-report) +- [Verbale collaudo](#verbale-di-collaudo) +- [Traceability Matrix](#traceability-matrix) +- [Change Request Report](#change-request-report) +- [Software Architecture Description](#software-architecture-description) +- [Risk Management Report](#risk-management-report) ## Changelogs @@ -82,71 +72,6 @@ You can download it from the [Overview page][software-system-overview]. ![Download release notes from Overview page](img/download_release_note.png) -## Risk report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------| -| PDF | System version | Overview page | - -The **Risk report** contains a detailed list of all risks linked to a system version and can be downloaded from the [Overview page][software-system-overview]. - -![Download risk report from Overview page](img/download_risk_report.png) - -For each risk, the following information are available: - -- **Title**: A brief description of the identified risk and a link to the Jira Issue represented by its Key. -- **Key**: identifier of the risk in the integrated ALM -- **Type**: type of risk -- **Status**: status of the risk -- **Assignee**: owner of assessing the risk -- **Hazardous situation**: The specific scenario in which the risk could occur. -- **Sequence of events**: The conditions leading to the risk. -- **Hazard**: The nature of the risk and its potential consequences. -- **Harm**: The expected negative impact. -- **Severity**: A numerical value representing the potential impact of the risk. -- **Probability**: A numerical value indicating the likelihood of the risk occurring. -- **Risk**: A classification based on probability and severity. [Levels][risks-levels] -- **Description**: A paragraph describing the risk. -- **Software Items**: The number of software items affected by the risk (name, version). -- **Risk Control Measures (RCM)**: A list of risk control measures that mitigate the risk (key, title, link) -- **Mitigated probability**: A number indicating how much the **RCM** mitigates probability. -- **Mitigation severity**: A number indicating how much the **RCM** mitigates severity. -- **Residual Risk**: The remaining level of risk after mitigation measures are applied. [Levels][risks-levels] - -## Software Item History - -| Available formats | Available for | Download from | -|:------------------|:--------------|:--------------------------| -| JSON, PDF | Software Item | Software Item drawer menu | - -The Software Item History report contains a log of the changes performed on a software item, from the most recent to the least, and can be download from the drawer that appears when you select a row in the software items table. - -![Download software item history](img/download_swi_history.png) - -This report is available in two formats: - -- **JSON**: the machine-readable version, including all the available information and suitable for further automated processing; -- **PDF**: the readable version, including the most relevant information for regulatory and compliance purposes. - -For each history item the report includes the following information: - -- the operation performed (e.g. approval, link creation/update/removal, …); -- the user who performed the operation; -- when the operation was performed; -- additional details about the operation performed (e.g. which fields were changed, which entity was linked, …). - -## SBOM report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------------| -| Excel (.xlsx) | System version | Software Items page | - -The SBOM report contains the list of dependencies of all custom services linked to a system version and can be downloaded from the **Software Items** page. - -![Download system version SBOM](img/download_sbom.png) - -For additional information about the Software Bill of Materials (SBOM), please take a look at the [dedicated page][sbom]. - ## SOUP report | Available formats | Available for | Download from | @@ -174,32 +99,6 @@ The spreadsheet contains two tabs: - **License**: the software item license; - **Required Software and Hardware**: software and hardware requirements. -## Test report - -| Available formats | Available for | Download from | -|:------------------|:---------------|:--------------| -| PDF | System version | Overview page | - -The **test report** contains a list of all tests linked to a system version, including their executions, and can be downloaded from the [Overview page][software-system-overview]. - -![Download test report from Overview page](img/download_test_report.png) - -For each test, the following information are available: - -- **Title**: the unique identifier (ID or key) and title of the test; -- **Key**: the identifier of the test in the ALM; -- **Type**: the type of test, like integration or system; -- **Status**: the status of the test, based on the outcome of the last execution; -- **Assignee**: the owner of the test; -- **Execution Mode**: how the test is executed (typically automatic or manual); -- **Description**: a detailed description of the test, including the scope and procedure; -- **Requirements**: the list of requirements covered by the test, with key, title and link to the ALM issue; -- **Software Items**: the list of software items associated to the test, with name and version; -- **Test executions**: the list of test execution, from most to least recent: - - **Execution date**: when the test was executed; - - **Tester**: who executed the test; - - **Outcome**: if the test passed or failed. - ## Unit Test report | Available formats | Available for | Download from | @@ -226,10 +125,285 @@ For each test case in the test suite the following information are provided: - **Class**: description of the test case; - **Time**: how much time the test case required to finish. +## Vulnerability Report + +| Available formats | Available for | Download from | +|:------------------|:---------------|:--------------| +| Excel (.xlsx) | System version | Overview page | + +The **Vulnerability Report** contain the list of all vulnerabilities for wach software item for specific system version. +You can download it from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Summary**: The summary of software items and their Open, Exploitable, Unexploitable Exploitable With Minor Damage +- **System Vulnerabilities**: The information of all the available vulnerabilities in the specific system version, including: + - **Vulnerability ID**: unique identifier of the vulnerability (e.g. CVE-2025-27152); + - **Name**: name of the vulnerable package; + - **Repository ID**: identifier of the repository; + - **Package ID**: identifier of the package; + - **Title**: title of the vulnerability; + - **Description**: detailed description of the vulnerability; + - **Software Item**: name of the software item; + - **Software Item Version**: version of the software item; + - **Installed Version**: installed version of the package; + - **Fixed Version**: version where the vulnerability is fixed; + - **Severity**: severity level (e.g. HIGH); + - **Severity Source**: source of the severity rating; + - **Severity Score**: severity score; + - **CVSS**: CVSS score; + - **Published Date**: date when the vulnerability was published; + - **Status**: current status (e.g. OPEN); + - **Resolution**: resolution status; + - **Justification**: justification for the status; + - **Rationale**: rationale for the decision; + - **Vendor Severity**: severity assigned by the vendor; + - **Package status**: status of the package; + - **PrimaryURL**: link to the vulnerability details; + - **Approver**: who approved the vulnerability; + - **Risks**: linked risks; + - **RCM**: linked risk control measures; + - **Last Updated Date**: date of the last update. +- **Info**: The information of the system-version and the user + +## Software Architecture Design + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| svg | System version | Overview page | + +The high level architecture image of software items for the specific system version. + +## Template Release notes + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Release notes** contain the list of all requirements and the hierarchy of software items (name and version) linked to the system version. +You can download it from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **New Features**: list of requirements linked to the release, including: + - **Requirement**: key, title, and link; + - **Tasks**: list of tasks linked to the requirement (issue type, key, title, link); + - **Bugs**: list of bugs linked to the requirement (key, title, link); +- **Bugfix**: list of bugs fixed in the release (key, title, link); +- **Breaking Changes**: list of possible breaking changes; +- **Software System**: list of software items composing the system (name, version, repository link); +- **Document generation info**: user who generated the document and timestamp. + +## Acceptance Test Report + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Acceptance Test Report** contains the outcome of the acceptance testing activities and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Reference Template**: name and revision of the template used; +- **Project Name**: name of the project; +- **Requesting Company**: + - **Requester**: name of the requester; + - **Offer Code**: code of the offer; + - **Customer Company**: extended name of the customer company; + - **Customer Requester**: name of the customer requester; +- **Date**: date of the document; +- **Location**: location (e.g. Milano); +- **Client**: client company name; +- **Mia-Care Project Manager**: Product Owner name; +- **Project Contact Person for the Client**: client contact person; +- **System Description**: introduction and list of requirements; +- **Reference Documents**: Project Offer reference document name; +- **Final Release**: + - **Acceptance Test Subject**: subject of the acceptance test; + - **Outcome**: result of the test (e.g. POSITIVE); + - **Subsequent Activities**: agreement details for AMS service; +- **Signatures**: Mia-Care Project Manager and Client Manager; +- **Document generation info**: user who generated the document and timestamp. + +## Verbale di Collaudo + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Verbale di Collaudo** contains the outcome of the acceptance testing activities and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information and the template is in italian: + +- **Template di riferimento**: name and revision of the template used; +- **Nome Progetto**: name of the project; +- **Società richiedente**: + - **Richiedente**: name of the requester; + - **Codice Offerta**: code of the offer; + - **Società richiedente estesa**: extended name of the customer company; + - **Referente cliente**: name of the customer requester; +- **Data**: date of the document; +- **Luogo**: location (e.g. Milano); +- **Committente**: client company name; +- **Responsabile Progetto Mia Care**: Product Owner name; +- **Referente di progetto per il committente**: client contact person; +- **Descrizione sistema**: introduction and list of requirements; +- **Documenti di riferimento**: Project Offer reference document name; +- **Rilascio finale**: + - **Oggetto collaudo**: subject of the acceptance test; + - **Esito**: result of the test (e.g. POSITIVE); + - **Attività successive**: agreement details for AMS service; +- **Firme**: Mia-Care Project Manager and Client Manager; +- **Document generation info**: user who generated the document and timestamp. + +## Traceability Matrix + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Traceability Matrix** contains the traceability information between requirements, tests, risks, software items and change requests and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Document version**: version of the document; +- **Scope**: scope of the document; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **Matrix**: table with the following columns for each requirement: + - **Requirement key**: key of the requirement; + - **Verified by (Test)**: list of tests verifying the requirement (key); + - **Mitigates (Risk)**: list of risks mitigated by the requirement (key, title); + - **Implemented in (Software Item)**: list of software items implementing the requirement (name, version); + - **Affected by (Change Request)**: list of change requests affecting the requirement (key, title); +- **Document generation info**: user who generated the document and timestamp. + + +## Change Request Report + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Change Request Report** contains the list of change requests linked to the system version and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Scope**: scope of the document; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **Summary of Change Requests**: list of change requests (key, title); +- **Change Requests**: detailed list of change requests, including: + - **Key** and **Title**; + - **Classification**: classification of the change request; + - **Description**: detailed description; + - **Acceptance criteria**: criteria for acceptance; + - **Affected Version**: version affected by the change; + - **Approval Date**: date of approval; + - **Assignee**: person assigned to the change request; + - **Status**: current status; + - **Linked Requirements**: list of linked requirements (key, title); + - **Notes**: additional notes; +- **Conclusion**: conclusion on change requests implemented in the software system version; +- **Document generation info**: user who generated the document and timestamp. + +## Software Architecture Description + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Software Architecture Description** contains the description of the software architecture and design and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Document version**: version of the document; +- **Scope**: scope of the document; +- **Product Information**: + - **Product Name**: name of the product; + - **Product Version**: version of the software system; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; +- **Reference Documentation**: scope of the document; +- **Software Architecture Overview**: + - **Schema**: software architecture image; + - **Components**: list of software items (name, version, parent, parent type, safety class, SOUP); +- **Software Design**: description of software design (e.g. authentication, design patterns); +- **Development Tools**: list of tools used for development; +- **Development Environment**: description of development environments; +- **Software Deployment**: description of the deployment process; +- **Main Technical Decision Justifications**: rationale for main technical decisions; +- **Document generation info**: user who generated the document and timestamp. + +## Risk Management Report + +| Available formats | Available for | Download from | +|:-----------------------|:---------------|:--------------| +| Markdown | System version | Overview page | +| Docx | System version | Overview page | + +The **Risk Management Report** contains the risk analysis and management information and can be downloaded from the [Overview page][software-system-overview]. + +The report provides the following information: + +- **Signatures**: table with Role, Name, and Signature for Author, Reviewer, and Approver; +- **Reference Template**: name and revision of the template used; +- **Document version**: version of the document; +- **Scope**: scope of the document; +- **Product information**: + - **Product Name**: name of the product; + - **Planned Date**: planned release date; + - **Released Date**: actual release date; + - **Version**: version of the software system; +- **Reference Documentation**: scope of the document; +- **Summary of Risks**: list of risks (key, title); +- **Risk Analysis**: detailed analysis for each risk: + - **Key**, **Status**, **Title**; + - **Assignee**: person assigned to the risk; + - **Hazard**: description of the hazard; + - **Sequence Of Events**: sequence of events leading to the hazardous situation; + - **Hazardous Situation**: description of the hazardous situation; + - **Harm**: description of the harm; + - **Risk Assessment**: table with Probability, Probability Notes, Severity, Risk (P*S), Probability after RCM, Severity after RCM, Residual Risk; + - **Linked Software Items**: number of linked software items; + - **Linked Risk Control Measures**: list of linked requirements (key, title); +- **Verification of Risk Control Measures**: comments on verification; +- **Conclusion**: conclusion on overall residual risk and benefit-risk analysis; +- **Document generation info**: user who generated the document and timestamp. + + [software-system-overview]: system_overview.md [changes]: changes.md [risks]: risks.md [risks-levels]: risks.md#levels [sbom]: sbom.md -[tests]: verification.md \ No newline at end of file +[tests]: verification.md diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/requirements.md b/versioned_docs/version-2.3.x/p4samd/handbook/requirements.md index c1e4a28326..c5802a6f08 100644 --- a/versioned_docs/version-2.3.x/p4samd/handbook/requirements.md +++ b/versioned_docs/version-2.3.x/p4samd/handbook/requirements.md @@ -25,7 +25,7 @@ Furthermore, the user is assisted evaluating the design inputs of the project th - **Status**: the status of the requirement (opened, closed, etc.) - **Software Items**: the number of software items affected by the requirement. - **Risks**: the number of risks mitigated by the requirement. -- **Tests (test coverage)**: the number of tests verifying the requirement. +- **Tests (test coverage)**: the number of tests verifying the requirement and the coverage of the requirement, evaluated by AI. - **Changes**: the number of changes applied to the requirement. The table presents an overview of the traceability, through the count of linked entities such as software items, tests, risks and changes. @@ -92,6 +92,7 @@ Also remember that information generated by AI may be inaccurate or misleading, ::: +### Requirement Quality You can assess the conformity of a SaMD requirement by hovering on the icon under the **Quality** column in the corresponding table row and click on the `Get evaluation` button. The assessment may take a while, usually around a minute, so while we process it in the background you can keep working on P4SaMD and come back to check the progress at any time. @@ -118,5 +119,8 @@ At the top you can see a **suggested description**, which provides an example of Also, you can check how it scored on each specific criteria mentioned above, including the specific areas of strength and weakness. +### Estimated Test Coverage + +The assessment on the requirement quality provides also an AI evaluation of the test coverage: all the **linked tests** are condidered for the estimantion, and the percentage result is shown in the **Tests (test coverage)** column. Additional information and insights about the score are reported in the Requirement Deatil (drawer), inside the Traceability tab. The system suggests also test cases based on the assessed requirement, to increase the coverage and improve the overall testbook completeness. [faq-data-sharing]: ../faq.md#does-mia-care-p4samd-share-data-with-third-party-organizations diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/system_overview.md b/versioned_docs/version-2.3.x/p4samd/handbook/system_overview.md index e894063145..38748ee7ef 100644 --- a/versioned_docs/version-2.3.x/p4samd/handbook/system_overview.md +++ b/versioned_docs/version-2.3.x/p4samd/handbook/system_overview.md @@ -25,15 +25,27 @@ Below the global progress bar, users will find a series of **detailed progress b These KPIs provide actionable insights, enabling teams to measure progress and focus on areas requiring immediate attention. ## Reports -Directly beneath the overall progress bar, a **select dropdown menu** enables users to generate and download reports tailored to the selected system version. The following reports are available: +Directly beneath the overall progress bar, a **select dropdown menu** enables users to generate and download reports tailored to the selected system version. +There will be some default reports that are taged as + + The following reports are available as set of `Default` templates: - **Release Note**: Summarizes the key updates, features, and resolved issues in the system version. -- **Risk Report**: Provides a detailed analysis of identified risks, their risk control measures and current statuses. -- **Test Report**: Lists all tests performed, their results, and any associated observations or issues. -- **Change Report**: Documents all approved and implemented change requests. - **SOUP Report**: Details the use of all Software of Unknown Provenance (SOUP). - **Changelogs**: A folder containing the changelogs of each custom software components. - **Unit Tests**: Presents the outcomes and coverage of unit tests performed on custom software components. - **Vulnerability Report**: Provides a summary and details of detected vulnerabilities for the specific system version. +- **Software architecture Design**: Provides the software items high level design as an image. + +The following reports are provided as the `Default templates`: +- **Release Note**: Summarizes the key updates, features, and resolved issues in the system version. +- **Acceptance Test Report**: Documents the results of acceptance testing to verify that the system meets specified requirements. +- **Verbale collaudo**: Provides the official test acceptance record (Italian compliance document). +- **Traceability Matrix**: Maps relationships between requirements, design elements, tests, and other artifacts to ensure full traceability. +- **Change Report**: Details all changes made to the system version, including modifications, additions, and deletions. +- **Software Architectural Design Description**: Describes the high-level software architecture, including components, interfaces. +- **Risk Management Report**: Provides a comprehensive overview of identified risks, their assessments, and mitigation strategies. +### Custom Reports +You can create additional custom reports by designing templates using the documentation engine. Once published, these templates will become accessible in the dropdown menu and can be downloaded for any system version. please take a look at the [Documentation Engin](document-engine.md) These reports ensure compliance, traceability, and readiness for audits or external reviews. diff --git a/versioned_docs/version-2.3.x/p4samd/handbook/verification.md b/versioned_docs/version-2.3.x/p4samd/handbook/verification.md index f47b0b9047..e7d7e98a58 100644 --- a/versioned_docs/version-2.3.x/p4samd/handbook/verification.md +++ b/versioned_docs/version-2.3.x/p4samd/handbook/verification.md @@ -14,11 +14,11 @@ Manual testing remains relevant, especially for usability and exploratory testin P4SaMD provides a comprehensive overview of all the tests planned for a version of the software system, organized in three main tabs: -- **All tests**: Displays the list of individual tests which are applicable for the current Software Version. The list includes all the tests associated to the current system version and the previous ones, as long as they are not deprecated. -- **Test suites**: Shows the available test suites and allows navigation into suite details. The Test Suites are collectors of tests, to facilitate the test grouping and their execution. +- **All tests**: Displays the list of individual tests which are applicable for the current Software Version. The list includes all the tests associated to the current and other system versions, as long as they are not deprecated. +- **Test suites**: Shows the available Test Suites and allows navigation into suite details. The Test Suites are collectors of tests, to facilitate the test grouping and their execution. - **Executions**: Lists all test executions with access to execution details and reports. The executions can refer to a single or multiple tests, achieved by the execution of Test Suites. -The tests originate from the integrated ALM, where they can be created, updated, and deleted. The table dynamically reflects any changes made inside the ALM. +The nominal definition of tests originates from the integrated ALM, where you can create new ones, update the information, and delete them. The P4SaMD table dynamically reflects any changes made inside the ALM. Users are assisted in evaluating the quality and compliance of the tests thanks to AI-powered evaluation features. ## All tests @@ -30,7 +30,7 @@ For each test the following information are provided: - **Quality**: the latest evaluation performed using AI, see a legend of the different icons below. - **Type**: the type of test, like integration or system; - **Execution Mode**: if the test is executed automatically or manually; -- **Test Suite**: if the test is part of an [automated test suite](#test-suites); +- **Test Suite**: if the test is part of an [automated Test Suite](#test-suites); - **Latest Execution**: details about the last text execution, including when it was performed and the outcome. The outcome can refer to the overall test (e.g. passed or failed for manual tests) or to the underneath test cases of the test (e.g. count of successful, failed or skipped test cases); - **Software Items**: the number of software items associated to the test; - **Requirements**: the number of requirements verified by the test. @@ -128,34 +128,83 @@ Also, you can check how it scored on each specific criteria mentioned above, inc ## Test Suites -In this tab, you can manage the tests though Test Suites: create, update and also delete them. The displayed Test Suites are referring to the current system version and allow to group multiple tests of the same type. In fact, Test Suites can be _automatic_ or _manual_, and the related tests must be coherent to the defined type. +In this tab, you can manage the tests through Test Suites: create, update and also delete them. The displayed Test Suites are referring to the current system version and allow to group multiple tests of the same type. In fact, Test Suites can be _automatic_ or _manual_, and the related tests must be coherent to the defined type. -For each test suite, the following information is shown: +For each Test Suite, the following information is displayed: -- **Title**: Name of the test suite. +- **Title**: Name of the Test Suite. - **Execution Mode**: Automatic or manual, strictly tied to the Execution Mode of the associated tests. - **Tests**: Number of tests included in the suite. - **Last Execution**: Status and date of the last execution. -### Actions +### Managing Test Suites -- **Add suite**: Create a new test suite. -- **Run all**: Initiate execution of all automated test suites that have an API Trigger configured. -- **View Details**: Click on a row to access the details of the selected test suite. -- **Run Test Suite**: Execute an automated test suite when its API Trigger is configured. You can also _select_ more than one Test Suite and execute multiple test suites in a single action. -- **Delete Test Suite**: Delete a specific test suite, without deleting the associated tests. -- **Edit Test Suite**: Allows users modify a specific test suite, such as the title. +#### Creating Test Suites -### Detail +- **Add suite**: Create a new Test Suite. NB. Test suites can be created for software versions that are not yet released. Each Test Suite can contain one or more tests. + +#### Running Test Suites + +- **Run all**: Initiate execution of all automated Test Suites that are configured with an External Test Executor. +- **Run Test Suite**: Execute a specific automated Test Suite when its API Trigger is configured. Multiple Test Suites can be selected and executed simultaneously. +- **Manual executions**: Must be handled in the ALM tool, where testers initiate and update execution information. + +#### Other Actions + +- **View Details**: Click on a row to access detailed information about the selected Test Suite. +- **Edit Test Suite**: Modify Test Suite properties such as the title. +- **Delete Test Suite**: Remove a specific Test Suite without deleting the associated tests. + +### Test Suite Details + +Clicking on a row displays the Test Suite details in three tabs: + +#### Tests Tab +Shows all tests included in the Test Suite with their individual properties and status. + +#### Executions Tab +Displays chronological executions of the specific Test Suite, with options to download corresponding reports when available. + +#### External Test Executor Tab +Configure the external service required for automatic test suite execution. -Clicking on a row open a new page where there's the details of the test suite. Here we have three tabs: -- **Tests**: Show all the tests related to the test suite. -- **Executions**: Displays all executions that include the test suite, with the option to download the corresponding report if available. -- **Api Trigger**: This section allow to create or edit the **Api Trigger** needed to automatically execute test suite. +**Configuration Requirements:** +- P4SaMD requires a `jobId` to trigger the executor correctly +- Include the `{{@jobId}}` placeholder in at least one of: **Endpoint URL**, **Payload**, or **Header** +- Without proper `jobId` configuration, the executor cannot run -### Test Suite Execution Flow +### Automatic Test Suite Execution -When you run a test suite, P4SaMD triggers the configured external test executor via API. The executor sends back results through a webhook to update the execution status. If the report is provided in JUnit format, P4SaMD automatically processes and displays the results in the dashboard. Otherwise, only the execution status is recorded, and the report file remains available for download. +#### Execution Flow + +1. **Initialization**: User triggers execution → new job created with assigned `JobId` +2. **Running**: `jobId` inserted into configured location → External Test Executor runs → job updates based on response +3. **Results**: External executor sends updates via webhook → execution status is updated → results are processed +4. **Reports**: JUnit format reports are automatically processed and displayed; other received formats are saved and are downloadable + +#### Configuration Prerequisites + +- External test executor must be configured +- `{{@jobId}}` placeholder must be set in test suite details +- Without proper configuration, P4SaMD cannot trigger or run test suites + +#### Webhook Integration + +External Test Executors update job status via webhook: + +``` +https://{{domain}}p4samd/webhook/update-run-test-suite/:jobId +``` + +**Supported Parameters:** + +| Name | Type | Description | +|------------|--------|------------------------------------------- | +| outcome | string | Updates the status of the job execution | +| result | string | Final test results (if report not in JUnit format) | +| message | string | Execution description | +| junitXml | string | JUnit format report (automatically processed) | +| reportFile | file | Report file (downloadable, not auto-processed) | ## Executions @@ -165,8 +214,8 @@ For each execution, the following pieces of information are available: - **Date and time**: When the execution was performed. - **Note**: Show an icon if there are some notes. -- **Test suites**: Number of test suites involved in the execution. -- **Outcome**: Result of the execution of all test suites included in that execution (passed, failed, etc.). +- **Test suites**: Number of Test Suites involved in the execution. +- **Outcome**: Result of the execution of all Test Suites included in that execution (passed, failed, etc.). - **Executed by**: User who performed the execution. - **Download report**: Download a ZIP archive containing a summary of the execution and all available individual reports from that execution. @@ -176,15 +225,12 @@ Each execution provides a downloadable ZIP archive containing: - **README.md**: A summary file with execution details, including: - Execution date and executor name - - Overview of all test suites included in the execution - - Final result for each test suite (passed, failed, etc.) - - Reference to corresponding report files when available -- **Individual Reports**: All available test suite reports from that execution - - -Clicking on a row opens the execution detail view, showing all relevant information about the selected execution. + - Overview of all Test Suites included in the execution + - Final result for each Test Suite (passed, failed, etc.) + - References to corresponding report files when available +- **Individual Reports**: All available Test Suite reports from that execution ### Detail Clicking on a row opens a new page showing the execution details. -Here you will find details including the execution date, the user who performed the execution, and any associated notes. The view also lists all test suites involved in the execution along with their related tests. You can download a comprehensive report for the test suite execution, which includes a summary file and all available individual test suite reports as attachments. +Here you will find details including the execution date, the user who performed the execution, and any associated notes. The view also lists all Test Suites involved in the execution along with their related tests. You can download a comprehensive report for the Test Suite execution, which includes a summary file and all available individual Test Suite reports as attachments. diff --git a/versioned_docs/version-2.3.x/p4samd/security/roles_permissions.md b/versioned_docs/version-2.3.x/p4samd/security/roles_permissions.md index 89a9f9de7d..71f95afdaf 100644 --- a/versioned_docs/version-2.3.x/p4samd/security/roles_permissions.md +++ b/versioned_docs/version-2.3.x/p4samd/security/roles_permissions.md @@ -39,6 +39,13 @@ All permissions starting with `console` are inherited from the Console, while th | [Evaluate test with AI](#evaluate-test-with-ai) | `p4samd.test.ai.evaluate` | | [Run test suite](#run-test-suite) | `p4samd.test.suite.run` | | [Delete test suite](#delete-test-suite) | `p4samd.test.suite.delete` | +| [Update Console project configuration](#update-console-project-configuration) | `console.company.project.configuration.update` | +| [Create document](#create-document) | `p4samd.documents.create` | +| [Delete document](#delete-document) | `p4samd.documents.delete` | +| [Download document preview](#download-document-preview) | `p4samd.documents.download.preview` | +| [Publish document](#publish-document) | `p4samd.documents.publish` | +| [Update document](#update-document) | `p4samd.documents.update` | +| [Download documentation](#download-documentation) | `p4samd.documentation.download` | This table provides the default list of the P4SaMD permissions granted to each Console role. Please contact directly Mia-Care for more info or customization. @@ -63,6 +70,12 @@ This table provides the default list of the P4SaMD permissions granted to each C | `p4samd.test.ai.evaluate` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | `p4samd.test.suite.run` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | | `p4samd.test.suite.delete` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.create` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.delete` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.download.preview` | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | +| `p4samd.documents.publish` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documents.update` | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ | +| `p4samd.documentation.download` | ❌ | ❌ | ✅ | ✅ | ✅ | ✅ | ## Security policies @@ -212,6 +225,27 @@ A user must have the Console `console.company.project.configuration.update` perm Without this permission, the user is not displayed the button on the [Software Items table][software-items-table] redirecting to the *Design > Microservices* section of the Console project. +### Create document + +A user must have the `p4samd.documents.create` permission to create a new template. + +### Delete document + +A user must have the `p4samd.documents.delete` permission to delete an existing template. + +### Download document preview + +A user must have the `p4samd.documents.download.preview` permission to download a preview of a template. + +### Publish document + +A user must have the `p4samd.documents.publish` permission to change the state of a template. + +### Update document + +A user must have the `p4samd.documents.update` permission to update an existing document. + + This permission is inherited from the [Console roles and permissions][console-roles-permissions]. diff --git a/versioned_sidebars/version-2.3.x-sidebars.json b/versioned_sidebars/version-2.3.x-sidebars.json index 161b631118..29ea1bdee4 100644 --- a/versioned_sidebars/version-2.3.x-sidebars.json +++ b/versioned_sidebars/version-2.3.x-sidebars.json @@ -74,6 +74,11 @@ "id": "p4samd/handbook/references", "label": "References", "type": "doc" + }, + { + "id": "p4samd/handbook/document_engine", + "label": "Documentation Engine", + "type": "doc" } ] },