Integrating Drupal with Your Salsa Supporter Database

4Site Interactive Studios released a Drupal module that syncs user data between the Salsa database (www.democracyinaction.org) and the Drupal platform. The module is being used on www.EdExcelencia.org, and it allows Excelencia in Education to fully integrate their Salsa supporter data into their Website. The module requires Salsa API to be installed.

To set up the Salsa Supporters module, you'll need:

• A valid Salsa campaign manager login
• A webserver with the cURL package for PHP installed (most do)
• A new Drupal installation with a cron job configured

There are four main steps to configuring the Salsa Supporters module.

1. Installing the modules
2. Configuring the Salsa API connection
3. Selecting which fields to synchronize
4. Setting permissions

Installing the Modules

First, you'll need to download and install both the Salsa API and Salsa Supporters modules as you would any normal Drupal module.  It's also a good idea to install the E-mail Change Confirmation module. Links to these packages are below:

• Salsa API
• Salsa Supporters
• E-mail Change Confirmation

All the modules in the Salsa category need to be enabled:

You might as well enable the "E-mail Confirm" module while you're at it.  (It's in the "Other" category.)

Configuring the Salsa API

For this step, you'll need your Salsa campaign manager login. Start by navigating to the Salsa login page you normally use, and jotting down these three things:

Back in your Drupal site, navigate to "Administer -> Salsa -> Salsa API Configuration."  You should see three boxes matching the information you just wrote down.  Here are the settings for my developer account:

Make sure you're settings are correct, and click "Save Configuration."  (If you get a connection error later on, it is likely that these settings are entered incorrectly.  Contact Salsa directly to verify your domain and username.)

Next, click the "Synchronization" menu item that appears beneath "Salsa API Configuration."  You should be presented with a page like this:

You should probably start by clicking "Synchronize Now" to test your connection settings. 

You can also use this page to configure how often Drupal will pull data from your Salsa database, and whether to restrict this to certain hours of the day.  (Note: You'll need to be running a cron job for this to work at all.) Save these settings once you're satisfied.

Selecting Fields

Click the "Fields" tab to begin selecting which Salsa fields to synchronize.

The next page may look daunting at first, but it's actually fairly simple.  Running from top to bottom is a list of all available Salsa supporter fields, including user-defined "Custom" fields.  For each field, you're given five options, which are described at the top. 

• Synchronize is required for any data for this field to be included in Drupal at all. (None of the other four options will work without this.)
• View enables data for that field to be displayed on user profile pages (or in the Views module.)
• Edit enables users to edit their own data in the field.
• Register allows new users to enter data for that field on the Drupal registration form.
• Required makes this field "required" on any form it appears (both the registration form and profile edit page.)

Let's suppose I want to do two things.  I'd like all new users to enter their zipcode during registration, for tracking purposes.  I'd also like all users to be able to edit their full name at any time, and to have this information appear on their user account page. 

For zipcode, I really only want to collect data.  I'll check "synchronize," "register," "edit," and "required."  (Users shouldn't be able to see each other's zip codes, so I'll leave "view" unchecked.) This field will now appear as an editable form field on both the registration and user edit screen. In both cases, it will be a required field.

For full names, I'd like users to be able to enter their first and last names at any time if they want to, but not require them to do so.  I'd also like users to be able to see each other's names.  I'll check "synchronize," "view," "edit," and "register" on both the First Name and Last Name fields.

There's also a custom field I have set up in Salsa for internal tracking.  I'll want admins to see that, so I'll check "synchronize" and "view." It only ever becomes modified from within Salsa, so I won't enable the "edit" or "register" options.

All done! Let's click "Save" and move on to permissions.

Configuring Permissions

Permissions for Salsa Supporters are handled in usual Drupal permissions page.  Head to "Administer -> User management -> Permissions" to set them.

I've allowed authenticated users to view each other's first and last names.  I've also allowed all authenticated users to edit their own profile.  Since "Last Publication Download" is only ever going to be used by admins, I've not granted users permission to view that.

If you want users to see each other's profiles, it's a good idea to enable the basic user account page permission, too.

Click "Save permissions."  Salsa Supporters is now configured.

Seeing it in Action

To try out the new functionality, logout of Drupal and head to the user registration page.  You should now see the fields you configured added to the registration form:

If you click "Create new account," your information will be added to the Salsa supporters database as well.  Log in to your salsa account, click on "Supporter Management" and you should find the new user added directly to Salsa:

Additional Notes

• Information changed in Drupal is updated in Salsa immediately.  However, Drupal only pulls information back from Salsa during cron runs, as configured in the Synchronization settings.  Changes made to supporter data directly in Salsa, or through other applications, will not be immediately present in Drupal.
• For security reasons, synchronization will not work for accounts made before Salsa Supporters was enabled.  For this reason, it's best to install Salsa Supporters on brand new Drupal sites.