Better Call TA User Guide

BetterCallTA enables Teaching Assistants to effortlessly manage your students' contacts. Optimized for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI), BetterCallTA handles all the nitty gritty details of your session so that you can focus on delivering the best to your students.

Overview

This section covers the overview of BetterCallTA application.

🎯 Target audience

NUS Teaching Assistants (TA) who can type fast, preferring typing over mouse/voice commands.

✨ Value proposition

Better Call TA is a contact management platform for teaching assistants to manage the details of students in their class(es) as well as relevant administrative details, such as their attendance, participation and grades.

πŸ€” Assumptions

  • You are familiar with the formats for certain fields in NUS (e.g. NUS Student ID format, Course format)
  • You do not have a student who is in your session for two (or more) different courses.

πŸ“ Notations

  • Angular brackets < number x '(list of characters) > means choose number from the list of characters, allowing duplicates. For example:
    • <2 x (A B C)> means choose two of A, B or C. </2>
    • <(0-2) x (A-Z)> means choose 0 to 2 of any capital letters.

Table of Contents

This section covers the table of contents of our user guide for BetterCallTA.

Quick start

This section covers how to get started on using BetterCallTA

  1. Ensure you have Java 17 or above installed in your Computer.

    • If you do not have it installed, follow the instructions here, selecting your appropriate Operating System (OS).

  2. Download the latest .jar file from here.

  3. Copy the file to the folder you want to use as the home folder for BetterCallTA.

  4. Open a command terminal (refer to the Glossary for a recommended terminal) and use the cd command with the folder you put the jar file in.

    • For example, cd .\Downloads

  5. Use the java -jar BetterCallTA.jar command to run the application.

    • A GUI similar to the one below should appear in a few seconds.

    Ui
    Fig 1 - Example User Interface (UI)

  6. Type the command in the command box and press Enter ↡ to execute it. e.g. typing help and pressing Enter will open the help window.

    Here are some example commands you can try:

    Command Description
    add /id A3478231B /name John Doe /phone 98765432 /email johnd@example.com Adds a student with the ID A3478231B to the application.
    edit /id A3478231B /attendance present /participation good /grade 84 Edits the attendance, participation and grade of the student with ID A3478231B to PRESENT, GOOD and 84 respectively.
    delete /id A1234567B Deletes the student with ID A1234567B in the student list.
    list Lists all students.
    clear Deletes all students.
    exit Exits the app.

Do refer to the Features below for details of each command!

Student

This section covers the Student field used in BetterCallTA, which encapsulates a student contact details in BetterCallTA.

Student descriptor
Fig 2.1 - Example Student

πŸ“ Note:
All of the attributes apart from student ID can hold duplicate values for different students. So please be careful when addressing other potential conflicts.

Properties

ID-Unique student identifier

Format:

<1 x (A/U/HT/NT)> + 7 digits + <1 x (A/B/E/H/J/L/M/N/R/U/W/X/Y)>
πŸ“Œ ID Format Rules Follows NUS Student ID format:
  • Student ID is case-sensitive
  • Must start with A, U, HT, or NT
  • Starting letters must be followed by 7 digits
  • Must end with one of: A, B, E, H, J, L, M, N, R, U, W, X, Y

Examples:

  • A0738475N
  • HT0347856U

Name-Your student name

Multiple students with the same name are allowed, as long as they have a unique Student ID.

Tips
  • All unicode strings are accepted for name. For example,
    • ι™ˆζŽ is accepted
    • X Γ† A-12 Musk is accepted

Phone-Student phone number

πŸ“Œ Phone Number Format Rules
  • Can start with +
  • Otherwise, must only contain numbers (0-9) or -
  • Cannot contain consecutive hyphens
  • Cannot start or end with hyphens
  • Must be at least 7 digits long and no more than 15 digits long

Default: 00000000

Example:

  • 86566289
  • +65-8576-9485

Email-Student email address

Format:

local-part@domain
πŸ“Œ Email Format Rules
Local-Part:
  • Only alphanumeric characters (a-z, A-Z, 0-9) and these special characters are also allowed: +, _, ., -
  • No other symbols are allowed
  • Cannot start or end with special characters
Domain:
  • Must end with domain label of at least 2 characters
  • Each label must:
    • Start and end with alphanumeric characters
    • Contain only alphanumerics and periods

Note
This is not a comprehensive list of all the constraints that an email address must satisfy.

Default: example@u.nus.edu

Valid Examples:

  • johndoe@u.nus.edu
  • example32@gmail.com

Course-NUS course code

Format:

<(2/3) x (A-Z)> + 4 digits + <(0-2) x (A-Z)>
πŸ“Œ Course Format Rules
  • Must start with 2 or 3 letters
  • Followed by exactly 4 digits
  • May optionally end with up to 2 letters

Default: AAA0000AA

Valid Examples:

  • CS2103T
  • IS1108
  • MA1101R

Attendance-Student class participation status

Status Description Case Sensitivity
PRESENT Present Case-insensitive
ABSENT Absent without valid reason Case-insensitive
EXCUSED Absent with valid reason Case-insensitive
πŸ“Œ Attendance Format Rules
  • Only the above status values are valid
  • Matches must be exact (e.g., "Absent" not "Absent again")
  • Input can be in any capitalization (e.g., "Present" or "PRESENT")

Default: UNMARKED

Participation-Student engagement level

Status Description Case Sensitivity
EXCELLENT Outstanding contribution Case-insensitive
GOOD Above average participation Case-insensitive
AVERAGE Meets basic expectations Case-insensitive
POOR Minimal or insufficient engagement Case-insensitive
NONE No observable participation Case-insensitive
πŸ“Œ Participation Format Rules
  • Only the above status values are valid
  • Matches must be exact (e.g., "Good" not "Good enough")
  • Input can be in any capitalization (e.g., "Excellent" or "EXCELLENT")

Default: UNMARKED

Grade-The predicted grade of your student based on their previous graded assignments

πŸ“Œ Grade Format Rules
  • You can only enter an integer from 0 to 100 (inclusive), or NA (case insensitive)

Notes-Additional details that you may want to keep about individual students

  • You can attach any number of notes to each student.
  • If a student has multiple notes, for example NOTE 1 and NOTE 2, it will be displayed as [NOTE 1, NOTE 2] in the command output window.

Multiple Notes Output
Fig 2.2 - Output of adding multiple notes to a student

Features

This section covers all the features of BetterCallTA. Navigate to the following sections to know more about BetterCallTA features.

Command Syntax Notes

This section covers the Command Syntax Notes you should be aware of when you are using BetterCallTA.

Command Syntax Notation

Notation Meaning Example
UPPER_CASE Required parameters you must provide add /id ID β†’ add /id A1234567X
[square brackets] Optional parameters add /name NAME [/phone PHONE_NUMBER] β†’ Can omit the /phone part
... (ellipsis) Parameter can be repeated multiple times /note NOTE... β†’ Can add multiple notes

Command Syntax Rules

Rule Description Example
Parameter Spacing Parameters must have a trailing space add /idA123 /nameJohn will not work.
It should be changed to add /name John /id A123 instead.
Parameter Order Parameters can be in any order add /id A123 /name John = add /name John /id A123
Extraneous Parameters Extra parameters are ignored for simple commands help 123 β†’ Treated as help
PDF Copy-Paste Warning Watch for missing spaces when copying from PDFs Ensure /idA123 becomes /id A123 when pasting

✨ Recommended Best Practices for Command Syntax

  1. βœ… Required Parameters

    • Must always be provided for commands that require them.
    • Example: ID in delete /id ID

  2. ❓ Optional Parameters

    • Can be omitted if not needed.
    • Example: Phone number in contact creation.

  3. βž• Repeated Parameters

    • Can add multiple instances where supported.
    • Example: Multiple notes for a student.

  4. βœ‚οΈ Format Preservation

    • Maintain exact spacing when copying commands.
    • Test commands after pasting from external sources.
