Report a Problem Design Doc
status of design doc:
Authors: Omar Nasr
Reviewers: TBD
The canada ca design system specifies that there must be a report a problem mechanism on each and every page. This is used to report issues such as bugs or typos on a page. This design doc will outline how we plan to implement this feature in our application.
Along with our user story
As a user I want to be able to tell the people in charge of this site if I experience a usability issue, an accessibility issue, a typo, or a bug so that it can be fixed quickly and I can help be part of improving this product.
There is a requirement according to the canada ca design system as mentioned that all pages must include a report a problem mechanism. Specifically this should be a button that when clicked will show a form where a user can specify the problem and then submit the form to send the feedback
This allows us to collect valuable user feedback on things such as bugs, typos and other technical feedback.
- Provide a mechanism for users to report problems in different categories
- Have a central location to collect technical feedback
- A generic feedback service, this is only meant for technical feedback
What are the high level checkpoints and when do we want to achieve them
Start Date: [ some date ]
Milestone 1 - [ goal ] [date]
Milestone 2 - [ goal ] [date]
.
.
.
End Date: [ some date ]
We do not have an existing solution currently.
The canada ca design system specifies that this must be included on every page however it does not specifically mention exactly how feedback is collected
Sending the form: Make sure to replace the "#" placeholder in the form action line with whatever your institution uses to collect the data from the form. Consider sending the form to a generic email inbox if you don't have a server set up to handle this type of form.
We have two main options
-
Build an API and UI applications to collect submissions from form and display feedback to admin users ( aka developers, product owner ect )
-
Use a generic inbox and send an email using the GC Notify Service along with a Next JS API route to collect submissions from the report a problem form
Option 1 would require a lot of effort since we would first need to build an API, secure it with some sort of authentication system and also a UI application to display and provides a means to search the information. This offers little return when compared to option 2
Option 2 is ideal as it requires much less effort and by virtue of using a generic inbox information is secured via access to the inbox and is searchable via outlook. In fact option two is how ESDC currently implements its report a problem feature on its pages
GC Notify is a SaaS service that provides an API that allows you to submit data and specify an email template from which the data is used to fill out to send an email to a specific address.
An alpha site application has already been set up on notify
An email template would need to be created with the content and fields that we want filled out using the notify format
Next JS provides a mechanism to build API routes using the underlying node HTTP server. So, this would involve building a route under /pages/api/ that would take data from the form submission (POST request) and then call the GC Notify api with the specific template and data in the form submission.
On the react/client side of things a form would be set up with the action being the path of the api route such as when the submit button is clicked the browser sends a POST request to our API with the form data.
<form id="report-a-problem" action="/api/report-a-problem" method="POST">
<!--hidden input to denote the language of the submission-->
<input type="hidden" id="language" value="en">
<label for="something-is-broken">Something is broken</label>
<input id="something-is-broken" value="something is broken" type="checkbox"/>
<!-- more fields -->
<button type="submit">
</form>When a checkbox is clicked a related text field appears under it to provide more detail.
on submission, the form would show a thank you message in the language of the user (english/french)
Unit testing and cypress end to end test will be written to make sure the entire flow works. Built in app service logging features will be used to monitor and alert should there be errors or issues in the Next JS API.
- Form could be abused providing a vector for spam attack from malicious actors or bots.
- Personally Identifiable Information could be entered on accident by unassuming users which could result in a personal information breach
- Logging setup in app service needs to be investigated to provide alerts on logging of error messages to console.
- How do we handle PII? There are many different options, we could come up with some regex to detect emails, phone numbers, SINs ect and prevent the user from submitting on the client side. This can also be done server side however, there is no concrete method on handling this.
- How do we incorporate spam prevention? Do we incorporate a captcha ? Rate limit the API ? ect ect