User Guide

Welcome to AdmiNUS!
Thank you for choosing AdmiNUS as your go-to contact management tool. Designed specifically for NUS Club Administrators. AdmiNUS aims to make your contact management experience easy and efficient. Whether you prefer the speed of typing commands or the clarity of a user-friendly GUI, AdmiNUS has you covered.

Why Choose AdmiNUS?

AdmiNUS streamlines contact management by combining the speed of CLI commands with an intuitive GUI. It is especially useful for NUS Club Administrator who need to manage contacts efficiently for events, vendors, and participants.

What AdmiNUS Offers:

• Add, edit, delete, and search student and company contacts easily.

• Track contacts by categories (e.g., students, companies) and tags.

• Seamlessly switch between CLI and GUI for versatile interaction.

• Import and export contact data via CSV files to facilitate data sharing.

The application is designed to optimize workflows for users managing events, coordinating groups, and ensuring smooth communication.

Example Use Case

Suppose you are organising an NUS event with over 200 participants, including student volunteers and vendors. With AdmiNUS, adding, editing, and filtering contacts is quick and straightforward. For example, to add a student:

student n/John Doe id/A0123456X p/98765432 e/johnd@example.com a/123 Clementi Rd, #02-01 t/volunteer

This command adds John Doe instantly, tagged as a volunteer. You can then use filtertag volunteer to find all volunteers, saving time compared to traditional methods.

AdmiNUS helps you stay organised and efficient, allowing you to focus on running successful events.

Who Benefits from AdmiNUS?

AdmiNUS is designed primarily for NUS Club Administrators who need an efficient way to manage member and participant lists. The tool helps streamline contact organisation, track participants effectively, and ensures smooth event coordination, making it an essential resource for those responsible for handling large contact databases.

Table of Contents

• Quick Start
• Features
  • Basic Commands
    • Viewing help: help
    • Link to the user guide: helpwindow
    • Listing all contacts: list
    • Viewing a contact: view
    • Clearing all entries: clear
    • Exiting the program: exit
  • Contact Management
    • Adding a student: student
    • Adding a company: company
    • Editing a contact: edit
    • Deleting contact(s): delete
  • Advanced Commands
    • Locating persons by name: find
    • Filtering contacts by tag: filtertag
    • Tracking contacts by category: track
    • Adding tag(s) to contact: tag
    • Deleting tag(s) from contact: deletetag
  • File Operations
    • Importing CSV files: import
    • Exporting CSV files: export
• Glossary
• FAQ
• Known issues
• Command summary

Quick start

1. Ensure you have Java 17 or above installed in your Computer. Download it here.

2. Download the latest .jar file from here.

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

4. Open a command terminal, and run the following commands:

   • cd your_file_path_to_folder which takes you to the folder you put the jar file in.
   • java -jar AdmiNUS.jar command to run the application.
     

   A GUI similar to the below should appear in a few seconds. Note how the app contains some sample data.
   

5. Type the command into the command box, which is indicated by Enter command here..., and press Enter to execute it. e.g. typing help and pressing Enter will open the help window.
   Some example commands you can try:

   • list: Lists all contacts.

   • student n/John Doe id/A0123456Z p/98765432 e/johnd@example.com a/John street, block 123, #01-01: Adds a student named John Doe to the AdmiNUS.

   • delete 3: Deletes the 3rd contact shown in the current list.

   • clear: Deletes all contacts.

   • exit: Exits the app.

6. Refer to the Features below for details of each command.

Features

Basic Commands

Viewing help: help

Shows a message explaining the various commands available.

Format: help

Expected message:

Showing list of possible commands on the right.

Link to the user guide: helpwindow

Pops up a window, where there is a link to the user guide for the user to easily access.

Format: helpwindow

Expected message:

For more information, please head to the user guide.

Listing all contacts: list

Shows a list of all persons in AdmiNUS.

Format: list

Expected message:

Listed all persons

Viewing a contact: view

Shows the details of a contact.

Format: view INDEX

Expected message:

Displayed person: (Details of person)

Example:

• view 1 shows the details of the first contact in the list.

Clearing all entries: clear

Clears all entries from AdmiNUS.

Format: clear

Expected message:

Contact list has been cleared!

Exiting the program: exit

Exits the program.

Format: exit

Contact Management

Adding a student: student

Adds a student to AdmiNUS.

Format:

student n/NAME id/STUDENT_ID p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​

Expected Message:

New student added: (details of the student added)

Examples:

• student n/John Doe id/A0123456X p/98765432 e/johnd@example.com a/John street, block 123, #01-01 adds a student named John Doe to AdmiNUS.

Adding a company: company

Adds a company to AdmiNUS.

Format:

company n/NAME i/INDUSTRY p/PHONE_NUMBER e/EMAIL a/ADDRESS [t/TAG]…​

Expected Message:

New company added: (details of the company added)

Examples:

• company n/Newgate Prison i/Security e/newgateprison@example.com a/Newgate Prison p/1234567 t/prison t/facility adds a company name Newgate Prison to AdmiNUS.

Editing a contact: edit

Edits an existing contact in AdmiNUS.

Format:

edit INDEX [n/NAME] [id/STUDENT_ID] [i/INDUSTRY] [p/PHONE] [e/EMAIL] [a/ADDRESS] [t/TAG]…​

Expected Message:

Edited Person: (details of the updated contact)

Examples:

• edit 1 p/91234567 e/johndoe@example.com edits the phone number and email address of the 1st contact to be 91234567 and johndoe@example.com respectively.
• edit 2 n/Betsy Crower t/ edits the name of the 2nd person to be Betsy Crower and clears all existing tags.

Deleting contact(s): delete

Deletes the contact(s) at the specified indices or all contacts currently shown in the list from AdmiNUS.

Format 1: delete INDEX [MORE_INDEX]…​

Expected Message:

Deleted Contacts:
(list of contact(s) specified at INDEX and MORE_INDEX if present)

Format 2: delete all

Expected Message:

Deleted Contacts:
(list of all contacts shown in the list)

Examples:

• list followed by delete 2 3 deletes the 2nd and 3rd contacts in AdmiNUS given that there are more than 3 contacts in the list.
• find Betsy followed by delete all deletes all contacts in the results of the find command.

Advanced Commands

Locating persons by name: find

Finds persons whose names contain any of the given keywords.

Format: find KEYWORD [MORE_KEYWORDS]…​

Expected Message:

(Number of) persons listed!

Examples:

• find John returns john and John Doe

• find alex david returns Alex Yeoh, David Allen
  

  

Filtering contacts by tags: filtertag

Finds contacts whose tags are the same as the specified keyword.

Format: filtertag KEYWORD [MORE_KEYWORD]…​

Expected Message:

(Number of) persons listed!

Examples:

• filtertag paid finds contacts who have tags saved as paid.

Tracking contacts by category: track

Tracks and lists all contacts who are in the category of the specified keyword.

Format: track CATEGORY​

Expected message:

Listed all persons under category: CATEGORY
(tracked list size number) persons listed!

Examples:

• track student finds contacts with category student.
• track company finds contacts with category company.

Adding tag(s) to contact: tag

Adds additional specified tag(s) to the specified contact or all contacts in the list provided no duplicate tags(s) are found in all contacts without overwriting existing tags.

Format 1: tag INDEX t/TAG [t/MORE_TAG]…​

Tagging operation applies to specified contact in the list.

Expected message:

Added tag(s): [TAG], [MORE_TAG(if present)]
to Person: (details of the person)

Format 2: tag all t/TAG [t/MORE_TAG]…​

Expected message:

Added tag(s): [TAG], [MORE_TAG(if present)] to all contacts.

Examples:

• tag 1 t/computerScience t/Y2 adds the tags computerScience and Y2 to the first contact in the list.

Expected outcome for the above tip on tag all:

• track student
  

  

• tag all t/paid
  

  

  Note: in this case, only all students are tagged with the paid tag.

Deleting tag(s) from contact: deletetag

Deletes the specified tag(s) from the specified contact or from all the contacts in the list provided they all have the specified tag(s).

Format 1: deletetag INDEX t/TAG [t/MORE_TAG]…​

Expected message:

Deleted Tags (TAG [MORE_TAG]) from Contact: (details of the updated contact)

