Skip to main content

Linking Forms

Thomas Hardy
  • Updated

Contents

Overview

Linking forms allows program administrators to make a Zengine database more powerful by connecting multiple sets of stored data to one another. 

Forms in a Zengine workspace function as data repositories that store information frequently collected at different stages or milestones in a program’s workflow. Each set of this information is known as a record, and each record on a form represents data about or submitted by a single applicant, organization, or project. Linking forms together is how Zengine maintains the integrity of this data: records on one form are linked to related records on another form, ensuring that this data is easy to access, review, and manage. 

This article will discuss a variety of different issues related to linking forms, including: 

  • how relationships between linked forms structure the Zengine workspace experience; 
  • managing and navigating between linked records on different forms; 
  • how to link forms together; 
  • how to display information from a linked record on a different form; 
  • how to set and change the type of relationship between two forms;
  • and finally, how linked form relationships affect the submission portal structure and experience

Form Relationships

Linking forms is integral to the way Zengine operates. Zengine is a relational database, which is a system structured to recognize connections among stored sets of information (known as records). When a Zengine workspace is set up, these connections are created between different forms, allowing records stored on those forms to be linked together. 

The manner in which these linkages are set up can be defined by different relationships between the forms; all records on one form linked to records on another form are structured by that same form relationship. However, different sets of linked forms can create different types of relationships. 

These form relationships affect not only the way data is stored and connected, but also the processes of collecting, viewing, and managing data (and a variety of different Zengine tools - see the section Linked Forms in Zengine below for more information). Because of that, understanding the types of form relationships is important before continuing. 

 

Parent and Child Relationships

The first aspect of form relationships to understand is known as a “Parent and Child” relationship. This refers to both the logic of how two forms are connected and the timing of which the records (or sets of data) on a form are collected: the records on a child form are dependent on the linked records of the parent form, which means that the information on the parent form is collected or stored first.

This may sound confusing, but can be demonstrated with a simple example. Let’s take a typical grant application program, which, among other stages, contains an Application and an Award. The Award isn’t useful on its own; it only makes sense in relation to an Application that has been awarded. In this sense, we can say that the data collected at the Award stage is dependent on the data collected at the Application stage. In database terms, this means that the Application form is the parent form, and the Award form is the child form.

While this terminology defines one aspect of the relationship between two forms, bear in mind that most programs will contain forms that are linked together in chains; this means that a form can be a child to one form and a parent to another. For instance, continuing the example from the previous paragraph, a typical program will require an applicant to complete a Profile (containing basic contact information) before starting an application. Since the records on these forms should be linked to each other, this means the Profile form is the parent of the Application form, which in turn is the parent to the Award form. 

 

 

Records on a form can be described the same way: records on the parent form are known as parent records, while records on a child form are known as child records.

 

One-to-One and One-to-Many Relationships

The second aspect of form relationships describes how many child records can exist for a single parent form. These types of form relationships can be characterized as a one-to-one relationship (i.e., only one child form record can be linked to a parent form record) or a one-to-many relationship (i.e., many child form records can be linked to a single parent form record). 

A one-to-one relationship is best used when there should only be one record on a form for each linked parent record. Continuing the same example as above, most typical grant application programs will only award one grant per application. (This grant may be disbursed in multiple payments, but they will only constitute one award.) That means that the relationship between records on the Application form and those on the linked Award form should be one-to-one.


 

Conversely, a one-to-many relationship is best when more than one child record can be linked to a single parent record. As one example, imagine that an organization works with multiple clients or companies, and these clients are managed in Zengine. Each of these companies, in turn, may have multiple contacts.  


 

Instead of entering multiple sets of fields to accommodate these contacts onto the company form, create a contact form (child form) and link this to the company form (parent form).  This would allow program administrators to link as many contacts as each company has to that company form, without needing to duplicate the company information on each contact record.

 

Linked Forms in Zengine

The ways that forms are linked together in a workspace not only provides structure to a workflow, but also determines how certain features and tools are used throughout Zengine.

Submission Portal 

Linked form relationships determine which records on different forms a portal user can view and enter information into.

For more information, see the articles Submission Portal Key Concepts: Beginner and Submission Portal Key Concepts: Intermediate.

