This article explains set up and mappings for Bloomerang Fundraising’s DonorPerfect integration.

Before getting started, you will need to request an API key from DonorPerfect. You can contact DonorPerfect Support by email at [email protected] to request one.

To set up the integration, click the Integrations icon along the left side of your screen.

Locate the DonorPerfect tile in the CRM section and click Connect.

Enter the API Key you obtained from DonorPerfect, and then click Connect again.

You'll be taken to a screen where you can configure your settings.

Settings are organized into tabs along the left side of the page. You'll be prompted to Save after you make changes on a tab.

On the General tab, use the calendar to choose the Export Data Starting On date. If you'd like to export data from a date prior to the current date, you can set your calendar accordingly so historical transaction data will be exported.

The Export Data Ending On field lets users input a date to end exports from the integration. Leave this field blank if you want the integration to export indefinitely.

In the Frequency drop-down, choose Manual, Hourly, Daily, or Every 15 Minutes exports.

If you choose Daily exports, you’ll also be able to choose the time (Eastern) for the export to occur.

Beneath the Frequency drop-down is the Maximum Transactions field. This required field specifies the maximum number of transactions Bloomerang Fundraising will export to the integration at a single time. The default setting is to export a maximum of 100 transactions. You can adjust this number higher or lower, but the number field cannot be blank.

Also note that smaller limits provide a safer export, reducing the likelihood of export issues due to a service interruption.
​

The next tab houses the Export settings.

Exclude Offline & Matching Donations, when toggled on, excludes offline and matching donations from exports.

The Exclude Facebook Donations toggle excludes donations made through Facebook.

The Enable Soft Credits toggle enables the exporting of soft credits for peer-to-peer transactions.

The Export GiftAssist as Separate Line Item toggle makes it possible to export GiftAssist as a separate line item from the donation itself.

This is particularly useful when exporting transactions that have multiple line items, such as an event registration with an additional donation. If Export GiftAssist as Separate Line Item is enabled, the GiftAssist amount will appear as a separate part of the transaction. If Export GiftAssist as Separate Line Item is not enabled, GiftAssist will be divided evenly among each of the transaction's line items.

The next toggle Excludes $0 Gifts From Being Created in DonorPerfect. An example of a $0 gift would be a registration for a free event.

The Override Opt-In toggle makes it possible to override DonorPerfect's Do Not Contact setting when importing donor information from Bloomerang Fundraising into DonorPerfect.

The next toggle enables DonorPerfect Pledge Support. This means that pledges created within Bloomerang Fundraising are able to be exported into DonorPerfect as a pledge. Gifts made in Bloomerang Fundraising that are paid toward the pledge balance are applied to the DonorPerfect pledge when data is exported.

For more on enabling pledge support, checkout this article.

The last toggle enables DonorPerfect Contact Support. Enabling this feature makes it possible to export donor contacts from Bloomerang Fundraising events and auctions into DonorPerfect. Event and auction attendee status in DonorPerfect is updated automatically when changed in Bloomerang Fundraising to make creating and tracking these records easy across your Bloomerang Fundraising and DonorPerfect accounts.

You can find a list of existing Codes within your instance of DonorPerfect. In the Settings menu, look for Code Maintenance.

In the Code Maintenance area, select “Activity / Contact Screen” in the Show only drop-down and then click Go.

Click Add to manually add a new Activity Code.

You’ll need to add “QGIV_ATTENDED” for “Attended” status and “QGIV_REGISTERED” for “Registered” status.

Beneath the export settings toggles is the Donor Matching Logic drop-down menu.

The options here determine how the integration will identify existing records in the CRM to import Bloomerang Fundraising information to if they're already in the database.

Using the "Last Name" options, the matching logic can match records by household, so if two people with the same last name, street address, and zip code donate, the integration can apply the gift to an existing record without creating a new record.

For example, Robert Smith can donate as "Mr. and Mrs. Smith" or Jane Smith, who lives at Robert Smith's address, can make a donation and the matching logic will apply the gift to Robert Smith's record in the database.

The integration's matching logic references common nicknames, so if a donor is listed in DonorPerfect by their legal name but uses their nickname when donating later, the integration won't create a new record in DonorPerfect if the other matching criteria remain the same.

For example, if you selected "First Name AND Last Name AND (Email OR Zip Code)" in the Donor Matching Logic drop-down, a donor in your database named Robert Smith can donate as "Bob Smith," and the matching logic will apply the donation to Robert Smith's record in the DonorPerfect database, provided the donor's last name and email address or zip code are the same.

