WhenFree - User Guide

• 1. Introduction
• 2. Quick Start
• 3. Features
  • Add a new contact
  • List all contacts
  • Display timetable of selected contacts
  • Schedule a new meeting
  • List all meetings
  • Edit a contact’s timetable
  • Delete an item
  • Exit application
• 4. FAQ
• 5. Command Summary

1. Introduction

(Written by: Xi Zhi, Chen Kun)

WhenFree is a scheduler chatbot that helps you find common free time among your and your friends, using just the NUSMODS links to your school timetable.

WhenFree is for NUS students who want to save time gathering their friends’ schedules to set up a meeting, whether for a long project discussion or a quick meal. With an easy-to-use command line interface, anyone can set up and use this application easily by following along this User Guide.

Get ready the NUSMODS links of you and your friends, and let’s get started!

This symbol denotes a tip which you might find useful when using the application.

This symbol denotes some information or caveats that you will need to take note of when using the application.

2. Quick Start

(Written by: Xi Zhi)

1. Ensure that you have Java 11 or later versions of Java installed on your computer.

   To check the version of Java on your computer, follow the instructions here.
   To download the latest version of Java on your computer, visit here.

2. Download the .jar file of our latest release of WhenFree, V2.1 here.
3. Copy the downloaded .jar file to an empty folder.
4. Open Command Prompt or Terminal and navigate to the folder using cd <folder_path>.
5. Run the .jar file using java -jar <file_name.jar>.

   Please resize the terminal to full screen mode to make full use of our CLI ASCII art. You will see this welcome message if you have done the above steps correctly.

The following part of the User Guide will explain the features of WhenFree in detail. You can follow along as we go through each of the features if you are starting out, or skip ahead to the Command Summary to see the commands of all features.

3. Features

• Add a new contact
• List all contacts
• Display timetable of selected contacts
• Schedule a new meeting
• List all meetings
• Edit a contact’s timetable
• Delete an item
• Exit application

Add a new contact

(Written by: Wei Yang)

Adds a contact into the application. You will need to key in <Contact Name> and <NUSMODS link> of the contact.

• You must add in your (main user’s) contact before you can use the application. If you try to enter a command before adding in your contact, WhenFree will remind you to key in your contact first. You can add as many contacts as you want thereafter.
• <Contact Name> should be a single word containing only alpha characters. It should not contain any whitespaces.
  

  Detailed instructions to obtain the NUSMODS links to the NUSMODS timetable can be found in the FAQ section.

Format:

<Contact Name> <NUSMODS link>

Examples of usage:

Juan https://nusmods.com/timetable/sem-2/share?CG2023=LAB:06,PLEC:02,PTUT:01

Tommy https://nusmods.com/timetable/sem-2/share?CG2027=LEC:01,TUT:01&CS2101=&CS2113T=LEC:C01

Example output:

↑ Return to list of Features

List all contacts: contacts

(Written by: Wei Yang)

Displays index and name of all contacts stored in the program.

This feature is usually used preceding Display timetable of selected contacts, Edit a contact’s timetable or Delete a contact features, to check for <Contact Index> and <Contact Name> of a contact.

Format:

contacts 

Example of usage:

contacts

Example output:

↑ Return to list of Features

Display timetable of selected contacts: timetable

(Written by: Xi Zhi)

There are 3 use cases illustrated below: to display the main user’s timetable, to display the timetable of a selected contact, and to display a combined timetable of multiple selected contacts.

• For all 3 uses cases, the timetable command shows only the current week’s timetable. To see up to two weeks of timetable, enter more command after the timetable command.

  You can check <Contact Index> of the contact(s) whose timetable you wish to display, by listing all contacts using contacts.

Use case 1: Displays your (main user’s) timetable.

Format:

timetable 

Example of usage:

timetable

Example output:

A cross in a 30-minute square of the timetable represents “busy”, while an empty square represents “free”.

Use case 2: Displays the timetable of a selected contact. You will need to key in <Contact Index> of the selected contact.

• Both timetable and timetable 0 display your (main user’s) timetable.

Format:

timetable <Contact Index>

Example of usage:

timetable 1

Example output:

Use case 3: Displays the combined timetable of multiple selected contacts. You will need to key in <Contact Index> of each of the selected contacts.

You can enter as many contacts as you wish

Format:

timetable <Contact A Index> <Contact B index> ...

Example of usage:

timetable 0 1

Example output:

Extended view: Displays up to 2 weeks of timetable.

Extended view is applied to the most recent timetable command

NOTE: Testers/Users currently in week 13 would be unable to use this command since week 13 is the last week.

Format:

more

Example of usage:

more

Example output:

↑ Return to list of Features

Schedule a new meeting: schedule

(Written by: Matthew)

Schedules a new meeting at a specified time slot and adds it into the meeting list. You will need to key in <Meeting Name>, and specify the meeting time slot with <Start Date> <Start Time> <End Date> <End Time>.