Data Views

When viewing records and creating data views in a workspace, an administrator can show fields from linked forms. However, only fields from parent forms and child forms in a one-to-one relationship can be shown. Fields from child forms in a one-to-many relationship cannot be shown on a data view for a given form.

For more information, see the article Working with Columns and Views.

Filter 

The filter tool, used with data views and a variety of other Zengine tools, can filter records based on criteria on a linked parent form.

For more information, see the article Filtering.

Auto Email

The Auto Email tool can be configured to send to the email address entered into email fields located on the Recipients form or a linked parent form. In addition, field references (also known as “data tags”) can insert the value of a field into the body of an email drawn from the Recipients form or any parent form.

For more information, see the article Auto Email.

Bulk Email 

The Bulk Email tool can also be configured to send to email fields located on the Recipients form or a linked parent form. However, field references (data tags) can only be added to the email body or subject line from the Recipients form or any child form that is linked in a one-to-one relationship. Field references cannot be drawn from child forms linked in a one-to-many relationship.

For more information, see the article Bulk Email.

Program Manager & Assignments and Review Portal 

Review feedback forms to be completed by reviewers must be linked to both the primary Application form to be reviewed, and the Reviewers list form in order to to assign application packages to be reviewed in a Review Portal. However, because more than one reviewer can be assigned to a single application package, these relationships must be configured as one-to-many relationships.

For more information, see the articles Program Manager and Review Portal Plugin Setup.

 

Viewing Linked Records

Administrators viewing and managing records in a workspace will frequently want to navigate between records on different forms belonging to the same organization, applicant, or project. 

Viewing Linked Child Records

To view linked records, begin by opening the form view of a record on a form that is linked to other forms:

  1. Navigate to the form in a workspace to see the records in a data view. In this example, the Applications form is shown, which is linked to four child forms and one parent form.

  1. Select a record to open the form view for that record.
  2. On the right hand side of the screen, the Linked Records pane should be visible.

 

Different information can be shown in this pane. If Linked Records is not showing, select the Linked Records icon in the upper right of this pane.


  1. The Linked Records pane will show child records for any forms that are linked to the form record currently open. To view a linked child record, select the name of the record under the section for the form on which it exists.

  1. This will open the record selected. To return to the previous parent record, select the Back button in the upper left corner.

Viewing Linked Parent Records

Parent records can also be accessed from an open form record, but are not shown in the Linked Records pane. To access a linked parent record:

  1. Open the form view for a record and identify the Linked Form field that contains the parent record. This can be identified as a dropdown field with the Linked Record icon next to it. (Note that the field name may differ by form and workspace.)

  1. Select the Linked Record icon next to the linked field; this will open up the form view of the parent record that is linked to the currently open record.
  2. To return to the previous child record, use the Linked Records pane on the right side of the screen (see the section Viewing Linked Child Records above) and select the name of the record under the appropriate Form. Alternatively, select the Back button in the upper-left corner of the screen.

Changing Linked Records

The value of a Linked Form field (i.e., what is entered into this field) consists of one of the available records on the linked parent form. This is what actually creates a link between two records across different forms. As a result, changing the value of a Linked Form field will change which records on two linked forms are connected. 

This should be done with caution, especially if the Linked Form field that will be changed is used to connect forms and records together for use in a submission portal. (For more information on how forms are linked for use with a submission portal, see the article Submission Portal Key Concepts: Beginner → Forms.) 

Most Linked Form fields will be filled in automatically as those form records are accessed and created by portal users, and the values that are automatically given are critical to maintaining the integrity of data across different forms. Thus, they should not be changed without a specific reason.

 

— IMPORTANT —

Changing the value of one of these Linked Form fields manually, without fully understanding how this may affect records, can result in major problems for portal users and administrators alike.

 

However, there may be times when changing the value of a Linked Form field manually is useful or necessary.  For example, perhaps a portal user’s submitted records became de-linked by accident, and an administrator wants to repair the correct linking. Another potential situation could be if a portal user accidentally created a second account and application in the submission portal, and an administrator wishes to combine the application with the portal user’s existing login and Profile.

The instructions below walk through through the process of changing which records are linked to each other. 

 

