Simple Invoices

From Bloominglabs
Jump to: navigation, search

We utilize Simple Invoices to automate dues invoicing. It has four main features which makes it useful for us: it's web based, it can be configured to send monthly recurring invoices, payments through PayPal automatically update the system for you, and members can check their current balance on their own. Manual payments can be processed by the admin or users depending on how you implement it. It's based on php/mysql and is probably about mid-way in it's development cycle. It takes some hacking to get it running, my notes are included below.

Simple Invoices works as-is, however it still lacks some key features to make it compete with commercial equivalents. Namely, if a member pays ahead and creates a credit balance, the recurring invoice will not reflect this (it will show they owe $40 rather than reflect their true balance minus the recurring dues charge). It has enough features to make us live with this "feature" until we can fix it ourselves.


Contents

How to mod Simple Invoices to work for a hackerspace

Installation

First get the latest version of SI, we used this version:

Version 2011-1 is still listed as the latest in some places, but we found that authentication was completely broken in that version.

Also you must separately download the latest version of Zend with version stable-2012-1-CIS3000:

Extract Zend to this place inside the SI install directory:

  • /libraries/Zend

This is a set of 4 customized files for version "stable-2012-1-CIS3000" which greatly enhances its usability out of the box, installation described below:

Edit /config/config.ini and input the database, database user, and password. Navigate to the website and follow the directions. Now you can complete the install. Once installed you will probably want to add the following customisations to it.


Customizations which we applied to SI

We wanted the treasurer to have admin access and members to only be able to view their dues balances. You know, that's the first thing everyone asks you at that time of the month - how far behind am I? This will let you send them to a report which tells who is behind and by how much.

Unpack File:Si mods.tgz and put the files in these locations:

  • acl.php -> /include/acl.php # Do this if you want members to have non-admin access (so they can see their outstanding dues balance)
  • index.php -> /index.php # This makes non-admin access easier - forwards them to a "reports" page rather than a "you cant view this" page upon login
  • index.tpl -> /templates/default/index # This customizes the Dashboard so only two reports are listed: Unpaid dues and total balances (for folks who pay ahead)

Open phpmyadmin, go your simpleInvoces DB->user_role table

There is one role there whch is the administrator, add at least the role of "viewer" with a different unique id. Now you can add non-admin users through the web interface.

Login to the site and set your username and password to login with. Then edit /config/config.ini and change this value to "= true":

authentication.enabled                          = true

You now have two account classes, admins and viewers, go to the web interface and create a non-admin user for members to login with. We just have two accounts and post the non-admin account for everyone to use.

Additional Customizations

By default emailed invoices (pdf) are usually around 600kb, install this file from the SI_mods.tgz bundle to knock them down to ~30kb:

  • config.inc.php -> /library/pdf/config.inc.php


If you want to change your login page edit this file:

  • /templates/default/auth/login.tpl


To make recurring invoices work, add this to cron on the host running SI:

0 1 * * * /usr/bin/wget -O - -q "http://www.yourspace.org/simpleinvoices/index.php?module=api&view=cron" > /dev/null 2>&1


Setting it up

First, go into phpmyadmin and remove any sample data (only invoices can be deleted - and only after enabling the delete-invoice setting in Settings)

Now go into the web interface:

  • Add a biller (Your space)
    • This is where you will add your paypal account info for automatic invoice updates from paypal
  • Add Customers (members)
    • Names and email at a minimum
  • Create an initial invoice for each member
  • Create a recurring invoice (most likely monthly) based on the initial one just created
  • Members who regularly pay ahead can be invoiced at separate increments (say, 6/12 months per recurrence)

Currently there's no way to have the system not invoice someone if they have paid ahead, but you can temporarily set the recurring invoice to not email them if you wish. Then when invoices get issued during your monthly cycle you can mark it paid, then turn email notifications for that member back on.


Things to be aware of

One thing we wanted was to have the invoicing system be smart enough to take the invoice out of a members balance if they had paid ahead. This isn't something it looks like SI will ever support. For most members this isn't an issue, but if you are luckey enough to have a member or two who pay ahead here is the workaround. Just create a recurring invoice based on their usual payment if possible. That being said, it does properly register credit balances at least if you do enter an over-invoiced amount into SI.


There is no way to stop recurring invoices or remove "customers" from within the application. This has to be done manually with either mysql or phpmyadmin. The trick to identifying which recurring invoice is which from inside the database is to use the date. You can update the date on the recurrence if needed to make it identifiable and then just remove it. Members are easy enough to locate and drop. This is an issue up for correction in their Github but it's way down the list of features they are working on adding. So the first thing you do after installing SI is to use phpmyadmin to remove the sample data. Really guys??


Scripts we have bolted-on to SI

We have several scripts that peridocally interact with SI to address some of the short-comings. They all go through the web interface even though they run on the same server that SI runs (shells scripts using wget).

The nag email script has 4 modes of operation and each mode runs once a month on different dates.

0 8 5 * *  /home/dosman/bin/balance_checker1.sh -prefinal                | Will deactivate RFID fobs for users over 3 months late - run between 15th and last day of current month
0 9 5 * * /home/dosman/bin/balance_checker1.sh -formermembers            | Find and notify former members who still owe a balance - run before the 15th of the current month
0 8 16 * * /home/dosman/bin/balance_checker1.sh                          | Notifies all users who are currently 2 months or more behind on dues.
0 8 26 * * /home/dosman/bin/balance_checker1.sh -endofmonthreminder      | Notifies members who are 2 months behind - run between 16th and last day of current month

Monthly treasurers report runs on the last day of the month (just before new invoices are cut). This gives the treasurer a list of all members behind on dues (and amount behind), a list of all dues payments made, and a list of everyone who has paid-ahead. The paid-ahead sections pulls data from the Google Spreadsheet.

55 23 28-31 * * [[ "$(date --date=tomorrow +\%d)" == "01" ]] && /home/dosman/bin/treasurers_report.sh | mail -s "Bloominglabs Monthly Treasurers Report" treasurer at bloominglabs.org

This runs actions when a member is detected who's membership has ended such as: removing them from the members mailing list, and disabling their RFID access:

0 3 * * 0 /home/dosman/bin/ex_member_reconcile.sh
Personal tools