VSO Permission Mapping in Caseflow - department-of-veterans-affairs/caseflow GitHub Wiki

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](/department-of-veterans-affairs/caseflow/wiki/"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:

VSO Section on 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.

VSO Users Management

Creating `TrackVeteranTask`s 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.