ProfBook User Guide 💡

Welcome to ProfBook, a specialised student management system exclusively tailored for CS2103T tutors by CS2103T students. This guide is your gateway to unlocking the potential of ProfBook, where you will discover how ProfBook can help streamline your administrative tasks, alleviate workload and most importantly reduce any administrative errors.

What can ProfBook do 🙋

As current students of CS2103T, we understand that CS2103T tutors have a high administrative workload on top of their existing tutor duties. On top of that, any administrative mistakes or oversights can increase that workload exponentially and may adversely impact students' learning. We deeply appreciate your role, and it is precisely to address these aforementioned issues that we designed ProfBook. ProfBook aims to drastically decrease administrative mistakes and your workload.

ProfBook is optimized for tutors' use via a familiar Command Line Interface (CLI) that uses Linux-styled commands while retaining the benefits of a Graphical User Interface (GUI). If you are a fast typer, ProfBook will empower you to efficiently track and manage students' progress and tasks, surpassing the capabilities of traditional GUI apps with a gentle learning curve.

---

Features overview

Consolidated Information

As a project-based module, CS2103T tutors have to juggle multiple groups. ProfBook aims to expedite this process by allowing you to keep track of all your groups and their progress within a centralised location. You would be able to traverse between the different groups quickly through familiar Linux commands.

Student and Group Management

ProfBook aids with the management of student and group information. ProfBook efficiently encapsulates information of every project group so that you can easily monitor their progress and relevant information. You can effortlessly add, delete and edit students or groups and even move students from one group to another.

Task Management

In addition to the efficient management of student and group information, ProfBook also aids with the management of task information. You can quickly and seamlessly allocate tasks to specific student or group and track their progress. With ProfBook, you can easily monitor each stage of the task journey, from start to finish, ensuring optimal productivity.

---

Quick start

The following steps are similar for all operating systems(OS) such as Windows, macOS and Linux.

1. Ensure you have Java 11 or above installed in your computer.

2. Download the latest ProfBook.jar from here.

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

4. Open a command terminal, cd into the folder you put the jar file in, and use the java -jar ProfBook.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.
   

   

5. Type the command in the command box and press Enter to execute it.
   Some example commands you can try:

   • cat grp-001 : Lists all tasks belonging to grp-001.

   • touch grp-001/0123Y --name Bob : Adds a student named Bob to the grp-001.

   • rm grp-001 : Deletes grp-001.

6. Refer to the General Commands, Student or Group Commands, Tasks Commands below for details of each command.

---

How to use the User Guide 😍

We understand that it may be daunting to delve into a completely new user guide. This section is designed to make this journey more smooth sailing for you and enhance your understanding of the commonly used icons and boxes. We hope you enjoy your reading experience! 😊 📖

---

Understanding ProfBook 📚

ProfBook Folder Structure

ProfBook is organized hierarchically with the following structure:

Root Directory (e.g., ~/)
The Root Directory serves as the main container for the ProfBook software. This is where all the data is organized.

Group Directories (e.g., grp-001, grp-002, ...)
Within the Root Directory, there are Group Directories only. Each Group Directory is dedicated to managing a specific group of students.

Student Directories (e.g., 1001Z, 5815Y, ...)
Inside each Group Directory, you'll find Student Directories only. These directories represent individual students within each group.

This hierarchical structure enables a well-organized and efficient way to manage groups and students within ProfBook.

ProfBook Command Format

• Words in UPPER_CASE are the compulsory parameters to be supplied by you.
  • e.g. In touch SPECIFIED_PATH -n NAME, SPECIFIED_PATH and the other field in UPPER_CASE can be substituted with the desired details to form touch 2000Y --name Bob.

• Words in UPPER_CASE that are surrounded by [square brackets] are optional parameters to be supplied by you.
  • e.g. In cat [SPECIFIED_PATH], [SPECIFIED_PATH] can be substituted with details or left empty, cat 2000Y and cat are acceptable commands.

• Parameters can be in any order.
  • e.g. If the command specifies -n NAME -e EMAIL, -e EMAIL -n NAME is also acceptable.

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

• Regarding the detection of duplicates,
  • For students and groups, duplicates can only be detected if they share the same StudentId or GroupId respectively across ProfBook.
  • For Todo tasks, duplicates can only be detected if the todo tasks share the same description (DESCRIPTION).
  • For Deadline tasks, duplicates can only be detected if the deadline tasks share the same description (DESCRIPTION) and due date (DATE_AND_TIME).

