PROJECT: Invités

Introduction

Preface: The purpose of this portfolio is to document my contributions, both technical and documentation-wise, to my software engineering project Invités.

Project scope and my contribution

Invités is a desktop application to help event managers and planners better organise and manage large events. Moreover, the application can mainly be controlled by a 3rd party using the Command Line Interface, as well as a Graphical User Interface (GUI).

ProductWorkflow Diagram 1 - Product Workflow

Invités was developed as part of my team’s Software Engineering Project, and some of its main features include the ability to send mass emails, keep track of payments, as well as keep track of attendance. To add to this, by using a standardised format, the application is able to take in Comma Separated Value (CSV) files and import data for a particular event.

Thanks to the complementary features my group implemented, we were able to create a streamlined workflow for event planners and managers, as depicted in Diagram 1 on the left.

My contribution involved implementing the mass-emailing functionality in our product, which allows you to send emails to individual, or all of your guests. Furthermore, an added ticket generation feature is also available, whereby you may send guests their tickets for the event. This feature is extremely crucial as it allows event managers to quickly inform all of their guests regarding details of the event in a swift and efficient manner, and eliminates the need of sending individual emails. Moreover, the ticket generation will also provide an environmentally-friendly alternative to printing tickets and banners for an event.

Team Invités

The team that worked with me on this project, as well as the features they implemented, is listed below:

  1. Sandhya Gopakumar - Events management

  2. Sarah Taaher Bonna - Guest list management

  3. Tan Tze Guang - Attendance management

  4. Tan Wei Ming - Data sharing

Summary of contributions

