StockPal

StockPal’s User Guide

Introduction

StockPal is a command line interface (CLI) application designed to help small E-commerce business owners who are just starting up to manage their stock-taking effectively. Users would mostly interact with StockPal via text commands.

StockPal is compatible for usage on Windows, Mac and Linux systems.

Not sure where to begin? Start by learning how to utilize this user guide.

Table of Contents

• Introduction
• Using This Guide
• Quick Start
  • Downloading StockPal
  • Running StockPal
• Glossary
• Features
  • Notes about the Command Format
  • Viewing help: help
  • Adding a new product: new
  • Listing all products: list
  • Editing product details: edit
  • Increasing quantity of existing product: inflow
  • Decreasing quantity of existing product: outflow
  • Viewing past inflow/outflow of existing product: history
  • Deleting a product and its details: delete
  • Find a keyword in the Product list: find
  • Exiting the program: exit
  • Saving the data
  • Editing the data file
• Command Summary
• FAQ

Using This Guide

Below are the symbols used in this guide and the meaning of these symbols.

Symbol	Meaning
	The exclamation mark symbol indicates actions that you should be cautious about.
	The i symbol indicates notes that are important for you when using the application.
	The lightbulb symbol indicates tips that hold useful information or advice that might be helpful for you.

Quick Start

Downloading StockPal

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

2. Download the latest StockPal.jar from here.

3. Copy the file to the folder you want to use as the home folder for the application. For example,C:\Users\setupuser\Documents\StockPal\StockPal.jar.

Running StockPal

1. For Windows users:

   Open a command prompt terminal. You can do so by searching for command prompt in the Windows search bar.
   

   
   
   

   For MAC users:

   Open a terminal. You can do so by searching for the terminal using the Spotlight icon in the menu bar. Click on the terminal.
   

   
   
   

2. Determine the file path to the home folder of StockPal.jar. You can do so by navigating to StockPal.jar in File Explorer (Windows) or Finder (MAC). For example, the image below shows that the file path to the home folder of StockPal.jar is C:\Users\setupuser\Documents\StockPal.
   

   
   
   

3. In the command prompt terminal, navigate to the home folder using the command cd <file path to the home folder>. For example, cd C:\Users\setupuser\Documents\StockPal.
   

   
   
   

4. In the command prompt terminal, run StockPal using the command java -jar StockPal.jar.

   
   
   

Glossary

The following is a collection of frequently used terms in the User Guide and their meanings.

PID (Product ID) - a unique number assigned to each product for identification purposes.

CLI (Command Line Interface) - a text-based interface used to interact with our program by entering commands into a terminal.

CSV (Comma-Separated Values) - a file format used to store tabular data. Each line represents a row of data, and each field within a row is usually separated by a comma.

JSON (JavaScript Object Notation) - a file format for storing and transporting data.

Features

Notes about the command format:

• Words in UPPER_CASE are the parameters to be supplied by the user.
  e.g. in new n/PRODUCT_NAME q/INITIAL_QUANTITY, PRODUCT_NAME and INITIAL_QUANTITY are parameters which can be used as new n/Math Textbook q/100.
• Items in square brackets are optional.
  e.g. n/PRODUCT_NAME q/INITIAL_QUANTITY [p/PRICE] can be used as n/Math Textbook q/100 p/20.00 or as n/Math Textbook q/100.
• Parameters must be in the specified order.
  e.g. if the command specifies n/PRODUCT_NAME q/INITIAL_QUANTITY, q/INITIAL_QUANTITY n/PRODUCT_NAME is not acceptable.
• Commands and flags are not case-sensitive.
  e.g. Both commands LIST -SN and List -sn will present the same output.

Viewing Help: help

Provides command details for all or specific commands.

When to Use?

This is a useful command to start with if you are new to StockPal!

Format: help [COMMAND]

Parameter	Representation	Constraints
COMMAND	The command for which you wish to display the help page	- Must be a valid command keyword. - If COMMAND is left empty, command details for all commands will be displayed. - List of valid command keywords: help, new, list, edit, delete, inflow, outflow, history, find, exit

Note: COMMAND is case-insensitive.
e.g. help will be considered the same as HELP and hELP.

Example 1

Input:

help inflow 

Output:

====================================================================================
Command: inflow

Description: Increases the quantity of a product from the existing amount.

Usage: inflow PID a/INCREMENT_AMOUNT

Options:
PID                   Product ID of product
INCREMENT_AMOUNT      Quantity of product to add
====================================================================================

Adding a New Product: new

Creates a new product to the inventory and assigns a unique Product ID (PID) to it.

When to Use?

• When starting as a new user of StockPal, use this command repeatedly to fill up your inventory to start tracking!
• Subsequently, when your business introduces new products, use this command to add them in too!

Format:

