Expense Tracker - User Guide

By: Team T12-1 Since: Oct 2018 Licence: MIT

Table of Contents

1. Introduction
2. About
3. Quick Start
4. User Interface
5. Features
6. FAQ
7. Command Summary
8. Command Shorthands

1. Introduction

Expense Tracker is a desktop application that you can use to track your expenses. Expense Tracker provides you with features such as setting a budget and expense statistics, which help you stay within your budget.

2. About

The Expense Tracker User Guide contains all the essential information for you to make full use of Expense Tracker. Jump to Quick Start to get started or go to Features for a list of all the commands available.

3. Quick Start

Follow these steps to start using Expense Tracker:

Install Java (version 9 or later) on your computer by going here and downloading the Java SE Runtime Environment for your operating system.
Download the latest expensetracker.jar file from here
Copy the file to the folder which you want to use as the home folder for your Expense Tracker.
Double-click the expensetracker.jar file to start the app. The GUI will appear and look like this:

Figure 1. User interface on application launch
Type the command signup USERNAME in the command box (the box where it says "Enter command here…") and press Enter to execute it, where USERNAME is the username of your choice. E.g. signup username123
Type the command login u/USERNAME in the command box and press Enter to execute it, where USERNAME is the username you signed up with in the previous step. e.g. login u/username123
You are now able to use all the commands of the app.
Type commands in the command box, as highlighted in the figure below, and press Enter to execute it. Refer to Features for details on all the available commands.
e.g. typing help and pressing Enter will open the help window.

For Linux users, if the error expensetracker.jar is not marked as executable error appears, please follow the steps below:
1. Open Terminal, enter the command cd path/to/expensetracker.jar
2. Enter the command sudo chmod 666 expensetracker.jar

expensetracker.jar will now be executable.

4. User Interface

After logging in, the interface will display as such:

Figure 2. User interface

There are 6 main components to Expense Tracker, each highlighted by the coloured box in the diagram above.

4.1. Left Panel

This component is highlighted by the red box. There are two modes to this panel:

Expense List mode
Statistics Panel mode

You are able swap between Expense List mode and Statistics Panel mode by using the list command and stats command, respectively.

See list and stats commands for more details on these commands.

4.1.1. Expense List mode

In Expense List mode, the Left Panel displays the list of all expenses, as shown below:

Figure 3. Left Panel in Expense List mode

Commands that alter the Expense List, such as find and list, will change the expenses that are shown.

See find and list commands for more details.

Each expense has an index number next to the expense name. These are relevant to the delete and edit commands.

See delete and edit commands for more details.

4.1.2. Statistics Panel mode

In Statistics Panel mode, the Left Panel contains upper and lower sections, similar to what is shown below:

Figure 4. Left Panel in Statistics Panel mode

The upper section displays statistical information about expenses.

The type of statistics shown can be changed via the stats command.

See stats command for more details.

The lower section shows four of the category budgets that have been set using the setCategoryBudget command.

If there are no category budgets set, the lower section will be empty, save for the title.

See setCategoryBudget command for more details.

4.2. Budget Panel

This component is highlighted by the blue box.

The Budget Panel shows information about your total expenditure and the budget which you set using the setBudget command. See setBudget command for more details.

On slow computers, it is possible that the texts in the Budget Panel may not appear.

4.3. Notifications Panel

This is the portion highlighted by the green box.

The Notifications Panel is where any automated notifications will appear. These include warnings about your expenditure and saving tips that you should consider.

The Notification Panel will only display a maximum of 10 notifications. If the Notification Panel is full, the oldest notification will be replaced by the newest notification.

You can toggle notifications on and off with the notification command. See notification command for more details.

4.4. Command Box and Console

This component is highlighted by the yellow box.

The Command Box is where the "Enter command here…" is located. To enter a command in the Command Box, use your mouse and click anywhere within the box, then proceed to type a command.

The Console displays any success and error messages that is relevant to the most recent command entered.

This component is highlighted by the orange box.

The menu bar contains two submenus, "file" and "help".

