UniLink User Guide

UniLink is a desktop app that allows National University of Singapore (NUS) students to manage their contacts. With UniLink, students can categorise their contacts into 'work', 'personal' and 'school' contacts to better manage their lives!

---

Quick start

1. Set up Java

• Ensure you have Java 17 or above installed in your Computer.
• Not sure? Open up Command Prompt (for Windows) or Terminal (for Mac) and type java -version to check.
• Download Java [here] if needed.

2. Download UniLink

• Download the latest .jar file from here.

3. Choose a Home Folder

• Move the .jar file to where you want to store your UniLink data. This will be your 'home folder'.

4. Launch the app!

• Open Command Prompt (for Windows) or Terminal (for Mac) and navigate to the folder where your JAR file is located. Use the cd command followed by the path to the folder.

  • E.g. If my jar file is in a folder called 'Contacts', which is inside another folder called 'Uni' on my Desktop, I can navigate to it with cd Desktop/Uni/Contacts

• Run UniLink by typing java -jar UniLink.jar

• The app should open within a few seconds, showing some sample data that you can explore!

• Using the Command Line: New to the command line? Check out this Command Line for Beginners guide!

5. Try out some commands

• Type commands in the command box and press Enter to execute it. Here are some commands to get you started:

  • list : Lists all contacts.

  • add n/John Doe h/@johndoe ct/work : Adds a contact named John Doe to the Address Book.

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

  • exit : Exits the app.

• For the full list of commands, refer to Command Summary below for more details of each command.

---

Features

Viewing help : help

Shows a message and brings you to the help page when you click 'open URL'.

Format: help

Adding a person : add

Adds a person to the address book.

Format: add n/NAME ct/CONTACT_TYPE [h/TELEGRAM_HANDLE] [p/PHONE] [e/EMAIL] [m/MODULE] [r/REMARK] [t/TAG]…​

• At least one of TELEGRAM_HANDLE, PHONE or EMAIL must be provided to add a contact.

Examples:

• add n/John Doe ct/work h/@johndoe p/99887766 e/johndoh@gmail.com m/CS2030S t/friend
• add n/Betsy Crowe ct/personal t/friend h/@betsy_c r/likes cats t/criminal

Listing all persons : list

Shows a list of all persons in the address book.

Format: list

Editing a person : edit

Updates details for an existing person in the address book.

Format: edit INDEX [n/NAME] [ct/CONTACT_TYPE] [h/TELEGRAM_HANDLE] [p/PHONE] [e/EMAIL] [m/MODULE] [r/REMARK] [t/TAG]…​

• INDEX refers to the person's position in the displayed list (i.e. must be a positive integer 1, 2, 3...)
• At least one optional field must be provided.
• Existing values are replaced by the new input values.
• When editing tags, the existing tags of the person will be removed i.e adding of tags is not cumulative.
• You can remove all the person’s tags by typing t/ without specifying any tags after it.

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 h/@betsyyy t/ Edits the name and Telegram Handle of the 2nd person to be Betsy Crower and @betsyyy respectively and clears all existing tags.

Finding persons by name : find

Finds persons whose names contain any of the specified keywords.

Format:
find NAME [MORE_NAME_KEYWORDS]

• 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
• Only the name is searched.
• Only full words will be matched e.g. Han will not match Hans
• Persons matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang

Examples:

• find John returns john and John Doe
• find alex david returns Alex Yeoh, David Li

Finding persons by Telegram Handle : findtele

Finds persons whose Telegram Handles contain any of the specified keywords.

Format:
findtele TELEGRAM_HANDLE [MORE_TELEGRAM_HANDLE_KEYWORDS]

• 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
• Partial matches are allowed, and the '@' symbol may be omitted, meaning searching part of a Telegram Handle will still return contacts with the full Telegram Handle e.g. Hans will match @Hansgruber
• Persons matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang

Examples:

• findtele @john returns john and John Doe
• findtele alex david returns Alex Yeoh, David Li

Finding persons by tags : findtag

Finds persons whose tags contain any of the specified keywords.

Format:
findtag TAG [MORE_TAG_KEYWORDS]

• The search is case-insensitive. e.g friend will match Friend
• The order of the keywords does not matter. e.g. Friend Family will match Family Friend
• Partial matches are allowed, meaning searching part of a tag will still return contacts with the full tag (e.g. fam will match family)
• Persons matching at least one keyword will be returned (i.e. OR search). e.g. friend family will return all contacts with friend OR family as a tag

Examples:

• findtag friend returns John Doe and Betsy Crowe
• findtag neighbour family returns Charlotte Oliveiro, David Li

