Skip to content

Intake Data Model

Jump to bottom
YANG YANG edited this page Jun 19, 2020 · 17 revisions

Intake Data Model

This is a brief tour of the commonly seen models within Intake. Each model has a short description of what it represents, how it relates to other models, and a few of its most useful methods.

While there is ample room for improvement, this page is by design an incomplete documentation of the data model. There are far too many models and methods to list exhaustively, and in this format, staying in sync with the codebase is infeasible. However, the intention is that by mentioning the most frequently employed ones, this document can still be a useful introduction to Intake and a cheatsheet when working with the models.

The page is divided into thematic groupings:

  1. Humans of Intake
  2. Intakes and Reviews
  3. Ratings and Request Issues
  4. VBMS and End Products
  5. Decisions
  6. Decision Review Tasks

Humans of Intake

The Person, Veteran, and Claimant models represent various ways in which veterans, and people acting on behalf of veterans, participate in the AMA process. These objects are stored as records in the Caseflow DB and correspond to records in BGS and VBMS via the participant_id value. A participant is intended to represent one human.

Person

  • participant_id - a unique key in BGS/CorpDB
  • claimants - list of reviews this person is a claimant on
  • date_of_birth
  • name
  • first_name
  • last_name

Veteran

A Veteran object represents the fact that a Person was previously in the military and is entitled to VA benefits and support. Nearly all data models in the Caseflow process are associated with a veteran, although initially the actual Veteran record may not have been persisted to Caseflow DB from BGS yet.

  • participant_id
  • end_products - fetch EndProducts from BGS by veteran file number
  • file_number - a unique identifier in Caseflow DB and BGS. It's possible that occasionally two file numbers refer to the same human in reality, and get merged in BGS -- we don't handle this very well yet.
  • person - the Person backing this veteran
  • ratings - fetch every Rating for this veteran from BGS

Claimant

A Claimant is an instance of a person's being listed as a claimant on a DecisionReview, and may or may not be the same person as the veteran. A person can be a claimant on multiple decision reviews, in which case they would have a Claimant record for each review.

  • decision_review
  • participant_id
  • payee_code - required when the review is processed in VBMS
  • person - the Person object backing this claimant
  • delegated to person: date_of_birth, name, first_name, last_name

User

A user of the Caseflow app. In the context of Caseflow Intake, often a Claims Assistant (CA) performing mail intake.

  • css_id - a unique key

Intakes and Reviews

Intake

An Intake is the processing of a form sent in by (or on behalf of) a veteran, to kick off the entire AMA process. In order to prevent the risk of duplicate work, multiple users cannot perform intake for the same type of form, although intakes expire after 24 hours.

There are two types of intake:

  1. AMA Decision Reviews. The AMA process specifies three decision review lanes: Supplemental Claims, Higher Level Reviews, and Board Appeals. The intake flows for the three lanes are very similar.
  2. RAMP (Rapid Appeals Modernization Program) Reviews. RAMP was an early pilot of the AMA process that allowed a veteran to convert their legacy appeal into a ClaimReview.

DecisionReview

Abstract superclass of ClaimReview (either a SupplementalClaim or a HigherLevelReview) and Appeal. Each of the three concrete subclasses corresponds to one "lane" of the AMA process. One other aspect with significant ramifications on the flow of logic is whether or not the review is processed in Caseflow; for non-Appeals, certain lines of business depend extensively on VBMS.

During the intake process, a DecisionReview must get at least one RequestIssue added to it.

  • claimants - Currently AMA only supports one claimant per decision review.
  • decision_issues
  • intake
  • legacy_opt_in_approved - whether the legacy opt-in check-box was selected on the intake form
  • processed_in_caseflow? - All Appeals, and ClaimReviews that are not compensation or pension are processed in Caseflow.
  • processed_in_vbms? - All compensation and pension ClaimReviews are processed in VBMS.
  • receipt_date - Date the form was received. Determines which issues are eligible to be contested. Note that SupplementalClaims don't have the same timeliness restriction as Appeals and HigherLevelReviews.
  • request_issues
  • request_issues_updates
  • uuid - a public unique identifier for this review, e.g. in Caseflow URLs
  • veteran

ClaimReview

Abstract superclass of SupplementalClaim and HigherLevelReview, subclass of DecisionReview. A claim review is not sent to the Board of Appeals. The benefit type (i.e. line of business) is specified on the form and determines whether the review is processed in VBMS (compensation and pension) or not.

  • benefit_type - The line of business specified on the form. Current allowed values: compensation, pension, fiduciary, insurance, education, voc_rehab, loan_guaranty, vha, nca.
  • end_product_establishments
  • inherited from DecisionReview: claimants, decision_issues, intake, processed_in_caseflow?, processed_in_vbms?, receipt_date, request_issues, request_issues_updates, veteran

HigherLevelReview

Subclass of ClaimReview. A non-appeal AMA review filed to receive a re-examination of existing evidence by a higher-level adjudicator.

  • remand_supplemental_claims - list of any supplemental claims auto-created from this review being remanded
  • inherited from ClaimReview: benefit_type, end_product_establishments
  • inherited from DecisionReview: claimants, decision_issues, intake, processed_in_caseflow?, processed_in_vbms?, receipt_date, request_issues, request_issues_updates, veteran

SupplementalClaim

Subclass of ClaimReview. A non-appeal AMA review filed with new evidence relevant to the veteran's case. Supplemental reviews may be automatically generated from a remand decision on a higher level review or an appeal.

  • decision_review_remanded - If this SupplementalClaim was generated from a remand, the original Appeal or HigherLevelReview that was remanded.
  • inherited from ClaimReview: benefit_type, end_product_establishments
  • inherited from DecisionReview: claimants, decision_issues, intake, processed_in_caseflow?, processed_in_vbms?, receipt_date, request_issues, request_issues_updates, veteran

Appeal

Subclass of DecisionReview, representing an AMA review sent to the Board of Appeals. All AMA appeals are processed in Caseflow.

  • decision_documents - only one per Appeal, until post decision motions are supported
  • remand_supplemental_claims - list of any supplemental claims auto-created from this review being remanded
  • inherited from DecisionReview: claimants, decision_issues, intake, processed_in_caseflow?, processed_in_vbms?, receipt_date, request_issues, request_issues_updates, veteran

LegacyAppeal

A LegacyAppeal represents an appeal in the pre-AMA system. The growing backlog of legacy appeals was the primary impetus for AMA which, in addition to creating the 3 new DecisionReview lanes, also allows a legacy appeal to be opted-in as an AMA DecisionReview. Legacy appeals are stored in VACOLS, and do not necessarily have a corresponding LegacyAppeal record in Caseflow.

  • case_record - a VACOLS::Case object representing the underlying VACOLS record
  • issues - a list of legacy issues associated with this appeal
  • vacols_id - primary key for this appeal within VACOLS, and a public identifier e.g. in Caseflow URLs.

RampReview

Abstract superclass of RampElection and RampRefiling.

Ratings and Request Issues

Rating

A rating is a structured representation of a VA decision -- in a sense, a legal document with an effective date, containing one or more rating issues. The rating profile of a veteran is the cumulative total of their ratings, which can be thought of as point-in-time diffs.

The Rating model encapsulates a veteran's rating profile as well as the most recent rating and its updated issues. Rating issues are often what veterans contest, and a decision in the review process may come in the form of a new rating and rating profile.

  • participant_id
  • profile_date - The datetime (not date!) this rating was decided; participant_id and profile_date form a compound primary key in BGS.
  • associated_end_products - Applicable to reviews processed in VBMS. Only includes EPs that have actually been created.
  • decisions - A list of RatingDecisions, if there are any disability issues on this rating. The feature toggle contestable_rating_decisions must be on, or this will return [].
  • issues
  • promulgation_date - the date this rating legally went into effect

RatingIssue

A specific assertion on a veteran's rating profile, which they may disagree with. A rating issue will often supercede another on the same issue, from an older rating. The most common kinds are disability issues, e.g. "Service Connection for Lower Back disability is granted at 70%".

When intaking a form for compensation or pension benefits, the intake user will see all rating issues for the veteran, and try to match them with issues written on the form. Once identified, a rating RequestIssue gets created and added to the review.

Business lines other than compensation and pension don't use rating issues, so any rating issues on the form would have to be added as an unidentified issue.

  • reference_id - primary key in BGS
  • benefit_type - either compensation or pension
  • contention_reference_ids - list of contention IDs that this issue matches. The many-to-many relationship between rating RequestIssues and their subsequent DecisionIssues is based on this matching.
  • decision_text