Similarly, the matching logic can match on secondary email addresses, so donors can use different email addresses to make donations, and the integration won't create a new record in DonorPerfect, as long as the donor's other information is consistent.

On the Default Values tab, choose a General Ledger, Campaign, Solicitation, Sub-Solicitation, Receipt Delivery Preference, Thank-You Letter, Gift/Pledge Receipting Preference, Acknowledgement Preference, and QuickBooks Class from the drop-down menus. The selections you make here will be your default mapping locations for transactions that cannot be mapped elsewhere. You can select Unmapped if you do not want any value to be used.

If there’s any extra information you’d like to add to the Gift Memo field in DonorPerfect upon export, you can choose from the options in the drop-down menu on the Extra Info tab.

You can read more about what those extra info fields mean here.

You can make multiple selections. They’ll appear one at a time below the drop-down menu as you select them.

Not all information is available for each transaction type (e.g. Participant Name will only show up for peer-to-peer registrations).

Once you’ve saved, click the Mappings tab to display your Optional Mappings options. This is where you’ll configure mappings if you’d like specific data sets mapped to something other than the default values in the settings area.

Mappings can be grouped by Mapping Type or by Form using the Group by drop-down menu.

You can also filter your mappings to display only specific Mapping Types or only certain Forms and Events.

To add a new mapping, click the Add New Mapping button and then select the Mapping Type from the drop-down.

For example, if you’d like to export data for a specific form, select Standard Donation Form > Form from the drop-down menu. Then, use the Form drop-down to select the form.

If you’d like to exclude the Bloomerang Fundraising data from your exports, check the box labeled Exclude from Export.

Excluding can be useful for something like a $0 category for a peer-to-peer campaign.

If you’d like to export the data to DonorPerfect, do not check the box, and then select the destination values.

When you’ve configured your mapping, click Add Mapping.

You can Edit or Delete a mapping by clicking the three dots at the right side of the mappings table.

If you’d like to delete multiple mappings, check the box next to the mapping’s names, and then click Delete Mappings at the top of the table.

The process is similar for each data set shown in the Optional Mappings area. There may be some slight variations in how many choices you have in each drop-down.

For example, if you’re mapping restrictions, you’ll see another drop-down menu, and still another if you’ve set up sub-restrictions.

When mapping events, you’ll be given the option to drill all the way down to event packages, if desired.

You can also map text campaigns:

Peer-to-peer events just require a form selection and export destination.

You can choose to export other peer-to-peer data, as well.

You can also map auction transactions.

You can also add Custom Mappings. You may already have similar mapping set up through the Extra Info fields. If you don't want this information to appear in both places, be sure to delete the Extra Info mappings once you set up your custom mappings.

Custom mappings allow you to dictate which target objects and fields you want data to go into in the integration. Custom fields must be active in the destination before you can map to them from Bloomerang Fundraising. There are three custom mapping types: static, custom field, and standard field. For each type, you can map to a target object + field using the data from that custom type. See the attached standard field mappings spreadsheet for details.

With static field mappings, you can add static values in Bloomerang Fundraising to target records in the integration service.

With custom field mappings, you can map custom field answers in Bloomerang Fundraising to target fields based on unique custom field reporting labels. For example, you can track custom fields for your fundraising events, such as gathering meal choices.

With standard field mappings, you can map standard field values to a target field.

Some values will be specific to a transaction line item (e.g. restriction name), while others will be for the entire transaction (e.g. transaction ID).

Click here to download a spreadsheet that details all Service Integration Standard Field mappings.

Don't forget to save your work!

When setting up custom mappings for drop-down fields and multiple selection fields, each answer you want to map must match a DP Code in DonorPerfect to export correctly.

For example, if you have a drop-down menu field to capture T-shirt size, in order to map the answers to DonorPerfect, each option in the drop-down must correspond to an existing DP Code.

You can find a list of existing Codes within your instance of DonorPerfect. In the Settings menu, look for Code Maintenance.

To add new codes to your instance of DonorPerfect, you’ll use the Import tool in Utilities. Check out this article in the DonorPerfect user community to learn more.

When you’re ready to run an export, click Export, which is located in the upper-right corner of your settings window. This is only necessary if you chose the Manual export option.

Otherwise, Hourly exports are scheduled to run once per hour at 15 minutes past the hour, but they are not guaranteed to run at exactly 15 minutes past. Actual run times depend on the server load. Daily exports will run at the time you chose.

