User Guide

For full usability and interactive features (if you are reading this as a PDF), view this guide online:
https://ay2526s1-cs2103t-f13-1a.github.io/tp/UserGuide.html

Table of Contents

1. Welcome to UniContactsPro!
2. Quick Start
3. Understanding the Interface
4. Command Basics
5. Features
6. FAQ
7. Glossary
8. Known Issues
9. Acknowledgements

1. Welcome to UniContactsPro!

Welcome to UniContactsPro! We built this desktop app specifically for you, an undergraduate student, to finally get your school contacts organized and accessible.

Think of it as your personal digital address book for university. Whether you’re managing project groupmates, classmates for a single module, or your CCA contacts, UniContactsPro is here to help. Our goal is to make sure you never lose touch, especially with those people you aren’t close to but still need to contact.

Target Users

UniContactsPro targets undergraduate students who:

• Need to organize and manage university-related contacts, such as project groupmates, classmates, and CCA members.
• Are comfortable using a Command Line Interface (CLI) for efficient data entry and management.
• Prefer a keyboard-driven workflow for speed.
• Want a dedicated, local desktop application to keep track of connections.

What you need

All you need is a Mac, Window or Linux laptop with around 50MB of storage space! Have these and you are good to go!

Using this guide

For new users…

• We suggest that you start from the Quick Start section, to learn how to set up and learn about UniContactsPro from scratch

For existing users…

• Head over to Features to learn or refresh yourself with the features we have in store

For experienced users…

• Head over to our Command Summary table to quickly find the command format you are looking for!

If you are looking for a specific section of the guide, have a look at our Table of Contents.

2. Quick Start

Get up and running with UniContactsPro in minutes! Let’s go through a few simple steps to get you there…

System Requirements

• Operating System: Windows, macOS, or Linux
• Java Version: Java 17 or above

Installation & Launch

1. Download: Go to our GitHub releases page. In the most recent release, scroll down to the Assets section and download UniContactsPro.jar by clicking on the file.
2. Store: Create a new folder, named UniContactsPro for the application and place the downloaded .jar file inside it.
3. Run:
   • Open a command terminal (instructions for this is in previous section).
   • Navigate (using cd) to the folder you created in step 2.
   • Execute the following command:

       java -jar UniContactsPro.jar
     

cd Desktop/UniContactsPro

The application will launch, pre-filled with sample data for you to explore.

Your First Commands

Once the app is open, try these commands in the command box:

1. Get directed to the User Guide:

   help
   

2. Add a new contact:

   add n/John Doe p/91234567 e/john@example.com a/123 Street h/@johndoe c/5
   

3. View all contacts:

   list
   

4. Clear the sample data: (When you’re ready to add your own contacts)

   clear
   

3. Understanding the Interface

Main Components

• Menu Bar: Access File and Help menus (press F1 for help)
• Command Box: Type commands here and press Enter to execute
• Result Display: Shows feedback messages and command results
• Contact List: Displays contacts with index numbers
• Status Bar: Shows data file location and total contacts

Contact Card Details

Each contact shows:

• Index: Position in list (useful for commands)
• Name: Contact’s full name
• Phone: 8-digit number
• Email: Email address
• Address: Physical address
• Telegram Handle: Telegram handle
• Closeness: Closeness rating
• Tags: Categories/labels (if any)

Navigating Command History

Using Command Autocomplete

UniContactsPro uses an autocomplete system to help you type commands faster and reduce errors

How it works As you type in the command box, a dropdown box will appear with recognized command word suggestions

Keyboard Controls:

Mouse Support:

• Hover over a suggestion to highlight it
• Click to accept the suggestion

4. Command Basics

Command Structure

Commands in UniContactsPro are simple to follow! Below is the typical command format…

command_word prefix/ARGUMENT [prefix/ARGUMENT]...

Prefixes are in the format:

prefix/ARGUMENT

Prefixes have several variations with different notations:

Variadic prefixes refer to prefixes which can appear multiple times in one command. The only such prefix in UniContactsPro is t/.

Valid Prefixes

Format rules will be discussed in more detail in the next section, Parameter Rules.

Parameter Rules

Name (n/):

