Skip to content

Latest commit

 

History

History
367 lines (271 loc) · 14.3 KB

UserGuide.adoc

File metadata and controls

367 lines (271 loc) · 14.3 KB

Duty Planner - User Guide

By: CS2103 W15-4 Since: Feb 2019 Licence: MIT

1. Introduction

MINDEF Duty Planner is a platform to assist military units in the SAF in the assignment of daily duties amongst the servicemen. The application is optimized for those who prefer to work with a Command Line Interface (CLI) while still having the benefits of a Graphical User Interface (GUI). The software is designed to automate the process of fairly assigning duties to available servicemen for an entire month. It also enables servicemen to conveniently indicate the days they are unavailable for duty. It seeks to fairly distribute duties by taking into account the varying importance of each duty (e.g. Sunday duties are worth more than weekday duties).

2. Quick Start

  1. Ensure you have Java version 9 or later installed in your Computer.

  2. Log in into the system as an admin or a general user. NRIC corresponds to the username. Both the NRIC and the password are case-sensitive.

    • For admin account: NRIC is Admin, password is Admin

    • For general account: NRIC is the user’s NRIC, password is NRIC by default which can be changed.

  3. 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.

  4. Some example commands you can try:

    • list : lists all contacts

    • addn/John Doe nr/S9012345N p/98765432 c/Echo s/2 r/CFC t/injured : adds a personnel named John Doe to the Personnel Database.

    • delete3 : deletes the 3rd contact shown in the current list

    • exit : exits the app

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

  6. Some commands can only be accessed by Admin type accounts and some by General type accounts.

3. User Features

3.1. Log in

  • For Practical Exam: You may use an administrator account with Username: Admin, and Password: Admin

  • For Practical Exam: In personnel list, the password of the users will be listed for your convenience.

  • If you close the login window, you are still able to view the personnel list and the calendar duty list. However, you will not be able to use any commands.

Logs user into account
NRIC and passwords are case-sensitive.
Enter in NRIC and password into the top and bottom text areas respectively, press enter.

  • Can only be done in the login box at the start of the program.

  • By default, if your password has not been changed by you or an Admin, the password is your NRIC.

  • Contact an administrator if you have trouble logging in.

  • If you need to change your account, exit the program, then log back into a different account.

  • There are 2 types of accounts: General type accounts, and Admin (or Administrator) type accounts.

  • Admin accounts have access to more commands, or more functionalities for some kind of commands.

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in login nr/NRIC, NRIC is a parameter which can be used as add n/S01234567Z.

  • Items in square brackets are optional e.g n/NAME [t/TAG] can be used as n/John Doe t/friend or as n/John Doe.

  • Items with …​ after them can be used multiple times including zero times e.g. [t/TAG]…​ can be used as   (i.e. 0 times), t/friend, t/friend t/family etc.

  • Parameters can be in any order e.g. if the command specifies n/NAME p/PHONE_NUMBER, p/PHONE_NUMBER n/NAME is also acceptable.

  • An Admin and a User may have different formats for the same command

3.2. Features for all users

3.2.1. Viewing help : help

Lists out a list of commands & instructions
Format: help

3.2.2. List all the users: list

Lists out all users with their details.
Format: list

3.2.3. View duties assigned to user : view

The user can see their details about their own duties assigned to them and their upcoming duties ranked by recency.
Format: view

3.2.4. View duties assigned to other users : view

The user can see their details about their own duties assigned to other users.
Format: view NRIC

Example:

  • view S9012345L

3.2.5. View roster : roster Not implemented yet

The user can see the full duty rosters for particular months.
Format: roster MONTH

Example:

  • roster February

3.2.6. Block dates : block

The user can block dates and set which dates they are unavailable to duties for upcoming months. A user can block up to 15 days per month.
Format: block MONTH DAY DAY DAY …​

Example:

  • block March 3 6 15 21 30

3.2.7. View blocked dates : block

The user can view the dates they have blocked for a particular month.
Format: block MONTH

Example:

  • block March

3.2.8. Make a swap request with another user : swap

