The BORG Calendar and Task Tracker HELP

This Help file does not list every single feature of BORG. Anything that BORG does that is not listed here is either something obvious, or something that is mistakenly missing from this help.

The Database Files

When BORG starts for the first time, it prompts for the location to store its database files. BORG uses 3 files, borg.jdb for storing calendar appointments, mrdb.jdb for tasks, and addr.jdb for address/contact info. These files are in a binary format. I would suggest backing up these files every so often if you use BORG, in case of disk failure (not because BORG is buggy :)

The database files are not simple data stores. These files are formatted to be highly resistant to corruption from disk space overruns and computer crashes.

Internationalization

BORG supports Locales (regional settings) as of release 1.3. The Locale can be switched from the Options screen. Once a new Locale is chosen, a restart is required before the new Locale is used. The date formats, month names, and weekday names are supported for all Locales listed. However, the majority of text strings in BORG come from a properties file. As of release 1.3, a Spanish property file has been created. So, except for this Help file and some README files, BORG supports Spanish. Translations to other languages would only require a translated version of the borg_resource.properties file that comes in the BORG jar file.

The Main Screen

The BORG main screen shows a single month at a time. The Navigation buttons appear on the bottom of the screen and are intuitive (Let me define intuitive. When I say intuitive, it means that I am describing something that I haven’t documented yet, and might not document, because it seems to be obvious enough. For example the "next" button on the main month window).

If the current month is being viewed, the current day will appear dark pink. Weekends are shaded slightly darker than weekdays. Days marked as holidays appear the same color as weekends. Days can also be marked as vacation days, and if so, will appear green.

To add/remove/update appointments for a given day, just click on the button containing the date.

Week View

To the right of each week is a button that will produce a "week view" when pressed. The week view is not interactive. It is a grid view of the week that plots the scheduled appointments for each day according to their start time and duration. The start and end range of the grid is user tunable. The week view can be sent to a printer via a menu option.

Editing appointments

When the appointment editor first appears (after clicking a date button), all of its fields are reset to default values and the text "***** NEW APPT *****" appears in the upper portion of the window. When this text appears, it means that the window is editing a new appointment that can be saved by hitting the Save button.

If the day being edited has existing appointments, they can be edited by clicking the corresponding appointment in the appointment list. The Save button saves any data for the appointment being edited.

Most of the fields in this window are intuitive and require no special documentation. Some items bearing explanation are:

If the "No specific time" checkbox is selected, no time string will appear in the main month display or print output and the appointment will be considered a non-scheduled appointment or "note".
The duration pulldown is new to Release 1.1 and affects the week view.
The color pulldown alters the appointment color on the main month view, and in the color printout.

To Do's

If the To Do checkbox is selected, the appointment will be marked as a To Do. It will appear on the To Do list window, and can be marked as done from the To Do window also.

Repeating Appointments

The frequency pulldown allows you to set the frequency of an appointment that repeats. The times field should be set to the number of repeats desired.

When deleting repeated appointments, Delete One Only and Delete buttons offer the choice of either deleting just the one occurrence of the repeat on the current day being edited, or all of the occurrences.

FYI - repeats are only added to the calendar for 2 years from the present date. So if you repeat something yearly for 1000 years and try to look ahead to the year 3000, you will be disappointed.

Repeating To Do's

Repeating To Do's will appear as multiple times on the month view windows (as determined by the frequency and Times). However, they will only appear once on the To Do list - starting with occurrence number one. If a repeating To Do is marked as done on the To Do list, the NEXT occurrence of the To Do will then be placed on the To Do list - this is done until the last occurrence has been marked as done.

Vacation, Half Day, Holidays

The vacation, half day, and holidays check boxes are used to mark the day in a different color on the main month view.

BORG currently can add certain US and Canadian holidays. This is an option from the preferences screen. BORG will also "guess" as to whether or not a US holiday should be marked using the holiday color or just normal day color. This is based on whether or not the holiday usually causes a day off from work in the US. So, for example, New Year's Day would be marked in weekend color, but Valentine's Day is not.

