data_coNdUctorS User Guide

data_coNdUctorS is a desktop address book application for managing contact details of members in NUS Co-Curricular Activity (CCA) groups. It is optimised for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, data_coNdUctorS can get your contact management tasks done faster than traditional GUI apps.

---

Table of Contents

• Quick Start
• Command Summary
• Features
  • General Notes about Command Format
  • Adding a Contact: add
  • Editing a Contact: edit
    • Edit by index
    • Edit by name
  • Deleting a Contact: delete
    • Delete by index
    • Delete by name
  • Finding Contacts by Contact Details: find
  • Listing all Contacts: list
  • Viewing Help: help
  • Clearing all Entries: clear
  • Exiting the Program: exit
  • Displaying Contacts in Pages: Pagination
  • Showing Total Number of Contacts: Footer Status Bar
  • Saving the Data
  • Editing the Data File
• What is Considered as Invalid Contacts
• Contact Fields Constraints
  • Name
  • Telegram Handle
  • Email
  • Student Status
  • Role
  • Nickname
• FAQ
• Known Issues

---

Quick start

1. Ensure you have Java 17 or above installed in your Computer.

2. Download the latest .jar file from here.

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

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar data_coNdUctorS.jar command to run the application. A GUI similar to the below should appear in a few seconds.

   Note how the app:

   • Contains some sample data
   • Displays contacts in alphabetical order
   • Utilises Pagination where 10 contacts are displayed per page at any one time
   • Shows both the number of contacts listed in the displayed pages and the total number of contacts stored in the application in the status bar footer
   
   

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.
   Some example commands you can try:

   • list: Lists all contacts.
   • add n/John Doe th/johnny_9876_haha ss/undergraduate 3 e/johnd@example.com r/Admin: Adds a contact named John Doe to the Address Book application.
   • delete 3: Deletes the 3rd contact shown in the current displayed list.
   • clear: Deletes all contacts.
   • exit: Exits the app.
   
   

6. Refer to Command Summary for a general overview of the commands available.

7. Refer to Features below for the details of each command feature and UI features.

Command Summary

---

Feature Details

---

Adding a Contact: add

Format:add n/NAME th/TELEGRAM_HANDLE e/EMAIL s/STUDENT_STATUS r/ROLE…​ [nn/NICKNAME]

Examples:

• add n/John Doe th/johndoe e/johnd@example.com ss/undergraduate 3 r/Admin r/President nn/altName
• add n/Betsy Crowe th/betsycrowe e/betsycrowe@example.com ss/masters r/President r/Admin
• add n/Alex Yeoh th/alexyeoh123 e/alexyeoh@example.com ss/masters r/President r/Admin

Editing a Contact: edit

In both methods of editing:

• Only contacts shown in the displayed list can be edited.
• After the command is successfully executed, the full contact list will be displayed.
• At least one of the optional fields must be provided.
• Existing values will be updated to the input values.
• When editing roles, the existing roles of the contact will be removed.

Edit by index

Format: edit INDEX [n/NAME] [th/TELEGRAM_HANDLE] [e/EMAIL] [ss/STUDENT_STATUS] [r/ROLE]…​ [nn/NICKNAME]

• Edits the contact at the specified INDEX.
• The index refers to the index number shown in the displayed contact list.
• The index must be a positive integer 1, 2, 3, …​ (if the number given is larger than MAX_INT (2147483647), it will be treated as a non-zero unsigned integer)

Examples:

• edit 1 th/johndoe123 e/johndoe@example.com
  Edits the telegram handle and email address of the 1st displayed contact to be johndoe123 and johndoe@example.com respectively.
  
• edit 2 r/Admin r/President
  Edits the roles of the 2nd displayed contact to be Admin and President, this replaces all existing roles of the contact.

Edit by name

Format: edit FULL_NAME [n/NAME] [th/TELEGRAM_HANDLE] [e/EMAIL] [ss/STUDENT_STATUS] [r/ROLE]…​ [nn/NICKNAME]

• Edits the contact specified by FULL_NAME.
• The FULL_NAME has to be an exact match to an existing contact which is displayed.
• The FULL_NAME is not case-sensitive.

Examples:

• edit alex yeoh th/johndoe123 e/johndoe@example.com
  Edits the telegram handle and email address of the contact Alex Yeoh to be johndoe123 and johndoe@example.com respectively.

Deleting a Contact: delete

Delete by index

Format: delete INDEX

