Working with Child Relationships

Overview

Create a Table

Grandchild Objects (Nested Loops)

Create Documents for Groups of Child records

Overview 

Salesforce supports master-detail relationships and we’ve given you the ability to use those relationships in Formstack Mappings. 

Using a child object in your document will mean that Salesforce will send over an array of data containing all of the records associated with that child object. This means you will need to create a loop in your document that supports iterating over a list of data. 

Note - If you need a more in depth breakdown on how to use "foreach / tablerow" functions to loop through a list of items, please review this article which walks through how to do so.


In this example we are using "Contact". Please replace with whatever child object you are using.
To do so:

{foreach from=$Contacts item=_contact}
    {$_contact.Name}
    {$_contact.Phone}
{/foreach}

The "_contact" part of this loop is the local variable that you'll use inside the loop.  To print out a field value, you use {$_contact.FIELD}, where FIELD is the Salesforce API Field Name for the sub field on that object (ie Name, Favorite_Color__c, etc).

*If you're not sure what the field names are called, turn on Debug Mode for your Document and after you run a test merge, you'll be able to see the field names.  You'll need to complete the next step first though!

In your Salesforce Formstack Mapping you will now have the ability to map a Salesforce field or relationship to "Contacts". When working with child relationships, we’re going to ignore the _contact field in this situation because it is the iterator. Let’s instead look at Contacts and in the Salesforce Field section, find the relationship you want to map to the list.
 

In this example, we will use Child Relationship: Contacts. This will allow you to create a Formstack Documents generated document that iterates over all the child contacts attached to a Salesforce record and output their Name and Phone Number.

 

Create a Table

If you'd like to create a table in your document, you can do that use a "tablerow" tag instead of the "foreach" loop like this:

Example - Opportunity Line Items + Pricebook

If you'd like to create a table in your document of line items, you can do that use a "tablerow" tag instead of the "foreach" loop like this:
 

Working with Grandchild Objects (Nested Loops)

If you need to loop through child records within your child relationships, Salesforce will send over a list of records indexed by the Id of your main child record.  You can do something like this in your document:

{foreach from=$Contacts item=_contact} 
  {$_contact.Name}
  {foreach from=$Dependents[$_contact.Id] item=_dep}
    - {$_dep.Name}
  {/foreach}
{/foreach}

You’ll then need to update your Salesforce Mapping to use a SOQL query to access the Dependents data related to the Contacts data

Create Documents for Groups of Child Records (Specialized Use Case)
 

Use Case 

A parent object has several child objects that need to be grouped together and individual documents need to be created for each group.
 

Solution 

• In addition to all the necessary field mappings - including the array of all child records - use a SOQL query to create an array of the individual groups by grouping child records by the appropriate field(s).
• Then use a data route and with rule repeat option to generate unique documents for each record in the array of individual groups.
• In the document, reference the appropriate field(s) in the group array and use conditional merge tags to compare it to the values of to those of each child record. Only include the child records that match the values of the field(s) in the grouped array.

Implementation Steps 

• Create and save a new document.

• In the Settings tab, the name of the file can be edited to include information about the group.

• To deliver the documents separately, go to the Deliver tab and set up any deliveries necessary.

• Create a new data route. '

• In the Rules tab, remove Rule 2 and Rule 3, leaving just Rule 1. In Send data to Document, select the document created in Step 1

• Check the box to the left of Repeat this rule. This will repeat this particular rule and generate the document for each record in an array.

• A new text box will appear upon checking to repeat the rule, Repeat this rule use the field (array). Enter a merge field here to be used to store the information of the different groups extracted from the child records. In this example, {$Groups} is used as the merge field.

 

• Click Update Rules to save the rule

• Go to the Formstack Mappings tab and create a new mapping. Give the mapping a name. Select the appropriate primary object from the dropdown in Salesforce Object.

• For Formstack Resource, select Route. And when Select a Route appears, select the appropriate route from the drop down.

 

• Click Save and Next

• Upon saving, the Field Mapping section will appear with the merge fields from the document included in the data route. The Salesforce fields can be mapped to the appropriate merge fields. The fields used for group information should not be mapped to any particular field.

• For the merge field used for the group array, select << SOQL Query >> from the drop down. Another text field will appear for the SOQL Query. Here a SOQL query using the GROUP BY option is used.

• Click Save to save the mapping.

• Assuming the Merge Document button has been added to the page layout of the primary object, the mapping will now appear in the list of mappings to select. Upon selecting the mapping, a unique document will be generated for each group.