The user can request for a duty swap with another user. This will be subject to the agreement of the other user and approval of the admin (i.e. commander).
The other user and admin will be notified upon login and they will be prompted to accept or decline the request.
Format: `swap ad/CURRENTDUTYDATE rd/DESIREDDUTYDATE

Example:

  • swap ad/14022019 rd/21022019 t/Please help a bro out!

3.2.9. Locating persons by name: find

Finds persons whose names contain any of the given keywords.
Format: find KEYWORD [MORE_KEYWORDS]

  • The search is case insensitive. e.g hans will match Hans

  • The order of the keywords does not matter. e.g. Hans Bo will match Bo Hans

  • Only the name is searched.

  • Only full words will be matched e.g. Han will not match Hans

  • Persons matching at least one keyword will be returned (i.e. OR search). e.g. Hans Bo will return Hans Gruber, Bo Yang

Examples:

  • find John
    Returns john and John Doe

  • find Betsy Tim John
    Returns any person having names Betsy, Tim, or John

3.2.10. Listing entered commands : history

Lists all the commands that you have entered in reverse chronological order.
Format: history

ℹ️

Pressing the ↑ and ↓ arrows will display the previous and next input respectively in the command box.

3.2.11. Undoing previous command : undo

Restores the address book to the state before the previous undoable command was executed.
Format: undo

ℹ️

Undoable commands: those commands that modify the address book’s content (add, delete, edit and clear).

Examples:

  • delete 1
    list
    undo (reverses the delete 1 command)

  • select 1
    list
    undo
    The undo command fails as there are no undoable commands executed previously.

  • delete 1
    clear
    undo (reverses the clear command)
    undo (reverses the delete 1 command)

3.2.12. Redoing the previously undone command : redo

Reverses the most recent undo command.
Format: redo

Examples:

  • delete 1
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)

  • delete 1
    redo
    The redo command fails as there are no undo commands executed previously.

  • delete 1
    clear
    undo (reverses the clear command)
    undo (reverses the delete 1 command)
    redo (reapplies the delete 1 command)
    redo (reapplies the clear command)

3.2.13. Exit : exit

Exits the program. User will be logged out automatically.
Format: exit

3.3. General Features

3.3.1. Edit own details : edit

Edits user’s own details. Can edit one or more fields.
Format: edit INDEX [c/COMPANY] [s/SECTION] [r/RANK] [n/NAME] [p/PHONE] [t/TAG] [pw/PASSWORD]

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the person will be removed i.e adding of tags is not cumulative.

  • You can remove all the person’s tags by typing t/ without specifying any tags after it.

Examples:

  • edit p/84523546 r/CPL
    Edits the phone number and rank of the user to be `84523546     and CPL respectively.

  • edit c/Hotel t/ pw/pass
    Edits the company of the user to be Hotel, clears all existing tags, and changes password to 'pass'.

3.4. Admin Features

3.4.1. Adding a user : add

Add a user to the system with the corresponding NRIC, password, company, section, rank, name and contact number.
Format: add nr/NRIC c/COMPANY s/SECTION r/RANK n/NAME p/PHONE [t/TAG]

  • By default, the user will be a General type account, and the password will be the NRIC.

  • Password and account type can be changed using the edit command.

3.4.2. Deleting a person : delete

Deletes the specified person from the duty planner.
Format: delete INDEX

  • Deletes the person at the specified INDEX.

  • The index refers to the index number shown in the displayed person list.

  • The index must be a positive integer 1, 2, 3, …​

Examples:

  • list
    delete 2
    Deletes the 2nd person in the duty planner personnel list.

  • find Betsy
    delete 1
    Deletes the 1st person in the results of the find command.

3.4.3. Clearing all entries : clear

Clears all entries from the duty planner.
Format: clear

3.4.4. Edit any user’s details : edit

Edits an existing user’s details in the personnel list. Format: edit INDEX [nr/NRIC] [c/COMPANY] [s/SECTION] [r/RANK] [n/NAME] [p/PHONE] [t/TAG] [pw/PASSWORD] [u/A or G]

  • Edits the person at the specified INDEX. The index refers to the index number shown in the displayed person list. The index must be a positive integer 1, 2, 3, …​

  • At least one of the optional fields must be provided.

  • Existing values will be updated to the input values.

  • When editing tags, the existing tags of the person will be removed i.e adding of tags is not cumulative.

  • You can remove all the person’s tags by typing t/ without specifying any tags after it.

  • For account type field specified by u/, A corresponds to an Admin account, G corresponds to a general account.

