Chimpegration for The Raiser s Edge

Chimpegration for The Raiser s Edge development@zeidman.info www.zeidman.info UK: 020 3637 0080 US: (646) 570 1131

Table of Contents Overview... 4 Chimpegration Versions... 4 Chimpegration Free... 4 Chimpegration Professional... 4 The Raiser s Edge Versions... 4 Installation... 4 Set up... 6 Activation... 6 Settings... 7 Security Settings... 9 Lists (for Pro users only)... 9 Campaigns... 11 Campaign Activity (for Pro users only)... 12 Duplicate Emails (for Pro users only)... 13 Export... 16 Manage Campaign results... 16 Synch... 16 Day to Day Usage... 17 Export... 17 Manage Campaign Results... 22 Synchronise The Raiser s Edge and MailChimp... 30 List... 30 Mapping... 31 Groups... 32 Settings... 35 Business Settings... 39 Spouse Settings... 42 Run... 44 Processing the Synchronisation... 45 Review... 45 Page 2

Synchronise Relationships between The Raiser s Edge and MailChimp... 48 Removing Constituents from a Mailing List... 48 Chimpegration View... 51 Resources... 53 Page 3

Overview Chimpegration for The Raiser s Edge integrates MailChimp with The Raiser s Edge to varying degrees. There are two versions of the application; Chimpegration Free and Chimpegration Professional. Chimpegration Versions Chimpegration Free Chimpegration Free allows you to export records directly from RE into MailChimp for use in mass email marketing and gives you the ability to manage your campaign results, including bounces and unsubscribes. Chimpegration Professional Chimpegration Professional in addition to the functionality of Chimpegration Free, allows you to synchronise MailChimp and The Raiser s Edge to ensure data is as up to date and clean as possible as well as view constituent mailing information from MailChimp directly from RE. The Raiser s Edge Versions In the release of RE 7.94 some functionality and appearance of the application differs. This means that depending on which RE version you are running Chimpegration is applied differently which is clearly marked on the documentation. Installation 1 When you download Chimpegration from Zeidman Development and unzip the compressed file, there are three applications to be installed: Zeidman Development Universal Server Installer installed on the server and only run once in order to set up the server. This should be run by the administrator. Chimpegration client Installed wherever The Raiser s Edge is installed and the user sends bulk emails. Chimpegration View installed wherever users need to view a constituent s MailChimp activity directly from the constituent record (Professional version only) 1 Please note that regretfully Chimpegration does not work in the Blackbaud hosted environment at the current time Page 4

In general the installation is straight forward. In each case run the setup.exe file and follow the wizard. Please ensure that The Raiser s Edge ad any other programmes are closed before starting your installation. FOR A NEW INSTALLATION ALWAYS START WITH THE SERVER INSTALL. FOR UPGRADES, UNLESS YOU ARE MOVING DATABASES, THERE IS NO NEED TO RUN THE SERVER INSTALL. Please download instruction for the Zeidman Development Universal Server Installer from our website: http://www.zeidman.info/downloads/zduniversalinstaller.pdf Page 5

Set up The first time you use Chimpegration you will need to configure it with MailChimp before you can start using it. Firstly go to plug-ins and open Chimpegration. You will see the screen below: Activation You need to first click on Activate Application. This will prompt you to enter your ZeidZone username and password. Page 6

Activation will register your copy of Chimpegration with Zeidman Development. The process sends your organisation name and Raiser s Edge serial number to our secure servers. This generates a registration code that is unique to your installation. Settings In order for Chimpegration to talk to MailChimp it needs to know your API key. Click on Settings and enter your MailChimp API key. To get your API key click on Where do I get my API Key from? link, this will take you directly to your MailChimp account settings (you will need to login to MailChimp), copy your API key and paste it here. Click ok. Page 7

The first time that you process a campaign or synchronise with MailChimp you will be prompted for the connection details that you created in the server setup as shown below: Page 8

Enter the SQL server credentials that you set up on the server in order to continue. Note that in order to use Chimpegration View (Professional version only) these settings need to have been entered previously). Note that you can also set these values by pressing the ZD logo on the main Chimpegration menu to bring up the About box. Under the advanced menu select Setup SQL Credentials to bring up the above screen. You are now ready to start using Chimpegration. Security Settings Here you can choose to lock down certain areas of functionality for non-supervisor users. Just check the radio boxes next to the appropriate area to restrict access. Lists (for Pro users only) This allows you to select a list which contains both constituent and non-constituent relationships and map the merge field that records the type of record it is. Page 9

