User Guide

Welcome to HouR

HouR is a desktop app for managing employee records, optimized for use via a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). If you can type fast, HouR can get your HR management tasks done faster than traditional GUI apps.

Table of Contents

• Using this guide
• Useful Notations and Glossary
• Quick Start
• Navigating the GUI
• Features
  • General Commands
    • Viewing Help: help
    • Clearing all employees: clear
    • Exiting the program: exit
  • Employee Commands
    • Adding an employee: add
    • Deleting an employee: delete
    • Editing an employee: edit
    • Listing all employees: list
    • Finding employees: find
    • Sorting employees: sort
  • Employee Metrics Commands
    • Adding a leave period: addleave
    • Deleting a leave period: deleteleave
    • Editing a leave date: editleave
    • Listing employees on leave: listleave
    • Adding remarks: addremark
    • Deleting remarks: deleteremark
    • Updating overtime hours: overtime
    • Generating an employee report: report
    • Resetting fields: reset
• FAQ
• Known Issues
• Command Summary
• Parameter Information

Using this guide

• If you are new here, visit our quick start guide to onboard onto HouR smoothly!
• If you are unsure of how to use HouR, the Command Summary is a good place to start.
• If you are a developer and want to help out, do take a look at our Developer Guide.

Useful Notations and Glossary

While exploring HouR’s features with this user guide, do take note of these symbols used and what they represent.

Symbol	Meaning
	Important information
	Warning or caution
	Additional information such as tips or notes

The following glossary table provides clarification on commonly-used terms as well as terminology that is possibly unknown to you.

Quick Start

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

2. Download the latest hour.jar from here.

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

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

Caution to macOS users: Performing these instructions may result in non-deterministic behaviour of data loading in HouR. This was tested on multiple macOS Systems:
1. Right-click hour.jar > Open With > JavaLauncher.app
2. First-time users may be prompted with a warning that the file was downloaded from the Internet. Simply click Open in the prompt to continue.

1. Type a 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:

   • help : Shows help window with link to user guide.

   • add n/John Doe pos/Senior Software Enginner id/EID2023-7890 p/81239876 e/johndoe@test.com s/5000 : Adds an employee named John Doe to the employee list.

   • list : Lists all employees.

   • edit 1 n/Alex Yeoh : Edits the name of the 1st employee shown in the current list to Alex Yeoh.

   • find Alex Manager: Lists all employees with the keywords Alex or Manager.

   • delete EID2023-1234 : Deletes the employee with employee id EID2023-1234 shown in the list.

   • sort f/salary in/asc : Sorts the employees by their salaries in ascending order.

   • addleave id/EID1234-5678 from/2023-12-26 to/2023-12-28 : Adds leave dates from 26 to 28 December 2023 inclusive for employee with id EID1234-5678.

   • deleteleave id/EID1234-5678 from/2023-12-27 to/2023-12-27 : Deletes leave date 27 December 2023 for employee with id EID1234-5678.

   • editleave id/EID1234-5678 old/2023-12-26 new/2023-12-29 : Edits the old leave date on 26 December 2023 of employee with id EID1234-5678 to new leave date on 29 December 2023.

   • listleave on/2023-12-28 : Lists all employees on leave on 28 December 2023.

   • addremark id/EID1234-5678 r/good worker : Adds the remark good worker to the employee with id EID1234-6788.

   • deleteremark id/EID1234-5678 r/good worker : Deletes the remark good worker from the employee with id EID1234-5678.

   • overtime id/EID1234-5678 o/inc a/10 : Increases the overtime hours of employee with id EID1234-5678 by 10 hours.

   • report EID1234-5678 : Generates a report with details of the employee with id EID1234-5678.

   • reset f/overtime : Resets the overtime hours field of all employees to the default value 0.

   • clear : Deletes all employees.

   • exit : Exits the app.

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

Navigating the GUI

HouR comes with a Graphical User Interface (GUI) to allow for nice visual feedback for our users. Here is a quick run-through of the different sections of our GUI, as well as some notes regarding the use of the GUI.

Quick Orientation

Employee Card

Features

Below is an overview of HouR’s features.

• View list of commands: help
• Add an employee: add
• Delete an employee: delete
• Edit an employee: edit
• List all employees: list
• Find employees: find
• Sort employees by attribute: sort
• Add leave dates for an employee: addleave
• Delete leave dates of an employee: deleteleave
• Edit leave of an employee: editleave
• List employees on leave: listleave
• Add remarks for an employee: addremark
• Delete remarks of an employee: deleteremark
• Update overtime hours of an employee: overtime
• Generate an employee report: report
• Reset specified field to default number: reset
• Clear all employees: clear
• Exit the program: exit

