Formstack: HTML forms integration
In this article:
- Setting up your Formstack integration
- Connecting your Formstack account with LGL
- Connecting your form
- Form preferences
- Mapping your form so your data flows into LGL
- Mapping the form fields
- Record matching preferences
- Mapping fields from source
- Reviewing and saving Formstack form submissions
- Integration Queue
- Editing the constituent assignment for records
Setting up your Formstack integration
Little Green Light is integrated with Formstack’s HTML forms, which makes it possible to collect information from your constituents online and have it automatically entered into your LGL database. Formstack forms can be hosted by Formstack or deployed on your website, for instance.
In this article, we walk you through connecting LGL to your Formstack account and then show you how to configure the forms so that information submitted through them will flow automatically into LGL.
Connecting your Formstack account with LGL
To set up your Formstack integration with LGL, you’ll first need to create a Formstack account. Then create a Formstack API key, and paste it into LGL:
- Click the My Profile button to open your profile.
- Choose API.
- On the Formstack API page, copy the entire key (making sure you have grabbed every character in the key—otherwise the integration won’t work.)
- In LGL, go to Settings > Integration Settings > Formstack Integration, and paste the API key into the Set Formstack API Key field.
- Click the Set API Key button.
- Click the Copy webhook url button to copy the webhook.
- Click the Okay button to copy the webhook to your clipboard (which means you’ll be able to paste it into the designated field in Formstack).
- Now go to your Formstack account and go to Settings > Emails & Redirects for your form. Click the Click here to change link in the “After the Form is Submitted” section of the page:
- In the dialog that opens, click the “Send Data to an External URL (WebHook)” radio button:
- Paste the webhook you copied a few steps earlier in the Webhook URL field. You will also need to check the “Post IDs using fields IDs instead of field names” checkbox, as shown below. Then click Save.
Click the New key button to generate your API key, if one hasn't already been created. A string of characters and numerals will appear. This is your API key.
Now you’ll need to copy and paste the key into the designated field in your Formstack Integration page in LGL:
Connecting your form
Note that when you create each form, you’ll need to add a webhook for it:
From this listing, you can toggle a few preferences:
- Review preferences: Do you want to automatically save new records or add them to a queue for review? We recommend setting this to “Yes” initially to make sure that submissions are happening appropriately. You can update the settings to process the records automatically at any time by unchecking the box.
- Review Queue: There are four possible queues: Constituent, Gift, Event, and Volunteering. This allows you to review and approve all submissions of a given type more easily.
- Use as template? Checking this box lets you use the selections made in your form as a template that you can use for other forms.
Now that your Formstack form and your LGL account are connected, you can create the mapping between the two.
Mapping your form so your data flows into LGL
To make the integration for any form complete, you need to tell LGL how to map the data from Formstack’s form into the appropriate places in LGL. For example, a simple donation form from Formstack would probably contain information about the following three types of data in LGL, at a minimum:
- Constituent name information
- Constituent contact information (phone, email, address)
- Gift information (amount, received date, notes, etc.)
Mapping the form fields
After choosing a form to integrate, you can select our record matching preferences for the form (how constituent information from new submissions will be matched to existing records in LGL), and also define the field mapping rules so that the information for each submission will end up in the right place.
Record matching preferences
You can decide if LGL should try to match new records to constituents by email and name, or just name, or both. If neither option is selected, LGL will create new constituents for every submission.
Mapping fields from source
All of the form fields from the selected Formstack form will be listed in this section, and you can map them to the appropriate record type and field within LGL. Many of these mappings will happen automatically if you use the standard Formstack field names, but if a field is not mapped (if the -- Do not import -- option is selected), then it will be left off.
Since this is a donation form, you would want to check the Include gift fields option, so that you can map the "Payment total" from Formstack into the "Gift amount" field in LGL. Now that you have the basics in place, you can save the form and complete the integration process.
Note that the only option for names is to map to full name, and the only option for address is to map the full address. When the data is brought in, LGL will attempt to parse it, however, as with any parsing this is not guaranteed to yield perfect results. The full address will be added to the street field in LGL, but if you use Smarty Streets (link to: http://help.littlegreenlight.com/article/173-clean-your-addresses-with-smartystreets-in-lgl), the address will be normalized.
Reviewing and saving Formstack form submissions
Now that you have a Formstack form (or two) mapped to our LGL account, the fun part begins. If you had existing forms in Formstack, it is quite likely that you have some entries logged there that are not yet in LGL. If so, the first step is to import them all.
Import all existing entries
You can pull all submissions from a given form into LGL all at once by clicking on the Import all button in the Actions column. This will go out and grab all of the entries in the specified Formstack form and pull them into LGL for review.
The import process will kick off within a minute or two and then start adding all the entries into your integration queue. If you have the Require review? checkbox checked, they will not be saved into your main LGL database. You can access your integration queue by clicking on the Integration Queue link in the Settings sub-navigation:
You can also go straight to the queue for a particular form by clicking on the X records link in the Submissions (to LGL) column:
This will bring you into the integration queue with the entries for that form listed:
From here you can perform a number of different actions:
- Filter results by status, source, and queue
- Review individual records and save or reject them as appropriate. The information for each record is displayed, so you can see what information will be added to LGL
- Save, reject, or reprocess whole sets of records (as defined by the filter selected)
- Assign constituents to records that did not find a match but should have
- Change the constituent if the assignment is not accurate
As mentioned previously, you can save records individually or in a batch. In both cases, the records will be set to a pending state and then imported into your main LGL database. In many cases, a form will describe multiple types of information, so a single record from Formstack might create a constituent, related contact information, and one or more gifts. It is also quite typical for categories to be added.
In the case where a record is updating an existing constituent, none of the primary constituent information (names, etc.) will be updated. However, all additional kinds of data will be appended (contact information, categories, gifts, etc.)
To save an individual record, click the Save button in the Record Status column. To save a batch of records, select the appropriate option from the -- bulk updates -- menu:
Sometimes you will get submissions from your forms that you don’t want to save. For example, if the submission is not valid or if it contains bogus information (like when you are testing), you probably don’t want to save it all the way into LGL. So, in those cases you can reject the records. This can also be done individually or in bulk.
Editing the constituent assignment for records
All form submissions must be connected to a constituent in one way or another. If a match is not found, then a new constituent record will be created. In the event that LGL does not match the constituent but it already exists (and you know this), you can override the constituent assignment.
If no constituent was found, you will see a record like this:
To set the constituent, you can click on the icon next to the constituent field, and then search for a constituent within the LGL database. Once this is done, you can save the record and the selected constituent will be updated.