In order to be able to synchronise both constituents and non-constituent relationships Chimpegration needs to know what type of record each subscriber in MailChimp is. You will need to set up a merge field in the list which designates this value. The merge field should be a dropdown merge field with a choice of two values e.g. constituents and relationships. This is shown below: In the example above we see the Record Type field has two options of Constituent and Relationship. In our list settings below we have selected our MailChimp list Relationships, we have ticked that it contains both constituents and relationships, that we are using the Record Type merge field to determine whether the subscriber is a constituent or a relationship and we have selected which options represent which record type. Page 10

Note that as with the regular synchronisation the ID field is still used to store the ID of both record types but for relationships it will be the import ID rather than the constituent id. Campaigns In order to keep your dropdown list in the Manage Campaigns section clean you can archive processed campaigns here by simply selecting them and moving them into the Archived Campaigns box using the arrow buttons. If you need to process a campaign after archiving just move it back into active campaigns and it will now appear in the dropdown menu again. Note that this only affects Chimpegration and does not impact on MailChimp itself. Page 11

Campaign Activity (for Pro users only) Here you can select the action attributes you wish to use to track information on email opens and clicks, this involves prior set-up on RE in the attributes actions text area of the Config. Page 12

Duplicate Emails (for Pro users only) Whilst MailChimp does not allow multiple records to share an email address you may have numerous contacts in RE who do share an email address, perhaps a family address or organisational main email address. This contact will then be used for all Chimpegration action where both contacts appear. This is a default setting and it will work differently depending on the area you are processing and some areas contain overwrites for this in the processing. Page 13

RE7.93 and below Page 14

RE7.94 and above As there is no requirement in RE for email address to be unique but there is such a requirement in MailChimp these settings allow you to determine which constituent should be regarded as the main contact person for a specific email. In all versions you can specify a constituent attribute or a constituent code. In 7.93 and below you can specify an address attribute. In 7.94 and above you can specify the constituent where the email address is marked as primary. These can settings can be overwritten in the respective modules of Chimpegration. The following describes how they are used in these modules. Page 15

Export If two constituents with the same email address appear in the query for export Chimpegration will select the one containing the attribute specified here. You can overwrite this in the export section for certain lists if you prefer. Manage Campaign results Here you have the option to process the records as per the defaults set above or to process against all records. However if you select to use Cons ID to identify matches this will ignore these settings. Synch Here the ConsID is used to identify constituents by default. However for new users signing up (who may already be in the database) it will use the email address and the criteria above to try and match the constituent. Page 16

Day to Day Usage The export and Campaign management functions are available for Chimpegration Free and Professional users. Export To export data from RE into MailChimp you must first create a list in MailChimp, add any merge fields you want to export to and ensure they are in the correct format. 2 Then in RE you can create a query of users who you wish to export, be sure to include any fields you wish to use in the mailing in the output criteria. These fields will map to your MailChimp list s merge variables. You will need to ensure there are no blank email address fields in your query, the best way to do this is to use the preferred email address field in the output. You can also set up groups in MailChimp into which you can add your list of users. Groups in MailChimp are used to segment your constituents so that you are able to send them different email campaigns. These may correspond to how you use constituent codes or attributes. Pro users can export both constituent and non-constituent records into a list, you must set-up a merge field distinguishing between these types of records in MailChimp in advance and map the type to that field. You should also use the import ID in the ID merge field for relationships records. Go into the plug-in and select Export list to MailChimp. Select your MailChimp list and any groups the exported users should be added to. Some people may have more than one value in a group e.g. Interests: Golf and Tennis, if you are adding new values to existing groups select Add to any existing groups. You may have a group where only one value is allowed, e.g. current donor?: yes/no, if you are updating these groups select: Replace existing groups with these. 2 Ensure that merge variable types correspond to the Raiser s Edge field types. For example do not create a number merge field for constituent id as The Raiser s Edge constituent id field is a text field. Page 17

Select the query of users to export and create a control report, this will show you errors, if any, from the export. Finally for Pro users if this list contains relationships you will need to select whether to add these records to MailChimp as constituents or relationships. Page 18

You can choose whether to only add new emails or add new email addresses and update existing records. The first option will not update the values of constituents already in MailChimp Pro users can also choose how to handle constituents who share an email address. The first option will select the constituent data containing the attribute specified in Page 19

your settings. If none of the duplicate records contain this attribute an exception will be raised and the constituents will be written to the control report and not exported as part of the list. The second option will simply choose one of those records to export at random. This might be preferable for generic mailing lists where no personalisation is used. This is the only option for those using Chimpegration Free. Next you need to map the fields from your query to the fields in MailChimp. You can set up any number of merge fields in MailChimp before your import to accommodate your RE fields. You must include an email address or the export will not run. For Pro users it is also recommended that you map the constituent ID if you plan to use this to manage campaign results and/or use the synchronisation module as this will give much better accuracy of matching. 3 3 The Constituent ID must be a text field rather than a number field. In MailChimp you should set the constituent Id merge variable (and any other variables you do not want your supporters to see or edit) to be hidden from forms so that supporters signing up using MailChimp s forms do not see, change or add a value for this field. Page 20

You can save mapping files you use regularly and load them here to save you time. Once all your fields are mapped click on Run Now. You will now be able to see your constituents in your MailChimp list and email them using a regular MailChimp campaign. Page 21

Manage Campaign Results Once you have run your email campaign as normal from MailChimp you can update records in RE based on the outcome of the mailing. Select the email campaign you wish to manage from the dropdown list. Professional Edition Only You may optionally select when to pull changes from. This is useful for automation campaigns so that you need not retrieve the changes for every single update but can adjust the date. It is also useful for regular campaigns where you know that there have been clicks and opens since you last ran the campaign. By selecting a date you will only retrieve clicks and opens since that date and will update any actions that have already been added with the new clicks and opens. Due to a MailChimp API limitation, if you select a date, you will not be able to retrieve soft bounces or those marking the email as spam. All Editions Select the type of emails to process. Select one of the following; Hard Bounces, Soft Bounces, Unsubscribes, Those marking email as spam or Everyone Sent. Everyone Sent will give you a list of all those people who actually received your email, so everyone on that list excluding the hard and soft bounces. Page 22

Create a control report for any errors in the process, you can also choose to create a query of updated records. Automation Campaigns (Professional) If you are running an automation campaign then you are given the option to retrieve all the email addresses from the beginning of the campaign or by selecting a date, Page 23

you are able to retrieve those from that date. This is shown below. Note that the text on the date from check box and the retrieve all check box changes when the campaign is an automation campaign. Professional Edition Choose how to identify your constituents in RE, you can either match on email address or Cons ID. Page 24

If matching on ID make sure you match to the same field you exported the ConsID to. If matching on email address you need to decide how to deal with constituents who share an email address. The first option will add the process only to the record identified as primary (as per your settings and listed here) or you can process against all records using that address. This might be useful for unsubscribes, bounces etc. Free Edition If you have the Free version users will be matched on email address and processed against all records by default. Page 25

You can now choose how the records should be processed, you can choose one or more of the following: Change the email type Mark the email as do not contact Delete the email address Page 26

Globally add an action (Pro users can also choose to add email opens and clicks to the action attributes these must be defined in advance in the settings menu), constituent attribute, solicit code or appeal to the constituent record. Globally add a relationship attribute (if you are processing relationship records) Some of these actions will be more relevant to the processing of emails. For example for bounced emails you may want to delete the email address or change the email type to Inactive email. Whereas if you select to process all emails that were sent, you may wish to add an action or an appeal to those constituents. Page 27

Once you have run the process you can repeat it as many times as you need to, performing different actions for different processes. Page 28

The above image relates to RE 7.94 where the change to if this type is already in use field has been removed. You can also see that it is possible to set an email as inactive, whereas in RE 7.93 this function isn t available. Page 29

The following features are available for Chimpegration Professional users only Synchronise The Raiser s Edge and MailChimp List When you first choose to synchronise The Raiser s Edge and MailChimp you will need to select a MailChimp list to work with. Choose the query to synchronise the list with and create a control report for any errors. The query should include all the constituents that should be synchronised between the two systems. If the constituent is not in the query then changes in The Raiser s Edge will not be transferred to MailChimp. Anybody who signs up on MailChimp will be brought over to The Raiser s Edge. However if they then to do not fulfil the query criteria they will not be included in subsequent synchronisations. To ensure that they are included add a common denominator to the query such as a constituent code that they will be given. You can also choose to only synchronise a segment of your list, this can be useful if you have a very large list and only want to bring over changes to certain records, or if your segmentation relates to groups or relationships. Page 30

Mapping Map across the fields which should be synchronised, as you did in the export. Note that not all fields in The Raiser s Edge can be synchronised in a meaningful way so these have been removed from the fields available. Page 31

Groups It is possible to synchronise MailChimp groups to Raiser s Edge attributes, solicit codes or constituent codes. Until an action has been set up all group actions will show as the last entry below i.e. the group will not be synchronised. Page 32

By pressing the edit button you are given a number of options as to how you synchronise the group with The Raiser s Edge. Page 33

In each case it is the value selected in the MailChimp group that is synchronised with The Raiser s Edge. Ignore this will not synchronise between the two platforms. Constituent Codes The MailChimp value corresponds to a constituent code which will be populated in RE or vice versa. Solicit codes - The MailChimp value corresponds to a solicit code which will be populated in RE or vice versa. A Single Attribute A MailChimp value will create an attribute with this category. If multiple MailChimp group values are selected a new attribute will be added but with the same category and differing values. If the MailChimp group is set up as a radio button or a single dropdown then the list of attributes will be those that are marked as Allow Only 1 per Record in RE. If the MailChimp group is set up as checkboxes then the list of attributes will be those that are not marked as Allow Only 1 per Page 34

Record. If the MailChimp group is set up as hidden from the sign up page then both types of attributes will be listed. Multiple Attributes A MailChimp value will create an attribute with the same category name as the group value. If a value is to be removed from RE because it no longer exists on MailChimp, you are given the option to remove it, or in some cases, add a date value to indicate when that group membership ended. Settings To ensure the data being synched back into RE has your business rules applied to it you can use the following settings: Page 35

7.93 and below: Page 36

7.94 and above Page 37

Code Tables If data has been added to MailChimp that does not currently exist in RE you can choose to Ignore that particular field Ignore the entire record Page 38

Attempt to add the code to the code table (assuming you have the correct permissions) Either way the result will be added to the control report Email Addresses (7.94 and above) In version 7.94 and above it is possible to mark email addresses as primary. These settings give you the option to decide whether an incoming email address should be marked as primary or not. In version 7.94 and above it is possible to have more than one email of the same type. These settings allow you to decide whether an incoming email address should be added to the list of existing emails or if it should overwrite and email address with the same type. Constituent s added as Subscribers When adding new users to RE from MailChimp you may wish to add a constituent code to the record, you can choose which one here. You can also choose to add that code to existing constituents that do not already have the code and add a start date too. We have enabled you add a constituent attribute to MailChimp users. This can be any type attribute type and the description box will adjust accordingly. Finally, by selecting the removal of the Request no email flag on the constituent bio 1 tab, any record coming from MailChimp will have this flag unset. Mandatory Last Name Field To ensure the synchronisation runs smoothly you can choose standard text to add to the last name field on the constituent record. If you have any user-defined manual fields these will appear as separate boxes beneath this one and you can select default text to fill those areas too. Business Settings If you have any business fields mapped then this tab will appear. Page 39

Business Creation You can decide whether or not business relationships are created with a nonconstituent relationship to the organisation or whether Chimpegration attempts to look up the organisation in your system. If it does not find a constituent with the same organisation name it will create a non-constituent relationship instead. Business Relationships and Reciprocal Relationship values Page 40

You can decide how the relationship and reciprocal relationship values are set up. Mandatory Organization Name To ensure the synchronisation runs smoothly you can choose standard text to add to the organization name field on the constituent record. If you have not mapped a merge variable to organization name but have mapped other business fields then this value is required in order to create a new organization relationship record in The Raiser s Edge Mandatory fields (not shown) If there are any user defined mandatory organisation relationship fields (including mandatory address fields) then these will be prompted for at the bottom of this tab. Page 41

Spouse Settings Spouse Relationships and Reciprocal Relationship values You can decide how the relationship and reciprocal relationship values are set up. These are based on the gender. If you have consistently set the gender for constituents and their spouses then you are able to set a value for dependant on the gender. If constituents have been set consistently but not their spouse relationships Chimpegration will assume the relationship has the opposite gender. Page 42

You are of course able to set gender neutral relationship types such as Spouse or Partner. Mandatory Spouse Last Name To ensure the synchronisation runs smoothly you can choose standard text to add to the spouse last name field on the constituent record. If you have not mapped a merge variable to spouse last name but have mapped other spouse fields then this value is required in order to create a new individual relationship record in The Raiser s Edge Mandatory fields (not shown) If there are any user defined mandatory individual relationship fields (including mandatory address fields) then these will be prompted for at the bottom of this tab. Page 43