• Alphabets, numerical digits, spaces, hyphens (-), apostrophes (' or ’), or periods (.) only
• Must begin with a alphabet
• First letter and letters after aforementioned special characters are automatically capitalised (josh o'connor will be reflected as Josh O'Connor)
• Extra spaces trimmed

Phone (p/):

• Exactly 8 numerical digits
• Must start with 8 or 9
• No spaces allowed

Email (e/):

• Must be valid email format (Local-part@Domain name)
  • Local-part
    • Alphanumeric characters and these special characters +, _ + ., - only.
    • May not start or end with any special characters.
  • Domain name
    • Made up of domain labels separated by periods.
    • Must end with a domain label at least 2 characters long
    • Must have each domain label start and end with alphanumeric characters
    • Must have each domain label consist of alphanumeric characters, separated only by hyphens, if any.
• Example: user@example.com

Telegram handle (h/):

• Alphabets, integers and underscores
• Must begin with an @
• Must be between 5 and 32 characters inclusive
• Must not start with a number

Closeness (c/):

• Numerical values between 1 and 5 inclusive

Tags (t/):

• Alphanumeric only
• Can specify multiple

5. Features

Adding Contacts

Command: add n/NAME p/PHONE e/EMAIL a/ADDRESS h/TELEGRAM HANDLE [t/TAG]... c/CLOSENESS

Example:

add n/John Doe p/91234567 e/john@example.com a/123 Street h/@johndoe t/friend c/5

Name formatting :

• Name is not case-sensitive. The first character of each word is capitalised, leaving the rest of the characters in lower case (eg. JOHN DOE, jOhN dOe will all be recorded as John Doe)
• The character following a non-alphabet character or a space will be capitalised (eg. L'oreal will be saved as L'Oreal, E-shin will be saved as E-Shin, j.k. rowling will be saved as J.K. Rowling)
• Additional spaces between two words will be trimmed to one, trailing white spaces are trimmed

Email formatting :

• Email is not case-sensitive. All characters will be saved in lower case (eg. jOhNdOe@gmAiL.cOm, JOHNDOE@GMAIL.COM will both be saved as johndoe@gmail.com)
• Periods(.) in the local part (text before the @) are ignored (eg. ter.e.s.ata.n@gmail.com will be saved as teresatan@gmail.com)
• Suffixes of + are ignored in the local part, since regardless of the plus suffixes, emails still go to the same inbox (eg. teresatan+amazon@gmail.com will be saved as teresatan@gmail.com)

Duplicates

• Two people are considered duplicates if they have either of the same fields :
  • Phone number
  • Email address (after email formatting)
  • Telegram handle

Success: Contact added with confirmation message:

New person added: John Doe; Phone: 91234567; Email: john@example.com; Address: 123 Street; Closeness: 5; Tags: [friend]

Errors:

The following error message is the “Invalid command format!” error message for this command:

Invalid command format! Check command convention!
add: Adds a person to the address book. Parameters: n/NAME p/PHONE e/EMAIL a/ADDRESS [t/TAG]... h/TELEGRAM HANDLE 
Example: add n/John Doe p/98765432 e/johnd@example.com a/311, Clementi Ave 2, #02-25 t/friends t/owesMoney h/@johndoe c/5

Even with correct command format, the following errors are possible if the user input does not adhere to the paramater rules.

• Invalid name
• Invalid phone number
• Invalid email format
• Invalid telegram handle
• Invalid tag format
• Invalid closeness rating

If the user’s input has multiple such parameter-related issues present, the error message corresponding to the first erratic prefix is printed.

Finally, the error message for trying to add a duplicate person is as follows:

This person already exists in the address book

Editing Contacts

Command: edit INDEX [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [h/TELEGRAM HANDLE] [c/closeness] [t/TAG]...

Example:

edit 1 p/98765432 e/newemail@example.com

Success: Contact edited with confirmation message:

Edited Person: John Doe; Phone: 98765432; Email: newemail@example.com; Address: 123 Street; Closeness: 5; Tags: [friend]

Errors: The following error message is the “Invalid command format!” error message for this command:

Invalid command format! Check command convention!
edit: Edits the details of the person identified by the index number used in the displayed person list. Existing values will be overwritten by the input values.
Parameters: INDEX (must be a positive integer) [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]...[h/HANDLE] [pp/PROFILE_PICTURE] [c/CLOSENESS]
Example: edit 1 p/91234567 e/johndoe@example.com

If the INDEX provided by the user is invalid, the following error message is produced:

The person index provided is invalid

Last but not least, the invalid prefix argument errors, as well as the duplicate person error from the add command are also possible for this command. The error messages are the same as well.

Adding Profile Picture

Adding a new image with a from a local file path

Command: addProfilePic INDEX pp/ImageFilePath.png

Example:

addProfilePic 1 pp/~/Downloads/example.png

Adding an existing image with ONLY the file name

Command: addProfilePic INDEX pp/imagename.png

Example:

addProfilePic 1 pp/example.png

Success:

Deleting Contacts

Command:

delete INDEX [MORE_INDEXES]...
delete all t/TAG

Examples:

delete 1
delete 1 2 3
delete all t/friends

Success: Single Deletion: Shows deleted contact(s) details. For example…

Deleted Person: Harry Kane; Phone: 91115432; Email: kane@example.com; Address: 210, Clarke Ave 3, #02-36; Closeness: 5; Tags: [friends]

Multiple Deletion: Shows number of deleted contacts. For example…

Deleted 2 People:
Homie; Phone: 88965432; Email: honnd@example.com; Address: 23, Clementi Ave 7, #02-25; Closeness: 5; Tags: [friends]
Lionel Messi; Phone: 98768888; Email: messid@example.com; Address: 31, Clementi Ave 2, #02-15; Closeness: 5; Tags: [friendsssssssssssss]

Errors:

If there is no contact found corresponding to a specified INDEX, the same invalid index error from the edit command occurs.

Listing Contacts

Command: list

Shows all contacts in order added (oldest first).

Searching Contacts

The find command allows users to search for contacts according to their names. Even partial matches to the KEYWORD are supported.

Command: find KEYWORD [MORE KEYWORDS]...

Example:

Given a contact book with the following state:

All of the following commands should result in only Alex being displayed:

find Al
find Alex
find ex
find Al ex

Success:

Shows the list of contacts with name matching the keyword. Successful execution message also states number of contacts displayed. For example…

1 persons listed!

Errors: If no KEYWORD is input by user, the following “Invalid command format” message is shown:

Invalid command format! Check command convention!
find: Finds all persons whose names contain any of the specified keywords (case-insensitive) and displays them as a list with index numbers.
Parameters: KEYWORD [MORE_KEYWORDS]...
Example: find alice bob charlie

Filtering by Tag

The filter command allows users to filter their contact list by tags. All contacts with a tag matching the TAG arguments will be shown.

Command: filter t/TAG [t/MORE_TAGS] ...

Example:

Given a contact book with the following state:

The following command will result in only Alex and Bernice being displayed:

filter t/friends

Success:

Shows the list of contacts with the respective tag. Successful execution message also states number of contacts displayed, similar to find.

Errors: The “invalid command format” message is shown when the user either misses the prefix t/. The message is as such:

Invalid command format! Check command convention!
filter: Filters and lists all persons who have at least one of the specified tags (case-insensitive) 
Parameters: t/KEYWORD [t/MORE_KEYWORDS]... 
Example: filter t/friends t/colleagues

If any of the user’s TAG arguments are invalid, the invalid tag error message is shown, similar to delete and edit.

Sorting Contacts

Contacts can be sorted by Closeness. The sortByCloseness command can sort the contacts either by ascending or descending order in terms of Closeness.

Command: sortByCloseness o/[asc|desc]

Examples: Given a contact book with the following state:

The following command:

sortByCloseness o/desc

results in the contact book looking like this:

Success:

Shows successful execution message stating order in which sort has been performed as shown below:

Sorted contact list by closeness (descending)

Errors:

If the user does not input any order after the prefix o/, does not specify the prefix at all, or enters and invalid ORDER argument, the following “Invalid command format” message is shown:

Invalid command format! Check command convention!
sortByCloseness: Sorts the contact list by closeness rating.
Parameters: o/{asc|desc}
Example: sortByCloseness o/desc

Note:

Clearing All Contacts

Command: clear

This command clears all the contacts in UniContactsPro.

Getting Help

Command: help

Opens help window with the User Guide link.

Exiting

Command: exit

Closes the application. Data is automatically saved.

6. FAQ

Storage and transfer of data

Q: Is my data automatically saved? A: Yes, all changes are saved immediately.

Q: Where is my data stored? A: In addressbook.json in the same folder as unicontactspro.jar.

Q: How do I transfer data to another computer? A: Copy the addressbook.json file to the new computer’s UniContactsPro folder.

Q: What if my data file gets corrupted? A: Keep regular backups of addressbook.json. The app will start with an empty list if the file is corrupted.

Commands

Q: Can I undo a command? A: No, undo is not currently supported. Be careful with delete and clear.

Q: Are commands case-sensitive? A: Command words are not case-sensitive.

Q: Why does editing tags replace all existing tags? A: This is intentional. To keep existing tags, specify them along with new ones.

Q: Can I search by phone or email? A: Currently, only name search is supported via the find command.

Q: How do I transfer data to another computer? A: Copy the addressbook.json file to the new computer’s UniContactsPro folder.

Q: What if my data file gets corrupted? A: Keep regular backups of addressbook.json. The app will start with an empty list if the file is corrupted.

7. Glossary

CLI (Command Line Interface)

A text-based way of interacting with software by typing commands.

Closeness

How close the user perceives him or herself to be in relation to the contact.

Command Box

The text input field where you type commands. Press Enter to execute.

Contact Card

Visual representation of a contact showing index, name, phone, email, address, and tags.

Index

The number shown next to each contact in the list. Used in commands to specify which contact. Starts at 1.

JSON

File format used to store contact data (addressbook.json). Not recommended to edit manually.

Parameter

Information provided to a command using prefixes. Example: n/John, p/91234567.

Prefix

The identifier before a parameter value, ending with /. Examples: n/, p/, e/, t/.

Tag

A label or category assigned to a contact for organization. Must be alphanumeric, maximum 15 characters.

Variadic

A command or prefix that can accept multiple values, entered one after another—for example, add t/friend t/CS2103T t/project uses variadic tags (you can add several tags at once).

8. Known Issues

Invalid address book file
Description: If the addressbook.json file is corrupted with missing or incorrect fields (as a result of external tampering it), the app may show an empty contact list but won’t alert you. Note: Keep regular backups, do not directly edit addressbook.json. Restore from backup or contact support if data disappears unexpectedly.

Image not deleted with contact
Description: When deleting a contact, their attached photo remains in the images folder, causing unnecessary storage use over time.
Note: Manually remove unused images from the folder when deleting contacts.

Intermittent loading issues
Description: Contacts may fail to load or show incomplete data after restarting; issue is not consistent and may be due to sync errors.
Note: Save and exit fully before closing the app. If issue persists, check the addressbook file or restart again.

Unclear email errors
Description: Invalid emails cause ambiguous error messages, making it hard to know which part is wrong.
Note: Check both local-part and domain formatting. Refer to the Parameter Rules for correct format.

Multiple app instances
Description: Running multiple windows of the app creates conflicts, as data does not sync and there are no warnings.
Note: Only use one app window at a time. Restore from backup if changes are lost.

Silent data loss on JSON corruption
Description: Corrupt addressbook.json files cause the app to start with an empty list, with no warnings about lost data.
Note: Backup data regularly. Restore from backup or sample data if contacts disappear.

Delete command message missing closeness
Description: The delete command’s success message shows contact details but omits the “closeness” value.
Note: Closeness information may need to be checked manually if needed after deletion.

9. Acknowledgements

UniContactsPro is developed as part of the CS2103T Software Engineering module at the National University of Singapore.

Project Team

• darzizalol - GitHub
• he-yue-svg - GitHub
• fifamobilegems - GitHub
• ravichandran-gokool - GitHub

Built On

This project is based on the AddressBook-Level3 (AB3) project created by the SE-EDU initiative.

Libraries and Tools

• JavaFX - GUI framework
• Jackson - JSON processing
• JUnit5 - Testing framework

Contact and Support

• Visit our GitHub Repository
• Report issues at GitHub Issues