hook_cdntaxreceipts_eligible

Je krijgt in België (op dit moment toch) een fiscaal attest als je op jaarbasis 40 EUR of meer schenkt. Het is een beetje vervelend dat hook_cdntaxreceipts_eligible per contributie wordt aangeroepen, want wat ik uiteindelijk doe, is voor iedere contributie apart nakijken of het gekoppelde contact over heel het jaar voldoende heeft gegeven om een attest te krijgen. Dit is erg inefficiënt, maar voor ons lijkt het te werken. Hier is de code

/*
 * Implements hook_cdntaxreceipts_eligible.
 *
 * Checks whether the contact can get a tax receipt for the year of the contribution.
 */
function chirocontribution_cdntaxreceipts_eligible($contribution) {
  if ($contribution->financial_type_id != 1) {
    return array(FALSE);
  }
  // TODO: More caching.
  $year = date('Y', strtotime($contribution->receive_date));
  $sql = "SELECT SUM(total_amount) FROM civicrm_contribution WHERE contact_id = %1 AND YEAR(receive_date) = %2;";
  $params = array(
    1 => array($contribution->contact_id, 'Integer'),
    2 => array($year, 'Integer'),
  );
  $total = CRM_Core_DAO::singleValueQuery($sql, $params);
  return array($total >= CRM_Core_BAO_Setting::getItem('chirocontribution', 'chirocontribution_amount_tax_receipt'));
}

Dus in de naam van de hook-implementatie verander je chirocontribution door de naam van je eigen extensie en module. Het opmerken waard is deze regel:

return array($total >= CRM_Core_BAO_Setting::getItem('chirocontribution', 'chirocontribution_amount_tax_receipt'));

Ik heb het bedrag van 40 EUR niet letterlijk in de code gezet; ik gebruik een CiviCRM setting chirocontribution_amount_tax_receipt uit de groep chirocontribution. Het idee is om ooit een formulier te maken via hetwelke we dat bedrag kunnen configureren, maar dat is nog een van de vele open issues van ons project ;-)

Je kunt die setting bijvoorbeeld als volgt zetten in de installer of upgrader van je extensie:

CRM_Core_BAO_Setting::setItem('40', 'chirocontribution', 'chirocontribution_amount_tax_receipt');

hook_cdntaxreceipts_alter_receipt

CDNTaxReceipts geeft de fiscale attesten het Contribution-ID van een van de contributies die bij het attest horen. Nu ken ik niet veel van attestnummers, maar ons oude systeem genereerde attestnummers in de vorm van jaartal/volgnummer. Bijvoorbeeld 2015/0004. Ik ben ook eens in de kast gaan kijken naar de fiscale attesten die ik zelf krijg, en die zijn gelijkaardig genummerd. Dus ik vermoed dat dat zo dan wel zal moeten in België.

Door hook_cdntaxreceipts_alter_receipt te implementeren, verander ik het nummer van het attest alvorens het gemaakt en bewaard wordt. Dit gebeurt alweer op een erg inefficiënte manier, die bovendien niet thread safe is. Maar ook dit werkt voor ons; misschien werkt het ook wel voor jullie. (Ruimte voor verbetering is er altijd.) De code:

/**
 * Implements hook_cdntaxreceipts_alter_recepit.
 *
 * Calculates receipt number for receipt.
 *
 * @param type $receipt
 */
function chirocontribution_cdntaxreceipts_alter_receipt(&$receipt) {
  $year = _chirocontribution_receipt_year($receipt);
  if ($year == NULL) {
    throw new Exception("All contributions should have receive_date in the same year.");
  }

  // Only generate a receipt number if it does not exist yet.
  // (see #4842).

  if (!$receipt['is_duplicate']) {
    // FIXME: this is slow, and not thread safe.
    // TODO: make number of digits after slash configurable.
    $sql = "SELECT MAX(CAST(SUBSTRING(receipt_no, 6) AS UNSIGNED)) FROM cdntaxreceipts_log WHERE receipt_no LIKE %1";
    $params = array(
      1 => array( $year . '/%', 'String' ),
    );
    $last = CRM_Core_DAO::singleValueQuery($sql, $params);
    $next_no = $year . '/' . str_pad($last + 1, 4, 0, STR_PAD_LEFT);
    $receipt['receipt_no'] = $next_no;
  }
}

/***
 * If all contributions of the receipt are in the same year, return that year.
 *
 * Otherwise return NULL.
 */
function _chirocontribution_receipt_year($receipt) {
  $result = NULL;

  foreach ($receipt['contributions'] as $contribution) {
    $contribution_year = date('Y', strtotime($contribution['receive_date']));
    if ($result == NULL) {
      $result = $contribution_year;
    }
    else if ($result != $contribution_year) {
      return NULL;
    }
  }
  return $result;
}