Examples:

  • edit 2 p/84523546 r/CPL u/A
    Edits the phone number and rank of the 2nd person to be 84523546 and CPL respectively, and grants the person’s account administrator privileges.

  • edit 1 c/Hotel t/ pw/pass
    Edits the company of the 1st person to be Hotel, clears all existing tags, and changes passworrd to 'pass'.

3.4.5. Scheduling duties : schedule

This command invokes the scheduling algorithm for the upcoming month. It generates a viable duty schedule roster where each duty slot for the upcoming month will be filled by the people currently in the database. ++

In order to ensure fair scheduling system,

  1. We introduce a point system to each individual such that a servivemen can earn points by doing duties. The points awarded to servicemen are cumulative, thus the points awarded are carried over to the next month.

  2. Each duty is worth a certain number of points and a person gains that amount of points by doing that duty. For example, if all Sunday duties are worth 4 points, a servicemen who is assigned a Sunday duty will by awarded 4 points.

  3. Before the scheduling command is called, each person has the opportunity to indicate the days in which they are unavailable to do duty. (See 3.9 block command)

The algorithm is optimized such that persons with low points will be allocated to duties with high points. It automatically attempts to balance out the points of each person by the end of the month.

The duty schedule generated by the schedule command is not deterministic, calling schedule command multiple times generates different duty allocation.

Calling the schedule command merely generates a viable shedule, but does not finalize the schedule (i.e. points awarded to each person is yet to be added). Schedule generated is also not deterministic, calling schedule command multiple times generates different duty allocation. Thus, the admin can call schedule command continuously until a satisfactory schedule is produced. To finalize the schedule, use the confirm command. (See 4.8 confirm schedule)

Format: schedule

3.4.6. Confirm a Schedule : confirm

Confirm and finalize the last generated duty schedule (from the schedule command) for the upcoming month.
Subsequent attempts to call schedule command will not result in any new duty allocation produced.
Format: confirm

3.5. Saving the data

Duty roster personnel list and the duties allocated are saved in the hard disk automatically after any command that changes the data.
There is no need to save manually.

4. FAQ

Q: What if I want to swap my duty with another person?
A: Use "swap" command to request a swap. If you receive no updates about it, contact your administrator.

Q: What is the main feature of this app?
A: The main feature is the automated scheduling algorithm, which significantly minimizes the amount of work that the admin has to do.

Q: What is my username and password?
A: Your username is by default your NRIC, used so prevalently in the SAF.
Your password is also your NRIC by default, unless you or your administrator changed it. you can use the 'edit' command to edit your password later on.

Q: What if I forgot my password?
A: Contact your administrator for help.

Q: What should I do if I need help with the app?
A: You can enter 'help' in the command line, or press Help > Help, or simply press F1. This will open up the User Guide in a new window.

5. Command Summary

5.1. All Users

  • Viewing help : help

  • Viewing own duties : view

  • Viewing other’s duties : view NRIC

  • Blocking dates : block d/date d/date d/date …

  • Make swap request : swap

  • List all the users : list

  • Locate person by name : find

  • List entered commands : history

  • Undo command : undo

  • Redo command : redo

  • Exit : exit

5.2. General accounts

  • Edit own info : edit [c/COMPANY] [s/SECTION] [r/RANK] [n/NAME] [p/PHONE] [t/TAG] [pw/PASSWORD]

5.3. Admin accounts

  • Add a user : add nr/NRIC c/COMPANY s/SECTION r/RANK n/NAME p/PHONE [t/TAG]

  • Edit any user : edit INDEX [nr/NRIC] [c/COMPANY] [s/SECTION] [r/RANK] [n/NAME] [p/PHONE] [t/TAG] [pw/PASSWORD] [u/A or G]

  • Delete a user : delete INDEX

  • Scheduling duties : schedule

  • Confirm schedule : confirm

  • Clear entries : clear