Form526Submission Improvements

tblackwe commented 9 months ago

Rational

We currently have multiple means by which a submission may succeed or fail. E.g.

primary path submission
backup path submission
remediation

Even when we successfully complete one of these paths, we still often are in a limbo state where we require polling to finalize success of this submission avenue.

Having a bare minimum state machine would allow us to track

backup path submissions final status after LH (benefits intake API) status polling)
remediation status, e.g.
- sent for remediation
- accepted to vbms
duplicate submissions. most failed submissions in our database are duplicates. We need a way to tell future generatations "this was not successfully processed nor was it remediated, and that's ok because it's a duplicate of this submission, which holds the true state"
- note that this is a rudimentary stop gap. Ultimately we will want to prevent and / or purge these.

Abstract

Proposed states

pending
- the intial state of all submissions
- no further action required
success
- accepted via primary path
- no further action is required, this is a successful submission
failed
- primary path submission has failed
- more action is required
polling
- delivered to LH intake, but not yet marked as success (vbms) by LH intake.
- more action is required
accepted
- delivered to LH intake, marked as success
- no further action is required, this is a successful submission
rejected
- delivered to LH intake and marked error by LH intake
- more action required
undelivered
- failed backup path, ready to deliver to intake
- can only be reached via the backup path, implying primary failure as well
- more action required
remediated
- unopinionated about how it got here. Any submission can be manually transitioned to remediated from any other state.
- implies this has been sent down a path, but lacks final confirmation from VBMS of acceptance
- more action required
finalized
- remediated and accepted by VBMS.
- no further action is required, this is a successful submission

Proposed Database changes

form526Submission Table

add aasm_state
- this is a text field that holds one of a pretermined number of 'states'.
- allows us to easily track remediation and identify incomplete or needy submissions
add duplicate_of_id
- foreign key pointer to another form526Submission record that is the 'primary' record amongst a set of identified duplicates. presence here indicates a record is a duplicate.
- for MVP this will be manually populated after a human has reviewed a "duplicate" report and made a dermination that this is a duplicate.

Proposed Code Changes

add AASM state machine.
- validates state values for inclussion in list of acceptable states
- manages transitions, preventing accidental bad transitions
- provides helper methods
Add basic lifecycle changes
- add a default of pending to all submissions
- add transitions for
  - successful primary
  - successful backup
  - failed primary
  - failed backup

Ommissions

Polling

Eventually we will be adding a solution for tracking the final status of a successful submission to LH. This will most likely be automated polling. However, for MVP just having a way to track our manual weekly polling will be a massive leap forward.