new n/PRODUCT_NAME q/INITIAL_QUANTITY [p/PRICE] [d/DESCRIPTION]

Parameter	Representation	Constraints
PRODUCT_NAME	Name of new product to be added.	- Limited to 50 characters. - Allowed characters: a-z, A-Z, 0-9,  , (), [], ,, ., -, _ - Name must be unique, i.e. no existing product with the same product name.
INITIAL_QUANTITY	Quantity of the new product to be added.	Must be an integer more than or equal to 0 and smaller or equal to INT_MAX (2147483647).
PRICE	Price of the new product to be added.	- Must be a numeric value more than equal to 0. - Can have at most 2 decimal places.
DESCRIPTION	Description of the new product to be added.	- Limited to 100 characters. - Allowed characters: a-z, A-Z, 0-9,  , (), [], ,, ., -, _

Note:

1. PRODUCT_NAME is case-insensitive, which means a name in lowercase will be considered as having the same name as the name in uppercase.
   e.g. Pen will be considered the same as pen and PEN.
2. When entering 0, 0.0 or 0.00 for PRICE, StockPal will deem it as not having PRICE entered, and display [X] for PRICE when using list command.

Example 1

Input:

new n/Pen q/40 

Output:

Product has been added.

Explanation:

This command adds your product to the inventory. The product’s details are as follows:

• Name of the product is Pen.
• Quantity of Pen is 40 units.

Example 2

Input:

new n/Ruler q/30 p/2.00 d/Curve Ruler

Output:

Product has been added.

Explanation:

This command adds your product to the inventory. The product’s details are as follows:

• Name of the product is Ruler.
• Quantity of Ruler is 30 units.
• Price of each unit is $2.00.
• Description of the Ruler product is Curve Ruler, which is the type of ruler.

Listing All Products: list

Lists all products in inventory.

Format: list [-sn|-sq]

Sorting:

• By default, products are sorted according to their PID.
• To sort according to their names, use the -sn field.
• To sort according to their quantity, use the -sq field.

Tip: Some of the commands may require PID as a compulsory field. Use list to obtain the required PID of the particular product you want to access.

Example 1

Context:

• View a list sorted by product PID.

Input: list

Output:

====================================================================================
1. PID: 1  |  Name: Pen  |  Quantity: 40  |  Price: [X]
Description: [X]
====================================================================================
2. PID: 2  |  Name: Ruler  |  Quantity: 30  |  Price: $2.00
Description: Curve Ruler
====================================================================================

Example 2

Context:

• Sort a list according to the quantity of the products.

Input: list -sq

Output:

====================================================================================
1. PID: 2  |  Name: Ruler  |  Quantity: 30  |  Price: $2.00
Description: Curve Ruler
====================================================================================
2. PID: 1  |  Name: Pen |  Quantity: 40  |  Price: [X]
Description: [X]
====================================================================================

Editing Product Details: edit

Edits details of an existing product in the inventory.

Format:

edit PID [n/PRODUCT_NAME] [q/QUANTITY] [p/PRICE] [d/DESCRIPTION]

Note: At least one parameter must be provided.

Parameter	Representation	Constraints
PID	Product ID of the existing product.	Must be a valid Product ID of an existing product.
PRODUCT_NAME	New product name of the product to be edited.	- Limited to 50 characters. - Allowed characters: a-z, A-Z, 0-9,  , (), [], ,, ., -, _ - Name must be unique, i.e. no existing product with the same product name.
QUANTITY	New quantity of the product to be edited.	Must be an integer more than or equal to 0, and smaller or equal to INT_MAX (2147483647).
PRICE	New price of the product to be edited.	- Must be a numeric value more than equal to 0. - Can have at most 2 decimal places.
DESCRIPTION	New description of the product to be edited.	- Limited to 100 characters. - Allowed characters: a-z, A-Z, 0-9,  , (), [], ,, ., -, _

Note:

1. PRODUCT_NAME is case-insensitive, which means a name in lowercase will be considered as having the same name as the name in uppercase.
   e.g. Pen will be considered the same as pen and PEN.
2. When entering 0, 0.0 or 0.00 for PRICE, StockPal will deem it as not having PRICE entered, and display [X] for PRICE when using list command.

Tip: If you are looking to increase or decrease the amount of stock of a particular product, use inflow or outflow instead. It is strongly not recommended to use edit for incoming or outgoing stocks. Unlike inflow and outflow, the change in product quantity using the edit feature will not be tracked and hence will not appear under history.

Example 1

Context:

• Product Pen’s Product ID (PID) is 1.
• You wish to update Pen’s information as follows.
  • PRICE: $1.50
  • DESCRIPTION: Sarasa Blue Pen

Input:

edit 1 p/1.50 d/Sarasa Blue Pen