— IMPORTANT — 

If a linked field was changed by accident, or if an administrator is unsure of the effects of changing a linked field value, there is the option to exit a record without saving (which will revert any changes that were made) and reach out to our Support Team for guidance.

 

To change which records on different forms are linked to each other:

  1. Navigate to the form that contains the child records that need to be re-linked. 
  2. Select the desired record to open the form view for that record.
  3. Identify the linked field on the form that contains the parent record. This can be identified as a dropdown field with the Linked Record icon next to it. (Note that the field name may differ by form and workspace.)

  1. Select the linked field to open a dropdown menu containing all available records on the linked parent form. 

 

A. Select the name of the parent record that should be linked to this record.

B. Parent records can also be searched for by typing the name of the parent record into the Type to search… bar to locate records matching that name.

C. To remove the linked field value without replacing it with another record, select X Clear Selection. This will de-link the record from the parent form.

D. Finally, if the parent record to be linked to the open record does not yet exist, select + Create New to open a blank record on the parent form. Once that parent record has been completed and saved, its value will automatically be filled into this Linked Form field, linking the two records together.

  1. When finished, select the blue Save [Record Name] button at the bottom left corner of the screen.

 

Setting Up Linked Forms

Linking two forms together involves adding a Linked Form field to the child form. However, planning ahead is important when setting up one or more sets of linked forms. Creating the forms and fields is relatively simple, but making sure a program’s data flows logically is more complex. 

The first thing to consider is which form should be the parent form and which should be the child in the linked form relationship. Remember that the child form is dependent on the parent form, meaning that the parent form record must be completed first. If several forms will be linked together in a chain, it’s helpful to first sketch out the order in which these forms should be completed, and link them in that order.

Second, consider whether the linked forms are intended to be used with another tool or feature in the workspace. Forms that will be used to collect or display information using the Submission Portal, Requests, Progress Reporting, and Review Portal features require forms to be linked in specific ways.

For more information about the use of linked forms:

 

Finally, consider whether the forms will be linked in a one-to-one relationship or a one-to-many relationship. Remember that the child form in a one-to-many relationship can have many records linked to a single parent form record, so the form containing multiple records for the same individual, organization, or project should be designated as the child form.

Linked Form Fields

A Linked Form field can be added to a form using the Form Editor tool (also called the Form Builder):

  1. From the workspace, navigate to the form that needs a Linked Form field. This should be the child form in the pair of forms being linked. In the example below, this is the Applications form. (Note that the displayed data view and form names will vary and may look different.)
  2. Locate the button labeled Form Tools on the right side of the data toolbar.

  1. Select the button to open a dropdown menu and select Edit Form. 

  1. This will bring up the Form Builder screen. (To learn more about the Form Builder, see the article Form Builder Overview.) The main part of the screen will show the fields that have already been added to the form. Locate the Field Types pane on the right side of the screen.

  1. Scroll down the Field Types pane until a field type called Linked Form under Input Fields is visible. (The Field Types pane will scroll independently of the list of already-added fields in the main part of the screen.)

  1. Select the Linked Form field type and drag-and-drop it into the list of fields in the main part of the screen where it should appear on the form. Upon doing so, the field will expand, prompting you to choose a parent form that this field should create a link to.

  1. Select the dropdown menu titled Please choose a form that your field should belong to to open a list of all available forms in the workspace.

  1. Select the parent form that this form should link to.
  2. When all changes to the form are complete, select the blue Save Form button in the lower left corner of the screen to save the changes. The new link will take effect immediately.

 

— IMPORTANT —

Once a form has been designated in a Linked Form field, it cannot be changed within that existing Linked Form field. If a linking change is needed, the field must be deleted and replaced with a new Linked Form field.

 

  • For more information on displaying fields from the linked record in the form view, see the section Linked Field Display below.
  • For more information on defining the form relationships between the parent and child form, see the section Defining Linked Form Relationships below.

Linked Form Field Limitations

