Gravity Forms

This page documents Gravity Forms and the Nationbuilder integration.

This documentation compliments the offical Gravity Forms Documentation. The aim of this page is to provide the additional information to configure the For Purpose Nationbuilder integration.

Note this page does not cover the donation form, for that please see the donation form documentation.

#Summary

• ECPAT uses Gravity Forms to generate the forms to collect information from the user.
• The Gravity Forms Webhook Add-on is used to configure the connection to the For Purpose Nationbuilder integration.
• When a user submits the form, the webhook will send the form information to the Nationbuilder integration, where a user profile is created or updated if the email already exists.

Gravity Forms Menu

You will see a new Forms menu in the Wordpress admin sidebar.

This menu is where the forms are created and configured.

Quick Instructions - Creating a new Petition or Event

These are quick instructions for creating a new Petition or Event. Please see the next section for more detailed information.

Create New Petition Form

When a new petition is created, a new form should be created to tag the user in Nationbuilder with the your new petition tag.

• In the admin panel, click Forms in the left sidebar
• Look for Petition Form Template
• Hover over this text and a new submenu should appear, similar to this:

• Click Duplicate in the submenu
• You should now see a new form Petition Form Template (1)
• Hover over this new form and click Settings in the submenu
• In the settings page, give your new form a new title
• At the bottom of the page click Save Settings
• Click Webhooks in the left menu on the setting page
• You should see an entry similar to Nationbuilder Petition Form Integration - Copy
• Hover over this and a new submenu will appear. Click Edit in the submenu.
• You can ignore most of the settings on this page. The key thing to change is the tag given to the user when they sign the petition.
• Scroll to the bottom of the page and look for tag in the left column.
• Change the value in the right from Signed Petition:PETITION NAME to your new petition name, for example Signed Petition:My amazing petition.
• Click Save Settings

Finally in your new petition page, make sure the petition form block is set to use your new form.

Create Event Form

When a new event is created, a new form should be created to tag the user in Nationbuilder with the new event tags.

This is much the same process as the petition form above:

• In the admin panel, click Forms in the left sidebar
• Look for Event RSVP Form Template
• Hover over this text and a new submenu should appear. Click Duplicate in the submenu.
• You should now see a new form Event RSVP Form Template (1)
• Hover over this new form and click Settings in the submenu
• In the settings page, give your new form a new title
• At the bottom of the page click Save Settings
• Click Webhooks in the left menu on the setting page
• You should see an entry similar to Nationbuilder Event Form Integration - Copy
• Hover over this and a new submenu will appear. Click Edit in the submenu.
• You can ignore most of the settings on this page. The key thing to change is are the tags given to the user when they RSVP to the event.
• Scroll to the bottom of the page and look for tag in the left column.
• Change the value in the right from RSVP:EVENT_NAME to your new event name, for example RSVP:December Conference.
• Events also collect Access Needs. Look for tag_prefix.EVENT_NAME Access Needs. Change EVENT_NAME to your new event, for example tag_prefix.December Conference Access Needs
• If the user fills in the Access Needs question, they will be tagged for example December Conference Access Needs:Wheelchair Access
• Click Save Settings

Note: There is more information about these "tag" field formats below.

Finally in your new event page, make sure the event form block is set to use your new form.

Creating a Form (General Instructions)

• You can create a new Form by clicking on the Forms menu, then New Form.

However it is recommended to duplicate an existing similar form, if that is possible.

• Click the Forms submenu to view all existing forms. Hover over an existing form and a small menu will appear. Click Duplicate to duplicate the form. Duplicating the form will also copy the Webhook configuration which will make things easier.

ssets/images/ecpat/Gravity-Forms-Form-List-Quick-Toolbar-animation.gif" "" "" "" "" "" "" "" "" "" "" "" %}

You may then need to edit the form fields. Please refer to the Gravity Form Editor Documentation for detailed information on form editing.

There are a few points to note when creating the form fields:

• An email address field is required to create or update the user in Nationbuilder
• If you wish to collect the users Country, please use an Advanced Address Field. This will show on the form as a dropdown list of countries. To only show the Country field, hover over the form Address field and click the settings icon. Then in the right menu hide the other address fields (Street Address, City etc).

Accesing the Nationbuilder Webhooks Integration

A Nationbuilder Integration must be configured for each form. This is done using the Gravity Forms Webhook Add On.

You access the Webhook configuration by hovering over the desired form and then hovering over the pop up Settings menu. You should see a second submenu pop up with a Webhooks menu option. Either click on this, or you can click Settings to go to the settings page, then Webhooks in the side menu.