Note:
  • There must be exactly one space between the flag and the argument provided. For instance, /flag arg1 is valid whereas /flagarg1 (no spaces) and /flag arg1 (with two spaces) are invalid.

Viewing Help: help

Shows a message explaining how to access the help page.

Format:

help

Help Message Example
Fig 3.1 - Pop-Up window from entering help command

Adding a Student: add

Adds a student to the application.

Format:

add /id ID /name NAME [/phone PHONE_NUMBER] [/email EMAIL] [/course COURSE] [/note NOTE...]

Examples:

  • add /id A4235352H /name John Doe /phone 98765432 /email johnd@example.com /note Consistently late
  • add /id A4045018Y /name Betsy Crowe /email betsycrowe@example.com /phone 1234567 /course CS4215
Tips
  • If phone, email, course or note are not specified, their default values will be used instead. They can manually be changed by the Edit command.


Add Command Example
Fig 3.2 - Output of
add /id A4235352H /name John Doe /phone 98765432 /email johnd@example.com /note Consistently late

Editing a Student: edit

Edits an existing student in the application.

Format:

edit /id ID [/newid NEW_ID] [/name NAME] [/phone PHONE_NUMBER] [/email EMAIL]
[/course COURSE] [/attendance ATTENDANCE] [/participation PARTICIPATION] [/grade GRADE] [/note NOTE…]

Notes:

  • Edits the student with the specified ID.
  • Only the specified properties will be updated. Other properties will remain as they were previously.
Warning
  • At least one optional field must be provided
  • Not more than one of each optional field should be provided
  • The new ID must not already be used by a different student

Example: edit /id A0123456N /phone 91234567 /email johndoe@example.com

This will update the phone number and email of the student with ID A0123456N to 91234567 and johndoe@example.com respectively.


Edit Command Example
Fig 3.4 - Output of
edit /id A0123456N /phone 91234567 /email johndoe@example.com

Deleting a Student: delete

Deletes the specified student from the application.

Format:

delete /id ID
  • Deletes the student with the specified ID.
  • The ID refers to the ID belonging to the student in the student list.

Examples:

  • delete /id A1234567N deletes the student with ID A1234567N.
  • delete /id A7654321B deletes the student with ID A7654321B.

Delete Command Example
Fig 3.7 - Output of delete /id A1234567N

Clearing All Entries: clear

Clears all entries from the application.

Format:

clear

If there are no students in BetterCallTA, an error message will be shown.

Alert!

The entire list will be permanently deleted and cannot be recovered, so proceed with caution.


Clear Command Example
Fig 3.11 - Output of clear

Locating Students by Name, ID or Course: find

Finds students whose names, IDs or courses contain any of the given keywords.

Format:

find KEYWORD [MORE_KEYWORDS]
Tips
  • The search is case-insensitive, e.g hans will match Hans
  • The order of the keywords does not matter, e.g. Hans Bo will match Bo Hans
  • Students matching at least one keyword will be returned (i.e. OR search),
    e.g. Hans Bo will return Hans Gruber , Bo Yang
  • Partial words are also matched e.g. Han will match Hans

Examples:

  • find John returns john and John Doe
  • find alex david returns Alex Yeoh, David Li
  • find A1234 returns students with ID numbers that start with A1234

Find Command Example
Fig 3.5 - Output of find alex david

Sorting Your List: sort

Sorts your current list by exactly one of four parameters: name, grade, attendance or participation.

Format:

sort /by <1 x (name/grade/attendance/participation)>
Tips
  • The keywords are case-insensitive, e.g grade will match Grade
  • To sort by multiple parameters, you must sort them one command at a time, in any order
  • The sort order for each keyword is as follows (name: special characters first, then numerical digits from 0 to 9, then Aa to Zz | grade: 100 to 0 | attendance: Present > Excused > Absent > Unmarked | Participation: Excellent to Unmarked)