Whether or not you use the US holiday feature, if a certain day is a holiday for you, you can add an appointment with the name of the holiday and mark the Holiday checkbox.

Private Appointments

Appointments marked as private using the private checkbox are processed differently from regular appointments in two ways:

1. The appointments only appear in the main month view and print output if the Options/Show Private checkbox is selected from the Options menu. In this way, Private appointments can be hidden when the calendar is used in a public setting. Example uses for private appointments would be to record certain doctor's appointments or to keep a log of your illnesses or any other private non-work related items.

2. Private appointments are encrypted in the borg.jdb file. Although anyone running BORG (WITH ACCESS TO YOUR FILES) can access even private appointments from a borg.jdb file, a casual snooper (like a sys-admin) who only gains access to the borg.jdb file and scans it for ascii text, will not be able to decode the private appointments.

The To Do List

The To Do list is accessed from the Action/To Do menu choice from the main Month screen. It also pops up upon start up. This list shows all appointments marked as To Do's that have not been marked as done. To Do's can be marked as done from the To Do window menu. There are 2 options to pick from when marking To Do's as done (from the Action menu). The "No Delete" option, removes the appointment from the To Do list, but leaves it on the calendar. The Delete option removes it from the calendar also (unless the todo has more repeats).

The To Do list can also be printed using its Action/Print List menu choice.

Pop-Up Reminders

These appear 3 hours before appointments (and 30 minutes afterwards if you start BORG up within 30 minutes after an appointment). If you are starting BORG up within 30 minutes after an appointment, BORG figures that you may have forgotten about it. These default values can be changed from the options window.

Around 15 minutes before an appointment that has a pop-up displayed, BORG will make an audible beep noise, and will try to bring the pop-up window to the front to remind you about the appointment. This will continue every 5 minutes until you dispose of the pop-up. These default values can be changed from the options window.

Email Reminders

BORG can be set to send an email reminder each day for the next day's appointments. The options menu is where you can enable email reminders. If this feature is turned on, BORG will send out a single email reminder of the next days appointments once per day.

The Task Tracker

The Task Tracker is used to keep track of various tasks with defined start and end dates, different statuses, descriptions, and resolutions.

It is up to the user to decide if something should be a task or regular appointment. Appointments can be used to hold simple tasks that require no special tracking, such as "pay mortgage" or "take out garbage". The task tracker is meant for longer running, more complex tasks, such as "code new BORG feature", "design new widget", or "re-floor bathroom" - things that have multiple steps to check off, that require documentation of a resolution, and/or have "sliding" due dates.

The main Task Tracker window shows a scrollable list of tasks. The Task Tracker Action menu can be used to add, update, and delete tasks. The radiobuttons on top can be used to show just open or closed tasks, tasks that are done but have not been recorded for performance review (PR), or all tasks.

A filter string can be typed in the text entry field. When the filter button is pressed, only tasks with text containing the filter string will be shown.

Tasks can also be filtered according to their category, using the category pull-down choice box.

Tasks with due dates will show on your calendar.

The task tracker is also designed to keep track of tasks done for later recording on your list of accomplishments at work. This is called performance review (PR). It is hoped that most BORG users do not have to deal with this kind of hell. One of the things that BORG can be used for is to figure out what you have done during the year at performance review time - and to make sure you can keep things that you have already claimed credit for apart from things that you have not. Some users will not identify with this. Others may be groaning in sympathy at this point.

Once added, tasks follow a set of states, which are user-configurable in BORG.

The different default task types are shown below:

TASK Type	Description	Allowable States (in no special order)
TASK	Normal task. Just something to do.	OPEN, IN_PRG, CLOSED, DEF, PR
ISSUE	An issue to be figured out	OPEN, IN_PRG, CLOSED, DEF, PR
CODE	Coding to be done	OPEN, DEV, TEST, DEF, PR, CLOSED
DOC	Document to write	OPEN, IN_PRG, RVW, BL, CLOSED, DEF, PR

