Sun Bangjie - Project Portfolio

PROJECT: Part-time Manager (PTMan)

Overview

Part-Time Manager (PTMan) is a desktop human resource application used for managing part-time employees in outlets such as bubble tea shops and fast food restaurants. PTMan aims to give part-time employees the freedom of choosing when they want to work by registering for the available shifts set by the outlet managers. Instead of huge amount of paper work and time spent on communication via phone calls and messages, PTMan helps both managers and employees reduce the hassle of work scheduling.

The user interacts with the application using a Command Line Interface (CLI), and it has a Graphical User Interface (GUI) created with JavaFX. It is written in Java, and has about 10 kLoC.

This project portfolio page aims to showcase my work in the project.

Summary of contributions

Major enhancement: Added the outlet feature.
- What it does:
  - It allows outlet managers to edit outlet information including name, operating hours, contact number and email.
  - It allows managers to create and broadcast announcement to all employees.
  - It allows managers to encrypt and decrypt data stored in local storage files.
- Justification: This feature improves the product significantly because:
  1. Outlet information is unique and essential. Operating hours will determine the timetable and working schedule. Contact number and email will be used to receive admin password reset. This outlet feature provides convenient ways for managers to manage the outlet.
  2. Creating and broadcasting announcement is necessary as it enhances communication between managers and employees.
  3. Encryption and decryption of local storage files prevents any group of people who do not have the access from interpreting the private and important data, and protects the credential of data.
- Highlights: This enhancement modifies the existing model to store outlet information. It also modifies the UI component to display outlet information. There were design considerations to integrate outlet information into the existing model while minimizing coupling with the other components. This enhancement also changes the storage component significantly as data stored can be encrypted and decrypted.
Minor enhancement: added functionality that backs up local storage files to .backup files.
Code contributed: [Functional code] [Test code]
Other contributions:
- Project management:
  - Managed release v1.3 (1 release) on GitHub.