Preface: The purpose of this section is to list the contributions I have made to project Invités.

  • Main Feature: added the ability to send mass emails to guests

    • What it does: allows you to either send emails to individual guests using the command email, or send mass emails using the emailAll and emailSpecific commands.

    • Justification: This feature will allow event managers to streamline their event notification process and inform all of their guests at once, regarding details of the event or otherwise. Furthermore, ticket generation provides users a digitised and economical solution for attendance taking once the event goes live.

  • Code contributed: [Contributed code]

  • Minor enhancement: added an addTag and removeTag command that adds or removes a set of tags to/from all guests in the list

  • Other contributions:

    • Project management:

      • Managed releases v1.1, v1.2, v1.2.1, v1.3, v1.3.9 (5 releases) on GitHub

      • Setup Travis, AppVeyor, auto-publishing of documentation, and issue and milestone tracker

    • Enhancements to existing features

      • Changed UI response for incorrect commands

      • Added a UI component to display number of guests in the current list in the footer of the application

    • Community

      • Reviewed Pull Requests (PRs) for several milestones to provide team members with ample and timely feedback - [#112] [[#153] #202] [#274] [#312]

      • Issues created to better structure the project workflow and ensure an iterative design process - [#121] [#133] [#178] [#239]

    • Tools

      • Integrated a third party library to enable email communication JavaMail API

Contributions to the User Guide

Preface: This section details the contributions I have made to the User Guide, and shows my ability to write documentation targeting end-users.

Adding a set of tags to all guests : addTag

This command allows you to add a set of tags to all guests in the current filtered guest list.
Format: addTag [t/TAG]…​

  • The addTag command will add any number of tags provided by you to all guests.

  • You must provide tags that are alphanumeric, otherwise the system will give you an error.

  • Moreover, if you provide empty tags, or tags that all your guests already have, the system will throw an error.

Examples:

  • addTag t/Veg t/VIP
    You will add the tags Veg and VIP to all guests in the current filtered list.

  • addTag t/@
    This will present you with an error as all your tags must be alphanumeric.

  • addTag
    You will receive an error message as you have provided empty tags.

Removing a set of tags from all guests : removeTag

This command allows you to remove a set of tags from all guests in the current filtered guest list.
Format: removeTag [t/TAG]…​

  • The removeTag command will remove any number of tags provided by you from all guests.

  • If the tags you provided are not shared by any of the guests in the current list, the system with throw an error.

  • You must provide non-empty tags, e.g. an input of removeTag will not do anything.

  • You must provide tags that are alphanumeric, otherwise the system will throw an error.

Examples:

  • removeTag t/Veg t/VIP
    You will remove the tags Veg and VIP from all guests in the current filtered list.

  • removeTag
    This will present you with an error, as you have not provided any tags to delete.

  • removeTag t/@!*
    This will present you with an error, as all your tags must be alphanumeric.

Sending emails to individual guests : email

Please ensure you have gone through Enabling Email Services first in order for this feature to work!

With this command you can send an email, with a QR code attachment, to the guest at a specific Index
Format: email INDEX

  • Sends an email to the guest at the specified INDEX.

  • The index refers to the index number of the guest as shown in the displayed guest list.

  • The index must be a positive integer 1, 2, 3, and cannot be out of bounds. For example, if there are 4 guests in your application, the command email 5 will give you an error as a guest does not exist at INDEX 5.

Examples:

  • email 2

    1. First, you will be presented with an EmailWindow similar to Figure 5 below.

    2. This window is for you to input your email address, password, email subject and message.

    3. You will then need to fill in all the required fields. If you miss any of the fields and try to click the Send button, an error message will pop up like the one in Figure 6.

    4. Once all fields are filled, you can click the Send button to send your email to the 2nd guest in the list. You can also click the Quit button if you do not want to send your email.

    5. If you are successful, you will see a message that says Successfully sent email!.

EmailWindow Figure 5 - EmailWindow

EmailWindowMissingMessage Figure 6 - Missing email message

Sending an email to all guests : emailAll

Please ensure you have gone through Enabling Email Services first in order for this feature to work!

With this command you can an email (no QR code attachments for this command) to all of the guests in the current filtered list
Format: emailAll

You should not enter any characters after the command word, only extra spaces are allowed! For example, the input emailAll extra_characters or emailAll 182$* will be incorrect, but emailAll   (i.e. with spaces) will be correct.

Examples:

  • list

  • emailAll

    1. The command list will list all your guests to ensure you send an email to all guests.

    2. First, you will be presented with an EmailWindow similar to Figure 5 above.

    3. This window is for you to input your email address, password, email subject and message.

    4. You will then need to fill in all the required fields. If you miss any of the fields and try click the Send button, an error message will pop up as the one in Figure 6 above.

    5. Once all fields are filled, you can click the Send button to send your email to all guests in the list. You can also click the Quit button if you do not want to send your email.

    6. If you are successful, you will see a message that says Successfully sent email!.

Sending emails to specific groups of guests : emailSpecific

Please ensure you have gone through Enabling Email Services first in order for this feature to work!

With this command you can send an email (no QR code attachments for this command) to all the guests with at least one of the tags specified+ Format: emailSpecific [t/TAG]…​

  • If the tags you provided are not shared by any of the guests in the current list, the system will throw an error

  • You must provide non-empty tags; an input of emailSpecific will not do anything.

  • You must provide tags that are alphanumeric, otherwise the system will throw an error.

Examples:

  • emailSpecific
    This will present you with an error, as you have not provided any tags to delete

  • emailSpecific t/@!*
    This will present you with an error, as all your tags must be alphanumeric

  • emailSpecific t/VIP t/Garbage

    1. This command will send an email to all the guests with a VIP tag, assuming no guest has the tag Garbage! (You can provide such Garbage tags!)

    2. First, you will be presented with an EmailWindow similar to Figure 5 above.

    3. This window is for you to input your email address, password, email subject and message.

    4. You will then need to fill in all the required fields. If you miss any of the fields and try click the Send button, an error message will pop up as the one in Figure 6 above.

    5. Once all fields are filled, you can click the Send button to send your email to all guests in the list. You can also click the Quit button if you do not want to send your email.

    6. If you are successful, you will see a message that says Successfully sent email!.

Enabling Email Services

In order for you to use the commands email, emailAll, and emailSpecific you must allow Invités to access your email account and send emails. Currently, our application only supports Gmail accounts, but we do plan on supporting other email domains.

If you do have a Gmail account, please follow these steps to enable email services:

  1. Login to your Gmail account using your preferred online browser (e.g. Chrome, Firefox).

  2. Click on your profile picture on the top right, and click on Google Account

  3. Once you are re-directed, under the Sign-in and security section, click on Apps with account access

  4. Scroll down till you find the section Allow less secure apps on the right. Set this option to ON.

  5. You are now ready to send emails to your guests through Invités!

Currently there is no other way to enable mailing services than to let your Gmail account allow less secure apps. However, our team is working quickly to find a more secure replacement.
If your operating system is macOS Mojave, please make an important note of the following:

  1. If you use any of the email-related commands (i.e. email, emailAll or emailSpecific), you will be presented with an EmailWindow similar to the one in Figure 5.

  2. If you use the command-tab keys when the EmailWindow is open to switch windows, the application will crash. This is due to Apple’s latest macOS release, in which some of the bindings are not compatible with key JavaFX functions.

  3. This issue does not occur on Windows, Linux, and older macOS systems, however it may still exist in other operating systems we have not tested on.

  4. We sincerely apologise for the inconvenience caused, and our team is quickly trying to fix this issue.

For testing purposes, you may use a default Gmail account we have created to save you some time:

Email Address: invitestestpe1@gmail.com

Password: practicalexam1

Contributions to the Developer Guide

Preface: This section details the contributions I have made to the Developer Guide, and shows my ability to write technical documentation to explain the implementation of my contributions, as well as methods to allow manual user-testing.

Email Functionality

High Level Algorithm Design

The email functionality, comprising of the commands email, emailAll, and emailSpecific, allows the user to send individual and mass emails to their guests. Moreover, all three commands will open a popup window to prompt the user to enter their relevant details, namely their email address and password, as well as the email subject and message. Currently Gmail is the only supported domain for the user’s email address, however the implementation of this function easily allows for more domains to be supported.

Additionally, the main location of the email functionality’s implementation resides within the Logic component, with an additional UI component to allow the user to input their details.

EmailAllClassDiagram
Figure 1. EmailAll Class Diagram

The figure above captures the main interactions between all classes when the user executes an emailAll command.

  • The command depends on the class EmailPasswordAuthenticator for verification of the user’s email credentials and the abstract class Email. The Email class creates the email object to be sent, as well as establishes a connection with Gmail’s SMTP server via Properties.

  • Moreover, the creation of the UI window is facilitated by the class EmailWindow, which also returns the email data once you input your details.

  • Furthermore, the email object is created thanks to the MimeMultiPart class, and comprises of two main parts:

    • The first part is the text input the user provided in the UI window, which is used by MimeMessage and MimeBodyPart, both of which implement the interface MimePart.

    • The second part is the QR code which acts as the guest’s ticket and is generated by QrUtil. Note that currently only the email command generates the QR code.

  • Finally, the email, with all its contents, is sent via the abstract class Transport.

Command Mechanism

MailCommandActivityDiagram
Figure 2. MailCommand Activity Diagram

The figure above represents an activity diagram when the user executes the email command. As you can see, the command involves error checking, followed by creating an email object, and finally sending this email to an individual guest. Furthermore, this procedure follows the interactions described earlier.

Design Considerations

Aspect: Creating an EmailWindow for user input

  • Current choice: Creating the UI component directly from the abstract class Email.

    • Pros: Reduces dependencies with other UI components and increases cohesion with Email class.

    • Cons: Does not use a controller to create the UI component, it is called directly from logic component Email.

  • Alternative: Create a controller for showing EmailWindow.

    • Pros: Will fit with the software architecture of the codebase.

    • Cons: Current model will have to be changed to allow feed back of user input.

Aspect: Implementing email verification of guest email addresses

  • Current choice: Email addresses are only checked for validity, not whether they exist.

    • Pros: Efficient way to send mass emails without slowing down the program for verification.

    • Cons: User will be unaware if the guest email address does not exist, which may affect communication.

  • Alternative: Implement email validation for all possible email domains.

    • Pros: User is able to check which guest email addresses do not exist.

    • Cons: Would make the codebase bulkier and require multiple email domain configurations.

Sending individual emails

  1. Send individual guests an email with a QR code attachment

    1. Test case: email 1

      1. Expected: Assuming there is at least one guest, UI Window opens to allow user input. If all inputs are valid, email is sent to the guest at INDEX 1.

    2. Incorrect commands to try: email The President, emailLL, email 12.3, etc.

      1. Expected: No email sent due to incorrect parameters.

Sending all guests an email

  1. Send all guests an email (no QR code attachments for this command)

    1. Test case: emailAll

      1. Expected: Assuming there is at least one guest, UI Window opens to allow user input. If all inputs are valid, email is sent to all guests.

    2. Incorrect commands to try: emailAll Celebrities, emailAllLL, etc.

      1. Expected: No email sent due to incorrect parameters.

Sending a group of guests an email

  1. Send an email to a group of guests (no QR code attachments for this command)

    1. Test case: emailSpecific t/Veg

      1. Expected: Assuming there is at least one guest with tag Veg in the filtered list, UI Window opens to allow user input. If all inputs are valid, email is sent all guests with tag Veg

    2. Incorrect commands to try: emailSpecific Puppies, emailSpecific t/@&@ etc.

      1. Expected: No email sent due to incorrect parameters.