Filtering persons by contact type : filter

Filters persons by their contact type (i.e. work, school or personal).

Format: filter CONTACT_TYPE

• Displays a list of persons tagged with that CONTACT_TYPE
• CONTACT_TYPE can be either 'WORK', 'SCHOOL', or 'PERSONAL'
• The search is case-insensitive. e.g. 'work' is the same as 'WORK'

Examples:

• filter WORK returns all the 'work' contacts
• filter SCHOOL returns all the 'school' contacts
• filter PERSONAL returns all the 'personal' contacts

Deleting a person : delete

Deletes the specified person from the address book.

Format: delete 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, …​

Examples:

• list followed by delete 2 deletes the 2nd person in the address book.
• find Betsy followed by delete 1 deletes the 1st person in the results of the find command.

Clearing all entries : clear

Clears all entries from the address book.

Format: clear

Switching display theme : switch

Changes the display to 'light' mode or 'dark' mode.

Format: switch THEME

• Displays the THEME specified
• THEME can be light or dark
• THEME is case-insensitive. e.g. 'light' is the same as 'LIGHT'

Examples:

• switch LIGHT switches to the 'light' display theme
• switch DARK switches to the 'dark' display theme

Importing data : import

Imports contacts from a spreadsheet to the program.

Format: import

• Upon first loading UniLink you will find an Import folder
• Download a spreadsheet (.csv) file containing important contact info
• Move the spreadsheet(s) to the Import folder
• Running the import command will import all valid contacts to the program's addressbook

Note:

• If the program comes across a contact with an empty or invalid optional field (e.g., remark or address), the contact will still be imported, but those specific fields will remain blank after importing.
• Take note that the same constraints apply as when trying to add new contacts using the add command.
• Contacts with critical issues such as missing required fields (e.g., contactType) or invalid formats will be skipped during the import process, and no feedback will currently be provided for skipped entries. Additionally, if a contact already exists and a new import contains the same contact with more fields, it will be skipped as a duplicate without notification.
• For more information on making a .csv file to use with the import command, please refer to the section: Preparing a .csv file

Exiting the program : exit

Exits the program.

Format: exit

Saving the data

UniLink 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

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

---

Preparing a .csv file

A .csv file is simply one of the ways that you can save a spreadsheet file. Common ways to edit or prepare a spreadsheet and save it as a .csv file include Google Sheets, and Microsoft Sheets. UniLink uses spreadsheets and .csv files to help you easily compile, and distribute a large number of contacts quickly. Once you prepare one .csv file or spreadsheet, you can send it out so that many people can import contacts to their own copy of UniLink.

For this guide, we'll be giving you a sample spreadsheet to easily convert into a .csv file, as well as some things to note when preparing your spreadsheet!

To start, here is a sample spreadsheet for you to copy! There is already some sample data inside the sheet, feel free to edit that.

Constraints

Do take note of the following when preparing your contacts,

1. Do not try to import a .csv file that is empty.
2. Do not change the capitalisation of the sections at the top, if you do, UniLink will not be able to import your data correctly.
3. Note that the contact type can only be either Work, Personal or School. If that contact contains any other contact type, or no contact type, it will fail to import.
4. UniLink requires at least one of the following fields to be filled for it to import your contact: Email, Phone Number or Telegram Handle.
5. All the information needs to follow the constraints laid out in the Field Constraints section, if you do not fill in the information as per the constraints, UniLink will not be able to import the contact at all!
6. UniLink will skip over duplicate contacts! Contacts are considered duplicate when they share the same name AND they have the same email, phone number or Telegram Handle
   1. Example: If I have a contact called Amy, whose Telegram Handle is @Amy, and I try to import another contact, Amy, whose Telegram Handle is @Amy1, this will work.
   2. Similarly, trying to add Ben with Telegram Handle @Amy will not work.
   3. This is the case with emails, phone numbers and Telegram Handles
7. Do not import contacts from any other source (E.g Google contacts)

---

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 UniLink home folder.
Q: When adding contacts, do I HAVE to add a Telegram Handle, Phone Number or Email?
A: UniLink does require at least ONE of these fields to be filled before adding a contact.

---

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. [For macOS users] If you open the application in fullscreen and then use the help command, the Help Window may sometimes display visual glitches (such as a black background). Despite this, the application will continue to function normally after closing the Help Window.

---

Command Summary

---

Field Constraints

To ensure your commands work as expected, refer to the table below for guidance on each field’s requirements, including format and length. This way, you’ll know exactly how to input information like names, phone numbers, and other fields correctly. We’ve also included examples to make things easier!