Format 2: deletetag all t/TAG [t/MORE_TAG]…​

Expected message:

Deleted the tag(s) (TAG [MORE_TAG]) from all contacts in the list.

Examples:

• deletetag 1 t/senior t/Y2 deletes the senior and Y2 tags from the first contact in the list.
• deletetag all t/senior t/Y2 deletes the senior and Y2 tags from all contacts in the list.

File Operations

Importing CSV Files: import

The import command allows you to bring data from a CSV file into the application, enabling seamless population of your contacts database from external sources.

Format: import FILE_PATH

Absolute Path:

• Specifies the full path from the root directory.
• Unix/Linux/Mac: /home/user/data/hackers_2022.csv
• Windows: C:\\Users\\user\\data\\hackers_2022.csv

Relative Path:

• Starts from the current working directory of the application.
• Example: data/File.csv or ./data/hackers_2022.csv
• If the application runs in /home/user/project, import data/File.csv points to /home/user/project/data/File.csv.

Examples:

• Absolute: import /home/user/data/hackers_2022.csv
• Relative: import ./data/hackers_2022.csv

• The contents of an example CSV file.

• After executing the import command, the contents of the CSV file are being imported to AdmiNUS.

Troubleshooting:

• For errors such as “file not found,” confirm the path type (absolute vs. relative) and the file’s existence.
• Ensure the application has access rights to the specified directory.
• If you receive an error message indicating that the file is “corrupted or missing compulsory fields,” check the following:
  • Ensure all required fields are present in each row of your CSV file (e.g., name, category, studentID or industry, phone, email, address).
  • Confirm that each row follows the correct format, with entries for every compulsory field. Empty fields can trigger this error.
  • Verify that the file is saved with a .csv extension and is structured as a valid CSV (comma-separated values), with columns corresponding to the required fields.

Exporting CSV Files: export

The export command is used to save your current contacts database into a CSV file, enabling data sharing and backup.

Format: export FILE_PATH

Absolute Path:

• Specifies the full path, starting from the root directory.
• Unix/Linux/Mac: /home/user/data/output_data.csv
• Windows: C:\\Users\\user\\data\\output_data.csv

Relative Path:

• Refers to paths relative to the current directory.
• Example: ./data/Output.csv saves to data in the current directory.

Examples:

• Absolute: export /home/user/data/output_data.csv
• Relative: export ./data/Output.csv

Troubleshooting:

• If an error occurs during export (e.g., “access denied”), check your write permissions for the specified directory.
• Confirm the path ends with .csv to avoid format issues.

Saving the data

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

Editing the data file

AdmiNUS data are saved automatically as a JSON file

[JAR file location]/data/addressbook.json

Advanced users are welcome to update data directly by editing that data file.

Caution: If your changes to the data file make its format invalid, AdmiNUS will discard all data and start with an empty data file at the next run. It is recommended to make a backup of the file before editing it. Furthermore, certain edits can cause AdmiNUS to behave in unexpected ways (e.g., if a value entered is outside of the acceptable range). Therefore, edit the data file only if you are confident that you can update it correctly.

Glossary

• Absolute Path: A full path that specifies the exact location of a file or directory from the root of the file system.
• Case-Insensitive: A term used to describe a system where uppercase and lowercase letters are treated as the same. For example, Apple, apple, and APPLE would be considered equivalent values.
• Case-Sensitive: A term used to describe a system where uppercase and lowercase letters are treated as distinct. For example, Apple, apple, and APPLE would be considered different values.
• Category: A label that represents the type of contact (e.g., student, company) used for filtering and sorting contacts.
• CLI (Command Line Interface): A text-based user interface through which users interact with the application by typing commands.
• CSV (Comma-separated values): A text file format that uses commas to separate values, and newlines to separate records.
• Directory: A file system structure that contains references to other files and directories. It is commonly referred to as a folder and is used to organise files hierarchically within a file system.
• GUI (Graphical User Interface): The part of the application that users interact with, which includes graphical components like command boxes and task lists.
• JSON (JavaScript Object Notation): A lightweight data interchange format that is easy for humans to read and write and easy for machines to parse and generate. JSON represents data using key-value pairs and supports data types such as strings, numbers, arrays, objects, and booleans. It is widely used for transmitting structured data over network connections, particularly in web applications.
• NUS Club Administrator: An NUS club admin user responsible for managing contacts of students, companies, etc.
• Parameter-like Sequence: A combination of a forward slash (/) and a single character that resembles the prefixes used in commands (e.g., n/, p/, e/). These are used to specify input fields in commands and should not appear in any text fields.
• Path: A sequence of symbols and names that identifies the location of a file or folder within a computer’s file system. Paths can be absolute, starting from the root of the file system (e.g., /home/user/documents/file.txt), or relative, which are based on the current directory (e.g., documents/file.txt).
• Relative Path: A file path that is relative to the current working directory of the user or application.
• Student ID: The student ID associated with each student in NUS. It has the format AxxxxxxxX (e.g. A0123456Z).
• Tag: A keyword or label associated with a contact that allows for easy grouping and filtering.

