User Guide

KeyContacts allows you to

• Keep track of your students' contacts, grade levels and pieces.
• Easily view all your scheduled lessons for the week at a glance through our calendar view.
• Schedule, cancel and make-up lessons for your students.

KeyContacts is optimized for use via keyboard commands while still being aesthetically pleasing and easy to use. If you type fast, you can complete your contact management tasks much faster with KeyContacts than with mouse-based apps.

---

Table of Contents

• Quick Start
• Command Overview
• Student Commands
  • Adding a student: add
  • Deleting a student: delete
  • Editing a student: edit
  • Assigning piano pieces to a student: assign
  • Unassigning piano pieces from a student: unassign
• Lesson Commands
  • Scheduling a regular lesson: schedule
  • Scheduling a makeup lesson: makeup
  • Cancelling a lesson: cancel
  • Uncancelling a cancelled regular lesson: uncancel
• General Commands
  • Viewing help: help
  • Listing all students: list
  • Viewing the schedule: view
  • Finding students: find
  • Sorting students: sort
  • Clearing all entries: clear
  • Undoing the last command: undo
  • Redoing the last undone command: redo
  • Exiting the program: exit
• FAQ
• Known issues
• Command Summary

---

Quick start

1. Ensure you have Java 17 or above installed in your Computer.
   • To check your java version, refer here.
   • If you don’t have Java 17 installed, you can download it here.

2. Download the latest keycontacts.jar file from our releases page here.
   • Scroll down until you reach Assets, then click on keycontacts.jar.

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

4. Open a command terminal of your preference (e.g. Command Prompt on Windows, Terminal on Mac) from your home folder.

   • On Windows, right-click the folder and select Open in Terminal.

• On MacOS, right-click the folder and select Services, then New Terminal at Folder.

5. Run the command: java -jar keycontacts.jar.

   You will see the app appear, filled with sample data:

   

6. Type a command in the command box and press Enter to execute it.
   Example: Typing help and pressing Enter will open the help window.

   Some example commands you can try:

   • list : Lists all students.
   • add n/John Doe p/98765432 a/John street, block 123, #01-01 gl/ABRSM 3 : Adds a student named John Doe to the student directory.
   • schedule 2 d/mon st/08:00 et/10:00 : Schedules a weekly recurring lesson for the 2nd student on Monday from 8am to 10am.
   • delete 3 : Deletes the 3rd student shown in the current list.
   • clear : Deletes all students.
   • undo : Undoes the last update to the student directory.
   • exit : Exits the app.

---

Command Overview

The commands you can use in KeyContacts are split into 3 different types:

• Student Commands
• Lesson Commands
• General Commands

Let's walk you through some basics of the command format.

Each command consists of a command word, and zero or more parameters.

• Words in UPPER_CASE are the parameters to be supplied by you.
  Example: In add n/NAME, NAME is a parameter which can be used as add n/John Doe.

• The parameter INDEX (e.g. in the command format delete INDEX) specifies the student to perform the operation on. INDEX refers to the index number shown in the displayed student list (at the top left of each student card). INDEX must be a positive integer, i.e. 1, 2, 3...

• Parameters in square brackets are optional.
  Example: [g/GROUP] can be omitted or used as g/Group One.

• Parameters with …​ after them can be used multiple times.
  Example: pn/PIECE…​ can be used as pn/Moonlight Sonata, pn/Moonlight Sonata pn/Ode to Joy etc.

• Parameters can be in any order (excluding INDEX, which must follow the command word).
  Example: If the command specifies n/NAME p/PHONE_NUMBER, p/PHONE_NUMBER n/NAME is also acceptable.

• Extraneous parameters for commands that do not take in parameters (i.e help, list, undo, redo, exit and clear) will be ignored.
  Example: If the command specifies help 123, it will be interpreted as help.

---

Student Commands

A student has a name, phone number, address, grade level and optionally, a group.
Students with the same group name (case-insensitive) will have synced lessons.

Listed below are the currently supported student commands.

Adding a student : add

Adds a student to the student directory.

Format: add n/NAME p/PHONE_NUMBER a/ADDRESS gl/GRADE_LEVEL [g/GROUP]

• If a group is not provided, or left blank (g/), the student will not be assigned to any group.
• If an existing group is provided, the student will be assigned all the lessons of the other students in the group.