State	Meaning
OPEN	Not started yet
IN_PRG	In progress
DEV (for CODE)	Coding started
TEST (for CODE)	Coding done, testing started
PR	Task is done, but not yet recorded in the next PR(or performance review, or whatever nonsense your company does)
CLOSED	Task is complete
RVW (for DOC)	Document has been written. Is out for review.
BL (for DOC)	Document is “baselined”, meaning that is is approved. There still may be busy work required before the document is official.
DEF	Deferred – to be worked on at some future time. Not being worked on now.

If you don't like the default task types and states, you can change them. Please see the section below on Editing Task Types and States for more info. The default task states are used by the author and provide a good example of what can be done. There is no problem if you discard them all and replace them with your own.

When editing tasks, much of the functioning of the editor window is obvious. However:

The PA (person assigned) and Pri (priority fields) don’t really do anything except hold data. Use them as you like.
The standard BORG check boxes (subtasks) for CODE and DOC tasks might not apply to most users (especially those who aren’t developers). Just as an FYI, here are what the CODE checkboxes were created for:
- Delta = put code under source control
- Blue Print = a date tracking blue print has been filled out – see ISO 9000 for more info – see Dilbert for more info on ISO 9000
- MR = a modification request has been issued (or change request, or whatever your build system might require to relate code to features/problems)
- Code Insp = code inspection done.
Here are the DOC checkboxes:
- DocNum = an official document number has been established
- VGs – viewgraphs have been prepared for the document presentation meeting
- Blueprint (see above)
- MR (see above)
- Library = the document has been officially filed in some library.

The check boxes don’t affect any processing. However, the values are remembered on a per-task basis. So use them as you like.

Subtasks

For each task, 5 subtasks can be defined by the user. These 5 check boxes can be used to keep track of anything the user needs to take care of as part of the overall task. For example, if a task is to refinance your home, subtasks might be "get appraisal", "fax pay stubs", "mail application", "final closing", "new payment book rcv'd". The subtasks just are there to be checked-off. They do not affect any other processing.

Each task type can also have up to 5 type-specific subtasks that are common to all tasks of a particular type.. The type-specific subtasks can be altered by the user (as of Release 1.0). See below.

Editing Task Types and States

The default task tracker states defined above are probably adequate for some users and inadequate for others. the user has the capability to edit the list of task types and state transitions in the task tracker. To edit the task types and states, first use the option from the task tracker options menu that exports the task type information to an XML file. Save this file in case you need to revert back to it.

The format of this file is XML - but simplified XML. The simple XML parser in BORG cannot handle comments, attributes, prologs - so the file should just contain XML elements as described below.

The XML contains a root element. Under the root are elements for each task type. To add a new task type, just add an element under the root.

Inside each task type element, the allowed state transitions are described. For each allowed state, there is an element. This element should contain an empty element for each state that can be reached from that state. Up to 5 CB elements can be present per type. These are the type-specific check boxes.

Here is the default subtree for the TASK type:

<root>
    <TASK>
        <OPEN>
            <IN_PRG/>
            <DEF/>
        </OPEN>
        <DEF>
            <OPEN/>
            <IN_PRG/>
        </DEF>
        <IN_PRG>
            <DEF/>
            <PR/>
            <CLOSED/>
        </IN_PRG>
        <PR>
            <CLOSED/>
        </PR>
        <CLOSED>
            <IN_PRG/>
        </CLOSED>
    </TASK>
    <ISS>
        <OPEN>
            <IN_PRG/>
            <DEF/>
        </OPEN>
        <DEF>
            <OPEN/>
            <IN_PRG/>
        </DEF>
        <IN_PRG>
            <DEF/>
            <PR/>
            <CLOSED/>
        </IN_PRG>
        <PR>
            <CLOSED/>
        </PR>
        <CLOSED>
            <IN_PRG/>
        </CLOSED>
    </ISS>
    <CODE>
        <OPEN>
            <DEV/>
            <DEF/>
        </OPEN>
        <DEF>
            <OPEN/>
            <DEV/>
        </DEF>
        <DEV>
            <DEF/>
            <TEST/>
        </DEV>
        <TEST>
            <DEV/>
            <PR/>
            <CLOSED/>
        </TEST>
        <PR>
            <CLOSED/>
        </PR>
        <CLOSED>
            <DEV/>
        </CLOSED>
        <CB>Delta</CB>
        <CB>Blueprint</CB>
        <CB>MR</CB>
        <CB>Code Insp</CB>
    </CODE>
    <DOC>
        <OPEN>
            <IN_PRG/>
            <DEF/>
        </OPEN>
        <DEF>
            <OPEN/>
            <IN_PRG/>
        </DEF>
        <IN_PRG>
            <RVW/>
            <DEF/>
        </IN_PRG>
        <RVW>
            <BL/>
            <IN_PRG/>
        </RVW>
        <BL>
            <RVW/>
            <PR/>
            <CLOSED/>
        </BL>
        <PR>
            <CLOSED/>
        </PR>
        <CLOSED>
            <IN_PRG/>
        </CLOSED>
        <CB>DocNum</CB>
        <CB>VGs</CB>
        <CB>Blueprint</CB>
        <CB>MR</CB>
        <CB>Library</CB>
    </DOC>
