From a53e161eeef40864dbe1c1ca9407ac477a55b87a Mon Sep 17 00:00:00 2001 From: "Matthew Wire (MJW Consulting)" Date: Thu, 22 Aug 2019 01:31:37 +0100 Subject: [PATCH] Update docs for 3.3 --- README.md | 101 ++++------------------------------ docs/batches.md | 20 +++++++ docs/index.md | 14 +++++ docs/release/release_notes.md | 21 +++++++ docs/setup.md | 30 ++++++++++ docs/submission.md | 13 +++++ docs/tax.md | 11 ++++ info.xml | 6 +- mkdocs.yml | 23 ++++++++ 9 files changed, 145 insertions(+), 94 deletions(-) create mode 100644 docs/batches.md create mode 100644 docs/index.md create mode 100644 docs/release/release_notes.md create mode 100644 docs/setup.md create mode 100644 docs/submission.md create mode 100644 docs/tax.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index 2e41faf..b3b70a3 100644 --- a/README.md +++ b/README.md @@ -1,102 +1,21 @@ # UK GiftAid Extension for CiviCRM -This extension adds custom fields and logic for managing the UK Gift Aid scheme. +This extension adds a profile, custom fields and code for managing the UK Gift Aid scheme. -### Install GiftAid Extension -See [Here](https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/ "CiviCRM Extensions Installation") for full instructions and information on how to set and configure extensions +The extension is licensed under [AGPL-3.0](LICENSE.txt). -### Upgrade GiftAid Extension -These instructions assume that you are only upgrading the Gift Aid module from v2.x to higer and not upgrading from v1.0 and are running version 4.4.x or higher CiviCRM. +## Requirements -1. If you navigate to the extension list in your install, CiviCRM should display a message stating that a newer version of the Gift Aid extension is available for download. +* PHP v7.x +* CiviCRM 5.13+ - Alternatively you can download the latest version of the Gift Aid extension from the Compucorp Github: [Download Gift Aid from Git](https://github.com/compucorp/uk.co.compucorp.civicrm.giftaid "GiftAid Github") +## Installation -2. Once installed you should receive a message bubble indicating that your Gift Aid module code has changed and an upgrade script is required to be run. - - Click the link in the message bubble to run the Gift Aid 2.1 upgrade script. - - The upgrade script will migrate all the previous batch names into an option group called "GiftAid Batch Name" as well as remove the previous registered report and will re-register a new Gift Aid report. (there's no need to do that manually anymore! woohoo! - -3. Give yourself a pat on the back... You're all done! - -### Configuration - -1. Edit the settings for the ‘Gift Aid’ data group here http://www.example.com/civicrm/admin/custom/group?reset=1 - -2. Click settings and then choose the specific contribution type(s) you want gift aid to be available for i.e “Donation” - -3. [3.1] Go to Gift Aid settings page via *Administer->CiviContribute->GiftAid->Settings* and select the financial types that should be considered as donation or leave it as default to enable Gift Aid for all financial types. - -4. [3.0] **[Important]** A new type of Gift Aid declaration is applied to covers both present and future donation and the donations a donor made in the past four years from the declaration date as long as the Gift Aid claim amount does not exceed tax amount. The old 'Yes' declaration is reserved to cover any old declarations donors made. Settings for the declatation options can be modified in the 'UK Taxpayer Options' list here: http://www.example.com/civicrm/admin/options?reset=1 - -5. [3.0] **[Important]** From Gift Aid 3.0 onwards, a new mechanism is introduced to marking donations from the past 4 years eligible to Gift Aid based on the new declaration type. **Present and future donations will not be affected by this new mechanism.** A scheduled job will be used to handle the 100 past donation records per run. To enable this scheduled job, please go to http://www.example.com/civicrm/admin/job and enable the job 'Process Gift Aid eligible donations'. - -6. [3.1] Gift Aid amount is calculated automatically when the contribution is created/updated. - - -### Configure the Gift Aid Profile and disclaimer - -You'll need to add a Gift Aid profile to any contribution forms that you want to use to collect "Gift-aid-able" contributions. - -1. Go to ‘Administer -> Custom Data and screens -> profiles’ to edit the info text or fields to display so it’s suits your organisation’s needs. - -2. Create Online Contribution Page. Go to ‘Contributions -> Manage Contributions Pages’ to add a new contribution page. See here for more details on how to do this: - -3. Add gift aid form to Contribution Form. In the profiles section of your contribution page ensure you include ‘Gift Aid’ in the top/bottom of your page. Or you can add the profile to an existing contribution page. Go to Contributions > Manage contribution pages. Select your contribution page > Configure > Include profiles. - - *Note: make sure there is no duplicated in fields in the form you are asking people to complete i.e name and address fields.* - -4. Now, when new contributions are made online with Contribution pages using the Gift Aid profile, two things will happen. The system will firstly store that the donation was "eligible for Gift Aid" and secondly the system will check whether that donor has an existing Gift Aid declaration and if not will make a new record against the contact. - -Having collected the relevant information about the donation you are now ready to create your batch and submit to HMRC. - -### Creating and managing your batch - -Having collected contributions with the appropriate Gift Aid profile enabled you can now create a batch to be submitted to HMRC by using GiftAid report. To do this you first need to create a batch. Instructions on how to do this are below - -1. To add a contribution to the Gift Aid Batch, from the main menu go to ‘Contributions -> Find Contributions’. When you have a list of your contributions, select the contributions using the checkbox to the left of each one and then select ‘Add to Gift Aid Batch’ from the drop down list and hit Next name your batch and click the “add to batch button” at the bottom of the screen. - -2. The module will indicate which contributions are eligible to be placed in a batch. These are contributions where the donor has a valid Gift Aid declaration at the time of the contribution, a valid UK address with postcode and where the contribution is not already in a batch. A valid UK address with postcode needs to be input by the donor at the point of signing up. - -3. You can use the 'Process eligible donations manually' function to process eligiblity of donations instantly if some donations are not yet marked as eligible when adding to batch. - - -Remove contributions from Gift Aid batch - If you need to remove a contribution from a Gift Aid batch, select the contributions, then select “Remove from gift aid batch” and hit ‘Go’. Then you will see the following information summarised: - -* The number of contributions selected. - -* The number of contributions removed from the batch. - -* The number of contributions not yet added to any batch - -**Note: contributions submitted to the HMRC should not be removed from a batch** - -### Submission to HMRC - -Create Report - After successfully creating a batch of contributions eligible for Gift Aid go to “Reports -> All Reports “ and click “new report” which will bring you here - -http://www.example.com/civicrm/report/template/list?reset=1 - -1. Select UK GiftAid report option from the list and continue. - -2. Select the name of the batch you have just created and click preview report. - -3. Once you are happy with your report you can save/print it and submit it to the HMRC. - -### Changing the basic rate of Tax -From v2.0 of the module you are now able to change the rate of tax that the module uses to calculate the Gift Aid amount reclaimable and stored in the Gift Aid amount field. The percentage used in the calculation is now stored in an option group labeled: - -The GiftAid basic rate tax - -You can edit this by navigating to administration>>>civigiftaid>>>basicrateoftax link in the admin menu. You can also edit the option value in the group.“Administer” system settings ‘Option groups’. - -Changing the rate of tax (shown as a percentage) will not affect past Gift Aid amounts calculated, but only the new amounts calculated when new contributions are added to a batch. +See: https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/#installing-a-new-extension ### Support -CiviCRM Extension Page: https://civicrm.org/extensions/gift-aid-extension-uk +Documentation: [docs/index.md](/docs/index.md) -Please contact the follow email if you have any question: -, +CiviCRM Extension Page: https://civicrm.org/extensions/gift-aid-extension-uk -Paid support for this extension is available, please contact us either via github or at +Please see info.xml for support information. diff --git a/docs/batches.md b/docs/batches.md new file mode 100644 index 0000000..bfe6e78 --- /dev/null +++ b/docs/batches.md @@ -0,0 +1,20 @@ +# Creating and managing your batch + +Having collected contributions with the appropriate Gift Aid profile enabled you can now create a batch to be submitted to HMRC by using GiftAid report. To do this you first need to create a batch. Instructions on how to do this are below + +1. To add a contribution to the Gift Aid Batch, from the main menu go to ‘Contributions -> Find Contributions’. When you have a list of your contributions, select the contributions using the checkbox to the left of each one and then select ‘Add to Gift Aid Batch’ from the drop down list and hit Next name your batch and click the “add to batch button” at the bottom of the screen. + +2. The module will indicate which contributions are eligible to be placed in a batch. These are contributions where the donor has a valid Gift Aid declaration at the time of the contribution, a valid UK address with postcode and where the contribution is not already in a batch. A valid UK address with postcode needs to be input by the donor at the point of signing up. + +3. You can use the 'Process eligible donations manually' function to process eligiblity of donations instantly if some donations are not yet marked as eligible when adding to batch. + + +Remove contributions from Gift Aid batch - If you need to remove a contribution from a Gift Aid batch, select the contributions, then select “Remove from gift aid batch” and hit ‘Go’. Then you will see the following information summarised: + +* The number of contributions selected. + +* The number of contributions removed from the batch. + +* The number of contributions not yet added to any batch + +**Note: contributions submitted to the HMRC should not be removed from a batch** diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..f417d6a --- /dev/null +++ b/docs/index.md @@ -0,0 +1,14 @@ +# Gift Aid + +This extension adds a profile, custom fields and code for managing the UK Gift Aid scheme. + +The extension is licensed under [AGPL-3.0](LICENSE.txt). + +## Requirements + +* PHP v7.x +* CiviCRM 5.13+ + +## Installation + +See: https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/#installing-a-new-extension diff --git a/docs/release/release_notes.md b/docs/release/release_notes.md new file mode 100644 index 0000000..ca3b7e0 --- /dev/null +++ b/docs/release/release_notes.md @@ -0,0 +1,21 @@ +## Release 3.3 +**In this release we update profiles to use the declaration eligibility field instead of the contribution. +This allows us to create a new declaration (as it will be the user filling in a profile via contribution page etc.) + and means we don't create a declaration when time a contribution is created / imported with the "eligible" flag set to Yes.** + +* Fix status message on AddToBatch. +* Fix creating declarations every time we update a contribution +* Remove duplicated option_group. +* Add documentation in mkdocs format (just extracted from README for now). + +## Release 3.2 +* Be stricter checking eligible_for_gift_aid variable type +* Fix issues with entity definition and regenerate +* Fix PHP notice +* Refactor addtobatch for performance, refactor upgrader for reliability +* Add API to update the eligible_for_gift_aid flag on contributions + +## Release 3.1 +* Be stricter checking eligible_for_gift_aid variable type + + diff --git a/docs/setup.md b/docs/setup.md new file mode 100644 index 0000000..9908985 --- /dev/null +++ b/docs/setup.md @@ -0,0 +1,30 @@ +# Setup and Configuration +## Configuration + +1. Edit the settings for the ‘Gift Aid’ data group here http://www.example.com/civicrm/admin/custom/group?reset=1 + +2. Click settings and then choose the specific contribution type(s) you want gift aid to be available for i.e “Donation” + +3. [3.1] Go to Gift Aid settings page via *Administer->CiviContribute->GiftAid->Settings* and select the financial types that should be considered as donation or leave it as default to enable Gift Aid for all financial types. + +4. [3.0] **[Important]** A new type of Gift Aid declaration is applied to covers both present and future donation and the donations a donor made in the past four years from the declaration date as long as the Gift Aid claim amount does not exceed tax amount. The old 'Yes' declaration is reserved to cover any old declarations donors made. Settings for the declatation options can be modified in the 'UK Taxpayer Options' list here: http://www.example.com/civicrm/admin/options?reset=1 + +5. [3.0] **[Important]** From Gift Aid 3.0 onwards, a new mechanism is introduced to marking donations from the past 4 years eligible to Gift Aid based on the new declaration type. **Present and future donations will not be affected by this new mechanism.** A scheduled job will be used to handle the 100 past donation records per run. To enable this scheduled job, please go to http://www.example.com/civicrm/admin/job and enable the job 'Process Gift Aid eligible donations'. + +6. [3.1] Gift Aid amount is calculated automatically when the contribution is created/updated. + +## Configure the Gift Aid Profile and disclaimer + +You'll need to add a Gift Aid profile to any contribution forms that you want to use to collect "Gift-aid-able" contributions. + +1. Go to ‘Administer -> Custom Data and screens -> profiles’ to edit the info text or fields to display so it’s suits your organisation’s needs. + +2. Create Online Contribution Page. Go to ‘Contributions -> Manage Contributions Pages’ to add a new contribution page. See here for more details on how to do this: + +3. Add gift aid form to Contribution Form. In the profiles section of your contribution page ensure you include ‘Gift Aid’ in the top/bottom of your page. Or you can add the profile to an existing contribution page. Go to Contributions > Manage contribution pages. Select your contribution page > Configure > Include profiles. + + *Note: make sure there is no duplicated in fields in the form you are asking people to complete i.e name and address fields.* + +4. Now, when new contributions are made online with Contribution pages using the Gift Aid profile, two things will happen. The system will firstly store that the donation was "eligible for Gift Aid" and secondly the system will check whether that donor has an existing Gift Aid declaration and if not will make a new record against the contact. + +Having collected the relevant information about the donation you are now ready to create your batch and submit to HMRC. diff --git a/docs/submission.md b/docs/submission.md new file mode 100644 index 0000000..3347354 --- /dev/null +++ b/docs/submission.md @@ -0,0 +1,13 @@ +# Submission to HMRC + +Create Report - After successfully creating a batch of contributions eligible for Gift Aid go to “Reports -> All Reports “ and click “new report” which will bring you here + +http://www.example.com/civicrm/report/template/list?reset=1 + +1. Select UK GiftAid report option from the list and continue. + +2. Select the name of the batch you have just created and click preview report. + +3. Once you are happy with your report you can save/print it and submit it to the HMRC. + +Or use the Gift Aid online extension to submit automatically: https://github.com/mattwire/uk.co.vedaconsulting.module.giftaidonline diff --git a/docs/tax.md b/docs/tax.md new file mode 100644 index 0000000..ce29bae --- /dev/null +++ b/docs/tax.md @@ -0,0 +1,11 @@ +# Managing the basic rate of Tax +From v2.0 of the module you are now able to change the rate of tax that the module uses to calculate the Gift Aid amount reclaimable and stored in the Gift Aid amount field. + +The percentage used in the calculation is now stored in an option group labelled: + +*The GiftAid basic rate tax* + +You can edit this by navigating to **Administer > CiviContribute > GiftAid > Gift Aid Basic Rate Tax** + link in the admin menu. + +Changing the rate of tax (shown as a percentage) will not affect past Gift Aid amounts calculated, but only the new amounts calculated when new contributions are added to a batch. diff --git a/info.xml b/info.xml index 67231ef..6c0fd22 100644 --- a/info.xml +++ b/info.xml @@ -9,15 +9,15 @@ https://github.com/mattwire/uk.co.compucorp.civicrm.giftaid - http://civicrm.org/licensing + https://civicrm.org/licensing AGPL MJW Consulting, Erawat Chamanont, Jamie Novick, Guanhuan Chen, Robin Mitra mjw@mjwconsult.co.uk, jamie@compucorp.co.uk, guanhuan@compucorp.co.uk - 2019-07-28 - 3.2 + 2019-08-22 + 3.3 beta 5.13 diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..288bd05 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,23 @@ +site_name: Smart Debit (Direct Debit provider in the UK) +repo_url: https://github.com/mattwire/org.civicrm.smartdebit +theme: material +markdown_extensions: + - attr_list + - admonition + - def_list + - codehilite + - toc(permalink=true) + - pymdownx.superfences + - pymdownx.inlinehilite + - pymdownx.tilde + - pymdownx.betterem + - pymdownx.mark + +pages: +- Release Notes: release/release_notes.md +- Introduction: index.md +- Setup and Configuration: setup.md +- Creating and managing your batch: batches.md +- Submission to HMRC: submission.md +- Managing the basic rate of Tax: tax.md +