By: Team T16-B1 Since: Sept 2017 Licence: MIT

1. Introduction

Unable to keep track of all your deliveries? Unsure which parcel is a more urgent delivery? Did you ever wish there was a way you could easily find your delivery destination? Now with Ark, you no longer need to worry about late deliveries and getting lost. Leave the heavy thinking to us and just deliver away!

Ark is a delivery parcel manager with the ability to keep track of your delivery details. These details include recipient’s names, delivery due dates, locations, and tags. Ark is also able to help you plan out your delivery route by using google maps to help you get to your destination.

2. About

This user guide gives you an overall view of the features of Ark and how to get started using Ark. The user guide includes all of Arks functions and how to use them, as well as providing you examples for easy reference.

Ark assumes that you already have the postal codes of the delivery locations of every parcel and searches for addresses by postal codes only.

3. Quick Start

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

    Having any Java 8 version is not enough.
    This app will not work with earlier versions of Java 8.

  2. Download the latest [T16-B1][Ark].jar here.

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

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

    Ark Main Window

    Figure 3.1 : Ark’s Startup Window

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

  6. Here are some commands that you can try:

    • list : lists all parcels and expands the parcel list section in the main window.

    • clear` : clears the list of parcels.

    • delete3 : deletes the 3rd parcel shown in the current list.

    • exit : exits the app.

  7. You can refer to the Features section below for details of each command.

4. Layout

These are the main components of the Ark user interface that will help you to interact with Ark.

Ark Main Window Numbered

Figure 4.0.1 : This is the main window of Ark with each section color coded

  1. Menu Bar - Click on the options here to access the main or help menu.

  2. Command Box - You can type commands here.

  3. Results Box - This box gives displays information when you have entered a command.

  4. Browser Panel - This area displays the destination address of a parcel when you double-click (or select) the particular parcel in the Parcel List Panel (Refer to No. 6 below).

  5. Tab Panel - Click on the All Parcels tab to display the list of undelivered parcels. To view the list of delivered parcels, click on the Completed Parcels tab.

  6. Parcel Card - The details of a parcel is showed here.

  7. Parcel List Panel - The list of parcels in your inventory is showed here.

  8. Status Bar Footer - You can view a summary of the parcels in your inventory here.

4.1. Google Maps Browser

Ark has an in-built Google Maps browser section in the main window and can be used to show you the locations of the delivery addresses of each parcel. This feature will be automatically used whenever you type select into the command box or click on a Parcel Card, and will display a Google Maps search of the postal code of the parcel’s address in the browser section of the main window.

Ark Browser

Figure 4.1.1 : Selecting a parcel

Every time you select a parcel, the Browser Panel will show as the Parcel List Panel minimizes. As seen in figure 4.11.1 above, when the parcel belonging to Cornelia Meier, at index 4, is selected, the Parcel List Panel minimizes, showing the Browser Panel and it displays the delivery destination address of the parcel. In this case, Cornelia wants her parcel to be delivered to 10th Street Singapore 123114.

4.2. More About Parcel List Card

Ark Parcel Card Numbered

Figure 4.2.1 : Labelled Parcel Card

  1. Parcel Index - This is the index number of the parcel in the displayed list.

  2. Name - This is the name of the recipient of the parcel. You can read more in the Name section.

  3. Tracking Number - This is the tracking number of the parcel. You can read more about it Ark’s parcel tracking numbers in the Tracking Numbers section below.

  4. Phone - This is the phone number of the recipient of the parcel. You can read more in the Phone section.

  5. Address - This is the address to deliver the parcel to. The address must end with the postal code of the address. You can read more about postal codes in Ark in the #postal-code[Postal Code] section below.

  6. Email - This is the email address of the recipient of the parcel. You can read more in the Email section.

  7. Delivery Date - This is the delivery date of the parcel. The parcel should be delivered on dates prior to or on this date. You can read more in the Due Date section.

  8. Status - This is the status of the parcel in the delivery workflow. Read more about parcel delivery status in the Status section.

  9. Tags - These are the tags of the parcel. They are used to provide more information about a parcel’s contents. Read more about parcel tags in the Tags section.

4.2.1. Parcel Tooltip

Ark comes with a tooltip feature that allows you to view parcel details that are too long. Suppose you have entered a parcel with really long details into Ark. As seen below, John’s parcel has a delivery address that is too long, and a part of it has been replaced by ellipsis i.e. …​ as seen in figure 4.21.1 below.

ParcelWithLongInput

Figure 4.2.1.1 : Parcel with a long address

To view the full delivery address, we simply mouseover his address and the full details of his address will appear as a tooltip. This can be seen in figure 4.22.2 below.

mouse over address

Figure 4.2.1.2 : Tooltip to show more of John’s address

4.3. GUI tab mechanism

To help you organise between the parcels you have delivered and the parcels you have delivered, Ark provides you two lists, one containing the parcels you have yet to deliver, and the other, the parcels that you have already delivered.

When you launch the application, Ark will show the list of undelivered parcels in your inventory. To view the list of delivered parcels, you can click on the Completed Parcel tab located on the Tab Panel of Ark.

completed parcel list

Figure 4.3.1 : Clicking on Completed Parcel tab

As seen above in figure 4.3.1, the list has changed to the list of parcels that have been delivered. To revert back to the list of parcels that have not been delivered, simply click on the All Parcels tab.

Parcels that have a COMPLETED status will be added to the list of delivered parcels directly while Parcels that do not have a COMPLETED status will be added to the list of undelivered parcels.

4.4. Overdue Parcels Popup Window

Every time you startup Ark, if you have any parcels with the status OVERDUE in the parcel list, a separate window will popup notifying you of the number of overdue parcels that are in the list. The popup window will show for 7 seconds before closing itself. You can also close the window manually by clicking the x at the top right of the window. Figure 4.4.1 below is an example of what the popup window looks like:

Ark Popup Window

Figure 4.4.1 : Overdue Parcels Popup Window

5. Parcel Fields

5.1. Name Field: Name of Parcel Recipient

The Name field represents the name of the parcel’s recipient. It can contain the name of the organisation or the person that you are delivering to the parcel to.

The Name field will only allow alphanumeric characters separated by whitespace. e.g. John Doe; 8 Noodles at Shangri-La’s Rasa Sentosa Resort & Spa
Non-alphanumeric entries will be rejected by Ark. e.g. John Doe!

5.2. Tracking Number Field: Tracking Number of Parcel

The Tracking Number field represents the tracking number of the parcels.

This field allows you to add tracking numbers to your parcels. Tracking numbers allow you to keep track of the parcels that are in your possession. This field is important because a single person can have many parcels belonging to him. Hence, you can use our tracking number system to differentiate between the different parcels that are allocated to a single recipient. You can also use tracking numbers to identify specific parcels.

Ark only supports tracking numbers for registered articles managed by SingPost at this instance. These numbers include two R`s followed by nine digits and ending with `SG. e.g. RR123456789SG
You can read more about SingPost Registered Article tracking number here.
Tracking numbers that do not conform to the above format will be rejected e.g. rr123545679sg; RR#12345678SG;
You can add multiple parcels with the same tracking number. This allows you to reuse tracking numbers in the event when the number of parcels in your inventory exceeds the number of tracking numbers. There has been instances of this occurring during festive seasons such as Christmas.
The team is working on adding support for more types of tracking numbers such as those of UPS and FedEx in the future.

5.3. Phone Field: Phone of Parcel Recipient

The Phone field represents the phone number of the parcel’s recipient. It can contain the phone number of the organisation or the person that you are delivering to the parcel to.

You can only assign a single phone number to a each parcel. You may omit this field in your entry, preferably only when it is not provided.

The Phone field will only allow you to add phone numbers with 3 or more digits. e.g. 1234 5678; 1122 2344 5678;
This is to allow you to add overseas numbers per the request of the parcel’s recipient.
Phone numbers shorter than 3 digits will be rejected. e.g. 4, 12;

5.4. Address Field: Destination Address of Parcel Delivery

The Address field represents the destination address of your parcel. This field contains the address that you should deliver your parcel to.

The Address field will only allow you to add an address with at least a single character as the text representation of the address, and appended with a valid postal code, separated from the text representation of the address with space(s). e.g. 123, example street #05-26 S012345;
Invalid address entries include the following: e.g. 123, example street #05-26 You can learn more about valid postal code entries below.

5.4.1. Postal Code: Postal Code of Delivery Address of the Parcel

Ark can store the postal address of locations in Singapore. It only accepts values of s or S followed by 6 digits. The postal code of a parcel is used to query Google Maps when the select command is executed or when a parcel in the Parcel List Panel is clicked. Invalid values would include the following: 213661; s#11122;

Postal codes must be appended to the end of the address text. e.g. Suppose you are adding a new parcel into Ark and entered add …​(Some info)…​ a/NUS School of Computing, COM1, 13 Computing Drive, S117417 …​(More info required in the add command)…​. In this case, S11417 is the postal code of the above address and is appended to its respective address, separated by a space.

If you did not append the postal code of the address at the end of your address, Ark will not recognize your address input as a valid input and would give you an invalid input message.
Presently, the PostalCode field still does a very relaxed validation and does not completely ensure that the postal code exists even though it might meet the criteria above. The team is working on producing a database of postal codes in Singapore. In the meantime, we encourage users to take additional precautions when entering the postal codes into Ark and ensure that the postal code inputs are valid.

5.5. Email Field: Email of Parcel Recipient

The Email field represents the email contact of the parcel’s recipient. It can contain the email of the organisation or the person that you are delivering to the parcel to.

The Email field will only allow alphanumeric or periods characters separated by an @ character. e.g. John@example.com Invalid Email entries include the following: e.g. John_Doe@example.com; JaneDoe.example.com;

5.6. Due Date Field: Due Date for Parcel Delivery

Delivery Date is used to indicate the delivery date that the parcel must be delivered by. The dates are only accepted if they are in the valid format DD-MM-YYYY or understandable by Ark.

Ark is able to recognise various forms of dates as shown in the table below but the dates in the Ark are formatted as DD-MM-YYYY. However, invalid inputs such as a phone number or symbols still will be rejected.

Current date as of writing is 12 November 2017.

User input Date parsed by Ark

01-01-2017

01-01-2017

01/01/2017

01-01-2017

01.01.2017

01-01-2017

01-01-17

01-01-2017

First day of 2017

01-01-2017

The day before yesterday

10-11-2017

Yesterday

11-11-2017

Today

12-11-2017

Tomorrow

13-11-2017

The day after tomorrow

14-11-2017

Three days from now

15-11-2017

Four days later

16-11-2017

Seventeenth of November

17-11-2017

This Friday

17-11-2017

Next Friday

24-11-2017

Christmas Eve

24-12-2017

A week before Christmas Eve

17-12-2017

A year from now

12-11-2018

Friday of the second week of January

Query too complicated, date defaults to today

123456789

Invalid date error shown

!@#$%^&*()

Invalid date error shown

The parcel list is maintained in sorted order by comparing their delivery dates, with the earliest on top.

5.7. Status Field: Delivery Status of Parcel

Status is used to indicate the current delivery status of a parcel. A parcel can have 4 possible delivery status and listed below is a description of these Status values.

Status Description

PENDING

This means that the parcel has not been delivered and has not passed the date it is supposed to be delivered by.

DELIVERING

This means that the parcel is currently working being delivered to its destination address.

COMPLETED

This indicates that the parcel has been successfully delivered to its destination.

OVERDUE

This state indicates that the parcel has not been delivered and has passed its due date.

To input a Status, you can type case-insensitive formats of the above Status. e.g. pending or Pending are valid inputs to add a PENDING Status.

Values other than the above values will be rejected. e.g. PROCESSING, PROCESSED;

5.8. Tags Field: Delivery Tags of Parcel

Tags are used to indicate how the parcel should be handled. Tags can contain one or more of the following Tag:

Tag Description

FROZEN

This means the parcel should be refrigerated as its contents are temperature sensitive.

FLAMMABLE

This means that the parcels' contents are highly flammable and should be kept away from heat.

HEAVY

This indicates that the parcel is heavy and may require additional manpower to deliver.

FRAGILE

This state indicates that the parcels' contents can be broken easily and requires additional care when handling.

To input a Tag, you can type insensitive formats of any of the above Tags. e.g. frozen or Frozen are valid inputs to add a FROZEN Tag.

Values other than the above values will be rejected. e.g. friends, colleagues. If your use of Ark requires more tags to be made available, please contact our team and we will see to your request.

6. Features

Command Format

  • Words in UPPER_CASE are the parameters to be supplied by the user e.g. in add #/TRACKING_NUMBER, TRACKING_NUMBER is a parameter which can be used as add #/RR000000000SG.

  • Items in square brackets are optional e.g /TRACKING_NUMBER [t/TAG] can be used as /RR000000000SG t/fragile or as #/RR000000000SG.

  • 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/fragile, t/flammable t/frozen etc.

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

6.1. Viewing help : help

Whenever you are unsure of Arks functions or commands, you can type help into the command box. Ark will then open this user guide in a new window for you to view.

Format: help

6.2. Adding a parcel: add

Adds a parcel to Ark
Format: add #/TRACKING_NUMBER n/NAME [p/PHONE_NUMBER] [e/EMAIL] a/ADDRESS d/DELIVERYDATE [s/STATUS] [t/TAG]…​

A parcel can have any number of tags (including 0) A parcel can only have one of four STATUS input. i.e. PENDING, DELIVERING, COMPLETED and OVERDUE. If there is no STATUS input, it defaults to PENDING

Examples:

  • add #/RR000000000SG n/John Doe p/98765432 e/johnd@example.com a/John street, block 123, #01-01 S123121 d/01-01-2001 s/DELIVERING

  • add #/RR000000000SG n/Betsy Crowe t/frozen d/02-02-2002 e/betsycrowe@example.com a/22 Crowe road S123123 p/1234567 t/fragile

Parcel address must be appended with their postal code in the form s or S followed by 6 digits. i.e. S123661 Failure to do so will result in an invalid address message from Ark. Parcel Tracking numbers presently support only tracking numbers for registered articles managed by SingPost. These numbers include two R`s followed by nine digits and ending with `SG.
Support for other delivery companies will come in future patches.
If not included in the add command, the default value of both the phone and email field is NIL while the default value for the status field is PENDING.
Upon successful execution of the add command, the latest parcel added will be selected.

6.3. Add Multiple Parcels into Ark from a Storage Fiel: import

You can import parcels into Ark using the import feature. This feature works with valid save files of Ark. To use this feature, you must first copy/move the save file that you want to import into the /data/import/ folder of Ark’s home directory. Then you can type the following command into the CommandBox, import , followed by the name of your file.

Ark will only import files that are stored in the .xml format.
Your file name is should only contain alphanumeric or underscore characters. e.g. ark_save, ark_save1;
Files name that contain characters other than alphanumeric or underscore characters will be rejected. e.g. ark#1;
Do not include the file type in your file name. The following inputs for the file name will be rejected. ark_save.xml;

Examples:

  • import ark - This will import parcels stored in data/import/ark.xml into the current instance of Ark

  • import ark_save - This will import parcels stored in data/import/ark_save.xml into the current instance of Ark.

Format: import FILE_NAME

6.4. Listing all parcels : list

Shows a list of all parcels in Ark and expands the Parcel List Panel section in the main window. The Parcel List section is scrollable and shows you all the information of a parcel. You can see an example in the figure 6.4.1 below.

Ark Parcel List

Figure 6.4.1 : The list command displays the list of all the parcels in Ark

Format: list

6.5. Editing a parcel : edit

Edits an existing parcel in Ark.
Format: edit INDEX [#/TRACKING_NUMBER] [n/NAME] [p/PHONE] [e/EMAIL] [a/ADDRESS] [d/DELIVERY_DATE] [s/STATUS] [t/TAG]…​

  • Edits the parcel at the specified INDEX. The index refers to the index number shown in the last parcel listing. 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 parcel will be removed i.e adding of tags is not cumulative.

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

Examples:

  • edit 1 p/91234567 e/johndoe@example.com
    Edits the phone number and email address of the 1st parcel to be 91234567 and johndoe@example.com respectively.

  • edit 2 n/Betsy Crower t/
    Edits the recipient’s name of the 2nd parcel to be Betsy Crower and clears all existing tags.

  • edit 1 d/03-03-2003
    Edits the delivery date of the 1st parcel to be 03-03-2003.

Upon successful execution of the add command, the latest parcel edited will be selected.

6.6. Locating parcels by name: find

Finds parcels whose recipient name 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 recipients’s 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 parcel belonging to people with names Betsy, Tim, or John

6.7. Deleting a parcel : delete

Deletes the specified parcel from the Ark.
Format: delete INDEX

  • Deletes the parcel at the specified INDEX.

  • The index refers to the index number shown in the most recent listing.

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

Examples:

  • list
    delete 2
    Deletes the 2nd parcel in the Ark.

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

6.8. Selecting a parcel : select

Selects the parcel identified by the index number used in the last parcel listing and expands the Browser Panel section in the main window. The Browser Panel section will then show a google map search of the selected parcel’s delivery address (postal code). You can see an example in the picture below.

Ark Browser

Figure 6.8.1 : The Select command will display the location of the selected parcel

Format: select INDEX

You can also select a parcel by mousing over and clicking on the specific Parcel Card in the Parcel List Panel.

  • Selects the parcel and loads the Google map page showing the delivery location of the parcel at the specified INDEX.

  • The index refers to the index number shown in the most recent listing.

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

Examples:

  • list
    select 2
    Selects the 2nd parcel in the Ark. Expands browser section.

  • find Betsy
    select 1
    Selects the 1st parcel in the results of the find command.

6.9. Selecting a tab : tab

Selects the tab identified by the index number and switches the tab shown in the Parcel List Panel. The selected tab will then display its respective parcel list according to its tab title.

The "All Parcels" tab shows all the parcels in Ark with the status of PENDING, DELIVERING, OVERDUE only. The "Completed Parcels" tab shows all the parcels with the status COMPLETED only.

Format: tab INDEX

You can also select a tab by clicking on the specified tab you wish to switch to in the Parcel List Panel.

Pressing the ← and → arrows when selecting a tab will switch to the tab in that respective direction

  • Selects the tab of the specified INDEX and switchs the current tab shown to the new selected tab.

  • The index must be within the number of tabs shown.

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

Examples:

  • list
    tab 2
    Selects the second tab "Completed Parcels" in the Parcel List Panel and displays its respective parcel list.

  • tab 1
    Selects the first tab "All Parcels" in the Parcel List Panel and displays it respective parcel list .

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

6.11. Undoing previous command : undo

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

Commands that can be undone: those commands that modify Ark’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)

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

6.13. Clearing all entries : clear

Clears all entries from Ark.
Format: clear

6.14. Exiting the program : exit

Exits the program.
Format: exit

6.15. Autocomplete

Trying to type in long commands can be quite a hassle. That is why Ark comes with tab autocompletion which is able to help fill in commands as well as the prefixes for you without requiring you to fully type out the command with the needed fields. Ark autocompletion is smart and knows exactly what field you need, all you have to do is press Tab and let Ark handle the rest!

Autocomplete for commands:
To make use of the autocomplete feature for commands, simply type in the first few letters of the command you want to use:

autocompleteWithStartOfAddCommand

Figure 6.15.1 : Fill in the first few letters of the command you want to use. In this case, we want to use the Add command, so we enter a into the text field

now press the Tab key:

autocompleteWithFullAddCommand

Figure 6.15.2 : After Tab is pressed Ark will fill in the command for you

Ark will then fill in the rest for you if there is a match.

If there is more than one possibility for the autocompletion, Ark will display the possible options to you as shown in the below.

autocompleteWithEditCommandCycle

Figure 6.15.3 : If there are multiple autocomplete options, the options will be displayed in the result window

In this case, you can press tab to cycle through the different options available.

autocompleteWithExitCommandCycle

Figure 6.15.4 : Pressing Tab again will cycle to the next matching command

Autocomplete for prefixes:
For commands that require prefixes, you can press Tab after filling in the command word. Ark will bring you to the next missing prefix for you to fill in. After this, you can then press tab to cycle through the list of prefixes.

autocompleteWithFullAddCommandAndOnePrefix

Figure 6.15.5 : After filling in the command into the text field, pressing Tab will bring you to the first missing prefix

autocompleteWithFullAddCommandAndOnePrefixCycle

Figure 6.15.6 : Pressing Tab will cycle to the next missing prefix

Alternatively, you can also enter the first letter of the prefix you want before you press Tab and Ark will fill in the / character for you.

autocompleteWithFullAddCommandAndPartOfPrefix

Figure 6.15.7 : Fill in the command you want along with the first letter of the prefix you want

autocompleteWithFullAddCommandAndOnePrefix

Figure 6.15.8 : Pressing Tab append the / character for you

After you have chosen the prefix you want, simply enter in the details as needed.

autocompleteWithFullAddCommandAndOnePrefixFilled

Figure 6.15.9 : Fill in the needed details as per normal

After you are done entering the needed details of the prefix, press Tab to move on to the next prefix. Note that if your input ends with the first character of a prefix preceded by a space (e.g " n"), you will need to press Space before you press Tab to get the outcome you want.

autocompleteWithFullAddCommandAndOnePrefixFilledNext

Figure 6.15.10 : Pressing Tab will fill in the next missing prefix

Autocomplete for indexes:
For commands that require indexes, you can press Tab after filling in the command word. Ark will then allow you to cycle through the indexes available by pressing Tab

autocompleteWithStartOfSelectCommand

Figure 6.15.11 : After filling in the command into the text field, pressing Tab will bring you to the first available index

autocompleteWithStartOfSelectCommandCycle

Figure 6.15.12 : Pressing Tab will cycle to the next available index

Examples:

  • a + Tab (auto-completes with add in the command line input)

  • e + Tab + Tab (cycles to exit command)

  • edit + Tab + Tab (auto-completes with edit 1 on the first tab and then cycles to edit 2 on the second tab)

  • add + Tab + Tab (auto-completes with edit #/ on the first tab and then cycles to edit n/ on the second tab)

If you try to move on the the next prefix by pressing Space followed by Tab, Ark will still detect the prefix as missing. Thus, the next prefix filled might be the same as the current prefix.
e.g If the current text in the text field is add #/ you press Space followed by Tab, the result you will get is add #/ #/ since the value of #/ has not been filled in yet.

6.16. Saving the data

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

6.17. Backing up the data

Ark data are backed up in the hard disk automatically at the start of every session of the program.
There is no need to back up the data manually.
The backup file is appended with -backup.xml and is stored in the same folder as the main storage file.

To load the backup file into Ark, you can perform the following actions:

  1. Firstly, open the /data/ folder in the home directory of Ark.

  2. Then, copy the backup file, and paste the copied file into your /data/import directory. i.e. ark-backup.xml

  3. Open the Ark Application. If Ark fails to start as a result of corrupted data in your Ark save file, simply delete the corrupted save file and restart the Ark application.

  4. Finally, import the backup save file into Ark by using the import command by typing import (back-up file name) . i.e. import ark-backup.xml

Alternatively, you can delete your original save file and rename your backup file to the name of your original save file. However, this approach will result in data being loss if your original save file was not corrupted and contains valuable data.

If Ark is unable to read your save file for reasons such as the save file being of an invalid format or if your save file was missing (gasp), Ark would not create a backup file for you on start up.

6.18. Maintaining a Sorted List

The list of parcels stored in Ark is maintained to be sorted according to the delivery date of the parcels, with the earliest delivery date at the top. This allows the more pertinent deliveries to be shown quickly.
The list is sorted whenever there is a change in the list that may potentially disrupt the order of the list so that the user does not have to manually do so.

6.19. ArkBot: Telegram Bot Interface for Ark

6.19.1. An Overview

As a desktop application, isn’t it rather cumbersome for a delivery man to check and update information on the go, when he is making his deliveries? We thought so to. As such we developed a Telegram Bot Interface for Ark so that the delivery man would be able to conveniently see which deliveries he has remaining and their addresses. Furthermore, he will be able to mark the deliveries as complete easily from the convenience of his phone.

Like all Telegram Bots, each command must be prefixed with a / character. So if I were to want to trigger the help command, I would send /help to ArkBot. The command formats are identical to that of Ark to make things easy to recall.

6.19.2. Configuring ArkBot

Telegram Bots require an Authorization Token which make them unique. To make the ArkBot respond only to your Ark software, head here to learn how to retrieve an Authorization Token from Telegram’s Botfather.

The following steps illustrate how you should retrieve and configure the Authorization Token:

  1. Retrieve Authorization Token from Botfather.

    • Your token should look something like this: 458231237:AAEPeghjklUxY7GHnYiJ5c0y-IldALLI0FE

  2. Initialize [T16-B1][Ark].jar to generate the default configuration file, config.json.

  3. Open config.json with your favourite text editor.

    • Some common text editors include Notepad or Vim.

  4. Change the value of the botToken field as shown in Figure 6.19.2.1.

  5. Restart Ark and you should be all set!

sampleConfigFileSelected

Figure 6.19.2.1 : Sample Configuration File with Telegram Bot Authorization Token field highlighted.

After which, enter the authorization token into the config.json file that is created in the same folder you placed the Ark software executable file. This token is especially important as anyone with access to it will be able to access the information that is sent and received by the bot.

6.19.3. ArkBot Commands

Here the commands that are available in ArkBot.

Command Description

/all #/TRACKING_NUMBER n/NAME [p/PHONE_NUMBER] [e/EMAIL] a/ADDRESS d/DELIVERYDATE [s/STATUS] [t/TAG]…​`

