Case Distribution Admin UI - department-of-veterans-affairs/caseflow GitHub Wiki

Objectives

The primary goal of our work is to provide a centralized location to be able to view values and descriptions of the levers used in the case-distribution algorithm. In addition to this, Administrative users of the Case Distro Algorithm Control team are able to replace existing values for the case-distribution variables.

Usage of levers within the algorithm

To use a lever within the algorithm you simply need to do CaseDistributionLever.lever_item where lever_item is the developer friendly item value for the lever from DISTRIBUTION.json.

This is possible because we are overriding method_missing for CaseDistributionLever ActiveRecord model object .

Categorization of Levers in Automatic Case Distribution Controls

Within the Case Distribution Admin UI, levers are categorized as Active and Inactive.

Active levers are levers that have the capacity to be changed, but their ability to be edited currently within the Case Distribution Admin UI is determined by the attribute is_disabled_in_ui. Levers actively being used within the case-distribution algorithm are not grayed out, and are determined by the attribute is_toggle_active.

The location of the lever seed data and default values is located at db/seeds/case_distribution_levers.rb

Active Levers

Active Levers are Divided into 4 primary groups; Excluding Appeals by Docket Type and Priority from Automatic Cade Distribution, Batch Size, Affinity Days, and AMA Non-priority Distribution Goals by Docket. Each of these groups are their own components and wrapped within the InteractableLeversWrapper.jsx file. The Named Judge Affinity Inclusion Levers live outside of these groups as it is found within the Caseflow Team Management page and not the Admin UI.

• Excluding Appeals by Docket Type and Priority from Automatic Case Distribution

  • Users can specify if they'd like to exclude specific docket types from automatic case distributions. They can further narrow that down to only exclude non-priority or priority appeals for that docket type if desired.
  • Excluding Appeals by Docket Type and Priority from Automatic Cade Distribution levers are currently disabled in the Case Distribution Admin UI for future work implementations.

• Batch Size

  • Batch Size levers control the amount of cases distributed to judges per request during the "Request More Cases" workflow, and the maximum limit of unassigned cases a judge may have.
  • Batch Size levers are classified as data_type: number with whole number inputs.

  Batch Size Lever	Description	Default Seed Value
  alternative_batch_size	Sets case-distribution batch size for judges who do not have their own attorney teams.	15
  batch_size_per_attorney	Sets case-distribution batch size for judges with attorney teams. The value for this data element is per attorney.	3
  request_more_cases_minimum	Sets the number of remaining cases a VLJ must have equal to or less than to request more cases. (The number entered is used as equal to or less than)	8

• Affinity Days

  • Affinity Days levers control the number of days each type of case respects the affinity to the qualifying judge. Affinity Day levers are classified as data_type: radio with 3 selectable options. A value option that is a whole number value quantifying the number of days, an "infinite" option that always distributes to the current judge, and "omit" option that omits the variable from distribution rules.
  • The Affinity Days lever type are currently implemented in the Case Distribution Admin UI with implemented levers below are noted in BOLD. However, all other affinity day levers are currently disabled pending future work implementations.

  Affinity Days Lever	Description	Default Seed Value
  ama_hearing_case_affinity_days	For non-priority AMA Hearing cases, sets the number of days an AMA Hearing Case is tied to the judge that held the hearing.	60
  ama_hearing_case_aod_affinity_days	Sets the number of days an AMA Hearing appeal that is also AOD will respect the affinity to the most-recent hearing judge before distributing the appeal to any available judge.	14
  cavc_affinity_days	Sets the number of days a case returned from CAVC respects the affinity to the judge who authored a decision before distributing the appeal to any available judge. This does not include Legacy CAVC Remand Appeals with a hearing held.	21
  cavc_aod_affinity_days	Sets the number of days appeals returned from CAVC that are also AOD respect the affinity to the deciding judge. This is not applicable for legacy apeals for which the deciding judge conducted the most recent hearing.	14
  aoj_affinity_days	Sets the number of days an appeal respects the affinity to the deciding judge for Legacy AOJ Remand Returned appeals with no hearing held before distributing the appeal to any available judge.	60
  aoj_aod_affinity_days	Sets the number of days legacy remand Returned appeals that are also AOD (and may or may not have been CAVC at one time) respect the affinity before distributing the appeal to any available jduge. Affects appeals with hearing held when the remanding judge is not the hearing judge, or any legacy AOD + AOD appeal with no hearing held (whether or not it had been CAVC at one time).	14
  aoj_cavc_affinity_days	Sets the number of days AOJ appeals that were CAVC at some time respect the affinity before the appeal is distributed to any available judge. This applies to any AOJ + CAVC appeal with no hearing held, or those with a hearing held when the remanding judge is not the hearing judge.	21