Examples:

• add n/John Doe p/98765432 a/John street, block 123, #01-01 gl/LCM 1 adds a student named John Doe with phone number 98765432, address John Street, block 123, #01-01, grade level LCM 1, and no group.

• add n/Mary Sue p/87654321 a/Mary avenue, block 51, #10-10 gl/ABRSM 1 g/Jack's Group adds a student named Mary Sue with phone number 87654321, address Mary avenue, block 51, #10-10, grade level ABRSM 1 and group Jack's Group. Mary Sue will have Jack's Group's lessons.

Deleting a student : delete

Deletes the specified student from the student directory.

Format: delete INDEX

• Deletes the student at the specified INDEX.

Examples:

• delete 2 deletes the 2nd student.

Editing a student : edit

Edits an existing student in the student directory.

Format: edit INDEX [n/NAME] [p/PHONE] [a/ADDRESS] [gl/GRADE_LEVEL] [g/GROUP]

• Edits the student at the specified INDEX.
• If the group is left blank (g/), the student will be removed from any existing group.
• Removing a student from a group also removes all the student's lessons.
• Existing values will be updated to the input values.
• You must provide at least one of the optional fields.

Examples:

• edit 1 n/Jane Doe p/91234567 edits the name and phone number of the 1st student to be Jane Doe and 91234567 respectively.
• edit 1 n/Penelope g/ removes the 1st student from their group, while also editing their name to be Penelope.
• edit 2 g/Jack's Group moves the 2nd student into the group Jack's Group. The 2nd student will also be updated to have Jack's Group's lessons.

Assigning piano pieces to a student : assign

Assigns piano pieces to a student in the student directory.

Format: assign INDEX pn/PIECE_NAME...

• Assigns piano pieces to the student at the specified INDEX.
• Existing piano pieces will remain.

Examples:

• assign 1 pn/Etude pn/Moonlight Sonata adds Etude and Moonlight Sonata to the 1st student's piano pieces.

Unassigning piano pieces from a student : unassign

Unassigns piano pieces from a student in the student directory.

Format: unassign INDEX [pn/PIECE_NAME]...

• Unassigns piano pieces from the student at the specified INDEX.
• All piano pieces provided must already be assigned to the student.
• If no piano pieces are provided, all piano pieces will be unassigned from the student.

Examples:

• unassign 1 pn/Etude pn/Moonlight Sonata removes Etude and Moonlight Sonata from the 1st student's piano pieces.
• unassign 2 clears all the 2nd student's piano pieces.
  
  

---

Lesson Commands

Each student can have one regular lesson in the same timeslot every week. You can also create make-up lessons and cancel lessons for each student.

Listed below are the currently supported lesson commands.

Scheduling a regular lesson : schedule

Schedules a weekly recurring regular lesson for the specified student in the student directory.

Format: schedule INDEX d/DAY st/START_TIME et/END_TIME

• Schedules the regular lesson for the student at the specified INDEX.
• Regular lessons are synced across students in the same group.
• If the student already has an existing regular lesson, it will be overwritten by the new regular lesson.
• DAY must be a day of the week (e.g. Monday, Tuesday etc.) or its 3-letter abbreviation (e.g. Mon, Tue etc.). This parameter is case-insensitive.
• START_TIME and END_TIME must be in 24-hour format (HH:MM), and START_TIME must be before END_TIME.

Example:

• schedule 1 d/Tuesday st/16:00 et/18:00 schedules a regular lesson every Tuesday, 4-6pm for the 1st student.

Scheduling a makeup lesson : makeup

Schedules a makeup lesson for the specified student in the student directory.

Format: makeup INDEX dt/DATE st/START_TIME et/END_TIME

• Schedules the makeup lesson for 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, …​
• Makeup lessons are synced across students in the same group.
• DATE must be a valid date in the format DD-MM-YYYY.
• START_TIME and END_TIME must be in 24-hour format (HH:MM) and START_TIME must be before END_TIME.

Examples:

• makeup 1 dt/25-12-2024 st/12:00 et/14:00 schedules a makeup lesson on 25th December 2024, 12-2pm for the 1st student.

Cancelling a lesson : cancel

Cancels a lesson for the specified student in the student directory.

Format: cancel INDEX dt/DATE st/START_TIME