</root>

So, as you can see, there is a TASK type of "TASK". From state "OPEN", you can transition to state "IN_PRG" or state "DEF", and so on...

All task types start in state OPEN. This is hard-coded in BORG. All task types can be forced to CLOSED state from the task tracker Action menu no matter what the XML state information allows.

Once you have created the task type XML, it should be imported back into the task tracker using the import option in the task tracker Options menu.

BORG will not import invalid XML. If the XML is valid, but not correct, you can fix the XML and import it again. No damage will be done by logical errors in your XML, except that you might not be able to transition your tasks correctly.

Address Book/Birthdays

The address book is pretty self-explanatory. It holds addresses and other personal information.

There is a birthday field for each record in the address book. If a date is entered in this field, the person's birthday will appear on the calendar on the appropriate day each year. In addition, the person's age will appear on the calendar also.

Options

Most of the options from the options screens are self-explanatory - except:

Email - an email message is sent once a day only, and only for the next day's appointments. Provide the name of an SMTP server and email address to send to. BORG cannot send a user/password to the SMTP server at this time.

Changing the database directory (where you keep BORG files), does not affect the files. They are not moved. If you want to change directories and keep your data, copy the files to the new directory, change the dir in BORG, and then restart BORG.

Logging - the log records provide a record of BORG activity (DB adds/deletes). The Java version of BORG does not have any tools to take action on the log records (i.e. view them nicely or play them back into a DB).

Auto Update Check - this only causes BORG to compare the latest release number from the BORG sourceforge web site to the release that you are running. If the releases are different, a popup will inform you. Nothing else is done. The feature is off by default. The check is done once per day. Only stable release numbers are kept on the web. New Beta releases will not be detected.

Look And Feel - the combo box will be populated only with the installed look and feels in your JRE. The default is Metal. You can put new look and feels in your classpath and type the full class name into the combo box. BORG looks good with the default Metal L&F and also the Kunststoff L&F, and the PlasticXP l&f from jgoodies.com, which is recommended. The Liquid L&F looks ok too. Some of the other L&Fs are not so appealing with BORG. No look and feels are distributed with BORG.

Holidays - Most US and Canadian holidays can be shown (optionally). Except for Christmas, religious/ethnic holidays are not yet included - mainly because they are usually lunar based and much harder to calculate - and because they aren't usually a day off from work. These can be added manually through the appointment editor.

Word Wrap - this will cause text to wrap in the month view and print. To take effect in the month view, the window must be destroyed and recreated either be restarting BORG, or by killing the window and re-opening from the systay icon (windows only).

Print Logo - A user defined print logo can be included on the month print. The logo space will be the last two empty boxes on the bottom right. This will have a size of 184x72 pixels. Any logo smaller than this will just be centered in this space. Any logo larger will be scaled to fit - retaining its aspect ratio. The logo can be GIF, JPG, or PNG. A color logo will print in color, even if the color-print option in BORG is turned off.

Start in Background - Windows only. This will cause BORG to start only as a systray icon. No other windows will be opened - except for reminder popups and the auto version check if applicable. BORG will still popup reminders and send email while running in the background. The main month view can be started by double clicking the systray icon or from the systray icon menu.

