123 Form Builder

This page describes configuring 123 Forms in Landcare Tasmania.

Please note, this document is a work in progress, and changes/additions are still being made

#Overview

The Landcare Tasmania website now uses 123 Form Builder to collect information from users (for individuals, organisations, and memberships).

Creating a new form no longer requires a developer. However to get the form to work with Nationbuilder a data integration between the two systems must be configured.

This document describes the steps to set up the integration between 123 Form Builder and Nationbuilder.

There are two main tasks when setting up the integration:

1. When the 123 Form is submitted, the data must be sent to Nationbuilder and the answers written to the correct locations.

The majority of the work setting up a data integration is creating the data mappings from the 123 Form Fields to the desired Nationbuilder fields.

2. The 123 Form must be shown in the Landcare Nationbuilder website.

This is done by setting up a host page in Nationbuilder and using page tags to activate the desired 123 Form.

The 123 Form fields can also be pre-filled with existing user data. This is done by configuring the Nationbuilder host page, and is described in more detail below.

Finally, the 123 Form should be set to redirect back to a Landcare page once the form is submitted. That is discussed last in the page.

123 Form to Nationbuilder Integration Options

There are two options to integrate 123 Form submissions with Nationbuilder.

1. The default integration provided by 123 Forms and Nationbuilder.

The documentation for configuring this integration is provided by 123 Form Builder here: https://www.123formbuilder.com/docs/nationbuilder-integration-for-online-forms/

This integration only can be used for forms for individual users.

This integration will only allow adding new tags to the user on form submission. If you wish to update or remove specific tags you will need to use the For Purpose Custom Integration.

Important: if using this default integration, please never check "Overwrite tags if this person already exists". The system uses tags to link users with their organisations and some forms might store answers as tags. This will delete that information.

To link your individual form into a Nationbuilder page and pre-fill any fields please see the section below called "Forms for Individuals".

2. The custom integration provided by For Purpose.

This custom integration was created by For Purpose specifically for Landcare organisations.

Landcare group profiles differ from standard individual profiles:

• Groups are managed indirectly by individual user accounts, but are never logged into directly. Effectivly a user will be filling in a form for another profile (the organisation).

• Groups do not have email addresses.

The custom integration allows updating organisations that do not have an email address. This option must be used for all organisation forms.

However, the integration can also be used for individual forms. It provides some more powerful features but is also a bit more complex to set up. Use this integration for individual user forms only if you need more powerful tag or address control that the default integration does not provide.

The majority of this documentation details the steps to configure the For Purpose Custom Integration.

1. Create 123 Form

Click here to read the 123 Form Builder Documentation

When creating your new 123 Form, be mindful of the where each field is going to end up in Nationbuilder.

If you are intending on writing the answer to a Nationbuilder custom field, note the field can be of different types:

1. A Text field. In 123 Form Builder you should use a Short Answer field in your form.
2. A Number field. In 123 Form Builder you should use a Short Answer field in your form. Then select the field and click on the cog to open the field settings, and set the Validation -> Data format to numeric.
3. A Checkbox field. In 123 Form Builder you should use a Single Choice field in your form.
4. A Multiple Choice field. In 123 Form Builder you should use a Dropdown field in your form. Then select the field and click on the cog to open the field settings, and add the choice options to the dropdown. It is important that these option are exactly the same as those in the Nationbuilder multichoice custom field options.

You also have the option of saving answers as tags.

1. You can use a Multiple Choice checkboxes to save each answer as a separate tag. When checked a tag is added, if unchecked the tag is removed.
2. You can use a Dropdown or Single Choice to save an answer as a single tag (where the older tag will be removed if the answer changes).

Details on how to configure saving answers as tags is described in more detail below.

The following fields can be added to capture location information.

1. An Address field. Add the field, then click on the cog, and change the Address format to Australia and the Postal/Zip label to Postal Code. Please also see the special mapping notes on this field below.
2. A Location on Google Map field. You will need to collect this information if you wish to display the organisation on a map. Add the field and the click on the cog to open the settings panel. You will need a Google Maps API key for this field to work. Please contact the appropriate person at Landcare or For Purpose to obtain this key. Please also see the special notes on this field in the mapping section below.

2. Add Special Hidden Form Fields

These steps are for the Custom Integration only.

Once you have completed your form, two additional hidden form fields need to be added for the form to work.

• id - this hidden field lets our integration know which user or organisation to update (Landcare organisations do not have an email).
• Authorization - this hidden field contains a token to ensure that only authorized users can change information for that user or organisation.

