TAssist User Guide

TAssist is a desktop app designed for CS2106 Teaching Assistants (TAs) to manage student records, optimized for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface(GUI). It provides:

• a simple, intuitive UI
• quick access to crucial student records, such as their contact, attendance and current grades
• high efficiency for fast typers
• human editable file formats for data persistence

CS2106 TAs can look forward to these attractive features that would assist their day-to-day tasks as a TA:

• Tracking a student's key school information like matriculation number, and handy information like their telegram handle
• Managing handy tags as reminders for students they may need to pay particular attention to
• Marking of tutorial attendance and updating of lab scores

---

Quick start

1. Ensure you have Java 17 or above installed in your Computer.
   Mac users: Ensure you have the precise JDK version prescribed here.

2. Download the latest .jar file from here.

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

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar TAssist.jar command to run the application.
   A GUI similar to the one below should appear in a few seconds. Note how the app contains some sample data.
   

5. 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.
   Note: For Windows users, copying text from a code block will result in the appending of an unknown symbol into your text. Do make sure that it is removed! Some example commands you can try:

   • list : Lists all contacts.

   • add -n John Doe -p 98765432 -e johnd@example.com -m A0123456J -t T01 : Adds a contact named John Doe to TAssist.

   • edit -i 1 -p 91234567 -e johndoe@example.com : Edits the phone number and email address of the 1st student to be 91234567 and johndoe@example.com respectively.

   • tag -a -i 1 -tag lateStudent : Adds a tag to the 1st student with the label lateStudent

   • del -i 3 : Deletes the student at index 3.

   • att -i 3 -w 5 : Marks the student at index 3 as attended tutorial in week 5.

   • export -f ./data/test.csv Exports the current data as a CSV file into the path ./data/test.csv

   • clear : Deletes all students.

   • exit : Exits the app.

• Tired of reading the user guide to understand how to use our app? Just type the command name (e.g. edit) into the command box to know more about how to use the command!

• Student particulars that you would not require on a regular basis can be hidden! Simply type toggle and they will disappear! Alternatively click on view → Compact View!
  

• To show more details about a particular contact, click on the contact itself!
  

• Refer to the Features below for details of each command.

  • Note that for all features below, the commands are all case-sensitive.

---

Features

Viewing help : help

Shows a message explaining how to access the help page.

Format: help

Listing all students : list

Shows a list of all students in TAssist.

Format: list

Toggling view : toggle

Toggles the student record view to be more compact. The following particulars of a student will be hidden if compact view is enabled where applicable: PHONE_NUMBER, TELEGRAM_HANDLE, EMAIL, YEAR and FACULTY.

Adding a student: add

Adds a student to TAssist.

Format: add -n NAME (-p PHONE_NUMBER -tg TELEGRAM_HANDLE) -e EMAIL -m MATRICULATION_NUMBER (-t TUTORIAL_GROUP -b LAB_GROUP) [-f FACULTY] [-y YEAR_OF_STUDY] [-r REMARKS] [-tag TAG]…​

Examples:

• add -n John -p 81234567 -tg @jornn -e e1234567@u.nus.edu -m A1234567X -t T02 -b B03 -f Computing -y 5 -r Likes to sing
• add -n Doe -tg @doe_a_deer -e e7654321@u.nus.edu -b B01 -m A7654321J

Notable Constraints:

• NAME, FACULTY, REMARK allows for most Unicode characters. Note that it is possible for some characters to be unable to be rendered, and the use of alphanumerics is highly recommended instead. This is to allow you (the user) to have freedom of customizing or using short forms as you please, though the onus would also be on you to remember them too!
• PHONE_NUMBER ranges from 4~15 digits following international guidelines.
• TUTORIAL_GROUP and LAB_GROUP each follow the same format: TXX and BXX respectively, where X refers to a single digit. You may input a single digit and the formatting will be handled by the application. e.g. T1 will be converted to T01 for you.
• Other unmentioned constraints will be prompted by the application itself when an invalid input for the particular field is provided.

Searching students: search

Search for students based on specific parameters. At least one parameter must be provided.

