Skip to content

UserGuide.adoc

Latest commit

 

History

History
699 lines (505 loc) · 25.2 KB

UserGuide.adoc

File metadata and controls

699 lines (505 loc) · 25.2 KB

Incident Management System - User Guide

By: Team CS2103-T11-1      Since: October 2019      Licence: MIT

1. Introduction

The Incident Management System (IMS) is a desktop app made for emergency call operators for coordinating emergency vehicle dispatch and incident report generation. IMS 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 streamlined workflow of the IMS is designed to enable call operators to dispatch vehicles and prepare reports without wasting any precious time. That’s because, in an emergency, every second counts.

2. Quick Start

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

  2. Download the latest ims.jar here.

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

  4. Double-click the file to start the app. The GUI should appear in a few seconds.

  5. You will first need to register an account, or login with one of the pre-made accounts.

  6. Logging in with an account that has the Admin tag (e.g. Agent01) gives you admin access to the system. The default password is 'password'.

    Ui

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

  8. Some example commands you can try: (TODO)

    • exit : exits the app

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

3. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in add n/NAME, NAME is a parameter which can be used as add n/John Doe.

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

  • Some commands have admin restrictions. Admins accounts are identified by the Admin tag.

ℹ️
 An account with admin privileges is included in the sample data with Username Agent01 and Password password

3.1. Viewing help : help

Format: help

3.2. Logging in: login

Logs the user into the IMS and registers the active session.
Format: login u/USERNAME w/PASSWORD

ℹ️
 The only commands available prior to login are Register, Login, Help, and Exit.

Example:

  • login u/Agent01 w/password

3.3. Logging out: logout

Logs the user out of the IMS and closes the user’s session.
Format: logout

3.4. Swapping interfaces: swap

Swaps the user interface between account view and incidents/vehicle view.
Format: swap

💡
 A user cannot access commands affecting entities not displayed in their current interface view.

Account Management Interface:

account

3.5. Registering an account: register

Registers an account into the Incident Management System
Format: register n/NAME p/PHONE_NUMBER e/EMAIL u/USERNAME w/PASSWORD [t/TAG]…​

