Skip to content

Latest commit

 

History

History
1113 lines (727 loc) · 53 KB

UserGuide.adoc

File metadata and controls

1113 lines (727 loc) · 53 KB
Raw

Alfred - The Hackathon Butler User Guide

By: Team F11-1

Since: August 2019

Licence: MIT

1. Introduction

Alfred is a desktop application to help Hackathons' Human Resource Managers organise a Hackathon event. Hackathons are difficult to manage manually as they involve different groups of individuals, each of whom have a different role to play and agenda to fulfill in the Hackathon. Alfred helps streamline this organisation and management process, allowing you to quickly get up to speed with the logistics and administrative details of the Hackathon you are organising.

Furthermore, Alfred is optimized for those who prefer to work with a Command Line Interface (CLI), while maintaining the benefits of having visual responses in a Graphical User Interface. This means that users mainly interact with Alfred by typing on the keyboard, instead of using the mouse to point and click. Point-and-click functionality is supported, but is not the main focus of the application.

Interested? Well, head to Section 3, “Quick Start” to get started. We hope Alfred serves you well!

2. About

This User Guide introduces you to Alfred’s features and how you can use them to enhance your productivity when organising a Hackathon. You can use Alfred to add and track participants in your Hackathon, assign mentors to participants, keep track of the scores of each team in a leaderboard, undo and redo changes you make, and a whole lot more. Note that Alfred was built for you to focus on and organise a single Hackathon event.

Alfred was designed to be as easy to use as possible, and the only assumption we made is that users are comfortable typing into a keyboard to interact with Alfred. No other technical knowledge is needed! It’s that simple.

Alfred is designed to be cross-platform and is available for the Linux, Windows and Mac OS operating systems.

Some simple conventions are used for this User Guide:

  1. Commands - You will typically interact with Alfred through what we call "commands". Each command is simply some text that you enter into Alfred. The command text that you should enter at the command line is formatted as user input

3. Quick Start

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

  2. Download the latest alfred.jar here.

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

  4. Double-click the file to start the app. Alternatively, if you use a Mac, type the command java -jar alfred.jar or replace alfred.jar with the name of the jar file downloaded. on terminal in the jar file’s directory to open and start the app. The GUI should appear in a few seconds.

    UiAnnotated
    Figure 1. Layout of the application

  5. Type the command in the command box and press Enter to execute it.
    e.g. typing help and pressing Enter will open the help window.

  6. Here are some sample commands you can experiment with:

    • list teams : lists teams in the hackathon

    • add participant n/Bartholomew Lim p/+6597654321 e/[email protected] : adds a new participant named Bartholomew Lim to the Hackathon.

    • delete participant P-1 : removes the participant with ID P-1 from the hackathon.

    • exit : exits the app

  7. Refer to Section 5, “Features” for details of each command.

4. Parameter Constraints and Additional Information

Entity Types

  • Mentor

    • A mentor has a name, phone number, email address, an organization, and a specialty (i.e. subject name) which must take on values mentioned below under "Parameters."

    • Two mentors are considered as the same mentor if and only if they have the same names along with one of their phone numbers or emails.

  • Participant

    • A participant has a name, phone number, and an email address.

    • Two participants are considered as the same participant if and only if they have the same names along with one of their phone numbers or emails.

  • Team

    • A team has a team name, a subject to focus on, score, its project name, and its location (table number). (For now, many teams can be grouped in 1 location. setting of restrictions coming in v2.0).

    • A team may also contain one mentor and 5 participants (setting of restrictions coming in v2.0).

    • Two teams are considered as the same team if and only if they have the same team names or project names.

All entities will also receive a unique ID, which means no two entity will share the same ID. That is, entities with same ID will also be considered as a same entity. This is to be considered for specific commands such as the Section 5.18.1, “CSV File Formatting” under the Bulk Registration command. Also, do not that entities are randomly generated and are not necessarily in ascending order.

Parameter Constraints

