Setting up NationBuilder

Mobile Commons supports NationBuilder API v1.

Unlike most out-of-the-box data syncs, the NationBuider integration does not require an email address.

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

To set up the NationBuilder data sync:

Preparing for setup

Before you begin, gather the log-in credentials and set up any other key connection settings for your NationBuilder 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 NationBuilder 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.

  1. Make a note of the following credentials from your NationBuilder system:

    • The existing NationBuilder login or API user name and password

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

    • OAuth API authentication token

    • API host name, which is usually the URL of your NationBuilder account

Configuring the NationBuilder integration

To sync data between your NationBuilder 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 NationBuilder.

  3. Select Create.

    The NationBuilder configuration form opens.

    NationBuilder configuration form

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

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

  5. (Optional) If users from NationBuilder 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. All mobile users from NationBuilder will receive opt-in messages from the opt-in path you specify.

  6. Enter the API authentication token (OAuth) for the web service.

  7. Enter the host name for API requests.

  8. In the Recruiter ID field, enter the Person ID for the user who creates the new records.

    Tip: The Person ID is usually a generic Mobile Commons user.

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

  10. When you are done, select Update.

Reviewing required and supported fields

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

The following fields are required:

  • Phone number

  • Opt-in status (for web signup only)

Note: Email is not a required field.

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

To set up custom field mappings:

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

    The home page for your NationBuilder 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 NationBuilder.

  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 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 either of these 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 NationBuilder. If it is set to Required, Mobile Commons profiles will not have this ID, causing the sync from Mobile Commons to NationBuilder to fail.

  5. When you are done, select Save.

Activating the NationBuilder 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 NationBuilder 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 NationBuilder integration sync, in the Integration Actions panel on the right, select Activate Activate Integration.

    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 NationBuilder database are both updated on a regular basis:

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

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

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

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

    Note: Once user records are synced, the record number from the NationBuilder 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.