Integrate New/Mode with NationBuilder

This is a complete guide to syncing your New/Mode actions to NationBuilder, from creating an integration in your organization to customizing field mapping in individual actions.

Adding a NationBuilder integration to your Organization

Connecting your NationBuilder integration with an Action

Syncing the fields in your Action to NationBuilder

Syncing Email Opt In to NationBuilder

Additional configuration options: political capital, constant field values

Tagging supporter data

Troubleshooting your integration:

Resetting a NationBuilder integration

Adding a NationBuilder integration to your Organization

1. Log into your NationBuilder account as an administrator.

2. Go to Settings > Apps > Install new app.

3. Find the NewMode app in the list and click the Install button next to it. (You might have to confirm a small popup dialog.)

4. Now you can head back over to your Organization dashboard at New/Mode, and follow the steps to Create an Integration.

5. Once you've selected NationBuilder as your CRM Service, you'll be asked to enter your NationBuilder Nation Slug. This is the first part of the URL of your NationBuilder nation, i.e. the part in front of .nationbuilder.com:

6. Click the Save button. Your Nationbuilder dashboard (or a page asking you to log in) should open in a new tab. You'll see a page asking to authorize the New/Mode integration. Select Authorize, and head back over to New/Mode.

7. After returning to New/Mode, click the Establish OAuth2 Connection tab. A message reading Success acquiring OAuth2 Access Token or OAuth2 Access Token already available should appear.

If you don't see a success message there, take a look at the Troubleshooting section.

Connecting your NationBuilder integration with an Action

In your New/Mode action, open the Edit tab, and scroll down to the Integrations section of the Basic Configuration page. Select your NationBuilder integration from the 'CRM Integration' menu and click on 'Save & Next' to complete the process.

Syncing the fields in your Action to NationBuilder

1. Start by opening Advanced > CRM Integrations to arrive at the Sync Settings page:

Sync Settings - NationBuilder

The Sync Settings page has three columns:

Webform Component NationBuilder Person Field
Operations

A list of the fields that supporters fill out on    your action.

A list of the user fields in NationBuilder where the data from your action will be sent.

Where you can edit your action's field to change the NationBuilder field they're linked to.

If any of your action fields listed on the left-side column are not pointing to the field you want on the NationBuilder field column, follow these steps:

2. Click on Edit.

3. Find the NationBuilder API section and, under 'NationBuilder field', select the right user field from the drop-down menu.

4. Scroll down to the end of the page and click on the Save button to complete the process.

Send To - NationBuilder field

Syncing address data to NationBuilder

If your action has an address field, follow our guide to complete the additional setup required to send supporter addresses to your NationBuilder.

Syncing Email Opt In to NationBuilder

1. On your action, click on Advanced and select CRM Integrations.

2. On the list of fields, find Email Opt In and click on the blue Edit link. (If you don't see an opt-in field, create an opt-in componend for your action following the steps here).

3. On the Send To section, select /tags as the NationBuilder field.

4. Under Option settings, check the box for 'Customize keys'.

5. Now that the keys fields are visible, enter the tags you want to use for each option.

Action opt-in tags

6. Click on the 'Save component' button to save the changes.

Additional configuration options

Start by opening Advanced > CRM Integrations to arrive at the Sync Settings page, then click on 'Edit NationBuilder API':

On the next page you'll see a few different optional settings:

  • Title: you can change the name of the integration here.
  • Political capital amount: enter the amount of political capital (in cents) that will be awarded to each submission on the action. (If you don't use political capital in NationBuilder you can leave this blank).
  • Political capital reason: enter the reason why the political capital you entered above was awarded. (You can leave this field blank too if you don't need it).
  • Constant Field Values: these are separate fields that allow you to attach other information to your supporter data:
    • On the NationBuilder Person Field drop-down menu, select the field in NationBuilder that this data should go to. (If you create custom people fields in NationBuilder you'll see it listed in this menu along with the default fields).
    • Under Constant Value, enter the value that you'd like to be added to each Person and sent to the field you selected above. (You can also use tokens to send metadata from submissions to NationBuilder).

Tagging supporter data using Constant Field Values

New/Mode adds a couple of tags by default to the supporter data we sync to NationBuilder: 'newmode' and 'oce' (which stands for "one click email" and changes depending on the type of action you're using).

To send other tags, open Advanced > CRM Integrations to arrive at the Sync Settings page, then click on 'Edit NationBuilder API'.

Next, select '/tags' as the NationBuilder Person Field, and enter the tags you want to add in the Constant Value field, separated by commas. These tags will appear on your supporter's Person profile in NationBuilder..

Make sure you save any changes!

Troubleshooting your NationBuilder integration

 

 

1. In your Dashboard, click on the integration on the list on the right, then check the 'Establish OAuth2 Connection' tab.
Does it show 'OAuth2 Access Token already available'?

No → Reset the integration following the steps described below.
Yes → Check the action's field mappings next.

2. In the action, open Advanced > CRM Integration and review the connection between the components in the action and the fields in NationBuilder.

Is all the information you need from the first column mapped to the correct fields in NationBuilder in the second column?

No → Fix this following the steps in Syncing the fields in your Action to NationBuilder.
Yes → Skip to the next step.

3. In Advanced > CRM Integrations, click on 'Edit NationBuilder API' and review the Constant Field Values.

Is there any NationBuilder field that's set to receive information from both a form component and a constant value?

Yes → Most NationBuilder fields (except for tags) can only receive information from a single source. If there is a component and a constant value mapped to the same field in NationBuilder, remove one.
No → Contact us at support@newmode.net and we'll look into it!

Resetting a NationBuilder integration

  1. In the action, open Advanced > CRM Integrations, and click on 'Edit NationBuilder API'. Take note of any settings and values there, as they'll be deleted in step 2. (Repeat this process if you have multiple actions connected to the same integration).
  2. In your Dashboard, delete the NationBuilder integration from the organization.
  3. Open a new tab in your browser and log into your Nation with an admin account. Once there, remove the New/Mode app from Nation (Settings > Apps > Installed Apps > Uninstall New/Mode).
  4. Back in your New/Mode Dashboard, create a new NationBuilder integration.
  5. Authorize the connection between NationBuilder and New/Mode when prompted.
  6. Open the 'Establish OAuth2 Connection' tab on the integration to look for a success message stating that an OAuth2 token is available.
  7. Connect the new integration to an action.
  8. In the action, open Advanced > CRM Integrations and reenter any settings and values from step 1, so that the integration has the same configurations it did initially.
  9. Open the Submissions tab, select a submission, and use the 'Execute' menu to sync it manually.
  10. After you've confirmed that the new integration works, repeat steps 7 and 8 for any other actions that you want to sync with NationBuilder.

If you still get sync errors with the new integration, contact us at support@newmode.net





    Last updated: April 15, 2021