Achteraf zal blijken dat CDNTaxReceipts de fiscale attesten zal bewaren met een bestandsnaam die het attestnummer bevat. Dat is wat vervelend met die slash, maar daar werken we straks nog rond. Wat je ook kunt doen, is een punt (.) gebruiken in plaats van een slash, in dat geval vervang je de slashes in de $params van de select query en in $next_no door een punt.

Configuratie

De extensie is behoorlijk configureerbaar, en dat doe je via het CiviCRM menu: 'beheer', 'civicontribute', 'cdntaxreceipts'.

Attesten maken

Dit is min of meer onze gebruikershandleiding:

1. Klik op 'Contacten', 'Geavanceerd zoeken'.

2. Klik het flapje 'Bijdragen' open.

3. In de sectie 'Bijdragen', kies je bij 'Ontvangstdatum' 'Vorig jaar', en je zorgt ervoor dat je enkel de contributies filtert die relevant zijn voor de fiscale attesten. (Bij ons zijn dat die contributies met als 'Financieel type' kies 'Donatie', maar ik weet niet of dat iets universeels is).

4. Klik 'Zoeken'. Je krijgt een lijst met alle personen die vorig jaar een gift deden.

5. Klik 'Alle X records' aan bij 'Selecteer records'.

6. Klik onder 'Acties' op 'Issue Annual Tax Receipts'.

7. Wacht even.

8. Kijk na of het juiste werkjaar is aangevinkt.

9. Klik 'Issue tax receipts'.

10. Wacht lang.

11. Download de PDF.

(Je kunt ook een preview maken van de tax receipts, maar ten gevolge van hoe we de attestnummers berekenen, hebben in die preview alle attesten hetzelfde nummer.)

Attesten herafdrukken

1. Zoek de persoon op waarvoor het fiscaal attest afgedrukt moet worden.

2. Klik op het flapje 'Bijdragen'.

3. Klik op 'weergeven' achter een gift uit het jaar waarvoor het attest herafgedrukt moet worden.

4. Klik op de knop 'Tax Receipt'.

5. Klik op de knop 'Re-Issue Tax Receipt'.

6. Bewaar de PDF.

Rapportering

De gegevens van de fiscale attesten moeten doorgegeven worden aan de overheid, en dat gebeurt bij ons via een csv-export. Op die export staat telkens een attestnummer, naam, adres en totaalbedrag. De overheid zou graag ook het rijksregisternummer hebben op dat overzicht, maar de privacywetgeving zegt ons dan weer dat we geen rijksregisternummers mogen opvragen of bewaren. Wie dat begrijpt, mag me dat eens komen uitleggen.

In CDNTaxReceipt zit een template voor CiviReport, maar daar staat geen adres op. Het is waarschijnlijk niet moeilijk om die template aan te passen, zodat er wel een adres op staat. Maar toen ik aan dat rapport begon te werken, was ik helemaal vergeten dat die template bestond. Ik ben nogal eens verstrooid of vergeetachtig, helaas. Ik heb dus een custom search gemaakt.

Custom searches maken is een vak apart, en de documentatie is in mijn ogen erg onduidelijk. Misschien schrijf ik daar bij gelegenheid ook nog eens een blog post over.

Ik zal alleszins de query meegeven die ik gebruik voor de custom search; desnoods kun je hem runnen op je database, en met dat resultaat iets verder doen. Voor 2016 ziet de query er zo uit:

SELECT tr.receipt_no, c.display_name, a.street_address, a.postal_code, a.city, tr.receipt_amount
FROM cdntaxreceipts_log tr
JOIN civicrm_contact c ON tr.contact_id = c.id
LEFT OUTER JOIN civicrm_address a ON c.id = a.contact_id and a.is_primary = 1
WHERE tr.is_duplicate = 0 AND issue_type = 'annual'
AND tr.receipt_no LIKE '2016/%'
ORDER BY receipt_no

Als je een custom search implementeert, dan zet je uiteraard niet letterlijk '2016/%' in je query, je gebruikt een query-parameter (alweer zo'n ongedocumenteerd iets in CiviCRM-land, maar in de hook-implementaties bovenaan deze post worden ze ook gebruikt). Die parameter vul je dan in op basis van het jaar dat de gebruiker kiest in je search form. Een aparte blog post dringt zich meer en meer op ;-)

De slash in de query, is dezelfde slash die we gebruiken in het attestnummer. Als je dus een ander scheidingsteken gebruikt in je attestnummer, pas dat dan ook aan in de waarde van je query parameter.