General Commands

This section contains commands that are not related to any specific feature in HouR.

Viewing help : help

Shows a window with link to access the help page.

Format: help

Tip: For Windows users, you can use keyboard shortcut F1 to open up the help window.

Caution: If you are running HouR on another monitor, the help window defaults to the centre of the primary monitor.

Clearing all entries : clear

Clears all entries from the employee book.

Format: clear

Exiting the program : exit

Exits the program.

Format: exit

Employee Commands

This section contains commands relating to the employee list and/or employees.

Adding an employee : add

Adds an employee to the employee list.

Format: add n/NAME pos/POSITION id/EMPLOYEE_ID p/PHONE_NUMBER e/EMAIL s/SALARY [d/DEPARTMENT]...

• Adds the employee with the specified details.
• The NAME, POSITION, PHONE_NUMBER, EMAIL and DEPARTMENT parameters are case-sensitive.
• The EMPLOYEE_ID refers to each employee’s unique employee id (must not already exist) and must follow the EID format (EID[4 digits]-[4 digits])
• The SALARY parameter only takes in positive integers.

Examples:

• add n/Alex Yeoh pos/Software Engineer id/EID2023-1234 p/87428807 e/alexyeoh@example.com s/8500 d/IT
• add n/Jane Doe pos/Manager id/EID2023-7891 p/81234567 e/janedoe@test.com s/5000

• add n/Charlotte Oliveiro pos/Sales Associate id/EID2023-1234 p/98561234 e/charlotte@example.com s/7300 d/Sales is invalid because EMPLOYEE_ID already exists in the records.

Deleting an employee : delete

Deletes an employee from the employee list.

Format: delete EMPLOYEE_ID

• Deletes the employee at the specified EMPLOYEE_ID.
• The EMPLOYEE_ID refers to each employee’s unique employee id and must follow the EID format (EID[4 digits]-[4 digits]).

Examples:

• delete EID2023-1234 deletes the employee with employee id EID2023-1234 in the employee list.

• delete EID0000-0000 is invalid because the EMPLOYEE_ID does not exist in the records.

Editing an employee : edit

Edits an existing employee in the employee list.

Format: edit INDEX [n/NAME] [pos/POSITION] [id/EMPLOYEE_ID] [p/PHONE_NUMBER] [e/EMAIL] [s/SALARY] [d/DEPARTMENT]...

• Edits the employee at the specified INDEX. The index refers to the index number shown in the displayed employee list.
• The INDEX must be a positive integer less than or equals to the number of employees shown in the displayed employee list 1, 2, 3, …​
• At least one of the optional fields must be provided.
• Existing values will be updated to the input values.

Examples:

• edit 1 pos/Senior Software Engineer edits the position of the 1st employee to be Senior Software Engineer.

• edit 100 pos/Senior Software Engineer is invalid because the index does not exist.

Listing all employees : list

Shows a list of all employees in the employee list.

Format: list

Finding employees : find

Finds employees whose name, position, department, phone number, email, or ID contain any of the given keywords.

Format: find KEYWORD [MORE_KEYWORDS]

• The search is case-insensitive. e.g hans will match Hans
• The order of the keywords does not matter. e.g. Hans Bo will match Bo Hans
• Only full words will be matched e.g. Han will not match Hans
• Employees matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber and Bo Yang.

Examples:

• find Roy EID1234-5678 returns Roy Balakrishnan and Alex Yeoh.

• find EID0000-0000 returns an empty list of employees since no employee has that ID.

Sorting all employees : sort

Sorts employees in the employee list by a given field.

Format: sort f/FIELD in/ORDER

• Sorts the employee list by the specified FIELD in the given ORDER.
• The FIELD has to be non-empty and can only be one of these 4 values: name, salary, overtime, or leaves.
• The FIELD and ORDER parameters are case-insensitive. (e.g. name and NAME are taken to be the same)
• The ORDER is either ascending (asc) or descending (desc).

Examples:

• sort f/salary in/asc sorts the employee list such that their salaries are arranged in ascending order from top to bottom

• sort f/blah in/desc is invalid because field blah is not one of the 4 mentioned values.

Employee Metrics Commands

You can use the following commands to keep track of employee metrics and gauge employee performance.

Adding a leave period of an employee : addleave

Adds the dates between a specified period of time to the leaves taken by the specified employee.

Format: addleave id/EMPLOYEE_ID from/START_DATE to/END_DATE

