Appeal State Tracking - department-of-veterans-affairs/caseflow GitHub Wiki
Overview
We are tracking the current state of appeals. The state of an appeal would be where in the process the appeal is in or the most recent action made on to the appeal.
States and Triggers
Appeal Cancelled - The appeal has all of its issues removed and the root task has been cancelled.
Appeal Docketed - The appeal has been docketed meaning it has a Distribution Task in the task tree. For Legacy Appeals it requires the Case to have a BFCURLOC (location code) of "01" for it be considered docketed.
Decision Mailed - The decision document for the appeal got processed and the notification got sent out to the appellant.
Hearing Postponed - The most recent hearing for hearing has been postponed which means the hearing disposition has been set to postponed.
Hearing Scheduled - A hearing for the appeal has just been scheduled which means the hearing disposition has been set to nil.
Hearing Withdrawn - The most recent hearing for the appeal has just been withdrawn or cancelled which means the hearing disposition has been set to cancelled.
Scheduled In Error - The most recent hearing for the appeal has been cancelled because there was an error in scheduling which means the hearing disposition has been set to scheduled in error.
Privacy Act Pending - The appeal is in a privacy act pending state which means at least one of the privacy act related tasks is still in an opened status.
Privacy Act Complete - The appeal is in a privacy act completed state which means all privacy related tasks are in a complete status.
VSO IHP Pending - The appeal is in a VSO IHP Pending state which means the most recent VSO IHP Organizational task in the task tree is in an opened state.
VSO IHP Complete - The appeal is in a VSO IHP Completed state which means the most recent VSO IHP Organizational task in the task tree is in a completed state.
Tables
Appeal State Table
appeal_states table - Initial table keeping up with all statuses pertaining to appeals. This is the one in the “One to Many relationship with these appeal_states_audit_table
appeal_type - type of appeal data type is a string. This will be 1 of 2 choices, “Appeal” or “Legacy Appeal”.
updated_by_id - This keeps track of the last person that updated the appeal. Data type is an integer. This will be the foreign key associated with the user that updated the appeal.
updated_at- If the Appeal is ever updated after the initial creation this will update the date. Data type is a timestamp in “String” form.
created_at - Will create a timestamp upon appeal creation. Data type is a string.
created_by_id - Keeps a record of which user created the appeal. This will be a foreign key that is unique to the specific user. Data type is an integer.
appeal_docketed - Keeps track of appeals that have been moved to docketed. The value is a Boolean.
privacy_act_pending - Keeps track of whether or not at least one privacy related task is assigned, in progress, on_hold or not. If it is the value will be “true”. Data type is a Boolean.
privacy_act_complete - Keeps track of whether or not all of the privacy related tasks have been completed or not. If it is the value will be "true". Data type is a Boolean.
ihp_task_pending - Keep track of whether or not the most recent IHP task is assigned, in progress, on_hold or not. If it is the value will be "true". Data type is Boolean
ihp_task_complete - Keep track of whether or not the most recent IHP task is completed or not. If it is the value will be "true". Data type is Boolean
hearing_scheduled - Will indicate whether a hearing has been scheduled or not. If it has been scheduled the value will be “true”. If it has not been scheduled, postponed or has been withdrawn it will be “false”. Data type is a Boolean.
hearing_postponed - Keeps track on whether or not the hearing disposition is postponed or not. Data type is a Boolean.
hearing_withdrawn - Keeps track on whether or not the hearing disposition is cancelled or not. Data type is a Boolean.
decision_mailed - Keeps track on whether or not the appellant has gotten a notification sent out. Data type is Boolean.
appeal_cancelled - Indicates if an appeal has been cancelled or not based on if there are any issues and the root task has been set to cancelled. Data type is a Boolean.
scheduled_in_error - Keeps track on whether or not the hearing disposition is scheduled_in_error or not. Data type is a Boolean.
Appeal Audit Table
appeal_states_audit table – “Paper Trail” table keeps track of all users that make any changes to any appeals. This is the many in the one to many. Each time an appeal is changed or updated, this will keep a record of who made the change. This table is the first to be housed in a schema called caseflow_audit. It has rows automatically added to it via a trigger on the appeal_states table in the public schema.
appeal_state_id - Primary key. Data type is autoincremented integer.
type_of_change - this will be the type of change that was made to the corresponding appeal. Data type is a “String” and has one of these, "I" for insert, "U" for update and "D" for delete
appeal_id - id of the appeal that this record is associated with. This data type is an integer.
appeal_type - Type of appeal data type is a string. This will be 1 of 2 choices, “Appeal” or “Legacy Appeal”.
updated_by_id - This keeps track of the user that updated the appeal with this time stamp related to the associated appeal. Data type is an integer. This will be the foreign key associated with the user that updated the appeal.
updated_at- If the Appeal is ever updated after the initial creation this will update the date. Data type is a timestamp in “String” form.
created_at - Will create a timestamp upon appeal creation. Data type is a timestamp in “String” form.
created_by_id - Keeps a record of which user created the appeal. This will be a foreign key that is unique to the specific user. Data type is an integer.
appeal_docketed - Keeps track of appeals that have been moved to docketed. This means the appeal has been placed into a queue to begin the workflow for the appeal. Data type is a Boolean with a value of “true” or “false”.
privacy_act_pending - keeps track of whether 1 of 5 privacy act tasks have been completed. Only 1 has to be completed the Data type is a Boolean and will hold a value of “true” or “false”. “true” if the task is pending and “false” if it is complete.
privacy_act_complete - keeps track of whether 1 of 5 privacy act tasks have been completed. Only 1 has to be completed the Data type is a Boolean and will hold a value of “true” or “false”. “true” if the task is complete and “false” if it is incomplete.
ihp_task_pending – Keep track of whether or not the most recent IHP task is assigned, in progress, on_hold or not. If it is the value will be "true". Data type is Boolean
ihp_task_complete – Keep track of whether or not the most recent IHP task is completed or not. If it is the value will be "true". Data type is Boolean
hearing_scheduled – Will indicate whether a hearing has been scheduled or not. If it has been scheduled the value will be “true”. If it has not been scheduled, postponed or has been withdrawn it will be “false”. Data type is a Boolean and the value will be either “true” or “false”.
hearing_postponed – Keeps track on whether or not the hearing disposition is postponed or not. Data type is a Boolean.
hearing_withdrawn – Keeps track on whether or not the hearing disposition is cancelled or not. Data type is a Boolean.
decision_mailed – Keeps track on whether or not the appellant has gotten a notification sent out. Data type is Boolean.
appeal_cancelled – Keeps track of appeals that have been cancelled. The value is a Boolean.
scheduled_in_error - Keeps track on whether or not the hearing disposition is scheduled_in_error or not. Data type is a Boolean.
One Time Migration
Two jobs called fetch_all_active_ama_appeals_job and fetch_all_active_legacy_appeals_job are going to run and they will be fetching all of the active appeals and manually mapping the current states of those appeals on to the appeal states table by creating the records and setting them as opposed to it being trigger based.
The amount of appeals that it fetches depends on a configurable ENV variable called STATE_MIGRATION_JOB_BATCH_SIZE which is used for limiting the batch size of how many appeals will get queried.
If there an error it will get handled by catching the error and then logging it an OpenStruct object with the appeal_type, appeal_id, error, error_message, and backtrace. The objects will get grouped into an array which will get built into a CSV and then uploaded into an S3 bucket.
"ama-migration-Year-Month-Day--Hour-Minute.csv" filename will follow this format and will replace "ama" with "legacy" for the appropriate job
Quarterly Notification Statuses
| >= One Hearing Scheduled? | >= One Privacy Act Pending? | >= One IHP Pending? | >= One Scheduled in Error? | >= One Hearing Postponed? | >= One Hearing Withdrawn? | Appeal is Docketed? | Appeal Status |
|---|---|---|---|---|---|---|---|
| yes | yes | Hearing Scheduled / Privacy Act Pending | |||||
| yes | no | Hearing Scheduled | |||||
| no | yes | yes | no | no | no | VSO IHP Pending / Privacy Act Pending | |
| no | yes | no | no | no | no | Privacy Act Pending | |
| no | no | yes | no | no | no | VSO IHP Pending | |
| no | no | no | no | no | no | yes | Appeal Docketed |
| no | no | no | no | no | no | no | There will be no appeal status in this situation because appeal will be in a pre-docketed state |
| no | yes | yes | yes | Hearing to be Rescheduled / Privacy Act Pending | |||
| no | yes | yes | no | Hearing to be Rescheduled / Privacy Act Pending | |||
| no | yes | no | yes | Hearing to be Rescheduled / Privacy Act Pending | |||
| no | no | yes | yes | Hearing to be Rescheduled | |||
| no | no | yes | no | Hearing to be Rescheduled | |||
| no | no | no | yes | Hearing to be Rescheduled | |||
| no | no | no | yes | Appeal Docketed |