• If you would like to pass in a field that starts with \, - or --, you would need to use \ before the start of that field.
  • Else, fields that start with - or -- will be treated as flags and fields that start with \ will be treated without \(\Orchard when inputted will be treated as Orchard).
    • e.g. To pass in -Clementi in the edit command, the command would be edit -a \-Clementi.

Flags 🚩🚩🚩

All flags begin with -- or -. Flags usually come before essential details required by the command and are compatible in both long and short forms:

• --name / -n followed by the name of student or group as specified by command.

• --email / -e followed by the email of student.

• --phone / -p followed by the phone number of student.

• --address / -a followed by the address of student.

• --id / -i followed by a STUDENT_ID or GROUP_ID as specified by the command.

• --desc / -d followed by the description of task specified by command.

• --datetime / -dt followed by the due date of a deadline task in the yyyy-MM-dd HH:mm format.

• --all / -al followed by either:
  • allStu which adds individual tasks to all students within the specified directory.
    • Can only be used at a group or root directory.
      • If used at group directory, task will be added to all students in that group.
      • If used at root directory, task will be added to all students in ProfBook.
  • allGrp which adds group tasks to all groups within the root directory.
    • Can only be used at root directory.

• --help / -h
  • Use with any command (except exit, help and clear) for more information.
  • e.g. touch --help to learn more about how to add a student to ProfBook.

Acceptable values for each parameter

SPECIFIED_PATH:

• Must be a valid path.
• Most commands will require the SPECIFIED_PATH to be a present path (path that currently exists within ProfBook) except for the touch and mkdir commands.

NAME:

• Must be a non-empty string that only contain alphanumeric characters and spaces.
• This means that you cannot input a blank field.

EMAIL:

• Must be a non-empty string following the format of local-part@domain.
  • local-part:
    • Should only contain alphanumeric characters and special characters, + _ . -.
    • May not start or end with any special characters.
  • domain:
    • Made up of domain labels separated by periods.
    • Domain labels:
      • At least 2 characters long.
      • Consist of alphanumeric characters, separated only by hyphens, if any.
      • Must end with alphanumeric characters.

PHONE_NUMBER:

• Must be a non-empty string of numbers of at least 3 digits.

ADDRESS:

• Must be a non-empty string, which means you cannot input a blank field.

STUDENT_ID:

• Must follow the format of a valid StudentId.

GROUP_ID:

• Must follow the format of a valid GroupId.

DESCRIPTION:

• Must be a non-empty string, which means you cannot input a blank field.

DATE_AND_TIME:

• Must be in the format yyyy-MM-dd HH:mm where each alphabet will be replaced by a positive whole number.
  • yyyy: year.
  • MM: month.
  • dd: day.
  • HH: hour (24-hour format).
  • mm: minutes.
• e.g. 2023-10-01 23:59

TASK_INDEX:

• Must be a positive whole number, which means it cannot contain decimals or fractions.
• Must fall within the range of 1 and the size of the task list of the specified student or group.

---

Navigating the Graphical User Interface(GUI) 👀

ProfBook's graphical user interface(GUI) presents crucial information through visuals. However, please note that ProfBook utilizes a Command Line Interface (CLI) approach, limiting the interactions with the graphical components to mainly scrolling via scrollbars. Let's navigate ProfBook's GUI together in sequential order!

Root Directory

Upon launching ProfBook, you will see the root directory as illustrated below.

Group Directory, grp-001

When you navigate to the group directory, grp-001, using cd grp-001, your interface should resemble the following.

Task List of Group Directory, grp-001

To view the task list of the current group directory, simply use cat.

---

General Commands

Change Directory: cd

Changes the current directory in ProfBook.

Format: cd SPECIFIED_PATH

Acceptable values for each parameter:

SPECIFIED_PATH:

• Must be a valid path to a group or root.

Example(s):

• When you are at the root directory ~/ and would like to take a look at the group directory, ~/grp-001,
  • cd grp-001 changes your directory to grp-001.
• When you are at the directory ~/grp-001 and would like to change directory from grp-001 to grp-002 you could use,
  • cd ../grp-002 -> use .. to navigate up to the root directory before proceeding to the grp-002 directory.
    

Display Directories : ls

Shows the list of children in the specified directory.

Format: ls [SPECIFIED_PATH]

Acceptable values for each parameter:

[SPECIFIED_PATH]:

• Must be a valid path to a group or root.

Example(s):

• When you are at the root directory ~/ and would like to see all the groups you have,
  • ls will return all the current groups.

Display all Tasks: cat

Displays all tasks in the specified directory.

Format: cat [SPECIFIED_PATH]

Acceptable values for parameter:

[SPECIFIED_PATH]:

• Must be a valid path to a group or student.
• Must not be a path to root.

Example(s):

• When you are at the directory ~/grp-001 and would like to see all tasks allocated to
  grp-001,
  • Executing cat will return all the tasks allocated to grp-001.
  • Result shown will be similar to this.

View Help : help

Shows a message of the commands you could use.

Format: help

Clear all Entries : clear

Clears all entries from ProfBook.

Format: clear

Exit ProfBook : exit

Exits the program.

Format: exit

---

Student or Group Commands 👪

Add a Student: touch

Adds a student into the specified group directory.

Format: touch SPECIFIED_PATH --name NAME [--email EMAIL] [--phone PHONE_NUMBER] [--address ADDRESS]

Acceptable values for each parameter:

SPECIFIED_PATH:

• Must be a valid path to a student.
• If the command is executed outside the intended group to add the student, the specified path must extend to encompass both the group and the student to ensure accurate execution.

Example(s):

• When you are at the directory ~/grp-001, you could add a new student named Bob with the StudentId 0200Y to this group through the following command,
  • touch 0200Y --name Bob

Create a Group : mkdir

Creates a group in the root directory that can contain students.

Format: mkdir SPECIFIED_PATH_TO_GROUP --name NAME

Acceptable values for each parameter:

SPECIFIED_PATH_TO_GROUP:

• Must be a valid path to a group.

Example(s):

• When you are at the root directory ~/ and would like to add a new group with the GroupId
  grp-001,
  • mkdir grp-001 --name Group 001 will add that group named Group 001.

Edit a Student: edit

Edits a student's details including name, email, phone, address or StudentId in the specified path.
One or more fields can be edited in a single command.

Format: edit SPECIFIED_PATH [--name NAME] [--email EMAIL] [--phone PHONE_NUMBER] [--address ADDRESS] [--id STUDENT_ID]

Acceptable values for each parameter:

SPECIFIED_PATH:

• Must be a valid path to a student.

Example(s):

• If a student in grp-001 with the StudentId 0010Y changed his phone number, you could execute the following command at the directory ~/grp-001, to make the necessary changes.
  • edit 0010Y --phone 91919191

Edit a Group: edit

Edits a group's details including name or GroupId in the specified path.
One or more fields can be edited in a single command.

Format: edit [SPECIFIED_PATH] [--name NAME] [--id GROUP_ID]

Acceptable values for each parameter:

[SPECIFIED_PATH]:

• Must be a valid path to a group.

Example(s):

• If grp-001 changed their group name, you could execute the following command at the directory ~/grp-001, to make the necessary changes.
  • edit --name Amazing Group1

Delete a Student or Group: rm

Removes a student or group from the specified path.

Format: rm SPECIFIED_PATH

Acceptable values for each parameter:

SPECIFIED_PATH:

• Must be a valid path to a student or group that you would like to remove.

Example(s):

• When you are at the root directory ~/ and would like to remove the group with the GroupId grp-001,
  • rm grp-001 will do that!

Move a Student: mv

Moves student from one group to another group.

Format: mv SPECIFIED_PATH_TO_STUDENT SPECIFIED_PATH_TO_GROUP

Acceptable values for each parameter:

SPECIFIED_PATH_TO_STUDENT:

• Must be a valid path to a student that you would like to move.

SPECIFIED_PATH_TO_GROUP:

• Must be a valid path to a group that you would like to move the student to.

Example(s):

• In the beginning of the semester, student transfers amongst groups are common. When you are at the root directory ~/, you could move a student with the StudentId 0123Y, from grp-001 to grp-002 through this command easily,
  • mv grp-001/0123Y grp-002

---

Tasks command 📋

Create Todo Task : todo

Creates todo tasks for specific student(s) or group(s).

Format: todo [SPECIFIED_PATH] --desc DESCRIPTION [--all CATEGORY]

Acceptable values for each parameter:

[SPECIFIED_PATH]:

• Must be a valid path to a student or group.

Example(s):

• When a specific student with the StudentId 0010Y has to redo his tutorial, you could use the following command when you are in the directory ~/grp-001 to allocate the task to just this student,
  • todo 0001Y --desc Redo tutorial

Create Deadline Task : deadline

Creates task with a deadline for specific student(s) or group(s).

Format: deadline [SPECIFIED_PATH] --desc DESCRIPTION --datetime DATE_AND_TIME [--all CATEGORY]

Acceptable values for each parameter:

[SPECIFIED_PATH]:

• Must be a valid path to a student or group.

Example(s):

