Merge Fields on Forms

Using Configurable Joins, query exports can be selected in a form to make those data points available as merge fields within instructional text or display labels for any form field. Merge fields may be added to forms that meet one of the following criteria:

  • The scope of the form is one that requires login (e.g. Application)
  • The form is used for custom tabs or reader review forms (i.e. the scope is Reader, Person Page, or Application Page)
  • The form is used as a custom application page visible to applicants
  • The form Security setting is set to 'Require secure link/login' or 'Allow secure link/login filters'

The purpose of adding merge fields to a form is typically to display information to the registrant related to their record that should not be edited. Merge fields are also used to personalize content displayed on the form, such as labels and instructions. This article will cover how to add merge fields to a form, as well as example use cases that illustrate their purpose.

Adding Merge Fields to a Form

To add a merge field to a form, ensure that the form is Application-scoped, or is otherwise set to require a login or allow secure filters. If the form was created prior to the existence of merge field functionality, take the following steps to trigger the Merge Fields section to show:

  1. Click Edit Properties within the Edit Form view.
  2. Without changing any settings, click Save.

This will now display the Merge Fields section in the Edit Properties pop-up window.

resave_form.gif

Selecting Exports

Three types of exports are available to add as merge fields to a form:

Icon Type of Export Description
export.PNG Standard export Allows the user to add direct and extended exports.
mceclip0__8_.png Subquery export Allows the user to add subquery exports such as concatenated values, existence exports, or formula exports. Filters and joins may be used within a subquery export to produce the desired export values.
mceclip1__5_.png Literal export Allows a static value to be created and exported for each form response.

It is critical to remember that the starting base for merge field exports is Form Response. This implies that the direct exports will always pertain to properties of the form response. When searching for merge field exports, it may be necessary to extend the data available out to different tables; this will require additional joins within the Merge Fields tool.

  Best Practice

When adding exports under the Merge Fields tool, it is recommended to replace the export name with a computer-friendly value. Otherwise, a space in the export name must be replaced by a dash (-) when referencing it as a merge field (e.g. Person Preferred > Person-Preferred).

Adding a Join

In many cases, at least one join may be necessary to access information related to data belonging to the record submitting the form.

For example, on an application-scoped form, clicking the 'Join' option under Merge Fields shows the following options for data tables to join (Application, which corresponds to the form's scope, Current User, and Sequential Value Groups):

joins.gif

Example Merge Field Use Cases

Displaying Name Information

A user has constructed an application-scoped form and would like to display Preferred Name and Last Name data, but does not need this data mapped or changed on the record.

In order to access the Preferred Name and Last Name exports, joins will first need to be added:

  1. Within the Edit Form view of the application-scoped form, click Edit Properties.
  2. Click Join.
  3. Select Application and click Continue, then Save. This will join the Applications table onto the Form Response table. With just the Applications table joined, person-scoped data will not yet be accessible. This implies that another join is necessary to access the Preferred Name and Last Name exports.
  4. Click Join once again. Now that application data has been joined, several more tables are accessible to join as well. Select Person under the 'Application' label and click 'Continue', then 'Save'.

This now provides access to direct exports related to the form response properties, the application record related to the form response, and the person record belonging to that application.

joins_and_exports.gif

Next, the desired exports (Preferred Name and Last Name, in this example) can be selected as standard exports:

add_exports.gif

The added exports can be referenced on the form itself by including them in an instruction block, a header, or a label. Double curly brackets must be used to include these merge fields, and remember to replace any spaces in the export name with a dash (-) when referencing it as a merge field (e.g. Person Preferred > Person-Preferred):

adding_merge_fields.gif

When previewing the merge fields now included in the instructions box, the record's preferred and last name are now merged and display on the form:

checking_merge_fields.gif

Was this article helpful?
15 out of 43 found this helpful