[epic] DR | Downloadable Copy of Submission

[saderagsdale]

Value Statement

As a Veteran that has just submitted an appeal on VA.gov I want to download a copy of the information I submitted on the form So that I can retain it for may records and reference it if I need to recall what I submitted for future filing purposes.

Initiative Brief

Success Metrics

We will know we are right when/if:

• Users can easily spot the accessible version and download it

Specifications

Category	Acceptance Criteria	UI + Accessibility Requirements	FE Technical Requirements	BE Technical Requirements	Logging and Monitoring	Implementation Idea(s)
Confirmation page	User is advanced to a confirmation page where they can both see and save the information they submitted.	Users see success alert, PDF download option, print button, what to expect next section, how to contact VA, and plain-text html version of their responses for the form	n/a	n/a	n/a	Already implemented.
Alert	User is aware they've successfully submitted their claim, when it was submitted, and what happens directly after submission	Users are shown a success alert that includes date of submission, form submitted, and next course of action	n/a	n/a	Alert visibility already sent to Google Analytics	Already implemented.
Download delay	User can still access the confirmation page if there is a longer than acceptable delay in PDF generation	While download link is loading, the user is shown a loading indicator (general or progress bar). The loading indicator will inform the Veteran of whether or not the content is still loading.	Option 1: Load confirmation page and show loading indicator for the PDF. When PDF is done loading, use aria-live to indicate that there's been an update to the page. Option 2: Delay loading confirmation page until API call is returned about PDF is generated, and upon failure, load page without PDF download From API: Need an endpoint to poll to get the status/availibility of the PDF. Options could be an immediate response yay/nay or an endpoint with a timeout of 30-60secs and a response of yay/nay	(Need to verify) API calls for submission are async. First submits form, with a response of an ID Second would be to poll LH with ID until PDF is ready, this can take an unknown amount of time. LH API needs to reopen endpoint to get PDF file.	Need to log API success & failures and add the result into a DataDog widget for each form
Download link	User can download a copy of the PDF via a link.	Success: Users see downlaod link	Does this open the PDF in a new window, or directly download the PDF? Direct download	LH API needs to reopen endpoint to get PDF file	Log usage of link	After the PDF is generated by Lighthouse, the confirmation page becomes available, and a user can download it.
PDF Error State	User is notified if the PDF is not available for download.	Failure: Users see alert that the download link did not generate, but they can still review the page for their answers. No extra accessibility requirements here: The alert will do the work, and we don't want to shift focus because the Veteran could be doing something else on the page.	From API: Need an endpoint to poll to get the status/availibility of the PDF. Options could be an immediate response yay/nay or an endpoint with a timeout of 30-60secs and a response of yay/nay	LH API needs to reopen endpoint to get PDF file Endpoint will have to return an expired status vs a not found status to tell the difference	Log time/status if PDF file is unavailable (might get noisy depending on how often we poll)
Print button	User can print the confirmation page by clicking a button and is made aware that printing will store all information on the page, but it won't be in the paper form format.	Users see a print button and clicking, triggers their browser's print modal.	Could use print/media styling to reformat page into printable version	n/a	n/a	Already implemented.
"What to expect next" content	User is made aware of the timeline for establishing their appeal and when/how to check the claim status tool.		n/a	n/a	n/a	Custom content and link to CST.
"You submitted the following information for the Board Appeal"	Users are able to review all of their answers from the form, and get a list of evidence file names (not the actual files themselves) they've uploaded with the form.	Users are able to use headers to navigate sections to review the form, and form responses are tied to questions for both visual and screen reader users Each section should use one unordered list and one list item for each form label/form data pair. This will help assistive technology group the content.	n/a	Data retention policies might prevent this feature. Working with Cory to concrete answers as ATO is ambigious	n/a
Confirmation email	User receives a confirmation email that notifies Veterans their submission has been sent and is being processed.		n/a	Will need vanotify template	Log when email is sent	Use the email Lighthouse is submitting (edit the copy)

[saderagsdale]

Old copy:

Specifications

• User can click a link to view submitted data on persistent page (open question: how are URLs generated if a user submits multiple appeals the same day?
• User can bookmark the page for later use (open question: how do users know that the page is persistent and can be revisited? What happens when the persistent page expires?)
• User can download the standard PDF available through lighthouse (open question: What happens when the persistent page expires?)
• Open question: How do we alert users with accessibility needs of the available format? (content, tabbing through headers
• User can download a copy of the data they submitted entered into their appeal form
• User can see the names of the files they submitted with the appeal form
• User can optionally download an accessible copy of the data they submitted entered into their appeal form
• User can optionally complete a brief survey answering if they are downloading an accessible copy to meet accessibility needs (Does this meet your needs. If not, why?)

[Mottie]

In a discussion with Michel about NOD E2E testing, he brought up some details about getting the status of a submission. Maybe we should consider adding the status of the application to the download page? Or at least a link to the Claim Status Tool with the status.

[saderagsdale]

@Mottie To make sure I understand correctly, are you recommending that we consider adding the status of the appeal the Veteran submitted to either the download page or CST?

[Mottie]

The status is already in the CST. I was just thinking it might be nice to include the status on this download page, since the Veteran will likely be coming back to the page some time after they submit the form. If we ultimately can only retain the form data for a month, then this page would not contain any useful information - data would be missing, and nothing to download.

[saderagsdale]

Ah, I see what you're saying. I think that is partly an assumption about how the user will interact with the page at a later time, and a question of what the experience looks like after our ability to retain data expires. @eileen-coforma thoughts?

[eileen-coforma]

@Mottie @saderagsdale It's an idea worth exploring once we validate our assumptions about how Veterans would want to use the page. We can consider it as we hash out the requirements after the study.

Julie linked a thread that mentioned there being a max retention period for submitted form data (which doesn't exist for forms not submitted). This could also influence the actions we want the Veteran to take when interacting with the page.

[saderagsdale]

@eileen-coforma @davidakennedy Moving DK's implementation note from the platform accessibility feedback ticket to this epic:

After our meeting Friday, exploring how PDFs are made via Lighthouse, I wanted to share some key aspects of accessible PDF creation and some potential software solutions.

Key Aspects of PDF Accessibility

1. Searchable text: The document is real text.
2. Document Language and Title Indication: It has a language and title so assistive technology users can read what the document is about.
3. Alternative Text Descriptions for Non-Text Elements: Any logos, images or decorative images need to be marked as much with proper alternative text so assistive technology users know what the image means.
4. Tagged Structure: PDF documents use tags, similar to HTML, to let assistive technology understand what the purpose of different types of text (heading, list item, etc.).

These are the basics of PDF accessibility, and where most PDF creation software gets it wrong. More details are covered in Adobe's guidance and WebAIM's guidance.

Possible Software

• PDFReactor
• Prince
• PDFKit

I don't think any of the above are perfect for our use case, but I still wanted to share them as what's good about them may help guide our choice in PDF library. A few more detailed thoughts on each of these:

• PDFKit uses JavaScript, Node and the browser. VA.gov uses it already for some frontend PDF generation.
• Prince and PDFReactor are paid libraries.
• I believe all of these can generate PDFs from HTML as well as edit an existing PDF.
• Prince has a number of wrappers available for different server side languages.

[saderagsdale]

Brian's Platform Accessibility feedback:

Feedback

Practice areas will document their feedback on the VFS-provided artifacts following the Must, Should, and Consider Framework. Platform reviewers may also provide additional notes that don’t comment on the artifacts themselves but are important for implementation (eg. engineering/coding notes).

• Consider: As I said in the touchpoint meeting, the benefits and challenges around PDFs all have to do with reputation. People tend to think of PDFs as being "official" and have a lot of trust in a downloadable PDF as a digital record of what they've done. But screen reader users encounter so many inaccessible PDFs that many of them just don't bother opening PDFs because their expectations have been so tainted.

  No way to win here, except to:

  1. Make the PDF as accessible as possible
  2. If possible, provide information in multiple data formats --- eg. available as a PDF download, but also available as a webpage you can visit, or as a .txt file you can download, or something like that.

  That may not be possible in the current iteration of what you're doing, but it's something to have on your radar and explore when you can.

• Must: The unfilled PDFs that get generated by VA's form generator are reasonably accessible. The challenge for the filled form will be ensuring that the data you're adding to the PDF is added so that a screen reader user is able to review their submission and hear everything in a sensible order, eg. the "First Name" field label, then their first name, then the "Last Name" field label, and so on. I don't know enough about the technical side of populating the PDFs to know how difficult that's going to be, so my best advice here is to try to get some sample filled forms generated as soon as possible so you have lots of time to test and decide if some other approach needs to be explored.

• Should: The watermark is tricky to implement accessibly, because you need to simultaneously:

  • Make the contrast ratio between the watermark text and the white background at least 3:1 (large text against background)
  • Make the contrast ratio between the form text and the watermark at least 4.5:1 (regular text against background)

  It's a pretty narrow color window to aim for, especially if you're just in grayscale. And those ratios are minimums for WCAG conformance, so you still might end up with something that's kind of difficult to read for some users even if you meet those contrast ratios. My advice would be to explore something other than a watermark, like a stamp in the top margin of each page that communicates what the watermark is intending to communicate. Overlapping text is just hard to do accessibly.

  • Conditional must: If you need to do a watermark anyway...
    • Make sure there's some kind of screen reader friendly text matching the watermark that's announced at the beginning of the document, so that it's the first thing screen reader users hear when opening the document.
    • If you're not able to find an accessible color combination, try to position the watermark to minimize how much text it obscures, and if it has to obscure text make sure it's form labels or instructions and not user submissions. At minimum we want to make sure users can review what they've entered, even if they can't read all of the instruction text again.
• Should: In the email notification, I think it would be good to include some kind of copy indicating that users may need to re-authenticate to download the PDF.

[eileen-coforma]

Updated epic details with updated feature specs and removed outdated specs. Keeping a copy of outdated specs in comments for tracking.

Specifications

1. User can click a link on the confirmation page to open the persistent page. Assumptions:

   • Users will gain value by being able to come back to this persistent page, thus the choice to NOT keep it in the confirmation page.
   • Users with accessibility needs will easily recognize that the accessible format is available and derive value from it.
   • This meets the needs of users with all kinds of accessibility needs. Open questions:
   • How do we let them know the page is accessible, re-visitable, and bookmarkable?
   • What is the UX experience when the Lighthouse PDF link expires?

2. User can click a link on the persistent page to download the standard PDF.

3. Page displays the following appeal data:

   • Name
   • Submission date
   • Personal information data
   • Issues for review data
   • Board review options data
   • Name of evidence files

4. User can return to the standard PDF link until it expires.

5. User can return to the persistent page indefinitely. Assumptions

   • User chooses to return to the persistent page

Open questions:

• How do we measure if they stored the accessible format? (what are the different design options for making that a measurable behavior?)
• How do we measure if someone returns to a persistent page?

7. User can store the information on the persistent page. Assumptions:
   • Users will click a button to download the accessible format.

Open questions:

• Where will this page live? (CAIA support)
• What will the URL be?
• How will we track usage?
• How can we track feedback from a11y users?
• What happens if a user submits multiple NODs?
• How long is the delay for the PDF link?

[eileen-coforma]

Submitted an experimental ticket: https://github.com/department-of-veterans-affairs/vets-design-system-documentation/issues/2767

[eileen-coforma]

Waiting on content review from CAIA. I made the mistake of giving this a lower priority, so I gave them to 5/21 latest due date.