BANAL version 0.10

Chapter 2: Basic Client Usage

The use of the bk client is very simple. We assume that the server is running and that you are familiar with the concepts presented in 1.2.

A list of commands and help is available by typing:
bk help.

You can obtain specific help on a command by typing:
bk help <command>.

It is important to note that the -L option is used with the directory that contains the BK subdirectory (in this distribution it is found in the lib directory). You should only need to use this option if you move the lib directory relative to the bin directory.

The -p must be passed the server name and port number in the form SERVER:PORT. This command line option will override both the default server and port and any values set by the environment variable BKPORT. BKPORT, if set, must also be of the form SERVER:PORT.

The client's default setting for the server name is localhost. You may change this in the bk script if it is easier than setting an environment variable or creating an alias.

2.1: Add/Edit/Delete Commands

These commands are used for manipulating records in a table. To see a listing of tables refer to section 4.3.

Here is a sample usage for modifying data in the invoice table. This usage would be identical (except for the command name) for any other existing table. The modify command is always the same as the table name.

invoice -- Create, delete, or edit an invoice
bk invoice [ -t template ] [ ID ]
bk invoice -o [ -t template ] [ ID ]
bk invoice -d ID
bk invoice -i

'Invoice' creates and edits invoice values using an ASCII form. An invoice is an entry in the bookkeeping system.
With no arguments, 'invoice' creates a blank invoice form and invokes the user's editor. When the form is saved, an invoice of the form invNNNNNN is created. If an ID is given on the command line either that named ID will be created or, if the ID already exists, the invoice can be modified. Use the -t option to indicate an existing entry that will supply initial values.
The -d flag deletes the named invoice. The -o flag causes 'invoice' to write the invoice form to the standard output, instead of invoking the editor. The -i flag causes 'invoice' to read an invoice form from the standard input.

2.1.1: Importing Information

Use the 'import' command to import table entries from another source.

import -- Import raw data into a table
bk import [ -f SEP ] table
Import reads raw information from standard input and enters in into the specified table. The -f option specifies the field seperator (eg. -f : or -f XXX). The default seperator is a tab space (<TAB>).
The format of the raw data is: FieldName1<SEP>FieldName2<SEP>FieldName3... # A comment FieldData1<SEP>FieldData2<SEP>FieldData3... ...
Only the fields that you require, or want, have to be present. If the table's Unique ID field isn't present then a new ID will be generated automatically.
If you want a tab or newline (for MULTILINE fields), use 'T' and 'N' respectively (without the quotes, of course).

2.2: List Commands

These commands are used for listing records (or the field information) from the table. You may limit the records that are listed by using an expression. See the expression section (7.1) for more details. To see a listing of tables refer to section 4.3.

Here is a sample usage for listing data in the invoice table. This usage would be identical (except for the command name) for any other existing table. The listing command is always the plural form of the table's name.

invoices -- Display a list of invoices
bk invoices [ -f SEP ] [ -r ] [ -c FIELDS ] [ expression ]
bk invoices [ -f SEP ] [ -F ] [ -T ] [ -D ]
Reports a list of all invoices currently known to the system. An expression may be any valid RDB expression. The -f option specifies the field seperator (eg. -f : or -f XXX). The default seperator is a tab space (<TAB>).
Use the -r flag to generate an entire RDB file instead of just a listing of entries.
The -c flag lets the user specify which fields (and which order) to report the entries. FIELDS must be one single argument if more than one field is requested (ie. -c 'Field1 Field2')
This command may also return the field names (-F), the field types (-T), and the Field descriptions (-D).

2.2.1: Listing "Expired" Entries

There is a subcommand called 'expired' which will list all past due invoices, overdue (or unstarted) projects, and clients that should be contacted.

