KeepInTouch User Guide

KeepInTouch is a desktop app for managing contacts for job-seekers. It can also help job-seekers to manage events for career purposes. KeepInTouch is optimized for use via a Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, KeepInTouch can get your contact management tasks done faster than traditional GUI apps.

Table of Contents

Quick start

  1. Ensure you have Java 11 installed in your Computer.

  2. Download the latest keepintouch.jar from here.

  3. Copy the file to the folder you want to use as the home directory for your KeepInTouch app.

  4. Open a command terminal, cd into the home directory, and use the java -jar keepintouch.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.) GUI example

  5. Type the command in the command box and press Enter to execute it. e.g. typing help and pressing Enter will show the list of all available commands.

  6. Refer to the Features below for details of each command.

Features

Notes about the command format:

  • Words in UPPER_CASE are the parameters to be supplied by the user.
    e.g. in delete contact CONTACT_ID, CONTACT_ID is a parameter which can be used as delete contact 1.

  • Items in square brackets are optional.
    e.g add contact -n NAME [-p PHONE_NUMBER] [-a ADDRESS] [-e EMAIL] [-t TAGNAME...] can be used as add contact -n Aaron -p 12345678 -a Baker Street 12 -e aaron123@gmail.com -t Frontend or as add contact -n Aaron -e aaron123@gmail.com.

  • Items with …​ after them can be used multiple times.
    e.g. [-t TAGNAME...] can be used as -t Frontend, -t Frontend -t Java etc.

  • Parameters can be in any order.
    e.g. if the command specifies -tit NOTE_TITLE -con NOTE_CONTENT, -con NOTE_CONTENT -tit NOTE_TITLE is also acceptable.

  • Extraneous parameters for commands that do not take in parameters (such as list contact and exit, etc.) will be ignored.
    e.g. if the command specifies exit 123, it will be interpreted as exit.

  • 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.

Requirements and details on user supplied parameters:

  • CONTACT_ID is the number that is on the left of the contact's name in each contact card.

  • CONTACT_ID should be a positive integer less than 2,147,483,648.

  • NAME should be alphanumeric, spaces are allowed.

  • PHONE_NUMBER should be numbers at least 3 digits long.

  • EMAIL should be of the format local-part@domain:

    • The local-part should only contain alphanumeric characters and the special characters +, _, ., -. The local-part should not start or end with any special characters.
    • The domain name should:
      • end with a domain label at least 2 characters long
      • have each domain label start and end with alphanumeric characters
      • have each domain label consist of alphanumeric characters, separated only by hyphens, if any.

  • TAGNAME should be alphanumeric, with no spaces.

  • TAGNAME is case-sensitive. For example, a contact can have tags Frontend and frontend at the same time.

  • START_TIME and END_TIME can be in one of the following formats:

    • Both date and time: yyyy-MM-dd HH:mm[:ss]
      • Example: 2023-10-12 20:05, 2023-10-12 20:05:30
    • Only date (Time will be defaulted to 00:00): yyyy-MM-dd
      • Example: 2023-10-12
    • Only time (Date will be defaulted to the current date): HH:mm[:ss]
      • Example: 00:10, 05:01:45

Viewing help: help

Shows a list of commands and functionalities.

Format: help [COMMAND_WORD]

  • Add COMMAND_WORD after help to view the specific functionalities of the command.
  • COMMAND_WORD includes: add, delete, clear, find, list.

Examples:

  • help
  • help add

Successful output: help success output help add success output

Listing contacts: list contact

Shows a list of all contacts in the contact list if tags not specified. Otherwise, shows a list of contacts which contains any one of the specified tags.

Format: list contact [-t TAGNAME...]

  • Lists all contacts if no tags passed.
  • If tags argument passed, lists only contacts that contain one of the tags.

Examples:

  • list contact to show all contacts.
  • list contact -t Recruiter to show all contacts which have a recruiter tag.

Successful output: list contact success output

Adding a contact: add contact

Adds a contact to the contact list.

Format: add contact -n NAME -p PHONE_NUMBER -a ADDRESS -e EMAIL [-t TAGNAME...]

Examples:

  • add contact -n Aaron -p 12345678 -a Baker Street 12 -e aaron123@gmail.com

Successful output: add contact success output

Unsuccessful output:

  • Contact already exists: This contact already exists in the contact list
  • Invalid phone number: Phone numbers should only contain numbers, and it should be at least 3 digits long

Deleting a contact: delete contact

Deletes the specified contact from the contact list.

Format: delete contact CONTACT_ID

Examples:

  • delete contact 1 deletes the first contact in the contact list.

Successful output: delete contact success output

Unsuccessful output:

  • Invalid index (out of range): The person index provided is invalid

Finding a contact: find

Finds a contact by their name by matching keywords with the contact's name. Only word-word matches will be detected, and partial words match will not be detected. For example, Ale will not match Alex, but Alex will match Alex Wong. Keywords are case insensitive.

Format: find KEYWORD [OTHER_KEYWORDS...]

Examples:

  • find David

Successful output: find success output

Adding tags: add tag

Adds one or more tags to a contact. Contact list will go back to showing all contacts upon successful addition.

Format: add tag -id CONTACT_ID -t TAGNAME...

  • Adds one or more tags to a contact.
  • Duplicates are accepted but only unique tags will be added.

Examples:

  • add tag -id 1 -t Frontend adds a tag with tag name "Frontend" to the first contact in the contact list.
  • add tag -id 1 -t Frontend -t Java adds two tags with tag name "Frontend" and "Java" to the first contact in the contact list.

Successful output: add tag success output

Unsuccessful output:

  • Invalid index (out of range): Can not find the target contact with ID: 100

Deleting tags: delete tag

Deletes one or more tags to a contact. Contact list will go back to showing all contacts upon successful deletion.

Format: delete tag -id CONTACT_ID -t TAGNAME...

  • Duplicate TAGNAME are accepted, but they will be treated as one.

Examples:

  • delete tag -id 1 -t Frontend deletes a tag with tag name "Frontend" from the first contact in the contact list.
  • delete tag -id 1 -t Frontend -t Java deletes two tags with tag name "Frontend" and "Java" from the first contact in the contact list.

Successful output: delete tag success output

Unsuccessful output:

  • Invalid index (out of range): Can not find the target contact with ID: 100

Adding a note to a contact: add note

Adds a note to a contact from the contact list.

Format: add note -id CONTACT_ID -tit NOTE_TITLE -con NOTE_CONTENT

Examples:

  • add note -id 1 -tit Meeting Topics -con The topic is about the framework design of the project
  • add note -id 2 -tit Open Position -con Applications for SWE full-time positions will open soon

Successful output: add note success output

Unsuccessful output:

  • Invalid index (out of range): Can not find the target contact with ID: 100

Deleting a note: delete note

Deletes the specified note from the contact list.

Format: delete note -id CONTACT_ID -nid NOTE_ID

  • Deletes the note with the id NOTE_ID from the contact with id CONTACT_ID.

Examples:

  • delete note -id 1 -nid 1 deletes the first note from the first contact in the contact list.

Successful output: delete note success output

Unsuccessful output:

  • Invalid contact index (out of range): Can not find the target contact with ID: 100
  • Invalid note index: Note not found: ID = 5

Listing events: list events

Shows a list of all events or events within a specified time interval.

Format: list events [-descending] [-st START_TIME] [-et END_TIME] (start time and end time are inclusive)

Arguments -st and -et must both present or both not present.

  • If both are not present, all events will be listed.
  • If both are present, events within the time interval will be listed.

By default, the list of events are sorted by the start time in ascending order (i.e. from earliest to latest). If you want to use descending order, add -descending to the command.

Executing this command will create a popup window, which shows a table representing the events within the specified time interval. The columns inside the table are resizeable.

Examples:

  • list events
  • list events -st 2023-11-01 -et 2023-11-02
  • list events -descending -st 2023-11-01 -et 2023-11-02

Successful output: list events success output list events success output

Adding an event: add event

Adds an event to a contact. The event should not have clashes in timing with other existing events in the contact list. Events with start time earlier than the current time are allowed for keeping track of past events.

Format: add event -id CONTACT_ID -en EVENT_NAME -st START_TIME [-et END_TIME] [-loc LOCATION] [-info INFORMATION]

  • If END_TIME is not given, it will be defaulted to the START_TIME.
  • If START_TIME is exactly equals to END_TIME, the END_TIME for the event will not be displayed in text-based UI.

Examples:

  • add event -id 1 -en Meeting with professor -st 12:00 -et 13:00 -loc COM 1 Basement -info Discuss the project implementation with the professor
  • add event -id 2 -en Chat with TikTok recruiter -st 17:00

Successful output: add event success output

Unsuccessful output:

  • Event already exists: Error: Operation would result in duplicate events
  • Invalid contact index (out of range): Can not find the target contact with ID: 100
  • Invalid time format: Invalid date-time format! Text '29/05/2024' could not be parsed at index 2

Deleting an event: delete event

Deletes the specified event from a contact.

Format: delete event -id CONTACT_ID -eid EVENT_ID

  • Deletes the event with the id EVENT_ID from the contact CONTACT_ID.
  • Note that EVENT_ID is the number that are in the left of the event line under each contact card.

Examples:

  • delete event -id 1 -eid 2 deletes the second event from the first contact in the contact list.

Successful output: delete event success output

Unsuccessful output:

  • Invalid contact index (out of range): Can not find the target contact with ID: 100
  • Invalid note index: Event not found: ID = 5

Clearing data: clear

Clears all KeepInTouch entries.

Format: clear

Exiting the program: exit

Exits the program.

Format: exit

Saving the data

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

Other Features

More features coming soon ...

Glossary

  • home directory:

    The directory where the jar file for the application and the data folder presents.

  • contact:

    The unit for storing the contact information for a person/entity in the address book. You can add tags, notes and events to a contact.

  • tag:

    Short tags to be added to the contact for you to reference. It can be the type of the contact, for example, company, HR, etc.

  • note:

    A piece of additional information for a contact that you want to store and reference in the future. It can be any additional information you'd like to keep with the contact.

  • event:

    A representative of an event that you will happen with a person/entity in a contact in the future. It can be job interviews, career fairs or HR meeting appointments.

FAQ

Q: Why can't I run the app?
A: Make sure you have Java 11 installed before running the app, and make sure you have followed the way mentioned in Quick Start.

Q: How do I transfer my data to another device?
A: Please follow these steps:

  • Download the jar file for the app on the new device.
  • Copy the data folder from the old device to the new device, and put it in the home directory on the new device.
    • The data folder from the old device is located at home directory/data`. You need to copy the folder along with all files inside to the new device to complete data transfer.
  • Run the application on the new device. Now you should see the data from old device on your new device.
  • Similarly, if you want to move the jar file to another directory (change the home directory) within the same device, you also need to make sure that the data folder is always in the new home directory together with the jar file.

Q: Can I modify the data file outside the application itself?
A: No, you should NOT directly modify the data file outside the application at anytime, otherwise it may lead to unpredictable consequences and errors to the application.

Known issues

No known issues at the moment

Command summary

Action Format, Examples
List Contact list contact [-t TAGNAME...]
e.g., list contact -t Recruiter
Add Contact add contact -n NAME -p PHONE_NUMBER -a ADDRESS -e EMAIL [-t TAGNAME...]
e.g., add contact -n Aaron -p 12345678 -a Baker Street 12 -e aaron123@gmail.com -t Frontend
Delete Contact delete contact CONTACT_ID
e.g., delete contact 1
Find Contact find KEYWORD [OTHER_KEYWORDS...]
e.g., find Alex
Add Tag add tag -id CONTACT_ID -t TAGNAME...
eg., add tag -id 1 -t Frontend
Delete Tag delete tag -id CONTACT_ID -t TAGNAME...
eg., delete tag -id 1 -t Frontend
Add Note add note -id CONTACT_ID -tit NOTE_TITLE -con NOTE_CONTENT
e.g., add note -id 2 -tit Open Position -con Applications for SWE full-time positions will open soon
Delete Note delete note -id CONTACT_ID -nid NOTE_ID
e.g., delete note -id 1 -nid 1
List Events list events [-descending] [-st START_TIME] [-et END_TIME]
e.g., list events -descending -st 2023-11-01 -et 2023-11-02
Add Event add event -id CONTACT_ID -en EVENT_NAME -st START_TIME [-et END_TIME] [-loc LOCATION] [-info INFORMATION]
e.g., add event -id 1 -en Meeting with professor -st 12:00 -et 13:00 -loc COM 1 Basement -info Discuss the project implementation with the professor
Delete Event delete event -id CONTACT_ID -eid EVENT_ID
e.g., delete event -id 1 -eid 1
Clear Data clear
Help help [COMMAND_WORD]
e.g., help add