Donorfy integration
This page covers how the website integrates with Donorfy to enable donations and the Friends of Wag functionality.
Settings
WordPress Dashboard > Donorfy Integration Settings
The following are entered on this screen:
- Donorfy API access settings.
- reCaptcha site key for the Donorfy Stripe integration.
- Notification email addresses - Donorfy tasks, FOW sign up
Access to the Donorfy REST API is restricted by IP address (range) and is set up via the Donorfy Web App. Settings > Configuration > API Settings
Plugin Logs
WordPress Dashboard > Donorfy Integration Settings > Donorfy Integration Logs
To aid with trouble shooting the plugin has its own logging mechanism to track the operation of the process handlers. This logging can be disabled if required.
The notification emails sent from the plugin to the nominated email addresses with a summary of the processing are also logged - this logging can not be disabled as there may be issues with summary emails not being received.
The current day's plugin and notification log can be viewed from this screen. Previous day days' logs stored in the folder 'logs' in the plugin folder.
How the integration works
Version 0.0.1.0 of the Donorfy Integration Plugin has been substantially refactored.
The code now is object oriented based but most importantly the creation of duplicate Individual constituent records due to timing issues is now avoided by implementing a solution whereby Donorfy is polled to check that its own WebWidget handler has completed execution, i.e. creating or otherwise updating an existing Individual constituent record, before the post submission handler attempts to carry out its processing.
The request for the requirement of a minimum donation amount to be made to qualify for the option of requesting a pin badge has been removed.
In addition some additional features to allow WAG administrators to more fully test the integration have been made more readily accessible to them.
The code inserted by the [bl_wag_donorfy] shortcode on the pages displaying the Donorfy Web Widget snippets has not been fundamentally altered - some javascript bugs have been addressed. As before, the code adds an event handler to the form submission button so that when clicked the data required to set the appropriate donorfy activity and active tags are pushed via an AJAX POST call to the server so that it can be stored in the PHP Session variable.
Integration implementation overview
In all three cases of Friend of Wag signup the process follows the same pattern.
When the user submits the donation form a Javascript function is called which collects and pushes the Constituent and Activity data to the server, storing it in a PHP Session variable.
When the payment has successfully completed and the user is redirected to the thank you page the Javascript inserted via the shortcode [bl_wag_donorfy_push] makes another AJAX POST call which is fired on page load which instructs the server to begin the main handling process handleUpdateDonorfy() (class-handler.php).
This post submission process checks that the previously submitted Constituent and Activity data stored in the PHP Session variable is complete and if it is then checks that the Donorfy WebWidget has completed its handler - that is that the Individual data held in the session variable matches present in WAG's Donorfy Instance.
The handler will poll 7 times, backing off a longer time each attempt until it either receives back the id of a matching constituent or null - in which event it is assumed that for some reason Donorfy's own WebWidget handler has failed. The user is not informed of this - but a notification is sent by the post submission handler to the nominated person at WAG.
If a match was found the handler will continue and carry out the next necessary steps. These steps depend the on kind of Sign Up process being handled.
Donorfy's WebWidget handler will add the ActiveTags to the Individual record it creates as they are passed with the form data.
The Renewal Activity is added where the payments made are one-off, i.e. via Stripe.
Individual Friend of Wag
- Set communication preferences to allow only emails
- Set Individual Timeline Activity (Friend of Wag sign up & Renewal)
Corporate Friend of Wag
- Update ActiveTags of individual record (Membership_ConnectedFoW)
- Set communication preferences to allow only emails
- Check if record exists of type 'Company'
- if not create it
- Add ActiveTags to Company record
- Set communication preferences for Company record to disable all channels
- Set connection between Company record and Individual record (employee)
- Set Company Timeline Activities (Corporate Friend of Wag sign up & Renewal)
Community Friend of Wag
- Update ActiveTags of individual record (Membership_ConnectedFoW)
- Set communication preferences to allow only emails
- Check if record exists of type 'Care Home'
- if not create it
- Add ActiveTags to Care Home record
- Set communication preferences for Care Home record to disable all channels
- Set connection between Care Home record and Individual record (employee)
- Set Care Home Timeline Activities (Community Friend of Wag sign up & Renewal)
In all cases a notification email is set at the end of the handling process - they are currently sent to donorfy@wagandcompany.co.uk the address to which they are sent is set in the Donorfy Integration Settings section on the WordPress dashboard.
Payment information
As they are created by the Donorfy WebWidget handler, the activity timeline entries relating to payments, Stripe payments or GoCardless RPI, are attached to the Individual Constituent record relating to the payee. These need to be manually reassigned to the company or care home record by a member of the Wag team.
General Donation - Stripe
ActiveTag: Engagement_Supporter
The user completes the donation form.
The Donorfy WebWidget handling code processes the form. No meaningful session data is passed to the server.
The user is directed on successful completion of the process is directed to the thank you page. As this is a donation and not a Friend of Wag sign up there is no session data to act upon.
Donorfy's documentation on Donations and existing Constituents can be found here: https://donorfy.zendesk.com/hc/en-us/articles/115000016389-Web-Widgets-Donations-and-Existing-Constituents
The following information pertains to the previous version of the plugin (0.0.0.15) and is retained here in case of roll back.
Friends of Wag Sign Up - Individual
ActiveTag: Engagement_FriendofWag,Membership_NoBadge/Membership_Badge
The user completes the donation form and presses the submit button.
The bespoke Javascript updates the Membership_* tag as appropriate based on whether they have opted to have one (Badge/NoBadge).
The data associated with the Friend of Wag sign up activity is collected for later processing by the post-submission-handler.
The Donorfy WebWidget handling code processes the form.
The user is redirected to the thank you page.
The post-submission-handler code is executed. It uses the Donorfy API to interact directly with Wag's Donorfy Database.
- The handler attempts to look up the id of record created/updated by Donorfy - Due to timing issues, this step may fail which means that the attempt to attach the Friend of Wag sign up activity would fail - this is mitigated as outlined below.
- If the record id look up has succeeded then the Friend of Wag sign up activity is added to the constituent's timeline and the contact details are updated to match what was submitted in the form.
- If the record id look up fails then the handler pre-empts the Donorfy WebWidget handler by creating a new Individual record.
- If the amount donated is £10 or more the Friend of Wag sign up activity and task is included in the signup activity.
- A notification email is sent from the post-submission-handler containing a summary of the registration information.
The following Friend of Wag sign up activity fields are automatically set using the data submitted in the form:
- Eligible for Pin Badge? - set to true if £10 or more is donated, otherwise false.
- Opted to have Pin Badge? - set to true if the user has opted to receive a pin badge, otherwise false.
Community/Corporate Friends of Wag Sign Up
Guidance for contacts when a Donorfy record already exists within the Wag system.
When processing a Friend of Wag Sign Up an existing constituent (Company/Care Home/Individual) record's contact details (address, postcode, phone & email) will be updated with the contact details entered on the sign up form. Company/Care Home contacts who will be responsible for signing up their organisation should be guided to enter the organisation's address and their work email on the form.
Checking for an existing Organisation
The post-submission-handler performs a failover look up that first checks for the prior existence of an Organisation's record by
- organisation name and postcode, and then if that fails
- by organisation name only
before determining that there is no pre-existing match and that a new record needs to be created rather than working with an existing one.
Working with Individual Records
The method for handling Friend of Wag Sign Ups has been designed to attempt to pre-empt the Donorfy WebWigdet's creation of an individual record since due to timing issues the post-submission-handler may end up looking for a record before the WebWidget code has created it.
By taking responsibly for the creation of the record the handler can ensure that the appropriate Sign up Activities can be consistently added to a record's timeline and that for organisations connections can be set up between an organisation and the individual employee who has completed the sign up form.
It also means that (ideally) only two records will be created as a result of an organisation signing up. This document covers why, due to timing differences outside our control, two individual constituent records might sometimes be created and the steps to take to resolve this.
Checking for Individual Records
The function uses the Donorfy API call which checks whether a matching individual record exists uses the following information submitted via the sign up form, the key values are the ones highlighted:
- First name
- Last name
- Address Line1
- Postcode
- Email address
The Donorfy API call for duplicates returns a score for potential matches:
- Matching Email + First Name + Last name results in a score of 14 (the maximum is 15)
- Matching Email + First Name results in a score of 13
- Matching Email + Last Name results in a score of 12
Since email, first name and last name required fields the function used to check for matches requires a score of greater than 13.
For individual's records these contact details need to be stored under the 'personal' section to be used in Donorfy's duplicate check.
Donorfy's own documentation can be found here:
- https://donorfy.zendesk.com/hc/en-us/articles/360007017038-Finding-Potential-Duplicates-
- https://donorfy.zendesk.com/hc/en-us/articles/360003416798-Duplicates
Friends of Wag Sign Up - Community
ActiveTag: Engagement_CommunityFriendofWag,Membership_CommunityNoLogo
The user completes the donation form and presses the submit button.
The bespoke Javascript updates the Membership_* tag as appropriate based whether the user wants their organisation's name and logo to appear on the Wag site.
The data associated with the Community Friend of Wag sign up activity is collected for later processing by the post-submission-handler.
The Donorfy WebWidget handling code processes the form.
- The WebWidget code creates/updates an Individual Constituent record (ideally - it has been observed that this has not occurred by the time the post-submission-handler executes)
The user is redirected to the thank you page.
The post-submission-handler code is executed. It uses the Donorfy API to interact directly with Wag's Donorfy Database.
- the handler first checks to see if a record exists for the Individual from this Care Home
- if it can't find one it uses the API to create a record for them and adds the contact details submitted in the form under the 'Personal' section
- the handler checks to see if a record already exists for this Care Home (based on organisation name and postcode)
- if a record is not found then an API call is made to create a new Care Home record using the information submitted in the form.
- if a record is found then an API call is made to update the record with the address details submitted in the form.
- The Individual record is connected to Care Home record as an Employee and tagged with Engagement_CommunityFriendofWag Membership_ConnectedFoW.
- The Community Friend of Wag sign up activity is added to the Care Home constituent's timeline.
- If appropriate, a Friends of Wag Renewal Reminder activity is added to the Care Home timeline.
- A notification email is sent from the post-submission-handler containing a summary of the registration information
Within Donorfy the financial transaction will most likely need to be assigned to the Care Home record.
The following Community Friend of Wag sign up activity fields are automatically set using the data submitted in the form:
- Name / Logo to be added to website?- set to true if the user has opted to have their organisations name and logo on the site, otherwise false.
Friends of Wag Sign Up - Corporate
ActiveTag: Engagement_CorporateFriendofWag,Membership_CorporateNoLogo and either Membership_Corporate1, Membership_Corporate2 or Membership_Corporate3
The user completes the donation form and presses the submit button.
The bespoke Javascript updates the Membership_* tag as appropriate based whether the user wants their organisation's name and logo to appear on the Wag site.
The data associated with the Corporate Friend of Wag sign up activity is collected for later processing by the post-submission-handler.
The Donorfy WebWidget handling code processes the form.
- The WebWidget code creates/updates an Individual Constituent record (ideally - it has been observed that this has not occurred by the time the post-submission-handler executes)
The user is redirected to the thank you page.
The post-submission-handler code is executed. It uses the Donorfy API to interact directly with Wag's Donorfy Database.
- the handler first checks to see if a record exists for the Individual from this Company
- if it can't find one it uses the API to create a record for them and adds the contact details submitted in the form under the 'Personal' section
- the handler checks to see if a record already exists for this Company (based on organisation name and postcode)
- if a record is not found then an API call is made to create a new Company record using the information submitted in the form.
- if a record is found then an API call is made to update the record with the address details submitted in the form.
- The Individual record is connected to Company record as an Employee and tagged with Engagement_CorporateFriendofWag Membership_ConnectedFoW and the relevant membership level tag.
- The Corporate Friend of Wag sign up activity is added to the Company constituent's timeline.
- If appropriate, a Friends of Wag Renewal Reminder activity is added to the timeline.
- A notification email is sent from the post-submission-handler containing a summary of the registration information
Within Donorfy the financial transaction will most likely need to be assigned to the Company record.
The following Corporate Friend of Wag sign up activity fields are automatically set using the data submitted in the form:
- Name / Logo to be added to website?- set to true if the user has opted to have their organisations name and logo on the site, otherwise false.
- Eligible for visit to care home? - set to true if the amount donated (per year/one off) is £250 or greater, otherwise false.
- Eligible for Paws the Pressure session? - set to true if the amount donated (per year/one off) is £500 or greater, otherwise false.
- Eligible for visit to workplace by elderly friend? - set to true if the amount donated (per year/one off) is £2000 or greater, otherwise false.
Friends of Wag Sign Up - Corporate Pledge
ActiveTag: Engagement_CorporateFriendofWag,Membership_CorporatePledge
The Corporate Pledge process does not involve any payments so the pledge details are captured using a form created using Contact Form 7. The Donorfy Web Widget is not involved in the process, as a result it may be necessary to create the Individual Constituent Record which the Donorfy Web Widget handler would otherwise create (if one does not already exist).
The user completes the donation form and presses the submit button.
The handler handleCorporatePledge() (hooked into wpcf7_before_send_mail) is executed. It uses the Donorfy API to interact directly with Wag's Donorfy Database.
- the handler first checks to see if a record exists for the Individual from this Company
- if it can't find one it uses the API to create a record for them.
- the handler checks to see if a record already exists for this Company (based on organisation name and postcode)
- if a record is not found then an API call is made to create a new Company record using the information submitted in the form.
- if a record is found then an API call is made to update the record with the address details submitted in the form.
- The Individual record is connected to Company record as an Employee.
- The Corporate Friend of Wag Pledge sign up activity is added to the Company constituent's timeline.
- The Friends of Wag Renewal Reminder activity is added to the Company constituent's timeline.
- A notification email is sent from the post-submission-handler containing a summary of the registration information
- Whether the logo is to be shown is toggled via the session variable.
The following Corporate Friend of Wag Pledge sign up activity fields are automatically set using the data submitted in the form:
- Name / Logo to be added to website?- set to true if the user has opted to have their organisations name and logo on the site, otherwise false.
- Eligible for visit to care home? - set to true if the amount donated (per year/one off) is £250 or greater, otherwise false.
- Eligible for Paws the Pressure session? - set to true if the amount donated (per year/one off) is £500 or greater, otherwise false.
- Eligible for visit to workplace by elderly friend? - set to true if the amount donated (per year/one off) is £2000 or greater, otherwise false.
On successful submission of the form Contact Form 7 redirects to the thank you page where the logo submission form is displayed if appropriate.
Due to continued divergence between Contact Form 7 and Bootstrap for Contact Form 7 version 5.3.2 of Contact Form 7 is recommended. If it does become necessary to redeploy the form using another form builder, such as Gravity Forms, the end points for GF have been included in the plugin.
Related Donorfy Documentation
https://donorfy.zendesk.com/hc/en-us/articles/360007017038-Finding-Potential-Duplicates-
About part way down the following article there is a table detailing how matches are scored
Archived records are excluded from Donorfy's DuplicateCheckPerson api call.
https://donorfy.zendesk.com/hc/en-us/articles/360003416798-Duplicates
Changes in Donorfy
If you make certain changes to the Donorfy set up this will impact the integration. This section explains when this can occur...
Changes to a field that currently passes data through from the website: if this changes the type of data passed through we will need to know what data is now being stored & passed through in this field to update the code. If the change is to the label of the field that doesn't impact the website.
Changes to a tag or a tag category used by the website: this can impact on the code as Donorfy does internal validation to check that a tag and tag category exist in the database. This means that any changes to these need to be updated in the website code, including case changes as it is case sensitive.
Changes to an activity name that is being supplied by the website: this is the same as a tag or tag category in that internal validation occurs so any changes, including case, need to be changed in the web code.
Changes to an Activity, its name or format made in Donorfy will require changes to the plugin handler code. The javascript which pushes the activity data to the session along with the code in class-internals.php for handling the formatting of the data in JSON will need to be updated.
Post Submission Tasks
Due to the changes in how the post submission handler operates it should no longer be necessary to carry out these tasks to merge duplicate records, these instructions are applicable when version 0.0.0.15 of the plugin or older is being used.
For Corporate/Community Sign ups when two individual records have been created.
This is due to a timing issue. Donorfy's Webwidget handling code runs independently of the post-submission-handler so sometimes it can be the case that between the time when the post-submission handler checks to see if the individual record exists and it makes the API call to create a record that the web widget has created a record. This results in two identical records, one of which is connected to the organisation and has the appropriate tags and another which is not connected but has the transaction or RPI associated with it.
Merging Individual Records.
In instances, outlined above, where two identical records have been created they can be merged as follows
Go to the record which is connected to the organisation
From the Manage button at the top of the screen click Merge Constituent
Click on Find Source Constituent
In the input box start typing the name of the constituent.
Select the matching constituent with the different #number (this record will be automatically archived by the merging process)
The click on the red Merge button at the far right of the page.
This will merge the records retaining the activity timeline items, tags and RPI item.
Reassigning Stripe Transactions
- Click on timeline and selecting the transaction
- Within the transaction, click on Manage and then Reassign.
- select the appropriate Care Home/Company record
- and then Reassign
Assigning Stripe Transactions
- go to Financial
- click on Online Donations
- Click to assign the Company/Care Home record rather than the individual.
Connecting Recurring Payment Instructions
- Go to the individual record
- click on Timeline
- click on Recurring Payment Instruction to show the details
- click on the 'Connected to' button
- In the Find Constituent Modal window enter the name of the organisation with you wish to connect the RPI with.
- When you view the timeline for the Company/Care home you will now see a Connected Recurring Payment Instruction.
Testing
Verifying Constituent and Activity Data
A logged in administrator of the site is able to override any donation form's minimum donation amount and donate test values of £1.
When they hover the donation form's submit button the data which will be sent to the server will be displayed so that they can verify the active tags and activity data which will be processed and sent to Donorfy, as well as the constituent data which will be used to check for existing records.
When the form is submitted this data is pushed to the server via an AJAX POST call.
Manual Testing
To carry out a manual push of the data to Donorfy the donation form is completed by a logged in administrator as usual but omit the title field so that the form validation will fail and not be submitted to the Donorfy WebWidget handler.
/dev_session/
This page is only viewable by a logged in administrator and will show the data that is being held in the PHP Session variable.
Using the session data found it will run some preliminary checks on the data. It can also be used to ensure that the link with Donorfy is functioning.
Clear Session - empties the PHP Session variable.
Handle Data - manually initiates the Donorfy update process.
Shortcodes
The following shortcodes are fundamental to the integration with Donorfy, if they are omitted from the donation/thank you pages then the integration with Donorfy will cease to function.
bl_wag_donorfy
The bl_wag_donorfy shortcode is used for bootstrapping the WebWidget Form and bespoke Javascript code.
- min_amount is to be set to the minimum amount accepted by the form. For testing it is set to 1. If amount has not been passed on the query string, or is lower than min_amount the amount field on the form will be set to min_amount, otherwise it will be set to the value of amount.
- tags is set to the appropriate Engagement_* tag for this form.
- redirect_to is used on Stripe forms and is set to the relative url for the appropriate thank you page.
- renew is used and set to 1 only in instances where a renewal reminder activity is to be attached to a timeline.
bl_wag_donorfy_stripe
The bl_wag_donorfy_stripe shortcode is required on the pages with Stripe forms, it handles the set up required for enabling reCaptcha on the page.
bl_wag_donorfy_carehome_autocomplete
This enables autocomplete on the organisation field based on the names of Care Homes with records already in the system. This is to help ensure consistency when care homes who are already on the system register as a Friend of Wag, so that their existing record is updated rather than a new, duplicate being added.
bl_wag_donorfy_company_autocomplete
This enables autocomplete on the organisation field based on the names of Companies with records already in the system. This is to help ensure consistency when companies who are already on the system register as a Friend of Wag, so that their existing record is updated rather than a new, duplicate being added.
bl_wag_donorfy_push
This shortcode is required on the thank you pages it calls the post-submission-handler which handles the pushing of data to Wag's Donorfy Database using Donorfy's API.
Donation Page
/support-us/donate/make-your-donation/
This page contains a Donorfy WebWidget form which uses Stripe.
[bl_wag_donorfy min_amount="1" tags="Engagement_Supporter" activity_type="" constituent_type="Individual" campaign="" redirect_to="/support-us/donate/thank-you/"] [bl_wag_donorfy_stripe]
Friend of Wag - Individual
/support-us/friends-of-wag/become-a-friend-of-wag/direct-debit/
[bl_wag_donorfy min_amount="1" tags="Engagement_FriendofWag" pin_badge="1" activity_type="Friend of Wag sign up" constituent_type="Individual" campaign="Friends of Wag"]
Friend of Wag - Community - Direct Debit
[bl_wag_donorfy min_amount="1" tags="Engagement_CommunityFriendofWag" campaign="Community Friends of Wag" activity_type="Community Friend of Wag sign up" constituent_type="Care Home"] [bl_wag_donorfy_carehome_autocomplete]
Friend of Wag - Community - Stripe
[bl_wag_donorfy min_amount="1" tags="Engagement_CommunityFriendofWag" renew="1" campaign="Community Friends of Wag" activity_type="Community Friend of Wag sign up" constituent_type="Care Home" redirect_to="/support-us/friends-of-wag/community-friends-of-wag/thank-you/"] [bl_wag_donorfy_stripe] [bl_wag_donorfy_carehome_autocomplete]
Friend of Wag - Corporate - Direct Debit
[bl_wag_donorfy min_amount="1" tags="Engagement_CorporateFriendofWag" activity_type="Corporate Friend of Wag sign up" constituent_type="Company" campaign="Corporate Friends of Wag"] [bl_wag_donorfy_company_autocomplete]
Friend of Wag - Corporate - Stripe
[bl_wag_donorfy min_amount="1" tags="Engagement_CorporateFriendofWag" renew="1" activity_type="Corporate Friend of Wag sign up" constituent_type="Company" campaign="Corporate Friends of Wag" redirect_to="/support-us/friends-of-wag/corporate-friends-of-wag/thank-you/"] [bl_wag_donorfy_stripe] [bl_wag_donorfy_company_autocomplete]
Friend of Wag - Corporate - Pledge
/support-us/friends-of-wag/corporate-friends-of-wag/fundraising-pledge/
This page uses a ContactForm 7 form
[contact-form-7 id="217" title="Corporate Pledge"] [bl_wag_cf7_redirect redirect_to="/support-us/friends-of-wag/corporate-friends-of-wag/thank-you/"] [bl_wag_donorfy_company_autocomplete]
Thank You Pages /Post Submission Handlers