Output:

Product details have been updated.

Example 2

Context

• Ruler’s Product ID (PID) is 2.
• You wish to update Ruler’s information as follows.
  • PRODUCT_NAME: Curve Ruler
  • QUANTITY: 35
  • PRICE: $2.50
  • DESCRIPTION: Math Curve Ruler

Input:

edit 2 n/Curve Ruler q/35 p/2.50 d/Math Curve Ruler

Output:

Product details have been updated.

Increasing a Product Quantity: inflow

Increase the quantity of an existing product in the inventory at the specific PID by a specified amount.

Format:

inflow PID a/QUANTITY

Parameter	Representation	Constraints
PID	Product ID of the existing product.	Must be a valid Product ID of an existing product.
QUANTITY	Quantity of the product to be added.	Must be an integer more than 0 and smaller or equal to INT_MAX (2147483647).

Tip: Use this command instead of edit if you already have an existing product and just want to increase the quantity when you have new stocks.

Example 1

Context:

• Product Pen’s Product ID (PID) is 1.
• Current QUANTITY of Pen is 40.
• Now, you have 20 new incoming stocks for Pen and you wish to update the quantity.

Input:

inflow 1 a/20

Output:

Quantity updated. Quantity: 60

Example 2

Context:

• Product Curve Ruler’s Product ID (PID) is 2.
• Current QUANTITY of Curve Ruler is 35.
• Now, you have 10 new incoming stocks for Curve Ruler and you wish to update the quantity.

Input:

inflow 2 a/10

Output:

Quantity updated. Quantity: 45

Explanation: The inflow command will update the quantity of the product by performing addition of the current quantity and the inflow quantity.

Decreasing a Product Quantity: outflow

Decrease the quantity of an existing product in the inventory at the specific PID.

Format:

outflow PID a/QUANTITY

Parameter	Representation	Constraints
PID	Product ID of the existing product.	Must be a valid Product ID of an existing product.
QUANTITY	Quantity of the product to be removed.	Must be an integer more than 0 and smaller or equal to INT_MAX (2147483647).

Tip: Use this command instead of edit if you already have an existing product and just want to decrease the quantity when you sell your stocks.

Example 1

Context:

• Product Curve Ruler’s Product ID (PID) is 2.
• Current QUANTITY of Curve Ruler is 45.
• Now, you sold 30 Curve Ruler and you wish to update the quantity.

Input:

outflow 2 a/30

Output:

Warning! This product is low in quality.
Quantity updated. Quantity: 15

Tip: Note that the warning will only appear once when the quantity first falls below quantity of 20. All low quantity products will be displayed when you exit the program.

Tip: Do note that if you added a new product with a quantity lower than the threshold quantity, warning will also be raised.

Example 2

Context:

• Product Pen’s Product ID (PID) is 1.
• Current QUANTITY of Pen is 60.
• Now, you sold 35 Pen and you wish to update the quantity.

Input:

outflow 1 a/35

Output:

Quantity updated. Quantity: 25

Tip: Since the new quantity does not fall below 20, no warning is given.

Explanation: The outflow command will update the quantity of the product by performing subtraction of the outflow quantity from the current quantity.

Viewing Past Inflow / Outflow of Existing Product: history

When to Use?

When you want to check on the previous inflow or outflow of a product, use this command!

Format:

history PID

Parameter	Representation	Constraints
PID	Product ID of the existing product.	Must be a valid Product ID of an existing product.

Example 1

Input:

history 1

Output:

1. PID: 1  |  Change in quantity: 20  |  Date of inflow: 29-03-2024 17:27:24
2. PID: 1  |  Change in quantity: -35  |  Date of outflow: 05-04-2024 17:33:40

Explanation:
This command will find any inflow or outflow quantities of your product which has PID 1, which is your Pen product.
As seen, you tried to:

• Increase the quantity of Pen by 20 on 29th March 2024, at 17:27:24 hours
• Decrease the quantity of Pen by 35 on 5th April 2024, at 17:33:40 hours

Example 2

Input:

history 2

Output:

1. PID: 2  |  Change in quantity: 10  |  Date of inflow: 18-03-2024 08:00:31
2. PID: 2  |  Change in quantity: -30  |  Date of outflow: 01-04-2024 10:00:00

Explanation:
This command will find any inflow or outflow quantities of your Curve Ruler which has PID 2.
As seen, you tried to:

• Increase the quantity of Curve Ruler by 10 on 18th March 2024, at 08:00:31 hours
• Decrease the quantity of Curve Ruler by 30 on 1st April 2024, at 10:00:00 hours

Deleting a Product and its Details: delete

Deletes an existing product from the inventory.

Format: delete PID

Parameter	Representation	Constraints
PID	Product ID of the existing product.	Must be a valid Product ID of an existing product.

