[Tech Spec] Improve handling of BEAAM Appeals

[lowellrex]

Identify BEAAM Appeals in Code/Database

Drafter: Lowell Wood
Discussion Meeting:

Context

The Board’s Early Applicability of Appeals Modernization program (BEAAM or BEEAM) was a test program in the summer of 2018 to exercise the Board's business and technical processes for supporting AMA appeals prior to the full rollout of AMA in February 2019 (more details about BEAAM can be found in this guide for representatives).

Caseflow Queue and the Task system were in early development during summer 2018 so BEAAM appeals lack all the attributes that Caseflow now expects Appeal objects to have (various task types, associated documents, and so on). We occasionally run into issues (like this recent example) where Caseflow behaves in an unexpected manner because a BEAAM Appeal does not have all the attributes Caseflow expects of a post-AMA Appeal.

This tech spec exists to explore ways to more gracefully handle BEAAM appeals given the current expectations of the Caseflow application.

Goals

1. Create historical record of which appeals were part of BEAAM program
2. Enable application code to identify BEAAM appeals
3. Allow application to handle BEAAM appeals similar to how it handles all other appeals

Options

1. Create BEAAM wiki page

This option would have us add a page to this repository's wiki that describes the BEAAM program, lists which appeals in the Caseflow database were part of the BEAAM program, articulates how those BEAAM appeals differ from post-AMA appeals, outlines the type of difficulties we face when processing BEAAM appeals in the current Caseflow application code, and describes how to resolve those difficulties.

This option does not satisfy all of the goals of this tech spec, but involves a low amount of effort and no changes to the existing codebase.

1. ✅ Create historical record of which appeals were part of BEAAM program
2. ❌ Enable application code to identify BEAAM appeals
3. ❌ Allow application to handle BEAAM appeals similar to how it handles all other appeals

2. Create beaam_appeal_records table

This option would have us add a new beaam_appeal_records table to the database that links to the existing appeals with one row for each of the 24 BEAAM appeals in the database (IDs confirmed most recently on 19 July 2021 by searching for Appeals created in August 2018 or earlier). We could add a beeam? method to the Appeal class that returns a boolean based on whether a BeaamAppealRecord exists for that appeal. We could use this method to add notes to our task tree views, badges to case details pages, and indicators anywhere else we view appeals to make us aware that this appeal is different from standard AMA appeals in some ways. We could also use this method to adjust behavior within the application itself, preventing actions that should not be available to BEAAM appeals or that might raise an error if an appeal with an incomplete task tree (as BEAAM appeals often have) is subjected to the action.

This option does not satisfy all of the goals of this tech, but involves relatively few code changes and data additions and does not make any changes to existing data.

1. ✅ Create historical record of which appeals were part of BEAAM program
2. ✅ Enable application code to identify BEAAM appeals
3. ❌ Allow application to handle BEAAM appeals similar to how it handles all other appeals

3. Backfill missing data for BEAAM appeals

This option would have us manually create the data we expect AMA appeals to have in the database but that BEAAM appeals do not have (task trees, decision documents, hearing dates, etc.). We've backfilled missing data for BEAAM appeals before (see this thread for examples) so we have an existing pattern we can follow for this work.

This option does not satisfy all of the goals of this tech spec, but will result in the application being able to properly handle BEAAM appeals without any changes to the codebase or additional database tables.

1. ❌ Create historical record of which appeals were part of BEAAM program
2. ❌ Enable application code to identify BEAAM appeals
3. ✅ Allow application to handle BEAAM appeals similar to how it handles all other appeals

Additional considerations

BEAAM was just one of two early access programs for the AMA functionality so we may eventually want to do something similar for RAMP decision reviews (the other program).

Research Notes

• BEAAM Representative Packet
• The Board's one-pager on BEAAM and RAMP posted on VA.gov

Tech Spec Process

• Tech spec drafter: Schedule time to discuss the tech spec with scrum team or whole engineering team depending on the scope of the tech spec
• Tech spec drafter: Facilitate that discussion.
• Other developers: Read the tech spec before arriving at the discussion.
• Other developers: Remind the tech spec drafter if a tech spec has been produced and no meeting has been scheduled.
• One or more solutions determined as viable paths forward
• Tech spec drafter: Turn tech spec into next-step actionable tickets.
  • Write tickets as is necessary
  • Other developers provide more formal feedback as is necessary.
• Once the tech spec is finalized, open a PR to add it to the docs/tech-specs directory following these instructions

[yoomlam]

Created a wiki page for BEAAM appeals: https://github.com/department-of-veterans-affairs/caseflow/wiki/BEAAM-Appeals