Warning
  • Exactly one field must be provided
  • The list will not automatically sort if you add more people or change student parameters. You must apply the sort again.

Examples:

  • sort /by name will arrange your list in alphabetical order.
  • sort /by grade will arrange your students by their grade scores in descending order.

Sort Command Example
Fig 3.6 - Output of sort /by grade

Listing All Students: list

Shows a list of all students in the application.

Format:

list

List Command Example
Fig 3.3 - Output of list

Saving Contact Data: file /save FILENAME

BetterCallTA data is automatically saved to addressbook.json in [JAR file location]/data/ by default unless the save file is modified with the file /load command.

Change the save file that the application will store data to with file /save.

Format

file /save SAVE_FILE
  • Modify the save file location as specified with SAVE_FILE in [JAR file location]/data/ as SAVE_FILE.json.

Examples:

  • file /save CS2103T-T10-3
Alert!
  • You do NOT need to specify the .json file extension as it will automatically be added by our application. If you attempt to include the file extension type SAVE_FILE, such as save.json, an error message will be shown.
  • Only alphanumeric characters and the following symbols are allowed: -, _, (, ). All other symbols are not allowed.
  • If SAVE_FILE.json already exists in the data directory, it will be overwritten.
  • It is recommended NOT to modify the saved SAVE_FILE.json directly as it may introduce unintended behaviour in the application.


File Save Command Example
Fig 3.8 - Output of file /save CS2103T-T10-3

Loading Contact Data: file /load FILENAME

BetterCallTA data will load the most recent save file that was used in the application by default. Save files can be loaded with the file /load command.

Change the .json save file that the application will read/save from with file /load.

Format

file /load SAVE_FILE
  • Load the specified save file [JAR file location]/data/SAVE_FILE.json to the current working application. Subsequent operations will be saved to the loaded SAVE_FILE.json file.

Examples:

  • file /load CS2103T-T10-3
Warning
  • If the save file you attempt to load contains illegal characters, it will not be loaded
  • The addressbook save file will be loaded by default.


File Load Command Example
Fig 3.9 - Output of file /load CS2103T-T10-3

Listing Save Files: file /list all

BetterCallTA stores all save files in [JAR file location]/data/ and the file /list all command will list out all .json save files in that directory (without the file extension type), as well as indicating the current save file that is being in use by the application as indicated by (current save file).

Format

file /list all

Lists out all the .json save file filenames (without the file extension type) stored by the application in the /data/* directory.

Examples:

  • file /list all

File List All Command Example
Fig 3.10 - Output of file /list all
* Actual output may be different depending on what files are in [JAR file location]/data/


![Clear Command Example]

Resetting All Attendance and Participation Records: resetRecords

Resets the attendance and participation status of all students to UNMARKED.

Format

resetRecords
Warning
  • If there are no students in BetterCallTA, or all students have their attendance and participation status UNMARKED, an error message will be shown.


Reset Records Command Example
Fig 3.12 - Output of resetRecords

Exiting the Program: exit

Exits the program.

Format:

exit

⚠️ Warning for Advanced Users You can update the data directly by editing the file, but be cautious.

  • Saving the application data with the file /save FILE command will overwrite the FILE.json save file if it already exists
  • Manually editing the .json file can introduce syntax errors, rendering the file unreadable by BetterCallTA. Validate your .json syntax using a JSON linter before attempting to load it.

Additional Features

Graph Visualisation

A histogram that shows the grades of all students in the current list.

Automatically updates when a grade is changed.

Tips
  • Grades with the value NA will be ignored by the histogram
  • Divider between list and histogram can be dragged to resize the widths of both sections.

Histogram Example
Fig 4 - Example of a populated graph

FAQ

This section covers some common questions that BetterCallTA users face.

Q: How do I transfer my data to another Computer πŸ’»?
A: Copy the save files stored in [home folder]/data/ over to the new Computer [home folder]/data/ location.

Q: Can I sort students by multiple criteria (e.g., sort by grade, then by name)?
A: The sort command only supports sorting by one criterion at a time. To sort by multiple parameters, you must use separate sort commands for each.

Q: How do I know the correct format for student IDs?
A: Student IDs must follow the NUS student ID format: <1 x (A/U/HT/NT)> + 7 digits + <1 x (A/B/E/H/J/L/M/N/R/U/W/X/Y)>.

Q: Does BetterCallTA support international phone number formats?
A: Yes, BetterCallTA supports phone numbers starting with a + and allows hyphens, as long as the length is between 7 and 15 digits.

Q: If I edit a student, and leave some fields blank, what happens?
A: If you edit a student, and only specify some fields, the other fields will remain as they were before the edit.

Q: What happens if I accidentally delete a student?
A: Deleted students are removed permanently. BetterCallTA does not have an undo function. Regularly backing up your save files is recommended.

Q: Why are command words not case-insensitive?
A: Command words are case-sensitive as we expect you TAs to not want to waste time capitalising the command word. For the same reason, prefixes are also case-sensitive. However, the parameters are case-insensitive as we understand different users have different ways of entering certain fields.

Q: Can I add a student without an email address?
A: Yes, the email field is optional.

Q: Is there a limit to the number of students I can add?
A: There is no hard limit, but performance may degrade with a very large number of students.

Known issues

This section covers the current known issues with BetterCallTA.

  1. Multi-Screen Issue:
    When using multiple screens, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the preferences.json file created by the application before running the application again.

  2. Minimized Help Window Issue:
    If you minimize the Help Window and then run the help command (or use the Help menu, or the keyboard shortcut F1) again, the original Help Window will remain minimized, and no new Help Window will appear. The remedy is to manually restore the minimized Help Window.

  3. Save File Corruption:
    In the event of an unexpected application crash or system failure during a save operation, the save file (.json) may become corrupted. Regularly backup your save files. If a file is corrupted, restore from a backup.

Command summary

This section covers the summary of commands in BetterCallTA.

Action Format Examples
Show Usage help (None)
Add add /id ID /name NAME [/phone PHONE_NUMBER] [/email EMAIL] [/course COURSE] [/note NOTE…​] add /id A0123456E /name James Ho /phone 22224444 /email jamesho@example.com
Delete delete /id ID delete /id A3456712E
Edit edit /id ID [/newid NEW_ID] [/name NAME] [/phone PHONE_NUMBER] [/email EMAIL] [/course COURSE] [/attendance ATTENDANCE] [/participation PARTICIPATION] [/grade GRADE] [/note NOTE…]​ edit /id A0123456N /phone 91234567 /email johndoe@example.com
Clear clear (None)
Find find KEYWORD [MORE_KEYWORDS] find James Jake
Sort sort /by KEYWORD [name/grade/attendance/participation] sort /by name
List all users list (None)
Save Data file /save SAVE_FILE file /save CS2103T-T10-3
Load Data file /load SAVE_FILE file /load CS2103T-T10-3
List Save Files file /list all (None)
Reset Attendance and Participation Records resetRecords (None)

Glossary

This section covers the glossary of key terms as discussed in this User Guide and in other BetterCallTA documentation.

Term Definition
TA Teaching Assistant - Supports the instructor in teaching a course by conducting tutorials, grading assignments, and assisting students
CLI Command Line Interface - Text-based interface for interacting with software
GUI Graphical User Interface - Visual interface with graphical elements
NUS National University of Singapore - Institution where this system is primarily used
ID Student Identification Number - Unique identifier following NUS format
Home folder The folder in your file system that serves as your personal storage space
Command terminal Powershell on Windows, Terminal on Mac and Linux
Unicode A text encoding standard maintained by the Unicode Consortium designed to support the use of text in all of the world writing systems that can be digitized.