Click on "file" to reveal a dropdown containing the option "exit". Clicking on "exit" will close the application. Entering the command exit into the Command Box achieves the same outcome.

Click on "help" to reveal a dropdown containing the option "help". Clicking on "help", or pressing the F1 key on your keyboard, will open a Help Window. Entering the command help into the Command Box achieves the same outcome.

4.6. Status Bar

This component is highlighted by the pink box.

On the leftmost side, the Status Bar displays the date and time of the last update to the Expense Tracker.

On the rightmost side, the Status Bar displays the directory or folder where the updated data was saved to.

5. Features

Take note of these instructions related to the format of the commands before using them:

Command Format

All commands begin with the command word. The command word may be followed by user-defined parameters.
According to the format of each command, words in UPPER_CASE are the parameters which can be specified by you.
- E.g. the login command has the format of login u/USERNAME where USERNAME is a parameter which can be replaced by a specified value. In order to log in to an account with the username "username123", enter the command login u/username123.
Parameters in square brackets are optional. This means that the parameter does not have to be included for the command to work.
- E.g if a command has a parameter format of n/EXPENSE_NAME [t/TAG], the parameters can be used as n/Birthday Present t/Girlfriend, which includes the "Girlfriend" tag, or as n/Birthday Present, which does not include a tag.
Parameters with … after them can be used multiple times.
- E.g. if a command format contains the parameter t/TAG…, the parameter can be replaced with t/friend or t/friend t/family
Parameters can be in any order e.g. if the command format specifies n/NAME c/CATEGORY, using the parameters c/CATEGORY n/NAME is also acceptable.

Before you are logged in, only login, signup and help commands are useable.
After you are logged in, the rest of the commands will become useable.

These are the commands available to use in Expense Tracker:

Creates a new user in Expense Tracker. You can log in to your newly created user after signing up.

Format: signup USERNAME

Examples:

signup username123
Signs up a user with the username "username123".

USERNAME must be 1 to 250 characters long
USERNAME cannot contain white spaces or any of the following characters : > < : \ / | ?

Logs in to Expense Tracker as an existing user and expands the user interface to show Expense Tracker if it is not already showing.

Format: login u/USERNAME [p/PASSWORD]

Examples:

login u/username123
Logs in a user with the username "username123".
login u/username1234 p/password1
Logs in a user with the username "username1234" with password "password1".

USERNAME is case insensitive
PASSWORD is case sensitive
PASSWORD cannot contain any spaces and must be 6 to 100 characters long
Expense Tracker contains a sample user with USERNAME sample
If a user has no password set, then the login will be successful regardless of whether a PASSWORD has been provided

5.3. Setting a password for the current user : `setPassword`

Sets a new password for the user which is currently logged in.

Format: setPassword n/NEW_PASSWORD [o/OLD_PASSWORD]

Examples:

setPassword n/pass123
Sets the current user’s password as "pass123", provided that there is no previously set password
setPassword n/pass123 o/password1
Sets the current user’s password as "pass123", provided that the current password is "password1"

OLD_PASSWORD is needed if a password has been previously set for the current user and they have to match.
OLD_PASSWORD and NEW_PASSWORD are case sensitive
OLD_PASSWORD and NEW_PASSWORD cannot contain any spaces and must be 6 to 100 characters long

5.4. Viewing help : `help`

Opens up a new window with the User Guide.

Format: help

5.5. Adding an expense: `add`

Adds an expense to Expense Tracker.

Format: add n/EXPENSE_NAME $/COST c/CATEGORY [d/DATE] [t/TAG]…

Examples:

add n/Lunch $/4.00 c/Food
Adds an expense with its name as "Lunch", cost as "4.00", category as "Food" and date as the current day.
add n/Stationery $/1.80 c/School t/bookhaven
Adds an expense with its name as "Stationery", cost as "1.80", category as "School", Tag as "bookhaven" and date as the current day.
add n/Project $/2.08 c/School d/01-01-2018
Adds an expense with its name as "Project", cost as "2.08", category as "School" and date as "01-01-2018".