There are a few limitations in which forms can be linked together:

  1. A parent form cannot be linked to its child. If this is attempted, a circular relation error message will display.

  1. The same form cannot be linked to another form twice. This will also result in an error message.

  1. There is a limit of ten linked forms to one another in cascaded progression. In other words, just nine successive forms can be linked to each other in a single chain. If an error message appears when attempting to add a linked form, it may be because too many cascaded forms are already linked to each other.
  2. A limit of 30 child forms can be linked to a single parent form.

 

Linked Field Display

Linked Fields allow administrators to display up to 10 fields from a selected linked parent record within the child record form view. This display is optional and can be enabled or disabled, but is useful for providing additional context to workspace administrators reading the record data without requiring them to navigate to the related parent record.

For example, while viewing an Application record, important details about the related Organization Profile (the linked parent record), such as name, email address, phone number, mailing address, and so forth can be shown in context while viewing the Application record.


 

Enabling Linked Field Display

To enable the linked field display for related parent records, begin by entering the Form Builder for that form (see the section Linked Form Fields above, Steps 1-3):

  1. Once in the form builder, identify the linked form field for which the field display should be enabled; select the Edit button for that field.

  1. This will open the field options. Select the checkbox next to Show related fields from this Linked Form. 

  1. Doing so will display a dropdown menu labeled Pick Fields to Show. Select this dropdown menu to show available fields from the linked parent form that can be displayed.

  1. Select the checkboxes next to each field from the parent form record that should be displayed when accessing the child record.
  2. When ready, select Save Form in the lower left corner for the changes to take effect.

When accessing a form record from the data view, these fields will now display information from the linked parent record underneath the linked form field that was just configured.

 

To remove a field from the linked field display, uncheck it from the dropdown menu that was accessed in Step 4 above and save the form.

To disable linked field display for a linked form field, uncheck the box next to the Show related fields from this linked form option that was accessed in Step 2 above before saving the form.

 

Linked Fields in Submission and Review Portals

Linked Form fields that are necessary for the functionality of a submission portal will be filled in automatically as a portal user accesses their forms, and will not be visible or editable by the portal user. (Administrators will still be able to view and edit these in the Zengine workspace.) 

Functionality, in this sense, refers to the way that submission portals use linked fields to maintain connections between records across different forms belonging to a single user; in other words, the Linked Form fields that connect a user’s Application record to their Profile, for example, or the Award Details record to the Application, will be automatically filled in with the portal user’s appropriate records by the submission portal. (For more information on forms and linkages used in submission portals, see the article Submission Portal Key Concepts: Beginner → Forms.)

Similarly, system-related Linked Form fields that are necessary for use in a Review Portal will not be visible to reviewers accessing the portal. These include two linked form fields on the Review Feedback form: one to the primary form of the application package that will be reviewed, and one to a list of Reviewers. These fields are filled in automatically when review assignments are made via the Program Manager. (For more information on setting up Linked Form fields for review feedback forms, see the article Program Manager → Feedback.)

However, while most linked forms will involve only one parent relationship, other Linked Form fields can be added to a form, and these can be viewable and/or editable for a portal user. This may be useful for situations in which a portal user is asked to select an option from a dropdown list that is too long for a normal dropdown field, will be updated frequently, or will contain several items of associated data with each entry. 

As one example, a scholarship program may ask high school student applicants to select the regional university they applied to from a pre-approved list as part of their application. These options may number in the hundreds, may change as eligible universities are removed or added, and may contain associated address information with each record. In this situation, these universities would be stored as individual records on a separate form and then linked to the Application form.


 

In the submission portal, a portal user filling out this form could then select their option from the list of records on this form, or begin typing in the name of their university to search among the records.

In addition, the Linked Field Display [LINK], if enabled, will display in the submission and review portals. The related fields help applicants confirm they have selected the right choice. (The same related fields can also be presented to program reviewers in review portals for similar purposes.)

 

Defining Linked Form Relationships

Whether the relationship between two linked forms is one-to-one or one-to-many can be defined by accessing the field options for the Linked Form field in the Form Builder. By default, the form relationship will be set to one-to-many, but this can be changed to a one-to-one relationship easily. The instructions below detail this process after the Linked Form field has been configured, but it can be done during the initial configuration. (If this is the case, skip to Step 3 below.)

  1. Open the Form Builder for the child form by navigating to the form data view, selecting Form Tools, and then selecting Edit Form. (See the section Linked Form Fields above, Steps 1-3.)
  2. Locate the Linked Form field and select the Edit button to open the field options.

  1. Select See advanced options.

  1. This will open up additional options; scroll down until a checkbox next to No Duplicates is visible.