Run Here you can select when the synchronisation should run from. If it has never previously been run (as shown above) all changes will be synchronised. If it has previously been run then this option will show the date of the last synchronisation. You can also choose to synchronise records from a set date too. Page 44

You can choose which data you want to review and how conflicts will be handled. Ordinarily you will want to review all records, unless you have a very large list which you are happy to go into RE, excepting conflicts. Before you process the records you can choose to save your settings for the next time you run your synchronisation. Processing the Synchronisation Once you are happy with the settings press the Run Now button to proceed. This will retrieve all the records that have been added to or updated on MailChimp. It will do the same for The Raiser s Edge. It will then display the records for review. Review The review screen shows the records as specified in your set up (as above). You can choose to process using the action to take specified on the screen, choose to process in a different way or skip and update later. Where there is an error in the processing the specific record (as shown in the figure below) you will be forced to skip that record. The explanation is shown in the top right box and will be added to the control report. To add your own notes to the record (which are saved in the control report) enter them in the box beneath. Page 45

In other cases you will be able to decide which direction the synchronisation will flow. If the record is new to The Raiser s Edge it will always go to MailChimp (unless you decide to skip it) and vice versa. Note that the constituent id for new records will always go to MailChimp. If you do not want a specific field level change to take place then set the action to take to None. You can change the direction of information flow at an individual field level either way using the dropdown in the centre. Page 46

In the example above the record does not exist on the Raiser s Edge and consequently all fields will be pushed to MailChimp. By default any fields more recently updated on one side will go over to the other. In some cases this is fine. In other areas we may not want to accept the defaults. Where a record has been changed both on MailChimp and on The Raiser s Edge it will be shown as in conflict. Before proceeding you will need to decide how to transfer the data (or set this up in the rules on the Run tab of the previous settings screen) The group synch will show you which groups it is synching and in which direction, it will also explain how the synch will work as there may be more than one area affected. Once you are happy with all the records; run the process, you will see a summary screen of the synch. Page 47

Your control report will contain the details of this synch and show any records skipped and the reasons why. Synchronise Relationships between The Raiser s Edge and MailChimp This process is almost identical to the synch process listed above, but when selecting the list only those configured for use with relationships are shown. There are a few other differences to the regular synchronisation: Remember to map the relationship ImportID to the ID field. Only non-constituent relationships are synchronised. If the import id points to a constituent relationship it will not be synchronised and instead you should use the regular synchronisation. No new records will be added to The Raiser s Edge. This should be done in the regular synchronisation. The reason for this is that there is no way of Chimpegration knowing which constituent record the new relationship record should be associated with. Removing Constituents from a Mailing List Select Remove Subscribers from the main menu, select the MailChimp list (and if this list contains relationships choose between constituent or relationship records) from which you wish to remove subscribers, map the ConsID to the appropriate merge field. IMPORTANT NOTE: if you map this incorrectly Chimpegration will attempt to delete all records, please check this carefully before proceeding. If you choose to match on email please select the email type from the list on the left and move to the right. You can select more than one. You can also choose to check only the preferred address for email addresses. Page 48

Choose the query to use and create a control report, as with all control reports this will show any errors in the remove process. Select whether to delete (remove from list, you can re-add this person at any time) or unsubscribe (only the constituent will be able to re-add themselves to this list, manually) the users. Finally if you can select that if subscribers are not in The Raiser s Edge they should not be removed. This may be the case for newly subscribed individuals who have yet to be brought over to RE. Page 49

Click delete to start processing. The application will let you know how many constituents will be removed from the list. Page 50

Click yes and your constituents have now been removed. Chimpegration View Chimpegration View allows you to view a constituents MailChimp data directly from the Raiser s Edge constituent record. You can see their details, mailings sent and any actions taken on those mailings, such as opening the email or clicking a link. From the constituent record go to the macro button and select View.On.MailChimp Page 51

This constituent has two email addresses and this will be reflected in the Chimpegration View. The activity for the constituent is dependent on their email address and the list that they are on. Note: if you have users sharing email addresses on RE Chimpegration View will show activity for that email address which may not be for this constituent depending on your settings for primary email address holder. Page 52

Resources For general information about working with MailChimp, see their resources section: http://mailchimp.com/resources/ For specific resources for Non-Profits see their guide for non-profits: http://mailchimp.com/resources/guides/mailchimp-for-nonprofits/ Page 53