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

Categories

From the Categories menu on the main screen, appointment categories can be created and filtered.  Each appointment can be assigned to a category.  The program can then filter appointments using a user-selected list of categories. Appointments that are in a category that is being shown behave normally and appear in the calendar, printouts, etc... Appointments that are in a category that is hidden, will remain in your database, but will not appear anywhere on any screen as long as their category is not being shown. This provides a way to manage "virtual" calendars in one database.

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 choosing File/Add.

If the day being edited has existing appointments, they can be edited by clicking the Show Next button until the appointment you want to edit is being displayed. Existing appointments can be updated or deleted from the File menu.

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, the File menu provides 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.

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.

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.

Email Reminders

BORG can be set to send an email reminder each day for the next day's appointments. The main 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.

Options

 
Most of the options from the main options screen are self-explanatory - except:

The font size increase/decrease currently only affects the appointment text in the main month view. Hopefully, the size of all other text is adequate. The users may want to change the appointment font size to taste, depending on how much they want to fit in a single day box versus how good their eyesight is.

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.

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. Importing can only be done into empty databases. This is enforced (to prevent really bad things from happening). 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.

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

AutoStart

The autostart feature provides a way for a user to have BORG automatically start if an appointment is coming due and the user has forgotten to start BORG.

Keep in mind that the best way to use BORG is to run it ALL the time. It will keep popping up reminders and sending reminder emails. If it can't be run ALL the time then have it always start when you first start your windowing system. There are a number of ways to do this in Windows - i.e. the startup menu or scheduled tasks. In UNIX, there are also a few ways depending on the flavor of X-windows that you run. GNOME on Linux has options to set startup programs by editing your login session.

If this is not appropriate for you, there is the autostart feature. Using this feature, you can have BORG try to start every so often (5/10 minutes? whatever you like) using the Windows task scheduler or cron under UNIX. When started with the autostart option, BORG will only start if an appoinment is approaching (<30 minutes away). Otherwise BORG will quickly exit. BORG will also exit quietly if it detects that another BORG process is already running. If you are not logged on, BORG will also exit quietly.

To use autostart under windows:

Create a .bat file that starts BORG in autostart mode. Here is an example of the contents:

javaw -jar c:\mbb\borgdir\borg.jar -autostart

Notice that javaw is used. Also notice the -autostart option. Use the proper path to borg.jar on your machine. Use the full path to javaw if it is not in your PATH already.
RIght click on the .bat file in explorer and set the following options - run minimized and close on exit. This will make sure that each run of BORG will not have MSDOS windows popping up or lying around.
Then set up a windows scheduled task item to run your .bat file as often as you like. This will run BORG over and over without starting the GUI until an appointment approaches.

The above example worked under Windows ME. Windows XP has not been tried.

To use autostart under UNIX:

Create an executable shell script that starts BORG in autostart mode. The following example worked under Fedora Linux:

export DISPLAY=unix:0
/usr/java/j2sdk1.4.1/bin/java -jar /home/mbb/sourceforge/borg_src/dist/borg.jar -autostart >/dev/null 2>/dev/null

Use the appropriate path to java and your borg.jar file. cron jobs don't have the same PATH set up as your login shell, so a full path is probably needed. Also notice the -autostart option. With Fedora Linux running the GNOME desktop, the DISPLAY variable needed to be set since the cron environment did not have this and did not default to anything usable. Each UNIX is different. You may have to experiment.
Removing the /dev/null stuff will cause cron to send BORG output to your email. This will help you debug problems if BORG does not seem to ever start correctly.

Then use crontab -e to add a cron job that runs your shell. See the man page for crontab(5). Also, you may have to set up your UNIX machine to give your login permission to use cron.