By default, this option will be left unchecked. 

Checking No Duplicates means that each value can be selected only once across all records on a form. In the case of Linked Form fields, the values are records on a parent form. This means that each parent record can only be linked to one child record, creating a one-to-one relationship.

Leaving No Duplicates unchecked means that each value in this field (which is a record on the parent form) can be selected for as many records on the child form as desired; there are no restrictions on how many times it can be used. This creates a one-to-many relationship, as the same parent record can be linked to multiple records on the same child form.

  1. When ready, select Save Form in the lower left corner for the changes to take effect.

Form Relationships in the Submission Portal

A one-to-one relationship between the Primary form (parent) and a linked secondary form (child), when associated with a Step in the submission portal, will create a Single Form Step Type, meaning that the applicant (portal user) can only fill out a form once as part of a Stage. In the Zengine workspace, this action will create only one record on that form, and administrators will be unable to create another.

Conversely, a one-to-many relationship between the Primary form and a linked child form will create a Listing Step Type in the Submission Portal, allowing the portal user to create more than one record on the associated form for each Primary form record. A Listing Step type allows a portal user to fill out the same form multiple times, creating more than one record, for that Step.

The Step Type is determined automatically from the form relationship between the form associated with the Step and the Primary form of the submission portal when a Step is created in the Submission Portal Settings.

For more information on how form relationships affect the submission portal experience, see the article Submission Portal Key Concepts: Intermediate → Step Types & Form Relationships. 

 

Changing Step Types in the Submission Portal

Because the Step Type in a submission portal is determined automatically from the associated form’s relationship to the Primary form, changing the Step Type means changing the form relationship by editing the Linked Form field directly on the child form (see Defining Linked Form Relationships above). 

The most common scenario where this is needed is when a mistake is made - that is, an administrator neglected to set a one-to-one relationship when creating linked forms, but didn’t realize it until a Listing Step was created in the submission portal rather than a Single Form step. (Changing the Step Type after a submission portal has been opened for live submissions should be avoided.)

To change a one-to-one relationship to a one-to-many relationship, simply de-select the No Duplicates checkbox in Advanced Settings for the linked parent form.

Conversely, to change a one-to-many relationship to one-to-one, check the No Duplicates checked in Advanced Settings for the linked parent form.

 

— IMPORTANT —

While form relationships can be changed, this becomes more difficult after records have been submitted: if changing a one-to-many relationship to a one-to-one relationship, all existing parent records must have only a single linked child record before this can be done. This means that any child records linked to the same parent record must be deleted or de-linked before continuing.

 

However, additional actions are needed if the child form involved in the linked form relationship has already been associated with a Step in the submission portal. These actions take place in the Submission Portal Settings. 

(For more information on accessing the Submission Portal Settings, see the article Submission Portal Settings → Accessing the Submission Portal Settings.)

If a linked form relationship has been changed, upon entering the Settings for a submission portal, an administrator will see a yellow error message labeled Pending issues appear in the upper right corner of the screen. This message will appear when there is an issue that needs to be resolved before a submission portal is fully functional.

  1. Selecting the message will display the specific problem.

In this example, the message means that the form associated with the Reimbursements Step in the submission portal had its form relationship with the Primary form changed, and that form relationship no longer corresponds with the Step Type that is currently configured in the portal (making it invalid).

  1. Selecting this second message will display the Step Settings page for the problematic Step. The current Step Type can be seen on this page.

  1. Checking the box next to Do you want to change this to a Single Form type? will update the Step Type that corresponds to the new form relationship. 

 

In this case, the Step was previously configured to be a Listing Step (resulting from a one-to-many relationship between the Primary form and the form associated with this Step) and the form relationship was changed to one-to-one. However, if the inverse was true, this configuration option would display Do you want to change this to a Listing Form type?.

  1. Finally, select the blue Save all settings button in the lower right corner for the changes to take effect. 





Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk