Compliance Report & Form - requirements

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

• 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.

• 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.

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:

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

https://www.figma.com/file/9XudBIl7YAt3aH1nMBoO4L/govstack?type=design&node-id=1629-5254&mode=design&t=3UW1rRs2svCic5yj-0

People responsible

• Requirements @Nico Lueck @Steve Conrad

• Development @Damian Borowiecki (Deactivated) @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 of StatusEnum, 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 type DeploymentComplianceSchema containing deployment-related information.

• compliance: An array of ComplianceVersionSchema 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 of SpecificationComplianceLevel, 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 the ComplianceDetailSchema.

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 of StatusEnum, representing the status of the compliance.

• submissionDate: A date representing when the compliance details were submitted.

• deploymentCompliance: An enumeration of SpecificationComplianceLevel, containing information about deployment compliance.

• interfaceCompliance: An object of type interfaceComplianceSchema describing the level of compliance with the interface.

• requirementSpecificationCompliance: An object of type requirementSpecificationComplianceSchema 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 of SpecificationComplianceLevel, indicating the compliance level.

• crossCuttingRequirements: An array of RequirementSchema objects representing cross-cutting requirements and their details.

• functionalRequirements: An array of RequirementSchema objects representing functional requirements and their details.

interfaceComplianceSchema

The interfaceComplianceSchema class defines the compliance level with respect to the interface.

Attributes:

• level: An enumeration of SpecificationComplianceLevel, indicating the compliance level.

• testHarnessResult: A string containing the test harness results.

• requirements: An array of RequirementSchema 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 of RequirementFulfillment, indicating whether the requirement has been met or not.

• status: An enumeration of RequirementStatusEnum, 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:

Open

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 )