User Guide

AcademySource is a streamlined contact management desktop app built for use via command-line interface (CLI), designed to help students stay connected with their academic network. It centralizes key contact details of professors and teaching assistants, removing the need to dig through emails or portals. With its simple and efficient CLI-based design, AcademySource lets you manage academic contacts quickly and effortlessly—so you can stay organized and focused on your learning journey.

With AcademySource, you can:

• Store and manage contact information of professors and TAs (e.g., email, phone number, role, module).
• Search for contacts by name, contact details, role, and/or module code.
• Mark important contacts as favorites for quick access.

Table of Contents

• Quick start
• Graphic User Interface Layout
• Keybinds
• Features

  - Prefix table
  - Modules Accepted by AcademySource
  - Viewing help
  - Listing all persons
  - Adding a person
  - Editing a person
  - Locating persons by name, phone, module and favourite
  - Mark / un-mark a person as favourite
  - Deleting a person
  - Clearing all entries
  - Exiting AcademySource
  - Saving the data
  - Editing the data file
  
• FAQ
• Known issues
• Command summary
• Glossary

Quick start

1. Ensure that you have Java 17 or above installed on your computer. Follow the steps below to check if you already have Java 17 installed:
   1. Navigate to your operating system’s terminal by following these steps:
      For Windows:

      1. Hold down Windows button and R (⊞ Win + R)
      2. Type cmd and press the Enter key
      For MacOS:

      1. Click the Launchpad icon in the Dock, type Terminal in the search field, then click Terminal, OR
      2. In the Finder, open the /Applications/Utilities folder, then double-click Terminal.
   2. Type java -version and press the Enter key.
   3. If Java 17 is installed, your terminal will look like this:
      On Windows:

      
       C:\Users\UserName>java -version
       java version "17.0.12" 2024-07-16 LTS
       Java(TM) SE Runtime Environment (build 17.0.12+8-LTS-286)
       Java HotSpot(TM) 64-Bit Server VM (build 17.0.12+8-LTS-286, mixed mode, sharing)
               

      On MacOS:

      
      user@username-MacBook-Air-3 ~ % java -version
      openjdk version "17.0.11" 2024-04-16 LTS
      OpenJDK Runtime Environment Zulu17.50+19-CA (build 17.0.11+9-LTS)
      OpenJDK 64-Bit Server VM Zulu17.50+19-CA (build 17.0.11+9-LTS, mixed mode, sharing)
               

2. If you have Java 17 installed, proceed to Step 3. If not, follow these instructions:
   1. Download Java 17 from here.
   2. Select the installation package based on your Operating System.
   3. Follow the instruction guide to install Java on your device. For more information, click here.
   4. Mac users: Ensure you have the precise JDK version prescribed here.
3. Download the latest version of AcademySource from here. Select academysource.jar to begin the download.
4. Copy the file to the folder you want to use as the home folder for AcademySource. Note: This will create additional files required for AcademySource in your home folder.
5. Open AcademySource by double-clicking the program file, academysource.jar. Alternatively, you may type java -jar academysource.jar into your terminal and press the Enter key.
   What you’ll see:
   On Windows:

   
   On Mac OS:

   

6. Type a command in the command box and press the Enter key to execute it. For example, typing help and pressing the Enter key will open the help window.
   Some example commands you can try:

   • list : Lists all contacts.

   • add n/John Doe p/98765432 e/johnd@example.com r/TA m/CS2103T : Adds a contact named John Doe to AcademySource with the phone number 98765432, email address johnd@example.com, role of TA and module CS2103T.

   • delete 3 : Deletes the 3rd contact shown in the current list.

   • clear : Deletes all contacts.

   • exit : Exits the app.

7. Refer to the Features section below for details of each command.

Graphic User Interface Layout 🔝

Basic features:

1. Menu Bar: A top menu bar that provides access to various functions within AcademySource.
2. Command Box: An input with a placeholder “Enter Command Here…” to enter commands into.
3. Result Display: A rectangular display box to display success message upon successful command execution, or error message upon failure.
4. Side Navigation: Buttons to navigate between the Modules and Contacts tab. Press their buttons or the Tab key to navigate between the two tabs.

Caution: Switching to Contacts tab by pressing tab or pressing on Contacts button will clear all filters on the list.

Modules Page:

1. Module Folder: A folder that stores contacts of a module code. Clicking a module folder will direct you to a page displaying contacts of that module code.

Caution: Commands can still be entered and work on the modules page, but the contact list is not visible. Thus, avoid entering commands that modify data (such as edit, delete) on the module page to prevent inadvertent actions.

Contacts Page:

1. Contact List: A list of contacts stored inside AcademySource. Each row stores a contact name card with their relevant details.
2. Role: The role in which each contact is assigned to. TA will be displayed as yellow bookmark while Professor will be displayed as orange bookmark.
3. Favourite Mark: A star symbol indicating contacts marked as favourite by you.

Keybinds 🔝

• Tab: Toggles between window between Modules and Contacts tab.
• Up Arrow (↑): Goes back to previous command in history.
• Down Arrow (↓): Goes forward to next command in history.

Features 🔝

Caution: AcademySource works best with standard English characters. Using characters from other languages (e.g., Arabic, Chinese, or Hebrew) or emojis may cause display and input issues. To keep things running smoothly, please stick to English characters.

Prefix Table 🔝

Note: Each prefix must be followed by at least one non-empty keyword. Empty keywords are not allowed for any of the prefixes.

Click here for find function prefix matching details

Modules Accepted by AcademySource 🔝

Viewing help : help 🔝

Shows a message with a URL to the help page.

Format: help

Listing all persons : list 🔝