- Enhancements to existing features:
  - Provided methods to encrypt and decrypt local storage files. (Pull requests: #121, #145, #193)
- Documentation:
  - Updated user stories, use cases and NFRs in Developer guide: #2, #10
  - Updated formatting of Developer Guide: #23
  - Updated manual testing in Developer Guide: #231
- Community:
  - Reported bugs and suggestions for other teams in the class (examples: #142)

Contributions to the User Guide

Given below are sections I contributed to the User Guide. They showcase my ability to write documentation targeting end-users.

Outlet Management

If you are a manager, PTMan allows you to manage your outlet. You can edit your outlet name, operating hours, contact number and email. The timetable automatically re-sizes according to the operating hours. You can also create announcements to broadcast to your employees. Moreover, PTMan allows you to encrypt and decrypt data stored locally to prevent unauthorised users from interpreting and understanding essential and private data.

If you are an employee, you can view announcements created by your manager and take actions accordingly.

Figure 1 shows the Outlet Display where you can view your outlet information.

Figure 1. Sample Outlet Information Displayed

Editing the outlet information: `editoutlet`

Edits the outlet information.

Format: editoutlet n/OUTLET_NAME h/OPERATING_HOURS c/CONTACT_NUMBER e/EMAIL
Shorthand: eo n/OUTLET_NAME h/OPERATING_HOURS c/CONTACT_NUMBER e/EMAIL

At least one of the optional fields must be provided.
Existing values will be updated to the input values.
OPERATING_HOURS are in HHMM-HHMM format.

Ensure that the outlet email is valid as it will be used to reset the admin password should you forget it.

Guided Example:

To edit the name, operating hours, contact number, and email of the outlet, key in the following as shown in Figure 2.

Figure 2. PTMan Edit Outlet Information Command
Upon successful execution of the command, you would see a confirmation message below the command bar, and the changes applied to the outlet information. Figure 3 shows how PTMan should look like after the above command.

Figure 3. Successful Edit of Outlet Information in PTMan
To edit only the name and contact number, key in the following as shown in Figure 4

Figure 4. PTMan Edit Selective Outlet Information Command
Upon successful execution of the command, a confirmation message will be displayed in the result display, and changes will be applied to the outlet information. Figure 5 shows how PTMan should look like after the above command.

Figure 5. Successful Edit of Selective Outlet Information in PTMan

Creating an announcement: `announcement`

Sets an announcement for the outlet.

Format: announcement ANNOUNCEMENT_MESSAGE
Shorthand: announce

Guided Example:

To make an announcement in PTMan, type the following command as illustrated in Figure 6.

Figure 6. PTMan Announcement Command
When a successful announcement is made, a confirmation message will be displayed in the result display, and the changes will be applied to the announcement. Figure 7 shows how PTMan should look like after the above command.

Figure 7. Successful Announcement Made in PTMan

Encrypting the local storage files: `encrypt`

Encrypts data stored in the files of the data folder.

Format: encrypt

Guided Example:

After your encrypt command is executed successfully, a confirmation message will be displayed in the result display as shown in Figure 8.

Figure 8. Successful Encryption of Local Files in PTMan

You can view your data stored in local files with the following steps:
1. Open the folder where your app PTMan.jar is at.
2. Open the folder named data. You will see two files outletinformation.xml and parttimemanager.xml there.
3. Open outletinformation.xml with Internet Explorer (IE) or your favourite editor. The third line of the file indicates the encryption status with reference to Figure 9.
Figure 9 shows an example of what the outletinformation.xml file should look like when the encrypt command is successfully executed.

Figure 9. Example of an Encrypted outletinformation.xml File

Decrypting the local storage files: `decrypt`

Decrypts data stored in the files in data folder.

Format: decrypt

Guided Example:

After your decrypt command is executed successfully, a confirmation message will be displayed in the result display as shown in Figure 10.

Figure 10. Successful Decryption of Local Files in PTMan
Open outletinformation.xml file again, now you can read and understand the data stored as shown in Figure 11.

Figure 11. Example of a Decrypted outletinformation.xml File

Viewing encryption status: `viewencrytion`

Shows encryption status of local storage files.

Format: viewencryption
Shorthand: ve

Guided Example:

After your viewencryption command is executed successfully, the encryption status will be displayed in the result display as shown in Figure 12.

Figure 12. Encryption Status Shown in PTMan

Backing Up the Data

Backup files are automatically created and saved in the hard disk upon exiting the app. There is no need to do backup manually.
Following these steps, you can replace your corrupted local storage files with the backup files:

Copy the backup files named outletinformation.xml.backup and parttimemanager.xml.backup.
Open the folder where you store PTMan.jar.
Open the data folder.
Paste your copied backup files in this data folder.
Rename outletinformation.xml.backup to outletinformation.xml.
Rename parttimemanager.xml.backup to parttimemanager.xml.
Run the app PTMan.jar and you will see all the restored data read from backup files.

Contributions to the Developer Guide

Given below are sections I contributed to the Developer Guide. They showcase my ability to write technical documentation and the technical depth of my contributions to the project.

Outlet Feature

Reason for implementation

PTMan is designed for outlets such as bubble tea shops and fast food restaurants which require a large number of part-time workers. This outlet feature stores essential outlet information such as outlet name, operating hours, contact number, email and admin password. Such details are also important to facilitate other functions such as the access control system and the timetable displayed in the app.

How it is implemented

OutletInformation class

The OutletInformation class represents an outlet in PTMan. It supports commands that utilize attributes of this class. It is also responsible for information displayed in the UI and data stored in local storage files.

Figure 13 is a class diagram that displays the association between OutletInformation and other classes in the Model.

Figure 13. Overview of the OutletInformation Class in the Model Component

With reference to Figure 13, an OutletInformation object stores a boolean value isDataEncrypted and six other attributes, including masterPassword, outletName, operatingHours, outletEmail, outletContact and announcement. Currently, the OutletInformation object initialized in the PartTimeManager is created by calling its default constructor:

OutletInformation outlet = new OutletInformation();

This default constructor initializes a boolean value isDataEncrypted to false and six other attributes to respective default values. This is because with the help of initial values, any employer new to PTMan does not need to create a new OutletInformation object using commands such as addoutlet. It provides convenience for users. Outlet managers can edit those values by entering an editoutlet command after they log in.

Commands

Currently, there are two commands that allow outlet managers to change attributes of the OutletInformation: editoutlet and announcement commands which are implemented in similar ways. The implementation of editoutlet command will be explained in details. In addition, there are also commands that allow managers to encrypt and decrypt local storage files. The implementation of encrypt command and how data is encrypted will be explained in details.

Edit outlet command

The editoutlet command can change outlet name, operating hours, contact number and email, which are displayed in the app as shown in Figure 14. The information displayed will change after a successful command.

Figure 14. Example of the Outlet Information Displayed

When an editoutlet command executes successfully, three events will be raised and handled as shown in Figure 15:

OutletNameChangedEvent updates the outlet name displayed in the app.
OutletInformationChangedEvent updates the operating hours, contact number and email displayed in the app.
OutletDataChangedEvent saves latest outlet information to the local storage file "data/outletinformation.xml".

EditOutletCommandHighLevelSequenceDiagrams

Figure 15. High Level Sequence Diagram for the editoutlet Command

The following sequence diagram (Figure 16) illustrates how an editoutlet command is executed in the Logic Component, and how it interacts with the Model Component.

Figure 16. Interactions inside the Logic Component for the editoutlet n/Edited Outlet Admin Command

Currently, editing outlet information with some fields unspecified is allowed. For example, editoutlet n/OUTLETNAME is a valid command. The reason why it is implemented in this why is that it enables employers to edit only the information required for change.

In order to check whether some fields are specified, several branches are created in the setOutletInformation method of the OutletInformation class. When all fields are null, it throws a new exception as shown below:

if (name == null && operatingHours == null && outletContact == null && outletEmail == null) {
    throw new NoOutletInformationFieldChangeException();
}

This NoOutletInformationFieldChangeException is then handled by the EditOutletCommand. When the exception is caught, the CommandException with a message of command failure will be thrown, with reference to the function below:

try {
    editedOutlet.setOutletInformation(name, operatingHours, outletContact, outletEmail);
} catch (NoOutletInformationFieldChangeException e) {
    throw new CommandException(MESSAGE_EDIT_OUTLET_FAILURE);
}

Encrypt and decrypt commands

Since PTMan stores files locally, it is highly possible that any worker in the outlet can open the storage files and read data inside. Such files store a large amount of essential and private data such as admin password, employees' passwords, employees' phones, addresses, and emails. By using the encrypt command, the data in local storage files can be hidden from any group of people who do not have the access to it. Managers can use the decrypt command to make the files human-readable.

When an encrypt command executes successfully, two events will be raised and handled with reference to Figure 17:

PartTimeManagerChangedEvent saves encrypted or decrypted information of employees and shifts to the local storage file "data/parttimemanager.xml".
OutletDataChangedEvent saves encrypted or decrypted outlet information to the local storage file "data/outletinformation.xml".

Figure 17. High Level Sequence Diagram for the encrypt Command

The following sequence diagram (Figure 18) illustrates how an encrypt command is executed in the Logic Component, and how it interacts with the Model Component.

Figure 18. Interactions inside the Logic Component for the encrypt Admin Command

Currently, the local data is encrypted in the Advanced Encryption Standard (AES) in XML files. The secret key used is a byte array of "TheBestSecretKey". The function below demonstrates how encryption is implemented using javax.crypto.Cipher:

Key key = generateKey();
Cipher c = Cipher.getInstance(ALGO);
c.init(Cipher.ENCRYPT_MODE, key);
byte[] encVal = c.doFinal(data.getBytes());
return Base64.getEncoder().encodeToString(encVal);

The encryption status is stored in OutletInformation as a variable isDataEncrypted. The encryption status stored in local files, with reference to the third line of Figure 19, is always plaintext because it is used to convert strings in XML files to models. In encryption mode, data writen to or read from XML files will be encrypted using encrypt(String plainText) or decrypted using decrypt(String cipherText) respectively.

Figure 19. Example of an Encrypted XML File of Outlet Information

Design considerations

Aspect: implementation of OutletInformation class

Alternative 1 (current choice): Use default constructor to initialize all attributes with default values.
- Pros: Provides convenience to users because they do not have to create a new outlet by themselves.
- Cons: Lacks flexibility to initialize the attributes with user-defined values.
Alternative 2: Use a constructor with more parameters.
- Pros: Allows flexibility in storing outlet information.
- Cons: Needs to be very careful when calling the constructor. Since isDataEncrypted can be initialized to true, users new to this app must be informed clearly that data stored in local files are encrypted. Moreover, the default admin password in the User Guide must be updated to what is initialized in the masterPassword. Otherwise, users are unable to log in with correct password when they start using the app for the first time.

Aspect: implementation of encryption and decryption

Alternative 1 (current choice): Encrypt and decrypt data writen to and read from XML files.
- Pros: Successfully prevents any user of the computer directly interpreting the stored information in a clean and fast way.
- Cons: Still maintains the XML file structure and does not encrypt the title of each element as shown in Figure 19. It is possible that any user with advanced knowledge of data encryption is able to decrypt the data with the found patterns.
Alternative 2: Encrypt and decrypt XML files with the XMLCipher package from apache.org with reference to the code below.
- Pros: Enhances safety of data since there are no more obvious patterns in XML files.
- Cons: Increases difficulty in saving and backing up data in local files because additional encrypted and decrypted files need to be created and replace original files.

public static Document encryptDocument(Document document, SecretKey secretKey, String algorithm) throws Exception {
    Element rootElement = document.getDocumentElement();
    XMLCipher xmlCipher = XMLCipher.getInstance(algorithm);
    xmlCipher.init(XMLCipher.ENCRYPT_MODE, secretKey);
    xmlCipher.doFinal(document, rootElement, true);
    return document;
}