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.

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

This menu is where the forms are created and configured.

Creating a Form

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.

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 textbox add the text Bearer SECRET_TOKEN, except SECRET_TOKEN must be the real secret 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.
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.

Key: first_name

Select your first name form field in the dropdown.

Key: last_name

Select your last name form field in the dropdown.

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.

Key: employer

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

Key: occupation

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

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.

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.