EveryAction¶
The ActionKit EveryAction sync transfers ActionKit data to EveryAction. You can use the sync to transfer data about Users (EveryAction Contacts), One-Time Donations (EveryAction Contributions), Recurring Donations (EveryAction Recurring Contributions), and Recurring Payments (EveryAction Installments).
The sync uses settings in ActionKit configuration, reports in ActionKit categorized as everyaction_sync and everyaction_donations_sync, as well as the field mappings in ActionKit to determine the data synced.
EveryAction Customization¶
The ActionKit EveryAction integration adds two new External IDs to your EveryAction committee - ActionKit ID and ActionKit User Profile. These are used to link Contact records back to ActionKit Users in the EveryAction admin interface.
Setup in EveryAction¶
We will set up an API user in your EveryAction committee which will be used by the sync system. This user will be given permissions to update all necessary data in your committee.
Then you'll be able to configure the settings in ActionKit, first to set which objects sync, then to map specific fields related to each object you want to sync, and finally to specify which users and donations will sync.
Setup in ActionKit¶
In ActionKit Settings (the cog wheel icon, top right of the screen) select CONFIGURE ACTIONKIT to get to the Config page. Scroll down to Integration Settings and click the Edit link next to EveryAction.
You’ll see options for managing the sync settings for Users, One-Time Donations, and Recurring Donations.
Syncing Users¶
If you enable the User sync from ActionKit to EveryAction, information about Users who are eligible for sync will transfer to EveryAction for any fields you specify in the User field mapping.
To be eligible, the User must meet the criteria in your EveryAction Sync Report (more on how to set that up below) or have met the criteria and been included in the sync previously.
Once a User is synced, their EveryAction ID is recorded in ActionKit in the core_everyactionusermap table and displayed on the user record next to the label "VAN ID". Any updates to fields you’ve mapped will transfer from ActionKit to EveryAction for Users with an EveryAction ID, even if that user no longer meets the EveryAction Sync Report criteria. If you must disable updates for a specific ActionKit User who is already in the sync, contact support.
The ActionKit to EveryAction sync runs automatically every ten minutes, sending data for any newly eligible or previously included user whose record has changed since the last sync.
User Matching¶
Matching from ActionKit Users to EveryAction Contacts happens within the EveryAction system. When ActionKit sends a new user to EveryAction, all mapped data associated with the user is used to find a match. Name, address, email and phone numbers are all considered. It is possible that multiple ActionKit Users will map to a single EveryAction Contact - that can happen when an EveryAction Contact has multiple email addresses (which is not possible for ActionKit Users) or by name, address or phone number matching.
User (Contact) Field Mapping¶
User Field Mapping is managed on the User Fields tab on the EveryAction Integration Settings page. First Name, Last Name and Email Address mappings are required and have fixed mappings which cannot be edited. We also provide non-fixed mappings for commonly used fields which you can edit or delete.
You can also select any available ActionKit User field and map it to a compatible EveryAction field. Custom fields are eligible for mapping in both systems, just be sure to keep the mapping considerations in mind.
Our recommended ActionKit User Field Mapping looks like this:
Data is loaded in EveryAction via a system of "mappers". Each mapper supports a variety of fields. For example, the default field mapping uses the "CreateOrUpdateContact" mapper, which has fields for email, address, phone, etc.
You may add new mappers amd fields by selecting from the dropdown list at the bottom of the User Field Mapping page:
Following is a description of the available mappers for Users/Contacts.
CreateOrUpdateContact Mapper¶
This mapper allows you to update the core Contact fields in EveryAction. The following fields are available:
| Display Name | Description |
|---|---|
| AddressLine1 | Address Line 1 |
| AddressLine2 | Address Line 2 |
| AddressLine3 | Address Line 3 |
| CellPhone | Cell Phone |
| CellPhoneCountryCode | Cell Phone Country Code |
| City | City |
| CountryCode | Country |
| DOB | Date of Birth |
| EmployerName | Employer Name |
| AdditionalEnvelopeName | Envelope Name - Additional |
| FormalEnvelopeName | Envelope Name - Formal |
| EnvelopeName | Envelope Name - Informal |
| FirstName | First Name |
| Phone | Home Phone |
| PhoneCountryCode | Home Phone Country Code |
| LastName | Last Name |
| MiddleName | Middle Name |
| Nickname | Nickname |
| OccupationName | Occupation Name |
| OtherEmail | Other Email |
| Title | Prefix |
| ProfessionalSuffix | Professional Suffix |
| AdditionalSalutation | Salutation"Additional |
| FormalSalutation | Salutation - Formal |
| Salutation | Salutation - Informal |
| Sex | Sex (free text) |
| StateOrProvince | State Or Province |
| Suffix | Suffix |
| WorkEmail | Work Email |
| WorkPhone | Work Phone |
| WorkPhoneCountryCode | Work Phone Country Code |
| ZipOrPostal | Zip Or Postal Code |
| TBD | Custom Contact Fields |
ApplyExternalID Mapper¶
This mapper allows you to set External IDs in EveryAction based on ActionKit data. For example, you could use this to associate a user with their Facebook profile. There are two fields required for each addition to this mapper:
ExternalIdTypeID - choose a value mapping and the type of the external ID (Facebook, for example)
ExternalId - map this to a field on the user object which contains the external ID value
Phones Mapper¶
This mapper allows you to load phone numbers with more flexibility than the fields in CreateOrUpdateContact. To use it you must map to these fields:
Phone - the phone number
PhoneTypeID - map this to one of the values available: "Cell", "Fax", "Work", etc.
You may also map values to PhoneOptInStatusID to record whether the user opted-in to contact on this number.
ApplyContactCustomFields Mapper¶
This mapper allows you to map ActionKit data to custom contact fields in EveryAction. You might use this to record data from ActionKit which falls outside the standard EveryAction fields. For example, you might use it to record an ActionKit User's University:
To use this mapper select any of the custom fields from the EveryAction Field dropdown. Be sure to check the compatibility of selected fields to avoid causing sync errors.
WorkAddress and MailingAddress Mappers¶
These mappers give you more control over how addresses are mapped to EveryAction. Each contains a set of address fields (ex. WorkAddressLine1, WorkCity, WorkStateOrProvince, etc) which allow you to map ActionKit address data to specific fields in EveryAction.
Email Mapper¶
The email mapper gives you extended control over how email addresses from ActionKit are stored in EveryAction. Available fields are:
Email - the email address
EmailTypeId - determines the type of the email: "Personal", "Work" or "Other"
EmailSubscriptionStatusId: "Unsubscribed", "Not Subscribed" or "Subscribed"
Note: the default mapping for email address uses "Personal" and "Subscribed".
User Field Mapping Considerations¶
The field type and the data in the field will determine which can be synced. We attempt to detect problems in your mapping choices and you may see error messages if you choose an invalid pairing.
However, it is still possible to end up with a bad mapping, which can break your sync. Once a field is in your mapping, review any changes to the data type or values to make sure they work with the sync.
Notes on specific mapping options follow:
- Understand how custom field validation works in ActionKit. While you can define Field Types for custom fields, the data is not validated for all possible avenues of entry. For example, if you set a custom user field to type 'Date' in ActionKit, this stops you from entering non-date values on the user record in the admin. This does not stop a user from entering non-date values in the same field on an action page unless you've applied custom validation when creating the page. Think about how you'll use the ActionKit field and what you can do to keep the data clean when you're mapping to a restricted field type.
- The location fields in ActionKit (latitude, longitude, congressional district, etc) and the location fields in EveryAction are calculated. That means they cannot be overwritten and each system will compute them from address data.
- EveryAction uses stricter postal/zip code validation than ActionKit. An invalid zip code will prevent syncing of any information for that user.
User Sync Reports¶
You set the criteria in ActionKit for which Users are eligible to be synced to EveryAction.
Reports tagged everyaction_sync are used to define the criteria. From the ActionKit EveryAction Integration Settings screen, click on "User Sync Reports" to view a list of reports with this tag.
ActionKit ships with one built-in report with this tag. This report returns only subscribed users.
The suggested base EveryAction sync report is:
SELECT id FROM core_user WHERE subscription_status='subscribed'
You may want to further restrict your sync, particularly if you have many users in your database. For example, you might decide to sync only donors:
SELECT u.id FROM core_user u JOIN core_order o ON (o.user_id = u.id) WHERE u.subscription_status='subscribed' AND o.status = 'completed'
Remember, User Sync Reports set the criteria for who is added to the sync. Once a User is included in the sync they are not removed, even if they no longer meet the criteria. Contact support if you need to remove a user from sync.
Creating a User Sync Report¶
To create your own report, use a Query Report, with SQL or the query builder. Your report must return a list of just ActionKit User IDs. Tag your report everyaction_sync.
You can delete or edit these reports and/or add your own reports via the Query Builder. For example, if you’d like to only include subscribed ActionKit Users who have also made a donation, your selections would look like this:
Or you can create the same results using custom SQL, like this:
Syncing Donations and Payments¶
If you enabled the Donation sync from ActionKit to EveryAction, all successful One-Time Donations, Recurring Donations and Recurring Payments that meet the criteria in your Donation Sync Report (described below) will be tranferred to EveryAction for all synced users. This includes full and partial refunds.
If you are using our default Donation Sync Report, when a user or contact is initially added to the sync, all successful historical donation records will sync for that user.
Donation and Payment information that is not linked to a synced user will not be included in the sync.
One-Time Donation (Contribution) Field Mapping¶
One-Time Donation Field Mapping is managed on the Order Fields tab on the EveryAction Integration Settings page. Order Amount and Order Date are required and cannot be edited. We also provide default mappings for commonly used donation fields which you can edit or delete.
You can also select any available ActionKit One-Time Donation field and map it to a compatible EveryAction field. Custom fields are eligible for mapping in both systems, just be sure to keep the mapping considerations in mind.
The first mapper on this page allows you to map ActionKit accounts to EveryAction Designations. You must choose a mapping for each account in ActionKit, and these mappings should not be changed once you begin syncing so it's important to set them up correctly.
The next editable section is ContributionData. This is where you set field mappings for ActionKit to EveryAction for all available fields.
The default fields are:
ContributionData allows mapping to the following EveryAction fields:
| Display Name | Description |
|---|---|
| Designation | Automatically mapped from account using the settings at the top of the page |
| PaymentTypeID | Set to "Credit Card" for all donations |
| Amount | Automatically mapped from the Order amount |
| DateReceived | Automatically mapped from the Order's created_at field |
| CodeID | Automatically mapped from the Order's source, truncated to 50 characters |
| CheckDate | Check Date |
| CheckNumber | Check Number |
| GatewayAccountTransactionID | Online Reference Number |
| DateDeposited | Deposit Date |
| DepositNumber | Deposit Number |
| ContributionStatusID | Automatically set to "Settled" |
| DirectMarketingCode | Direct Marketing Code |
| Notes | Internal Note field |
| TBD | Custom Contribution Fields |
Recurring Donation (Contribution) Field Mapping¶
Recurring Donation Field Mapping is managed on the Recurring Fields tab on the EveryAction Integration Settings page. Recurring Amount and Order Date are required and have fixed mappings which cannot be edited. We also provide non-fixed mappings for commonly used donation fields which you can edit or delete.
You can also select any available ActionKit Recurring Donation field and map it to a compatible EveryAction field. Custom fields are eligible for mapping in both systems, just be sure to keep the mapping considerations in mind.
The RecurringCommitmentData mapper is where you can set mappings for all available Recurring Donation fields.
Recurring Payment (Installment) Field Mapping¶
Recurring Payment Field Mapping is managed on the Recurring Payment Fields tab on the EveryAction Integration Settings page. Transaction Amount, Transaction Date and EveryAction Recurring Contribution ID are required and have fixed mappings which cannot be edited. We also provide non-fixed mappings for commonly used fields which you can edit or delete.
You can also select any available ActionKit Recurring Payment field and map it to a compatible EveryAction field. Custom fields are eligible for mapping in both systems, just be sure to keep the mapping considerations in mind.
The ContributionData mapper is where you can set mappings for all available Recurring Payment fields.
Donation Sync Reports¶
The default report includes all One-Time Donations, Recurring Donations, and Recurring Payments, so these will transfer to EveryAction for any user in the sync.
If you want to limit the donations to be synced, you can edit the existing report tagged everyaction_donations_sync, or add your own.
The reports must select two columns: order_id and transaction_id. Order_id is always required. A transaction_id is optional for onetime donations. Remember, the Donation Sync Report only applies to donations from users who are in the sync.
Mapping With Merge Queries¶
All sync types can use merge queries to enable syncing of felds that arent' available in any of the standard mappers. To add fields to the sync with a merge query follow these steps:
1 Create a merge query that includes all of the fields you want for one type of sync.
2 For each field type include one of the following required fields:
- Users:
user_id- One-Time Orders:
order_id,transaction_id- Recurring Donations:
order_id- Recurring Payments:
order_id,transaction_id3 Add the category tag everyaction_merge.
4 Select your new merge query from the dropdown on the bottom of the mappings page, click Save Changes.
5 Continue mapping. Merge fields will now be a field type option for all editable mappers.
Example Merge Query¶
The following merge query would add the field total_donated to the available fields for User sync.
SELECT u.id as user_id, SUM(o.amount) as total_donated FROM core_user u JOIN core_order o ON (u.id = o.user_id) WHERE o.status = 'completed'
Mapping Edits¶
When you change your field mappings for users, orders or recurring orders, the changes do not apply retroactively. For example, if you add a custom userfield to your mapping, users who already have a value for that field in ActionKit will not have the value transferred automatically. Only future entries in the field will transfer. You can force the sync by importing users whose records have changed -- a new action prompts ActionKit to update all mapped fields. Make sure to test your new mapping when you apply it; invalid mapping can break the sync. See User Field Mapping Considerations for details.
Donation-Only Mode¶
A special mode is available, designed for using EveryAction as your database of record for donation tracking purposes. When enabled it makes the following changes:
- Only donors are sent to EA. If you select non-donors with your User Sync Report they will not be sent to EA.
- Only new donations trigger a Contact update. Non-donation activity like Petition sigatures will not trigger an update.
- The Contact fields which normally come from the User object come from the most recent Order's User Detail object instead. This ensures that the contact data in EA matches up with user data entered during a donation.
You can turn Donation-Only Mode on or off from the Global Settings tab of the EveryAction Integration Settings.
Syncing Contacts from EveryAction to ActionKit¶
If you enable Copy contact data from Everyaction to ActionKit, information about Contacts who are eligible for sync will transfer to ActionKit for any fields you specify in the User Reverse field mapping.
Once a User is synced, their EveryAction ID is recorded in ActionKit in the core_everyactionusermap table and displayed on the user record next to the label "VAN ID". Any updates to fields you’ve mapped will transfer from EveryAction to ActionKit.
The EveryAction to ActionKit sync runs automatically every ten minutes, sending data for any newly eligible or previously included user whose record has changed since the last sync.
This sync uses EveryAction's Changed Entity Export system, and as such can only access data which has been recently updated. There is no provision for sending existing data en-masse from EveryAction to ActionKit. This API also has limits on the kinds of data that can be mapped, offering less options than the API used for ActionKit to EveryAction data mapping.
Eligibility for Syncing From EveryAction¶
Eligibility for syncing is controlled by the "New User Creation Mode". It has the following settings:
Always: all updated Contacts in EveryAction will sync to ActionKit.
Never: only users sync'd from ActionKit to EveryAction will have their updates sent back to ActionKit.
Donors-Only: users who make a donation in EveryAction will be sent to ActionKit, in addition to anyone already sync'd from ActionKit to EveryAction.
Contact Field Mapping Considerations¶
ActionKit users have exactly one email address - the email field you pick in the mapping will control which email field in EveryAction is used. You can map additional email addresses in EveryAction to custom fields in ActionKit but there is no support currently for mapping them to additional users.
If you do not map a field for source in ActionKit the default source will be "everyaction".
To the degree possible you should setup a mapping for the reverse sync (EveryAction to ActionKit) that matches your settings for the ActionKit to EveryAction sync. This may be difficult since the fields available in the EveryAction Bulk Upload API don't always have the same names as the fields in the EveryAction Changed Entity Export API. If you run into a case where you're not sure how to get the two field mappings to match please contact support and we may be able to help.