• AMA Non-priority Distribution Goals by Docket

  • The AMA Non-priority Distribution Goals by Docket section consists of Docket Time Goal and Distribution Prior to Docket Time Goal. These levers are independent of one another, but grouped within this section based on their effect on AMA Hearings, AMA Direct Review, and AMA Evidence Submission
  • Docket Time Goal
    • Each AMA docket type has a time goal for distribution. This is the target number of days in which they would like that docket type to be worked.

  Docket Time Goal Lever	Description	Default Seed Value
  ama_hearings_docket_time_goals	AMA Hearings Docket Time Goals	730
  ama_direct_review_docket_time_goals	AMA Direct Review Docket Time Goals	365
  ama_evidence_submission_docket_time_goals	AMA Evidence Submission Docket Time Goals	550

  • Start Distribution Prior to Docket Time Goal
    • The Start Distribution Prior to Docket Time Goal levers are classified as data_type: combination and consist of two interactive components. The first is a toggle switch to enable or disable the distribution prior to goals. The second (if toggled on) is an integer input for the designated number of days to begin distribution prior to docket time goal.
    • When turned on, this works with the Docket Time Goal number to indicate how many days prior to the specified docket time goal to release the appeal for distribution. This theoretically gives the appeal enough time to be distributed and completed within the time goal.
    • Distribution Prior to Docket Time Goal levers are currently disabled in the Case Distribution Admin UI for future work implementations.

  Distribution Prior to Docket Time Goal Lever	Description	Default Seed Value
  ama_hearings_start_distribution_prior_to_goals	AMA Hearings Start Distribution Prior to Goals	60
  ama_direct_review_start_distribution_prior_to_goals	AMA Direct Review Start Distribution Prior to Goals	365
  ama_evidence_submission_start_distribution_prior_to_goals	AMA Evidence Submission Start Distribution Prior to Goals	60

• Named Judge Affinity Inclusion

  Named Judge Affinity Inclusion Levers	Description	Default Seed Value
  exclude_appeals_from_affinity	Used to track whether a judge (team) should have their affinity appeals distributed to any available judge team even if the set amount of time has not elapsed.	False

  • The Named Judge Affinity Inclusion Levers are toggles to indicate specific judges who should be excluded from distribution of affinitized appeals, so that those appeals don't have to wait for the affinity days to elapse before being made available for distribution to any available judge if the affinitized judge has known unavailability.

  • These levers live outside of the Admin UI and can be found within the Caseflow Team Management page. Any user with access to the Caseflow Team Management page can designate an individual judge as eligible or ineligible to receive affinitized appeals.

  • When the box is checked, the judge will not receive cases with which there is an existing affinity relationship. Any appeal with an affinity relationship to that judge will immediately be released for distribution to any judge once the appeal is ready to distribute. Appeals that are tied (e.g., legacy hearing) are unaffected by this value.

• When visiting the Case Distribution Admin UI, users will be reminded that the removal of individual judges from Affinity Case Distribution is within the Caseflow Team Management page.

Inactive Levers

• Inactive Levers are levers classified in the lever_group: static and currently support multiple data types. Interaction with these levers is strictly disabled for both standard users and administrators.

  Inactive Levers	Description	Default Seed Value
  maximum_direct_review_proportion	Sets the maximum number of direct reviews in relation to due direct review proportion to prevent a complete halt to work on other dockets should demand for direct reviews approach the Board's capacity.	70%
  minimum_legacy_proportion	Sets the minimum proportion of legacy appeals that will be distributed.	90%
  nod_adjustment	Applied for docket balancing reflecting the likelihood that NODs will advance to a Form 9.	40%
  bust_backlog	Distribute legacy cases tied to a judge to the Board-provided limit of 30, regardless of the legacy docket range.	True

Audit Lever History

The Audit Lever History section provides a log of changes to the levers over the past 365 days with the timestamp, editing user's user_css_id, the lever title, and its previous and updated values.

• If a user makes multiple updates at once, a database entry will be created for each individual lever changed, an associated timestamp, and the user. When displaying this information to the user, however, these individual entries will be grouped together based on user and timestamp to show all the edits that were made at that moment by that user as an indexed list.

• The timestamp format displayed on the Audit Lever History section is different from what is saved to the database. The formatting of this displayed timestamp is handled in app/caseDistribution/utils.js

Member and Admin Views and Restrictions

• Non-members of the Case Distro Algorithm Control group are unable to access the page, view its contents, nor edit any existing lever attributes.

• Members of the Case Distro Algorithm Control group, but those who are not Admins, are authorized to view the full contents of the page, but levers are restricted to read-only in this view.

• Admin members are able to change values, save and update lever information, and have their edits displayed within the Audit Lever History section. Admin members are not able to edit levers that have been disabled, and are not able to interact with inactive levers.

• Members can be added to Case Distro Algorithm Control group, and given administrative access, on the ACD Controls Test Page.

Implementation of React Redux and Redux Store

• Primary reducer is implemented as leversReducer in LeversReducer.js in app/caseDistribution/reducers/levers
  • Reducer action types follow convention of being defined in LeversActionTypes.js, and those actions are fully defined in leversActions.js. Both located within the same reducers/levers folder.
• leversReducer is imported into root.js and incorporated into the rootReducer there.

How levers and history are stored

Testing

Feature Tests

Each section of the Case Distribution AI UI has an associated feature test to ensure that:

• All elements are displayed in read only mode for the CDAControlGroup non-admins
• The appropriate elements are displayed as editable for CDAControlGroup admins
• The appropriate elements are displayed in read only mode for CDAControlGroup admins

There are tests that also ensure that:

• The audit lever history table properly updates when a lever(s) has been updated
• The UI has the proper functionality including editing, saving, and updating

These tests are generally found in the spec/feature/automatic_case_distribution directory.

Testing Page

Access to the testing page located at /acd-controls/test and their scope accessibility is limited to local and testing environments. Notable testing features within this page include

• View All levers and their meta-data.
  • 
• Alternate view of Lever Audit History.
• Adding Users as members able to access Case Distribution Admin UI.
• Promoting users to administrators in Case Distribution Admin UI.
• Reseeding AOD and Non-AOD appeals within Case Distribution Admin UI.