Once you have followed the Basic Configuration article to create your Document Action, it is time to configure your Document Action template by following the steps below.
- Open the Template Builder
- Select Base and Child Object(s)
- Apply Filters and Sorting
- Merge Images
- Bulk Image Merge
- Add Conditional Section Merge
- Merge Field Into Document
Open the Template Builder
Click the Edit Template button on the top right corner of the Document Action screen. This will take you to the Template Builder, where you can add Salesforce merge field code to your Google Docs template.
Select Base and Child Object(s)
Select Base Object
When you select the base object, all base object fields will appear, as well as a menu of related lists and all child objects with their related lists. If you need to select any field from a related object, all lookup fields will have “ID>” following the field label. Click on it and a menu of fields from that object will appear to the right.
Select Child Object
If you would like to merge fields and/or related lists from a child object, select your base object first, then the child object from the “Select Child Object and Field” menu that appears. Choose the related lists to merge.
For example, to create an Opportunity Summary that shows Opportunity Line Items, you would select Opportunity as the base object and Opportunity Line Items as the child object. Related lists could include Opportunity Product Name, Quantity, List Price, and Total Price.
Select Child Object’s Related Object
If you would like to go down an additional level, select the base object, the child object, then the child object’s related object from the “Select Child Object’s Related Object and Field” menu that appears. Choose the related lists to merge.
For example, to create a Quote that shows Groups with Line Items, you would select Quote as the base object, Line Item Groups as the child object, and Line Items as the child object’s related object.
Once you’ve selected the related lists, continue to next section for information about filters and sorting or skip directly to Merge Field into Document.
- If you want to merge a related list from an object that is not on the list of child objects, you would need to relate that object to the object being used as base object of the Document Action.
Apply Filters and Sorting
Apply a Filter
You can set a Filter option for the entire table by adding it once to any of the fields you’re merging into the table. Specifically, you may want to filter on some of your related list items based on some condition or validation.
For example, you may only want to merge Line Items from a specific group:
- Select the base object and child object, Quote and Line Item Groups.
- Select the child object’s related object, Line Items.
- Choose the related list, Product Name
- In the Apply Filter section, select the field you wish to filter by. In this case, select Group Name, then add your filter into the text box. In this case, if the filter is “Software”, only Line Items within the “Software” group will populate.
- The merge field code will appear in the Merge Field Code section for you to copy/paste into the document.
If you would like to sort your related list items in a certain order, you can use the Sort By feature.
For example, you could sort by the Sort Order field, which is configured on the Opportunity record in Salesforce:
- Select the base and child objects, Opportunity and Opportunity Line Items.
- Choose the related list field, Opportunity Product Name.
- In the Sort By section, select Sort Order and A to Z for ascending order.
- Merge field code will populate in the Merge Field Code section for you to copy/paste into the document.
- If you would like to filter based on more than one filter condition, create a formula field that results in a checkbox and put all the different logic in if statements into that formula field. Then, you can filter on the single formula/checkbox field. The formula can have all the different conditions.
- If you want to be able to sum up child records in Salesforce, you can use Rollup summary field for Master-Detail relationship Objects and can refer to this FAQ article for more detail.
A5 Documents allows you to dynamically merge images from a public URL accessible to the internet. Supported image types include jpg, jpeg, png, gif. To merge the image into your document, you’ll create a custom long text field, add the publicly available URL to the custom field, then merge the custom field into your template. See detailed steps below:
Create a custom field
This custom field will hold the URL and add to base object’s page layout. Field type should be “long text” rather than URL, since the URL Sources in this article will have URLs that exceed the 255 character limit.
Choose your URL source
Follow the steps below to create a publicly available URL to the direct image.
Documents (Classic only)
- Go to Documents tab in Salesforce.
- Upload the image to Documents or open an existing Documents file.
- Select the checkbox “Externally Available Image”.
- Right click the image and select “Copy Image Address”.
- Paste URL into the custom field.
Files (Lightning only)
- Upload a new File or open an existing one
- Select File Sharing Settings>Share With Link.
- Copy that link and open it.
- Right click on the image displayed.
- Select “Copy Image Address”.
- Paste URL into the custom field.
You can merge images from a publicly available web source, images hosted on any web server, AWS, or CDN server. To copy the direct URL of the image, right click the image and select “Copy Image Address” and paste the URL into the custom field.
If you would like to merge images that are stored on Google Drive, this is possible; however, the link provided by Google does not work as provided so some modification is necessary (see below for each option). In general, we have found that using publicly available images from Google Drive is not as reliable as the other options; we would advise using Files, Documents, or web source instead if possible.
Google Drive – Public Folder
- Put your files in a public folder.
- Right click “Share” button at top right of screen.
- Change settings to “Anyone with Link”=”Viewer”.
- Any file in the folder will be made publicly available by entering URL in this format: “https://googledrive.com/host/<folderID>/<filename>”.
- For example, if you created a test folder on Google Drive and uploaded a file testImage.png, the image URL would be: “https://googledrive.com/host/0BwdB0jiqM9yCXzlGeDZjaUhYZFk/testImage.png”.
- Copy the new image URL and paste it into the custom field.
Google Drive – Main Folder
If you don’t want to put files into a shared folder, you can use images that are uploaded directly to Google Drive (as long as they’re publicly accessible).
- The image URL format will be: “https://docs.google.com/uc?id=<file-ID>”.
- For example: If you uploaded a file directly to your drive with a file ID of “0BwdB0jiqM9yCM01iekxpdlc4ZHc“, the Image URL would be: “https://docs.google.com/uc?id=0BwdB0jiqM9yCM01iekxpdlc4ZHc“.
- Copy the new image URL and paste it into the custom field.
Merge the Image Field Into Your Template
- Locate the custom field in the template builder.
- Check the “Image” checkbox.
- The merge field code will populate in the “Merge Field Code” field at the bottom for you to copy and paste into the template body, header, or footer.
Bulk Image Merge
If merging 3 or more images into your template, we recommend selecting the Bulk Merge Images checkbox on the Document Action. When enabled, this feature uses Google Docs Batch API to merge images, which works faster for a larger number of images.
When using this feature it is not possible to set the width of the image to depend on the table cell width. So, it will be necessary when using this feature to prepare images in the actual size that will need to be merged into the document.
Customers upgrading the app from older versions will need to add this field to the Document Action object page payout.
Add Conditional Section Merge
The conditional section merge feature allows you to merge one or more sections into your document based on a condition of a checkbox or formula field. It is also possible to have one checkbox field that refers to multiple conditional merge sections in template. The section merge feature also makes it possible to create a conditional page break in your template.
Conditional Merge Based on a Checkbox Field
The conditional merge feature allows you to merge sections of text into your document based on the value of a standard checkbox field (true or false).
There will be a start and end to each conditional merge section that you will need to mark with tags. The template builder will generate the tags for you as part of your merge field code that you copy and paste into the document. Your conditional merge section start and end tags should be on their own line in the template.
After the merging of start/end conditional section is completed within the generated document, these tag lines will be removed from the document. Note that if you have a conditional merge section end tag at the end of the document template, you must add one extra line below that tag so the conditional end section end tag is not the last line of the entire document.
As an example, a sales rep could use the conditional merge feature to control whether to include or not include a “Special Terms” section in a contract document attached to an Opportunity record. To do this, they would create a checkbox field on the Opportunity object called “Special Terms”. If on the Opportunity record this checkbox field were checked (true), then this additional agreement section would merge onto the template. If this checkbox field were not checked (false), then this agreement section would not merge onto the document.
Steps to configure:
- Select the related checkbox field from in embedded template builder. For this example, we are using “Special Terms”.
- Under “Section”, type the section name, then select “Start of Section” and it will generate the merge field code for your conditional section start.
- Copy this merge field code and paste it where you want the section to start on your template.
- Repeat these steps to generate the conditional section end tags and paste where you want the conditional section to end.
- Add the conditional section to the document between the start and end tags. This conditional section can contain any combination of hardcoded text or merge field code. This content will only display if the checkbox = TRUE.
Conditional Page Break
You can create a page break within the conditional section merge. This can be helpful to control where the page break will occur if the conditional section is merged. For example, to ensure that the conditional section is preceded by a page break, you’d arrange the template as follows:
Conditional Merge Based on a Formula Field
For example, you could create a conditional merge section based on a formula field on an Opportunity record to merge ONLY if there is at least one product related to the Opportunity.
- Create the section and content on template builder.
- Create a formula field with the type as checkbox on the object merging from such as Opportunity. The formula field in our use case could be called “Line Items Exist”. This formula would have an IF statement to check whether the record has at least one product related to the opportunity, then return true or false.
- Go to the template builder and select the formula field.
- Check the box to indicate that it is a conditional section.
- Copy/paste the merge field code to create the section start/end tags in your document
Multiple Conditional Section Merge
If you would like to have one checkbox field that refers to multiple conditional merge sections in template, you can see this use case article for more detail.
Merge Field or Related List Into Document
To merge a field, copy the value from the “Merge Field Code” and paste it into the body, header, or footer of the template.
To merge a related list, copy the value from the “Merge Field Code” and paste the merge field code into one row of a table. The row will repeat for each record. The merge field code must be represented within a table so that the rows can repeat with multiple values.
To merge a related list from a child object’s related object, it must be added to a row directly below the merge code of the child object. If you add a row with text or otherwise separate the rows, the related list of the child object’s related object will not populate. Format the table such that the merge field code from the child object is in a row directly above the row containing merge field code from the child object’s related object.