• Add dates between START_DATE and END_DATE inclusive into the leaves taken by employee with id EMPLOYEE_ID.
• EMPLOYEE_ID must follow the EID format (EID[4 digits]-[4 digits]).
• START_DATE and END_DATE must be in the YYYY-MM-DD format.
• START_DATE must not be after END_DATE.
• Dates between START_DATE and END_DATE inclusive must not already exist in the leave list.
• The total number of annual leaves used cannot exceed the maximum of 14 as per the Singapore Ministry of Manpower’s guidelines.

Tip: If the current date falls within the leave period, the leave status of the employee will change from “Present” to “On Leave”.

Tip: The leave list displayed shows the leaves arranged in the order they were added, i.e. leave dates added later will be added to the end of the leave list.

Examples:

• addleave id/EID1234-5678 from/2023-12-26 to/2023-12-28 adds the dates 26, 27, and 28 December 2023 to the leaves taken by employee with id EID1234-5678.

• addleave id/EID1234-5678 from/2023-12-31 to/2023-12-28 is invalid because the start date 2023-12-31 is after the end date 2023-12-28.

• addleave id/EID1234-5678 from/2023-12-28 to/2023-12-30is invalid because the date 28 December 2023 already exists in the leave list.

Deleting a leave period of an employee : deleteleave

Deletes the specified leave dates of an employee.

Format: deleteleave id/EMPLOYEE_ID from/START_DATE to/END_DATE

• Delete any leave dates that are between START_DATE and END_DATE inclusive from the leaves taken by employee with id EMPLOYEE_ID.
• EMPLOYEE_ID must follow the EID format (EID[4 digits]-[4 digits]).
• START_DATE and END_DATE must be in the YYYY-MM-DD format.
• START_DATE must not be after END_DATE.
• There should be at least one existing leave taken by the employee that falls within the period between START_DATE and END_DATE inclusive.
• If the employee does not have any leaves taken that fall anytime during the period between START_DATEand END_DATE inclusive, the command will output an error and will not change anything.

Tip: If the current date is deleted, the leave status of the employee will change from “On Leave” to “Present”.

Examples:

• deleteleave id/EID1234-5678 from/2023-12-26 to/2023-12-28 deletes all leave dates of employee with id EID1234-5678 that fall on 26, 27, and 28 December 2023.

• deleteleave id/EID1234-5678 from/2023-12-31 to/2023-12-28 is invalid because the start date 2023-12-31 is after the end date 2023-12-28.

• deleteleave id/EID1234-5678 from/2023-12-28 to/2023-12-28 is invalid because there is no existing leave on 28 December 2023.

Tip: There is currently no feature for viewing the full list of leaves taken by an employee. However, you can curb this by adding a “dummy” leave using addleave before deleting the added “dummy” leave using deleteleave. You should be able to view the list of leaves taken by the employee in the Result Display.

Editing a leave date of an employee : editleave

Edits the old leave date to the new leave date of the specified employee.

Format: editleave id/EMPLOYEE_ID old/OLD_DATE new/NEW_DATE

• Edits leave on OLD_DATE to NEW_DATE of the specified employee with id EMPLOYEE_ID.
• EMPLOYEE_ID must follow the EID format (EID[4 digits]-[4 digits]).
• OLD_DATE and NEW_DATE must be in the YYYY-MM-DD format.
• OLD_DATE must already exist and NEW_DATE must not already exist.

Tip: If OLD_DATE is the current date, the leave status of the employee will change from “On Leave” to “Present”. Conversely, if NEW_DATE is the current date, the leave status of the employee will change from “Present” to “On Leave”.

Examples:

• editleave id/EID1234-5678 old/2023-12-26 new/2023-12-28 edits the leave on 26 December 2023 to 28 December 2023 for employee with id EID1234-5678. The old leave date is replaced by the new leave date in the leave list.

• editleave id/EID1234-5678 old/2023-12-31 new/2023-12-28 is invalid because there is no existing leave on 31 December 2023.

• editleave id/EID1234-5678 old/2023-12-27 new/2023-12-28 is invalid because there is an existing leave on 28 December 2023.

Listing the employees on leave on a specified date : listleave

Lists all the employees on leave on the specified date.

Format: listleave on/DATE

• Lists all the employees who are on leave on the specified DATE.
• DATE must be in the YYYY-MM-DD format.

Examples:

• listleave on/2023-12-28 lists all the employees that are on leave on 28 December 2023.

• listleave on/2023-12-29 displays an empty list because there are no employees that are on leave on 29 December 2023.

Adding a remark for an employee : addremark

