Compliance Report & Form - requirements
- 1 Feature Description
- 2 Goals
- 3 Actors
- 4 Use cases
- 5 User Stories
- 6 Components and functional requirements
- 7 Non-functional requirements
- 8 Evaluation Report Flow
- 9 Designs
- 10 People responsible
- 11 Technical specification
- 12 DeploymentComplianceSchema
- 13 requirementSpecificationComplianceSchema
- 14 interfaceComplianceSchema
- 15 RequirementSchema
- 16 Roadmap
- 17 Sing-off
- 18 Q&A
Feature Description
The scope of this feature is to extend the testing app to not only cover the API tests results but also enable viewing overall compliance reports for each category(Deployment, Interface, and Requirements Specification compliance) of each software. It should also enable Software Providers to submit their candidate application to be checked against GovStack requirements.
List of softwares' compliance results
All users should be able to view the list of all softwares' reports summary as well as view the detailed report. All users should be able to see rows with “Approved” and “Rejected” status. Users with “Approver” role should also be able to see rows with “In Review” status. No one should be able to see forms with “Draft” status.
The summary should only contain the newest results for each BB that the software was tested against.
Example:
Software A version 1.0 checks compliance against Identity BB version 1 and Registration BB version 1. Outcome:
Rows for both BBs should be displayed in the table
Software A | ||
---|---|---|
Software A version 1.0 | Identity BB version 1 | … |
Software A version 1.0 | Registration BB version 1 | … |
There is a new version 1.1 of Software A. Software Provider checks compliance against Identity BB version 1 but doesn’t check against Registration BB again.
Outcome:
Only the newest software version for Identity BB should be visible in the summary table. Registration BB results for the previous version of the system should also be visible.
Software A | ||
---|---|---|
Software A version 1.1 | Identity BB version 1 | … |
Software A version 1.0 | Registration BB version 1 | … |
There is a new version of Identity BB. Software A version 1.1 wants to check its compliance against the newest version of this BB.
Outcome:
Only the newest Identity BB version that was tested should be visible in the table. Registration BB results for the previous version of the system should also be visible.
Software A | ||
---|---|---|
Software A version 1.1 | BB Identity version 2 | … |
Software A version 1.0 | BB Registration version 1 | … |
The detailed view should include software details as well as the whole history of checks for each version of the system and each version of the building block.
Example:
Software A version 1.0 | ||
---|---|---|
Identity BB | V1 | … |
Registration BB | V1 | … |
Software A version 1.1 | ||
---|---|---|
Identity BB | V1 | … |
Identity BB | V2 | … |
… | … | … |
Compliance form
Software Providers should be able to submit the compliance form for each compliance category. Deployment compliance is a required category for the user to fill in as well as it’s required to complete at least one of the Interface and Requirements Specification in order to submit the form. Deployment configuration is completed only once for one software. Interface Compliance as well as Requirements Specification compliance categories are filled in for each BB separately as for each BB those requirements are different and this functionality should allow completion of the form for more than one BB at the same time. User should be able to save the draft without submitting it and edit it in the future (no longer than 3 days without being active in the form(to confirm) from creating the draft). Once the draft is created, user should get an email with a personalized link that will allow him to complete and submit the form. When the user submits the form, a new Jira ticket should be created and a notification with a link to it should be displayed in addition to an email automatically sent to the user.
Approver view
GovStack staff with approver role should be able to log into the system using proper credentials. For now, accounts should be created in the backend, without a registration page. Once the compliance form is submitted, GovStack staff should be able to review it. They should see the summary of the submitted compliance form with calculated results. They should also be able to see the detailed view for each compliance category. During review, they should be able to add comments as well as choose compliance level. Compliance form can be either approved and moved to the “Approved” state or rejected and moved to the “Rejected” state. Rejected forms can be edited by their authors with a link that is sent to their email after the review is completed.
The solution should be aligned with an overall Compliance Concept described in this document Software Compliance Concept.
Goals
To allow users looking for a specific tool to view detailed software compliance results for each BB they were checked against.
To allow Software Providers to draft, edit, and submit compliance form for their software on each level of compliance for specified BBs and check the results.
To allow GovStack staff to review evaluation reports.
Actors
Software Providers
GovStack Approvers
Users looking for a specific tool
Government Ministry
System integrator
Use cases
Software Providers
Draft an evaluation report
Submit an evaluation report
Update an evaluation report
GovStack Approvers
Verify an evaluation report
Add notes to an evaluation report
Select the compliance level for each category
Approve evaluation report
Reject evaluation report
Users looking for a specific tool
View evaluation report overview
View one specific evaluation report
User Stories
Components and functional requirements
Menu
The system must allow all users to navigate between Compliance Reports and API Testing Reports
Evaluation Reports
The system must allow all users to view a summary of evaluation reports for all softwares.
The system must allow all users to view detailed reports for each software with the history for each version.
The system must show user description of the Evaluation Schema (Software Compliance Concept | Evaluation Schema )
Compliance form
The system must allow Software Providers to create a draft form.
The system must allow Software Providers to save changes in a draft (automatically + manually).
The system must allow Software Providers to edit not submitted or rejected draft with a personalized link sent by email.
The system must allow Software Providers to submit a draft.
The system must upload Requirements Specification data from GovStack GitBook specification https://govstack.gitbook.io/specification/.
Approver form
The system must allow GovStack staff to view the evaluation summary with all the details.
The system must allow GovStack staff to add notes to each compliance category.
The system must allow GovStack staff to either approve or reject the form.
Integration with Jira
The system must integrate with Jira to create an issue once a new form is submitted.
Email notification
The system must send a confirmation email when a draft is created with a link to edit the form.
The system must send a confirmation email when a form is submitted with a link to Jira issue.
The system must send a notification email after a review is submitted with the output.
The system must send a notification email after 48 hours with a link to the edit form.
Authentication
The system must allow GovStack staff to log into their account using GitHub SSO.
Non-functional requirements
Performance
Developed software should be of adequate speed, stability, responsiveness, reliability, and scalability, which could be verified by traffic, load, and stress testing. Performance testing should be done in every regression testing cycle, at first manually, but at a later date, automated performance checks will be created to assist in software maintenance.
Accessibility
Developed software should be as inclusive as is required by business and as such it should be designed from the start with accessibility in mind. To adhere to the general standard for digital products, compliance with the WCAG 2.0 level AA is desirable. The compliance level will be checked through design testing and later by web auditioning tools.
Compatibility
Developed software should work as was intended in a manner that is of the highest quality on named devices, OSes, and browsers:
Lenovo Legion Y540-15IRH-PG0
Ubuntu 22.04.2 LTS
Chromium 116.0.5845.179
Mozilla 116.0.3
HP ENVY 13-AD0XX
Windows 10 HOME
Chrome116.0.5845.188
Mozilla 117.0.1
Security
The app will be run against a web auditing tool before every major version release with a report presented to the development team.
Localization
As the app will be used by an international audience, localization testing will be taken into account during all the major version releases. To facilitate use in different cultural, linguistic, and geographic settings, things like languages, local variables, or date and time formats will be included.
Evaluation Report Flow
Designs
People responsible
Requirements @Nico Lueck @Steve Conrad
Development @Damian Borowiecki @Damian Szafranek @Łukasz Ruzicki @Karolina Kopacz (Deactivated)
Testing @Piotr Kabelis (Deactivated)
Sign-off @Nico Lueck @Steve Conrad
Technical specification
Compliance Report Schema
Attributes:
softwareName
: A string that represents the name of the software.logo
: A string containing a URL or path to the software's logo.website
: A string that contains the website URL of the software.documentation
: A string that contains the URL to the software's documentation resources.description
: A string that provides a description of the software (limited to 400 characters).pointOfContact
: A string that specifies the contact point or person for the software.status
: An enumeration ofStatusEnum
, representing the status of the software.uniqueId
: (optional, UUID): A string that serves as a unique identifier for the software. This field is required only when the status of the software is in "DRAFT" status. If the status is not "DRAFT," this field may not be present.expirationDate
: A date (optional) representing the expiration date of the draft compliance report. This field is required only when the status of the software is in "DRAFT" status. If the status is not "DRAFT," this field may not be present.deploymentCompliance
: An object of typeDeploymentComplianceSchema
containing deployment-related information.compliance
: An array ofComplianceVersionSchema
objects, capturing compliance details for different versions of the software.
DeploymentComplianceSchema
The DeploymentComplianceSchema
class represents compliance information related to the deployment of the software.
Attributes:
documentation
: A string that may contain either a URL or an image saved as a string. It serves as a reference to documentation related to the deployment.deploymentInstructions
: A string that may contain either a URL or an image saved as a string. It provides information on how to deploy the software.requirements
: An array of objects, each containing:requirement
: A string that describes a specific requirement.level
: An enumeration ofSpecificationComplianceLevel
, indicating the compliance level of the requirement.
Compliance Version Schema
The Compliance Version Schema defines the structure for capturing compliance information related to different versions of the software.
Attributes:
version
: A string that indicates the version of the software.bbDetails
: A map containing details of the Building Block (bb), represented by theComplianceDetailSchema
.
Compliance Detail Schema
The Compliance Detail Schema defines the structure for capturing detailed compliance information for a specific version of the software.
Attributes:
bbSpecification
: A string that uniquely defines the name or specification of the Building Block. This string serves as the unique identifier for the Building Block.bbVersion
: A string that represents the version of the Building Block.status
: An enumeration ofStatusEnum
, representing the status of the compliance.submissionDate
: A date representing when the compliance details were submitted.deploymentCompliance
: An enumeration ofSpecificationComplianceLevel
, containing information about deployment compliance.interfaceCompliance
: An object of typeinterfaceComplianceSchema
describing the level of compliance with the interface.requirementSpecificationCompliance
: An object of typerequirementSpecificationComplianceSchema
describing the level of compliance with requirements specifications.
requirementSpecificationComplianceSchema
The requirementSpecificationComplianceSchema
class defines the compliance level with respect to requirements specifications.
Attributes:
level
: An enumeration ofSpecificationComplianceLevel
, indicating the compliance level.crossCuttingRequirements
: An array ofRequirementSchema
objects representing cross-cutting requirements and their details.functionalRequirements
: An array ofRequirementSchema
objects representing functional requirements and their details.
interfaceComplianceSchema
The interfaceComplianceSchema
class defines the compliance level with respect to the interface.
Attributes:
level
: An enumeration ofSpecificationComplianceLevel
, indicating the compliance level.testHarnessResult
: A string containing the test harness results.requirements
: An array ofRequirementSchema
objects representing interface-related requirements and their details.
RequirementSchema
The RequirementSchema
class represents a requirement and its related information.
Attributes:
requirement
: A string that describes the requirement.comment
: A string for additional comments or details regarding the requirement.fulfilment
: An enumeration ofRequirementFulfillment
, indicating whether the requirement has been met or not.status
: An enumeration ofRequirementStatusEnum
, specifying the status of the requirement (required, recommended, or optional).
Enums:
Status Enum:
Values:
DRAFT
(0): Indicates that the software is in a draft status.IN_REVIEW
(1): Indicates that the software is currently under review.APPROVED
(2): Indicates that the software has been approved.REJECTED
(3): Indicates that the software has been rejected.
Requirement Status Enum:
Values:
REQUIRED
(0): Indicates that a requirement is required.RECOMMENDED
(1): Indicates that a requirement is recommended but not mandatory.OPTIONAL
(2): Indicates that a requirement is optional.
Specification Compliance Level:
Values:
NA
(-1): Denotes that the compliance level is not applicable.LEVEL_1
(1): Indicates compliance at level 1.LEVEL_2
(2): Indicates compliance at level 2.
Requirement Fulfillment:
Values:
NA
(-1): Denotes that the requirement fulfillment status is not applicable.MET
(1): Indicates that the requirement has been met.NOT_MET
(0): Indicates that the requirement has not been met.
UML Diagram:
Roadmap
October
Viewing compliance result summary table
November
Viewing detailed compliance result report for each software
Starting new draft
Email notifications
Form submission
December
Form submission
Login and logout functionality
Approver view
Sing-off
What do we need to hand off the feature?
Tested and working solution with all functional requirements met
Test cases for each functionality
How the work will be accepted?
Tickets for final acceptance for each milestone
Email sent by SolDevelo after each milestone completion (@Damian Szafranek)
3-5 days for a final sign-off of milestones
Who will accept the work?
@Steve Conrad
@Nico Lueck
Q&A
Can we only have GitHub authentication for GovStack approvers without email/password login? We don't need to store it in the database and doesn't require registration form.
GitHub authentication will be sufficient for now.
Deployment compliance form - what link or data should be provided there by user?
They should provide one or more URLs that point to files in GitHub - these will be the Dockerfiles, docker-compose, and/or Kubernetes/Helm charts.
If we want to get the Requirements Specification compliance data from Gitbook - is it possible to format all the requirements differently to make sure it's consistent across all BBs? Ideally, we could have them in the table format, the first row for a requirements and the second "is required".
Or maybe instead of parsing data from GitBook we could have an excel file with all the requirements that will be updated before the release when there are some changes added?SolDevelo can go through and adjust the requirements in section 6 of each spec to be in a format that is readable by the parser.
All questions were asked and answered on Slack (https://govstack.slack.com/archives/C048RT2FPP1/p1693814923303529 )