Format: search (-n NAME) [-p PHONE_NUMBER] [-e EMAIL] [-m MATRICULATION_NUMBER] [-t TUTORIAL_GROUP] [-b LAB_GROUP] [-f FACULTY] [-y YEAR_OF_STUDY] [-tag TAG]

• The search is case-insensitive (e.g., john will match John).
• The order of parameters does not matter.
• If multiple parameters of the same type are provided (e.g., -f SoC -f FoS), only the last one is used for searching.
• The search supports partial matching (e.g., jo will match John).

Parameters:

• -n: Search by student name
• -p: Search by phone number
• -e: Search by email address
• -m: Search by matriculation number
• -t: Search by tutorial group
• -b: Search by lab group
• -f: Search by faculty
• -y: Search by year of study
• -tag: Search by tag

Examples:

• search -n john returns students with names containing "john" (e.g., "John Doe", "Johnny")
• search -f Computing returns students from the Computing faculty
• search -t T01 returns all students in tutorial group T01
• search -tag lateStudent returns students tagged with "lateStudent"

Redo command: redo

Format: redo

Redo the last command that was executed. Refer to Undo Command for the list of commands supported.

Example:

1. Run a command lab -ln 1 -msc 25
2. undo (undo the command lab -ln 1 -msc 25)
3. Here you can still redo the command, but if you run something step 4:
4. list or att -i 1 -w 3
5. You cannot redo the lab -ln 1 -msc 25 command

Undo command: undo

Format: undo

Undo the last command that was executed.

Supported commands:

• add
• edit
• delete
• clear
• att
• lab
• tag

The following commands will ignore any changes:

• list
• exit
• help
• toggle
• search
• export
• load

Editing a student : edit

There are 2 possible ways to edit the students in the list.

1. Edit a single student

Edits an existing student in TAssist.

Format: edit -i INDEX [-n NAME] [-p PHONE_NUMBER] [-tg TELEGRAM_HANDLE] [-e EMAIL] [-m MATRICULATION_NUMBER] [-t TUTORIAL_GROUP] [-b LAB_GROUP] [-f FACULTY] [-y YEAR_OF_STUDY] [-r REMARKS]​

• Edits the student at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
• At least one of the optional fields must be provided.
• Existing values will be updated to the input values.
• The behaviour of the edit command depends on the field being edited:
  • For mandatory fields of a student: -n NAME, -e EMAIL, -m MATRICULATION_NUMBER, a valid input value must be provided to replace the current value.
    • E.g. edit -i 1 -n Alex is valid, editing the name of student of index 1 to Alex.
    • edit -i 1 -n 123!#$ is invalid, because 123!#$ is not a valid name.
    • edit -i 1 -n is invalid, because a student must have a name, which is a mandatory field.
  • There are two sets of conditional fields: Set 1: -p PHONE_NUMBER -tg TELEGRAM_HANDLE and
  • Set 2: -t TUTORIAL_GROUP -b LAB_GROUP. These are conditional fields, whereby AT LEAST ONE or BOTH of the fields in EVERY SET must have a valid input.
    • Providing a valid input value for either or both fields will always be supported as a valid edit.
    • The validity of the edit command depends on whether the student fulfills these conditions after the edit:
      • After the edit, the student has AT LEAST a valid PHONE_NUMBER OR a valid TELEGRAM_HANDLE.
      • After the edit, the student has AT LEAST a valid TUTORIAL_GROUP OR a valid LAB_GROUP.
    • E.g. if the student of index 1 currently has a valid PHONE_NUMBER but no valid TELEGRAM_HANDLE:
      • edit -i 1 -p 90001234 is valid, because he will still have a valid phone number after the edit.
      • edit -i 1 -tg @telehandle123 is valid, because he will have BOTH a valid phone number AND a valid teleHandle after the edit.
      • edit -i 1 -p is INVALID, because the proposed edit would make the student have NEITHER a valid phone number, NOR a valid teleHandle after the edit.
  • Optional fields like FACULTY, YEAR and REMARKS can be edited to any valid input (except YEAR), or empty input.
  • The valid range of YEAR is from 1 to 6

Examples:

• edit -i 1 -p 91234567 -e johndoe@example.com Edits the phone number and email address of the 1st student to be 91234567 and johndoe@example.com respectively.
• edit -i 2 -n Betsy Crower Edits the name of the 2nd student to be Betsy Crower.