• If you have copied an existing form (recommended), you should see an existing webhooks configuration titled something like Nationbuilder Integration. Hover over the configuration and click Edit in the pop up menu.
• Or click the Add New button to create a new webhook configuration.

Configuring the Webhooks Integration

For an overview of the configuration it is recommended to read the offical Gravity Forms Webhook Documentation.

If you have copied an existing form, the fields should already be prefilled. You will just need to tweak the settings for your form.

These are a description of the fields and values you will need to use.

Name

Nationbuilder Integration (recommended)

This is the name of this Webhook (it is possible to configure multiple webhooks for a form). You can pick any name, we recommend something like the above.

Request URL

https://ecpat-api-612dc6efdc5a.herokuapp.com/people-upsert-form

This is the web address of the For Purpose Nationbuilder integration. It must be set to exactly the above address.

Request Method

POST (leave as is)

Request Format

JSON (leave as is)

Request Headers

Authorization : Bearer SECRET_TOKEN

This value stores a secret token that the For Purpose Integration checks to ensure ECPAT is sending the request. There are two settings: in the left dropdown select Authorization. In the right dropdown first select Add Custom Value (the last item), and then add the text Bearer SECRET_TOKEN, where SECRET_TOKEN is the secret webhook token. You can copy the secret token from another webhook configuration, or you will need to contact ECPAT or For Purpose to get this value.

Request Body

Pick Select Fields. This is required to configure how the feilds are sent to the Nationbuilder integration.

You will then need to pick the form fields to send. The following describes how to send specific fields to the Nationbuilder integration.

• The Key field controls where this information is written to in Nationbuilder, and must be exactly as specified below.
• The Value field is a dropdown where you should pick the appropiate form field to send.
• Click the + icon to add new fields.

Email

• Key: email

Select your email form field in the dropdown. This field is required for the Nationbuilder integration to work. Users are identified by email in Nationbuilder. The integration will look up the user by email. If they exist in Nationbuilder the user will be updated, else a new user with that email will be created.

First Name

• Key: first_name

Select your first name form field in the dropdown.

Last Name

• Key: last_name

Select your last name form field in the dropdown.

Mobile Phone

• Key: mobile

Select your mobile phone form field in the dropdown.

Country

• Key: home_address.country_code

Select Address (Country). In Nationbuilder, this will set the users Home Address Country. You can replace it with work_address.country_code or mailing_address.country_code if you wish to change the address type. Note that country_code is used - Nationbuilder expects a country code, but the integration will automatically convert country names into country codes.

Organisation or Employer

• Key: employer

Pick your Organisation or Employer form field in the dropdown. This value is stored in the Employer field in Nationbuilder.

Role or Occupation

• Key: occupation

Pick your Role or Occupation form field in the dropdown. This value is stored in the Occupation field in Nationbuilder.

Tag User (special field)

• Key: tag

This is a special key that will Tag the User in Nationbuilder with the form value. You might also want to set an explict tag here, for example to tag all users who submit this form Requested Contact. To do this, select Add Custom Value in the Value dropdown (at the bottom of the list of options). You can then enter the specific text you wish to tag the user with. You may add multiple fields with the tag keyword to add multiple tags.

Tag User if checkbox selected (special field)

• Key: tag.TAG_NAME

This is a special key that will Tag the User in Nationbuilder with TAG_NAME if they value is true, else it the tag will be removed. This is designed to be used with checkbox type answers. For example you might have a checkbox named 'Request Contact'. If you set the tag key tag.Requested Contact the tag Requested Contact will be added to the user if the checkbox is true, and removed if the checkbox is false.

Tag User with unique answer (special field)

• Key: tag_prefix.PREFIX

This is a special key that will Tag the User in Nationbuilder with a unique answer. This is desigined to be used with form values that provide a list of options to select an answer from. If the answer changes, the tag will be replaced with the new answer. These tags will always be in the format PREFIX:ANSWER, for example Favourite Food:Ice Cream. In this case you would set the key to tag_prefix.Favourite Food and the user would get tagged Favourite Food:Users Answer depending on the options provided in the form. If there already exists a tag on this user with the prefix Favourite Food: that tag will be replaced.

Log a contact with a message (special field)

• Key: contact.note

This is a special key that will Log a Contact in Nationbuilder against that user with a note set to the form answer. This is useful for the contact form message - each new form submission logs a new contact note against the user.

Updating Other Nationbuilder Fields

The integration can update any person field in Nationbuilder (that is text or numeric). For a full list of possible fields, please see this People API Reference Document.