Adds a parcel.

/list

Lists uncompleted parcel deliveries.

/find KEYWORD [MORE_KEYWORDS]

List uncompleted parcels with keywords in names.

/delete [Parcel Index]

Deletes a parcel.

/undo

Undo a command.

/redo

Redo a command.

/complete [Parcel Index]

Marks a parcel as completed.

/complete

Activates listen mode.

/cancel

Cancels listen mode.

/help

Brings up help dialogue with information on commands.

6.19.4. ArkBot Listen Mode

If /complete is entered without a parcel index, ArkBot will enter listen mode. In listen mode, ArkBot will wait for an image QR code to be sent. The QR code must contain details of the parcel and the parcel must be present in the Ark’s list of parcels.

QR Sample Interaction

Figure 6.19.3.1: Sample interaction of sending QR code to ArkBot

As shown in Figure 6.21.3.1, upon typing /complete, ArkBot will prompt the user for an image. If ArkBot is able to recognise the parcel, it will reply with the parcel’s previous details as shown and mark it as completed on Ark.

If ArkBot is not in listen mode and a QR code with parcel details are sent, ArkBot assumes that the user is trying to read the information on the QR code and displays it.

7. 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 Address Book folder.

Q: My save file is corrupted. How can I restore it?
A: The save file cannot be restored. You can instead load up a backup of your save file. Please refer to the Backing up the data section.

Q: Some parcel details are too long and they became cut off with ellipsis i.e. …​ . What do I if I want to see the full information in these details?
A: Please refer to the Parcel Tooltip section .

Q: I want to add parcels from a save file on another computer to my own instance of Ark without having to overwrite my own copy of Ark. How can I do this?
A: Copy the save file on the other computer into your computer. Store this save file in the /data/import directory of your Ark application. Then launch the Ark application and import your the copied save file into Ark. Please refer to the Import Command section if you are unfamiliar with using the import command.

8. Command Summary

Command

Description

Compulsory fields

Optional fields

Example usage

Add

Adds a new parcel to Ark

#/TRACKING_NUMBER
n/NAME
p/PHONE_NUMBER
e/EMAIL
a/ADDRESS
d/DELIVERY_DATE

s/STATUS
t/TAG

add #/RR906906906SG n/James Ho p/22224444 e/jamesho@example.com a/123, Clementi Rd, S123465 d/12-12-2012 s/pending t/flammable

Clear

Deletes all parcels from Ark

clear

Delete

Deletes a particular parcel from Ark

INDEX

delete 1

Edit

Edits the details of a particular parcel in Ark

INDEX

#/TRACKING_NUMBER
n/NAME
p/PHONE_NUMBER
e/EMAIL
a/ADDRESS
d/DELIVERY_DATE
s/STATUS
t/TAG

edit 2 #/RR000000000SG n/James Lee e/jameslee@example.com

Find

Searches Ark for a parcel containing a particular keyword

KEYWORD

ADDITIONAL KEYWORDS

find John

List

Lists all parcels currently in Ark

list

Help

Opens the help window

help

Select

Selects a particular parcel in Ark

INDEX

select 1

History

Displays the history of previous commands executed in Ark

history

Undo

Undoes the latest command executed in Ark

undo

Redo

Redoes the latest undone command in Ark

Redo

Import

Imports one or more parcels from an xml file

FILE_NAME

import ark_save

9. Patch Notes

9.1. Features added in v1.0

In version v1.0, users will be able to:
* Add Parcels to Ark. * List Parcels in Ark. * Delete Parcels in Ark by list index. * Edit Parcels in Ark. * Find Parcels in Ark by name. * Undo commands * Redo commands * Display command History

9.2. Features added v1.1

In version v1.1, users will be able to:

  • Have their data backed up automatically when Ark is launched.

  • Delete tag from all parcels in Ark.

9.3. Features added in v1.2

In version v1.2, users will be able to:

  • Work with parcels instead of persons.

  • Add and edit the tracking numbers of parcels.

  • Use Tab to autocomplete basic commands.

  • Delete tag command deprecated.

