VSO Permission Mapping in Caseflow

VSO Permission Mapping in Caseflow

Overview

This page documents how a VSO's permissions in BGS get mapped to capabilities in Caseflow.

(Ferris) I am creating this page to document my knowledge of how Caseflow knows what a VSO user can see.

Process

Identifying a VSO user in Caseflow

From the Rails console, a VSO User can be identified by their roles. All VSO users will have a VSO role.

[22] pry(main)> User.where('? = ANY(roles)', ['VSO']).first
[2020-03-04 11:30:28 -0500]   User Load (1.1ms)  SELECT  "users".* FROM "users" WHERE ('VSO' = ANY(roles)) ORDER BY "users"."id" ASC LIMIT $1  [["LIMIT", 1]]
=> #<User:0x000055e219591b08
 id: 19,
 created_at: Mon, 24 Feb 2020 21:21:47 UTC +00:00,
 css_id: "BILLIE_VSO",
 efolder_documents_fetched_at: nil,
 email: nil,
 full_name: "BILLIE VSOUser Jones",
 last_login_at: nil,
 roles: ["VSO"],
 selected_regional_office: nil,
 station_id: "101",
 status: "active",
 status_updated_at: nil,
 updated_at: Mon, 24 Feb 2020 21:21:47 UTC +00:00>

Creating a VSO in Caseflow

VSOs and their users can be managed by a team admin in Caseflow. The easiest way to do this is by accessing the UI, and using the team management page:

The BGS Participant ID field for the VSO maps to the VSO in BGS (not to a specific member of the VSO). Caseflow uses this to check if a user is part of a VSO in Representative#user_has_access?, by seeing if the VSO's participant ID is included in a list of participant IDs for POAs the user represents.

Here is what a VSO looks like in the database:

=> #<Vso:0x000055e2190678a8
 id: 7,
 created_at: Mon, 24 Feb 2020 21:21:47 UTC +00:00,
 name: "VSO",
 participant_id: "2452415",
 role: "VSO",
 status: "active",
 status_updated_at: nil,
 type: "Vso",
 updated_at: Mon, 24 Feb 2020 21:21:47 UTC +00:00,
 url: "veterans-service-organization">

Once a VSO is tracked in Caseflow, members of the VSO can be added to VSO using the users management page. It's also an easy way to see which users are part of a VSO.

Creating TrackVeteranTasks in Caseflow

Refer to the Task Tree documentation for actual task trees with the TrackVeteranTask.

A TrackVeteranTask is created for every one of the Veteran's representatives that is working a case. The task doesn't track work that needs to be completed like other tasks, but instead functions as a marker task that grants access for an appeal to an Organization (POA). Because the TrackVeteranTask doesn't track work, some statuses for the task carry slightly different meanings:

Status	Description
in_progress	The assigned_to organization is an active representative for the case
cancelled	The assigned_to organization was previously a representative for the case

UpdateAppellantRepresentationJob runs TrackVeteranTask#sync_tracking_tasks for a set number of appeals periodically. This will create or update TrackVeteranTasks for each representative on an appeal. The TrackVeteranTask ultimately maps a Caseflow Organization to POA in BGS.

Determining Access

Caseflow primarily consults BGS to determine whether or not a POA should have access to a case. To do this, Caseflow checks if an appeal has a TrackVeteranTask associated with it. If there is one, Caseflow uses the assigned_to field and checks if the current user has access to the Organization associated with the TrackVeteranTask.

See this code.

Caseflow does this by obtaining a list of POAs a user represents from BGS using the user's participant ID. Once Caseflow has this list, it just checks if the BGS participant ID associated with the Organization is among the list of POAs the user represents -- if it is, then Caseflow will grant access to that user to view the case.

See this code.

Glossary

• POA: Power of Attorney. A person or organizaiton that represents the veteran.

• VSO: Veteran Service Organization. An organization that works on behalf of the veteran.

  • "VSO" is also a role for users in Caseflow.
  • Vso is also a kind of Representative, and by extension, a kind of Organization in Caseflow.

• User: A user in Caseflow.

• User#vsos_user_represents: Returns all VSOs that the user represents from BGS.

• Organization: A grouping of users in Caseflow.

• Representative: A person or organization that represents the appellant (usually the veteran but doesn't have to be).

  • Representative: A Caseflow Representative is a kind of Organization that groups together users from a VSO. There is a Representative record for each VSO in Caseflow.

• Representative#user_has_access?: Tests through BGS if a user is a POA representing the VSO.

• TrackVeteranTask: A Task that indicates that an appeal is visible to a representative.

• UpdateAppellantRepresentationJob: A recurring job that updates any changes to the veteran's representation for an appeal. The job does this by creating or cancelling any TrackVeteranTasks on the appeal.

• BgsService#fetch_poas_by_participant_id: Fetches POAs related to a BGS participant ID. The participant ID here refers to the participant id for a specific user. The BGS call returns all POAs that the user represents.

• Hearing#assigned_to_vso?: Determines if a VSO user can access a Hearing.

  • Same as LegacyHearing#assigned_to_vso?

Additional Resources

• VSO Overview Documentation