RequestIssue

An atomic unit of disagreement with a prior VA decision. The original issue may be a rating issue, a non-rating issue, or an unidentified issue. All three types of RequestIssues are stored in the same table, but behave differently depending on the fields that determine the type.

  1. Rating RequestIssues correspond to RatingIssues.
  2. Non-rating RequestIssues are more unstructured; we store just the category, decision date, and a description. The set of valid categories depends on the benefit type (line of business).
  3. Unidentified RequestIssues are issues where the intake user isn't sure which rating issue is being contested. Each should be resolved downstream (by a user clicking "Edit in Caseflow") and replaced with a rating RequestIssue, or else will be considered ineligible to be decided on. Currently, these occur often because older rating issues are missing from the upstream database.

A RequestIssue can be connected to a legacy VACOLS issue, but is only eligible if the veteran checks the SOC/SSOC box to withdraw it from the legacy appeals process and opt-in to AMA.

Note that some of the methods on RequestIssue are only applicable in certain situations, e.g. Contention-related methods for reviews processed in VBMS.

  • benefit_type
  • contention - the VBMS contention corresponding to this issue, if it has been created
  • contention_disposition - the disposition of this issue's contention if it has one yet
  • contention_reference_id - the ID of the VBMS contention corresponding to this issue, populated after the EP and contention are created
  • contested_decision_issue - a DecisionIssue, if contesting one
  • contested_rating_issue - fetch a RatingIssue from BGS, if contesting a rating issue
  • contested_rating_issue_reference_id - a RatingIssue reference ID, if contesting a rating issue
  • decision_date - Date of the RatingIssue or DecisionIssue being contested, or a date entered by the user. Even if this is an unidentified issue, the date may help determine which issue it should be matched to.
  • decision_issues - list of DecisionIssues providing resolution to this request issue (many-to-many relation)
  • decision_review
  • decision_sync_error - error message describing why this issue failed to create a DecisionIssue, if applicable
  • end_product_establishment - the EPE if this is a ClaimReview processed in VBMS. Note: this may also be nil if the issue is ineligible.
  • ineligible_due_to - a prior RequestIssue that caused this issue to be ineligible, if applicable
  • ineligible_reason - if ineligible, a string identifier for the reason this issue is ineligible
  • is_unidentified[?] - whether this is an unidentified request issue
  • legacy_issue_opted_in?
  • matching_rating_issues - for a VBMS issue, a list of RatingIssues on the decision that decide this particular issue
  • nonrating? - whether this is a non-rating request issue
  • nonrating_issue_category
  • rating? - whether this is a rating request issue
  • vacols_id
  • vacols_issue - the connected legacy issue, if the VACOLS id and sequence id are set
  • vacols_sequence_id
  • veteran_participant_id
  • delegated to decision_review: veteran

RequestIssuesUpdate

A RequestIssuesUpdate represents a change to a decision review, consisting of additions, removals, edits, withdrawals, and corrections of RequestIssues.

  • review
  • user - the user who initiated this update
  • before_issues
  • after_issues
  • removed_issues - collection of issues that appear in the before list but not in the after list
  • withdrawn_issues
  • removed_or_withdrawn_issues
  • corrected_issues - issues that need updating after the corresponding EP has already cleared

Issue

An Issue is an ephemeral object that represents a legacy issue stored in VACOLS.

  • close_date
  • disposition - a snake_case symbol representing the issue's disposition, e.g. allowed, remanded, denied, ama_soc_ssoc_opt_in, etc
  • disposition_id - VACOLS code determining the issue's disposition. See this file for the mapping to human-readable values.
  • disposition_date
  • legacy_appeal
  • vacols_sequence_id

VBMS and End Products

EndProduct

When completing an intake for a ClaimReview processed in VBMS, or finalizing DecisionIssues, Caseflow creates one or more end products (EPs) in VBMS. Because EP creation is asynchronous and complex, Caseflow stores and deals with EndProductEstablishments (EPEs).

