Form Definitions

Forms are defined with JSON (but see issue 2282). Typically they are collected in the oat-forms project in git.

Form Sections:

The top-level sections of a form definition are name, theme, useif, formElements, restrictions, and reportExpr.

Name

The name of the form, as it appears in a list of forms to advisors or students.

Theme:

The name of a CSS file that allows different units/faculties to have a consistent colour scheme, for example. The most common value is themeCS.css. It’s generated from _wapp/app/assets/stylesheets/themeCS.less. Two other themes exist as of 2025-07-28: themeCourseOverride.less and themeMath.less.

UseIf:

Text displayed at the top of the form explaining when to use the form.

FormElements:

A list of the elements contained by the form. There are several different kinds of elements:

  • Instructions: Communicate information without asking a question.
  • Questions: These can be text fields (single line), text blocks (multi-line), checklists or radio buttons.
  • DB Info: Information fetched from the database and displayed.
  • DecisionsGroup: Information about who should decide how the form is handled. ( 2025-07-28: Byron thinks this should really be a higher-level construct; a sibling to formElements.)

Form elements are defined in oat.xplatform.models.forms.FormElements.scala.

All form elements can be declared for officeUseOnly meaning they will show to advisors but not to the student filling out the form. This is primarily intended for information from the database but also for questions the advisors may fill in (eg decision reached).

The following outlines the most important fields for each type of form element.

FormElements: Instructions:

  • text: A vector of strings that give instructions to the form user.
  • html: An optional string formatted as HTML. Only displayed if text is empty. The awkwardness of formatting a potentially long html blog as a single string is one of the reasons we should move from JSON to HCON for these definitions.

These fields can be expanded with terms. See comments under “Questions”.

FormElements: Questions:

All question types have the following fields:

  • questionType: One of Radio, Checklist, Text, TextField, CourseSelect.
  • question: A string containing the question to answer.
  • html: An optional html blob that follows the question to add more context.
  • name: A one “word” name for the question’s response (eg work_location). If not provided, it will default to the question type (which may result in duplicate names).
  • officeUseOnly: As above.

question and html can contain {{prevTerm}}, {{currentTerm}}, {{nextTerm}}, and {{nextNextTerm}} which will be expanded with the appropriate term reference in TTyy (eg W25) format.

Radio Questions: In addition to the fields for questions, has

  • options: A vector of options to list. Each option has two strings. The first to display to the user, the second is how the data is recorded. For example, [["Yes", "true"], ["No", "false"]].

Checklist Questions: In addition to the fields for questions, has

  • options: Same as for radio questions.
  • ensureOneChecked: Optional. Use true to force choosing at least one.

Text Questions: In addition to the fields for questions, has

  • charLimit: A vector of two integers giving the minimum and maximum number of characters allowed.

TextArea Questions: Like a text question but formatted for multiple lines of input when displayed.

CourseSelect Questions: Displays a drop-down list populated with a set of courses. In addition to the fields for questions, has:

  • studentCoursesOnly: Optional; defaults to false. If true, displays only the courses the student is in during the current term.
  • required: Optional; default to true.

FormElements: DB Info:

These elements fetch information from the database. Specific parts of this can be formatted for display using information in ReportExpr section. Each of these has corresponding code in OAT.

BasicID: Fetch name, uwid and userid.

CsStdXferInfo: Information about a student who would like to transfer to CS: cs136_grades, cs_avg, num_advanced_courses, comm_course_avg.

StdPlansInfo: Fetches from the database: uw_id, userid, term_id, registration_status, withdraw_code, projected_level, cumulative_gpa, standing_code, coop_term_type_code, coop_workterm_status_code, recent_and_future_plans, and most_recent_averages.

Grades: Fetches grades for courses matching a regex contained in courseRegEx.

FormElements: Decision Group:

ToDo.

I really doubt that this should be a FormElement. Seems like the whole thing should be one of the form’s top-level keys.

Restrictions:

This is a set of parameters that determine when and where the form can be used:

  • startAccepting: When to start accepting the form. Submissions are not allowed before this.
  • stopAccepting: When to stop accepting the form.
  • validPlanGroups: A list of plan groups. The student must belong to at least one of them to be able to submit the form.
  • invalidPlanGroups: A list of plan groups. The student must not belong to any of them to be able to submit.
  • allowMultipleSubmissions: If true, allow the form to be submitted several times (e.g. an override for a course; may need to override several).

ReportExpr:

A vector of vectors that determine how data is presented on the page that lists the forms for advisors. Each of the inner vectors had three parts:

  1. The header name for the table.
  2. An optional class name for HTML formatting.
  3. A Racket-like expression that consumes a json value and transforms it.

Valid expressions are poorly defined. Sources to consult for more information:

  • Existing forms.
  • The code in oat.xplatform.jsonExprInterp.
  • The test suite.

Operators include:

  • String concatenation (+)
  • Field selection (.)
  • map over a collection
  • cap the length of a string
  • cond for selection
  • At least some basic arithmetic.