Steps to add special hidden fields in 123 Form Builder:

1. Add a new "Short Answer" field to form. Call it "User ID".

• Select the field and click the cog. In the panel that opens on the right, set the "Hidden" toggle and set the "Readonly field" toggle.

2. Add a new "Short Answer" field to form. Call it "Authorization".

• Again, select the field and toggle on "Hidden" and "Readonly field".

Setting up these special form fields is now done. Note these fields will be pre-filled once the form is integrated in Nationbuilder, steps to do this is described at the end.

3. Set up Integration with our custom Nationbuilder webhook

• Select the "Setup" menu, then select "Integrations" in the dropdown.

• Select "Webhooks" and click the "Connect" button.

• Enter our custom integration URL:

https://landcare-tasmania-api.herokuapp.com/people-update-123form

4. Set up mappings from 123 Form Builder fields to Nationbuilder Fields

The fields collected in the new form must be mapped to the correct fields in Nationbuilder. This is the majority of the work to set up the integration.

4-1. Set up special field mappings

Begin by mapping the special "Authorization" and "id" fields that were created previously.

• Check "Use Webhook Mapping".

• Set up the mapping for the special "Authorization" field. Click "Customize Headers". Only the Authorization field needs to be set in this "Headers" dialog.

• Change the first Map header parameters field to Authorization. (it is important this field is exact - note the capital "A" and the American "z").
• In the dropdown, select the Authorization form field you created previously.
• Click "Save".

• Click "Customize Data". This is where the rest of the form data mappings are set up.
• Set up the mapping for the special "id" field. This special field is to tell the integration how to find the right user or organisation to update.

• In the first Map URL parameters field, type "id". (this should be also be exact - ensure "id" is lowercase.)
• In the dropdown, select the "User ID" field you created.

4-2. Set up main form field mappings

Now the same mapping needs to be done for each form field. You will be mapping your form answers to one of the following locations in Nationbuilder:

Mapping an answer to a Nationbuilder custom field.

• Type the Nationbuilder custom field slug into the relevant Map URL parameters field.
• Select the correct 123 Form field for that answer.

You can find all Nationbuilder custom field slugs in the control panel by clicking "Settings" in the side bar then the "Nation defaults" tab, and "Custom fields" subtab.

Mapping an answer to a default Nationbuilder profile field (for example first_name or last_name).

• Type the Nationbuilder field into the relevant Map URL parameters field.
• Select the correct 123 Form field for that answer.

A full list of all available fields can be found clicking here.

Note: Nationbuilder uses the "last_name" field to store the organisation name

Note: Not all Nationbuilder fields listed in the above link can be updated - but all standard fields can be

Mapping an answer to a tag.

Due to limitations on the number of allowed custom fields in Nationbuilder, it can be necessary to store some answers as tags on the user or organisation.

This involves using a few special keywords in the Map URL parameters field.

There are three cases covered:

Case 1: I want to save a text answer as a tag. I don’t need to remove this tag.

Solution:

• Create a 123 form text answer
• In the mapping, choose the 123 Form Field for that answer
• Set the Map URL parameters field to tag
• This will tag the organisation with the answer.

Note, you will probably not normally want to tag users with free text answers, but a good use case is to set a hidden pre-filled form field to tag all users who answer the form (like a NB sign up form tag).

Case 2: I want a checkbox (or a group of checkboxes). If any option is checked, tag the user, if not checked remove the tag.

Solution:

• Create a Multiple Choice (checkbox) answer.
• For each answer, create a seperate data mapping for each answer. Set the 123 Form field to be the checkbox answer
• Set the Map URL parameters field to tag.TAG_NAME where TAG_NAME is the tag you wish to add if checked.
• For example an “I like cats” checkbox could be tag.likes_cats. If “I like cats” is checked, the user will be tagged likes_cats, if not the tag will be removed

Important Note: 123 Forms will not allow the colon : character in the mapping parameter field so these tags cannot include that character. If you wish your tag to include a colon, you can use two full stops (..) which will be replaced when generating the tag.

Case 3: I want a dropdown or a single choice radio button group. If a choice is made I want the user tagged with the answer and all other tags for previous answers should be removed.

Solution:

Note: this requires that the tags will be in the format category:answer

