Next Previous Contents

7. Advanced configuration topics

This section is intended for those who wish to use e-Bills more seriously. This could allow you to:

Some of the functions will require a small understanding of coding in PHP (C experience is fine)

If we've missed something please let us know using the discussion forum via http://ebills.sourceforge.net

7.1 Changing _configure.inc

etc/_configure.inc is the file that contains configuration variables for the server side PHP code. The contents of this file are well commented, so if you need to take a browse and update as necessary.

If you run multiple instances of e-Bills you will definitely need to update this file.

7.2 Using customer references in your style

If the format of customer references created in the "Add customer" function do not meet the needs of your business then edit the auto_customer_ref() function in create-defaults.inc (remember to take a copy first). The default is for this function to create references of the style CSnnnnnn, where nnnnnn is a random number. It can be manually overwritten in the "Add customer" entry form.

7.3 Using contract references in your style

If the format of contract references created in the "Add customer" and "Add contract" functions do not meet the needs of your business then edit the auto_contract_ref() function in create-defaults.inc (remember to take a copy first). The default is for this function to create references of the style CS-yyyy-iiii, where yyyy is the year and iiii is a sequential number. It can be manually overwritten in the "Add contract" entry form.

The following variable is defined in etc/_configure.inc:

INVOICE_NUMBER_START defines the base for your invoice numbers, change it as required or set to zero.

7.4 Creating your own billing template

You only need to do this once, but it is necessary to learn something about TeX. The TeTeX HOWTO gives some useful advice and there are some great sites, including Text Processing using LaTeX from the University of Cambridge Department of Engineering which contains excellent tutorial information. I strongly suggest you create a new .tex file from Standard.tex and use that as a starting point.

Here's some useful pointers:

1. All PHP variables start with a '$' sign. I've used the same within the billing template file (it was easy for PHP to evaluate directly) and TeX doesn't use the $ often. Here's the list:

PurposeVariable name
Date
$todays_date
$payment_duedate
Reference
$invoice_number
$customer_ref
$contract_ref
$billing_sequence
Customer
$customer_name
$contact_name
$address1
$address2
$address3
$town
$county
$postcode
Your organisation
$org_vat_reg
$org_company
$org_address1
$org_address2
$org_address3
$org_town
$org_county
$org_postcode
$org_tel
$org_fax
$org_email
$org_web
$org_co_reg
Product data
$ref
$product_code
$description
$qty
$comments
$amount
Charge summary
$vat
$subtotal
$grandtotal

You'll see how these are used within Standard.tex. Note also that you don't need to use of these within a bill and that some fields can be used in different ways, e.g. $contact_ref could be used as a "Meter number" or a "Customer Purchase Order Number", rather than a contract number

2. I've deliberately started all the template filenames with a capital letter 'A' through 'Z'. The configure billing template file written in PHP will only pick up filenames with a capital starting letter and a .tex extension.

3. Note that I've used '%%% Detail' within the .tex file to state that the next line contains the (repeated) line with Product information. This line is output as many times as needed within the production of a bill.

4. If your bills extend to more than one page ensure that you sort out the headers and footers for subsequent pages.

5. Changing simply the currency is quite easy. Replace the "\pounds" with "EUR" for example.

6. Test this new template using an existing .tex file created by ebills (from the ebills.pdfs directory) and run from the command line with:

7.5 Configuring the email format sent with bills

You can specify how bills will be delivered to customers with each contract. There are three options: post, emali and fax, with the latter not fully implemented yet. The default option is post, resulting in bills being printed.

emails are sent as html, with the same text repeated as a plain text attachment and the bill attached as an Adobe® Portable Document Format (PDF) file.

If you send bills by email then you may wish to edit 'etc/send_bill_by_email.htm'. This is an html file contain various PHP variables. The variables are evaluated prior to sending, in order to give the email some life.

The variables that you can use are:

Restriction: please note that this file is also used to create the plain text attachment that is sent with the html email. The PHP simply removes html tags to create the plain text file. You are advised to edit this file using an html editor to ensure that the line width appropriate for plain text reading (i.e. not too long and not too many line breaks).

7.6 Using the Billing Engine

The billing engine is detected automatically by the web side PHP code and if present it will be used. To use the billing engine all you need is:

7.7 Configuring the Billing Engine

The following shows the options available from the Billing Engine:

When run from the web-side code it will be called with the "-fp" switches, resulting in html formatted output and a .tex and .pdf file being produced.

When run as a cron job you would use the "-qp" switches and from the command line use the "-p"

You can optionally provide specify a configuration file (see etc/ebills.conf). The default looks like:

7.8 Running multiple instances of e-Bills

You may find yourself running in either an ASP environment or simply in an environment where you have to produce bills for two or more legal entities. Running e-Bills as separate instances allows you to control which employees access the data from each company anf for you to utilise bill formats that show the correct company addresses and corporate information.

The process is quite simple and if you've already installed e-Bills is a case repeating the process using new domain names, directory names and database name

and that's about it.... login as su, add some users, update the organisation data and you are there.

7.9 Adding a logo into your bills

To add a logo into your bills you will need to create a version of your logo as an EPS (Encapsulated PostScript) file. We used OpenOffice Draw (www.openoffice.org) to create our logo and to save it as an EPS file using the File / Export function. Remember to set the image size to be sensible for the invoice (the e-Bills logo is 3.5 cm wide x 2.6 cm high). The file saved as type 2, color was 7KB. Save the logo in your bill_templates folder (e.g. /home/ebills/bill_templates)

When you've created your EPS logo edit the relevant bill template file (e.g. Standard.tex). This contains the following lines:

Remove the comment ('%' character) from the beginning of the 4 lines. Also ensure that the path to the logo file is correct. Next, select that billing template from the Super User configuration options.

The next bill you create will contain your logo.

7.10 Linking to e-Bills from your intranet

e-Bills can easily be linked to your Intranet or to an extranet.

The easiest way is to simply provide a link to index.html in your e-Bills directory. This provides the start button which opens e-Bills in a new browser window and prompts for username and password.

If the above approach is clumsy, then simply extract the html and the newWindow function from index.html and paste it into your site. This will allow users to open a single new window with the login screen on a single click.

7.11 Running the billing engine as a cron job

The billing engine can be run every night, or once a week or whenever is necessary to create your invoices in bulk. This allows invoices to be spooled directly to a printer for posting to your customers, or simply ensures they are available on your server running e-Bills for manual use.

To run as a cron job, you should simply type:

and then in the resultant editor screen:

The above will run ebills at 22:30 every day. Check

man 5 crontab
for details as to the other fields

Note that if you were using a config file you would need to specify that also:

The above will also automatically spool invoices to your configured printer.

7.12 Configuring the email format used with work items

You can change the format of the email used to send notifications and reminders associated with work items.

emails are sent as html, with the same text repeated as a plain text attachment.

The file to edit is 'etc/send_workitem_by_email.htm'. This is an html file contain various PHP variables. The variables are evaluated prior to sending, in order to give the email some life.

The variables that you can use are:

This email is intended as a notifier or reminder only. As such it deliberately excludes detail of the work item itseld.

Note that a future version of ebills will include the ability to click on a link within these emails to be taken directly to page to change the work items (including via a login screen).


Next Previous Contents