Error Formatting in Caseflow

Initially this will be scoped to just the hearings codebase so that it can be expanded upon in other parts of the codebase in the future. We can begin by determining the current structure of errors and agreeing on a single structure to be applied. The next step could be creating a new component to handle the updated error structure. When the component is in place, we can then begin going through screens/controllers individually and updating the existing handling of errors to use the new component and structure.

Outlined below is a list of the controllers and frontend components involved with sending/displaying errors to the user.

Frontend

The components below are grouped by the current hearings screens in order to better understand the flow of errors within the frontend and show why different components might be used for different screens based on the types of errors being handled.

Current Structure

All of the hearings frontend components that are not shared with other Caseflow apps reside in: client/app/hearings. The entry point for the Hearings app is: client/app/hearings/HearingsApp.jsx. This component contains the browser router and all of the screens within Hearings. Below are the current list of screens:

  • HearingWorksheetPrintAllContainer: /hearings/worksheet/print

    • UnsupportedBrowserBanner (loaded when browser not chrome)
    • StatusMessage
      • Static type/title/messageText
    • LoadingDataDisplay
      • HearingWorksheetPrinted
        • WorksheetFooter
        • WorksheetHeader

  • DailyDocketContainer:

    Routes

    • /hearings/docket/:hearingDayId/print
    • /hearings/schedule/docket/:hearingDayId

    State

    • serverError
      • Boolean
      • Set by HANDLE_DAILY_DOCKET_SERVER_ERROR action
    • dailyDocketServerError (redux)
      • Boolean
      • Set by HANDLE_DAILY_DOCKET_SERVER_ERROR action
    • onErrorHearingDayLock (redux)
      • Boolean
      • Set by HANDLE_LOCK_HEARING_SERVER_ERROR action

    Components

    • LoadingDataDisplay
      • Alert client/app/components/Alert.jsx
        • message or children
        • title
        • type one of success, error, warning, or info
      • DailyDocketPrinted
      • DailyDocket

        • UserAlerts client/app/components/UserAlerts.jsx

          Props

          • alerts
            • Array of Objects
            • Set by props
            • Objects contain keys that match the Alert component

          Components

          • Alert client/app/components/Alert.jsx

        • Alert client/app/components/Alert.jsx

          • 3 instances all with hard-coded values

        • DispositionModal

        • RemoveHearingModal

        • LockModal

        • DailyDocketEditLinks

        • DailyDocketHearingRows

          • DailyDocketRow

          State

          • alerts
            • Array of Objects
            • Set by RECEIVE_TRANSITIONING_ALERT, TRANSITION_ALERT, REMOVE_ALERTS_WITH_EXPIRATION, CLEAR_ALERTS, or RECEIVE_ALERTS
            • client/app/components/common/reducers.js
          • transitioningAlerts
            • Array of Objects
            • Set by RECEIVE_TRANSITIONING_ALERT or TRANSITION_ALERT
            • client/app/components/common/reducers.js

          Components

          • HearingText client/app/hearings/components/dailyDocket/DailyDocketRowDisplayText.jsx

            • PreppedCheckbox client/app/hearings/components/dailyDocket/DailyDocketRowInputs.jsx
            • DocketTypeBadge
            • PowerOfAttorneyName client/app/queue/PowerOfAttorneyDetail.jsx
            • HearingTime client/app/hearings/components/HearingTime.jsx

          • HearingTime client/app/hearings/components/modalForms/HearingTime.jsx

            • errorMessage string is set by props, however does not appear to be set by the DailyDocketRow

          • VirtualHearingModal

            State

            • representativeEmailError
              • String
              • set bythe catch block of onSubmit
              • Value always set to INVALID_EMAIL_FORMAT constant
            • appellantEmailError
              • String
              • set by setAppellantEmailError in validateForm and in the catch block of onSubmit
              • Value always set to INVALID_EMAIL_FORMAT constant

          • AodModal

          client/app/hearings/components/dailyDocket/DailyDocketRowInputs.jsx

          • StaticHearingDay
          • HoldOpenDropdown
          • StaticVirtualHearing
          • DispositionDropdown
          • Waive90DayHoldCheckbox
          • TranscriptRequestedCheckbox
          • HearingDetailsLink
          • LegacyAodDropdown
          • AmaAodDropdown
          • AodReasonDropdown
          • HearingPrepWorkSheetLink
          • StaticRegionalOffice
          • NotesField
          • HearingLocationDropdown

        • StatusMessage

          • title set by COPY.HEARING_SCHEDULE_DOCKET_JUDGE_WITH_NO_HEARINGS or COPY.HEARING_SCHEDULE_DOCKET_NO_VETERANS
      • HearingDayEditModal
        • HearingRoomDropdown
          • errorMessage string set by props, not used in HearingDayEditModal
        • JudgeDropdown
          • errorMessage string set by props, not used in HearingDayEditModal
        • HearingCoordinatorDropdown
          • errorMessage string set by props, not used in HearingDayEditModal

  • HearingsUserContext: /hearings/:hearingId/details

    • HearingDetailsContainer

      • LoadingDataDisplay

      • HearingsFormContextProvider

        • Snapshot of hearings state, does not contain error state

      • HearingDetails

        • Catches errors in submit
          • Mapped to error.message instead of error.detail

        State

        • virtualHearingErrors
          • Object
          • Set by submit function checks and catch block
          • Maps to errors object in lower components
        • error
          • String
          • Set by
            • resetState
            • submit function catch block

        Components

        • UserAlerts client/app/components/UserAlerts.jsx
        • Alert client/app/components/Alert.jsx
        • HearingConversion
          • HearingTime
          • AppellantSection
          • RepresentativeSection
          • VirtualHearingSection
        • DetailsHeader
          • TitleDetailsSubheader
            • TitleDetailsSubheaderSection
          • DocketTypeBadge
        • DetailsForm
          • JudgeDropdown
          • HearingCoordinatorDropdown
          • HearingRoomDropdown
          • HearingTypeDropdown
          • VirtualHearingForm
            • HearingLinks
            • VirtualHearingFields
              • Timezone
              • VirtualHearingEmail
              • HelperText
          • EmailNotificationHistory
          • TranscriptionFormSection
            • TranscriptionDetailsInputs
        • VirtualHearingModal
          • Catches errors in onSubmit
            • Mapped to error.message instead of error.detail
              State
          • representativeEmailError
            • String
            • set bythe catch block of onSubmit
            • Value always set to INVALID_EMAIL_FORMAT constant
          • appellantEmailError
            • String
            • set by setAppellantEmailError in validateForm and in the catch block of onSubmit
            • Value always set to INVALID_EMAIL_FORMAT constant

  • HearingWorksheetContainer: /hearings/:hearingId/worksheet
    NOTE: Did not find any errors outside of local errors

    • LoadingDataDisplay
    • HearingWorksheet
      • HearingWorksheetDocs
      • HearingWorksheetStream
        • HearingWorksheetIssues
          • HearingWorksheetIssueFields
          • HearingWorksheetPreImpressions
          • HearingWorksheetIssueDelete
      • WorksheetHeaderVeteranSelection
      • WorksheetHeader client/app/hearings/components/hearingWorksheet/WorksheetHeader.jsx
        • DocketTypeBadge
        • WorksheetFormEntry client/app/hearings/components/hearingWorksheet/WorksheetHeader.jsx
      • WorksheetFormEntry client/app/hearings/components/hearingWorksheet/WorksheetHeader.jsx

  • ListScheduleContainer: /hearings/schedule
    State

    • serverError
      • Boolean
      • Never set or used

    Components

    • QueueCaseSearchBar
      • CaseListSearch
        • CaseSearchErrorMessage
          • errorType, queryResultingInError, and errorMessage set by caseList.search redux state
          • Alert
    • Alert (no errors displayed)
    • Alert (Second instance shows error based on invalidDates key through props from hearingSchedule redux state)
    • ListSchedule
      • ListTable
        • LoadingDataDisplay
        • QueueTable
      • ListScheduleDateSearch
    • HearingDayAddModal
      State
    • errorMessages
      • Array of Strings
      • Set by onClickConfirm
    • roErrorMessages
      • Array of Strings
      • Set by onClickConfirm
    • dateError
      • Boolean
      • Set by onClickConfirm, resetErrorState
      • Pushes to errorMessages local variable
    • typeError
      • Boolean
      • Set by onClickConfirm, resetErrorState
      • Pushes to errorMessages local variable
    • roError
      • Boolean
      • Set by onClickConfirm, resetErrorState
      • Pushes to roErrorMessages local variable
    • serverError
      • Boolean
      • Set by persistHearingDay
    • noRoomsAvailableError
      • Boolean
      • Set by persistHearingDay
      • Maps to error.detail instead of error.details

    Components

    • Alert (Displays errors only for serverError and noRoomsAvailableError)
    • RegionalOfficeDropdown
    • JudgeDropdown
    • HearingCoordinatorDropdown
      • errorMessage received through props

  • BuildScheduleContainer: /hearings/schedule/build

    • BuildSchedule
      • Alert (Displays only success messages)

  • BuildScheduleUploadContainer: /hearings/schedule/build/upload
    State

    • All errors set by
      • createSchedulePeriod
        • Calls POST '/hearings/schedule_periods' endpoint
      • validateData
    • uploadFormErrors
      • Set by hearingSchedule redux state
    • uploadRoCoFormErrors
      • Set by hearingSchedule redux state
    • uploadJudgeFormErrors
      • Set by hearingSchedule redux state

    Components

    • BuildScheduleUpload
      • uploadJudgeFormErrors, uploadRoCoFormErrors
        • String
        • Removes "Validation failed: " string
        • Splits and maps to individual strings on commas
      • uploadFormErrors set on RadioField component

  • ReviewAssignmentsContainer: /hearings/schedule/build/upload/:schedulePeriodId
    State

    • schedulePeriodError
      • Set by redux state schedulePeriodError
      • Calls GET '/hearings/schedule_periods/:schedulePeriodId' endpoint
    • spErrorDetails
      • Set by redux state spErrorDetails
      • Maps to error.details instead of error.detail

    Components

    • ReviewAssignments
      • Alert
      • StatusMessage

  • AssignHearingsContainer: /hearings/schedule/assign

    • RegionalOfficeDropdown
    • LoadingDataDisplay
    • AssignHearings

      • NoUpcomingHearingDayMessage

        • StatusMessage

      • AssignHearingsTabs

        • UpcomingHearingsTable
          • LinkToAppeal
          • HearingAppellantName
          • HearingDocketTag
          • HearingTime
          • QueueTable
        • AssignHearingsTable
          State
        • showNoVeteransToAssignError
          • Boolean
          • Set by onPageLoaded

        Components

        • NoVeteransToAssignMessage
          • StatusMessage
        • QueueTable

