Chapter 7. Converting PIM data with Perl

Table of Contents

7.1. Invoice calculation scripts

Limitations of XSL. XSL can only do so much. Converting to file formats of a similar structure and layout is relatively simple and problem-free. Converting to file formats or objects that require multiple calculations or associating data within objects of different types is less reliable. An example is the invoice XSL: It works OK for simple invoices (one client per day, one expense, one mileage claim per invoice) but fails with more complex invoices.

Modules. Data Freedom perl scripts use these Perl modules which might not be installed on your system:

These modules are dependencies of datafreedom-perl.

Currently, the perl scripts are not as complete as the XSL but work is progressing. Feel free to contribute any improvements via the QOF-devel mailing list, the wiki or the mantis bug tracker.

datafreedom-perl includes a variety of scripts to summarise or report on various types of supported data, including mileage claims (via gpe-expenses or pilot-qof) and invoices (pilot-qof). These scripts developed from the 'pilot-qof' package but now include support for other packages and formats and will continue to be extended along the lines of - liberating user data from the application. Therefore, the datafreedom scripts use a 'df' prefix.

The scripts continue to be developed within the pilot-qof CVS until such time as the scripts are sufficiently cohesive to form a new source package. The scripts are part of the datafreedom-perl package in Debian/Ubuntu and are installed in your main system path. Please refer to the manpage for each script for full information.

Example scripts in /usr/share/doc/. To reduce dependencies, some scripts are provided as examples and are not installed to privileged system folders within your PATH.

Subsequent scripts are planned to include methods to convert standard PIM formats into QSF XML for further processing.

Invoice calculation scripts

Version 0.2.0 contains two new scripts, dfinvoice-future (summarises pending bookings and estimates the costs to be invoiced) and dfinvoice-month (displays the submitted invoices and can support matching invoices against payments.

Using a configuration file in the user home directory, /home/user/.datafreedom/invoice.conf, the script reads the Palm data synchronised using pilot-qof --invoice-city, combines the data with location and rate details in the configuration file and outputs a table summarising the invoices and costs.

Example configuration:


 [Acacia Avenue]

This configuration sets a mileage rate (expenses charged for personal transport for business purposes, per unit distance) and a default hourly rate for the work itself. Other expenses are read in from the pilot-qof data in the basefile. If category value is set, the string is passed to the --category option of pilot-qof to isolate specific categories of appointments, expenses and contacts from the rest of your data. (Only one category is supported per user.)

internationalisation support

The term mileage in the configuration file is a keyword (it is not interchangeable with other terms like distance etc.), but the Palm takes care of selecting the distance unit - miles or kilometres - and the scripts will use that value.

For places where the rates differ, location-specific sections can be added - the hourly rate overrides the default rate and the code is meant to be a shorthand for the location itself. e.g. if Head Office etc. puts a code in the invoice payment notice to represent the location or the cost code and similar, to help you identify the appropriate line of content in the notice itself.

The simple table formatting used in the output appears to have a minor issue with UTF-8 - if the currency symbol for your locale uses UTF-8, the rows using the symbol will be shortened by one character per use of the UTF-8 symbol, causing the column markers to be mis-aligned.

Payments can also be handled with a simple list in ~/.datafreedom/paid where each line refers to one invoice (even if more than one invoice is paid with the same reference). The list needs a simple format:

 date : reference

where 'date' matches the date format used by the pilot-qof -t option: e.g. 2009-11-24 for the 24th day of the 11th month in the year 2009.

 $ date +%Y-%m-%d

Whatever text occurs after the colon until the end of the line is used as the payment reference.

Only one reference can be supported for any one date.

If no invoice exists for the date for any given reference, that reference is ignored in the output but is still counted.

The design of the script and the structure of the data suits particular types of businesses (specifically mine) and might not suit others so well.

The main objective is to support "consultant" or "service" industries rather than "retail" or "commodity" industries - with a further assumption that work is performed and paid on the basis of single dates with not more than one invoice per day, although one payment can cover more than one date and therefore more than one invoice.