2. Edit multiple students (Batch edit)

Edits several existing students in TAssist in one go.

Format: edit -i INDEX_RANGE [-t TUTORIAL_GROUP] [-b LAB_GROUP] [-f FACULTY] [-y YEAR_OF_STUDY]

• Edits the student at the specified INDEX_RANGE. The index must be a positive integer 1, 2, 3, …​
• At least one of the optional fields must be provided. (Only the 4 stated here can be edited. Any other fields will not be accepted.)
• Existing values will be updated to the input values.
• The valid range of YEAR is from 1 to 6

Examples:

• edit -i 1-3 -y 2 Edits the year of study for the 1st to 3rd students to be 2
• edit -i 1, 4, 5 -y 2 -f SOC Edits the year of study for the 1st, 4th and 5th students to be 2 and faculty to be SOC

Deleting student(s): del

Deletes the specified student(s) from the currently displayed list.

1. Delete a single student

Deletes one student from the currently displayed list. Format: del -i INDEX Details:

• Deletes the student at the specified INDEX.
• The index refers to the number shown in the current displayed list.
• The index must be a positive non-zero integer (e.g., 1, 2, 3...).
• Only one student will be deleted.

Example:

• del -i 2 → Deletes the second student shown in the current list view.

2. Delete multiple students (Batch delete)

Deletes multiple students in a single command using comma-separated indices or index ranges. Format: del -i INDEX[,INDEX or RANGE]... Details:

• Accepts:
  • Multiple indices: 1,3,5
  • Index ranges: 2-4
  • Mixed usage: 1,3-5,7 Commas , separate each index or range.
• Ranges use dashes - (e.g., 3-5 includes 3, 4, and 5).
• Indexes must be positive non-zero integers.
• All indices must be within the current list size.
• Ranges must be valid (e.g., 2-1 is not allowed).
• The -i prefix must be provided only once.
  • E.g.,
  • Valid: del -i 1,2
  • Invalid: del -i 1 -i 2

Example:

• del -i 1,3-5,7 → Deletes students at indices 1, 3, 4, 5, and 7.

Clearing all entries : clear

Clears all entries from TAssist.

Format: clear

Tagging a student: tag

There are 3 ways to tag a student.

1. Adding tags

Adds tag(s) to a student.

Format: tag -a -i INDEX [-tag TAG_NAME]...

• Adds tags to the student at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
• You need to add at least 1 tag. The tag will be added on top of the current tags the student has.
• The TAG_NAME must be alphanumeric and have a maximum of 60 characters.
• This is purely for adding. To edit and delete tags, look at Edit Tags and Delete Tags

Examples:

• tag -a -i 1 -tag lateStudent Adds a tag to the 1st student with the label lateStudent
• tag -a -i 1 -tag NeedHelp -tag AbleToCompete Adds a tag to the 1st student with the labels NeedHelp and AbleToCompete
  • The resultant tags will be sorted alphabetically.

2. Editing a tag

Edits a current tag.

Format: tag -m -i INDEX -tag OLD_TAG_NAME -tag NEW_TAG_NAME

• Edits the tag OLD_TAG_NAME and replaces the tag's value with NEW_TAG_NAME of the student at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
• You can only edit 1 tag at a time. The OLD_TAG_NAME must exist for you to edit and replace its value.
• The OLD_TAG_NAME and NEW_TAG_NAME must be alphanumeric and have a maximum of 60 characters.

Examples:

• tag -m -i 1 -tag lastStudent -tag earlyStudent Replaces the value of the lateStudent tag, of the 1st student, with earlyStudent
• tag -m -i 1 -tag NeedHelp -tag CanSurvive Replaces the value of the NeedHelp tag, of the 1st student, with CanSurvive

3. Deleting tags

Removes tag(s) from a student.

Format tag -d -i INDEX [-tag TAG_NAME]...

• Deletes the specified tags from the student at the specified INDEX. The index refers to the index number shown in the displayed student list. The index must be a positive integer 1, 2, 3, …​
• You must specify at least 1 tag when using this command. TAG_NAME is case sensitive and will only delete exact matches.
• The TAG_NAME must be alphanumeric and have a maximum of 60 characters.