Name, Organization, ProjectName - can be any combination of spaces, letters, and these special characters (,.-')

Phone - can be any combination of numbers (at least three digits), space, hyphens (-), and periods (.) with or without a country code. Country code of Singapore (+65) will be automatically included if it is not added.

Email - must include an address and an email domain. It can include special characters (-,.), excluding bracket.

SubjectName - the subject a mentor or team will be focusing on in the Hackathon
Must be one of the values below:

  • Environmental

  • Social

  • Health

  • Education

  • Entertainment

  • Other

Score - must be an integer ranging from 0 to 100.

Location - must be an integer ranging from 1 to 1000, indicating a table number. Restrictions of the number of teams per table will be coming in v2.0.

5. Features

Prelude - Command Format

  • Words in UPPER_CASE are the parameters which you need to supply. For example, in add mentor n/NAME, NAME is a parameter which you need to specify as the mentor’s name (i.e. add mentor n/John Doe).

  • You can input the parameters in any order. For instance, if the command specifies n/NAME p/PHONE_NUMBER, you may input p/PHONE_NUMBER n/NAME and Alfred will still consider it as an acceptable command.

  • Words in {curly braces} indicate values for the command that you need to select and provide.

    • For example in the case of add {mentor/participant/list}, you can choose to type add mentor, add participant or add team

  • Words in [brackets] indicate values that are optional for the command.

    • For example, in the case of export [CSV_FILE_PATH], you can choose to leave out the file path.

  • Whenever you need to specify an ID, the ID will be prefixed with an alphabet indicating the type of the Entity (e.g. M for Mentors, P for Participants, T for Teams).

  • Type your commands in the textbox displayed on the Alfred UI. After you are done typing the command, press Enter on your keyboard to execute the command.

Also, please refer to Section 4, “Parameter Constraints and Additional Information” for more information on the different restrictions for each parameter.

5.1. Saving the data:

Data in Alfred is saved to the hard disk automatically after any command that changes the data. There is no need for you to save the data manually.

Should any tampering of the data in storage result in an invalid state for the data, the data will be re-initialised and the old data will be lost. Hence, please avoid directly altering the storage files as any minor errors could result in permanent loss of critical information.

5.2. Viewing help : help

If at anytime you don’t understand how to do a certain thing on Alfred, use this command to display a help page in a separate pop-up window.

  • Should you require further information, the pop-up window also includes links to further references and documentation.

To close the window, run any non-help command.

Format: help

5.3. Adding an Entity: add {participant/mentor/team}

Use this command to add a new entity for Alfred to keep track of.

  • Creates an Entity as specified by you. Each Entity object will have a unique ID automatically assigned to it.

  • As of version 1.1, you must provide all the fields. There are no optional fields.

  • Note that the Specialisation and Subject fields can only take on the values specified in SubjectName in Section 4, “Parameter Constraints and Additional Information”:

5.3.1. Adding a Participant: add participant PARAMETERS

Use this command to add a new Participant to Alfred to keep track of for your hackathon.

  • Participants have the fields "Name", "Phone number" and "Email address" which you must provide.

  • For now, to cater to an international audience, we do not check for validity of phone numbers.

Format: add participant n/NAME p/PHONE_NUMBER e/EMAIL_ADDRESS

Examples:

5.3.2. Adding a Mentor: add mentor PARAMETERS

Use this command to add a new Mentor to Alfred to keep track of for your Hackathon.

  • Mentors have the fields "Name", "Phone number" and "Email address."

  • Mentors also have a field called "Organization", which refers to the organization for which they work.

  • Mentors also have a field called "Specialisation", which refers to the field of work they specialise in. The Specialisation can only take on the values specified in SubjectName in Section 4, “Parameter Constraints and Additional Information”.

  • All of these fields must be specified in order to successfully add a mentor.

Format: add mentor n/NAME p/PHONE_NUMBER e/EMAIL_ADDRESS o/ORGANIZATION s/SPECIALISATION

Examples:

5.3.3. Adding a Team: add team PARAMETERS

Use this command to add a new Team to Alfred to keep track of for your Hackathon.

  • Teams have the fields "Name", "Project name" and "Table Number" which you must provide.

  • Teams also have a field called "Subject", which refers the area the team’s project focuses on, and must be chosen from the predetermined list of subjects described in SubjectName in Section 4, “Parameter Constraints and Additional Information”.

Format: add team n/NAME s/SUBJECT pn/PROJECT_NAME l/TABLE_NUMBER

Examples:

  • add team n/Team01 s/Social pn/EmotionTrain l/12

  • add team n/HackathonWinners4Sure s/Environmental pn/Path-ify l/3

5.4. Updating an Entity: edit {mentor/participant/team} ENTITY_ID [PARAMETERS]

Edits an entity based on the parameter values you supply. Use this command in case you want to make changes to an entity you have already created within Alfred.

  • Updates the fields of the Entity with the ENTITY_ID you specified to the new fields you type in as the parameter. The ID is the unique identifier for the particular Entity you wish to edit.

  • You must provide at least one of the optional fields.

  • The fields you provide must pertain to the specified entity in order for the edit to be successful. For instance, you cannot add a field "pn/NewProjectName" for a participant as a participant doesn’t have a project name.

  • Existing values will be updated to the input values you provide.

Examples:

  • edit mentor M-1 n/NewMentorName

  • edit team T-1 n/NewTeamName pn/New Project Name

  • edit participant P-1 n/NewParticipantNAme

5.5. Listing all Entities : list {mentors/participants/teams}

Shows a list of all the entities corresponding to the entity you specified that Alfred keeps track of.

  • The fields of the Entity will be displayed on Alfred’s Graphical User Interface.

Examples:

  • list mentors will list all mentors stored within Alfred.

  • list participants will list all hackathon participants stored within Alfred.

  • list teams will list all hackathon teams stored within Alfred.

5.6. Viewing a Specific Entity: view {mentor/participant/team} ID

Shows a single entity with given ID.

  • The fields of the Entity will be displayed on Alfred’s Graphical User Interface.

Examples:

  • view mentor M-1 will show the mentor with ID M-1 stored within Alfred.

  • view participant P-1 will show the hackathon participant with ID P-1 stored within Alfred.

  • view team T-1 will show the hackathon team with ID T-1 stored within Alfred.

5.7. Deleting an Entity: delete {mentor/participant/team} ID

Deletes an Entity, so that Alfred will no longer keep track of that Entity.

  • Deletes the Entity with the ID that you specify.

  • Note that when you delete a Team, it does not delete the participants or mentors associated with the teams.

Examples:

  • delete mentor M-1 will delete the mentor with ID M-1 from Alfred.

  • delete participant P-1 will delete the participant with ID P-1 from Alfred.

  • delete team T-1 will delete the team with ID T-1 from Alfred.

5.8. Finding a Specific Entity: find {mentor/team/participant} n/NAME …​

Searches for Entities by selected fields, instead of their ID, in case you find that the ID is difficult to keep track of.

  • Take note that the find command only searches and matches the fields whose strings are a substring of the given value. It also does an intersection search in the event where one or more fields are provided, that is, the entities found would have the selected values for each of the fields you key in. This search is case insensitive.

Examples:

  • find mentor n/Joshua Wong will display a list of all mentors in the Hackathon who are named "Joshua Wong", or have "Joshua Wong" in their name.

  • find participant n/John Doe will display a list of all participants in the Hackathon who are named "John Doe", or have "John Doe" in their name.

  • find team n/FutureHackathonWinner will display a list of all teams in the Hackathon that are named "FutureHackathonWinner", or have "FutureHackathonWinner" in their name.

Each entity will have different fields available to find.

For participant, n/NAME e/EMAIL p/PHONE are all options to search for.

For team, n/TEAMNAME pn/PROJECTNAME are also all options to search for.

For mentor, n/NAME, e/EMAIL, p/PHONE o/ORGANIZATION are all available.

Example for multiple fields:

  • find participant n/Damith e/damith.com finds all participants whose name contains the string "Damith" and whose email contains "damith.com"

5.9. Advanced Finding of a Specific Entity by Union or Negative: find [AND/OR] {mentor/team/participant} n/NAME …​ [EXCLUDE] …​

The default find command for single and multiple fields works via a find by intersection. That is, entities must be true for all the predicates for it to be displayed. However, Alfred also supports finding by union.

As above, all find commands are case insensitive.

The commands for this is as such:

  • find participant OR n/Damith e/nus will do a search for all Participants whose name contains "Damith" or whose email contains "nus" in it.

Also do note that for this command, the OR key must be placed before all the arguments to the command. Also, the OR key can be replaced by the AND key to do a search by intersection. If none are provided, then a search by intersection is done by default. The AND/OR keyword must be in caps.

Next, Alfred also supports negative searches, if you wish to do it. Simply run

  • find mentor n/Boss EXCLUDE e/boss.com will return all mentors whose name has a "boss" and whose email does not contain "boss.com"

Also, you can do negative searches by union as well.

  • find mentor OR n/boss EXCLUDE e/boss.com will now return all mentors whose name has a "boss" in it or whose email does not contain "boss.com"

However, there are also some caveats when it comes to using find.

  1. The AND/OR keyword must be placed at the front before all parameters and the EXCLUDE keyword

  2. Anything after the EXCLUDE keyword will be processed using negative find.

  3. No AND/OR keywords are allowed after the EXCLUDE keyword.

  4. You can only search by AND or OR. You cannot do a search by both AND and OR

Some notes on the logic used in find.

  • The logic used in find obeys normal boolean, probabilistic logic.

  • Hence commands like find participant n/Ki EXCLUDE n/Ki will return an empty list.

  • Likewise, commands like find participant OR n/Ki EXCLUDE n/Ki will return the full list.

Other examples of valid commands are also provided here for your reference:

  1. find team OR EXCLUDE n/ArsenalFC pn/Football will do a search of all teams whose name does not contain "ArsenalFC" or whose project name does not contain "Football".

  2. find participant AND n/Abramov EXCLUDE e/react will do a search where participant names contain "Abramov" and whose email does not contain "react". In this case, the AND keyword could have been omitted because the default find does a search by intersection.

5.10. Assigning a Entity to a Team: assign {mentor/participant} ID TEAM_ID …​

Assigns Mentor or Participant Entity by their ID to a team identified by TEAM_ID. It is possible to assign a participant or mentor to multiple teams.

  • Take note that the assign command can only be used to assign Participants and Mentors to a Team.

  • An error will be shown if the Team already has a Mentor.

  • An error will be shown if the Team already has said Participant.

  • An error will be shown if the Team has reach the maximum capacity of five members.

Examples:

  • assign mentor M-18 T-2 will assign a Mentor with ID M-18 to Team with ID T-2. Running the command will show you the following output in the 'Team' section of the GUI:

AssignCommandExample1

  • assign participant P-100 T-2 will assign Participant with ID P-100 to Team with ID T-2. Running the command will show you the following output in the 'Team' section of the GUI:

AssignCommandExample2

5.11. Removing an Entity from a Team: remove {mentor/participant} ID TEAM_ID …​

Removes Mentor or Participant Entity by their ID from a team identified by TEAM_ID.

  • Take note that the remove command can only be used to remove Participant or Mentor from a Team.

  • An error will be shown if the Participant or Mentor is not in the specific Team.

  • Deleting a Participant or Mentor will also delete all their connections with all the teams it belongs to.

Examples:

  • remove mentor M-18 T-8 will remove Mentor with ID M-18 to Team with ID T-8. Running the command will show you the text 'Mentor not assigned' in the respective team. The following will be shown in the 'Team' section of the GUI:

RemoveCommandExample1

  • remove participant P-100 T-2 will remove Participant with ID P-100 from Team with ID T-2.Running the command will show you the following output in the 'Team' section of the GUI

RemoveCommandExample2

5.12. Show Command History: history

Shows you up to the last 50 commands that you executed.

UndoRedoExplanation
Figure 2. History Section of UI

  • This command is to facilitate the undo/redo commands, as it becomes easier for you to track what changes were made before, and which commands can be undone/redone. This is especially useful when many commands have been executed and it is difficult to remember the sequence of execution of the commands.

  • Executing the command will bring you to the "History" section of Alfred, which displays all the previously-executed commands as panels. There are 3 main delimiters. Each delimiter is just a visual representation of the limits for the undo/redo commands.

  • You cannot redo any command beyond the "redo" delimiter.

  • You cannot undo any command beyond the "undo" delimiter.

  • The "current" delimiter tells you where you are at relative to the rest of the commands you have executed. It represents the current state of the data.

  • Note that only commands that change the state of the data in Alfred will be displayed in the "History" section and are undo/redo-able. For instance, list participants will not be undo/redo-able, as it simply shows you the participants in Alfred and does not change any information in Alfred. On the other hand, invoking add participant with the suitable parameters will be undo/redo-able and will be shown in the "History" section by the history command.

  • In total, only 50 states will be stored, so this serves as a limit for the number of commands you can undo/redo to.

ℹ️
 The following commands are not undo/redo-able: help, list, find, history, leaderboard, getTop, export, help, home, undo, redo. All other commands are undo/redo-able.

Example:

After running the following commands:

  1. list participants

  2. add participant n/SuperHero1 p/+6591111111 e/[email protected]

  3. add participant n/SuperHero2 p/+6592222222 e/[email protected]

  4. add participant n/SuperHero3 p/+6593333333 e/[email protected]

  5. edit participant P-4 n/The Flash

Running history will show you the following output in the "History" section of the Graphical User Interface:

HistoryCommandExampleOutput
Figure 3. Output from History Command

The topmost panel is the "redo" delimiter. The second panel from the top is the "current" delimiter. The bottommost panel shows you the "undo" delimiter.

In this example, the output of the history command shows you can invoke the undo command four times.

Notice that the list participants command is not shown in the "History" section as it does not change data.

Also note that the undo-able commands are numbered, with the 1st undo-able command being the most recently executed command (the EditParticipantCommand), and the 4th undo-able command being the oldest executed command. In this case, the maximum number of commands you can undo at once is 4.

Also note that in this case, no commands are redo-able, that’s why there are no panels between the "redo" and "current" delimiters. Hence, executing redo command will result in an error.

5.13. Undo Previous Commands: undo [NUM_COMMANDS_TO_UNDO]

Undoes previously executed commands.

There are 2 ways for you to use this commands:

  1. undo: This implicitly executes undo 1 and undoes 1 command only.

  2. undo [NUM_COMMANDS_TO_UNDO]: This undoes NUM_COMMANDS_TO_UNDO commands, subject to the number of available commands that you can undo, as per the output of the history command.

  • This command undoes the effects of previously executed commands, and will return Alfred to the previous state (as though you had never executed the NUM_COMMANDS_TO_UNDO previous commands)

  • All commands that can be undone can be found in the output of the history command. Use this to see the total number of commands and which commands you can undo.

  • To be certain which command you are actually undo-ing, first run the history command and examine the output.

  • Only the commands that actually change the data in Alfred will be undo-able. Commands that perform read operations (such as find and list) will not be found in the output of the history command. See Section 5.12, “Show Command History: history” for a full list of commands that are not undo-able.

  • Note that NUM_COMMANDS_TO_UNDO must be an integer, and must be a number between 1 and 49 (because only a maximum of 50 states are stored). If NUM_COMMANDS_TO_UNDO exceeds the number of commands that can be undone, Alfred will indicate that the undo command cannot be executed.

Format: undo [NUM_COMMANDS_TO_UNDO]

5.14. Redo Previous Commands: redo [NUM_COMMANDS_TO_REDO]

Redoes previously executed commands.

There are 2 ways for you to use this commands:

  1. redo: This implicitly executes redo 1 and redoes 1 command only.

  2. redo [NUM_COMMANDS_TO_REDO]: This redoes NUM_COMMANDS_TO_REDO commands, subject to the number of available commands that you can redo, as per the output of the history command.

  • This command undoes the effects of previously executed commands, and will return Alfred to the previous state (as though you re-executed the NUM_COMMANDS_TO_REDO previous commands)

  • All commands that can be redone can be found in the output of the history command. Use this to see the total number of commands and which commands you can redo.

  • To be certain which command you are actually redo-ing, first run the history command and examine the output.

  • Only the commands that actually change the data in Alfred will be redo-able. Commands that perform read operations (such as find and list) will not be found in the output of the history command. See Section 5.12, “Show Command History: history” for a full list of commands that are not redo-able.

  • Note that NUM_COMMANDS_TO_REDO must be an integer, and must be a number between 1 and 49 (because only a maximum of 50 states are stored). If NUM_COMMANDS_TO_REDO exceeds the number of commands that can be redone, Alfred will indicate that the redo command cannot be executed.

Format: redo [NUM_COMMANDS_TO_REDO]

5.15. Command History Navigation

Navigate to previous commands by pressing the alt key Alt, together with the up ↑ or down ↓ arrow keys. For Mac users, press the option key Opt in place of the alt key Alt instead. Should you have re-mapped/re-purposed the alt key Alt, press the remapped key on your keyboard instead.

  • Every time you execute a command successfully, the command is saved in Alfred, so you can navigate to a previous command without re-typing the whole thing. There is only 1 exception to this rule: the import command can be navigated to even if there are errors raised during execution. This is because the import command will do its best to import as many Entities into Alfred as possible, before finally notifying the user of any incorrect entries (so there is partial successin the command’s execution).

  • Press Alt + up ↑ to navigate to the previous command.

  • Press Alt + down ↓ to navigate to the next command.

  • Unlike most of the other features in Alfred, this is not a command you type into Alfred’s command input box. This is a keyboard shortcut that is mainly for your convenience as it allows you to quickly re-use previously executed commands.

  • Note that Alfred’s command input box must be in focus (the cursor is active in the command input box) for the keyboard shortcuts for this feature to work

  • This feature only allows you to navigate up to the previous 50 successfully executed commands.

5.16. Scoring: score

The score command allows you to change a particular team’s score. It allows you to:

  • Add points to a team’s score

  • Subtract points from a team’s score

  • Set a team’s score to a certain number of points

  • Reset a team’s score

The usage of the above commands are explained in the following subsections.

5.16.1. Add points: score add TEAM_ID POINTS

Adds the value of POINTS to the current score of the team with ID TEAM_ID.

  • Use this command when you want to award a particular team a certain amount of points.

  • If you try to award more than the maximum amount of points (which is set to 100 points as default), Alfred will not allow it and will display an error message.

  • If the addition of points makes the team’s total exceed the maximum, the score will simply be set to the maximum score.

Format: score add TEAM_ID POINTS

Example:

  • score add T-1 20 will add 20 points to the score of the team with ID T-1.

  • score add T-5 60 will add 60 points to the score of the team with ID T-5.

5.16.2. Subtract points: score sub TEAM_ID NEW_POINTS

Deducts the value of POINTS from the current score of the team with ID TEAM_ID.

  • Use this command when you want to take away a certain amount of points from a particular team.

  • If you try to subtract more than the maximum amount of points (which is set to 100 as default), Alfred will not allow it and will display an error message. If the subtraction of points makes the team’s total go below the minimum (which is set to 0 points), the score will simply be set to 0.

Format: score sub TEAM_ID POINTS

Example:

  • score sub T-1 15 will subtract 15 points from the score of the team with ID T-1.

  • score sub T-5 10 will subtract 10 points from the score of the team with ID T-5.

5.16.3. Set points: score set TEAM_ID NEW_POINTS

Sets the score of the team with ID TEAM_ID to a new score NEW_POINTS, regardless of the team’s current score.

  • Use this command when you want to set a team’s score to an exact score, rather than adding or subtracting points from their current score.

  • If you try to set more than the maximum amount of points (which is set to 100 as default), Alfred will not allow it and will display an error message.

  • If you try to set less than the minimum amount of points (which is set to 0 as default), Alfred will not allow it and will display an error message.

Format: score set TEAM_ID POINTS

Example:

  • score set T-1 15 will set the score of the team with ID T-1 as 15.

  • score set T-5 10 will set the score of the team with ID T-5 as 10.

5.16.4. Reset points: score reset TEAM_ID

Resets the score of the team with ID TEAM_ID to the minimum amount of points allowed, which is set to 0 as default.

  • Use this command when you want to set a team’s score to directly to the minimum, rather than subtracting points from their current score until you get the desired result.

Format: score reset TEAM_ID

Example:

  • score reset T-1 will reset the score of the team with ID T-1.

  • score reset T-5 will reset the score of the team with ID T-5.

5.17. Team Rankings: leaderboard and getTop k

In addition to assigning scores to teams, Alfred also facilitates viewing the leaderboard and fetching the top teams in the hackathon with ease. The following subsections explain how to do so within Alfred.

5.17.1. View Leaderboard: leaderboard

Displays the ranking of all the teams in the hackathon in descending order of their points.

  • Once you run this command, Alfred’s UI will display a list of all the teams stored within Alfred sorted in descending order of their points.

  • By default Alfred sorts teams with equal points in the order they were added into Alfred, based on their ID.

Format: leaderboard

Running leaderboard will show the following on the GUI:

LeaderboardExample
Figure 4. GUI Display for Command "leaderboard"

5.17.2. Get the top k teams: getTop K

Lists the top k teams in the leaderboard, where k is a valid positive integer which you specify.

  • This command will show you a cropped version of the leaderboard.

  • Alfred’s UI will display a list of top "k" teams based on their current score.

  • Do note that this command does not discriminate between teams of the same score - Teams with equal scores will be counted as one. Due to this, the command "getTop 1" (for example) may show more than 1 team if there are more than 1 teams with the same high score.

  • If you input K as a number more than the number of teams in the hackathon, Alfred will simply display all the teams in the Hackathon, in descending order of their points.

Format: getTop K

Example:

  • getTop 2 will display the top 2 teams with the highest points in the hackathon as shown below:

TopTeamExample
Figure 5. GUI Display for Command "getTop 2"

  • getTop 4 will display the top 4 teams with the highest points in the hackathon as shown below:

GetTop4
Figure 6. GUI Display for Command "getTop 4"

Note that due to the tie between the fourth and fifth teams, more than 4 teams are shown.

5.17.3. Extensions to leaderboard and getTop K Command

To provide additional functionalities to the leaderboard and getTop k commands, there are few extensions that can be added to these two commands to allow you to customize them to your needs. These extensions are explored below.

5.17.3.1. Tie-Break

By default Alfred leaderboard and getTop k commands fetch and display teams in descending order of their score, and by the order they were added into Alfred in case of tied scores.

Alfred’s tiebreak feature provides an extension to the leaderboard and getTop k commands allowing you to choose how you want to break the tie between the teams when calling these commands. To break a tie, follow the following format:

  • leaderboard tb/METHOD_1 METHOD_2 METHOD_3 in the case of a leaderboard command

  • getTop NUMBER tb/METHOD_1 METHOD_2 METHOD_3 in the case of a getTop NUMBER command

where METHOD_N is one of the following currently available tie-break methods:

  • moreParticipants: teams with more participants are win the tie.

  • lessParticipants: teams with lesser participants are win the tie.

  • higherId: teams registered more recently (hence the highest ID) win the tie.

  • lowerId: teams registered earlier (hence the lowest ID) win the tie.

  • random: in case all methods used yield no distinct winner, random can be used as a method of last resort to break a tie in favour of a randomly chosen team.

  • You may choose one or more methods from the above list to break the tie. You need to precede the tie-break methods with the prefix tb/ and separate each method with a single space for Alfred to properly understand them.

  • Use the prefix "tb/" with discretion as Alfred will only select tiebreak methods followed by the last "tb/" prefix if more than one such prefix is specfied in the command.

  • Do note that the tie-break methods will be applied in the order in which you state them. That is, first METHOD_1 will be applied to break the ties, and only then will METHOD_2 be applied to break any remaining ties, if the command leaderboard tb/METHOD_1 METHOD_2 is called.

  • The getTop NUMBER command may still display teams more than the value of NUMBER if Alfred was still unsuccessful in breaking certain ties despite applying the tie-break methods you stated.

  • When using the random method, it must be the last stated tie-break method if it is being used alongside other tie-break methods.

Example:

  • leaderboard tb/moreParticipants lowerId will display the leaderboard on the UI with Alfred breaking the tie between teams with equals scores based on which team has more participants, and if the number of participants is equal then by which team has the lower ID.

LeaderboardSimple
Figure 7. GUI Display for Command "leaderboard tb/moreParticipants lowerId"

Note that in the above team "BroBro" comes above team "Bro" despite having the same number of points as "BroBro" has more participants. Secondly, "Amazon Warriors" comes first before "Teen Titans" despite having the same score and number of participants, since "Amazon Warriors" has a lower ID.

  • getTop 3 tb/lessParticipants random will display the top 3 teams on the UI with Alfred breaking the tie between teams with equals scores based on which team has fewer participants, and if the number of participants is equal then Alfred will randomly pick the winners for the tie.

RandomGetTop
Figure 8. GUI Display for Command "getTop 3 tb/lessParticipants random"

Note that in the above "Amazon Warriors" comes first before "Teen Titans" despite having the same score and number of participants, due to the random tiebreak. Repeating the above command would change the outcome due to the random nature of the tiebreak.

5.17.3.2. Filter by Subject

By default, when running either the leaderboard or getTop k command, Alfred will show all the appropriate teams irrespective of their subject. However, Alfred’s filter by subject feature provides the ability to view the leaderboard or top teams for a specific subject, by following the below format:

  • leaderboard s/SUBJECT_NAME in the case of a leaderboard command

  • getTop k s/SUBJECT_NAME in the case of a getTop k command

  • You must precede the subject you want to filter by with the prefix s/ for Alfred to understand your request. You can specify only one subject to filter the leaderboard or top teams by.

  • This extension can be used in addition to tiebreak methods in which case the tiebreak methods will be used to split ties between any teams with the same subject.

Example:

  • leaderboard s/Health will display the leaderboard consisting only of teams with the subject "Health" as shown below:

HealthLeaderboard
Figure 9. GUI Display for Command "leaderboard s/Health"

  • getTop 3 tb/moreParticipants s/Health will display the top 3 teams within the hackathon, all of which will consist of only of those with subject "Health". Additionally, any ties between these teams will be broken using the tiebreak method "moreParticipants" - the team with more participants wins the tie.

HealthMoreP
Figure 10. GUI Display for Command "getTop 3 tb/moreParticipants s/Health"

Note that in the above team "BroBro" goes above team "Bro" as it has more participants, despite both teams having equal scores.

5.18. Bulk Registration: import fp/PATH_TO_CSV_FILE [fp/PATH_TO_ERROR_FILE]

You may import multiple entities at once into Alfred through the specification of a CSV file.
If the PATH_TO_ERROR_FILE is specified, Alfred will create a new CSV file with all of the lines that were not able to be loaded.

Example:

  • import fp/C:/User/Hackathon2019/participant.csv will import data from the participant.csv file into Alfred.

  • import fp/Hackathon2019/participant.csv will look for the CSV file in your current directory (or the folder where alfred.jar is downloaded).

💡
 First, locate the desired file in your respective file manager.
On Windows, hold down shift, click the file, then click Copy as path to copy its file path.
On Mac, right-click the file, hold down OPTION key, then click Copy (item name) as Pathname to copy its file path.

Example usage of error file is shown below.

5.18.1. CSV File Formatting

In order for the contents of the CSV file to be correctly loaded into Alfred, the file has to be in the correct format, which will be discussed below. For most platforms, there will be a default editor for a CSV file. If the editor is anything other than text editor, please ensure that the default separator is set as one comma (,). There may be whitespaces surrounding a comma if it is easier for you to edit.

EntityType - single capital letter representing the entity type

  • Mentor: M

  • Participant: P

  • Team: T

[ID] - the ID of the entity (optional)

  • Mentor: M-d, where d can be any positive integer

  • Participant: P-d, where d can be any positive integer

  • Team: T-d, where d can be any positive integer

    • You can also express ID as only a positive integer.

For the rest of the parameters, please refer to Section 4, “Parameter Constraints and Additional Information”.

5.18.1.1. Mentor Data

Header: EntityType,ID,Name,Phone,Email,Organization,SubjectName

Example:

5.18.1.2. Participant Data

Header: EntityType,ID,Name,Phone,Email

Example:

5.18.1.3. Team Data

Header: EntityType,ID,Name,Participants,Mentor,SubjectName,Score,ProjectName,Location

[Participants] - A list of participant IDs in the team.
This field is optional, but if it is included, participants with given ID must exist in Alfred.

[Mentor] - An ID of the mentor associated with the team.
This field is also optional, but if it is included, mentor with given ID must exist in Alfred.

If you are importing multiple entity data at once, don’t worry! Alfred will make sure Participant and Mentor data are loaded before Team data to ensure that all of them are present in Alfred before checking whether they exist or not.

See example usage down below.

Example:

  • T,T-1,Justice League,,,Social,100,Save the Earth,1

  • T,1,Justice League,[P-1|P-2|P-3],M-1,Social,100,Save the Earth,1

  • T,,Justice League,[P-1|P-2|P-3],1,Social,100,Save the Earth,1

Alfred will recognize each of the entity headers and will not count it as an error. Example CSV file may look like this:

    Alfred.csv

    EntityType,ID,Name,Participants,Mentor,SubjectName,Score,ProjectName,Location
    T,,Justice League,[P-1|P-2],M-1,Social,100,Save the Earth,1
    T,,Amazon Warriors,[P-3|P-4],,Environmental,100,Save the Amazon,2
    EntityType,ID,Name,Phone,Email,Organization,SubjectName
    M,1,Alfred the Mentor,+6512345678,[email protected],Batcave Corp.,EDUCATION
    M,,Joker,,is this my email??
    EntityType,ID,Name,Phone,Email
    P,1,Bruce Wayne,+65 23456789,[email protected]
    P,2,Superman,+6519231486,[email protected]
    P,3,Diana,+6547234328,[email protected]
    P,3,Lois Lane,+6598765432,[email protected]

You can also download a sample CSV file here to try it out for yourself.

Assuming Alfred has no data, we can see that lines 3, 6, and 11 will fail.

  • Line 3: No participant with ID P-4 exist (Missing entity)

  • Line 6: Phone number is missing and email is invalid (Invalid format)

  • Line 11: Another participant with ID P-3 exists (Duplicate entity)

If you give the following command to Alfred,

import fp/Alfred.csv fp/Alfred_Errors.csv

then the following CSV file will be created where Alfred.csv is located at.

    Alfred_Errors.csv

    T,,Amazon Warriors,[P-3|P-4],,Environmental,100,Save the Amazon,2
    M,,Joker,,is this my email??
    P,3,Lois Lane,+6598765432,[email protected]

5.19. Export Data: export [{mentor/participant/team}] [fp/DESIRED_CSV_FILE_PATH]

You may export Alfred data to an external CSV file. If the entity type is specified, Alfred will export all the data corresponding to that entity type only. If the desired CSV file path is left empty, Alfred will create a CSV file at the default location (./AlfredData/Alfred_Data.csv).

Example:

  • export will export all entities' data in Alfred to the default file path: /AlfredData/Alfred_Data.csv.

  • export mentor fp/data/Alfred.csv will export all mentor data in Alfred to /data/Alfred.csv. If the any folders do not happen to exist, Alfred will create them for you.

5.20. Help command

The help command will list all the commands you need to use this application properly!

Simply run help.

If you want the help window to close, simply run another command that is not help and the window will close by itself.

5.21. Home command: home

This command allows you to navigate to the homepage where the system statistics are updated in real time. The homepage statistics are also available when you start-up the application.

Example: Suppose you want to check the distribution of teams by subjects, in order to gauge the demand for mentors for each subject.

Instead of manually sieving through all the teams by the subject that their project is on, you can easily view the distribution of teams and mentors by subject via the home command.

To navigate to home:

  1. Type home into the command box, and press Enter to execute it.

  2. The result box will display the message “Showing homepage” in the result box. You can see the statistics and the ‘Home’ section of sidebar being highlighted. Below is the layout of the homepage:

HomeCommandExample
Figure 11. Output of home command

5.22. Command Suggestion Prompt

As you type, there will be a popup box predicting the type of commands you are going to type. You can navigate through these suggestions and choose the template that suits you.

  • Take note that the command suggestion for a command will not show if the command is fully entered by the user, excluding parameters.

Example:

Let us suppose that you want to type the command add mentor and you forgot the fields that are required in the command.

Instead of going through the user guide to look for the command, a popup box will appear as you type. The content in this box will change as you type, such that the commands suggested will start with the words or letters that you have already entered.

As you type:

  1. Type ‘add’ into the command box, and add participant, add mentor and add team commands will be suggested to you. The grey text are meant as guides and blue text are meant as usage instructions . These text will not appear when you choose the command of choice.

CommandSuggestionStep1
Figure 12. Step 1 of command suggestion box

  1. Press the up arrow or down arrow arrow keys to navigate up and down the popup box.

CommandSuggestionStep2
Figure 13. Step 2 of command suggestion box

  1. Press Enter to choose the command of your choice. The command will then appear on the user input box.

CommandSuggestionStep3
Figure 14. Step 3 of command suggestion box

  1. Press left arrow or right arrow keys to navigate the cursor and fill in the respective fields. Press Enter to execute the command.

CommandSuggestionStep4
Figure 15. Step 4 of command suggestion box

5.23. Seating: locate {PARTICIPANT/TEAM} (Coming in v2.0)

Find where a particular participant or team is seated.

Examples:

  • locate n/Brian will tell you where the participant Brian is seated.

  • locate n/GenericTeamName will tell you where the team GenericTeamName is seated.

5.24. Swag (Coming in v2.0)

5.24.1. Add Swag: add swag DESCRIPTION QUANTITY

Add swag to inventory Examples: add swag Android Plushie 5

5.24.2. Track inventory of available swags: list swag

List the currently available swag

5.25. Schedule (Coming in v2.0)

5.25.1. Add schedule: addSchedule TIME TEAM_ID MENTOR_ID

Add a schedule for a team

5.25.2. Update schedule: updateSchedule SCHEDULE_ID TIME TEAM_ID MENTOR_ID

Update a schedule for a team

5.25.3. Delete schedule: deleteSchedule SCHEDULE_ID

Delete a Schedule for a Team

5.26. Food (Coming in v2.0)

5.26.1. Add Food Company and Inventory: addFoodCompany COMPANY_NAME INVENTORY QUANTITY

Add a Food Company and it associated food item inventory

5.26.2. Mark Food as Received: receiveFood COMPANY_NAME INVENTORY QUANTITY

Mark the inventory as received

5.26.3. List Food Inventory: list food

List the food inventory and its current status (e.g. delivering, received)

5.27. Waitlist (Coming in v2.0)

5.27.1. Add to waitlist: addToWaitList PARTICIPANT_ID

Add a participant to a waitlist when the number of participants exceeds a stipulated capacity.

5.27.2. Remove from waitlist: removeFromWaitList PARTICIPANT_ID

Remove a participant from the waitlist.

5.27.3. List by Registration Time: listWaitList

Go through the waitlist and list the participants in the waitlist in ascending orger of registration time.

  • This helps fulfill a first-come-first-serve policy.

6. FAQ

Q: How do I transfer my data to another computer?
A: First, download alfred.jar in your other computer. Then, transfer the data folder at where alfred.jar is downloaded in your old computer over to your new computer. In your new computer, transfer the data folder over to where alfred.jar is downloaded.

7. Command Summary

Command Function Format Example

Add an Entity

Add an Entity for Alfred to keep track

add {mentor/participant/team} PARAMETERS

Participant: add participant n/NAME p/PHONE_NUMBER e/EMAIL_ADDRESS
Team: add team n/NAME s/SUBJECT pn/PROJECT_NAME l/TABLE_NUMBER
Mentor: add mentor n/NAME p/PHONE_NUMBER e/EMAIL_ADDRESS o/ORGANIZATION s/SUBJECT

Update an Entity

Edits an entity based on the supplied parameter values

edit {mentor/participant/team} ID [PARAMETERS]

Participant: edit participant P-1 n/NewParticipantName
Team: edit team T-1 n/NewTeamName pn/New Project Name
Mentor: edit participant P-1 n/NewMentorName

List all Entities

Shows a list of all the entities corresponding to the entity type

list {mentors/teams/participants}

Participant: list participants
Team: list teams
Mentor: list mentors

Deleting an Entity

Deletes an Entity, so that Alfred will no longer keep track of that Entity

delete {participant/mentor/team} ID

Participant: delete participant P-1
Team: delete team T-1
Mentor: delete mentor M-1

Finding an Entity

Searches for Entities by their name

find {mentor/team/participant} NAME

Participant: find participant n/John Doe
Team: find team n/FutureHackathonWinner
Mentor: find mentor n/Joshua Wong

List Undo/Redo-able Commands

Displays the Undo/Redo-able Commands in the "History" section of the GUI

history

history

Undo Previous Command

Undoes the previously executed command. Look at output of history to see which command can be re-done.

undo

undo

Redo Next Command

Redoes the next command. Look at output of history to see which command can be re-done.

redo

redo

List Team Rankings

Displays the ranking of the teams in the Hackathon in descending order of their points

leaderboard

Team: leaderboard

List Team Rankings with Tie Break

Displays the ranking of the teams in the Hackathon in descending order of their points with specified tiebreak methods used to break ties

leaderboard tb/METHOD_1 METHOD_2…​

Team: leaderboard tb/moreParticipants random

Get the top k teams

List the top k teams in the leaderboard, where k is a number (NUMBER) which you specify

getTop NUMBER

Team: getTop 5

Get the top k teams with Tie Break

List the top k teams in the leaderboard with specified tiebreak methods used to break ties, where k is a number (NUMBER) which you specify

getTop NUMBER tb/METHOD_1 METHOD_2…​

Team: getTop 5 tb/moreParticipants random

Add points to a Team

Adds the value of POINTS to the current score of the team with TEAM_ID

score add TEAM_ID POINTS

Team: score add T-1 20

Subtracts points from a Team

Deducts the value of POINTS from the current score of the team with TEAM_ID

score sub TEAM_ID NEW_POINTS

Team: score sub T-1 15

Sets points of a Team

Sets the score of the team with TEAM_ID to a new score NEW_POINT

score sub TEAM_ID NEW_POINTS

Team: score set T-1 15

Bulk Registration

Adds multiple participants at once into Alfred through the specification of a .csv file

import fp/CSV_FILE_PATH fp/[ERROR_FILE_PATH]

import fp/C:\User\Hackathon2019\participants.csv will import data from participants.csv into Alfred

Export Data

Exports all data in Alfred to an external CSV file

export [{mentor/participant/team}] fp/[CSV_FILE_PATH]

All: export fp/data/alfred.csv
Participant: export participant
Team: export team
Mentor: export mentor

Add a schedule for a Team (Coming in v2.0)

Adds a time slot where the Team of TEAM_ID meets with Mentor of MENTOR_ID

addSchedule TIME TEAM_ID MENTOR_ID

addSchedule 1/2/2019 1400 T-1 M-1 the specified Mentor will meet with Team on 1st February 2019 2pm

Update schedule of a Team (Coming in v2.0)

Updates the existing schedule of SCHEDULE_ID of a Team of TEAM_ID. New schedule will be added if the Team does not have an existing schedule of SCHEDULE_ID

updateSchedule SCHEDULE_ID TIME TEAM_ID MENTOR_ID

updateSchedule S01 1/2/2019 1400 T-1 M-1 Schedule S01 of T-1 will be updated to meet with Mentor M-1 at 1st February 2pm

Delete a schedule for a Team (Coming in v2.0)

Deletes a time slot where the of SCHEDULE_ID

deleteSchedule SCHEDULE_ID

deleteSchedule S-1

Add addFoodCompany and Inventory (Coming in v2.0)

Adds a Food with COMPANY_NAME, INVENTORY_QUANTITY and CATERING_TIME

addFoodCompany cn/COMPANY_NAME pax/INVENTORY QUANTITY t/CATERING_TIME

addFood cn/Neo’s Garden pax/100 t/1/2/2019 1400

Marked Food as received (Coming in v2.0)

Marks a Food with COMPANY_NAME and CATERING_TIME as received

receivedFood cn/COMPANY_NAME pax/INVENTORY_QUANTITY

receiveFood cn/Neo’s Garden pax/100

List all Food (Coming in v2.0)

Lists the inventory of Food

list food

list food

Add User to WaitList (Coming in v2.0)

Adds a prospective Participant by USER_ID to Waitlist

addToWaitList USER_ID

addToWaitList U-1

Remove a User from WaitList (Coming in v2.0)

Removes a prospective Participant by USER_ID from Waitlist

removeFromWaitList USER_ID

removeFromWaitList U-1

List all User in WaitList (Coming in v2.0)

Lists all prospective Participant in Waitlist

listWaitList

listWaitList