You’ll receive a message in a pop-up alerting you that your export was completed. If successful, you’ll see the following:

Clicking View Export History will open the Export History Report, but will display only the records associated with this export.

If there were any issues during the export, you’ll see a message similar to the following:

At the top of your integration management screen, you’ll see an Export History tab. Here, you’ll see some basic information about your past exports, including the Export ID, Date and Time, Status, and Total Transactions.

Clicking the Export ID will take you to the more detailed Export History report, filtered by the transactions that were exported in that batch.

To view the full Export History report, click View All Export History.

When you do so, you’ll open the Export History Report, which includes a table which details all exported records across your service integrations.

In the Export History Report you may notice an icon that looks like the outline of a person with a plus sign. This means a new record was created as the result of a new donor or registrant.

Additionally, you may notice an additional alert icon in the Export Status column. Hover over the icon to see more details. The message will also display in the Export History Report.

Follow the link to learn more about the Export History Report.

When you log in to your DonorPerfect account, you should see your newly imported transactions in the locations you specified!

If you'd like to read more about how we decide which mapping to use, read the Mapping Specificity article located here.

Multi-restriction and multi-package transactions get split up into multiple DonorPerfect gifts. If you have GiftAssist enabled, those amounts get divided up across transactions. In case there is a remainder, one donation may get a bit more than the rest. For example, a donation made to two restrictions—$50 to one and $20 to another—with a GiftAssist amount of $5 (for a total of $75) could get split up into two gifts: one of $52.50 and one of $22.50 in DonorPerfect.

Note that transactions from Facebook Fundraisers are given the code ID, indicating an Internet Donation.

For your convenience, you can download an Excel spreadsheet containing the above codes as well as Bloomerang Fundraising to DonorPerfect field mappings. That spreadsheet is available as an attachment to this article.

There are also additional DonorPerfect standard fields Bloomerang Fundraising users can map to. A table of these fields appear below.

From your DonorPerfect Dashboard, click Advanced Search in the top left corner.

The gift portion of a Bloomerang Fundraising transaction ends up as a gift and/or pledge in DonorPerfect. The donor portion of a Bloomerang Fundraising transaction ends up as a donor in DonorPerfect.

To view specific transactions, go to Search Criteria on the left and enter donor information or type "Qgiv" in the Quick Search box.

Within a record, you can find the donor info on the Main tab, one-time and/or pledge payments on the Gifts tab, pledge info on the Pledges tab, and event attendee check-in info on the Contacts tab.

The mappings you set up in Bloomerang Fundraising will populate in the donor record under Qgiv Data.

If you chose not to exclude soft credits in Bloomerang Fundraising, a soft credit will be populated in the Gifts area (if applicable).

Now, the Created By field will show "Qgiv API:" followed by the name of the user who ran the export. For example, Qgiv API: ShaneGrossman.

If you have a lot of optional mappings, you may want to back them up to a CSV file. This is useful if you need to deactivate a service or adjust your connection and want to make sure your mappings are safe.

Click the Mappings Backup link to access the Mappings Backup & Recovery settings.

From here, you can download your mappings as a CSV file, as well as upload a previously downloaded backup file.

The Re-authenticate link lets users reconfirm their integration credentials or enter credentials for a different account.

When you click Re-authenticate, you'll be prompted to Activate the integration or Cancel the reauthentication process. Clicking cancel keeps the integration set up the way it was before clicking Re-authenticate.

If this service integration is no longer needed, it can be deleted by clicking Delete Integration in the left-hand navigation.

You'll be prompted to confirm your choice to delete the integration by typing the word DELETE.

After deleting the service integration, if you need to re-enable it you can reconnect just like when you originally set up the service integration.

To save you time and prevent you from accidentally creating duplicate records, you'll be prompted to Restore export history when you establish your integration again. Note that this will not import any past integration settings. If you would rather start with a clean slate, select Start from scratch instead.

To be notified via email when a service integration becomes inactive, the integration is locked for an extended period, or a transaction fails to export, you can turn on the Service Integrations notification.

To manage notifications, navigate to the Notifications area of your org-level control panel.

Click Manage for each user you’d like to receive the notification.

Then, search for Service Integrations at the top of the screen, or scroll down to Service Integrations in the System Notifications section.

Check the box next to the notification to activate it.

Scroll to the bottom of the screen and click Save Settings to save your changes.

To read more about Notifications, check out this article.