• Deletes the contact at the specified INDEX.
• The index refers to the index number shown in the displayed contact list.
• The index must be a positive integer 1, 2, 3, …​ (if the number given is larger than MAX_INT (2147483647), it will be treated as a non-zero unsigned integer)

Examples:

• list followed by delete 2 deletes the 2nd contact in the address book.
• find n/alex followed by delete 1 deletes the 1st contact in the results of the find command.

Delete by name

Format: delete FULL_NAME or delete n/FULL_NAME

• Delete the contact whose name matches the specified FULL_NAME.
• Only contacts shown in the displayed contact list will be deleted.
• find n/alex followed by delete Amy Gould would not work, since Amy Gould would not be displayed.
• The FULL_NAME has to be an exact match to an existing contact in the displayed list.
• The FULL_NAME is not case-sensitive.

Examples:

• Both delete Amy Gould and delete n/Amy Gould delete the user whose name is Amy Gould (not case-sensitive) in the address book.

Finding Contacts by Contact Details: find

Format: find [n/NAME] [th/TELEGRAM_HANDLE] [e/EMAIL] [ss/STUDENT_STATUS] [r/ROLE]…​ [nn/NICKNAME]

• Role field [r/ROLE]:
  • Can be repeated any number of times e.g. find r/Vice President r/Admin → valid
  • Have to take a valid role value (Refer to role constraints)
    e.g. find r/pres → invalid
    e.g. find r/President → valid
  • Not case-sensitive e.g. find r/pResiDent → valid
  • Specifying multiple roles returns contacts holding all specified roles. e.g. find r/Vice President r/Admin will only return contacts holding both roles.
• All other fields [n/NAME] [th/TELEGRAM_HANDLE] [e/EMAIL] [ss/STUDENT_STATUS] [nn/NICKNAME]:
  • The order of the keywords does not matter. e.g. query Hans Bo will match Bo Hans.
  • Substring matching e.g. query Han will match Hans, but query Hans will not match Han.
  • Each keyword is treated as a separate substring e.g. both keywords in query Hans Ansbo will match Hansbo.
  • Contacts matching only one keyword will not be returned (i.e. AND search). e.g. query Hans Bo will match Hans Boey and Hans Jobo but not Hans Gruber.

Examples:

• find n/john returns Johnny Tan and John Doe.
  
• find n/harlot olive ss/masters returns Charlotte Oliveiro, who holds the student status masters.
  
• find r/Admin r/President returns Joanna Carroll who holds both roles, but not Alex Yeoh who only holds the role Admin.
  

Listing all Contacts: list

Format: list [all]... [contacts]... [allcontacts]...

Viewing Help: help

Format: help

This also prompts the user to do help COMMAND_WORD where COMMAND_WORD refers to:

• add
• edit
• delete
• find
• list
• clear
• exit

From this, the user can get a quick reminder on how to use the various commands without having to refer to the User Guide.

Clearing all Entries: clear

Format: clear

Exiting the Program: exit

Format: exit

---

Displaying Contacts in Pages: Pagination

The app comes with a pagination at the bottom of the list. It supports navigation to a specific page or navigation to the next or previous page. Each page contains a maximum of 10 items. The pagination supports a maximum of 10 pages being displayed at one time, to access more pages, one can go to the last page shown at the bottom and click on NEXT page button to access other pages.

Alternatively, users can make use of left and right arrow keys on the keyboard to navigate to the previous and next page. To do this, users need to make sure that they have at least one click on the pagination before using keyboard to make sure that the app is focusing on the pagination component.

Pagination UI:

Showing Total Number of Contacts: Status Bar Footer

A status bar that contains information about the number of contacts in the list and the address book data file path is attached as a footer at the bottom of the app. It shows the total number of contacts being listed in the app.

Examples:

• find n/Adam may show only 1 contact out of 19. 1 refers to the number of found contacts, 19 refers to the total number of contacts in the address book.

Saving the Data

AddressBook 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

AddressBook data are 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.

---

What is Considered as Invalid Contacts

Identity conflict:

• No two contacts are allowed to share the same identity in the address book.
  
• Two contacts are considered to have the same identity if they share the same Name and Nickname.
  
• Note that Nickname is case-sensitive, e.g. nn/alice and nn/Alice are considered different nicknames.

Duplicate fields

• No two contacts are allowed to share the same fields for Telegram Handle, Email, and Nickname.
• Note that Telegram Handle, Email, and Nickname are all case-sensitive, and will only be considered duplicate entries if the case matches exactly.
• In the entire address book, there can only be 1 President.

For example, if there are contacts with the following data:

• n/Alice Tan th/alicetan123 e/alicetan123@example.com ss/phd r/Marketing
• n/John Doe th/johndoe e/johnd@example.com ss/undergraduate 3 r/Admin r/President nn/Johnny
  

Assuming the above entry in the address book, the following parameters passed into edit / add are considered valid / invalid:

Contact Fields Constraints

• By default, all fields inputted after the prefix must be non-empty when prefix is specified (except nn/).

Name

• Must contain English alphabets and spaces only, with the following exceptions:
  • @, S/O, D/O in the middle of the name is allowed. e.g.Ravi S/O Ramasamy
  • A blank space must come before and after S/O or D/O
  • (INSERT_NAME) at the end of the name is allowed. e.g. Gianna (Gian)
• Must not be blank.
• Will be automatically converted to Start Case (i.e. Only the first letter of every word is in upper-case) except for D/O and S/O which will automatically converted to upper case.

Telegram Handle

• Must contain alphabets, numbers and underscores only.
• Must have a length between 5 and 32 characters inclusive.
• Must not include @.

Email

• Emails must be of the format LOCAL_PART@DOMAIN.
• LOCAL_PART
  • Must only contain alphabets, numbers, and special characters +_.-.
  • Must not start or end with any special characters.
• DOMAIN
  • Domains must end with a domain label at least 2 characters long.
  • Each domain label must only contain alphabets, numbers, and -, if any.
  • Each domain label must not start or end with -.
  • Domain does not have to include a period ., e.g. .com, .edu etc

Student Status

• Must take one of the following values:
  1. Undergraduate x (where x is an integer between 1 and 6 inclusive).
  2. Masters
  3. PhD

Role

• Each contact may take on multiple roles.
• Each role must take one of the following values:
  1. President
  2. Vice President
  3. Admin
  4. Marketing
  5. Events (Internal)
  6. Events (External)
  7. External Relations

Nickname

• Is an optional field.

---

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 AddressBook home folder.

Q: How do I update a contact's information?
A:Use the edit command followed by the contact's index or name and the new details. For example, edit 1 n/Updated Name th/new_handle.

Q: Why is my newly added contact not showing on the first page?
A: Contacts are sorted alphabetically by default. If the contact’s name falls further down the list, it may appear on a later page. Use pagination controls to locate it.

Q: What happens if I add a contact with the same name but a different nickname?
A: As long as the nickname differs, the contact will be added without conflict. However, identical Nickname and Name entries are flagged as duplicate identities and will not be allowed.

Q: Why are undergraduate 1 to 6 being allowed? Isn't it typical for undergraduates to only have 4 years of study?
A: Some undergraduate students such as those with a double degree programme has a maximum candidature period of 6 years.

Q: Why is my command returning an "Invalid Role" error?
A: Ensure roles are entered in the exact format expected by the app. An "Invalid Role" error may indicate that a role was mistyped or included with extra symbols, such as [ ].

Q: Can I undo a deletion?
A: Currently, deletions are final and cannot be undone. Always double-check before using the delete command to avoid accidental deletions.

Q: Can I add or edit or delete multiple contacts within a single command?
A: This functionality is not supported.

Q: How can I search for contacts without case sensitivity?
A: Searches are case-insensitive, so you can enter names, nicknames, or other fields without worrying about uppercase or lowercase letters.

Q: After executing the find command, why can't the display continue to show the filtered list if I add or edit a contact immediately after?
A: This functionality is not supported. Adding or editing a contact will show the full list of contacts with the updated change made as the display (i.e., as if list command has been executed after add or edit command is executed).

---

Known Issues

1. When using multiple screens, if the user moves the application to a secondary screen, and later switches 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. When inputting duplicate contact, if the user edits a contact with the same NAME and NICKNAME as an existing contact currently produces an unclear message ("This contact already exists in the address book"), but could instead display the conflicting contact details and clarify the duplicated fields.

3. When a wrong field is inputted, running add n/John Doe th/johnny_9876_haha e/johnd@example.com ss/undergraduate 3 r/Admin r/President [nn/altName] outputs a vague error message ("Invalid Role"), which should specify the unrecognised role "President [".

4. Case Sensitivity for Some Contact Fields: Some contact fields, such as Nickname, Telegram Handle, and Email, are currently case-sensitive, which may lead to duplicate entries when similar contacts with different cases are loaded into the address book.

5. Delayed Display of Newly Added Contact: If a contact is added but does not appear immediately on the first page, it may be due to the alphabetical sorting. Users may need to navigate through pages to locate newly added contacts if their names fall further down alphabetically.