LegacyLink User Guide

This image was generated by Midjourney

Welcome to LegacyLink! 👋

LegacyLink is your all-in-one family contact and event management solution, combining the speed of keyboard (CLI, standing for Command Line Interface) commands with the convenience of a modern interface.

Perfect for managing both small, close-knit families and large extended family networks!

🎯 Key Features

---

🚀 Quick Start Guide

---

1. System Setup

1. Download and install Java 17 from the Java downloads page.
2. To check if Java is correctly installed:
   1. Open your computer's command prompt/terminal * Windows: Press Win + R, type cmd, and press Enter * Mac: Open Terminal from Applications
      • Type java -version and press Enter
      • You should see a version number 17, something like the image below.
        

2. Download LegacyLink

1. Get the latest version (.jar file) from our releases page.
2. Specifically, look for a file named legacylink.jar and click on it to download.
3. Save it in a folder where you want to store your LegacyLink data.
   • Ideally, this should be new folder specifically for LegacyLink.

3. Launch the Application

1. Get your folder path:

   • Open the file management application (i.e. file explorer for Windows, Finder for MacOS).
   • Navigate to the folder containing the jar file.
   • Copy the path from the address bar.

2. Open your command prompt/terminal (see instructions above).

3. Navigate to your LegacyLink folder:

   • Type cd followed by a space
   • Windows: Type your folder path (e.g., cd C:\Users\YourName\LegacyLink)
   • Mac/Linux: Type your folder path (e.g., cd /Users/YourName/LegacyLink)
   • Pro tip: You can alternatively drag and drop your folder into the terminal after typing cd (with a space) to automatically fill in the path!

4. Run LegacyLink by typing: java -jar legacylink.jar

5. Pressing enter will open up the LegacyLink window as shown below!

   

4. Try These Basic Commands

We've prepopulated LegacyLink with some dummy data for you to play around and get a feel of how LegacyLink works! Here are some simple commands to get you started:

📋 Essential Commands:
----------------------------------------
list -p     → Show all your contacts
list -e     → Display all events
help        → View all available commands

Ready to explore more features? Continue reading our features overview below in the what can you do with LegacyLink section or navigate to the deepdive section, where we break down each command in detail!

---

🎯 What Can You Do With LegacyLink?

Our primary features include the following:

📱 Essential Contact Features

🎉 Event Management

✏️ Update & Modify

Keep your information current with these features:

• Contact Updates

  • Edit contact details
  • Update relationships
  • Modify phone numbers/emails

• Event Changes

  • Reschedule dates
  • Change locations
  • Update attendee lists
  • Modify event names

🗑️ Cleanup & Organization

Manage your data efficiently:

• Contact Management

  • Remove single contacts
  • Clear all contacts
  • Organize by relationships

• Event Cleanup

  • Cancel individual events
  • Clear all events
  • Remove specific attendees

Refer to the feature list below for detailed information of each command that is available in LegacyLink.

📚 Features Overview

Contents

• General Commands
• Managing Contacts
• Organizing Events

Using This Guide:

• Commands are case-sensitive (help works, Help doesn't)
• Words in UPPER_CASE are values you provide
• Parameters can be in any order
  • For 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 (such as help and exit) will be ignored.
  
• If you are using a PDF version of this document, be careful when copying and pasting commands that span multiple lines as space characters surrounding line-breaks may be omitted when copied over to the application.

General Commands

Get Help 💡

Format:

help

• Shows a message (pictured below) with the link to access this user guide.
• Use anytime you need assistance.

Save Your Data 💾

• All changes are saved automatically
• No manual saving needed
• Data is stored in your LegacyLink folder

Exit LegacyLink 👋

Format:

exit

• Closes the application
• All data is automatically saved

⚠️ Warning: No confirmation message is displayed.

Editing The Data File

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

Managing Contacts

View Your Contact List 👥

list -p

• Shows all your family contacts in one view
• Use this to check contact details or before using other commands

Add a New Contact ➕

Format:

add -n NAME -p PHONE_NUMBER -e EMAIL -rs RELATIONSHIP

• Adds a person to the address book.
• All parameters NAME, PHONE_NUMBER, EMAIL, RELATIONSHIP must be present.
• If you want to use special characters such as d/o or s/o in name, please omit the / and enter so and do instead.

Valid Example:

add -n Betsy Crowe -rs Mother -e betsycrowe@example.com -p 98262123

• This command adds a person named Betsy Crowe with the phone number 98262123, email betsycrowe@example.com, and the relationship Mother to the address book.

Invalid Example (Invalid Phone Number):

add -n Betsy Crowe -rs Mother -e betsycrowe@example.com -p 12

• This command will result in the following error message since the phone number must be at least 3 digits long.

Invalid Example (Duplicate Persons):

• Assuming the contact add -n Betsy Crowe -rs Mother -e betsycrowe@example.com -p 98262123 already exists.
• Typing the following command add -n Betsy Crowe -rs Mother -e betsycrowe@example.com -p 98262123 will result in a duplicate entry and the person will not be added.
• The following error message will be shown:

Edit a Contact 📝

Format:

edit INDEX [-n NAME] [-p PHONE] [-e EMAIL] [-rs RELATIONSHIP]

• Edits an existing person in the address book.

Valid Example (One field edited):

• edit 2 -n Betsy Crower Edits the name of the 2nd person to be Betsy Crower.
• Note: this assumes that the address book contains at least 1 person.

Valid Example (Multiple fields edited):

• edit 1 -p 91234567 -e johndoe@example.com -rs Father Edits the phone number, email and relationship of the 1st person to be 91234567, johndoe@example.com and Father respectively.

Invalid Example:

• edit 1
• This command will result in the following error message since at least one of the optional fields must be provided.

Invalid Example (Multiple parameters):

• edit 1 -n Carmen -n Betsy -p 12345678 -p 87654321 -e example@email.com -e example@gmail.com -rs Brother -rs Mother
• This command will result in the following error message since each value should be edited at most once.

Invalid Example (Duplicate Persons):

• Assuming the contact add -n Betsy Crowe -rs Mother -e betsycrowe@example.com -p 98262123 exists as the first contact.
• Attempting to edit another contact:
  e.g. edit 2 -n Betsy Crowe -rs Mother -e betsycrowe@example.com -p 98262123 will result in a duplicate entry and the person will not be edited.
• The following error message will be shown:

Find Contacts By Name 🔍

Finds persons whose names contain any of the given keywords.

Format:

find KEYWORD [MORE_KEYWORDS]

Valid Example (Found 1 person):

• find John returns anyone with John as part of their name

Valid Example (Found multiple person):

• find Alex David returns anyone with Alex OR David as part of their name
  

Valid Example (Found no person)

• find Magnus
• Note: since there are no Magnus in the contact, 0 person is listed.

Delete a Contact ❌

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, …​

Valid Example:

• list -p followed by delete 1 deletes the 1st person in the address book.

Valid Example:

• find Charlotte followed by delete 1 deletes the 1st person in the results of the find command.
• Assumes that only 1 person named Charlotte is found by the find command.

Clearing All Contacts ❌❌

Format:

clear -p

Clears all persons from the address book.

Organizing Events

View All Events 📅

Format:

list -e

• Shows a list of all events in the event book.

Create New Event 🎉

Format:

event -n EVENT_NAME -sd EVENT_START_DATE -ed EVENT_END_DATE -l LOCATION [-a ATTENDEES]

• Adds an event to the event book.
• Dates are in (yyyy-mm-dd) format.

Valid Example:

• event -n Get Together Party -sd 2023-10-25 -ed 2023-10-27 -l MBS.
  Adds a "Get together party" event to the event book.

• event -n Birthday Party -sd 2023-10-15 -ed 2023-10-15 -l Home -a 1 2 3.
  Creates the birthday party event and adds the first 3 people in the contacts book to the event.

Invalid Example:

• event -n Birthday Party -sd 2023-10-15 -ed 2023-10-15 -l Home -a 1, 2, 3
• This command will result in the following error message since the list of indexes must be separated by whitespaces, not anything else like commas.

Invalid Example:

• event -n New Year's Party -sd 2025-01-01 -ed 2025-01-02 -l Times Square -a 1 2 -a 4 5
• This command will result in the following error message since the optional field -a is specified more than once.

Update Event Details ✏️

Format:

update -i INDEX [-n NEW_NAME] [-sd NEW_START_DATE] [-ed NEW_END_DATE] [-l NEW_LOCATION] [-a NEW_ATTENDEES_INDICES] [-r REMOVED_ATTENDEES_INDICES]

• Updates the details of an existing event in the address book. Note: Dates are in (yyyy-mm-dd) format.

Valid Example (One field updated):

• update -i 1 -l NUS UTown only updates the location of the first event to NUS UTown.

Valid Example (Multiple field updated):

• update -i 3 -n New Year's Party -sd 2025-01-01 -ed 2025-01-02 -l Marine Parade Road #12-34 -r 3 6 updates the 3rd event, reflecting all the provided details.

Invalid Example:

• update -i 3 -n New Year's Party -n Christmas Celebration -a 1 2 -a 4 5
• This command will result in the following error message since the optional fields -n and -a are specified more than once.

Cancelling Events ❌

Format:

cancel INDEX

• Deletes the event at the specified INDEX.
• The index refers to the index number shown in the displayed event list.
• The index must be a positive integer 1, 2, 3, …​

Valid Example:

• list -e followed by cancel 1 deletes the 1st event in the address book.

Clearing All Events 🗑️

Format:

clear -e`

• Clears all events from the event book.

⚠️ Warning: No confirmation message is displayed. This action is irreversible, you will have to use event command to add all the events again.

---

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 LegacyLink 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. When creating 2 or more events that have the same name, start date, end date, and location, it is possible for these events to have attendees which are subsets for each other, but not equal to each other. The remedy is to implement a more sophisticated duplicate event detection system to enhance user experience in the future.
4. Imprecise error message for invalid index in edit command. Currently, the error message for invalid index such as -1 (negative numbers), 0 and integer overflow is an invalid command instead of an index out of bounds. This is a known issue and will be addressed in an upcoming update to ensure that users receive more accurate and specific error messages when encountering invalid index values.
5. Truncation of text in the GUI. fields with lengthy text, such as long names and address, can sometimes be truncated in the GUI. To avoid this, you can adjust the size of the window by dragging the sides to enlarge the window.
6. Delay between updating of UI and updating of contact information. You may notice that the UI is not immediately updated upon executing commands such as edit or delete. You may have to refresh the UI by clicking on the person/event card again to see the updated person/event information.

---

Command summary