Backend

The controllers below each contain some response with a defined error structure. They can be grouped based on how the error is currently being constructed and sent to the frontend.

Current Structure

  • HearingsController app/controllers/hearings_controller.rb
    • all
      • ActiveRecord::RecordNotFound (errors [message, code])
      • ActiveRecord::RecordNotUnique (errors [message, code])
      • ActiveRecord::RecordInvalid (errors [message, code])
      • Caseflow::Error::VacolsRepositoryError (errors [message, code])
    • find_closest_hearing_locations
      • no error class "facility response error"
      • defined in ExternalApi::VADotGovService, serialized in Caseflow::Error
        • Caseflow::Error::VaDotGovMissingFacilityError (errors [{ status, title, detail}])
      • defined in ExternalApi::VADotGovService::Response, serialized in Caseflow::Error
        • Caseflow::Error::VaDotGovLimitError (errors [{ status, title, detail}])
        • Caseflow::Error::VaDotGovRequestError (errors [{ status, title, detail}])
        • Caseflow::Error::VaDotGovServerError (errors [{ status, title, detail}])
  • Hearings::ScheduleHearingTasksColumnsController app/controllers/hearings/schedule_hearing_tasks_columns_controller.rb
    • appeal_type
      • Caseflow::Error::InvalidParameter (parameter, message)
  • Hearings::SchedulePeriodsController app/controllers/hearings/schedule_periods_controller.rb
    • show
      • HearingSchedule::Errors::NotEnoughAvailableDays (error, details, type)
      • HearingSchedule::Errors::CannotAssignJudges (error, details, type)
    • create
      • ActiveRecord::RecordInvalid (error)
    • update
      • no error class "schedule period cannot be finalized" (error)
  • Hearings::HearingDayController app/controllers/hearings/hearing_day_controller.rb
    • create
      • ActiveRecord::RecordInvalid (errors: [title, detail])
      • no error class "no available rooms" (errors: [title, detail, status])
    • index, index_with_hearings
      • no error class "hearing day range invalid" (errors: [title, details])

Risks/Unknowns

  • Potentially a large number of controllers involved with a single screen
    • Could cause challenges with implementation if some controllers have different error structure than others.
  • How dependent on the redux state is the error handling currently?
  • How much of the error handling resides in component lifecycle methods currently?
  • Are there places where the hearings app receives error messages from an endpoint outside of the core hearings app controllers and if so how does the error handling differ there?
Select a repo