• Cancels a lesson for the student at the specified INDEX, on the specified DATE that starts at the specified START_TIME.
• Cancellations are synced across students in the same group.
• DATE must be a valid date in the format DD-MM-YYYY.
• DATE must match the student's lesson DATE, and START_TIME must match the student's lesson START_TIME.
• START_TIME must be in 24-hour format (HH:MM).

Example:

• cancel 1 dt/15-10-2024 st/16:00 cancels a lesson on 15th Oct 2024, starting at 4pm for the 1st student.

Uncancelling a cancelled lesson : uncancel

Uncancels a cancelled lesson for the specified student in the student directory.

Format: uncancel INDEX dt/DATE

• Uncancels a regular lesson for the student at the specified INDEX.
• Uncancelling a lesson removes it from the student's cancelled lesson list.
• DATE must be a valid date in the format DD-MM-YYYY.
• DATE must match the student's cancelled lesson DATE.

Example:

• uncancel 1 dt/20-10-2024 uncancels a regular lesson on 20th Oct 2024 for the 1st student.

---

General Commands

Listed below are the currently supported general commands.

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 the student directory.

Format: list

Viewing the schedule : view

Displays the lesson schedule for the specified week.

Format: view [dt/DATE]

• If no date is provided, the current date will be used.
• DATE must be in the format DD-MM-YYYY.

Examples:

• view displays the schedule for the current week.
• view dt/01-11-2024 displays the schedule for 28 Oct 2024 (Monday) to 3 Nov 2024 (Sunday).

Finding students : find

Finds students whose personal details match inputs.

Format: find [n/NAME_KEYWORD] [p/PHONE_KEYWORD] [a/ADDRESS_KEYWORD] [gl/GRADE_LEVEL_KEYWORD] [g/GROUP_KEYWORD]

• The search is case-insensitive. e.g hans will match Hans.
• Only the name, phone number, address, grade level and group is searched.
• Partial inclusion of a keyword will be considered a match. e.g ng will match huang.
• Students matching all fields will be returned (i.e. AND search). e.g. n/Hans p/98765432 will return Hans Gruber; 98765432, but not Hans Goretzka; 12345678.
• You must provide at least one of the optional fields.

Examples:

• find n/John returns all students with John in their name, such as john and Johnny Doe.
• find n/will p/8765 returns all students with will in their name and phone number containing 8765, such as
  william; 87654321 but not will; 12341234.

Sorting students : sort

Sorts students based on personal details.

Format: sort [n/ASC or DESC] [p/ASC or DESC] [a/ASC or DESC] [gl/ASC or DESC] [g/ASC or DESC]

• The order of prefixes matters. If there are ties in the first field, later fields will be used to tie-break.
• Only name, phone number, address, grade level and group are valid fields to sort by.
• The sorting order must be ASC (ascending) or DESC (descending), and is case-insensitive.
• You must provide at least one of the optional fields.

To clear the sorting conditions, use the command sort clear.

Examples:

• sort n/ASC sorts the students by name in ascending order.
• sort gl/DESC n/ASC sorts the students by grade level in descending order, and tie-breaks using name in ascending order.

Clearing all entries : clear

Clears all entries from the student directory.

Format: clear

Undoing the last command : undo

Undoes the last command that modified the student directory.

Format: undo

Redoing the last undone command : redo

Restores any changes that were previously undone using the undo command.

Format: redo

Exiting the program : exit

Exits the program.

Format: exit

---

FAQ

How do I save my data?
Student directory data is saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Help, why does it keep telling me that my date needs to be a valid date?
Firstly, make sure that your date exists (take note of the 29th of February on non-leap years). Next, make sure that your date is following the DD-MM-YYYY format (pay attention to the hyphens in between).
Example: 30-10-2024 is allowed, while 30/10/2024 is not allowed.

Can I edit the saved data file manually?
Student directory data is saved automatically as a JSON file at [JAR file location]/data/studentdirectory.json.
Advanced users are welcome to update data directly by editing that data file.

How do I transfer my data to another computer?
You can do so by copying the data file over to the other computer as follows:

1. Copy the studentdirectory.json file in the data folder over to the other computer.
2. Download KeyContacts in the other computer.
3. Run KeyContacts in the other computer. This will generate a data folder containing a sample studentdirectory.json file.
4. Replace this sample data file with the data file you copied from your previous computer.

---

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