<commit_before>CiviMailchimp Sync
==================

The CiviMailchimp extension allows CiviCRM Groups to sync to Mailchimp Lists. If a Group is configured to sync to a Mailchimp List any Contacts in that Group will be synced to Mailchimp. 

## What Makes It Different

There are a couple of other extensions that handle syncing with Mailchimp, but we decided to start from scratch with this one for a couple of reasons.

Tests! We determined that the best way to ensure that the extension was working was to have as much of the code covered by automated tests as possible, which we've done.

Logging and Error Handling! Sometimes things do go wrong, and when they do, we decided it's best to have them fail spectacularly. Throughout the code, we've added error handling and logging that surfaces errors to the CiviCRM log as soon as a problem is detected so it can be taken care of quickly. The worst thing is to find out months later that contacts were not being synced properly and having to unravel that mess! Also, when CiviCRM's Debug mode is enabled, all incoming and outgoing requests from/to Mailchimp are logged in the CiviCRM log.

## How To Install and Configure

Follow the standard steps for installing and enabling an extension at http://wiki.civicrm.org/confluence/display/CRMDOC/Extensions.

Once the extension is enabled:

Enter your Mailchimp API Key by going to Administer > CiviMailchimp > Mailchimp Settings. If you need to use a different base url for Mailchimp's Webhooks than your CiviCRM base url, as you might if your site is behind an .htaccess password, you may enter it here, too. 

Both of these values can be overriden in your civicrm.settings.php file by following the procedures in http://wiki.civicrm.org/confluence/display/CRMDOC/Override+CiviCRM+Settings. The two values you can override are $civicrm_setting['CiviMailchimp Preferences']['mailchimp_api_key'] and $civicrm_setting['CiviMailchimp Preferences']['mailchimp_webhook_base_url'].

At this point, you should be able to edit a CiviCRM Group and associate it to a Mailchimp List (of course, you should setup at least one List in Mailchimp first). When you edit the Group, you'll see a new "Mailchimp Sync Settings" section where you can select the Mailchimp List the Group should sync with. If you've configured Interest Groups in Mailchimp for this List, you can also select some or all of those, too. Note that only one Mailchimp List can be associated with a CiviCRM Group at the same time. Also, to ensure that the First Name and Last Name fields get synced properly, the Mailchimp merge fields should be name FNAME and LNAME respectively.

Changes to Contacts in that Group are added to a CiviCRM Queue. In order to trigger the processing of that Queue, you must configure CiviCRM's Cron as documented at http://wiki.civicrm.org/confluence/display/CRMDOC/Managing+Scheduled+Jobs. Then, enable the "Sync Contacts to Mailchimp" Scheduled Job by going to Administer > System Settings > Scheduled Jobs. You can also manually execute the scheduled job here for debugging and testing purposes.

If the Group or Mailchimp List have existing records, in order to ensure those records are properly synced, you can run a Force Sync. Go to Administer > CiviMailchimp > Force Sync, select the CiviCRM Group and click Submit. This will perform a one-time sync between CiviCRM and Mailchimp.<commit_msg>Update readme to include info about log and error popups.<commit_after>CiviMailchimp Sync
==================

The CiviMailchimp extension allows CiviCRM Groups to sync to Mailchimp Lists. If a Group is configured to sync to a Mailchimp List any Contacts in that Group will be synced to Mailchimp. 

## What Makes It Different

There are a couple of other extensions that handle syncing with Mailchimp, but we decided to start from scratch with this one for a couple of reasons.

Tests! We determined that the best way to ensure that the extension was working was to have as much of the code covered by automated tests as possible, which we've done.

Logging and Error Handling! Sometimes things do go wrong, and when they do, we decided it's best to have them fail spectacularly. Throughout the code, we've added error handling and logging that surfaces errors to an admin accessible CiviMailchimp sync log as soon as a problem is detected so it can be taken care of quickly. In addition, popup error messages will be shown to the admin and will continue to be shown until an admin chooses to not display the message again. The worst thing is to find out months later that contacts were not being synced properly and having to unravel that mess! Finally, when CiviCRM's Debug mode is enabled, all incoming and outgoing requests from/to Mailchimp are logged in the CiviCRM log.

## How To Install and Configure

Follow the standard steps for installing and enabling an extension at http://wiki.civicrm.org/confluence/display/CRMDOC/Extensions.

Once the extension is enabled:

Enter your Mailchimp API Key by going to Administer > CiviMailchimp > Mailchimp Settings. If you need to use a different base url for Mailchimp's Webhooks than your CiviCRM base url, as you might if your site is behind an .htaccess password, you may enter it here, too. 

Both of these values can be overriden in your civicrm.settings.php file by following the procedures in http://wiki.civicrm.org/confluence/display/CRMDOC/Override+CiviCRM+Settings. The two values you can override are $civicrm_setting['CiviMailchimp Preferences']['mailchimp_api_key'] and $civicrm_setting['CiviMailchimp Preferences']['mailchimp_webhook_base_url'].

At this point, you should be able to edit a CiviCRM Group and associate it to a Mailchimp List (of course, you should setup at least one List in Mailchimp first). When you edit the Group, you'll see a new "Mailchimp Sync Settings" section where you can select the Mailchimp List the Group should sync with. If you've configured Interest Groups in Mailchimp for this List, you can also select some or all of those, too. Note that only one Mailchimp List can be associated with a CiviCRM Group at the same time. Also, to ensure that the First Name and Last Name fields get synced properly, the Mailchimp merge fields should be name FNAME and LNAME respectively.

Changes to Contacts in that Group are added to a CiviCRM Queue. In order to trigger the processing of that Queue, you must configure CiviCRM's Cron as documented at http://wiki.civicrm.org/confluence/display/CRMDOC/Managing+Scheduled+Jobs. Then, enable the "Sync Contacts to Mailchimp" Scheduled Job by going to Administer > System Settings > Scheduled Jobs. You can also manually execute the scheduled job here for debugging and testing purposes.

If the Group or Mailchimp List have existing records, in order to ensure those records are properly synced, you can run a Force Sync. Go to Administer > CiviMailchimp > Force Sync, select the CiviCRM Group and click Submit. This will perform a one-time sync between CiviCRM and Mailchimp.
{'fraction_non_alphanumeric': 0.043, 'fraction_numerical': 0.0, 'mean_word_length': 4.729132569558102, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 15, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7160055', 'n_tokens_mistral': 1832, 'n_tokens_neox': 1779, 'n_words': 1066}