Printing

For some users, printing a month view may be the most important part of BORG. Some users will print the next few months and use the printout as a "daily planner" until they can get back to BORG to update it online. There is ample room on the printout to jot new appointments.

The printing uses the Java print service to find a printer that can print the month view. It may take a few seconds before Java scans the printers on your system and pops up the printer selection box.

Systray Icon (Windows only)

Version 1.2 now supports a systray icon. See file SYSTRAY.txt for information on how to set this up.

Import/Export to XML

BORG can export/import its data to/from XML. This is a fully functional export/import with an improved XML format as of release 1.2. The import/export actions can be found on the month view Action menu. Import/Export provides a good way to backup your data in human readable/editable form.

Import will merge data into the current database. This can be dangerous. Importing data back into the database it came from will create duplicates of
every item, whith no automatic way of cleaning them up, so be careful.

In 1.3.2, import from a URL was added. An example URL would be http://your.server.name/some/path/borg.xml.
Export to a URL will export all 3 databases as files borg.xml, mrdb.xml, addr.xml to wherever the URL points. You cannot use an http URL. You need to use something like FTP. For example, ftp://username@your.ftp.server/your/path. If a password is needed, you must specify in the URL - ftp://username:password@your.ftp.server/your/path. Besides providing a backup for your own data, Import/Export from URL could be used to share common data, such as meetings, holidays, etc...

Command Line options:

-db <dir>	set database directory
-trayname <string>	set tool tip text for system tray icon ( windows )

mdbtool.jar

A file called mdbtool.jar is distributed with the BORG binary .zip file. It is a tool that can be used to debug, turn on logging, and do some other stuff for .jdb database files. It is not vital to BORG and not fully documented. You shouldn't need to use it unless you playing with the database source code and need to do some debugging.

In version 1.2 some options were added to mdbtool.jar:

The Repair option will scan through a database looking for bad rows. Any bad rows will be marked as deleted, allowing the rest of the database to be accessed. Database corruption usually only occurs when a disk is bad, out of space, or during a computer crash. Usually, only 1 database row will be affected. In most cases, BORG will automatically detect this and ignore bad rows. In rare cases, BORG will error and appear to not fully fill in an entire screen of data. This is the case where the repair tool can help. DO NOT RUN REPAIR UNLESS YOU HAVE A PROBLEM.

The Convert Dates option is only to be used under rare circumstances. Convert Dates will take a pre-1.2 BORG database and alter the date information to a standard format. Databases created by version 1.2 and later will be created using this standard format. THIS OPTION IS A BIT EXPERIMENTAL - and should only be used if needed. One reason to need this option is if you change locales (region setting) on your computer to use a date format different from the one you have been using with BORG 1.1 or earlier. Another reason would be if you try to copy a pre-1.2 db file to a machine that uses a different date format. If this happens, BORG will error trying to parse dates. If (AND ONLY IF) you get these date errors, then backup your db files, and run the Convert Dates option to make your DB files portable across locales. Do not run this option if you have no problems.

RDBMS Support

BORG 1.3 contains experimental support for keeping its data in a relational DB instead of normal files. Only a single user is supported per DB in this release (with the intent of supporting multiple users in a single DB in the future). However, multiple DBs can be created for multiple users.
See file RDBMS.txt for more information.

Multi-User Support

The multi-user support is in 1.3.2. You have to turn in on from the options menu and restart (if you want to use it).

In general, the way it works is that all BORGs sharing the same DB files will use locking to prevent concurrent access. There will be a counter in the database that each client will use to determine if another clent has updated the database since the last time it checked the DB. If a client determines that the DB has been updated by another client, it will flush all cached data and rescan the database to sync up.

A menu option has been added to force BORG to sync with the database. This is useful when you want to pull in other users' changes but have no desire to update the DB yourself. BORG will always sync the DB before it tries to update it, but if you are just browsing data, BORG will run from its cached data and not force a sync - hence the sync menu option in case you want to pick up someone elses changes.