Examples:

• tag -d -i 1 -tag earlyStudent Deletes the tag earlyStudent from student 1
• tag -d -i 1 -tag tag1 -tag tag2 Deletes the tags tag1 and tag2 from student 1

Marks attendance: att

Marks the attendance of an individual student, or a tutorial group.

Format: att (-i INDEX -t TUTORIAL_GROUP) -w WEEK [-mc] [-u] [-nt]

• Conditional parameters: EITHER -i INDEX OR -t TUTORIAL_GROUP, ONLY.
  • Not accepted: NEITHER of the flags provided, or BOTH flags provided together.
• Mandatory parameter: -w WEEK.
  • Not accepted: MISSING week flag
• Optional parameters: EITHER ONE OF -mc, -u, OR -nt
  • Not accepted: TWO or more of the above flags.

Note the following restrictions on the provided inputs.

• INDEX must be a positive integer, from 1 to n inclusive, where n is the number of students in the list.
  • In the case whereby n = 0, i.e. there are no students in the list, then you will need to minimally add one student with a valid tutorial group into the list, in order to use the Mark Attendance Command.
• TUTORIAL_GROUP must be a String of two OR three characters.
  • The first character must be a capital 'T' or small letter 't'.
  • The second (and optional third) character(s) must be numerical digit(s) from 0 to 9 inclusive.
  • Valid TUTORIAL_GROUP inputs include T1 (which is equivalent to T01), T02, t10.
  • Besides, note the additional restriction that a TUTORIAL_GROUP provided must be a tutorial group attribute of at least ONE student in the list. For example, if T99 is provided, but no students in the list are of tutorial group T99, then this is not a valid tutorial group that matches to any student, given the current list of students.
• Note that a valid index and tutorial group does NOT necessarily mean the command will be valid. There are other restrictions to fulfill, as illustrated by the parameters above and the additional restrictions below.

Passing in an invalid index will result in an error message.

Additional restrictions apply to the marking attendance command.

• Commands using the -i flag have additional restrictions.
  1. -nt flag cannot be used on a command with the -i flag. This means you cannot mark an individual as having No Tutorial.
     • If Alex of index 1 didn't attend Week 5 tutorial, mark him as Not Attended (or Unattended) using att -i -w 5 -u.
     • If Alex's tutorial group T01 falls on a public holiday, such that the Week 5 tutorial gets cancelled, mark the whole tutorial group as No Tutorial. Use the command att -t T01 -w 5 -nt.
  2. If the student specified by the INDEX has No Tutorial in the given week, the command is invalid. This means you cannot mark an individual to any attendance status, if he currently has No Tutorial.
     • Assume Alex of tutorial group T01 originally had their tutorial cancelled due to the public holiday. Now, the profs announce a make-up tutorial for T01 that everyone must attend (like normal tutorials).
       • First, mark the whole tutorial group as Not Attended, using att -t T01 -w 5 -u.
       • On the day of the makeup tutorial, you find that Alex (index 1) attended.
       • Then, mark Alex as having attended the tutorial, att -i 1 -w 5.
  3. If the student has a Blank Attendance List, any command on the student will be invalid.
     • Alex of index 1 has no TUTORIAL_GROUP (e.g. he is not in your tutorial group). Then it doesn't make sense to mark his attendance for any week.
     • If you realise Alex is actually in tutorial group T01, use the edit command to edit his TUTORIAL_GROUP to T01 first. Then you can use the mark attendance command on him.

Marking attendance for one student for a week he has no tutorial in, will result in an error message.

• You will need to mark his whole tutorial group as attended/not attended for the week first, before you can mark the individual index as attended/not attended.

Assuming the restrictions are satisfied,

• Marks the attendance of a student (if -i INDEX is provided) OR all students in a tutorial group (if -t TUTORIAL_GROUP is provided).
• The new attendance status is ATTENDED by default. However:
  • If -mc is provided, the new attendance status is ON MC.
  • If -u is provided, the new attendance status is NOT ATTENDED.
  • If -nt is provided, the new attendance status is NO TUTORIAL.