COST should be a non-zero positive number with two decimal places
If the DATE parameter is not provided, the date of the expense will default to the current day.
DATE should be in the format of "dd-mm-yyyy".
DATE can be a date in the future

5.6. Editing an expense : `edit`

Edits the expense at the specified INDEX. The INDEX refers to the index number shown in the displayed Expense List next to the name of the expense in the Expense List. Existing values of the expense will be edited according to the value of the parameters

Format: edit INDEX [n/EXPENSE_NAME] [$/COST] [c/CATEGORY] [d/DATE] [t/TAG…]

Examples:

edit 1 n/Stationery $/1.80 c/School
Edits the name and category of the first expense in the Expense List to be "Stationery" and "school" respectively.
edit 2 d/01-10-2018
Edits the date of the second expense in the Expense List to be the 1st of October, 2018.

At least one of the optional fields must be provided.
The index must be a non-zero positive integer and must correspond to an expense in the Expense List.
COST should be a non-zero positive number with two decimal places
DATE should be in the format of "dd-mm-yyyy".
DATE can be a date in the future

5.7. Editing multiple expenses : `massedit`

Edits the all expenses which match the keywords specified. Existing values of the expense will be edited according to the value of the parameters

Format: massedit [n/EXPENSE_NAME] [$/COST] [c/CATEGORY] [d/DATE] [t/TAG…] -> [n/EXPENSE_NAME] [$/COST] [c/CATEGORY] [d/DATE] [t/TAG…]

Examples:

massedit c/school -> c/food
Edits all the expenses in the "school" category to have their categories changed to "food".
massedit n/School fee d/01-10-2018:03-10-2018 -> t/books
Edits all the expenses which have names containing "School", with dates between "01-10-2018" and "03-10-2018", to have their tags changed to "book".
massedit $/1.00:2.00 -> c/waste n/saving
Edits all the expenses which have costs between "1.00" and "2.00" to have their categories changed to "waste" and names changed to "saving".
massedit c/shopping $/100.00 -> n/waste $/200.00
Edits all the expenses in the "shopping" category, which have a cost of "100.00", to have their names changed to "waste" and costs changed to "200.00".

At least one keyword before -> and one keyword after -> must be provided.
The order of the keywords does not matter.
Keywords are case insensitive, i.e. the KEYWORD have is equivalent to the KEYWORD Have
COST should be a non-zero positive number with two decimal places
DATE should be in the format of "dd-mm-yyyy".
DATE can be a date in the future
Only Tag keywords can have multiple keywords. Name,Category,Cost,Date can only have one keyword, i.e. find t/lunch t/family is permitted but find n/school n/book is not permitted.

5.8. Deleting a expense : `delete`

Deletes the expense at the specified INDEX. The INDEX refers to the index number shown in the displayed Expense List next to the name of the expense.

Format: delete INDEX

Examples:

delete 1
Deletes the first expense in the Expense List from Expense Tracker.

The index must be a non-zero positive integer and must correspond to an expense in the Expense List.

5.9. Locating expenses by keywords: `find`

Finds expense which contains all the given keywords.

Format: find [n/NAME] [c/CATEGORY] [$/COST:COST] [d/DATE:DATE] [t/TAG…]

Examples:

find c/School
Find all the expenses under the School category.
find d/1-10-2018:7-10-2018
Find all the expenses which have dates between 1-10-2018 and 7-10-2018(inclusive).
find d/1-10-2018
Find all the expenses with dates on 1-10-2018
find $/10.00:20.00
Find all the expenses with costs between 10 and 20(inclusive).
find $/10.00
Find all the expenses with costs of 10.00.
find c/School t/lunch d/1-10-2018
Find all the expenses under the "School" category, with "lunch" tags and dates on 1-10-2018.

At least one keyword should be provided
Keywords are case insensitive, i.e. the KEYWORD have is equivalent to the KEYWORD Have
The order of the keywords does not matter, i.e. the KEYWORD Have lunch is equivalent to the KEYWORD lunch have
Partial words will be matched, i.e. using the KEYWORD Hav for expense name will give an expense with the name Have
Only Tag keywords can have multiple keywords. Name,Category,Cost,Date can only have one keyword, i.e. find t/lunch t/family is permitted but find n/school n/book is not permitted.