FAQ

Q: How do I transfer my data to another computer?
A: Install the app on the new computer, then replace its default data file with the data file from your previous AdmiNUS home folder. Alternatively, export your data to a CSV file from the original computer using the export command and import it on the new computer using the import command.

Q: How do I back up my AdmiNUS data?
A: The data is saved automatically in a JSON file located in the

[JAR file location]/data/addressbook.json

You can make a backup by copying this file to a safe location. Alternatively, you can export your data to a CSV file using the export command.

Q: Can I use AdmiNUS without Java installed on my computer?
A: No, AdmiNUS requires Java 17 or above to run. You need to ensure that the correct version of Java is installed before using the application.

Q: Is there a way to undo a deletion?
A: Currently, there is no built-in undo function. Once a contact is deleted using the delete command, it cannot be recovered unless you have a backup of your data file.

Q: Why can’t I add a student with the same Student ID?
A: Each student in AdmiNUS must have a unique Student ID. If you try to add a student with an existing Student ID, the system will reject the new entry. Make sure to verify the ID before adding a new student.

Q: I get an error message saying “Invalid path” when importing a CSV. What should I do?
A: This error can occur if the file path you specified is incorrect or if the file doesn’t exist. Ensure you are using a valid absolute or relative path and that the file is present in the directory. If you are on Windows, remember to use double backslashes (\\) in the file path.

Q: Can I edit the data file manually?
A: Yes, advanced users can manually edit the addressbook.json file where data is saved. However, any incorrect modification may cause data loss or unexpected behavior in the application. Always make a backup before editing.

Q: Why are my tags disappearing when I edit a contact?
A: When editing a contact, if you use the t/ parameter without specifying new tags, all existing tags will be removed. To retain the tags, include all desired tags in the edit command.

Q: What should I do if AdmiNUS opens off-screen after using multiple monitors?
A: This can happen if you move the application to a secondary screen and then disconnect that monitor. To resolve this, delete the preferences.json file generated by AdmiNUS, and the app will reset its position to the primary screen.

Q: How do I efficiently delete multiple contacts?
A: You can use the delete INDEX [MORE_INDEX]…​ command to delete multiple contacts by specifying their indices. If you want to delete all contacts displayed after a filter operation, use delete all. Be careful with this command as it cannot be undone.

Known issues

1. When using multiple screens, if you move the application to a secondary screen, and later switch to using only the primary screen, the GUI will open off-screen. The remedy is to delete the preferences.json file created by the application before running the application again.
2. If you minimize the Help Window and then run the help command (or use the Help menu, or the keyboard shortcut F1) again, the original Help Window will remain minimised, and no new Help Window will appear. The remedy is to manually restore the minimized Help Window.
3. Entering parameter-like sequences in input fields: If a user enters text that resembles a parameter prefix (e.g., n/, p/, e/) within an input field like Name or Address, it may cause unexpected parsing errors or rejections. Ensure that parameter-like sequences are avoided within fields that do not expect them.
4. Case Sensitivity of the Industry Field: The industry field is currently case-sensitive. This means that entries with different capitalisation (e.g., University and UNiversity) will be treated as separate and distinct values, even though they appear visually identical in the interface. This behavior can lead to unintended duplicates if users do not input industry names with consistent capitalisation.

Command summary

Back to Table of Contents