• You can schedule a meeting on only the current week and the next week, for which your timetable can be displayed with the timetable and more commands
• Hence, <Start Date> and <End Date> represents the date number you wish to schedule the meeting on, within the current week and the next week, from the current date onwards. For example, if the date today is 27 April:
  • You can schedule a meeting on 29 April this week with <Start Date> and <End Date> as 29.
  • You can schedule a meeting on 6 May next week with <Start Date> and <End Date> as 6.
  • You will not be able to schedule a meeting with <Start Date> and <End Date> as 26. Even though 26 April is within this week, the date has passed. The future date 26 May is also not within the current week and the next week.
• <Start Time> and <End Time> should be in the 24-hour HH:MM format. For example, the time 3pm should be represented as 15:00.
• <Meeting Name> should be a single word with no whitespace character.
• Scheduling a meeting will modify only your (main user’s) timetable, to be busy at the specified time slot. Timetables of other contacts will not be modified.

  You cannot schedule a meeting if your timetable is busy at the specified time slot. WhenFree will remind you to check your timetable if you try to schedule a meeting during a time slot which you are busy for.

Format:

schedule <Meeting Name> <Start Date> <Start Time> <End Date> <End Time>

Example of usage:

schedule meeting 11 17:00 11 19:00

Example output:

↑ Return to list of Features

List all meetings: meetings

(Written by: Matthew)

List all scheduled meetings stored in program.

This feature is usually used preceding Delete a meeting feature, to check for <Meeting Index> a meeting.

Format:

meetings

Example of usage:

meetings

Example output:

↑ Return to list of Features

Edit a contact’s timetable: edit

(Written by: Xi Zhi)

There are 2 use cases illustrated below: to edit a contact’s timetable to “busy” for a specified time slot, and to edit a contact’s timetable to “free” for a specified time slot.

• You can edit the contact’s timetable for only the current week and the next week, for which your timetable can be displayed with the timetable <Contact Index> and more commands
• Hence, <Start Date> and <End Date> represents the date number you wish to edit the timetable for, within the current week and the next week, from the current date onwards. For example, if the date today is 27 April:
  • You can edit the timetable on 29 April this week with <Start Date> and <End Date> as 29.
  • You can edit the timetable on 6 May next week with <Start Date> and <End Date> as 6.
  • You will not be able to edit the timetable with <Start Date> and <End Date> as 26. Even though 26 April is within this week, the date has passed. The future date 26 May is also not within the current week and the next week.
• <Start Time> and <End Time> should be in the 24-hour HH:MM format. For example, the time 3pm should be represented as 15:00.

  You can check <Contact Index> of the contact whose timetable you wish to edit, by listing all contacts using contacts.

Use case 1: Edits a contact’s timetable to be “busy” for a specified time slot. You need to key in <Contact Index> of the contact, and specify the time slot to be marked “busy” with <Start Date> <Start Time> <End Date> <End Time>.

Format:

edit busy <Contact Index> <Start Date> <Start Time> <End Date> <End Time>

Example of usage:

edit busy 0 11 09:00 11 10:00

Example output:

Use case 2: Edits a contact’s timetable to be “free” for a specified time slot. You need to key in <Contact Index> of the contact, and specify the time slot to be marked “free” with <Start Date> <Start Time> <End Date> <End Time>.

Format:

edit free <Contact Index> <Start Date> <Start Time> <End Date> <End Time>

Example of usage:

edit free 0 11 09:00 11 10:00

Example output:

↑ Return to list of Features

Delete an item: delete

(Written by: Chen Kun)

There are 2 use cases illustrated below: to delete a scheduled meeting and to delete a contact from the list.

You can check <Meeting Index> of the meeting you wish to delete, by first listing all meetings using meetings.
You can check <Contact Name> of the contact you wish to delete, by first listing all added contacts using contacts.

Use case 1: Deletes a meeting from the meeting list. You will need to key in Meeting Index of the meeting you wish to delete.

Format:

delete <Meeting Index>

Example of usage:

delete 1

Example output:

Use case 2: Deletes a contact from the contact list. You will need to key in Contact Name of the contact you wish to delete.

Format:

delete <Contact Name>

Example of usage:

delete Tommy

Example output:

↑ Return to list of Features

Exit the application: exit

(Written by: Chen Kun)

Exits the application and ends the current session.

Format:

exit

Example of usage:

exit

Example output:

↑ Return to list of Features

4. FAQ

(Written by: Wei Yang, Xi Zhi)

Q: How do I transfer my data to another computer?

A: Copy the data folder in the program directory and paste into the selected directory containing the .jar file in another computer.

Q: How do I prevent file corruption?

A: Ensure that you do not abruptly exit the application and do not edit delete the data file while application is still running, or outside of the application.

Q: How can I create a NUSMODS timetable?

A: Visit the NUSMODS website to create a NUSMODS timetable.

Q: How do I obtain the NUSMODS links to my NUSMODS timetable?

A: 1) Visit the NUSMODS website in your browser. If you do not already have a NUSMODS timetable saved in your browser, you can create a new one. Else, you will be brought to your saved NUSMODS timetable.
2) Click on the red “Share/Sync” button located at the bottom right of the page.
3) Click on the red copy icon next to the NUSMODS link in the pop-up box.
4) Paste the link into the CLI for the add a new contact feature.

↑ Return to the top

5. Command Summary

(Written by: Xi Zhi, Wei Yang, Chen Kun, Matthew)

↑ Return to the top