5.10. Listing all expenses : `list`

Updates the Expense List to show all expenses in Expense Tracker.

This command can be used after the find command is used, to display all the expenses in Expense Tracker, as the find command will filter out certain expenses.

Format: list

5.11. Setting a total budget: `setBudget`

Sets a total budget. Available spending is defined as the total amount of expenses you can add before you exceed your budget. The Expense Tracker will warn you when adding an expense results in your available spending exceeding the total budget that is set to prevent yourself from overspending. The warning is shown below.

Figure 5. Warning that is shown when a user adds an expense which results in the user exceeding the budget.

Format: setBudget MONEY_WITH_TWO_DECIMAL_PLACES

Examples:

setBudget 2.00
Sets a total budget of $2.00.
setBudget 20.00
Sets a total budget of $20.00.

The setBudget command is case sensitive.
MONEY_WITH_TWO_DECIMAL_PLACES must be a positive number with two decimal places.

5.12. Setting a recurrence frequency for total budget: `setRecurrenceFrequency`

Sets the recurrence frequency for resetting the available spending of the total budget of Expense Tracker.

If you draw a salary/have an allowance, this would allow you to track the portion of money you have spent against your salary/allowance of the week/month. This ensures that you do not overspend on a certain day, causing you to not have enough money until you draw your next salary/allowance.

A diagram of a use case and its detailed explanation is given below:

Figure 6. Diagram showing the operation of the setRecurrenceFrequency feature

You type in the command setRecurrenceFrequency hrs/24 as you want your available spending to reset every day when you receive your allowance.
You close the application.
You reopen the application on the next day to record another expense.
Your available spending will now be reset as it is past the set frequency of one day. A notification will be shown to inform you that this is done.

Format: setRecurrenceFrequency [hrs/HOURS] [min/MINUTES] [sec/SECONDS]

Examples:

setRecurrenceFrequency hrs/1
Sets the available spending of your total budget to reset every 1 hour
setRecurrenceFrequency hrs/1 min/30
Sets the available spending of your total budget to reset every 1 hour and 30 minutes

The setRecurrenceFrequency command is case sensitive.
HOURS/MINUTES/SECONDS must be a positive number.
This feature does not reset all of your expenses. It just resets your available spending. Thus, it is possible that you have 10 expenses of $200.00 with a budget of $10, and yet you are not over your budget.

5.13. Setting a Category Budget: `setCategoryBudget`

Sets a Budget to limit expenses on a certain category. If adding an expense causes the available spending of that category to exceeds Category budget, a warning will be displayed.

Format: setCategoryBudget c/CATEGORY b/BUDGET

Example:

setCategoryBudget c/School b/10.00
Sets a budget of $10 for the School category.

The setCategoryBudget command is case sensitive
CATEOGRY can only consist of one keyword and BUDGET must be a positive number with two decimal places.
The sum of all Category budgets cannot exceed the total budget of Expense Tracker. This is because Category budgets are used to segment your total budget, not as a replacement.

5.14. Listing entered commands : `history`

Lists all the commands that you have previously entered in reverse chronological order.

Format: history

Press the ↑ and ↓ arrows to display the previous and next commands respectively in the command box.

5.15. Undoing previous command : `undo`

Restores Expense Tracker to the state before the previous undoable command was executed.
Undoable commands are commands that change expenses in Expense Tracker (add, delete, edit and clear).

Format: undo

Examples:

delete 1
list
undo
Reverses the delete 1 command.
list
undo
The undo command fails as there are no undoable commands executed previously.
delete 1
clear
undo
undo
The first undo reverses the clear command. The second undo reverses the delete 1 command.

5.16. Redoing the previously undone command : `redo`

Restores Expense Tracker to the state before the most recent undo command.

Format: redo

Examples:

delete 1
undo
redo
The undo command reverses the delete 1 command.
The redo command reverses the undo command.
delete 1
redo
The redo command fails as there was no undo command executed previously.
delete 1
clear
undo undo redo (reapplies the delete 1 command)
redo (reapplies the clear command)
The first undo reverses the clear command.
The second undo reverses the delete 1 command.
The first redo reverses the second undo command, reapplying delete 1. The second`redo` reverses the first undo command, reapplying clear.

5.17. Showing expense statistics: `stats`

Changes the Expense List to show the Statistics Panel if the Expense List is currently showing, then displays a graph of your expenditure over a specified time period, in a given MODE.

You can use this command to analyse your expenses, observe your spending patterns and to identify categories which take up most of your budget.

There are two available modes: Time and Category, which can be indicated by t or c respectively in the MODE parameter.

Choosing Time mode will show a bar chart, similar to the one below, in the statistics panel, where amounts for each day or month will displayed, depending on the specified PERIOD_AMOUNT and PERIOD, starting from the current day or month.

Figure 7. Statistics Panel showing a bar chart in Time mode

Choosing Category mode will show a pie chart, similar to the one below, in the statistics panel, where amounts for each category will displayed for expenses in the specified PERIOD_AMOUNT and PERIOD.

Figure 8. Statistics Panel showing a pie chart in Category mode

The available options for PERIOD are d and m, which represents day and month respectively. E.g. if PERIOD_AMOUNT is 7 and MODE is d, the statistics will include data from the past 7 days.

Format: stats n/PERIOD_AMOUNT p/PERIOD m/MODE

Examples:

stats n/14 p/d m/t
Shows the expense statistics for the past 14 days as a bar chart showing expenses for each day
stats n/3 p/m m/t
Shows the expense statistics for the past 3 months as a bar chart showing expenses for each month
stats n/7 p/d m/c
Shows the expense statistics for the past 7 days as a pie chart showing expenses for each category
stats n/3 p/m m/c
Shows the expense statistics for the past 3 months as a pie chart showing expenses for each category

PERIOD_AMOUNT must be a positive integer
PERIOD can only be d or m, for day and month respectively
MODE can only be t or c, for time and category respectively
Leaving all parameters blank, i.e. typing the command stats, defaults in showing expenses for the past 7 days in Time mode.

5.18. Toggling Notifications: `notification`

Toggles the ability of Expense Tracker to generate and display automated notifications.

There are 2 types of notification to toggle:

Warning - Referenced by warning as the NOTIFICATION_TYPE parameter. These notifications will be sent when you are over or about to go over your budget.
Tip - Referenced by typing tip as the NOTIFICATION_TYPE parameter. These notifications are saving tips that will be sent once every 24 hours when you log onto an account.

As shown below, Warning-type Notifications can be indicated by exclamation mark image displayed along with the notification:

Figure 9. Example of a Warning-type Notification

Meanwhile, Tip-type Notifications can be indicated by light bulb image displayed along with the notification:

Figure 10. Example of a Tip-type Notification

There are two toggle options, on and off, which can be indicated by 'on' or 'off' respectively in the TOGGLE_OPTION parameter.

TOGGLE_OPTION is a required parameter. NOTIFICATION_TYPE can be omitted.

Format: notification n/NOTIFICATION_TYPE t/TOGGLE_OPTION

Examples:

notification n/warning t/off
Disables the sending Warning type notifications.
notification n/tip t/off
Enables the sending of Tip type notifications.
notification t/off
Disables the sending of both types of notifications.

NOTIFICATION_TYPE can only be 'warning' or 'tip'
TOGGLE_OPTION can only be 'on' or 'off'
NOTIFICATION_TYPE is optional

5.19. Clearing all entries : `clear`

Deletes all expense entries from Expense Tracker.

Format: clear

5.20. Exiting the program : `exit`

Exits the program.

Format: exit

5.21. Encrypting text using your password : `encrypt`

This command is for advanced users only and should be used with caution.

Encrypts text using your account’s password. You may want to use this feature if you wish to edit your expenses in the data file directly.

Format: encrypt TEXT

