Christmas is long over, yet we have a wish: we want to introduce a new field to `civicrm_contribution`, (tentatively) called `sequence_number`. This will give contributions records belonging to a recurring contribution some self-awareness, by recording which installment in the series each contribution record represents.
Our itch to scratch here regards to direct debits, where we need a simple and reliable method for determining which installemnts have already been created, and which still need to be created. But let's think big: it seems to me that storing this information should be useful for other types of recurring contributions as well.
Note the emphasis on reliable. In the ordinary case, we should be able to derive the sequence number easily by counting the contribution records. However, in the Real World (TM), nothing ever goes as it should -- especially when computers are involved :-)
For one, counting only works if the contribution records in CiviCRM are complete. And while CiviCRM is meant to be omniscient, this might not always be the case: for example when importing from legacy systems; or if an IPN callback from the provider doesn't get through for some reason. Also, individual contribution records sometimes might be deleted or duplicated -- whether due to technical imperfections (impossible! yet real), human error (same...), or even intentionally -- for example when dealing with failed payments.
In such cases it would be tricky for smart humans, and virtually impossible for the dumb machine to figure out what happened. Of course these are all more or less exceptional events -- which is to say, they are actually quite common; and when they do occur, it is very comforting to have some reliable records helping with understanding the situation...
Or getting back to our own itch (how could we have ignored it for so long?): it is really crucial to reliably know the current sequence number -- even in exceptional situations -- if followup payments are generated internally by the payment extension: such as direct debits triggered from CiviCRM.
So, now that we established the rationale, you are surely itching to see the code? Well, I'm sorry to say we don't have it just yet -- but I will follow up as soon as I get to it, which I expect to be in a week or two, barring some medium-sized or larger catastrophe.
(Not worth holding your breath very much though: it will be just a simple schema change plus upgrade SQL, and some basic form code to display the field for recurring contribution installments.)
Ah, but I have saved up one really interesting question for you :-) What to do with the existing Payment Providers? Ideally, the sequence number shall be passed from the remote server in the IPN, and can be stored in our shiny new DB field directly. Now this would be so useful, that I fully expect at least some providers to omit this information. In such cases, we might want to cheat a bit, deriving the sequence number from the existing payment records instead. This wouldn't be really reliable though, which is the whole point of introducing the field in the first place... Still, it might be useful, if generic mechanisms start using this information. So what do you think?