Intake Batteam Training - department-of-veterans-affairs/caseflow GitHub Wiki
How to use this document
This document provides an overview of Intake's functionality from a technical point of view, with inline code to help investigate, diagnose, and resolve issues for the Batteam.
Shorthand abbreviations are used to stand for different objects in code snippets, for example an EndProductEstablishment may be referred to as epe. Multiple EndProductEstablishments may be referred to as epes.
Strategies for batteam
- First review the Caseflow data related to the issue
- If this is due to a known, unresolved issue, such as an upstream error, link the GitHub Issue for Support
- Also check BGS and VBMS data to see if there are unexpected discrepancies
- If the app behaved as expected, the user may need an explanation
Primary Models of interest and shorthand
- Veteran (v)
- User (u)
- Intake (i)
- DecisionReview (dr)
- EndProductEstablishment (epe)
- RequestIssue (ri)
- RequestIssuesUpdate (riu)
- DecisionIssue (di)
- BoardGrantEffectuation (bge)
- LegacyIssueOptin (lio)
Please see Intake Data Model for more details
Getting started
Data provided by support:
- User CSS_ID
- Veteran ID
- Decision Review Type
- Decision Review UUID
- End Product / Claim ID
Finding an Intake
Finding the Intake is often not necessary, but if you only have a user's CSS_ID, it can be a useful place to start.
u=User.find_by(css_id: css_id)
# Any intake with a completion_status of "success" will have a "detail".
# A detail can either be a RAMP review, or an AMA Decision Review
is=Intake.where(user_id: u.id, completion_status: "success")
# If you know the type of decision review or the veteran ID, you can narrow it down even more
Intake.where(user_id: u.id, detail_type: "HigherLevelReview", veteran_file_number: v.file_number)
# From the intake, you can get the decision review by calling detail
i.detail
Finding a Decision Review
Given a Veteran ID
Often in Batteam, we are given the veteran ID: https://appeals.cf.ds.va.gov/search?veteran_ids=477226
v=Veteran.find(477226)
# From there, if you know the Decision Review Type, you can try to find the Intake or Decision Review
is=Intake.where(veteran_file_number: v.file_number)
hlrs=HigherLevelReview.where(veteran_file_number: v.file_number)
scs=SupplementalClaim.where(veteran_file_number: v.file_number)
as=Appeal.where(veteran_file_number: v.file_number)
Given a UUID
Sometimes we get the actual UUID and Decision Review Type from an edit URL: https://appeals.cf.ds.va.gov/supplemental_claims/a8e27ef6-6776-4138-b848-cce9348ac452/edit
hlr=SupplementalClaim.find_by(uuid: "a8e27ef6-6776-4138-b848-cce9348ac452")
Given a Claim ID
If you are provided with a claim_id, or an end product's ID, you can first try to find the End Product Establishment:
epe=EndProductEstablishment.find_by(reference_id: 1234567)
# Look at the epe.source_type to find out what kind of End Product it is for
# For HigherLevelReview and SupplementalClaim you can get the decision review from:
dr=epe.source
# If the source is a DecisionDocument, you can get the Appeal like:
a=epe.source.appeal
Finding a veteran
If you have an Intake, DecisionReview, or EndProductEstablishment, you can easily get to the veteran.
v=i.veteran
v=dr.veteran
v=epe.veteran
Finding a RequestIssuesUpdate
If there is a problem with the Edit screen, a good place to start is looking at the Decision Review's updates:
rius=RequestIssuesUpdate.where(review_type: dr.class.name, review_id: dr.id)
What to look at next
Once you have a decision review, where you go depends on the problem reported in Batteam.
Problem with an end product
First find the end product establishment:
epes=dr.end_product_establishments
If there is no end product establishment
If there is no end product establishment, then check if there were any eligible request issues that would be processed in VBMS. If there are no eligible issues, then no EPE is created.
dr.request_issues.map(&:ineligible_reason)
If an End Product Establishment is found
If the epe has a reference_id, then it has been established in VBMS. You can look at the actual End Product data from BGS:
ep=epe.result
# This allows you to compare the EPE to the EP, such as if the status, and the epe.code and ep.claim_type_code matches
If the End Product is not established:
# If the epe does not have a reference_id, then it has not yet established. You should be able to see an error message for why.
# You can check the decision review:
dr.establishment_processed_at
dr.establishment_error
# How to reattempt a Decision Review with an error:
DecisionReviewProcessJob.new.perform(dr)
# If the Decision Review was successfully established, you can try looking at RequestIssuesUpdates for that Decision Review
rius=RequestIssuesUpdate.where(review_type: dr.class.name, review_id: dr.id)
riu.processed_at
riu.error
# Reattempting a riu happens the same way:
DecisionReviewProcessJob.new.perform(riu)
For End Products that have failed to establish, we keep track of the upstream errors with the upstream-error label. If these are ongoing issues we are trying to resolve with external stakeholders, they are in the Icebox column. If they are in a regular engineering column, then it's something we have engineering work to do on.
Problem with an issue
The life of an issue: Prior decision -> Request Issue on AMA form -> New Decision
Prior decisions
In order for an issue to be added as a request issue to an AMA Decision Review, it should first have a prior decision.
To see prior decisions that we know about:
dr.contestable_issues
Nonrating issues
If the issue is a nonrating issue and it has not yet been through AMA then we do not have access to prior decision data for it and raw data needs to be entered by the user.
The user will enter:
- A description
- A category
- A decision date
Once the issue has an AMA decision, then that decision becomes a contestable issue in the future.
Rating issues
We get data for prior decisions on rating issues from BGS.
rs=v.ratings
# You can look at the issues on a rating with:
r=rs.first
is=r.issues
These are saved with the rating issue reference ID in Caseflow.
Unidentified issues
If an issue is a rating issue, and it's not showing up, the user can add it as an unidentified issue. These have the is_unidentified flag set to true. This is currently what users should do if the rating issue is missing.
Request issues
Once an issue is added to a decision review, it becomes a request issue. Some of these are closed immediately due to ineligibility (see ri.ineligible_reason).
If a request issue is processed in VBMS, it will have an EPE:
ri.end_product_establishment
Contentions
If a Decision Review is processed in VBMS, a contention will be added to the End Product representing the request issue.
# If the contention still exists, you can look at the VBMS data for it with this:
ri.contention
Editing a contention
Contention text can be edited in the Caseflow UI. If so, they will have an edited_description. If this has been successful, contention_updated_at will be populated.
This is done through RequestIssueContention.
Deleting a contention If a request issue is removed from a Decision Review, the contention is removed. This is also done through RequestIssueContention.
If successful, contention_removed_at will be populated.
Deleting a contention can fail if the contention is in the process of being decided and is connected to a new rating issue. It can also fail if the contention has an exam scheduled.
Previously, contention removal would also fail if the text was not populated in VBMS. Hopefully these are being prevented now. If you notice the ri.contention.text is blank, and a user is trying to remove it, it can be removed with:
c=ri.contention
c.text = "something nonblank"
VBMSService.remove_contention!(c)
After manually removing a contention, it would be good to run the RequestIssuesUpdate again to ensure all other actions have happened.
riu.perform!
If the veteran has a locked rating, which means there's a rating that is actively being worked on, we are not able to fetch it. We detect these if the rating that a request issue is associated with does not show up in the veteran's ratings when we fetch them from BGS. If a rating connected to a request issue is locked, it is presumed that the contention may have a new rating issue associated to it, so removal is prevented.
To see if a request issue might have a rating issue (if it's not locked):
ri.end_product_establishment.associated_rating
Currently, we do not detect if a contention has an exam scheduled, but accounting for this is planned.
If an End Product has no more contentions on it, because all of the issues have been removed, the End Product gets cancelled. Therefore, if manually removing a request issue, it is best to do it through RequestIssuesUpdate.
Decision issues
Once a request issue's End Product is cleared, we start pinging VBMS and BGS to see if there's a decision issue. For nonrating issues, the request issue only needs to have a contention_disposition:
ri.contention_disposition
For rating issues, they must have both a contention disposition, and a new rating issue.
ri.matching_rating_issues
Once these conditions are met, then decision issues are created. They can be accessed through:
ri.decision_issues
If these conditions ARE met, but there is no decision issue, then the job may have expired. To re-attempt, try:
ri.sync_decision_issues!
Remand Supplemental Claims
If an issue gets a remanded disposition - remanded, DTA error, or Difference of Opinion, then we automatically generate a Supplemental Claim contesting that decision. These are called Remand Supplemental Claims.
In order for a remand supplemental claim to be created, the original review must have decision issues, and at least one of them needs to have one of those types of dispositions.
From the original review:
# Check if there are remand supplemental claims
dr.remand_supplemental_claims
# If not, check the decision issues
dr.decision_issues
dr.decision_issues.map(&:disposition)
If there are not decision issues with a remanded disposition, please see the Decision Issues section to check if the request issue has met the required conditions for getting a decision issue. If so, you can try syncing the decision issues. If not, you can report to Support why it hasn't happened yet, such as not having a decision issue, or not having the correct disposition.
From the remanded supplemental claim, you can access the original claim:
dr.decision_review_remanded
Legacy issue opt-ins
When a request issue is connected to an eligible legacy issue, it should be opted-in which means it was closed in VACOLS.
A majority of reported issues with this is due to user error and requires manual handling. This points to the code to start looking into that, but does not get into details of opting in issues or rolling back opt-ins if they were not properly connected to the request issue.
# Find the legacy issue opt-ins
lio=ri.legacy_issue_optins
# if processed_at is blank, then you can try re-processing:
LegacyOptinManager.new(decision_review: dr).process!
Summary of interactions with external systems
- Establishing an End Product
- After Intake for eligible issues that are processed in VBMS
- After editing a Decision Review, and adding request issues whose end product type is not yet created
- Automatically after a request issue gets decided with a remanded disposition
- Creating a contention
- Contentions are added to an End Product
- Happens when an eligible request issue that is processed in VBMS is added to a Decision Review
- This can happen during Intake, or during an edit
- Editing a contention
- Users can edit the contention text for issues processed in VBMS, unless the issue is an "Unidentified issue"
- Removing a contention
- Contentions are removed when an issue is removed during edit
- Contentions are also removed when an issue is withdrawn
- Cancelling an end product
- If all contentions on an end product are removed, the end product is also cancelled
- Syncing decision issues
- Once an End Product is cleared (synced_status: "CLR"), we start checking VBMS for a contention disposition, and a matching rating issue (if rating). Once both of these happen, a decision issue is created
- Opting in Legacy Issues
- When a user connects a request issue to an eligible legacy issue, the legacy issue is closed in VACOLS
- If all legacy issues on a legacy appeal are closed, the legacy appeal is also closed in VACOLS
- Rolling back a legacy issue opt-in
- If an opted-in issue is removed or withdrawn from a review, the legacy issue is re-opened
- If the legacy appeal was closed, it is also re-opened
Known problems
Missing ratings
If a user is unable to find the issue they are looking for, this is a missing rating. The user should add the issue as an unidentified issue, and wait to hear back from the business on when they can try to process it again.
Upstream errors
If an end product fails to establish, the error will likely be stored in the dr.establishment_error or the riu.error.
If the establishment was attempted less than a day ago, it may be due to an issue that will resolve itself such as an upstream error. You can re-attempt these manually:
DecisionReviewProcessJob.new.perform(dr)
If establishment is still failing after 1 day, it may be due to a longer term issue. Users should get a message in their inbox discouraging them from submitting a support ticket.
These are being handled in a separate process in collaboration with external partners. To see the relevant error, check the "Icebox" pipeline in ZenHub, or look for issues labeled "upstream-error", and provide the link to the issue to Support.
When these are successfully established, users will get another message informing them.
Request issues being removed, but the contention isn't removed
If a request issue is removed, it will have a closed_status of "removed" or "withdrawn" and it will not show up on the Caseflow UI. If the ri.contention still exists, then the contention was not successfully removed in VBMS and it will still show up in VBMS.
This can be re-attempted in the case of a locked rating that did not have a matching rating issue. However, there are cases where we should not be allowing the user to remove a contention and we are not effectively preventing it yet. In this case, it is best to update the request issue to show that it is not removed:
ri.update!(closed_status: nil, closed_at: nil)
Board grant rating issues are not editable
If we get a report of a board grant contention having text that is not sufficiently descriptive, these need to be updated manually because there is currently no user interface for updating these. See RequestIssueContention. In order to update these, we need to get the desired text from the user.
Recently fixed
Difference of Opinion claims
We did not have EP codes for DOO claims until recently, so if these were reported previously the only guidance we could give was to wait. This was just implemented, and these should start being automatically processed as of 2/19/2020.
Contention text is blank
There were some contentions being created with blank text in VBMS due to having newline characters. This impacted some, but not all request issues with newline characters.
A fix for this was merged on 2/18/2020 and previously impacted contentions were manually cleaned up.
This was also causing contention removal to fail, because VBMS did not allow removing contentions with blank text. This can be overridden by setting the contention text for the contention to be removed to a non-blank value.
Claim was manually cleared and the request issues should be "re-opened"
Sometimes End Products are changed to a 400 EP and manually cleared. The request issues on that end product are not expecting decisions, and are still considered active. The user probably wants to try to intake them again, but they are ineligible due to being active on another review.
These are automatically being handled now if their EP was changed to a 400 EP. If there is a case where they were not changed to a 400 EP, but the user manually cleared the claim and wants the request issues closed as not expecting a decision.
See Making a stuck issue available from a manually cleared claim
Request issue withdrawals
There was a bug processing request issue withdrawals to have them removed in VBMS. These should be manually removed in VBMS. See RequestIssueContention. Fixed in #14116.