Examples:

encrypt secret thing
Displays the encrypted version of the text secret thing to be used with your account.
encrypt secret_thing
Displays the encrypted version of the text secret_thing to be used with your account.

Any leading and trailing spaces in TEXT are ignored

5.22. Decrypting text using your password : `decrypt`

This command is for advanced users only and should be used with caution.

Decrypts an encrypted text that has been encrypted using your account’s password. You may want to use this feature if you wish to edit your expenses in the data file directly.

Format: decrypt TEXT

Examples:

decrypt sadoasiondoofdnig
Displays the decrypted version of the string sadoasiondoofdnig.
encrypt dsfresf==asdas
Displays the encrypted version of the string dsfresf==asdas.

Any leading and trailing spaces are ignored
Only text that has been encrypted using your account’s password can be decrypted by you

6. FAQ

Q: Do I need to manually save my data?
A: There is no need to save your manually. All the data in Expense Tracker is automatically saved in the hard disk after any command that changes the data.

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and copy the data folder in your previous Expense Tracker folder over to the new Expense Tracker folder on your other Computer. If you wish to copy only one user over, create a folder named data in the app directory on the other computer and copy the xml file with your username in the data folder of the old computer into the data folder of the new computer.

Q: How is my expense data kept safe when I use this application?
A: All user expense-specific data is encrypted. The program ensures that no one will be able to decrypt encrypted information without your actual plain text password, which is not stored anywhere. So rest assured that no one can access your data without your password.

Q: How do I manually encrypt text to edit my user XML file as a technologically-savvy user?
A: You can make use of the encrypt and decrypt commands that have been described in the previous section.

7. Command Summary

This is a summary of the commands available in Expense Tracker:

Sign up : signup USERNAME
e.g. signup username123
Login : login u/USERNAME [p/PASSWORD]
e.g. login u/username123 p/password1
Set Password : setPassword n/NEW_PASSWORD [o/OLD_PASSWORD]
e.g. setPassword n/pass1 o/passold
Help : help
Add add n/EXPENSE_NAME $/COST c/CATEGORY [d/DATE] [t/TAG]…
e.g. add n/Lunch e/4 c/Food
Edit : edit INDEX [n/EXPENSE_NAME] [$/COST] [c/CATEGORY] [d/DATE] [t/TAG…]
e.g. edit 2 n/Lunch e/4 c/Food
Mass Edit : massedit [n/EXPENSE_NAME] [$/COST] [c/CATEGORY] [d/DATE] [t/TAG…] → [n/EXPENSE_NAME] [$/COST] [c/CATEGORY] [d/DATE] [t/TAG…]
e.g. `massedit c/school -> c/food
Delete : delete INDEX
e.g. delete 3
Find : find [n/NAME] [c/CATEGORY] [$/COST:COST] [t/TAG] [d/DATE:DATE]
e.g. find c/School
List : list
Set budget for Expense Tracker : setBudget
e.g. setBudget 20.00
Set recurring frequency for the budget: setRecurrenceFrequency [hrs/HOURS] [min/MINUTES] [sec/SECONDS]
Set category budgets : setCategoryBudget c/CATEGORY b/BUDGET
History : history
Undo : undo
Redo : redo
Statistics : stats n/NUMBER_OF_DAYS_OR_MONTHS m/MODE
e.g. stats n/7 m/d
Toggle Notifications : notification n/NOTIFICATION_TYPE t/TOGGLE_OPTION
e.g. notification n/tip t/off
Clear : clear
Exit : exit
Encrypt : encrypt TEXT
Decrypt : decrypt TEXT

8. Command Shorthands

Commands also come with command shorthands which can be used in place of the command word. I.e. using h has the same outcome as help This is a list of commands and their command shorthands in Expense Tracker:

signup: su
login: li
setPassword: sp
help: h
add: a
edit: e
delete: d
find: f
list: l
setBudget: sb
setRecurringFrequency: srf
setCategoryBudget: scb
history: h
undo: u
redo: r
stats: su
notification: n
clear: c
exit: x