9.4. Features added in v1.3

In version v1.3, users will be able to:

  • Add one of four possible Status to parcels. i.e. PENDING, DELIVERING, COMPLETED and OVERDUE.

  • Import parcels stored in an Ark storage file in xml format into Ark.

  • Have Ark maintain a sorted list of parcels according to when they need to be delivered.

  • Use Tab to cycle through possible commands if there are multiple options available.

9.5. Features added in v1.4

In version v1.4, users will be able to:

  • Click on tabs to select between two lists, one of which contains undelivered and the other, delivered parcels

  • Add parcel-related tags to inform delivery personnel on additional precautions to take while delivering a parcel.

  • Use Tab to fill in the next prefix for add command.

9.6. Features added in v1.5rc

In version v1.5rc, users will be able to:

  • View a tooltip of parcel details when they mouseover the detail. i.e. address

  • Use Tab to cycle through indexes and prefixes for all commands that require them.

9.7. Features added in v1.5

In version v1.5, users will be able to:

  • Use Telegram Bots to interface with the Ark Software.

  • Upload QR codes of delivery parcels to mark them as completed.

10. Features Coming in v2.0

In Ark v2.0, the delivery vendor will be able to do the following:

  • Filter Parcel by tags

  • Know the shortest path from one address to a delivery address.

  • Find the shortest path from the current location to a delivery address.

  • Find customer’s Parcel by TRACKING_NUMBER

  • Find customer’s TRACKING_NUMBER

  • Sort by delivery deadlines for the parcel

  • Sort by TRACKING_NUMBER

  • Sort by customer’s NAME

  • Sort by customer’s PHONE

  • Sort by customer’s ADDRESS

  • Update status of Parcel

  • Color code ParcelCard based on impending deadlines.

  • Generate the optimal route for the day’s deliveries, based on shortest time, shortest distance travelled or most

  • Archive completed deliveries parcels delivered.

  • Add multiple parcels by importing a XML file

  • Store the sender’s and receiver’s details (i.e. Name, Phone, Email Address, Address)

  • Autocomplete input commands.

  • Be informed of overdue parcels.

  • Be informed of parcels that can be delivered at a specific location.

  • Assign levels of importance to deliveries.