Shows a list of all contacts in AcademySource.

Before command:

After command:

Format: list

Adding a person: add 🔝

Adds a contact to AcademySource.

Before command:

After command:

Format: add n/NAME p/PHONE_NUMBER e/EMAIL r/ROLE [t/TELEGRAM] [m/MODULE] [m/MORE_MODULES]…​

Tip: A person can have any number of modules (including 0)

• ROLE must be either ta or prof (Case-insensitive, which means TA or Prof are also valid).
• MODULEmust be one of the accepted module codes given in the module table.

Examples:

• add n/John Doe p/98765432 e/johnd@example.com r/prof m/CS2103T
• add n/Betsy Crowe e/betsycrowe@example.com p/1234567 r/TA m/CS2103T t/@johnd

Editing a person : edit 🔝

Edits an existing contact in AcademySource.

Before command:

After command:

Format: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [t/TELEGRAM] [m/MODULE] [m/MORE_MODULES]…​

• Edits the person at the specified INDEX. The index refers to the index number shown in the displayed person 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.
• Roles can not be edited.
• When editing modules, the existing modules of the person will be removed i.e adding of modules is not cumulative.
• MODULEmust be one of the accepted module codes given in the module table.

Examples:

• edit 1 p/91234567 e/johndoe@example.com Edits the phone number and email address of the 1st person to be 91234567 and johndoe@example.com respectively.
• edit 2 n/Betsy Crower m/ Edits the name of the 2nd person to be Betsy Crower and clears all existing modules.
• edit 2 m/CS2103T m/CS2106 Edits the module of the 2nd person to be CS2103T and CS2106.
• edit 2 t/ clears existing telegram for 2nd person.

Locating persons by name, phone, module, and favourites: find 🔝

Finds persons whose names contain any of the given keywords.

Before command:

After command:

Format: find [n/NAME_KEYWORDS] [p/PHONE_KEYWORDS] [mm/MODULE_KEYWORDS] [f/FAVOURITE_STATUS] [r/ROLE] [t/TELEGRAM_KEYWORDS] [e/EMAIL_KEYWORDS]

Prefix Matching Details:

• n/ — Supports case-insensitive and partial name matches.
• p/ — Supports partial phone number matches.
• mm/ — Supports case-insensitive and partial module code matches.
• f/ — Supports case-insensitive favourite status matches.
• r/ — Supports case-insensitive role matches.
• t/ — Supports case-insensitive and partial Telegram handle matches.
• e/ — Supports case-insensitive and partial email matches.

🔎 Search Behavior

• Case-Insensitive & Partial Matching:
  The search for names, phone numbers, and module codes is performed in a case-insensitive manner and supports partial keyword matching.
  Example: find n/john matches a person named “John Doe”.
• Keyword Order:
  For names, the order of keywords does not matter. For example, find n/Hans Bo matches “Bo Hans”.
• Single Instance per Prefix:
  Only one instance of each prefix is allowed. Repeating a prefix (e.g., n/John n/Doe) is not permitted.
• AND Combination:
  When multiple prefixes are specified (e.g., find n/John mm/CS2103T), a person must satisfy all criteria (i.e. the keywords across the different fields are combined using an AND operation) to be included in the results.

✅ Valid Examples

❌ Invalid Examples

Mark / un-mark a person as favourite : fav 🔝

Mark a specific person as favourite, or un-mark a person from favourite if that person is already marked as favourite. A star will be shown beside the person’s name if it is marked as favourite.

Before command:

After command:

Format: fav INDEX

• Toggles the favourite status of the person at the specified INDEX.
• The index refers to the index number shown in the displayed person list.
• The index must be a positive integer 1, 2, 3, …​

Examples:

• list followed by fav 2 marks the 2nd contact in AcademySource as favourite.
• fav 2 again un-marks the person.

Deleting a person : delete 🔝

Deletes the specified contact from AcademySource.

Before command:

After command:

Format: delete INDEX [MORE INDEX]

• Deletes the person at the specified INDEX.
• The index refers to the index number shown in the displayed person list.
• The index must be a positive integer 1, 2, 3, …​
• Index should not repeat in the same command.

Examples:

• list followed by delete 2 deletes the 2nd contact from the result of the list command.
• find Betsy followed by delete 1 deletes the 1st contact in the results of the find command.
• delete 1 2 3 deletes the first 3 contacts, given that all indexes exist within the contact list.

Clearing all entries : clear 🔝

Clears all entries from AcademySource.

Before command:

After command:

Format: clear

Exiting AcademySource : exit 🔝

Exits AcademySource.

Format: exit

Saving the data 🔝

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

Editing the data file 🔝

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

Caution: If your changes to the data file makes its format invalid, AcademySource will discard all data and start with an empty data file at the next run. Hence, it is recommended to take a backup of the file before editing it.
Furthermore, certain edits can cause AcademySource to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.

FAQ 🔝

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous AcademySource 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.
3. All commands are functional in Module Page, despite not able to see the details of contacts. Use list or find command to display the desired contacts before editing the contact list.
4. Using complex characters like emojis or script (Arabic and Hebrew) causes the command box input to behave in weird ways. Avoid entering these characters in the command box.
5. On the modules page commands can still be entered and work, but the contact list is not visible. Thus, avoid entering commands on the module page to prevent inadvertent actions.
6. If you are using OS Debian GNU/Linux 12 (bookworm) x86_64 with Gnome, you will realise you may be able to shrink the window size below the minimum dimension of 740x600. We currently have no workaround for this. If you are using this OS, please keep the window above the minimum dimension to prevent JavaFX rendering issues.

Command summary 🔝

Glossary 🔝