Example 1

Input:

delete 1

Output:

Product has been deleted.

Example 2

Suppose the product with PID 3 is not in the inventory. As such you should not be able to delete anything.

Input: delete 3

Output: Product with the following PID is not found: 3

Find a Keyword in the Product List: find

When to use?

This is a useful command for when you want to know if there is already an existing product that matches your keyword. Or when you just want to get the product’s PID in a long list of products.

Format: find KEYWORD

Note:

• Only the product name is searched.
• The search is case-insensitive. e.g “find apple” will match “Apple”.
• Partial or full words will be matched e.g. “find Pe” will match “Pen”.

Example 1

Input:

find Ruler

Output:

====================================================================================
1. PID: 2  |  Name: Curve Ruler  |  Quantity: 15  |  Price: $2.50
Description: Math Curve Ruler
====================================================================================

Explanation:
This command will find any product name that contains Ruler in the product’s name, regardless of case sensitivity.

Example 2

Input:

find THISISASUPERLONGSTRINGANDTHEREISNOMATCH

Output:

No matches found.

Explanation:
This command will find any product name that contains THISISASUPERLONGSTRINGANDTHEREISNOMATCH in the product’s name, regardless of case sensitivity. There is however no match in any of the product’s names in the product list.

Exiting the program: exit

Exits the program.

Format:

exit

Example 1

Input:

exit

Output:

These products have low quantity! Please top up!
====================================================================================
PID: 2  |  Name: Curve Ruler  |  Quantity: 15 
====================================================================================
Exiting program, goodbye!

Explanation: This command will exit the program and print out all the products that are low in quantity. Our program will print a statement to bid you goodbye!

Example 2

Input:

exit wrong usage

Output:

Exit Command does not take in any extra arguments!

Explanation: In example 2, the literal string input:exit wrong usage was entered by the user.

To address possible typo issues caused by typing “exit” when you want to type “edit”, ensure that no arguments should be passed to the Exit command.

Saving the Data

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

Editing the Data File

StockPal inventory data is saved automatically as a CSV file [JAR file location]/data/inventory.csv, while the past transactions data is saved automatically as a JSON file [JAR file location]/data/transactions.json. Advanced users are welcome to update data directly by editing these data files, even though it is highly not recommended.

Note: Allowed characters to use when editing the data file:
a-z, A-Z, 0-9,  , (), [], ,, ., -, _

Caution: If your changes to the data file makes its format invalid, StockPal will not discard the data, but instead display an error that the data has erroneous input, and close the app thereafter.
Furthermore, certain edits can cause StockPal to behave in unexpected ways (e.g., if a value entered is outside the acceptable range). For example,

• When editing the data file, you should NOT be editing the PID or the name of the products directly, as it will most likely cause errors in the application itself, and StockPal will show errors if there are duplicate PIDs or names.
• If you want to do an inflow or outflow, do not do it by editing the data file itself, as these edits will not be recorded in the transactions list of StockPal.
• Do be careful when using the semicolon character (;) when editing inventory.csv, as that is the main separator of the CSV file, adding or removing them will likely cause data to be lost.

Therefore, edit the data file only if you are confident that you can update it correctly, as we would not be responsible for any errors caused by the manual editing of the data file, and it is recommended to make a backup of the file before editing it.

Command Summary

This section provides a quick overview of all the commands. For more detailed information on the command format, click on the command to be redirected to the command’s details under the Features section.

Command	Description
help [COMMAND]	Provides command details for all or specific commands
new n/PRODUCT_NAME q/INITIAL_QUANTITY [p/PRICE] [d/DESCRIPTION]	Creates a new product
list [-sn|-sq]	Lists all products in the inventory
edit PID [n/PRODUCT_NAME] [q/QUANTITY] [d/DESCRIPTION] [p/PRICE]	Edits an existing product’s field
inflow PID a/QUANTITY	Increases the quantity of an existing product in the inventory at the specific PID
outflow PID a/QUANTITY	Decreases the quantity of an existing product in the inventory at the specific PID
history PID	Finds the list of transactions for a particular product based on its PID
delete PID	Deletes a product
find KEYWORD	Finds the list of products that contains the keyword in their name
exit	Exits the program

FAQ

Q: How do I transfer my data to another computer?

A: There are 2 ways to transfer your StockPal data over to another device.
Method 1:

1. Install StockPal on your new device.
2. On your old device, locate inventory.csv and transactions.json in StockPal’s home folder. Copy over the 2 files to the home folder of StockPal on your new device.
3. On your new device, run StockPal.jar (located within the home folder of StockPal).

Method 2:

1. On your old device, locate StockPal’s home folder.
2. Copy the entire folder over to your new device.
3. On your new device, run StockPal.jar (located in the copied folder from Step 2).