• Create either a Single Choice radio button group or a Dropdown answer. Set your answers using the cog to open the side panel.
• Set the data mapping to use your dropdown or radio buttons form field
• Set the Map URL parameters field to be tag_prefix.CATEGORY where CATEGORY is the common prefix all answers will share.
• For example if the answers are “Chicken”, “Steak”, “Veges” the field could be set to tag_prefix.food
• If the user picks "Chicken", they will be tagged food:Chicken. All other tags with the prefix food: will be removed.

Mapping and Address and Geolocation.

These fields have some additional requirements:

You should add a 123 Form Address type field to collect address information.

Addresses can be mapped to different Nationbuilder address types, for example: home_address, work_address, billing_address, or registered_address.

If collecting info for a organisation, please use work_address.

Because of this, the mapping fields for addresses require a slighly different format. For example, to collect fields for a work_address, use the following mapping names:

• work_address.address1 - for Street Address (line 1)
• work_address.address2 - for Street Address (line 1)
• work_address.city - for City
• work_address.state - for Region
• work_address.zip - for Postal/Zip Code
• work_address.country_code - for Country

Note: Nationbuilder uses codes for country and region, like 'TAS' for Tasmania and 'AU' for Australia. The intergration handles mapping these values for you, but be aware that only Australian regions and a few countries (AU, NZ, UK, US) are currently working.

If you wish to display this profile on a map you will also need to collect the Geolocation (lat / lng).

To get 123 Formbuilder to Geocode an address:

• Add a Location on Google map field to the form

• Create a new Short Answer field to hold the coordinates. Call it Lat Lng, and click on the cog and toggle Hide Field so it is not visible to the user.

• Click on the Google maps field, and then the cog to open the properties panel.

• Set the Google Maps API key. You will need to obtain this key from the relevant admin at Landcare Tas or For Purpose.

• If you have an address field on the form, you can link the map so it updates when the address changes. Toggle on Match with Address field and select the address field in the drop down.

• Toggle on Send coordinates to a field and pick the Lat Lng field you created. When the user choses an address, this field is set with the coordinates of the address.

• Return to the Set up -> Integrations -> Customize Data form.

• Add two new mapping entries for the coordinates:

• work_address.lat -> set this to your Lat Lng form field

• work_address.lng -> also set this to your Lat Lng form field

Note: 123 Formbuilder stores the lat and lng coordinates in a single text field - the integration will automatically convert this to the Nationbuilder 'lat' and 'lng' address fields

Finish the mapping:

• Hit the "Save button" to close the mapping dialog.

• Hit the "Save" button on the webhook form to finish.

Note - during development, sometimes 123 Forms complains the webhook "cannot be found". Just click save again and it should work. If you continue to get errors, please let FP dev know.

5. Find your 123 Form ID

Once the host page is created, you need to find and note down the 123 Form ID for your new form. This ID is used to link the 123 Form into Nationbuilder.

To find the 123 Form ID:

• One method is to click the "Publish" button in 123 Form Builder. In the "Copy the link to your form" box, there is a web link. The Form ID is after "https://form.123formbuilder.com/", in this example the form ID is 6823577.

6. Activate the Form in Nationbuilder

To activate the Form in Nationbuilder, it first depends if the form is for an Individual or a Group.

Forms for Individuals

You have a few options to activate an individual form:

Option 1: Quick 123 Form Activation

You can quickly activate a 123 Form on the bottom of any basic page by tagging the page 123form:FORM_ID where FORM_ID is the 123 Form ID you found in the previous step.

This option is the easiest unless you wish to pre-fill many form fields.

Option 2: Full Page Form Activation

For more complex forms where:

• you plan to prefill many form fields
• you only need to show the form on the page (and no other content)

Then creating a basic page to host the form is the better option. This will allow you to configure the prefilling of the form in the page content (see step 7).

• Create a new basic page in Nationbuilder.

• Tag this page 123form:FORM_ID where FORM_ID is the 123 Form ID you found the previous step.

• Tag the page page_123_form to activate the page.

Option 3: Subpage Layout Form Activation

Use this option when you are using the subpage layout and have other content modules on the page.

• Create a new subpage.

• Tag the page 123form:FORM_ID where FORM_ID is the ID you found the previous step.

• Tag the page module_123_form to activate the 123 Form subpage module.

Forms for Organisations

Form for Organisations are activated differently from Individual Forms. This is because a organisation profile is managed by an individual user (i.e, a organisation is a seperate profile from the user entering the information).

This requires that the form must be activated on the Group Admin Page.

Note - the page might have already been created for you - check for a "123 Forms" folder in the site.