An example of a valid command to mark the attendance of individuals of indexes 5 and 6, as attended week 7's tutorial.

Examples:

• att -i 1 -w 3 marks the first student as attended Tutorial Week 3.
• att -i 2 -w 10 -mc marks the second student as on MC for Tutorial Week 10.
• att -t T01 -w 1 -nt marks the whole tutorial group T01 as No Tutorial for Tutorial Week 1.
  • This means each student in tutorial group T01 has his attendance updated to No Tutorial.
• att -i 1-5 -w 3 marks the students of indexes 1 to 5 (inclusive) of week 3 as Attended.

Updating lab scores: lab

Updates the lab score for the specified student, or update the maximum score for the specified lab.

3 ways of using this command

1. Update lab score: Updates the student INDEX lab LAB_NUMBER score to be NEW_SCORE.
   • Command format: lab -i INDEX -ln LAB_NUMBER -sc NEW_SCORE.
2. Update maximum lab score: Updates the lab LAB_NUMBER maximum score to be NEW_SCORE.
   • Command format: lab [-i INDEX] -ln LAB_NUMBER -msc NEW_SCORE.
   • Note that the maximum lab score is capped at 100. Scores above 100 will not be accepted.
   • Note that the -i flag is optional here as it will be ignored if it is provided.
3. Update both lab score and max lab score: Updates the student INDEX lab LAB_NUMBER score to be NEW_SCORE_1 and at the same time update lab LAB_NUMBER maximum score to be NEW_SCORE_2.
   • Command format: lab -i INDEX -ln LAB_NUMBER -sc NEW_SCORE_1 -msc NEW_SCORE_2.

Examples:

• lab -i 1 -ln 1 -sc 20 updates the first student lab score to be 20/25 (assuming default maximum score is not changed).
• lab -ln 2 -msc 35 updates the maximum score for lab 2 to be 35.
• lab -i 1 -ln 1 -sc 29 -msc 30 updates lab 1 maximum score to be 30 and also updates the first student lab score to be 29/30.

Load Data : load

Imports student data from an existing .csv or .json file.

Format: load -f FILE_NAME -ext FILE_EXTENSION

• The FILE_NAME should not include a file extension or path. It must refer to a file in the /data folder, e.g. userdata.
• The FILE_NAME must contain only alphanumeric characters, dashes, or underscores (e.g., my-data_123).
• Unlike the export command, the load command can only access files directly in the /data folder of the application. Full or relative paths with special characters (like ~ or /) are not supported.
• The FILE_EXTENSION must be either csv or json.
• The file must follow TAssist's expected format. Invalid or malformed data will be rejected with a warning.
• Duplicate records will be skipped with error messages shown.
• For CSV files, formatting errors (such as missing commas or incorrect number of fields) may cause the entire file to fail loading, with an appropriate error message displayed.

Examples:

• load -f userdata -ext csv loads a CSV file named userdata.csv located in the /data folder.
• load -f students -ext json loads a JSON file named students.json in the /data folder.

Export Data : export

Exports all the student data as CSV or JSON file. There are 2 ways to export data

1. Using the CLI:

Format: export -f FILE_PATH

• Exports the data to the FILE_PATH specified in this command.
• The FILE_PATH can either be relative to the current application OR be a full file path.
• The FILE_PATH must end either in a <filename>.csv or <filename>.json

Examples:

• export -f ./data/test.csv Exports the current data as a CSV file into the path ./data/test.csv
• export -f /Users/user_name/Desktop/data.json Exports the current data as a JSON file into the Desktop under data.json

2. Using the UI:

1. On the toolbar, go to Files > Export Data...
2. Select the file type (either JSON or CSV)
3. Select where you want to save your file at

Exiting the program : exit

Exits the program.

Format: exit

Saving the data

TAssist data is saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Editing the data file

TAssist data is saved automatically as a JSON file [JAR file location]/data/addressbook.json. Advanced users are welcome to update data directly by editing that data file.

---

FAQ

Q: How do I transfer my data to another Computer?
A: Install the app on the other computer and overwrite the empty data file it creates with the file that contains the data of your previous AddressBook home folder.

---

Known issues

1. 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. 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.

---

Command summary