EndProduct is an ephemeral model used when interacting with VBMS, and end_product.rb is the canonical document for understanding the specifics of this interaction. It is possible to instantiate an EndProduct object before the EP is actually created in VBMS, for the purposes of working with EP-related logic (although this usually lives in the EPE).

  • claim_id - a unique identifier in VBMS, which is stored as the EPE's reference_id, or nil if EP doesn't exist yet
  • claim_type_code - the main source of information about what this EP is, stored as the EPE's code
  • contentions - fetch a list of this EP's contentions from VBMS, or nil if it doesn't exist yet. The resulting elements are instances of VBMS::Responses::Contention.
  • bgs_contentions - fetch a list of this EP's contentions from BGS, which may be empty if doesn't exist yet

EndProductEstablishment

An EPE is a Caseflow model and abstraction layer over the fact that we need to work with or reason about an EP that may not actually exist in VBMS yet (conceptually: a Promise, with many other capabilities).

For VBMS-processed reviews, when an EP is "cleared" (completed) we load its new rating issues and dispositions, and use these to create DecisionIssues.

The process of syncing decision issues may trigger further EPs, e.g. in the case of duty-to-assist (DTA) errors, the remand automatically generates a SupplementalClaim with an EP 040.

  • associated_rating - A new Rating that provides a decision on the rating RequestIssues associated with this EPE (if applicable). Fetched from BGS.
  • bgs_contentions - fetch a list of contentions on the EP from BGS, if it has been created
  • claimant_participant_id
  • code - EP code, containing lots of information about the EP being established
  • contentions - fetch a list of contentions on the EP from VBMS, if it has been created
  • end_product - alias for result
  • established_at
  • reference_id - the VBMS identifier (claim_id) of the established EP
  • request_issues
  • result - the established EP, fetched from BGS, or nil if reference_id isn't set yet
  • source - a ClaimReview or a DecisionDocument
  • synced_status - non-comprehensive list of values: CAN (canceled), CLR (cleared), PEND (pending), PW (ready to work)
  • user
  • veteran
  • veteran_file_number

Contention

A contention is a VBMS entity corresponding to a RequestIssue, attached to an EP. Contentions eventually get dispositions in VBMS, which are loaded by the EPE and accessible via the original RequestIssue or a newly created DecisionIssues.

Note that the Contention class in the Caseflow codebase is only used to manage string processing operations for contentions' description text. In this document, a contention fetched from VBMS (e.g. returned by EndProduct#contentions) is actually an instance of VBMS::Responses::Contention.

BgsContention

A BgsContention represents the same underlying record as a VBMS::Responses::Contention, but is fetched from BGS rather than VBMS. Used to determine whether a contention has an exam scheduled.

RequestIssueContention

An ephemeral class for managing the work between a RequestIssue and its Contention.

Decisions

DecisionDocument

A document created by the Board when it has made a decision on an appeal. Attorneys create DecisionIssues, which in turn create EPs to notify relevant people and systems at the original branch (only for lines of business that use VBMS).

DecisionIssue

A specific VA decision on an AMA DecisionReview. DecisionIssues have a many-to-many relationship to RequestIssues.

A rating-associated decision issue will always map to a single rating issue. However, multiple request issues may be decided by the same rating issue; in this case, multiple decision issues are created only when the request issues have different dispositions.

For Board Appeals, decision issues are created by Board attorneys.

BoardGrantEffectuation

Represents the work item of updating records for a granted DecisionIssue on a Board appeal.

Decision Review Tasks

Caseflow supports multiple lines of business (LOB) within the VA. During Intake, it is possible to select a LOB based on the Benefit Type selected for the Decision Review and/or Non-Rating Request Issue.

Pension and compensation reviews are administered via VBMS. When a LOB is selected that is not administered via VBMS, Caseflow creates tasks that each business line must process. These are available via the /decision_reviews/:business-line:/ endpoint. The Task model is used with the same status categories as for Caseflow Queue with the one exception that DecisionReviewTask instances do not have a parent RootTask. They are not part of the Queue task tree. To locate the relevant tasks for a given LOB, you would use SQL similar to:

SELECT * FROM tasks
WHERE assigned_to_id IN (SELECT id FROM organizations WHERE url = 'vha')

or Ruby like:

vha = BusinessLine.find_by url: 'vha'
vha.tasks.open # returns array of open tasks that inherit from DecisionReviewTask
Clone this wiki locally