Adds the specified remark to the specified employee.

Format: addremark id/EMPLOYEE_ID r/REMARK

• Adds the REMARK to the employee with the specified EMPLOYEE_ID.
• EMPLOYEE_ID must follow the EID format (EID[4 digits]-[4 digits]).
• REMARK must be unique. Duplicate remarks are not allowed.
• REMARK is case-insensitive (e.g. good remark and GOOD REMARK are taken to be equal).

Examples:

• addremark id/EID1234-5678 r/good worker adds the remark good worker to employee with id EID1234-5678.

• addremark id/EID1234-5678 r/GOOD WORKER is invalid because there is already a remark good worker for the employee.

Tip: To view the entire list of remarks of an employee, use the report command with the respective employee id.

Deleting a remark of an employee : deleteremark

Deletes the specified remark from the specified employee.

Format: deleteremark id/EMPLOYEE_ID r/REMARK

• Adds the REMARK to the employee with the specified EMPLOYEE_ID.
• EMPLOYEE_ID must follow the EID format (EID[4 digits]-[4 digits]).
• REMARK must already exist in the remark list.
• REMARK is case-insensitive (e.g. good remark and GOOD REMARK are taken to be equal).

Examples:

• deleteremark id/EID1234-5678 r/good worker deletes the remark good worker from employee with id EID1234-5678.

• deleteremark id/EID1234-5678 r/team player is invalid because the remark team player does not exist under the employee with id EID1234-5678.

Updating overtime hours of an employee : overtime

Updates the overtime hours of an employee.

Format: overtime id/EMPLOYEE_ID o/OPERATION a/AMOUNT

• Updates the overtime hours of the employee with the specified EMPLOYEE_ID in EID format (EID[4 digits]-[4 digits]).
• OPERATION can be either inc or dec to increase or decrease the overtime hours respectively.
• OPERATION is case-sensitive (i.e. INC is invalid).
• AMOUNT is the number of hours to increase or decrease the overtime hours by.
• AMOUNT must be a positive integer (i.e. greater than 0).
• The total number of overtime hours worked in a month must not exceed the maximum of 72 as per the Singapore Ministry of Manpower’s guidelines.

Examples:

• overtime id/EID1234-5678 o/inc a/10 increases the overtime hours of employee with id EID1234-5678 by 10 hours.

• overtime id/EID1234-5678 o/inc a/0 is invalid because the given amount is not a positive integer.

• overtime id/EID1234-5678 o/dec a/20 is invalid because it will result in negative overtime hours.

Tip: To view the total number of overtime hours and overtime pay of an employee, use the report command with the respective employee id.

Generating a report : report

Generates a report with details on leaves, overtime hours, overtime pay, and remarks for an employee.

Format: report EMPLOYEE_ID

• Generates and downloads a report for the employee with the specified EMPLOYEE_ID.
• The EMPLOYEE_ID must follow the EID format (EID[4 digits]-[4 digits])
• The report is downloaded in a .txt file, located in the reports folder in the location of hour.jar.
  • The .txt file follows the naming convention DATE_NAME where DATE is the date the report is created, and NAME is the name of the corresponding employee.
  Tip: Note that unlike the hour.json file in the data folder, making changes in the .txt file in the reports folder does not change the data seen in the HouR app.
• The overtime pay is calculated based on the overtime hours and the salary of the employee.

  • The following Singaporean Ministry of Manpower’s prescribed formula is used to calculate overtime pay.

    

Tip: The remarks displayed in the report are arranged in the order they were added, i.e. remarks added later will be added to the end of the remark list.

Examples:

• report EID1234-5678 generates and downloads a report for the employee with employee id EID1234-5678.

• report EID0000-0000 is invalid because the id does not exist.

Resetting fields : reset

Resets the specified field to its default value.

Format: reset f/FIELD

• Resets the specified FIELD of all employees in the employee book.
• The FIELD has to be non-empty and can only be either overtime or leaves.
• The FIELD parameter is case-insensitive. (e.g. overtime and OVERTIME are taken to be the same)

Examples:

• reset f/overtime resets the overtime hours of all employees in the list to the default value 0.

• reset f/leaves resets the number of leaves taken by all employees in the list to the default value 0.

• reset f/name is an invalid field and cannot be reset.

Miscellaneous Features

The following are miscellaneous features available to users.

Saving the data

HouR 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

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

Caution: DO NOT modify data directly as it might result in the malfunction of the application.If your changes to the data file makes its format invalid, HouR will discard all data and start with an empty data file at the next run. We recommend that users download a backup of the file before editing it.

FAQ