💡
 A account can have any number of tags (including 0). Only logged-in admins can add tags.

  • Usernames must be at least 3 characters in length and must be unique.

  • Usernames can only consist of alphanumeric characters and the following special characters, excluding the parentheses, (.-)

  • Usernames cannot begin or end with a non alphanumeric character.

  • Usernames and Passwords cannot be blank or contain a whitespace.

  • Passwords must be at least 6 characters in length.

  • Passwords can only contain alphanumeric characters and/or these special characters, excluding the parentheses, (!#$%&'*+/=?`{|}~^.-)

Examples:

  • register n/John Doe p/98765432 e/johnd@example.com u/op1 w/password

  • If logged in with an admin account:
    register n/Betsy Crowe e/betsycrowe@example.com u/oc1 w/password p/1234567 t/Team-1-OC

3.6. Updating an account : update

Updates an existing account in the incident Manager or the own account of the user logged in if the index is left empty.
Format: update [INDEX] [n/NAME] [p/PHONE] [e/EMAIL] [u/USERNAME] [w/PASSWORD] [t/TAG]…​

ℹ️
 Only admins can update other user accounts. Non-admins cannot specify an index when executing the update command.

  • If an index is not provided, update executes on the account of the user logged in.

  • If an index is provided, updates the account at the specified INDEX. The index refers to the index number shown in the displayed account 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 updating tags, the existing tags of the account will be removed i.e adding of tags is not cumulative.

  • Only admins can access and edit tags. Admins cannot remove their own admin tag.

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

Examples:

  • update p/91234567 e/johndoe@example.com
    updates the phone number and email address of the logged in account to be 91234567 and johndoe@example.com respectively.

  • update 2 n/Betsy Crower t/
    updates the name of the 2nd account to be Betsy Crower and clears all existing tags.

3.6.1. Incident Auto Update [coming in v2.0]

Any updates to user account details will search for all incidents created by the account and update those references as well.

3.7. Listing accounts : list-a

Shows a list of all accounts registered in the incident Manager or those whose tags match any of the keywords if a keyword is specified.
Format: list-a [KEYWORD] [MORE_KEYWORDS]

  • The search is case insensitive. e.g admin will match Admin

  • Only the account tags are searched.

  • Only full words will be matched e.g. ad will not match admin

  • Accounts matching all keywords will be returned (i.e. AND search).

Examples:

  • list-a
    Displays the entire list of accounts

  • list-a team-1 admin
    Returns a list of all accounts that have both the admin and team-1 tag

3.8. Locating accounts by name or username: find-a

Finds accounts whose name or username contains any of the given keywords.
Format: find-a 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 and username is searched.

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

  • Partial words will be matched for Usernames e.g. Agent will match Agent01

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

Examples:

  • find-a John
    Returns john and John Doe

  • find-a Agent01 Betty Returns all accounts with username or name matching either agent01 or betty

3.9. Deleting an account : delete-a

Deletes the specified account from the incident Manager.
Format: delete-a INDEX

  • Deletes the account at the specified INDEX.

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

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

ℹ️
 Only admins can access the delete command. You cannot delete your own account.

Examples:

  • list-a
    delete-a 2
    Deletes the 2nd account in the Incident Manager.

  • find-a Agent01
    delete-a 1
    Deletes the 1st account in the results of the find command.

3.9.1. Incident Auto Update [coming in v2.0]

Deleting a user will search for all incidents created by the user and place a deleted flag next to the account details.

3.10. Create New Incident: new

When new incidents are reported, vehicles are to be dispatched to the incident site. As of now, when there is no vehicle available in the district of incident, a new report cannot be generated.

This command works in two ways:

1. auto/Y
Format: new dist/DISTRICT auto/Y

  • An available vehicle in the given district will be automatically dispatched to the incident site.

    • If no vehicle is available, the vehicle pane will be blank, and a relevant message is displayed.

  • After the new incident is successfully created, the vehicle pane will show all vehicles in the given district.

    • The draft incident only has three fields filled: operator, district and vehicle dispatched.

Important
 Valid district numbers are from 1 to 28!

  • Example usage:

newCommandAutoYBeforeSS

  • Expected outcome: In this case, there is no vehicle available in district 1.

newCommandAutoYAfterSS

2. auto/N
Format: new dist/DISTRICT auto/N v/INDEX

  • A list of available vehicles in the given district will be shown.

    • INDEX is the index of the chosen vehicle, based on the list of available vehicles in the district.

    • If v/INDEX is not included, a message will appear to prompt user to also include the index of the chosen vehicle.

    • If no vehicle is available, the vehicle pane will be blank, and a relevant message is displayed.

  • After the new incident is successfully created, the vehicle pane will show all vehicles in the given district.

Important
 For manual dispatchment of vehicle, the index of the chosen vehicle must be from the list of vehicles available in the given district, which is only displayed when new dist/DISTRICT auto/N is used.

  • Example usage:

newCommandAutoNPromptSS

Once user adds v/1, a new incident will be drafted.

ℹ️
 If multiple flags of the same prefix is provided by user, the command will take the last valid parameter of each prefix.
For example new dist/1 dist/2 dist/3 auto/Y auto/N is equivalent to new dist/3 auto/N.
Rationale: user need not waste time backspacing if an input was keyed in wrongly.

3.11. Filling a draft incident report: fill

Fills a draft incident report if relevant parameters are specified, otherwise lists all draft reports ready for filling.

This command works in two modes:

1. No parameter mode
Format: fill
Lists all draft incident reports ready to be filled.

  • This command lists both incomplete and complete drafts.

  • If no drafts exist, a message is displayed and the Incident list remains unchanged.

  • Outcome of fill:

fillCommandNoParamsAfterScreenshot

2. Parameter mode
Format: fill [INDEX] [p/CALLER_NUMBER] [desc/DESCRIPTION]
Fills the draft incident report corresponding to the specified index with the phone number of the caller who reported the incident and the description of the incident.

ℹ️
 The user can only fill the draft incident reports that have been created by them.

  • Index must be assigned with reference to the currently shown list of incidents on the GUI incident panel.

  • Both incomplete and complete drafts can be filled.

  • Fields of complete drafts will be overwritten.

  • Executing this command changes incident status to 'Complete Draft'.

  • Both CALLER_NUMBER and DESCRIPTION fields must be specified while executing this command.

  • The newly filled draft will now appear at the top of the list of incidents in the GUI incident panel view.

  • Outcome of fill 1 p/90309049 desc/Traffic accident reported at FKU hospital junction:

fillCommandWithParamsAfterScreenshot

Using fill in both modes one after the other thus enables convenient listing and filling of target incident reports.

3.12. Submitting a completed draft report: submit

Submits a completed draft incident report if relevant parameters are specified, otherwise lists all completed drafts ready for submission.

Similar to fill, this command also works in two modes:

1. No parameter mode
Format: submit
Lists all completed draft incident reports ready for submission.

  • This command only lists complete drafts.

  • If no complete drafts exist, a message is displayed and the Incident list remains unchanged.

  • Outcome of submit

submitCommandNoParamsAfterScreenshot

2. Parameter mode
Format: submit [INDEX]
Submits the completed draft incident report corresponding to the specified index.

ℹ️
 The user can only submit the completed incident reports that have been created by them.

  • Index must be assigned with reference to the currently shown list of incidents on the GUI incident panel.

  • Only complete drafts can be submitted.

  • Executing this command changes incident status to SUBMITTED_REPORT.

  • The newly submitted draft will now appear at the top of the list of incidents in the GUI incident panel view.

  • Outcome of submit 1:

submitCommandWithParamsAfterScreenshot

3.13. Admins can fill and submit drafts [coming in v2.0]

This feature will allow admins to fill and submit incomplete and complete drafts, in case the operator that created those reports has been now removed from the system.

3.14. Tracking incident history [coming in v2.0]

Allows user to track any changes made to an incident report throughout its lifecycle in the incident management system.
Format: track [INDEX]
Function: Outputs a list of timestamps and a brief summary of changes made to the specified incident report.

This feature will allow the user to improve accountability in filing incident reports. As the IMS handles incident data which is very sensitive in nature, it will be crucial for users to know when exactly were what changes made to a given incident report.

3.15. Listing all incidents: list-i

Shows a list of all incidents in the Incident Manager
Format: list-i

Example usage and expected outcome:

listIncidentsCommand
Fig X. The list-i command returns all incidents within the system.

  • The listing returns all incidents, inclusive of all incomplete drafts and complete drafts and submitted incident reports

  • Adding any keywords or parameters will result in an error. Only list-i is allowed.

3.16. Locating an incident report using incident ID, operator name or description keyword: find-i

Finds incidents containing the relevant specified parameters. Possible Parameters: id/, op/, desc/, self

Different Parameters

By Operator Name
Format: find-i op/<OPERATOR KEYWORD [MORE_KEYWORDS]>
Lists all incidents whereby the operator name contains any of the given keywords

  • Accepts multiple search terms for the parameter, searching for any match with any search term

  • Example of Successful Single Operator Search and Expected Outcome:

findIncidentsCommandWithOperatorParameter
Fig X. The find-i command has been called with one word under parameter op\, returning all incidents whereby the operator name matches alex (case-insensitive)

  • Example of Successful Multiple Operator Search and Expected Outcome:

findIncidentsCommandWithOperatorsParameter
Fig X. The find-i command has been called multiple words under parameter op\, returning all incidents whereby the operator name matches irfan or bernice (case-insensitive)

By Description
Format: find-i desc/<DESCRIPTION KEYWORD [MORE_KEYWORDS]…​>
Lists all incidents whereby the incident description contains any the given keywords

  • Example of Successful Usage and Expected Outcome:

findIncidentsCommandWithDescriptionParameter
Fig X. The find-i command has been called with parameter desc\, returning all incidents whereby the description contains either keyword fire or arson

By ID
Format: find-i id/KEYWORD
Lists all incidents whereby the incident ID is an exact match with the given keyword

  • Requires an exact ID match, only accepts one ID

  • Example of Successful Usage and Expected Outcome:

findIncidentsCommandWithIdParameter
Fig X. The find-i command has been called with parameter id\, returning all incidents whereby the ID matches 0620150001 exactly

Self-Search
Format: find-i self
Lists all incidents whereby the operator name matches the logged-in user’s name.

  • Example of Successful Usage and Expected Outcome:

findIncidentsCommandWithSelfParameter
Fig X. Executing find-i self lists all completed drafts ready for submission

  • Requires an exact name match with the logged-in user’s name

  • The search is case insensitive. e.g dave will match Dave

  • The search returns all incidents found regardless of state (incomplete and complete drafts, submitted incidents)

  • Multiple words can be taken for the operator and description parameter. The command returns all incidents which contains at least one of the words within the parameter

  • The ID parameter requires an exact match

  • Multiple parameters can be searched, returning incidents whereby all parameters match

  • Only full words/IDs will be matched e.g. Fir will not match Fire

Examples:

  • ID Match: find-i id/0920160001
    Returns Incident #0920160001

  • Multiple Parameters: find-i op/Dave desc/fire
    Returns any incidents whereby the operator’s name contains 'Dave' and the description contains 'fire'

  • Multi-word Parameter Search: find-i op/Alex Bernice
    Returns any incidents whereby the operator’s name contains either 'Alex' or 'Bernice'

  • Self-Search: find-i self
    Returns any incidents whereby the operator’s name matches the logged-in operator’s name

3.17. Editing an Incident: edit-i

Edits an existing incident in the Incident Manager as identified by the index in the display. Format: edit-i [INDEX] [dist/DISTRICT] [p/CALLER NUMBER] [desc/DESCRIPTION]

  • If an index is not provided, system will prompt for index. Does not make any edits.

    ℹ️
    		 Use edit-i to list all submitted reports

  • Only admins can edit all reports, other users are only allowed to edit the reports they created.

  • Number of fields provided for update is optional and can vary.

    ℹ️
    		 If no fields are provided, incident will remain unchanged.

  • Existing values will be updated to input values provided.

  • Edits that result in duplicate incidents are not allowed

  • Can only edit submitted reports. Edit command should not be used on reports in draft state, instead, the fill command should be used.

ℹ️
 Incidents with all the same fields (DateTime, District, IncidentId, Caller Number) are considered duplicates.

Example of input:

  • edit-i 1 dist/2 desc/This is an incident description.

    • result: only district and description is changed.

  • edit-i 1

    • result: No new fields were provided, incident is not edited.

editIncident1
editIncident2

3.18. Adding a Vehicle: add-v

Adds a vehicle into the Incident Management System. Format: add-v [dist/DISTRICT] & [vnum/VEHICLE NUMBER] & [vtype/VEHICLE TYPE] & [a/AVAILABILITY]

ℹ️
 All fields must be provided in order to make a valid addition to the Incident Management System. If any of the fields are missing, vehicle will not be added.

  • Vehicles that have the same vehicle number and vehicle type are considered to duplicate vehicles

  • Duplicate vehicles cannot be added into the Incident Management System.

Examples:

  • add-v dist/2 vnum/SFD1234A vtype/Ambulance a/available

    • result: New vehicle added: Ambulance Vehicle Number: 12345 District: 2 Availability: AVAILABLE

  • add-v dist/12 vnum/SFD1234A vtype/Patrol Car a/busy

    • result: New vehicle added: Patrol Car Vehicle Number: 23456 District: 12 Availability: BUSY

addVehicle1
addVehicle2

3.19. Editing a Vehicle: edit-v

Edits a vehicle identified by the index displayed in the Incident Management System. Format: edit-v [INDEX] [dist/DISTRICT] [vtype/VEHICLE TYPE] [a/AVAILABILITY]

ℹ️
 Number of fields provided for edit may vary. If no fields are provided, the vehicle will not be edited.

  • Edit inputs that result in duplicate vehicles in the list will not be allowed.

  • Only vehicles displayed on the interface are valid of edit.

  • Existing values will be updated to the input values given.

  • Any vehicle can be edited regardless of state.

Example:

  • edit-v 1 dist/13 vtype/Ambulance

    • result: district will be changed to 13 and vehicle type will be changed to Ambulance

Edit vehicle:

editVehicle1
editVehicle2

Edit Vehicle that results in duplicates:

editDuplicateVeh1
editDuplicateVeh2

3.20. Listing vehicles

Shows a list of all vehicles registered in the incident Manager. Format: list-v

  • The listing returns all vehicles and their relevant details.

  • All keywords and parameters used are ignored.

3.21. Finding a Vehicle: find-v

Finds a vehicle by its district number, vehicle number or vehicle type.

The command works in three ways:

1. Find by district Format: find-v dist/DISTRICT [MORE DISTRICTS]

  • User can input multiple districts to search for vehicles in.

Example usage:

findVDsBeforeSS
findVDsAfterSS

2. Find by vehicle number Format: find-v vnum/NUMBER

  • The number need not be an exact match of any vehicle number; any vehicle with input number in its vehicle number will be returned.

Example usage:

findVVnumBeforeSS
findVVnumAfterSS

3. Find by vehicle type Format: find-v vtype/VEHICLE TYPE

  • The vehicle type keyword must match the actual vehicle type exactly.

Example usage:

findVVtypeBeforeSS
findVVtypeAfterSS

3.22. Deleting a Vehicle: delete-v

Deletes a vehicle in the list as identified by the index.

Format: delete-v [INDEX]

  • Only an admin account can delete vehicles.

  • A valid index has to be provided

    ℹ️
    		 A valid index is a positive integer and points to a vehicle displayed in the vehicles list.

  • Vehicles that are currently dispatched or indicated as BUSY will not be able to be deleted.

deleteVehicle1
deleteVehicle2

3.23. Exiting the program : exit

Exits the program.
Format: exit

3.24. Saving the data

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

3.25. Decrypting data files [coming in v2.0]

Decrypts the incident manager data file.
Format: decrypt PASSWORD

Data files will be encrypted by default. Users can decrypt the file with the command above.

3.26. Creating new incidents even when no vehicle is available in the given district. [coming in v2.0]

User can choose to create an incident pending vehicle dispatchment. Format: new dist/DISTRICT auto/Y r/pending

4. FAQ

Q: How do I transfer my data to another Computer?
A: Install the app in the other computer and overwrite the empty data file it creates with the file that contains the data of your previous Incident Management System folder.

5. Command Summary

  • Help : help

  • Login : login u/USERNAME w/PASSWORD

  • Logout : logout

  • Swap : swap

  • Register : register n/NAME p/PHONE_NUMBER e/EMAIL u/USERNAME w/PASSWORD [t/TAG]…​
    e.g. register n/James Ho p/22224444 e/jamesho@example.com u/Agent-3 w/password t/Admin t/Team-01

  • Update : update [INDEX] [n/NAME] [p/PHONE_NUMBER] [e/EMAIL] [u/USERNAME] [w/PASSWORD] [t/TAG]…​
    e.g. update 2 n/James Lee e/jameslee@example.com

  • List Accounts : list-a [KEYWORD] [MORE_KEYWORDS]
    e.g. list-a Admin

  • Find Account : find-a KEYWORD [MORE_KEYWORDS]
    e.g. find-a James Jake

  • Delete Account : delete-a INDEX
    e.g. delete-a 3

  • New : new dist/DISTRICT auto/[Y/N] [v/INDEX]
    e.g. new dist/1 auto/n v/1

  • Fill

    1. fill (to list all draft incidents ready for filling)

    2. fill [INDEX] [p/CALLER_NUMBER] [desc/DESCRIPTION] (to fill specified incident report)
      e.g. fill 1 p/98984932 desc/This is a sample description for incident 1 in district 3.

  • Submit

    1. submit (to list all completed draft incidents ready for submission)

    2. submit [INDEX] (to submit specified incident report)
      e.g. submit 4

  • List Incidents : list-i

  • Find Incidents : find-i [op/KEYWORD(s)] [desc/KEYWORD(s)] [id/KEYWORD] [self]
    e.g. find-i op/alex yeoh desc/6 self

  • List Vehicles : list-v

  • Find Vehicles : find-v [dist/KEYWORDS] [vtype/KEYWORD] [vnum/KEYWORD]
    e.g. find-v dist/1 2 3