CiviCRM Community Forums (archive)

Hi everyone,

We recently put together a draft spec for an Event Registration Invoicing add-on for CiviCRM/CiviEvent.  I'm posting a sanitized version here to solicit feedback from:

a) anyone who has a similar requirement for actual invoice documents,
b) any developers who are working on accounting-related features in 4.4 that have input, and
c) anyone else in the community who wants to share their $0.02 :-)

Thanks in advance for any thoughts, suggestions, constructive criticism, etc.!
-Jim

CivInvoice Feature Spec


Our organization recently launched an overhauled website for event registration built using CiviCRM 4.3.x/CiviEvent on Drupal 7.x.  Our staff members require flexible invoice management features; this document proposes a set of features that would generate, email, and archive invoice files (PDFs) upon event registration and provide a simple management interface for staff to search and manage invoices.

Existing Customization and Problem Definition

Our existing CiviCRM and CiviEvent installation includes a custom component that generates a human-friendly “Invoice Number” for each transaction (CiviEvent’s Contribution records for event registration).  This invoice number is a five-digit integer (seeded from 10000) issued sequentially.  In addition, a set of search fields was added to the CiviCRM Find Participants search screen allowing staff to generate a list of Participants based on an Invoice Number or range of Invoice Numbers.

This limited Invoice Number functionality does perform as expected but we wish to enhance it further.  Specifically, the concept of “Invoice Number” simply mapping to an Event Registration Transaction/Contribution record does not allow for the creation of actual invoice documents.  Invoice documents meeting certain data and formatting requirements are now required by clients, including the collection of Billing Addresses for “pay later” transactions.  In addition, the ability to save invoice document files corresponding to specific invoices/transactions is required by staff.

Proposed Workflow Modifications

The Invoice functionality is only required when website visitors (authenticated via Drupal, with corresponding contact records in CiviCRM) register for paid events.  In addition, modifications to the CiviCRM interface will be required so staff can search for specific invoice records.  Existing workflows are outlined below with proposed/required changes indicated in italics.

User Event Registration Workflow


User visits CiviCRM Event Registration page for a specific event

User proceeds through registration, is able to select from payment methods of  “Credit Card” or “I will pay by check” (Civi’s “Pay Later’ option) currently, “Pay Later” selectees may not have associated billing information on file.  The CiviEvent logic does not require collection of this information; however, our new Invoice format requires an up-to-date Billing Address, Billing Email Address, and Billing Phone Number.  This deficiency may be solved in Civi 4.4 (see post here) and if so, any solution for collecting Billing info must be compatible with future Civi 4.4. changes to this logic.

When User clicks “Continue” on the registration confirmation page, the proposed invoice / receipt procedure is invoked:
the transaction is processed as normal, including the assignment of a human-friendly invoice number associated with this transaction (i.e., preserve the existing invoice number functionality provided by the existing custom module)

* a PDF file is generated using an Invoice template, with relevant data from this transaction inserted into the PDF where appropriate (see Attachment 1) and with relevant restrictions (see “Invoice Data Considerations” below)

* the final PDF file is stored on the server in a custom private files directory for later retrieval/management

* in addition to the human-friendly invoice number that is stored with the Participant record, a link to the PDF invoice should also be associated with that Participant record for later retrieval by staff

* the PDF invoice file will be emailed to: (i) the website visitor completing the registration transaction in addition to the existing text/HTML and PDF copies of the registration confirmation email, (ii) any address specified in the participant’s Billing Email Address field, and (iii) an internal address specified by our admin to collect all invoices for backup purposes

* on the confirmation screen, a temporary link to the Invoice will be presented to the user (since they should not be able to access the permanently-stored invoice on the server as non-staff users).

When users are added to an event’s wait list, they should receive an email “wait list” notification but should not receive an Invoice or Receipt file, and the activity should not be assigned an Invoice number.  If those users sign up at a later date via the Wait List process, they should then receive an Invoice/Receipt number depending on their payment choice.


Staff Invoice Management Workflow

Authenticated, authorized staff member visits the CiviEvent “Find Participants” page to search for one or more specific invoices.
This page currently includes a search fieldset allowing staff to search for an invoice or a range of invoices based on invoice number
The new invoice search feature will preserve the invoice number search and also present a search fieldset based on invoice date (for our purposes, invoice date is identical to transaction date/time and registration date/time for the specific event registration).

Once staff has entered their invoice search criteria, they will be presented with the resulting Participants records table as built-in to CiviEvent.  Staff will need to select “View” to view details on a specific Participant record.

The resulting “View Event Registration / View Participant” record detail page will now include a link to the stored PDF invoice file associated with that specific Event Registration.

Invoice Data Requirements

(these are fields that appear on a mock invoice template; the specific placement on the page is not relevant to this post)

## If “Pay Later” has been selected, the “Invoice” template is used.
## If “Pay by CC” has been selected, the “Receipt” template is used.
## Templates are identical other than “Invoice” or “Receipt” header, and numbers
## come from the same sequential pool.

A.   Invoice Date
   Equivalent to Registration Date/Time since invoices are “issued” upon registration

B.    Invoice Number
   Human-friendly Invoice # generated by existing custom code

C.   Billing Address
   See note above about need to collect this information for “pay later” participants

D.    Service Address
This is the primary participant’s primary address, which may or may not be identical to Billing Address. If there is no Address/Primary, the Billing Address should be duplicated here.

E.    Registration Details
   Identical to existing invoice/receipt template line items, including pricing data and any
   CiviDiscount discounts applied

F.   Invoice Total
   Total of all fees less discounts, summed from line items as in existing invoice/receipt
template

G.   Static Text Areas (1-3)
These are regions of static text that can be defined and updated by site administrators.  The text fields could be stored in Drupal, CiviCRM, or a standalone table as long as administrators can modify the fields and have those modifications reflected on all future invoices generated.


Open Source Considerations


Our organization is committed to the principles of open source software.  All attempts should be made to make this code reusable and suitable for release to the CiviCRM community.