PASIprep Error Display Guidelines

This is a UI Pattern for PASIprep UI Guidelines.

Types of Errors

The errors shown in PASIprep can be divided into the following categories:

Validation rule or server errors

  • These are generally errors thrown by the services used by the screen when user performs an action or is attempting to view data on screen.
    • These should be displayed in message panels; see PASIprep Page Layout Guidelines for placement of error/warning message panels. It is possible to have more than one panel if multiple errors occurs.
    • If the Error is a Rejection from a Validation Rule, the message should be displayed as “{Rule #} – {Rule Message}”
  • If there are errors on one or more records during a bulk operation, a summary error message would be shown in the panel with an Export link that'll allow user to download the details on the records that failed.
    • The summary message should show the number of successes and failures and provide an export link, e.g. “The save operation failed for 10 of 20 records. [Export] to view the details of the affected records.”
    • The export should trigger the download of a CSV containing:
      1. Error Code (i.e. Validation Rule Number)
      2. Error Message (i.e. Validation Rule Message)
      3. {all columns that were visible on the grid where the user performed the bulk operation on}
      4. {Last Column} URL (to the View page that the user should go to to review the issue)

Form/field level validation errors

  • Field level validations are generally performed client side and is used to validate the data value's format and structure (e.g. accepted data type (date, int), formats (e.g. postal code formats), maximum lengths allowed).
  • They should be display below the field that triggered the error
    • In addition to the field-level error message, an error message panel with the message “There are one or more issues on the form. Please review the form and resolve the issue(s) before continuing.” will be displayed to alert user to go through the form.
  • See PASIprep Writing Guidelines for a list of commonly used error messages

Unexpected errors and failures

  • These are errors that results from user performing something unexpected or the server responded in an unexpected manner (e.g. database failure). These are scenarios where it is important not to expose data or allow user to perform an action, thus an error page should be used
  • If the Error happens when user is performing an action that will take them away from the screen (e.g. submitting a form, where on success user would be redirected to a different page), and the error prevents user from advancing, they should remain on the page the action originated from, and the Error(s) should be displayed on that screen.

When to use Client Side vs Service Validation Errors

For PASIprep, any validation that is covered by a validation rule in the service should ideally not be repeated as client side validation. The goal is to reduce maintenance effort on keeping both server side and client side in sync.

Thus the following guidelines on the usage of client side vs service validation is recommended:

  • If a function uses a specific PASI Core Service that has (or will have) rejection validation rules implemented against it, unless there is a reason to do so, the UI should not try to replicate the rules defined in the service to predicatively 'hide' a function.
    • e.g. there is a validation rule on the Submit Student Name service that forbids a user from deleting a preferred name. PASIprep screens should not replicate that logic and put a client-side error message on deleting of Preferred name; this prevents having to maintain the logic in multiple areas.
  • If the function does not use a Core Service, or an appropriate validation rule on the Core service doesn't exist (and is not appropriate to add to the Core Service), the expectation is that on the server side, either 1) there are service security restrictions implemented (preferred method is possible) or 2) User Error type validation rules created to enforce the business rule required. This applies to all business rules related to PASIprep Permission checks, as the Core Services cannot validate against those permissions. Note that User Error validation rules are preferred if either 1) a user-friendly message needs to be provided to the user as they can encounter the security restriction with 'normal usage' (i.e. they didn't try to 'hack' the URL or screen to try to get to a function they shouldn't have), OR 2) the rule involves checking a PASIprep permission in conjunction with another data element (e.g. School Year), as service security restrictions cannot meet these two objectives.
    • Exceptions to the above rule:
      • In grids, if the Action is not valid because user didn’t select anything on the grid to perform the action on, show an Alert popup titled “Missing Selection” with a message: “Please select a record first.”
      • In grids, to prevent user from getting the not-as-friendly rule 9023 Empty Update error, if the Action does not update the record (e.g. user clicked [Delete] when they have a Deleted record selected) show an Alert popup titled “No Update Required” with a message: “The selected record _” (← the design will need to specify the message unless it’s one of the common ones below)
        • Common messages:
          • “The selected record has already been deleted.” (for deleting a deleted record)
          • “The selected record is not a deleted record.” (for undeleting a non-deleted record)
        • In bulk-select action scenario, if a mix of records are selected where some will be empty updates and some will be true updates, then no alert/warnings will be shown - the empty updates will simply be bypassed quietly.
      • In grids, if the Action is not valid because user selected multiple rows in a multi-select grid and the Action can only apply to a single selection, show an Alert popup titled “Invalid Action” with the message: “Please select a single record only to perform this action”.

Error Message Writing Guidelines