Setting up Salsa

Mobile Commons supports Salsa API v1.

The Salsa data sync allows for flexibility in sync type for new and updated records. User records must include a listed mobile number and the Country field setting must be US:

  • If Liberal sync is enabled, the data is synced in both directions, regardless of the opt-in status in Salsa.

  • If Liberal sync is not enabled (Conservative sync), the data is updated only for those records with an opt-in status of true in your Salsa system.

For information on selecting the data sync type, see Configuring the Salsa integration.

Note: You must have Administrator access to work with data syncs in Mobile Commons. For assistance, contact Technical Support.

To set up the Salsa data sync:

Preparing for setup

Before you begin, gather the log-in credentials and set up any other key connection settings for your Salsa CRM system.

  1. In Mobile Commons, create or designate a web opt-in path, which will serve as the default opt-in path for any new users pulled from the Salsa data set. For more information, see Adding a new web opt-in path.

    New subscribers will receive the Welcome message associated with the selected opt-in path. For more information, see Data sync paths.

    Tip: You can also sync/map different opt-in paths from Mobile Commons to specific Salsa groups. For assistance, work with your customer success manager.

  2. Make a note of the following credentials from your Salsa system:

    • Login or API username (email address) and password

      Tip: Create a new set of credentials exclusively for use with Mobile Commons (recommended).

    • Salsa API host name

    • Salsa organization

  3. (Optional) If you are syncing Mobile Commons and a specific chapter under Salsa, make a note of the Salsa chapter ID.

  4. (Optional) If you are configuring a Conservative data sync:

    • You can use the standard field, "receive_phone_blasts," which is a Boolean/true-false type of field.

    • In Salsa, create a new custom field named "Mobile opt in," which should also be a Boolean/true-false type of field.

    • Build a custom report in your Salsa interface. For more information, see Building a custom report.

Building a custom report

In order to use a Conservative data sync, you first need to build out a custom report in Salsa:

  1. Select the Supporter Management tab, and then select Manage Exports.

  2. Scroll to the bottom of the page and select Add New Export.

  3. Select Create an export based on a report.

  4. To build out your report, include the following standard fields with Not Empty selected in the Operator or Function field:

    • Email

    • Cell phone

    • Opt in (Boolean)

  5. Select any other standard columns you want to include in the report.

    Note: Do not include custom columns in Salsa or columns that map to custom fields in Mobile Commons.

  6. Select Save.

  7. To set up the report to output a CSV (comma-separated values) file once a day, select Edit Export.

  8. In the Recurring Frequency field, select Every Day from the drop-down list.

  9. In the Format field, select CSV from the drop-down list.

  10. Select Save.

  11. When you are done, select Run Report.

  12. To view your report, go to Reports and Statistics and open your report.

  13. Copy the URL for the report from the address field in your browser.

    Tip: Keep the URL at hand, so you can enter it in the Custom Export URL field when you are configuring the integration.

Configuring the Salsa integration

To sync data between your Salsa database and Mobile Commons:

  1. Select Home Home in the left pane, and then select Data Sync.

  2. From the Integration Type drop-down list, select Salsa.

  3. Select Create.

    The Salsa configuration form opens.

    Salsa configuration form

    For assistance, select Help Help next to the field label.

  4. In the Login field, enter your user name for your Salsa system, and then enter your password in the Password field.

  5. (Optional) If users from Salsa will opt-in to your campaign via a web path opt-in, select the Mobile Commons web opt-in path from the drop-down list. New mobile users from Salsa will receive opt-in messages from the opt-in path you specify.

  6. In the Salsa node domain field, enter the host name for your Salsa node.

  7. Enter your Salsa organization ID.

  8. (Optional) If you are configuring a Conservative sync, in the custom export URL field, enter the full URL of the Salsa custom report. For more information, see Building a custom report.

  9. Enter the chapter ID for your organization, if available.

  10. Enter the source code identifying Mobile Commons to your Salsa system. The default entry is Mobile Commons.

  11. Select the type of data sync:

    • Select On to enable Liberal data sync: sync data in both directions, regardless of the opt-in status.

    • Select Off to disable Liberal data sync (Conservative sync): sync data only for those records with an opt-in status of true in your Salsa system.

  12. (Optional) Enter your notes for internal use only.

  13. When you are done, select Update.

