Introduction

This article will describe various aspects of the integration between RaiseDonors and Aegis CRM API. To begin, RaiseDonors has worked closely with the team at Aegis to ensure this integration successfully and completely covers the features of the legacy file based integration. 

All information exchanged from RaiseDonors to Aegis is communicated through the Aegis API. With this communication channel, RaiseDonors is able to:

• query various data objects (ie: partners, appeal codes, origin source codes, etc),
• modify data objects (ie: partners)
• create data objects (ie: transactions)

The integration was built to support network communication issues meaning that RaiseDonors can continue to function normally if Aegis were to ever go offline. 

What actions trigger an integration to Aegis CRM?

There are seven events that can trigger RaiseDonors to initiate an integration to a CRM. Those are:

• A new donation
• A new note in a donor account
• Updating donor information
• Modifying a recurring schedule
• Terminating/suspending a recurring schedule
• Refunding a donation
• Pull donation history for donor portal

Currently, RaiseDonors supports six of these events with Aegis CRM,

• New Donation
• Modifying a recurring schedule
• Terminating a recurring schedule
• Refunding donation
• Updating donor information
• Pull donation history for donor portal

All other events are currently ignored, but are on the roadmap to be developed soon.

How does each event work?

New donation

When a new donation is placed, the system will be notified that a new donation has occurred. Within 3 minutes, the system will pick up the new donation and begin processing the donation. One of the processing items is to send the donation details to Aegis. There are several micro-steps in this process. 

If the donor does not have a CRM key, begin calling the Aegis API to locate this partner (using the configured business rules for matching donations to donors). Once a match is established, save the partner Id to the Donor.CRM property.

If multiple partners are located, the integration will follow the prescribed business rules to determine which partner to use (or create a new one).

Build the transaction payload to send to Aegis. This includes many items from the data mapping table below. 

If this is a new recurring donation, first create a new pledge in Aegis CRM and store the pledge ID on the schedule.CRM property.

If this is an instance of a recurring schedule, locate the schedule.CRM key - and ensure the pledge is active and exists in Aegis. Include the pledge id with the transaction information.

Build out the "gifts" to be included with this transaction. Each gift item corresponds to a project allocation in the donation. If a donation only has one project allocation, then only one gift will be included with the transaction. If however, the donation has multiple project allocations, then multiple gifts will be included with the transaction. If this is a recurring donation of any kind, Include the pledge id with each and every gift being sent with this transaction.

If the donation includes a product, build out the product order section in the transaction. Shipping information from the donation will be included in the product order section.

Evaluate the donation for gift aid, media station data, In Honor/Memory of information, and relevant attributes for meta information. 

Send final payload to Aegis for processing asynchronously and does not impact the donor's experience during the donation process.

The transaction id from Aegis is stored on the RaiseDonors.Donation.CrmKey field. 

Modify a recurring schedule & terminating a recurring schedule

Gateways routinely communicate with RaiseDonors and it's possible that this communication would update the recurring schedule. Doing so will push an update to the associated pledge in Aegis. 
This event can also be triggered from an admin or donor who directly makes changes to the schedule. The pledge id is stored on the RaiseDonors.Schedule.CrmKey field. Having the CrmKey field populated with a valid pledge id is how the systems know the two are connected. If there is no value in the CrmKey field, RaiseDonors will attempt to create a new pledge in Aegis. 

Refunding a donation

When a donation is refunded or voided inside RaiseDonors, the integration will send a new transaction containing a negative amount to Aegis CRM. This transaction will include all of the same properties as the original transaction.

Updating donor information

If the donor has a CRM property that matches to an active partner in Aegis, the integration will push the changes to Name, Address, Phone, and Email to Aegis CRM. 
If the donor does not have a CRM property that matches to an active partner in Aegis, the system will email the notification list with the supplied changes.

Pull donation history for donor portal

RaiseDonors will use the Donor.CRM property and query Aegis API for all transactional history. This data will span various segments (digital, inbound call, postal mail, etc) and will be displayed to the donor. This ensures the donor can have a view of their complete giving history.

Donations successfully sent to Aegis will have the RaiseDonors.Donation.CrmKey field populated with the Transaction.InvoiceNumber. When pulling back history from Aegis, the RaiseDonors.Donation.CrmKey field will be used to map matching records.

If the Donor.CRM property does not match to an active partner in Aegis, only transactional history from RaiseDonors will be displayed to the donor.

Gifts to multiple projects vs one project

Multiple Projects

A donation in RaiseDonors must be attributed to a Project. It's possible for a donation in RaiseDonors to be allocated across multiple projects. It's important to understand that if a donation is attributed to multiple projects, then 1 transaction with multiple gift allocations will be created in Aegis. In the example below, 1 transaction will be created in Aegis with 4 gift allocations:

Gift #1 - $75
Designation #1 - $50
Designation #2 - $20
Designation #3 - $5

Single Project

If a donation is only attributed to one project, then only one transaction with one gift allocation will be created in Aegis.

Data mapping

Here is the mapping of our integration showing how foreign keys are stored and mapped. If you are importing data into RaiseDonors, populating these fields will be crucial.

Here is the mapping of our integration showing how data from RaiseDonors flows into Aegis.

Verbose notes tell you the following,
Everything in the simple notes plus,
Test mode?
Recurring?
Payment type (cc / ach) and card brand if CC.
Motivation code
Source code
Referring URL
Google UTM codes
IP Address
If premium, premium code and name
If media outlet included, media code
Shipping address information, if included.

Custom Fields

RaiseDonors has the ability to store custom pieces of information with each donation. This custom data can be added on the donation page or through the API. There are specific custom fields that are special for Aegis API integration. Custom fields, by default, have a name beginning with "custom_". You can push custom field data all the way through to Aegis's Transaction.Attribute property. 

The special name for custom fields is (without the double quotes),
"custom_aegisapi_"

For example, if you wanted to pass the gateway transaction Id from RaiseDonors into the Aegis.Transaction.Attribute field, you would pass
custom_aegisapi_transactionid=1234

This will show up as an attribute on the transaction object in Aegis as,
attribute name = transactionid
attribute value = 1234

Whatever value you place in the custom field name, is what will become the attribute name. Example,
custom_aegisapi_{name}
will become the attribute "name" with a value of "{name}".

Media attributions

If RaiseDonors is configured to support media attributions, this information can also be sent with each donation into Aegis. The integration will include the selected media code in the transaction and then also include an attribute named "media station".

United Kingdom Gift Aid

RaiseDonors supports Gift Aid for organizations processing in GBP thru their gateway. To facilitate Gift Aid requests from the donor into Aegis, the integration will create an attribute in the transaction named "Gift Aid Requested".