Launching HouR

Q: How can I launch HouR if clicking on the JAR file does not work?
A: There are two possible methods to launch HouR.

Method 1: For users familiar with the Command Prompt

1. Open the Command Prompt
2. Navigate to the directory where the JAR file is located using cd [JAR file location]
3. Type java -jar hour.jar and press Enter
4. HouR should launch

Method 2: For users that wish to create a script to launch HouR (Recommended)

1. Create a new text file
2. Copy and paste the following into the text file: java -jar [JAR file location]/hour.jar
3. Save the text file as hour.bat (Windows) or hour.sh (macOS/Linux)
4. Change the admin settings of the script to allow it to run as program:
   • Windows: Right-click on the script and select Properties. Under General, check the box that says Allow this file to run as a program.
   • macOS/Linux: Open the Terminal and navigate to the directory where the script is located. Type chmod +x [script name] and press Enter.
     Note: (chmod +x changes permissions of the script to allow it to be executed)
5. Double-click on the script to launch HouR
6. HouR should launch

If you have any further issues, please raise an issue on our Github page. We will attend to you as soon as we can.

Checking Java Version

Q: How can I check my Java version?
A: Open a Command Prompt and type java -version. If you do not have Java installed, you can install Java 11 using the Oracle guide here. Alternatively, you can install the OpenJDK version.

For macOS users, you may wish to follow the instructions listed here.

Loading Data from Another Computer

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

Q: How can I load data from one computer into HouR installed on another computer?
A: This can be done by following the three steps below.

1. Delete the hour.json file (stored at [hour.jar file location]/data/hour.json) from the computer that you wish to use HouR on.
2. Copy over the hour.json file from the computer which you no longer wish to use HouR on.
3. Boot up HouR to check whether your employee information is properly loaded into the new computer

Using HouR

Q: What are the available commands?
A: Refer to the Command Summary for the list of available commands. Alternatively, from the main application window, you can type help to view the list of available commands.

Q: Do I need an internet connection to use HouR?
A: All of HouR’s functionality can be used offline! No internet connection is required.

Q: How do I save my data?
A: Data is saved in the hard disk automatically after any command that changes the data. There is no need to save manually.

Q: How do I view the leave dates taken by a specific employee?
A: Unfortunately, HouR does not currently have a command to allow the users to view the leaves taken by an employee. To overcome this, we recommend that you add a “dummy” leave with addleave, before deleting the added “dummy” leave deleteleave. You should be able to view the list of leaves taken by the employee in the Result Display.

Q: How do I find out the number of leaves an employee has remaining?
A: To do so, simply type in the report command using the ID of the employee you are interested in. From there, HouR’s result display will show you the number of leaves already taken by the employee.
Since an employee can take a maximum number of 14 leaves, to calculate the number of leaves remaining:

number of leaves remaining = 14 - number of leaves used

Q: How do I view the number of overtime hours worked by a specific employee?
A: To do so, simply type in the report command using the ID of the employee you are interested in. From there, HouR’s result display will show you the number of overtime hours worked by the employee.

Q: Can I reset fields for specific employees rather than all employees?
A: Unfortunately, HouR only allows fields like leaves taken and overtime hours worked to be reset for all employees using the reset command. If you would like to reset the number of leaves or overtime hours for a specific employee, you can follow the steps below.

1. Resetting the number of leaves
   1. View the leave dates taken by the specified employee by adding a “dummy” leave, before deleting the added “dummy” leave.
   2. From the list of leaves taken by the employee, identify the earliest and latest leave date taken.
      e.g. If an employee with employee ID “EID1234-5678” has a total of 3 leaves taken, 14-16 November 2023, 14 November 2023 and 16 November 2023 are the earliest and latest leave dates taken respectively.
   3. Use the deleteleave command to delete all the leave dates under the employee.
      e.g. As per the above example, we would type deleteleave id/EID1234-5678 from/2023-11-14 to/2023-11-16 into the command box.
   4. All the leaves will be deleted from the employee, and the employee’s number of leaves taken will be successfully reset to 0.
2. Resetting overtime hours
   1. View the number of overtime hours taken by the specified employee using the report command.
   2. Using the overtime command, subtract the overtime hours of the specified employee by the number of overtime hours already worked.
      e.g. If the employee with employee ID “EID1234-5678” has worked 12 overtime hours, overtime id/EID1234-5678 o/dec a/12 will successfully reset the employee’s overtime hours to 0.

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.

Command summary

Parameter information

The table below provides information on the usage of the allowed parameters in HouR. Do note that the examples given are not exhaustive.