expired -- Generate a list of expired invoices, projects, and client contacts
bk expired [ -e days -i -p -c ]
Expired generates a list of expired invoices (based on the Date it was generated and the Term set in their Client info), projects (based on either the EstimatedStart/StartDate or the EstimatedEnd/EndDate fields), and client contacts (based on ContactWhen).
Use the -e option to add or substract extra days to the search. For example, use '-e 90' to find all entries that have been expired for 90 days or longer. Use '-e -14' to find all entries that will expire within the next two weeks (or have already expired).
The default behaviour is to find all expired items. Use the '-i' option to get the list of expired invoices. Use the '-p' option to get the expired projects. Use the '-c' option to get the expired contacts.

2.2.2: Listing Table Names

There is a subcommand called 'tablelist' which will list all of the tables that the BANAL server knows about.

tablelist -- List known tables
bk tablelist
Tablelist is used to list all of the tables that you can use for edit/modify/delete commands.

2.3: Categories and Settings

There is one big distinction between a Category and a Setting. The categories are used to define valid values for a CATEGORIZED field in a table (such as taxes and countries). Settings are used to define values for certain information (such as specific tax rates, when taxes are deducted in income statements or the user's company information).

2.3.1: Common Categories

There are several fields in the BANAL tables that are classified as CATEGORIZED. They are:

ClientState

lists whether clients are active, inactive, etc...

ClientType

lists industry (or other relevant) sectors of you clients.

Country

lists the known countries from which you may choose.

Currency

lists the valid currencies in which you may invoice. Currently, an entire invoice must be in the same currency.

Expenditure

lists the types of expenses that may be incurred.

Interval

lists the way in which a Recurrence may be repeated.

ProjectClass

lists classes of projects that are undertaken (eg. training).

ProjectType

lists possible terms for projects (eg. fixed price or time and material).

State

lists known states. States, in this context, are politcial subdivisions of a country.

TableName

lists the names of tables. Currently, this list is used for creation of new entries in a Recurrence. Thus, the Setting table is not lists, by default, to prevent people from inadvertently changing them.

Tax

lists the type of taxes that exist. If you are not in Canada, then you will probably have to define your own (and create accompanying settings).

Unit

lists the type of goods/services that may be sold. These may include units such as day/hour/week as well as fixed, for fixed price work or "real" goods.

WorkCode

lists the types of work that an Employee may perform.

Any of these categories may be re-used in another or new table as long as the underlying values are still valid. Otherwise, it would be better if you created a new Field name.

You can also add more values to any Category.

2.3.2: Configuration Settings

Settings allow an arbitrary depth of it's name by using a '/' delimiter. The Value that accompanies the setting will be used during report generation and caculations, as appropriate.

The current classes of settings are:

/Expenditure

is used to define expense specific information. Values in use now (where <EXPENSETYPE> corresponds to a Expenditure value in the Category table) are:

/Expenditure/<EXPENSETYPE>/Deductibility: is used to define a deductibility other than the default (1.0). For example, to have a class of expenses that are only deductible at 50%, you would use a setting like:
/Expenditure/Horses/Deductibility 0.5

/NewID

is used to change the way a new ID is created for a table.

/NewID/<TABLE>/Digits

specifies the minimum number of digits to use. If you "overflow" the number of digits then more will appear.

/NewID/<TABLE>/Prefix

specifies the prefix for new entries in the table. This value is evaluated at creation so that you can use values in the form to create the prefix (or just a straight string). Two examples are:

/NewID/Project/Prefix "HI MOM"

/NewID/Project/Prefix uc(substr($entry{ProjectClass}, 0, 2))

Please note that the values from a form are available using the $entry{FIELDNAME} format. Plain strings should always be in quotes.

/Tax

is used to define tax specific information. Values in use now (where <TAXTYPE> corresponds to a Tax value in the Category table) are:

/Tax/<TAXTYPE>/DeductWithExpense

specifies whether or not to deduct the tax on an expense when calculating the total expense. Use the value 0 for no and 1 for yes (yes is the default if the setting doesn't exist for that Tax).

/Tax/<TAXTYPE>/ReportWithRevenue

specifies whether ot not to report the tax an invoice's charge with the revenue. Use the value 0 for no and 1 for yes (yes is the default if the setting doesn't exist for that Tax).

/Tax/<TAXTYPE>/TaxRate

specifies the rate (in decimal) for that Tax. For example, for a 7% GST (Goods and Service Tax) you would use the setting:

/Tax/GST/TaxRate 0.07

0% is the default tax rate, if it isn't defined.

/UserInfo

is used to define user specific information. Values in use now are:

/UserInfo/BusinessLabel

is used to add company specific information ont invoices. For example, I use it to supply my GST number. My label looks like:

/UserInfo/BusinessLabel GST Number: R123456789

A setting for this is completely optional.

/UserInfo/CompanyID

is used to define which entry in the Client table to get all of the user's company information from. There is no default for this setting.

/UserInfo/DrawLetterHead

is used to tell the document whether or not to draw the letterhead on an invoice. This is currently only used in the PostScript output. It's purpose is to allow companies that have letterhead paper to omit the generation of new letterhead.

/UserInfo/User

this is used to specify the user's name. This is provided in case, you aren't using a new bk client (which will attempt to determine your name). It is also possible that bk won't be able to determine your name if you are using a service such as NIS. I've punted on this for now, let me know if it becomes an issue for your site.

Refer to the file templates/data/empty/Setting.dat for more examples.

2.4: Generating Invoices

This command is used to generate invoices based on information in the project and timesheet tables. Here is the usage:

billem -- Generate invoices from project work
bk billem [ -n ] [ projects... ]
Billem generates invoices based on finished projects, in the case of fixed price projects, and on work in progress (WIP), in the case of time and materials projects. If any project IDs are specified then only those will be be generated.
Use the -n to find out what projects would have been billed without it actually being generated.
NOTE: For Fixed price projects, if you specify a budget of 0 (or no budget at all) then existing invoices are used. Also, only one charge from one valid invoice will be used to updated the timesheets.

2.4.1: Printing Invoices

This command is used to create an invoice document based on information in the charge and invoice tables. Here is the usage:

print -- Generate an invoice, quotation or check document
bk print [ -d doctype -q ] InvoiceID bk print [ -d doctype ] -c CheckNumber
Print generates a file containing information from one of: o the InvoiceID and related Charges o a group of Expense entries and their Supplier
If the invoice has no Date set then it defaults to today and this value is saved in the database.
If the expenses have no Paid date set then it defaults to today and this value is saved in the database. If the Paid date is set on any expenses or the supplier isn't unique then the operation aborts.
Use the -q option to indicate that this is only a quotation and not a real invoice. In this instance, the Date will not be set. If the Date is already set, you will get an error.
Use the -c option to indicate that you want to print out a check. The default is to expect an Invoice ID.
Use the -d option to specify a document type. Currently, the 'postscript' and 'text' types are available. Postscript is the default.

2.5: Generating Financial Statements

Use this command to generate financial statements.

Currently there is only the income and expense summary statements available.

2.6: Generating Reports

Use this command to generate management reports.

Currently there is only the timesheet ad worksummary reports available.

2.7: Running Memorized and Recurring Transactions

For more information on recurring/memorized transaction refer to chapter 5. A special note should be added that you do not need to run this command if you only have recurring transactions (as opposed to memorized). The server will run the recurring transactions for you.

Here is the general usage of the runbatch command:

runbatch -- Process recurring transactions
bk runbatch [ -d date ] [ -m mID ] [ cmds ... ]
Runbatch may be used to force the processing of recurring transaction or to run a memorized transaction. Optional commands may be added on the command line and they will evaluated before each transaction's commands.
Use the -m option to specify the Recurrence ID of a memorized transaction (ie. NextDate is empty and Interval is 'never'). Use the -d option to specify the date to run under. This may be useful, for example, to get ahead in your work.
It should be noted that the server will process recurring transactions automatically and periodically.