• Create a new basic page in Nationbuilder to host the form.

• Tag the page 123form:FORM_ID where FORM_ID is the ID you found the previous step.

The specific form to show is controlled by tagging your new page with one of the following tags:

• profile_form_account_settings - this form is shown when the user edits the organisation account settings (for all organisation types)
• profile_form_profile_settings - this form is shown when the user edits the organisation profile settings (for all group types)

New Membership Forms (one for each organisation type):

• profile_form_new_membership_group - this new membership form is shown after a new community organisation is created
• profile_form_new_membership_school - this new membership form is shown after a new school organisation is created
• profile_form_new_membership_associate - this new membership form is shown after a new associate organisation is created

Renew Membership Forms (one for each organisation type):

• profile_form_renew_membership_group - this form is shown after when a community group renews their membership
• profile_form_renew_membership_school - this form is shown after when a school renews their membership
• profile_form_renew_membership_associate - this form is shown after when a associate renews their membership

Note - these activation tags may not be the final list
Note - if new forms need to be linked in, it requires a dev change to the Nationbuilder template _z_profiles_show_group_admin.html.

You should now be able to view your form via the members toolbox link for Organisations.

7. Pre-fill 123 Form Values

• The embedded 123 Form can have its fields pre-filled from values in Nationbuilder.

• Important: For Group forms the two special form fields that were created above ("id" and "authorization") must be set up to be pre-filled for the form to work. Instructions on how to do this are below in the section called Steps to set up pre filling Special Fields.

• All other form fields you have created can be optionally pre-filled.

Option 1: Configure Prefilling in Page Content

It is easier to configure the prefilling in the basic page content.

Note: If you activated the form using the "Quick 123 Form Activation" then you must use Option 2: Configure Prefilling using Page Tags below.

Each line in the page content defines how to prefill a 123 Form field with a Nationbuilder value. Each line should be in the following format:

123_FORM_FIELD_ID=NATIONBUILDER_FIELD

How to find these values is described next.

Examples:

• Mapping the id field: 22212345=id
• Mapping the last_name field: 22213434=last_name

Option 2: Configure Prefilling using Page Tags

Alternatively you can set the prefill config by adding tags to the Nationbuilder page.

If you activated the form using the "Quick 123 Form Activation" then you must use this method.

These tags should be in the following format:

123formfield:123_FORM_FIELD_ID=NATIONBUILDER_FIELD

How to find these values is described next.

Examples:

• Mapping the id field: 123formfield:22212345=id
• Mapping the last_name field: 123formfield:22213434=last_name

Finding the 123 Form Field ID.

Each 123 Form Field has a unique ID. To find this field ID:

1. Click on the relevant field in the 123 Form, click the cog, and then scroll to the bottom of the form on the right.
2. At the bottom, there is a drop down called "FIELD DETAILS". Click to open the dropdown.
3. Copy the Field ID.

Note: address fields have a single Field ID but multiple sub fields (Address line 1, suburb, city etc). For work addresses you only need to copy the main field ID (see more below).

Note: Some 123 Form Field answers are "combined" into a single group with a single form field ID. For example if you created a group of checkboxes then you will find they all are grouped with the same field ID. To target a specific checkbox usually you would add the position in the list to the field ID (starting from 0). For example if the checkbox group form field ID is 2335553 then each individual checkbox ID will be 2335553-0, 2335553-1, 2335553-2 etc. Please refer to this more advanced video on finding the 123 Form Field IDs.

Find Nationbuilder Field

The Nationbuilder Field can be either:

1. A custom field slug. These are the same slugs that were used above. You can find all custom field slugs in the Nationbuilder control panel by clicking "Settings" in the side bar then the "Nation defaults" tab, and "Custom fields" subtab.

2. If you have created a group form, you have access to all profile fields, listed here

3. For an individual user form, you have access to all sign up fields, listed here

4. An address. Address fields are special as they have multiple sub fields (address line 1, suburb, city etc). If you use the address (primary address), home_address or work_address field names, the address sub fields are automatically pre-filled for you. For to prefill a the primary address, the config line would be:

YOUR_123_FORM_ADDRESS_FIELD_ID=address

5. A fixed value. Sometimes you might want to pre-fill a form field with fixed text. For example if you have created a form field to add a tag to this user you could prefill it here. To do this, add quotes around the field you want to add. For example:

222345="my_tag_to_be_added"

