User access permissions in Caseflow - department-of-veterans-affairs/caseflow GitHub Wiki
About: This document captures the current state of access permissions patterns (aka user authorizations) in Caseflow.
Intended audience: Caseflow team members
NOTE: For a list of user roles, see the Roles Overview page.
Caseflow has disparate permissioning sources:
- CSEM/CSUM roles and functions
- Feature toggles
- VACOLS roles
- Caseflow organizations
It's complex, because:
- How we use feature toggles overlaps with CSEM/CSUM roles
- How we use feature toggles overlaps with Caseflow organizations
- How we use VACOLS roles overlaps with Caseflow organizations
Resources:
- https://github.com/department-of-veterans-affairs/caseflow/issues/5549 - discusses role based and activity based approaches to access permissions
- department-of-veterans-affairs/appeals-pm#1540 - (2017) Caseflow teamwide discussion about permissions
- CSEM/CSUM is an access permissions application used by VA.
- Not all agencies use it. In mid-2019, the Caseflow team learned that VHA applications do not rely on CSEM
- It has 2 concepts: roles and functions
- Initially, our team used both
- Then, we relied more on functions, and kept the role vague as "User"
- Currently, Caseflow uses CSEM functions (which are meant to be activity-based, but the way we do so doesn’t neatly match either the activity-based or role-based approach)
- Some Caseflow CSEM functions are phrased as activities e.g. “Certify Appeal”, “Establish Claim”
- Some are phrased as roles e.g. “Reader”, “Hearing Prep”
- Users submit a form (8824e) to another VA entity that process those requests - basically flips the switch. This process is notoriously cumbersome.
| CSEM function | High-level functionality |
|---|---|
| Global Admin | Everything + impersonating users |
| Software Engineer System Admin | Access level for Software Engineers developing new functionality for the Caseflow system |
| Download eFolder | eFolder Express |
| Mail Intake | Create a new intake, add/remove issues. See more |
| Admin Intake | Everything Mail Intake can do and view submitted jobs and view a non-compensation or pension organization's queue. See more |
| Establish Claim | Caseflow Dispatch flow |
| Manage Claim Establishment or "Manage Claims Establishme" | Caseflow Dispatch flow + manager view + Missing Decisions report |
| Certify Appeal | Caseflow Certification |
| Edit HearSched | For Hearing Management Branch employees to schedule hearings |
| Build HearSched | For Hearing Management Branch operations and leadership to
|
| RO ViewHearSched | For users that need a read-only view of the hearing schedule and daily docket |
| Hearing Prep | For users that need to edit hearing worksheets (VLJs, attorneys) |
| VSO | VSO/private attorney/agent view of hearing schedule, VSO/private attorney/agent view of queue |
| Case Details | Search --> Case Details |
| Reader | Reader, Queue, Search, Case Details |
| DRO, RVSR, VSR |
Unused in the application but still granted by CSEM (can be discovered by searching for all granted roles in the Rails console: User.all.pluck(:roles).flatten.uniq.compact.sort) |
Feature toggles are used to control access to a new feature while it is still in development, allowing engineers to continue to deploy code to production for multi-ticket features daily without inadvertently giving users access to incomplete functionality.
Assumption: feature toggles should be used for functionality that is rolled out to all users, or will eventually be removed when another mechanism for user permissions for this functionality has been decided.
A good example of using feature toggles as many consider they are intended is the Summer 2019 pagination API work use_task_pages_api. This refactoring and tech improvement begins behind a feature toggle, but can then be rolled out to everyone, and thus the feature toggle safely removed. PRs: #11213, #12744
- Add a new feature toggle to the list of feature toggles in appeals-deployment enabling access for the appropriate user groups. Example PRs: #2298, #2239
- At the top-level entrypoint into your feature in caseflow, check whether the feature toggle is enabled for a given user. Example PRs: #11213, #1164
The technical implementation of FeatureToggle lives in caseflow-commons.
We should not be using feature toggles for functionality that only some users should get because we will then need to maintain the feature toggle indefinitely. The organization user access pattern or another option should be considered. However, some feature toggles that break the pattern are:
- Example:
withdraw_decision_reviewis a feature toggle, when really, only a subset of BVA users should be able to do this. And, all VBA users want the ability to do this. - Example:
remove_decision_reviewsis a feature toggle that is currently turned on for everyone, but it should be restricted.
- The VACOLS staff table is the canonical Board list of users in many roles (Attorney, Judge, Acting Judge, VLJ Support), and it currently is role-based
- Jed Wagner, Board employee who built VACOLS, updates this list
- The primary roles that provide support tickets and confusion are: Attorney, Judge, and Acting VLJ
- There are fewer VACOLS roles than there are Caseflow organizations, already
- Caseflow organizations are how Caseflow groups members of various BVA (and beyond!) teams. Since members of the same team have similar responsibilities and levels of access, we are able to use organization membership as a form of access control. -
- Individuals are members of organizations, which often map to teams or subteams at the Board who complete certain tasks. For example: individual VLJ Support Staff are members of the VLJ Support Staff organization.
- This pattern is largely:
- Organization:Tasks :: Role:Activity
- Some organizations represent people at the Board - for example, every judge or acting judge has an organization of their name, with attorneys as members
- Each VSO - field or national, IHP-writing - has an organization with their name
- Each private attorney or agent has an organization with their name
- Organizations can have
team admins, which have different functionality:- All admins can add users to their organizations
- Admins of VLJ Support Staff, each VSO organization, and Board Dispatch can act on behalf of members in their organization - they are presented with task actions available to the individual who is currently assigned the task (e.g. reassign, complete, place tasks on hold)
| Organization | Permissions |
|---|---|
| Bva | - Ability to visit /team management page in order to create/edit/remove organizations and members |
| Case Review | - Ability to withdraw appeals |
| Translation | - Ability to act on Translation tasks |
| Hearings Management | schedule hearings and complete hearing tasks |
| Hearings Admin | - Ability to work Hearing Admin Action tasks |
| VLJ Support Staff | work ColocatedTasks |
| Privacy team | |
| Each judge or acting judge | - Ability to request cases from automatic case distribution |
| Quality Review | |
| Board Dispatch | |
| - Ability to create mail tasks, which include post-decisional motions tasks | |
| Advance on Docket | - Ability to mark cases AOD |
| Litigation Support | |
| Case Movement | - Ability to move cases that are ready for distribution to a judge manually (not relying on auto-case distribution) |
| Each VSO, private attorney, or agent organization |