Tip: To test your configuration, supply your Mobile Commons team with a web form that we can use to generate test users in Salsa and validate the data sync from Salsa to Mobile Commons.

Reviewing required and supported fields

The Salsa data sync supports all standard profile fields; it does not sync custom fields. After you configure your Salsa integration with Mobile Commons, review your Salsa system and Mobile Commons user records (profiles) to ensure required and supported fields are available in both data sets.

The following fields are required:

Category Field Default field name
Subscription status Opt-in (required for Conservative data sync) "opt_in_status"
Demographic Phone number (required) "phone_number"
  First name "profile_first_name"
  Last name "profile_last_name"
  Email (required) "profile_email"
Address/Location Street address "address_street_1"
  Street address 2 "address_street_2"
  City "address_city"
  State "state"
  Zip Code "address_postal_code"
  Country "address_country"
Other Constituent ID

The field names differ by data set:

  • "constituent ID" (Mobile Commons)

  • "supporter_KEY" (Salsa)
  Donation amount "amount" (in both data sets)

If you are not using the default field names, use custom field mappings to specify field names in Salsa.

To set up custom field mappings:

  1. Select Home Home in the left pane, and then select Data Sync.

    The home page for your Salsa sync opens.

  2. In the Integration Actions panel on the right, select Edit Field Mappings.

  3. Review the field names to ensure that they are correct.

    • The Field column contains the Mobile Commons field name.

    • The API Field Name column contains the API field name in Salsa.

    • The CSV Heading column contains the heading in the CSV export file.

  4. To limit the sync to records that contain data in specific fields, select the Required? checkbox next to the field name. When a field is required, it must contain a value in order to be synced. Empty fields are not synced.

    Caution: Do not select Required for Phone number, Email, or Opt-in status fields, which must by default exist in both databases in order to sync data. Use caution if you change the field name for any of these three fields; if the custom field name is incorrect, the data sync will fail.

    Caution: Do not select Required for Constituent as this ID is provided by Salsa. If it is set to Required, Mobile Commons profiles will not have this ID, causing the sync from Mobile Commons to Salsa to fail.

  5. When you are done, select Save.

Activating the Salsa sync

Before you begin, review the configuration settings for your sync:

  1. Select Home Home in the left pane, and then select Data Sync.

    The home page for your Salsa sync opens.

  2. In the Integration Actions panel on the right, select Configure Configure Integration.

  3. Review the configuration settings, making adjustments as needed.

  4. When you are done, select Update.

  5. To activate the Salsa integration sync, in the Integration Actions panel on the right, select Activate Activate Data Sync.

    The indicator in the upper-right corner is Active Active. The first data sync will run the following morning.

Data sync updates

After activation, the Mobile Commons data set and your Salsa database are both updated on a regular basis:

  • Mobile Commons checks for updates nightly, processing all recent updates from Salsa during overnight hours.

  • Any new opt-ins or opt-outs from Mobile Commons are synced to Salsa every five minutes during the day.

    • For users whose profile records contain an email address, new opt-ins are added to Salsa as a new record with an opt-in status of true.

    • For users with a matching record in Salsa, new opt-outs update their opt-in status to false.

    Note: Once user records are synced, the record number from the Salsa system is added to the Constituent ID field in Mobile Commons user profile and serves to identify records across both of your systems.

After your data sync runs, you can open the Synchronization report. For more information, see Working with the Synchronization report.

Tip: If you need to shut off the data sync with your CRM system, whether temporarily or permanently, you can deactivate it. For more information, see Deactivating the integration.