6. A tag. If you have saved an answer as a tag (see the tag section above), then you might want to pre-fill the answer again. This requires using a few key words in the Nationbuilder field.

6.1 tag:TAG_NAME - this should be used with checkbox answers. If the user has the tag TAG_NAME the box will be checked. For example:

223456=tag:likes_cats

If the user has the tag likes_cats the checkbox will be checked

6.2 tag_prefix:TAG_PREFIX - this should be used with dropdown answers that have been saved as tags in the format TAG_PREFIX:ANSWER. If the user has such a tag with a matching TAG_PREFIX then the form field will be pre-filled with the ANSWER value. For example:

1234453=tag_prefix:destination

If the user has the tag destination:London then the form dropdown answer will be set to London

7. The final allowed field names are special internal fields, for example "authorization" which is used for the security token.

Steps to set up pre filling Special Fields (id and Authorization)

1. Prefill User ID Field

• In 123 Form Builder: Click on the "User ID" field, click the cog, then scroll down to the bottom of the form on the right, click FIELD DETAILS, then copy the Field ID
• In Nationbuilder: Add a line to the page content in the format 123_FORM_FIELD_ID:id - replace FIELD_ID with the value you just copied.

2. Prefill Authorization Field

• In 123 Form Builder: Click on the "Authorization" field, click the cog, then scroll down to the bottom of the form on the right, click FIELD DETAILS, then copy the Field ID
• In Nationbuilder: Add a line to the page content in the format 123_FORM_FIELD_ID:authorization - replace FIELD_ID with the value you just copied.

Your content page should look something like the following:

You can follow the same steps to set up pre-filling any other fields on your new form.

Redirecting the Form after submission

After the user submits their form, they should be redirected back to a page in the Landcare Tas website. This must be configured in 123 Form Builder.

The redirect URL can be set in 123 Form Builder by clicking the Create menu, then Thank You, then toggle Redirect and select the redirect page URL.

Enter a full Landcare URL, for example to redirect back to the members toolbox, enter https://www.landcaretas.org.au/members-toolbox.

Membership Payments Redirect

For membership forms where the user (might) pay online for a membership, the redirect system must be a bit more complicated.

The general idea is:

• the membership forms have a question asking the user how they would like to pay.
• if the user selects "pay online", then the redirect link includes this answer as a parameter appended to the URL.
• the "Thank you" page is set up to look for this answer in the URL and redirects the user to the payment page if "pay online" is set to 'Yes'.

Additionally, for organisation payment forms we must also pass the organisation ID through to the donation page so we know which group to apply the membership to.

Here is the template for a redirect link that passes pay_online and org_id as URL parameters:

https://tassielandcare-landcaretas.nationbuilder.com/THANK-YOU-PAGE?customVars123=yes&org_id=requestUSER_ID_CONTROL_ID&pay_online=requestPAY_ONLINE_CONTROL_ID

IMPORTANT After going live replace all example occurances of https://tassielandcare-landcaretas.nationbuilder.com with https://www.landcaretas.org.au

This is a breakdown of the link parts:

• /THANK-YOU-PAGE - replace this with the "Thank you" page slug (part of the full URL)
• customVars123=yes - this is needed to turn on passing form results
• org_id=requestUSER_ID_CONTROL_ID - replace USER_ID_CONTROL_ID with the Form Field ID for the User ID - a number, just like when setting prefilling
• pay_online=requestPAY_ONLINE_CONTROL_ID - replace PAY_ONLINE_CONTROL_ID with the Form Field ID of the "pay online" option - a number, just like when setting prefilling

The 123 Form redirect link will end up looking something like:

https://tassielandcare-landcaretas.nationbuilder.com/application_thank_you?customVars123=yes&org_id=request118141960&pay_online=request118218582-0

And the generated (real) redirect link will become something like:

https://tassielandcare-landcaretas.nationbuilder.com/application_thank_you?customVars123=yes&org_id=55&pay_online=Yes

Important - do not pass the org_id parameter for individual forms

"Thank You" page payment redirect

The 123 Form will redirect to a Landcare "Thank you" page. This should be set to look for the pay_online parameter and redirect to the donation page if it is set to "Yes".

To activate this functionality on a new "Thank you" page:

• tag the page module_payment_redirect
• tag the page with the donation page slug to forward to for individual online payments: individual_payment_page_slug:MY_DONATION_SLUG
• tag the page with the donation page slug to forward to for organisation online payments: org_payment_page_slug:MY_DONATION_SLUG