• When a specific student with the StudentId 0010Y has to hand in his assignment again by a certain date, you could use the following command when you are in the directory ~/grp-001,
  • deadline 0001Y --desc resubmit Assignment 1 --datetime 2023-10-11 23:59

Mark Task as Completed: mark

Marks the specified task as done for the specified student or group.

Format: mark TASK_INDEX

Example(s):

• When you find yourself in the ~/grp-001 directory and wish to mark the completion of the first task allocated to student with the StudentId 0123Y, you could follow these commands in sequential order.
  1. cat 0123Y
  2. mark 1

Unmark Task: unmark

Unmarks the specified task for the student or group.

Format: unmark TASK_INDEX

Example(s):

• When you are at the ~/grp-001 directory and would like to unmark the first task allocated to this group, you could follow these commands in sequential order.
  1. cat
  2. unmark 1

Delete Task: rmt

Removes a task according to the task index.

Format: rmt TASK_INDEX

Example(s):

• When you are at the ~/grp-001 directory and no longer want to keep track of the first task allocated to student with the StudentId 0123Y, you could always remove this task by following these commands in sequential order.
  1. cat 0123Y
  2. rmt 1

---

Save the data

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

---

Commonly made mistakes

At ProfBook, we wholeheartedly believe that mistakes are part of the learning journey. We are here to support you in your quest of mastering ProfBook, helping you recover from any hiccups that may happen along the way. As such, we have collated a list of some commonly made mistakes and solutions to them. 💪

Mistake 1: Invalid command format

Some possible errors from invalid command format are,

1. Excessive or duplicate arguments.
   • This occurs when there are duplicate flags or an excess of compulsory or optional parameters as outlined in the command format.
2. Missing arguments.
   • This issue arises when there are missing compulsory parameters from the command you entered.
3. Invalid option.
   • Solution:
     • Pay close attention to the invalid option (also known as flags) indicated in the return message.
     • First, ensure that the option is applicable for the command you are utilising.
     • Second, confirm that there are no misspellings especially when it comes to options in their long forms. By adhering to these steps, you could efficiently correct invalid options in your commands.

General solution: Ensure that the command you enter adheres to the format provided in the user guide.

Mistake 2: Invalid path

Solution: Please check that the path you entered is the path required by the command which can be seen in the User Guide. Additionally, do ensure that it is the intended path you wish to utilise, and it exists within ProfBook.

Mistake 3: Invalid task index

Solution: Task index starts from 1. Check that the index you input is a positive whole number and falls within the range of 1 to the total number of tasks in the task list.

Mistake 4: The display panel is not showing task list

Solution: Please do not forget to execute the cat command prior to executing the required command.

Mistake 5: At least one field to edit must be provided

Solution: If editing a student, ensure that you have indicated at least one field (NAME, EMAIL, PHONE_NUMBER, ADDRESS or STUDENT_ID) to edit and that the flag used is accurate.
If editing a group, ensure that you have indicated at least one field (NAME or GROUP_ID) to edit and that the flag used is accurate.

Mistake 6: Value(s) provided is the same as the current value(s). No changes have been made.

Solution: When modifying information for a student or group, please ensure that at least one field you intend to edit differs from the current parameters associated with the student or group.

Mistake 7: Duplicate Id.

Solution: Ensure that the GroupId or StudentId you entered does not coincide with other GroupId or StudentId respectively in the whole ProfBook.

---

FAQ

Q: How do I transfer my data to another computer?
A: Install ProfBook in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous ProfBook home folder.

Q: Is there an edit command for tasks?
A: Currently, we do not have an edit command for tasks. But we would love to have it in ProfBook and are definitely working toward including it in our future enhancements.

---

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.

---

Exciting future developments 👀

This section is dedicated to the exciting future enhancements we envision for ProfBook.

Viewing edited group name at current group directory:

• Current: To view changes to the group name, you would need to cd out of the current group directory to the root directory, similar to terminal behaviour.
• Upcoming enhancement: ProfBook will return a more informative message that clearly indicates the updated group name after execution of command.

Marking and Unmarking tasks:

• Current: You can mark and unmark tasks that are already marked or unmarked respectively.
• Upcoming enhancement: ProfBook will return a return message confirming that the task has already been marked or unmarked, and the current command will not result in any changes.

Editing tasks:

• Current: ProfBook does not have an edit command for tasks. But you could always rmt the task and add it back through the todo or deadline command!
• Upcoming enhancement: We are actively developing the edit command for tasks, mirroring the edit command for students and groups. This addition will simplify the learning process of this new command, ensuring a seamless experience for you.

---

Command summary